From b8399b59494b269fc0d39a1a2258f11d8980febc Mon Sep 17 00:00:00 2001 From: AskaEth Date: Mon, 5 Oct 2026 19:44:53 +0800 Subject: [PATCH] =?UTF-8?q?docs(02):=20=E5=AE=A2=E6=88=B7=E7=AB=AF?= =?UTF-8?q?=E7=99=BB=E8=AE=B0=E2=80=94=E2=80=94=E5=B7=A5=E5=85=B7=E8=B0=83?= =?UTF-8?q?=E7=94=A8=E8=AE=B0=E5=BD=95=E5=9C=A8=E5=9B=9E=E5=90=88=E7=BB=93?= =?UTF-8?q?=E6=9D=9F=E5=90=8E=E6=B6=88=E5=A4=B1=EF=BC=8C=E6=A0=B9=E5=9B=A0?= =?UTF-8?q?=E6=98=AF=E8=90=BD=E5=BA=93=E6=B6=88=E6=81=AF=E6=B2=A1=E6=9C=89?= =?UTF-8?q?=E5=B7=A5=E5=85=B7=E5=AD=97=E6=AE=B5=EF=BC=88=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E9=9D=A2=E7=BC=BA=E5=A4=B1=EF=BC=89=EF=BC=8C=E5=B9=B6=E7=BB=99?= =?UTF-8?q?=E5=87=BA=E8=A6=81=E8=A1=A5=E7=9A=84=E5=9B=9B=E7=82=B9=E4=B8=8E?= =?UTF-8?q?=E5=BD=B1=E5=93=8D=E9=9D=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 排查证据：助手行落库时客户端会为流式思维链做「打捞 + 滞留」，而工具没有字段可打捞、连同流式路一起被丢弃；后端其实已把工具调用落进 flow_graphs，缺的是取出来给聊天端。 --- devdocs/02-前后端协同事项.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/devdocs/02-前后端协同事项.md b/devdocs/02-前后端协同事项.md index 765fbf6..ffd0796 100644 --- a/devdocs/02-前后端协同事项.md +++ b/devdocs/02-前后端协同事项.md @@ -589,3 +589,24 @@ - **IM 落库补 `turn_id`（`8f6a75b`）**：我们**不改代码**即可在 IM 来源消息上分桶。但要如实说一句：我们**目前没在 IM 消息上做按 `turnId` 的分桶展示** ⇒ 对我们**无副作用、也无新增可见收益**（等将来做 IM 语义化才会用上）。 - **并行提示（`fa850f9` / `ba19740`）**：WS 形状零变化 ⇒ 我方零改动。你们修的「各路互相复述对方那题」正是我们上一批实测时**不敢下结论**的那类串话 —— 这条很有价值。 - 其余（IM 历史转录 / QQ 适配器 logger / 契约 v0.67）对我们的影响面与你们说的一致或为零，已核对。 + +--- + +## 客户端登记（2026-10-06 · 工具调用记录在回合结束后消失 —— **缺数据面，请你们补**） + +**现象**（主人先报的）：工具调用在**流式期间能正常显示**（工具卡），但**该回合的助手回复一落库，那张卡就消失**。 + +**根因（我方只读排查）**：工具卡的数据**只活在流式路的本地状态**里（`StreamingLeg.tools`），而**落库消息的 DTO 里没有任何工具字段**可渲染。 +证据是**同一段代码里的对比**：助手行落库时（`ChatViewModel.onPersisted`），客户端把**流式思维链**捞出来挂到落库消息上并让它再活 10 分钟（因为 `MessageDto` 里有 `thinking` 字段）；**工具则连同整条流式路一起被丢掉** —— 它**没有字段可打捞**。 +⇒ 结论：**这是数据面缺失，不是我方本地状态的 bug**。我方行为与自己的设计文档一致（`devdocs/03:141`「thinking / tool_call：仅 WS 实时有」）。 + +**我们知道的旁证**：你们**已经**把工具调用落了库（存在 `flow_graphs` 里）——缺的只是「取出来给聊天端」这一步。 + +**请你们补的**（形状你们定；我方按「未知值原样显示、不猜文案」的既有纪律解析）： + +1. 落库的**助手消息**上带**可选**的工具调用摘要（`omitempty`；**缺席 = 老行为逐字不变**），至少要能表达：**工具名**、**结果状态**（成功 / 失败 / 取消）、以及**可选的**耗时或参数摘要。 +2. 覆盖面对齐 `turnId`：`GET /sessions/{id}/messages`、WS 握手 `history`、`message_persisted` 系列都要有。 +3. **归属要明确**：工具调用属于**哪条助手消息**（或哪一路 `turnId`）——两路并行时没有这个就无法归属。 +4. 若你们认为**该开独立端点**而不是塞进消息 DTO，也说一声，我方按你们定的来。 + +**影响面（我方）**：目前 `ToolCard` 在「已落库消息」那条渲染路径上**是不可达代码**（已落库消息的渲染器签名里没有 tools 参数）。字段一到，我方接线即可；**不需要你们动客户端**。