本目录按调用流程组织 Agent OpenAPI 文档，重点说明客户端应如何组合接口、维护状态和处理恢复。
你需要：
Run 的已知状态包括：
遇到未知状态时按非终态处理，避免后续扩展导致客户端提前结束。
run.superseded 是结束旧订阅的事件，不是新的 Run 状态。它携带旧 Run 的真实终态，并可能提供接管任务的 current_run_id。
不要保存 SSE 帧 id 用于跨连接续传；服务端不支持 Last-Event-ID。断线后重新连接同一事件端点，使用 message.snapshot 恢复文本和可选的 tool_calls，并按 usage_id 去重结算事件。
☐ Token 和 API Key 只保存在可信服务端。
☐ 每条用户消息使用独立 Idempotency-Key，超时重试复用原键及相同配置。
☐ run_id 与 conversation_id 分开保存，没有混用。
☐ 模型选项来自 capabilities；模型和档位省略时使用本次默认值，继续会话时按需显式重传。
☐ disable_cloud 仅本次 Run 生效；同 Run 恢复保留，下一次 Run 省略为 false，YOLO 不能绕过。 ☐ SSE 使用 Authorization Header，没有把 Token 放进 Query。
☐ 凭证具有 agent.read，并按 tool_call_id 和字段正确处理默认发送的工具 delta/snapshot。
☐ message.snapshot.content 使用替换语义；tool_calls 存在时整体替换，缺省时保留已有工具状态。
☐ 区分参数生成完成与工具执行成功，实际结果读取 tool.call.outcome，并处理 truncated 标记。
☐ run.usage 按 usage_id 去重，使用整数安全的方式累加字符串 credits_used；缺失事件不视为零消耗。
☐ 能处理 run.input_required 的 answers 和 confirmation 两种 Action。
☐ 能识别 unsupported_action 并引导用户到 Meoo Web。
☐ 重连 input_required Run 时，用最新签发的 Action Token 替换旧 Token。
☐ 将正常终态作为最后一个业务帧处理；终态后停止重连，未知事件和字段能够被忽略。
☐ 附件签名 URL 和 Action Token 没有进入日志。
☐ 支持人员可以用 X-Meoo-Trace-Id 排查问题。
开始前
你需要：
- OAuth Access Token 或用户 API Key。
- 一个可访问项目的 url_id，作为 Agent 路径中的 project_id。
- 查询模型与性能档位、启动和交互使用 agent.run；读取状态、SSE（默认包含 Write/Edit 正文）和历史使用 agent.read。 项目不存在时，可以先通过 POST /open/v1/projects 创建，详见 用户与项目 API。
- 调用 GET .../agent/capabilities 获取实时模型目录、性能档位和默认值，不要硬编码模型 ID。
- 为用户消息生成稳定的 Idempotency-Key。
- 调用 POST .../agent/runs，保存返回的 run_id、conversation_id、本次 model 和 speed_tier；需要禁用 Meoo Cloud 时在请求中传 disable_cloud: true。
- 立即订阅该 run_id 的 SSE；Write/Edit 白名单正文默认通过工具事件输出。
- 将 message.delta 追加到回复；将 message.snapshot.content 作为全量文本替换。存在 tool_calls 时整体替换当前轮公开工具状态，缺省时保留已有状态。
- 收到 run.input_required 时，根据 action.kind 和 action.input_schema 收集输入并回复。
- 按 usage_id 去重并累加每条 run.usage.data.credits_used；一条是单次结算值，同一 Run 可多次结算。最终结算事件若有，会先于正常终态。
- 收到终态后停止重连。继续对话时把原 conversation_id 放入新的 Run 请求；需要保持模型、档位或禁云配置时再次显式传入。
- 每次新 Run 的 model、speed_tier 省略时使用当前 capabilities 默认值，disable_cloud 省略为 false；同一 Run 的恢复和压缩保留已保存配置。禁云时不会调用 Meoo Cloud CLI 或生成云确认卡，已有云资源不会被关闭；外部 API 仍可用，缺少后端时使用 mock 并如实说明。
状态模型
Run 的已知状态包括：
| 状态 | 是否终态 | 客户端处理 |
|---|---|---|
submitted | 否 | 已准入，准备执行 |
working | 否 | 展示公开进度并继续消费 SSE |
input_required | 否 | 展示 Action；提交回复后继续订阅 |
completed | 是 | 展示最终内容或预览 |
failed | 是 | 展示失败并允许用户重新发起 |
canceled | 是 | 展示已取消 |
interrupted | 是 | 展示执行中断 |
客户端需要保存什么
| 数据 | 保存期限 | 用途 |
|---|---|---|
project_id | 项目生命周期 | 所有项目资源路径 |
conversation_id | 会话生命周期 | 继续同一对话、读取历史 |
run_id | 至少保留到 Run 结束 | 订阅事件、取消和刷新恢复 |
已处理的 usage_id 与积分累计值 | 至少覆盖本次 Run 和页面恢复 | 防止重连重放导致积分重复累计 |
model / speed_tier | 至少保留到 Run 结束 | 展示本次选择；下一次 Run 需要显式重传才能保持 |
请求中的 disable_cloud | 至少保留到 Run 结束 | 同 Run 恢复保留；下一次 Run 省略为 false |
按 tool_call_id 维护的工具状态 | Run 展示和恢复期间 | 处理输入 delta/snapshot 与当前轮工具快照 |
Idempotency-Key | 至少覆盖请求重试窗口 | 同一消息的安全重试 |
action_id | 仅当前 Action，有效期内 | 回复问答或确认；不得解析 |
X-Meoo-Trace-Id | 按排障需要 | 联系支持时定位请求 |
专题文档
| 专题 | 内容 |
|---|---|
| Run 生命周期 | capabilities、模型与档位、单次禁云、start/current/cancel、幂等与错误 |
| 事件流与 Action | 工具输入流、执行结果、文本/工具快照、积分去重、重连与 Action |
| 附件与 Skills | 公网附件、直传票据、自定义 Skill 三态选择语义 |
| 会话与恢复 | 参数继承、conversation 延续、历史分页、页面刷新和断线恢复 |