对话模块 API 文档（实时抓取版）

本文档由本地运行中的 KIAP 后端（http://localhost:8001）真实请求抓取生成，非手写推测。用于前端对接、回归核对。git 版本号为快照节点，后期 git 更新后可据此区分接口是否变化。

0. 快照信息（git 版本号，重要！）

项	值
git commit（短）	`4f46278`
git commit（完整）	`4f462789875d362ff4b9106a7b73222e8c58b632`
commit 日期	`2026-08-11`
后端端口	`8001`
接口前缀	`/external/private/api`
Controller	`conversation/api/{ConversationController, ConversationMessageController, ConversationTurnController, ConversationCaseController, ConversationAgentDraftSuggestionController, RecommendedWordController}.java`
抓取时间	`2026-08-12`

⚠️ 后期若 git pull / rebase 导致接口变化，以本 commit 4f46278 为基线对比。

1. 鉴权头（所有接口必带）

见 agent-module-api.md 第 1 节：必须同时带 DEFrame-UserId / DEFrame-TenantId / DEFrame-ExtendedInfo: {}，否则 TPT_ACCESS_DENIED。

2. 接口总览

#	方法	路径	说明	类型
1	GET	`/external/private/api/conversations`	会话列表（分页）	租户过滤
2	GET	`/external/private/api/conversations/{conversationId}`	会话详情	租户过滤
3	POST	`/external/private/api/conversations`	创建会话	写
4	PATCH	`/external/private/api/conversations/{conversationId}`	更新会话	写
5	DELETE	`/external/private/api/conversations/{conversationId}`	删除会话	写
6	GET	`/external/private/api/conversations/{conversationId}/messages`	消息列表（游标分页）	租户过滤
7	POST	`/external/private/api/conversations/{conversationId}/messages`	发送消息（SSE 流）	写（SSE）
8	GET	`/external/private/api/conversations/{conversationId}/timeline`	时间线（Turn 分组）	租户过滤
9	GET	`/external/private/api/conversations/{conversationId}/turns`	Turn 列表（游标）	租户过滤
10	GET	`/external/private/api/conversations/{conversationId}/turns/{turnId}`	Turn 详情（含 Blocks）	租户过滤
11	POST	`/external/private/api/conversations/{conversationId}/turns/{turnId}/cancel`	取消运行中的 Turn	写
12	GET	`/external/private/api/conversations/{conversationId}/turns/{turnId}/stream`	重放 Turn SSE 流	租户过滤（SSE）
13	GET	`/external/private/api/cases`	案例列表（分页）	租户过滤
14	GET	`/external/private/api/cases/{caseId}`	案例详情（含消息）	租户过滤
15	POST	`/external/private/api/cases`	保存案例	写
16	PATCH	`/external/private/api/cases/{caseId}`	更新案例	写
17	DELETE	`/external/private/api/cases/{caseId}`	删除案例	写
18	POST	`/external/private/api/cases/{caseId}/share`	分享案例（返回分享链接）	写
19	POST	`/external/private/api/conversations/{conversationId}/save-as-agent`	会话另存为 Agent	写
20	GET	`/external/private/api/conversations/{conversationId}/agent-draft-suggestion`	草稿建议（Agent 推荐）	租户过滤
21	POST	`/external/private/api/conversations/{conversationId}/agent-draft-suggestion`	采纳草稿建议	写
22	GET	`/external/private/api/recommended-words`	推荐词列表（按场景）	租户/全局

另：公网分享接口 GET /external/public/api/cases/{shareId}（无鉴权，返回 PublicCaseShareResponse）。

3. GET 接口（真实返回值）

3.1 GET /external/private/api/conversations

名称：会话列表（分页）作用：分页查询当前用户的会话列表，用于「我的对话」主页。返回 code:200 + data.records[]，字段见 ConversationSummaryResponse：conversationId / title / status / agentId / agentName / expertMode / lastMessage / lastMessageAt / messageCount / hasArtifacts / timeBucket / createdAt / updatedAt；外加分页 current/size/pages/total。

真实数据（节选 1 条，实际 total:158）：

json

{
  "code": "200",
  "data": {
    "records": [
      {
        "conversationId": "conv_769fd08b21474bd29a777648fb5cd9d2",
        "title": "滨州有哪些电站",
        "status": "COMPLETED",
        "agentId": "sys_energy_xiaoxi",
        "agentName": "能源运营专家",
        "expertMode": true,
        "lastMessage": "滨州共有 **12 个电站**……（含表格）",
        "lastMessageAt": "2026-08-11 09:17:55",
        "messageCount": 2,
        "hasArtifacts": false,
        "timeBucket": "LAST_7_DAYS",
        "createdAt": "2026-08-11 09:17:44",
        "updatedAt": "2026-08-11 09:17:55"
      }
    ],
    "current": 1, "size": 10, "pages": 16, "total": 158
  },
  "success": true
}

status：PENDING_ACTION（草稿/待操作）、COMPLETED（完成）等；timeBucket：LAST_7_DAYS 等时间分桶；支持 ?timeBucket= 过滤。

3.2 GET /external/private/api/conversations/

名称：会话详情作用：根据 conversationId 查询会话完整信息（含绑定 Agent、专家模式、资源、进行中运行 ID）。返回 code:200 + data = ConversationDetailResponse：

json

{
  "code": "200",
  "data": {
    "conversationId": "conv_769fd08b21474bd29a777648fb5cd9d2",
    "title": "滨州有哪些电站",
    "status": "COMPLETED",
    "agent": {
      "agentId": "sys_energy_xiaoxi",
      "name": "能源运营专家",
      "icon": null
    },
    "expertMode": true,
    "resources": [],
    "activeRunId": null,
    "createdAt": "2026-08-11 09:17:44",
    "updatedAt": "2026-08-11 09:17:55"
  },
  "success": true
}

3.3 GET /external/private/api/conversations/{conversationId}/messages

名称：消息列表（游标分页）作用：查询会话消息（USER/ASSISTANT 等），支持游标上/下翻页，用于对话窗口渲染。返回 code:200 + data.messages[]（ConversationMessageResponse）+ nextCursor/prevCursor/hasMore。

ConversationMessageResponse 字段：messageId / role / messageType / content / answerContent / thinkingSteps / sequenceNo / agentId / runId / turnId / parentBlockId / toolName / attachments[] / createdAt。

真实数据（节选 USER 与 ASSISTANT 各 1 条）：

json

{
  "code": "200",
  "data": {
    "messages": [
      {
        "messageId": "msg_18c39c7f22934ef2b7140512c1230b2c",
        "role": "USER",
        "messageType": "TEXT",
        "content": "滨州有哪些电站",
        "answerContent": null,
        "thinkingSteps": null,
        "sequenceNo": 1,
        "agentId": "sys_energy_xiaoxi",
        "runId": "run_d904e0d4a0a944d79cd90f93d4de3267",
        "turnId": null,
        "parentBlockId": null,
        "toolName": null,
        "attachments": [],
        "createdAt": "2026-08-11 09:17:45"
      },
      {
        "messageId": "msg_8ec024bcd4bb4bcbb18e7c6620666618",
        "role": "ASSISTANT",
        "messageType": "ANSWER",
        "content": "滨州共有 **12 个电站**……（完整 markdown）",
        "answerContent": "滨州共有 **12 个电站**……（完整 markdown）",
        "thinkingSteps": null,
        "sequenceNo": 2,
        "agentId": "sys_energy_xiaoxi",
        "runId": "run_d904e0d4a0a944d79cd90f93d4de3267",
        "turnId": null,
        "parentBlockId": null,
        "toolName": null,
        "attachments": [],
        "createdAt": "2026-08-11 09:17:55"
      }
    ],
    "nextCursor": "2", "prevCursor": "1", "hasMore": false
  },
  "success": true
}

role：USER/ASSISTANT；messageType：TEXT/ANSWER/CHOICE_REQUEST 等；runId 关联 AgentRun（即执行记录）。

3.4 GET /external/private/api/conversations/{conversationId}/timeline

名称：时间线（Turn 分组）作用：以「用户消息 + 其下 Turn」分组的时间线，供前端按对话轮次渲染。返回 code:200 + data.items[]（ConversationTimelineItemResponse），元素 kind: "TURN_GROUP" + sourceMessage + turns[]（嵌套 Turn 摘要 + blocks[]）。

真实数据（节选 1 个 turn-group 的 sourceMessage + 1 个 turn）：

json

{
  "code": "200",
  "data": {
    "items": [
      {
        "kind": "TURN_GROUP",
        "itemId": "turn-group:source:msg_18c39c7f22934ef2b7140512c1230b2c",
        "anchorAt": "2026-08-11 09:17:45",
        "sourceMessage": {
          "messageId": "msg_18c39c7f22934ef2b7140512c1230b2c",
          "role": "USER", "messageType": "TEXT",
          "content": "滨州有哪些电站", "answerContent": null,
          "thinkingSteps": null, "sequenceNo": 1,
          "agentId": "sys_energy_xiaoxi",
          "runId": "run_d904e0d4a0a944d79cd90f93d4de3267",
          "turnId": null, "parentBlockId": null, "toolName": null,
          "attachments": [], "createdAt": "2026-08-11 09:17:45"
        },
        "syntheticUser": null,
        "turns": [
          {
            "turnId": "turn_d8156a03b8914de5a398ab3a4572de86",
            "conversationId": "conv_769fd08b21474bd29a777648fb5cd9d2",
            "sourceMessageId": "msg_18c39c7f22934ef2b7140512c1230b2c",
            "state": "COMPLETED",
            "activeAgentId": "sys_energy_xiaoxi",
            "activeAgent": { "agentId": "sys_energy_xiaoxi", "name": "能源运营专家", "icon": null },
            "activeRunId": "run_d904e0d4a0a944d79cd90f93d4de3267",
            "turnRevision": 26, "lastEventSeq": 27,
            "userContent": "滨州有哪些电站",
            "answerPreview": "滨州共有 **12 个电站**……（预览）",
            "blocks": [ { "blockId": "block_91210fdb7f05435e87e5bf5cbd401339", "kind": "PROCESS", "blockType": "PROCESS", "sortOrder": 10, "position": 10, "status": "COMPLETED", "minimumDisplayMode": "STANDARD", "contentFormat": "PLAIN_TEXT", "content": "图表生成", "payload": { "steps": [] } } ],
            "blockCount": 3, "hasArtifacts": true,
            "startedAt": "2026-08-11 09:17:45", "terminalAt": "2026-08-11 09:17:55",
            "createdAt": "2026-08-11 09:17:45", "updatedAt": "2026-08-11 09:17:55"
          }
        ]
      }
    ]
  },
  "success": true
}

Agent 执行记录（AgentRun）即体现在这里的 turn.activeRunId 与消息 runId（关联 tpt_agent_runs）。

3.5 GET /external/private/api/conversations/{conversationId}/turns

名称：Turn 列表（游标）作用：查询会话下所有 Turn（一轮 Agent 运行）的摘要列表，含运行状态与进行中运行 ID。返回 code:200 + data.items[]（TurnSummaryResponse）+ nextCursor/hasMore。

真实数据（节选 1 条）：

json

{
  "code": "200",
  "data": {
    "items": [
      {
        "turnId": "turn_d8156a03b8914de5a398ab3a4572de86",
        "conversationId": "conv_769fd08b21474bd29a777648fb5cd9d2",
        "sourceMessageId": "msg_18c39c7f22934ef2b7140512c1230b2c",
        "state": "COMPLETED",
        "activeAgentId": "sys_energy_xiaoxi",
        "activeAgent": null,
        "activeRunId": "run_d904e0d4a0a944d79cd90f93d4de3267",
        "turnRevision": 26, "lastEventSeq": 27,
        "userContent": "滨州有哪些电站",
        "answerPreview": "滨州共有 **12 个电站**……",
        "blockCount": 3, "hasArtifacts": true,
        "startedAt": "2026-08-11 09:17:45", "terminalAt": "2026-08-11 09:17:55",
        "createdAt": "2026-08-11 09:17:45", "updatedAt": "2026-08-11 09:17:55"
      }
    ],
    "nextCursor": null, "hasMore": false
  },
  "success": true
}

3.6 GET /external/private/api/conversations/{conversationId}/turns/

名称：Turn 详情（含 Blocks）作用：查询单个 Turn 的完整信息，含 Block 列表（过程/结果块），用于回放某轮运行。返回 code:200 + data = TurnDetailResponse（在摘要基础上扩展 blocks[]，每个 Block：blockId/kind/blockType/sortOrder/position/status/minimumDisplayMode/contentFormat/content/payload）。

真实数据（节选 1 个 PROCESS Block；payload.steps[] 为过程步骤）：

json

{
  "code": "200",
  "data": {
    "turnId": "turn_d8156a03b8914de5a398ab3a4572de86",
    "conversationId": "conv_769fd08b21474bd29a777648fb5cd9d2",
    "sourceMessageId": "msg_18c39c7f22934ef2b7140512c1230b2c",
    "state": "COMPLETED",
    "activeAgentId": "sys_energy_xiaoxi",
    "activeAgent": null,
    "activeRunId": "run_d904e0d4a0a944d79cd90f93d4de3267",
    "turnRevision": 26, "lastEventSeq": 27,
    "userContent": "滨州有哪些电站",
    "answerPreview": "滨州共有 **12 个电站**……",
    "blocks": [
      {
        "blockId": "block_91210fdb7f05435e87e5bf5cbd401339",
        "kind": "PROCESS", "blockType": "PROCESS",
        "sortOrder": 10, "position": 10, "status": "COMPLETED",
        "minimumDisplayMode": "STANDARD", "contentFormat": "PLAIN_TEXT",
        "content": "图表生成",
        "payload": {
          "steps": [
            { "title": "意图识别开始", "status": "thinking", "message": "正在理解您的问题…" },
            { "title": "模型推理", "status": "done", "message": "用户问\"滨州有哪些电站\"…" }
          ]
        }
      }
    ],
    "blockCount": 3, "hasArtifacts": true,
    "startedAt": "2026-08-11 09:17:45", "terminalAt": "2026-08-11 09:17:55",
    "createdAt": "2026-08-11 09:17:45", "updatedAt": "2026-08-11 09:17:55"
  },
  "success": true
}

3.7 GET /external/private/api/cases

名称：案例列表（分页）作用：分页查询当前用户的保存案例（含公开分享的），用于「案例库」展示。返回 code:200 + data.records[]（CaseSummaryResponse）：caseId / title / summary / category / visibility / conversationTitle / agentId / agentName / messageCount / artifactCount / shareUrl / sharedAt / expiresAt / createdAt / updatedAt。

真实数据（节选 1 条，total:11）：

json

{
  "code": "200",
  "data": {
    "records": [
      {
        "caseId": "case_bcd4c4cf4bcf450693d2ef263ac1f7f0",
        "title": "预测数据经典案例",
        "summary": null,
        "category": "ENERGY",
        "visibility": "PRIVATE",
        "conversationTitle": "帮我预测数据",
        "agentId": "sys_smart_forecast_xiaoxi",
        "agentName": "能源预测专家",
        "messageCount": 8, "artifactCount": 2,
        "shareUrl": null, "sharedAt": null, "expiresAt": null,
        "createdAt": "2026-08-07 11:38:57", "updatedAt": "2026-08-07 11:38:57"
      }
    ],
    "current": 1, "size": 10, "pages": 2, "total": 11
  },
  "success": true
}

category：ENERGY/BENEFIT/SAFETY/QUALITY；visibility：PRIVATE/PUBLIC_SHARED。

3.8 GET /external/private/api/cases/

名称：案例详情（含消息）作用：查询案例完整内容，含其来源会话的消息列表（可回放）。返回 code:200 + data = CaseDetailResponse（CaseSummaryResponse + conversationId/conversationTitle/agent{message} + messages[]）。

真实数据（节选结构，messages[] 多条，节选 1 条 USER）：

json

{
  "code": "200",
  "data": {
    "caseId": "case_bcd4c4cf4bcf450693d2ef263ac1f7f0",
    "title": "预测数据经典案例",
    "summary": null,
    "category": "ENERGY",
    "visibility": "PRIVATE",
    "conversationId": "conv_bb16eeeefb814ce8bfff03abc38484ac",
    "conversationTitle": "帮我预测数据",
    "agent": { "agentId": "sys_smart_forecast_xiaoxi", "name": "能源预测专家", "icon": null },
    "messages": [
      {
        "messageId": "msg_76bdfc2c636d4542a48487583ef9077f",
        "role": "USER", "messageType": "TEXT",
        "content": "帮我预测数据", "answerContent": null,
        "thinkingSteps": null, "sequenceNo": 1,
        "createdAt": "2026-08-07 11:03:26"
      }
    ],
    "messageCount": 8, "artifactCount": 2,
    "shareUrl": null, "sharedAt": null, "expiresAt": null,
    "createdAt": "2026-08-07 11:38:57", "updatedAt": "2026-08-07 11:38:57"
  },
  "success": true
}

3.9 GET /external/private/api/recommended-words

名称：推荐词列表（按场景）作用：按 scene（如 CONVERSATION_START）返回推荐提问词，用于对话输入框快捷入口。返回 code:200 + data.items[]（RecommendedWordResponse）：recommendWordId / scene / agentId / agentName / content / description / sortOrder / enabled / metadata。

真实数据（节选 2 条）：

json

{
  "code": "200",
  "data": {
    "items": [
      { "recommendWordId": "rw_system_trade_start", "scene": "CONVERSATION_START", "agentId": null, "agentName": null, "content": "分析本月交易收益", "description": "快速生成本月收益分析", "sortOrder": 10, "enabled": true, "metadata": {} },
      { "recommendWordId": "rw_system_ops_start", "scene": "CONVERSATION_START", "agentId": null, "agentName": null, "content": "总结今日运营异常", "description": "快速查看运营风险", "sortOrder": 20, "enabled": true, "metadata": {} }
    ]
  },
  "success": true
}

支持 ?scene=CONVERSATION_START&agentId= 过滤；agentId 为空表示系统通用词。

3.10 GET /external/private/api/conversations/{conversationId}/agent-draft-suggestion

名称：草稿建议（Agent 推荐）作用：基于会话内容生成「建议另存为的 Agent」草稿（名称/类型/描述/系统提示词草稿）。返回 code:200 + data = ConversationAgentSummaryResponse（含草稿字段；hasDraft/draft 等）。

真实结构以 ConversationAgentSummaryResponse 为准（含 suggestedName/suggestedType/suggestedDescription/suggestedSystemPrompt/draftExists 等字段）。

4. 写接口（请求示例 + 响应示例）

写接口统一使用 R<T> 包装：{ code, message, data, ext, success }。响应标注「结构示例」的基于真实 DTO，未执行实测（避免污染库或触发 SSE 实时流）。

4.1 POST /external/private/api/conversations —— 创建会话（ConversationCreateRequest）

名称：创建会话作用：新建一个会话（可选指定 Agent、专家模式、标题），返回新会话 ID，用于进入对话。 请求示例：

json

{
  "title": "新的对话",
  "agentId": "sys_energy_xiaoxi",
  "expertMode": true,
  "metadata": {}
}

响应示例（结构示例）：

json

{
  "code": "200", "message": null,
  "data": { "conversationId": "conv_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  "ext": null, "success": true
}

4.2 PATCH /external/private/api/conversations/{conversationId} —— 更新会话（ConversationUpdateRequest）

名称：更新会话作用：更新会话标题/状态/绑定的 Agent 等。 请求示例：

json

{ "title": "新标题", "status": "COMPLETED" }

响应示例（结构示例）：R.success(ConversationDetailResponse)（同 3.2）。

4.3 DELETE /external/private/api/conversations/{conversationId} —— 删除会话

名称：删除会话作用：删除会话（级联删除消息/Turn），无请求体。 响应示例：{ "code": "200", "data": { "deleted": true }, "success": true }

4.4 POST /external/private/api/conversations/{conversationId}/messages —— 发送消息（SSE 流）

名称：发送消息作用：向会话发送一条用户消息并触发 Agent 运行，返回 SSE 事件流（非普通 JSON），用于实时渲染。 请求体：SendMessageRequest（content / attachments / interactiveChoice / metadata）。 请求示例：

json

{ "content": "滨州有哪些电站", "attachments": [], "metadata": {} }

响应：text/event-stream SSE 流（event: message / event: turn / event: block / event: error 等），不返回 R<T> JSON。

4.5 POST /external/private/api/conversations/{conversationId}/turns/{turnId}/cancel —— 取消运行

名称：取消运行中 Turn 作用：取消一个正在运行（未完成）的 Turn，返回取消结果。 响应示例（结构示例）：R.success(TurnCancelResponse)（{ turnId, state, cancelled }）。

4.6 POST /external/private/api/conversations/{conversationId}/turns/{turnId}/stream —— 重放 Turn 流

名称：重放 Turn SSE 流作用：以 SSE 流形式重放某个已完成 Turn 的事件（用于断线恢复/历史回放），返回 SSE 流。

4.7 POST /external/private/api/cases —— 保存案例（SaveCaseRequest）

名称：保存案例作用：将某会话（或其中若干消息）保存为案例，便于复用与分享。 请求示例：

json

{
  "conversationId": "conv_769fd08b21474bd29a777648fb5cd9d2",
  "title": "预测数据经典案例",
  "summary": "时序预测示例",
  "category": "ENERGY",
  "visibility": "PRIVATE"
}

响应示例（结构示例）：R.success(SaveCaseResponse)（{ caseId }）。

4.8 PATCH /external/private/api/cases/{caseId} —— 更新案例（UpdateCaseRequest）

名称：更新案例作用：更新案例标题/摘要/分类/可见性。 请求示例：{ "title": "新标题", "summary": "新摘要", "category": "ENERGY", "visibility": "PRIVATE" }响应示例（结构示例）：R.success(CaseSummaryResponse)。

4.9 DELETE /external/private/api/cases/{caseId} —— 删除案例

名称：删除案例作用：删除案例（取消公开分享链接），无请求体。 响应示例：{ "code": "200", "data": { "deleted": true }, "success": true }

名称：分享案例作用：生成案例的公网分享链接（可选有效期），返回分享 URL 与过期时间。 请求示例：{ "expiresAt": null }响应示例（结构示例）：R.success(ShareCaseResponse)（{ caseId, shareUrl, sharedAt, expiresAt }）。

4.11 POST /external/private/api/conversations/{conversationId}/save-as-agent —— 会话另存为 Agent（SaveConversationAsAgentRequest）

名称：会话另存为 Agent 作用：将当前会话沉淀为一个新 Agent（使用草稿建议的系统提示词等），返回新建 Agent ID。 请求示例：

json

{
  "name": "我的电站查询Agent",
  "type": "OPTIMIZATION",
  "description": "基于会话沉淀",
  "systemPrompt": "你是……",
  "groupId": "sys_group_builtin"
}

响应示例（结构示例）：R.success(CreateAgentResponse)（{ agentId, agentCode, ... }），复用 Agent 模块返回结构。

4.12 POST /external/private/api/conversations/{conversationId}/agent-draft-suggestion —— 采纳草稿建议（AgentDraftSuggestionRequest）

名称：采纳草稿建议作用：确认/采纳上一步生成的 Agent 草稿建议，触发「另存为 Agent」流程。 请求示例：{ "accept": true, "draft": { "name": "…", "systemPrompt": "…" } }响应示例（结构示例）：R.success(ConversationAgentSummaryResponse)。

5. 公网分享接口（无鉴权）

5.1 GET /external/public/api/cases/

名称：案例公网详情作用：通过分享链接直接访问案例内容（无需登录），返回脱敏后的案例与消息。 响应示例（结构示例）：R.success(PublicCaseShareResponse)（{ caseId, title, summary, category, agent, messages[] }，不含私密字段）。

6. 错误码速查

code	含义	触发场景
`200`	成功	—
`TPT_ACCESS_DENIED`	403 无权限/无租户	缺 `DEFrame-TenantId` 或 `DEFrame-ExtendedInfo`
`chat_not_found`	资源不存在	`conversationId`/`turnId`/`caseId`/`messageId` 错误
`chat_validation_error`	参数校验失败	请求体字段缺失/类型错误

附录：复现脚本（PowerShell，稳定可靠）

powershell

$h = @{ 'DEFrame-UserId'='1123598821738675201'; 'DEFrame-TenantId'='000000'; 'DEFrame-ExtendedInfo'='{}' }
$base = 'http://localhost:8001/external/private/api'
$c = 'conv_769fd08b21474bd29a777648fb5cd9d2'
$case = 'case_bcd4c4cf4bcf450693d2ef263ac1f7f0'

(Invoke-RestMethod -Uri ($base+'/conversations') -Headers $h) | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\c.json
(Invoke-RestMethod -Uri ($base+"/conversations/$c") -Headers $h) | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\cd.json
(Invoke-RestMethod -Uri ($base+"/conversations/$c/messages") -Headers $h) | ConvertTo-Json -Depth 8 | Out-File -Encoding utf8 C:\temp\cm.json
(Invoke-RestMethod -Uri ($base+"/conversations/$c/timeline") -Headers $h) | ConvertTo-Json -Depth 8 | Out-File -Encoding utf8 C:\temp\ct.json
(Invoke-RestMethod -Uri ($base+"/conversations/$c/turns") -Headers $h) | ConvertTo-Json -Depth 8 | Out-File -Encoding utf8 C:\temp\cturns.json
(Invoke-RestMethod -Uri ($base+"/cases") -Headers $h) | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\cases.json
(Invoke-RestMethod -Uri ($base+"/cases/$case") -Headers $h) | ConvertTo-Json -Depth 12 | Out-File -Encoding utf8 C:\temp\cased.json
(Invoke-RestMethod -Uri ($base+'/recommended-words?limit=3') -Headers $h) | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\rw.json

对话模块 API 文档（实时抓取版） ​

0. 快照信息（git 版本号，重要！） ​

1. 鉴权头（所有接口必带） ​

2. 接口总览 ​

3. GET 接口（真实返回值） ​

3.1 GET /external/private/api/conversations ​

3.2 GET /external/private/api/conversations/ ​

3.3 GET /external/private/api/conversations/{conversationId}/messages ​

3.4 GET /external/private/api/conversations/{conversationId}/timeline ​

3.5 GET /external/private/api/conversations/{conversationId}/turns ​

3.6 GET /external/private/api/conversations/{conversationId}/turns/ ​

3.7 GET /external/private/api/cases ​

3.8 GET /external/private/api/cases/ ​

3.9 GET /external/private/api/recommended-words ​

3.10 GET /external/private/api/conversations/{conversationId}/agent-draft-suggestion ​

4. 写接口（请求示例 + 响应示例） ​

4.1 POST /external/private/api/conversations —— 创建会话（ConversationCreateRequest） ​

4.2 PATCH /external/private/api/conversations/{conversationId} —— 更新会话（ConversationUpdateRequest） ​

4.3 DELETE /external/private/api/conversations/{conversationId} —— 删除会话 ​

4.4 POST /external/private/api/conversations/{conversationId}/messages —— 发送消息（SSE 流） ​

4.5 POST /external/private/api/conversations/{conversationId}/turns/{turnId}/cancel —— 取消运行 ​

4.6 POST /external/private/api/conversations/{conversationId}/turns/{turnId}/stream —— 重放 Turn 流 ​

4.7 POST /external/private/api/cases —— 保存案例（SaveCaseRequest） ​

4.8 PATCH /external/private/api/cases/{caseId} —— 更新案例（UpdateCaseRequest） ​

4.9 DELETE /external/private/api/cases/{caseId} —— 删除案例 ​

4.10 POST /external/private/api/cases/{caseId}/share —— 分享案例（ShareCaseRequest） ​

4.11 POST /external/private/api/conversations/{conversationId}/save-as-agent —— 会话另存为 Agent（SaveConversationAsAgentRequest） ​

4.12 POST /external/private/api/conversations/{conversationId}/agent-draft-suggestion —— 采纳草稿建议（AgentDraftSuggestionRequest） ​

5. 公网分享接口（无鉴权） ​

5.1 GET /external/public/api/cases/ ​

6. 错误码速查 ​

附录：复现脚本（PowerShell，稳定可靠） ​

对话模块 API 文档（实时抓取版）

0. 快照信息（git 版本号，重要！）

1. 鉴权头（所有接口必带）

2. 接口总览

3. GET 接口（真实返回值）

3.1 GET /external/private/api/conversations

3.2 GET /external/private/api/conversations/

3.3 GET /external/private/api/conversations/{conversationId}/messages

3.4 GET /external/private/api/conversations/{conversationId}/timeline

3.5 GET /external/private/api/conversations/{conversationId}/turns

3.6 GET /external/private/api/conversations/{conversationId}/turns/

3.7 GET /external/private/api/cases

3.8 GET /external/private/api/cases/

3.9 GET /external/private/api/recommended-words

3.10 GET /external/private/api/conversations/{conversationId}/agent-draft-suggestion

4. 写接口（请求示例 + 响应示例）

4.1 POST /external/private/api/conversations —— 创建会话（ConversationCreateRequest）

4.2 PATCH /external/private/api/conversations/{conversationId} —— 更新会话（ConversationUpdateRequest）

4.3 DELETE /external/private/api/conversations/{conversationId} —— 删除会话

4.4 POST /external/private/api/conversations/{conversationId}/messages —— 发送消息（SSE 流）

4.5 POST /external/private/api/conversations/{conversationId}/turns/{turnId}/cancel —— 取消运行

4.6 POST /external/private/api/conversations/{conversationId}/turns/{turnId}/stream —— 重放 Turn 流

4.7 POST /external/private/api/cases —— 保存案例（SaveCaseRequest）

4.8 PATCH /external/private/api/cases/{caseId} —— 更新案例（UpdateCaseRequest）

4.9 DELETE /external/private/api/cases/{caseId} —— 删除案例

4.10 POST /external/private/api/cases/{caseId}/share —— 分享案例（ShareCaseRequest）

4.11 POST /external/private/api/conversations/{conversationId}/save-as-agent —— 会话另存为 Agent（SaveConversationAsAgentRequest）

4.12 POST /external/private/api/conversations/{conversationId}/agent-draft-suggestion —— 采纳草稿建议（AgentDraftSuggestionRequest）

5. 公网分享接口（无鉴权）

5.1 GET /external/public/api/cases/

6. 错误码速查

附录：复现脚本（PowerShell，稳定可靠）