# 从回答创建会话分支

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

从源会话中的一条已完成回答创建子会话。子会话保留通向该回答的对话内容，并使用独立的 Provider 会话继续对话。


```http
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/{conversation_id}/forks
```

## 调用前准备

`BASE_URL` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

1. 使用目标环境的普通产品身份凭据和工作区。将 `BASE_URL` 设为该环境的完整产品 API 前缀。此入口会拒绝附加的任务运行期授权头。
2. 读取当前用户创建的源会话及其消息。源会话须为 `purpose=chat`、`status=active`、`visibility=visible`。
3. 从源会话选择一条原生的 `assistant` 或 `agent` 消息，填写它的 `id`。该消息须关联同一会话、同一智能体的已完成 Astra 任务，并具有当前用户和工作区匹配的 Provider 会话记录。
4. 为这次分叉生成并保存 `REQUEST_ID`。请求结果未知时，保留原请求 ID、源会话、源消息、标题以及发起时的有效角色。

从已有分支继承的消息带有 `source_message_id`，不能直接作为新的分叉点；可选择该分支后来生成的原生回答。源会话中更晚的其他任务仍在运行，不代表选中的已完成回答不能分叉。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

准备 `WORKSPACE_ID`、`CONVERSATION_ID`、`SOURCE_MESSAGE_ID` 和已保存的 `REQUEST_ID`。此请求创建子会话，但不会提交新的对话任务。

```bash
jq -n \
  --arg request_id "$REQUEST_ID" \
  --arg source_message_id "$SOURCE_MESSAGE_ID" \
  '{request_id: $request_id, source_message_id: $source_message_id}' > fork-request.json

curl --request POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID/forks" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-binary @fork-request.json
```

保存成功响应中的子会话 `data.id`。通过会话详情和消息列表核对父会话、源消息和继承内容，再使用子会话 ID 继续对话。

:::::
:::::{tab-item} 参数说明

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `workspace_id` | 路径 | string | 是 | 当前用户所属的工作区 ID。 |
| `conversation_id` | 路径 | string | 是 | 源会话 ID。 |
| `agent_id` | 查询 | string | 否 | 限定源会话所属的智能体。 |
| `agent_workspace_id` | 查询 | string | 否 | 限定智能体所属的工作区，只接受当前工作区或 `system`；只能出现一次，空值按当前工作区处理。 |
| `request_id` | 请求体 | string | 是 | 此次分叉的稳定请求 ID，最多 128 字节。 |
| `source_message_id` | 请求体 | string | 是 | 选中回答的消息 ID，最多 128 字节。 |
| `title` | 请求体 | string | 否 | 子会话标题；合法 UTF-8，最多 256 个 Unicode 码点。 |

`request_id` 和 `source_message_id` 不能是空字符串、`.` 或 `..`，不能含 `/`、`\` 或控制字符，前后不能有空白。

省略 `agent_workspace_id` 且指定 `agent_id` 时，智能体工作区默认为路径工作区。`title` 会去掉前后空白；省略、空字符串或全部为空白时，系统根据源会话标题生成带序号的标题。省略或传入 `null` 的 `title` 都由当前字符串绑定处理为空标题。

分叉复制所选回答的祖先分支，包含所选回答。重新生成的其他回答版本及其后续消息不会因时间较早就被一起复制。子会话消息使用新的 ID，通过 `source_message_id` 标识来源；继承消息没有源任务或执行清单身份。显示内容中的文件引用保留为引用，不表示复制全部物理文件或授予新的文件权限。

同一工作区和用户下，请求 ID 标识同一次分叉。确认结果时保持源会话、源消息、标题和原有效角色一致。同一请求 ID 改换内容会发生冲突；只改变有效角色时，返回角色变化错误。请求 ID 不是客户端指定的子会话 ID。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "id": "7d694ce0-e9e6-5e16-b7aa-ef0ecbe261d5",
    "workspace_id": "workspace-example",
    "agent_workspace_id": "workspace-example",
    "agent_id": "agent-example",
    "agent_summary": {
      "id": "agent-example",
      "workspace_id": "workspace-example",
      "display_name": "知识问答",
      "status": "active",
      "available": true
    },
    "title": "数据分析（2）",
    "title_user_edited": true,
    "status": "active",
    "purpose": "chat",
    "visibility": "visible",
    "parent_conversation_id": "conversation-example",
    "source_message_id": "assistant-example",
    "pinned": false,
    "head_message_id": "child-message-example",
    "last_message_at": "2026-11-12T01:00:00Z",
    "created_at": "2026-11-12T02:00:00Z",
    "updated_at": "2026-11-12T02:00:00Z"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 `0`；HTTP 状态码为 `201`。 |
| `data.id` | string | 服务端生成的子会话 ID；成功表示分叉会话已发布。 |
| `data.workspace_id` | string | 会话所属工作区 ID。 |
| `data.agent_workspace_id` | string | 智能体所属工作区 ID。 |
| `data.agent_id` | string | 智能体 ID，与源会话相同。 |
| `data.agent_summary` | object | 智能体的当前展示信息和可用状态。 |
| `data.agent_summary.id` | string | 智能体 ID。 |
| `data.agent_summary.workspace_id` | string | 智能体工作区 ID；有值时返回。 |
| `data.agent_summary.display_name` | string | 智能体名称；有值时返回。 |
| `data.agent_summary.avatar_ref` | string | 头像引用；有值时返回。 |
| `data.agent_summary.status` | string | 智能体状态；有值时返回。 |
| `data.agent_summary.available` | boolean | 智能体当前是否可用。 |
| `data.agent_summary.unavailable_reason` | string | 不可用原因；有值时返回。 |
| `data.title` | string | 子会话标题；有值时返回。 |
| `data.title_user_edited` | boolean | 分叉标题标记为已编辑，异步标题生成不会覆盖它。 |
| `data.status` | string | 会话状态。新分支为 `active`。 |
| `data.purpose` | string | 会话用途。分叉为 `chat`。 |
| `data.visibility` | string | 会话可见性。成功发布后为 `visible`。 |
| `data.parent_conversation_id` | string | 源会话 ID。 |
| `data.source_message_id` | string | 选中的源回答消息 ID。 |
| `data.pinned` | boolean | 是否置顶。新分支为 `false`。 |
| `data.head_message_id` | string | 子会话中复制后的末条消息 ID。 |
| `data.active_task_id` | string | 当前任务 ID；有值时返回。分叉本身不创建任务。 |
| `data.latest_task_id` | string | 最近任务 ID；有值时返回。新分支未继承源任务 ID。 |
| `data.latest_task_state` | string | 最近任务状态；有值时返回。 |
| `data.last_message_at` | string | 末条继承消息的时间；有值时返回。 |
| `data.created_at` | string | 子会话创建时间，RFC 3339 格式。 |
| `data.updated_at` | string | 子会话更新时间，RFC 3339 格式。 |

:::::
::::::
:::::::

## 错误响应

```json
{"code":"conversation_fork_role_changed","msg":"此分支操作由另一个角色发起。请切回发起时使用的角色，再重试以确认结果。"}
```

| HTTP 状态码 | `code` | 条件及处理 |
| --- | --- | --- |
| 400 | `conversation_fork_invalid` | 分叉参数或分叉记录无效。检查请求字段。 |
| 403 | `conversation_fork_forbidden` | 当前主体或 Provider 会话身份不满足分叉条件。 |
| 404 | `conversation_fork_not_found` | 源会话、选中消息或相关 Provider 对象不存在或不符合读取范围。 |
| 409 | `conversation_fork_not_ready` | 选中任务尚未完成，或 Provider 的对应位置尚未就绪。保留原请求身份确认结果。 |
| 422 | `conversation_fork_unsupported` | 会话用途、消息类型、Provider 位置或历史文件引用不支持分叉。 |
| 409 | `conversation_fork_conflict` | 相同请求 ID 对应不同请求内容，或 Provider 返回分叉冲突。 |
| 409 | `conversation_fork_role_changed` | 重试使用了不同有效角色。切回原角色确认结果。 |
| 409 | `conversation_fork_pending` | 同一次操作仍在执行、竞争执行权或等待继续。保留原请求内容重试。 |
| 410 | `conversation_fork_aborted` | Provider 已确认该分叉终止。需要重新创建时使用新的请求 ID。 |
| 429 | `conversation_fork_quota_exceeded` | Provider 的用户会话数、并发会话数或每日 token 配额不足。处理配额后再发起新的操作。 |
| 503 | `conversation_fork_unavailable` | 依赖、存储或响应确认失败；操作可能已经产生效果。保留原请求内容确认结果。 |

身份认证、路径与查询参数校验、工作区准入可能先于分叉业务校验返回通用错误。错误 `msg` 会按请求语言本地化，程序应读取 `code`。

超时、断开连接或 `503` 都不能证明没有创建分支。系统会保留无法确认结果的操作并尝试恢复；恢复仍使用发起时的用户和有效角色重新校验准入。确认结果前，不要更换请求 ID 重复创建同一分支，也不要将关闭页面视为取消。
