REST API 总览

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：crates/cheng-api/src/rest/routes.rs、crates/cheng-api/src/rest/dto/common.rs、crates/cheng-api/src/middleware/workspace_context.rs

ChengOS 中的一切都与同一个后端服务 cheng-api 通信。编辑器、对话网关和 cheng CLI 都只是本文所述 API 的普通客户端——不存在什么它们专用、而你无法使用的私有接口。

基础地址与约定

带版本的接口位于 /api/v1 之下。对默认安装而言就是 http://127.0.0.1:3000/api/v1。

有几个路由被刻意放在版本前缀之外，因为它们属于基础设施而非产品 API：

请求与响应体都是 JSON，字段名使用 camelCase，尽管后端是 Rust。登录响应形如 {"token": …, "refreshToken": …, "expiresIn": 3600}。

认证

多数接口需要 JWT。通过 POST /api/v1/auth/login 获取：

curl -X POST http://127.0.0.1:3000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "…"}'

{
  "token": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…",
  "expiresIn": 3600,
  "user": { "id": "…", "email": "…", "username": "…" }
}

之后每个请求都要带上该令牌：

Authorization: Bearer <token>

访问令牌一小时后过期。请用 POST /api/v1/auth/refresh 换取新令牌，而不是重新登录。POST /api/v1/auth/logout 返回 204，且只作用于客户端——它是在告诉你丢弃令牌，并不会在服务端吊销它。

认证接口的其余部分：

另外三种凭证类型

JWT 并不是唯一的入口，混淆它们是 401 的常见来源：

• 渠道密钥（chk_ 前缀）用于外部渠道适配器——WhatsApp、Telegram、Slack 等——的认证，且仅对 /api/v1/channel/* 有效。它们以凭证形式存储，不携带任何用户会话。
• WebSocket 票据（chtk_ 前缀）由已认证的渠道 REST 接口签发，在 WebSocket 升级时一次性消费。它们存在的意义就是让渠道密钥永远不出现在 URL 中。
• MCP 令牌用于 MCP 服务的认证，可以是数据库托管的（推荐），也可以是静态的 MCP_SERVER_TOKEN。

选择工作区

几乎所有资源都归属于某个工作区。为了不必在每个路径里重复工作区，已认证的请求通过请求头携带它：

X-Workspace-Id: <workspace-uuid>

这个头会被授权校验，而不只是读取：中间件在认证之后运行，如果调用方对请求头中指定的工作区没有访问权限，请求会被拒绝。传入一个你看不到的工作区 id 会得到 403，而不是悄悄回落到某个默认工作区。

主要接口分组

有两组是条件挂载的——/schedules 和 /mcp/servers。如果它们在一个其他方面都健康的系统上返回 404，那是功能未配置，而不是出了故障。

分页

列表接口接受 offset 与 limit 查询参数。limit 默认为 20，并且被限制到最大 100——请求更多不会报错，你只会拿到 100 条。limit 为 0 会被当作默认值处理，而不是返回空页。在支持的地方，sortBy 与 order（asc / desc）控制排序。

响应会包裹整页：

{
  "total": 137,
  "items": [ … ],
  "hasMore": true,
  "offset": 0,
  "limit": 20
}

请使用 hasMore，而不要拿 offset + limit 与 total 比较；前者已经把实际返回的条数计算在内了。

错误

所有错误共用一个信封：

{
  "code": "VALIDATION_ERROR",
  "message": "供人阅读的描述",
  "details": { },
  "timestamp": "2026-08-12T10:30:00Z",
  "requestId": "…"
}

请匹配 code 而不是 message——message 是给人看的，措辞可能变化。requestId 是把客户端故障与服务端日志对应起来时应当引用的值。

有一个 code 值得特别说明：403 DEMO_MODE_RESTRICTED 表示该安装正以 CHENG_DEMO_MODE=true 运行，按白名单拒绝写入与执行。它反映的是配置，而不是你账号的权限问题。

实时执行事件

工作流运行通过 /ws/executions 以 WebSocket 流式推送，也可以从 /api/v1/ws/executions 访问。使用 JWT 认证，可放在 Authorization 请求头中，也可以作为 ?token= 查询参数传入；渠道客户端则改用 ?ticket=chtk_… 连接。该流承载节点级进度、流式节点的增量输出以及终态，这正是编辑器实时执行视图得以工作的原因。

下一步

• 环境变量参考——决定哪些接口会被挂载的那些设置。
• 第一个工作流——通过编辑器完成同样的操作。