通用约定

标识符与时间

资源 ID 是带类型前缀的不可变字符串，例如 project_…、session_… 和 work_…。时间使用 ISO 8601 字符串。客户端应把 ID 当作不透明值，不要依赖长度或自行解析业务含义。

幂等请求

创建项目、创建会话和重建 WorkSet 等可能重试的写操作需要 Idempotency-Key。同一个业务动作重试时复用原值，不同动作必须使用新值。

Code
Idempotency-Key: 018f6d7e-0dd1-7b67-9f65-2ec3fd436ef0

上传音频分块还必须提供 X-CapWorks-Chunk-ID。服务端会在响应中标明该分块是否为重复提交。

错误响应

业务 API 使用稳定的错误结构：

Code
{
  "error": {
    "code": "project_not_found",
    "message": "Project not found.",
    "retryable": false,
    "requestId": "request_..."
  }
}

自动重试前必须同时检查 HTTP 状态和 retryable。验证错误、权限错误和幂等键冲突不应盲目重试。

实时连接

WebSocket 连接使用现有登录会话。会话和成果协作通道支持 resume 消息，客户端应保存最后收到的 sequence，并在断线重连时请求补发。实时草稿更新携带客户端生成的 updateId，用于重复提交去重。完整消息联合类型见实时 API。