1. URL、格式与版本
- 业务接口前缀：
/open/v1。 - 请求和响应使用 JSON；字段统一为
snake_case。 - OAuth Token 和吊销端点使用
application/x-www-form-urlencoded。 - 版本位于 URL 中。
v1内只做向后兼容的字段扩展，不改变既有字段含义。
2. 身份与资源边界
- 用户身份只来自 Bearer 凭证。
- 不接受
user_id、openid等参数改变当前用户。 openid只用于你的应用建立用户映射。- 项目相关接口继续执行与 Meoo 业务一致的项目权限、用户状态和业务准入检查；Scope 不是资源权限的替代品。
- 无权访问的资源通常与不存在资源一样返回 404，避免资源枚举。
3. 类型
| 类型 | 对外表示 |
|---|---|
| 时间 | Unix 毫秒时间戳，JSON integer |
| 数据库 BIGINT、文件大小等可能超出 JS 安全整数的值 | 十进制字符串 |
项目 url_id、Run ID、Release ID、Action ID | 应完整保存并原样使用的字符串 |
| URL | 完整 HTTPS URL 或 null，按 Schema 定义 |
number；需要运算时使用 BigInt 或高精度十进制库。
4. 分页
列表统一使用：
- 请求：
page_size、page_token。 - 响应：
next_page_token。 page_size=0或不传时默认 20，最大 100。
page_token 与当前查询条件绑定。请原样回传，不要解析、修改或自行生成；翻页期间保持筛选条件不变。收到 invalid_page_token 时从第一页重新开始。
5. 幂等
会触发耗时写操作的接口使用 Idempotency-Key：
- 由调用方生成高熵、不复用的字符串。
- 同一个逻辑操作重试时复用同一个 Key。
- 不同逻辑操作必须使用不同 Key。
- 不要把用户输入、Token 或其他敏感信息直接放入 Key。
6. SSE
SSE 请求仍通过 Authorization Header 认证，不支持把 Token 放在 Query 中。
Agent 的事件字段、快照替换和 Action 回复语义见 事件流与 Action。
客户端应：
- 按
event:名称分发事件。 - 把每个
data:作为 JSON 解析。 - 忽略未知事件和未知字段。
- 仅在网络错误和可恢复服务端错误时有限重连。
- 收到终态事件后停止重连。
Cache-Control: private, no-cache, no-store, no-transform 并禁止代理缓冲。
7. 错误
OAuth 端点返回 OAuth 标准错误：
/open/v1 返回 application/problem+json：
code 分支处理，不要解析可能本地化的 title 或 detail。
| HTTP | 常见 code | 含义 |
|---|---|---|
| 400 | invalid_request | 参数或请求体不合法 |
| 400 | invalid_query | SQL 语法、对象名称或约束不合法；修改查询后重试 |
| 400 | invalid_grant | Code 或 Refresh Token 无效、已使用或过期 |
| 400 | invalid_page_token | 分页游标无效或与筛选条件不匹配 |
| 401 | invalid_client | Client 凭证或认证方式不正确 |
| 401 | invalid_token | Bearer 凭证无效、过期或已撤销 |
| 403 | insufficient_scope | 缺少接口要求的 Scope |
| 403 | forbidden / access_denied | 业务准入拒绝或用户拒绝授权 |
| 404 | not_found | 资源不存在或当前用户无权访问 |
| 409 | cloud_not_enabled | 项目尚未启用对应云能力 |
| 413 | response_too_large | 公开接口响应超过上限 |
| 429 | temporarily_unavailable | 超过限频，遵循 Retry-After |
| 502 | upstream_error | 依赖服务暂不可用 |
8. 响应 Header
X-Meoo-Trace-Id：排查请求的标识；反馈问题时提供该值。Cache-Control: private, no-store：私有 JSON 响应不得由共享缓存保存。WWW-Authenticate：401 或 Scope 不足时提供认证提示。Retry-After：429 后至少等待的秒数。