HTTP API
以当前源码为依据的认证、读取与集成接口说明。
认证与兼容性
API 与页面同源,路径以 /api/ 开头。除健康检查和登录等认证接口,业务接口均要求 Authorization: Bearer <token>。请求和错误使用 JSON。
当前接口供工作台和连接器使用,尚未提供独立版本化的公共 SDK。集成时固定项目版本,并核对 src/tenantRuntime.ts、src/authHttp.ts 和 src/rbac.ts。以下仅展示可验证的接口,不鼓励自动重放执行请求。
建立登录会话
curl --fail-with-body https://your-workbench.example.com/api/auth/login \
-H "Content-Type: application/json" \
--data @login.json{
"username": "your-username",
"password": "replace-with-your-password"
}成功返回 token、expiresAt、user、tenant 和 permissions。将本地登录文件限制为本人可读,不提交到版本库。会话过期后重新登录;不要将令牌放进 URL。
常用读取接口
| 方法与路径 | 用途 / 权限 |
|---|---|
| GET /api/health | 数据库健康状态;无需登录;成功 200,异常 503。 |
| GET /api/auth/session | 当前身份和权限;需要有效会话。 |
| GET /api/bootstrap | 当前空间工作台初始化数据;read。 |
| GET /api/task-center | 当前租户任务中心快照;read。 |
| GET /api/task-center/changes?since=<version> | 自指定版本开始的增量;read。 |
| GET /api/agent-sessions | 当前空间可见历史会话列表;read。 |
| GET /api/agent-sessions/:id?turns=10 | 历史详情轮次页;用 turnPage.before 获取更早轮次;read。 |
curl --fail-with-body https://your-workbench.example.com/api/task-center \
-H "Authorization: Bearer $WORKBENCH_TOKEN"工作空间 API
以下接口要求有效的浏览器登录会话;连接器会话一律拒绝访问。空间创建、列出、切换、查看成员和接受邀请要求 read;邀请与撤销要求 members.manage,并进一步检查角色。需要当前团队的接口不能在个人空间使用。
| 方法与路径 | 请求与行为 | 成功响应 |
|---|---|---|
| GET /api/workspaces | 列出有权进入的空间,以及发给当前账号的有效邀请。 | 200:currentId、workspaces、invitations。 |
| POST /api/workspaces | name:1–80 字符;requestId:16–64 位字母、数字或短横线。每账号最多创建 20 个团队。创建不会自动切换 API 会话。 | 201:{ id },团队空间 ID。 |
| POST /api/workspaces/switch | tenantId:要进入的个人或已加入团队空间 ID。 | 200:token、expiresAt、user、tenant、permissions。 |
| GET /api/workspaces/members | 需当前团队;返回成员及 updatedAt,管理者还可读取待接受邀请。 | 200:members、invitations。 |
| POST /api/workspaces/invitations | 需当前团队;username:已注册的唯一用户名;role:operator(默认)、viewer 或 admin。只有所有者可邀请 admin。 | 201:{ id },邀请 ID。 |
| POST /api/workspaces/invitations/:id/accept | 无需请求体;只有邀请对应账号可以接受,接受不会自动切换 API 会话。 | 200:{ id },团队空间 ID。 |
| DELETE /api/workspaces/invitations/:id | 需当前团队及成员管理权限;管理员不能撤销管理员邀请。 | 200:{ ok: true }。 |
| PATCH /api/organization/members/:id | 管理当前空间成员,需 members.manage;团队成员的 expectedUpdatedAt 必须与读取值一致,可更新 role、enabled(布尔值)、displayName。 | 200:{ user },更新后的成员。 |
切换成功后,后续请求使用返回的新 token。清除旧空间的页面缓存、关闭旧实时订阅,并以新身份重新加载。旧标签页的会话不会因切换自动退出。若发送 X-Tenant-Id,它必须匹配令牌所属空间,不能靠修改此请求头切换空间。
{
"name": "产品研发团队",
"requestId": "11111111-2222-4333-8444-555555555555"
}上例 requestId 是格式示例,实际创建时为每次新的创建意图生成一个唯一标识。相同账号以相同名称和 requestId 重试会返回原空间;同一标识换名称返回 409。
{
"username": "colleague",
"role": "operator"
}邀请有效期 7 天。同账号、同角色的有效待接受邀请会复用;不同角色返回 409,需先撤销。已加入的有效成员不能重复邀请。接受同一已接受邀请会返回原团队 ID,但成员已停用时返回 409,不恢复访问。
{
"role": "viewer",
"expectedUpdatedAt": "2026-10-30T08:00:00.000Z"
}expectedUpdatedAt 示例必须替换为成员列表中实际读取的 updatedAt。遇到 409 先刷新核对,不要自动覆盖。团队成员通过邀请加入,不能用 POST /api/organization/members 新建团队账号;团队管理员不能重置成员的个人密码。完整操作说明见团队协作空间。
写入、幂等与权限
POST /api/sync 触发同步,POST /api/bugs/:id/task 从缺陷生成任务,均要求 work.execute。任务命令通过 POST /api/task-center,执行通过 POST /api/task-center/execute;请求结构和版本约束请核对对应版本源码。
写入前校验归属、版本、幂等标识与权限。超时不等于失败;涉及 Agent 的请求结果不确定时应查询原请求状态并人工核对,不要自动重试或改用另一通道。
错误与实时通知
| 状态 | 含义与处理 |
|---|---|
| 400 | 输入不合法;修正参数。 |
| 401 | 未登录或会话过期;重新登录。 |
| 403 | 权限不足或跨租户请求;核对身份和权限。 |
| 404 | 资源或接口不存在;未知业务接口默认拒绝。 |
| 409 | 冲突;读取当前状态后核对版本。 |
| 429 | 登录等操作受限;按提示等待。 |
| 500 / 503 | 服务错误或不可用;核对原请求状态和服务日志。 |
错误通常包含 error 与 message;部分接口仅包含 message。WebSocket /api/realtime 的 task-center 通道通知租户版本变化,客户端再读取增量。通知不是完整数据快照。