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. 类型
禁止把 BIGINT 字符串转为 JavaScript
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。
8. 响应 Header
X-Meoo-Trace-Id：排查请求的标识；反馈问题时提供该值。Cache-Control: private, no-store：私有 JSON 响应不得由共享缓存保存。WWW-Authenticate：401 或 Scope 不足时提供认证提示。Retry-After：429 后至少等待的秒数。