> ## 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.

# 会话与恢复

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

## 新建与继续

首次启动时省略 `conversation_id`：

```text theme={null}
{
  "message": "创建一个活动报名网站"
}
```

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

```text theme={null}
{
  "message": "增加报名记录导出功能",
  "conversation_id": "conv_01JEXAMPLE"
}
```

会话与项目绑定。不能把项目 A 的 `conversation_id` 用在项目 B 的路径中，也不能通过会话 ID 绕过项目权限。

省略 `skills` 时，继续会话会继承该会话保存的用户 Skill 选择；详细规则见 [附件与 Skills](https://alidocs.dingtalk.com/i/nodes/R1zknDm0WR6XzZ4LtzmdN0N7WBQEx5rG)。模型、性能档位和禁云参数按下表分别处理；内部 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 目录中。

## 查询会话列表

```text theme={null}
GET /projects/{project_id}/agent/conversations
```

所需权限：`agent.read`

按会话创建时间从新到旧返回；查询不会创建新会话，也不会触发 Agent。

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

```text theme={null}
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}"
```

```text theme={null}
{
  "conversations": [
    {
      "conversation_id": "conv_01JEXAMPLE",
      "created_at": 1786410000000
    }
  ],
  "next_page_token": "opaque_page_token"
}
```

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

## 查询会话公开消息

```text theme={null}
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`。

```text theme={null}
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}"
```

```text theme={null}
{
  "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。

## 页面刷新恢复

推荐流程：

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

`runs/current` 在没有活动 Run 时返回最近一次终态 Run，因此不能把 `200` 等同于“正在运行”。必须检查 `status`。

`runs/current` 返回最后持久化的 `model` 和 `speed_tier`，可用于恢复 UI。刚启动时它不构成与 start 响应相同的原子确认；启动响应保存本次选择，重新启动时则应按当前 capabilities 校验可选值。

公开 messages 接口仍只返回用户/助手文本，不会因为 SSE 新增 `tool_calls` 而返回工具参数或积分。工具展示通过对应 Run 的 SSE 快照或接入方已保存状态恢复；结算事件只可能在缓存窗口内重放，不要把历史消息当作完整积分账单。

## 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` 超时：

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

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

## 数据保存建议

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