> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通用协议

## 1. URL、格式与版本

* 业务接口前缀：`/open/v1`。
* 请求和响应使用 JSON；字段统一为 `snake_case`。
* OAuth Token 和吊销端点使用 `application/x-www-form-urlencoded`。
* 版本位于 URL 中。`v1` 内只做向后兼容的字段扩展，不改变既有字段含义。

调用方必须忽略未知 JSON 字段和未知枚举值，避免服务端兼容扩展导致失败。

## 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 定义 |

禁止把 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。

Agent Run 和 Release 的具体幂等窗口、必填性以 OpenAPI 契约为准。

## 6. SSE

SSE 请求仍通过 `Authorization` Header 认证，不支持把 Token 放在 Query 中。

Agent 的事件字段、快照替换和 Action 回复语义见 [事件流与 Action](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/17319bd5-e1db-4375-9a50-ea0b2415ed61)。

客户端应：

1. 按 `event:` 名称分发事件。
2. 把每个 `data:` 作为 JSON 解析。
3. 忽略未知事件和未知字段。
4. 仅在网络错误和可恢复服务端错误时有限重连。
5. 收到终态事件后停止重连。

响应会使用 `Cache-Control: private, no-cache, no-store, no-transform` 并禁止代理缓冲。

## 7. 错误

OAuth 端点返回 OAuth 标准错误：

```text theme={null}
{
  "error": "invalid_grant",
  "error_description": "授权码无效、已使用或已过期"
}
```

`/open/v1` 返回 `application/problem+json`：

```text theme={null}
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "page_size 必须是非负整数",
  "code": "invalid_request",
  "trace_id": "7f0d..."
}
```

按 HTTP 状态和 `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 后至少等待的秒数。