会话与恢复

Conversation 表示用户与 Agent 的持续上下文；Run 表示其中一条用户消息触发的执行。继续对话时复用 conversation_id，订阅或取消某次执行时使用 run_id。

新建与继续

首次启动时省略 conversation_id：

{
  "message": "创建一个活动报名网站"
}

保存响应中的 conversation_id。后续消息继续该会话：

{
  "message": "增加报名记录导出功能",
  "conversation_id": "conv_01JEXAMPLE"
}

会话与项目绑定。不能把项目 A 的 conversation_id 用在项目 B 的路径中，也不能通过会话 ID 绕过项目权限。省略 skills 时，继续会话会继承该会话保存的用户 Skill 选择；详细规则见附件与 Skills。模型、性能档位和禁云参数按下表分别处理；内部 mode、MCP 配置和 Web 端扩展字段仍不可通过 OpenAPI 覆盖。

配置继承规则

参数	同一 conversation 启动下一次 Run 时
`model`	省略使用当前 `capabilities.defaults.model`，不继承上次模型；保留选择需显式重传。
`speed_tier`	省略使用 `standard`，不继承上次档位；保留选择需显式重传。
`disable_cloud`	省略或 `false` 均为不禁用，上一 Run 的 `true` 不自动继承；仍需禁云时重传 `true`。
`skills`	省略继承该会话保存的 Skill 选择；显式空数组清空选择。
`yolo`	已持久化的 `true` 可继续生效；`false` 或省略不能清除它，也不能绕过禁云策略。

上述“下一次 Run”与“同一 Run 恢复”不同：回复 Action、工具或进程恢复、上下文压缩不会创建一次新的外部启动请求，应沿用该 Run 已保存的配置。禁云策略也会传给该 Run 的子 Agent。前面的最小继续会话示例省略了模型、档位和禁云参数，因此使用当前默认模型、standard 和 disable_cloud: false。若希望延续上次选择，请显式补齐；模型 ID 必须仍在当前 capabilities 目录中。

查询会话列表

GET /projects/{project_id}/agent/conversations

所需权限：agent.read 按会话创建时间从新到旧返回；查询不会创建新会话，也不会触发 Agent。

Query	说明
`page_size`	默认 20，最大 100；`0` 按默认值处理
`page_token`	上一页返回的不透明令牌

curl --request GET \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/conversations?page_size=20" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}"

{
  "conversations": [
    {
      "conversation_id": "conv_01JEXAMPLE",
      "created_at": 1786410000000
    }
  ],
  "next_page_token": "opaque_page_token"
}

next_page_token 只在还有下一页时返回，必须与原查询条件一起原样回传。

查询会话公开消息

GET /projects/{project_id}/agent/conversations/{conversation_id}/messages

所需权限：agent.read

Query	说明
`page_size`	默认 20，最大 100
`page_token`	上一页令牌
`order`	`asc`（默认，旧到新）或 `desc`（新到旧）

page_token 与 order 绑定。改变方向后必须从第一页重新查询；跨方向复用令牌会返回 400 invalid_page_token。

curl --request GET \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/conversations/${CONVERSATION_ID}/messages?order=asc&page_size=50" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}"

{
  "messages": [
    {
      "message_id": "msg_01JEXAMPLE",
      "role": "user",
      "content": "创建一个活动报名网站",
      "created_at": 1786410000000
    },
    {
      "message_id": "msg_01JEXAMPLE2",
      "role": "assistant",
      "content": "活动报名网站已经生成完成。",
      "created_at": 1786410060000
    }
  ]
}

消息接口只返回已落库且适合最终用户展示的 user / assistant 文本，不返回：

system prompt 或 system reminder。
隐藏上下文和内部消息。
工具参数、工具调用和工具结果。
metadata、Token 用量和内部诊断信息。

该接口用于历史记录，不是实时输出通道。Run 执行期间仍应消费 SSE。

页面刷新恢复

推荐流程：

调用 GET /projects/{project_id}/agent/runs/current。
如果返回 submitted、working 或 input_required，用返回的 run_id 重新订阅 SSE。
如果是 input_required，使用重连后新签发的 action_id 替换本地旧 Token。
收到 message.snapshot 时整段替换本地回复文本；存在 tool_calls 时整体替换当前轮公开工具列表，缺省时保留已有工具状态。
处理重放的 run.usage 前按 usage_id 去重，再累加 credits_used；刷新前已处理的结算不能重复累计。
如果返回终态，可读取目标 conversation_id 的消息历史恢复页面。
项目从未有 Run 而返回 404 时，展示空会话状态。

runs/current 在没有活动 Run 时返回最近一次终态 Run，因此不能把 200 等同于“正在运行”。必须检查 status。 runs/current 返回最后持久化的 model 和 speed_tier，可用于恢复 UI。刚启动时它不构成与 start 响应相同的原子确认；启动响应保存本次选择，重新启动时则应按当前 capabilities 校验可选值。公开 messages 接口仍只返回用户/助手文本，不会因为 SSE 新增 tool_calls 而返回工具参数或积分。工具展示通过对应 Run 的 SSE 快照或接入方已保存状态恢复。素材 Bash 快照可包含 sub_type、状态和可公开的 result，用于恢复图片、视频、语音或音乐结果卡；普通 Shell 命令不进入工具快照。结算事件只可能在缓存和 Run 状态允许时重放，不保证补齐全部历史积分，不要把历史消息当作完整积分账单。

SSE 断线恢复

不支持 Last-Event-ID，帧 id 不能跨连接复用。
重新 GET 同一 run_id 的 events 端点。
保留当前文本和按 tool_call_id 维护的工具状态，等待 message.snapshot 全量校正；存在 tool_calls 时替换，缺省时保留。
tool.input.delta 按工具与字段追加，tool.input.snapshot 整体替换该工具输入；对重放的 run.usage 按 usage_id 去重后累计。
不要重新 POST 同一 Run 来恢复 SSE；只有启动请求本身结果不确定时才使用原 Idempotency-Key 重试 start。
收到 run.superseded 时保留旧 Run 的真实终态；存在 current_run_id 时结束旧订阅并切换到新 Run。

启动请求结果不确定

如果 POST .../agent/runs 超时：

使用相同 Idempotency-Key 和完全相同的逻辑请求重试。
不要为同一条消息生成新 Key，否则可能创建重复 Run。
如果收到 409，查询 current 并核对本地消息状态，再决定后续操作。

重试应保持相同 model、speed_tier、disable_cloud。模型和档位的解析值参与幂等摘要，省略模型但默认目录已经变化时，同一键也可能冲突；禁云 false 与省略等价，切换为 true 会改变逻辑请求。

数据保存建议

把 project_id、conversation_id、run_id 当作不透明字符串。
按 Run 保存 model、speed_tier 和本次请求的 disable_cloud，继续对话时按意图显式重传。
按 Run 保存已处理的 usage_id 集合及积分累计值，至少覆盖本次运行与页面恢复；主 Agent 和素材可能分别结算，credits_used 是单笔非负整数字符串，使用整数安全的方式累计。积分事件不含 tool_call_id 或 sub_type，不要按到达顺序绑定工具。
按 tool_call_id 区分工具状态，不使用可能重名的 file_name 作为唯一键。
不把 Access Token、API Key、Action Token 或签名附件 URL 写入会话日志。
历史分页游标不应长期保存或跨筛选条件复用。
排障时保存接口时间、HTTP 状态、稳定错误码和 X-Meoo-Trace-Id。

​新建与继续

​配置继承规则

​查询会话列表

​查询会话公开消息

​页面刷新恢复

​SSE 断线恢复

​启动请求结果不确定

​数据保存建议