# DevOS v1 API 契约

基址：`/api/v1`。所有响应为 JSON；变更（mutation）契约：zod DTO 校验 → 工作区授权 → 风险判定 → 审计记录 → 事件（如适用）→ 响应头 `X-Request-Id`。

## 错误契约

```json
{ "error": { "code": "RESOURCE_NOT_FOUND", "message": "Server not found", "requestId": "uuid" } }
```

错误码：`VALIDATION_ERROR`(400) / `UNAUTHORIZED`(401) / `FORBIDDEN`(403) / `RESOURCE_NOT_FOUND`(404) / `CONFLICT`(409) / `UPSTREAM_FAILURE`(502) / `TIMEOUT`(504) / `INTERNAL_ERROR`(500)。

## 认证

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | /auth/register | `{email,password,name?}` → `{token,user}`（自动创建 OWNER 工作区） |
| POST | /auth/login | `{email,password}` → `{token,expiresIn,user}`（JWT HS256，12h） |
| GET | /auth/me | 当前用户 + 工作区列表 |
| POST | /auth/logout | 无状态登出（审计记录） |

鉴权：`Authorization: Bearer <jwt>`；工作区：`X-Workspace-Id` 头（缺省用 token `wid` 或第一个成员关系）。角色：VIEWER 只读，MEMBER 可操作，ADMIN 管理成员/凭据，OWNER 全权。

## 工作区

- `GET /workspaces` 我的列表
- `POST /workspaces` `{name}` 创建（创建者 OWNER）
- `GET /workspaces/:id` 详情（须为成员；路径参数越权返回 403）
- `GET|POST /workspaces/:id/members`、`POST /workspaces/:id/members/:memberId`（改角色）、`DELETE .../:memberId`

## 资源（统一模型）

- `GET /resources?type=&status=&q=&page=&pageSize=`
- `POST /resources`（通用类型：PROJECT/REPOSITORY/DATABASE/DOCUMENT/BACKUP/EMAIL_ACCOUNT/TASK/NOTE）
- `GET|PATCH|DELETE /resources/:id`（DELETE 需 ADMIN）
- `GET|POST /resources/:id/relations`、`DELETE /resources/:id/relations/:rid`

## 服务器

- `GET|POST /servers`；创建：`{name,host,port,username,provider:"ssh"|"local",authType,password|privateKey|credentialId}`
  - `provider:"local"`：通过本机 `/var/run/docker.sock` 管理（无需凭据）
- `GET|DELETE /servers/:id`
- `POST /servers/:id/connect` 连通性探测（刷新状态、发 server.online/offline 事件）
- `GET /servers/:id/status` 含 docker 可用性
- `POST /servers/:id/exec` `{command,timeoutMs}`（审计；危险命令风险 CRITICAL）
- `POST /servers/:id/restart` `{confirm:true}`（ADMIN；HIGH）

## 容器

- `GET /containers` 全工作区
- `POST /servers/:id/containers` 发现（docker ps → 入库/更新 + runs_container 关系）
- `GET /servers/:id/containers`
- `GET /containers/:id/inspect`（env 键脱敏）
- `POST /containers/:id/restart` `{confirm:true}`

## 网站

- `GET|POST /websites`：`{name,primaryDomain?,serverId?,repositoryUrl?,deployType,port,healthPath,env?,domainId?}`
- `GET|PATCH|DELETE /websites/:id`
- `POST /websites/:id/deploy` → 创建部署（HIGH）
- `GET /websites/:id/logs?limit=` 最近部署日志
- `GET /websites/:id/health` 即时健康检查

## 部署

- `GET /deployments?websiteId=`；`GET /deployments/:id`（含 logs）
- `POST /deployments` `{websiteId,branch?,trigger?}`
- `POST /deployments/:id/cancel`（QUEUED 立即取消；RUNNING 步骤间生效）

## 域名

- `GET|POST /domains`：`{name,provider:"CLOUDFLARE"|"MANUAL",credentialId?}`
- `GET|DELETE /domains/:id`
- `GET /domains/:id/records`（CLOUDFLARE 实时拉取并同步本地）
- `POST /domains/:id/records` `{type,name,value,ttl?,proxied?}`（upsert）
- `POST /domains/:id/records/:localId/delete`

## 监控

- `GET|POST /monitors`：`{name,kind:"HTTP"|"TCP",target,intervalSec?,timeoutMs?,websiteId?,enabled?}`
- `GET /monitors/:id`（含 50 条结果历史）
- `PATCH /monitors/:id` `{enabled}`；`DELETE /monitors/:id`

## 自动化

- `GET|POST /automations`：`{name,triggerType,triggerConfig:{cron|eventType|secret},conditions:[{path,op,value}],actions:[{type,args,timeoutMs,retries}],enabled}`
- `GET /automations/:id`（含 20 条执行历史）
- `POST /automations/:id/enable|disable|run`
- `POST /automations/:id/webhook`（公开；`X-Webhook-Secret` 头校验）
- `DELETE /automations/:id`（ADMIN）

## AI

- `GET|POST /ai/runs`：`{objective}` → 创建后异步规划；HIGH/CRITICAL 停在 `AWAITING_APPROVAL`
- `GET /ai/runs/:id`（plan/toolCalls/verification）
- `POST /ai/runs/:id/approve|reject`（ADMIN）

## 凭据

- `GET|POST /credentials`（ADMIN）：`{name,type,provider?,secret}` — 明文仅存在于请求瞬间，任何响应不含密文
- `PATCH /credentials/:id`（轮换）、`DELETE /credentials/:id`（ADMIN）

## 审计与事件

- `GET /audit?page=&pageSize=&resourceType=&resourceId=&action=`
- `GET /events?page=&pageSize=&eventType=`

## 系统

- `GET /health`（公开）
- `GET /dashboard`（工作台统计）

## MCP

- `POST /api/v1/mcp` — Streamable HTTP（无状态）。请求头：`Authorization: Bearer <jwt>`、`Accept: application/json, text/event-stream`
- 工具：`devos.server.list/status/exec/getDockerContainers`、`devos.website.list/deploy/logs/health`、`devos.deployment.get/list`、`devos.domain.list/records`、`devos.automation.list/run`
- 所有调用经 ToolRegistry → 各模块 service（同授权/审计；actorType=MCP）