From 1d150cce85314d5f47b5784b1b10d07f13bea067 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Tue, 6 Oct 2026 08:24:50 +0800 Subject: [PATCH] =?UTF-8?q?docs(02):=20=E5=AE=A2=E6=88=B7=E7=AB=AF?= =?UTF-8?q?=E7=AD=94=E5=A4=8D=20=E2=80=94=E2=80=94=20=E5=9B=9E=E6=89=A7?= =?UTF-8?q?=E4=BA=8C=E5=8D=81=E5=9B=9B=C2=B7=E8=A1=A5=EF=BC=9A=E2=91=A0?= =?UTF-8?q?=E6=8E=A8=E8=BF=9F=E7=85=A7=E5=8A=9E=E3=80=81=E2=91=A1=E6=9C=AA?= =?UTF-8?q?=E8=AF=BB=E5=8F=A3=E5=BE=84=E7=A1=AE=E8=AE=A4=EF=BC=88=E7=BB=B4?= =?UTF-8?q?=E6=8C=81=20omitempty=EF=BC=89=E3=80=81=E4=B8=A4=E6=9D=A1?= =?UTF-8?q?=E6=BE=84=E6=B8=85=EF=BC=8C=E5=B9=B6=E5=8F=8D=E9=97=AE=20.end?= =?UTF-8?q?=20=E8=83=BD=E5=90=A6=E5=B8=A6=E7=BB=93=E6=9E=9C=E6=91=98?= =?UTF-8?q?=E8=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 改了什么（只加了我们这一节，未碰他们那一节）： - ① 工具回看面推迟：照办。明确写死两条口径——不把「toolCalls[] 缺席」当「这轮没调工具」； 不再按消息字面 join turnId（两者不是同一套标识）。也说明我们**不提前写**那个解析器。 - ② 未读面：回答他们的问题——**维持 omitempty 即可**，因为对我们权威来源是列表面（GET /sessions 恒带 unreadCount），增量键只是省一次重拉的优化；接入口径按他们说的「键在才改、缺席什么都不做」。 同时如实说明本端**还没消费**这个键（今天走的是 W49 的重拉，已实机验收），免得他们误以为已生效。 - 两条澄清：GET /api/v1/messages/{id} 我们从未用过（只有 PATCH/DELETE，SessionsApi.kt:130,137）； tool_execution (a) 维持收到。 - 反问一件与回看面无关的事：能否给 tool_execution.end 加可选 resultSummary（截断、缺席语义）—— 因为 .end 只带 tool/phase/id、update 又没有生产者，实时工具卡的结果区结构性为空；这是投入最小的一条。 明确说「不做也接受，但请明说」，我们要的是确定而不是一定要这个键。 - 告知 W50/W48/W49 已落地并实机验收（不需要他们动作）。 为什么：他们那条回执标红了「别把缺席当没调过」，并直接问我们要不要区分「确实 0 / 不知道」—— 这两个都是会决定他们改不改代码的问题，必须当场答清。 --- devdocs/02-前后端协同事项.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/devdocs/02-前后端协同事项.md b/devdocs/02-前后端协同事项.md index a33bbfe..8fdc10d 100644 --- a/devdocs/02-前后端协同事项.md +++ b/devdocs/02-前后端协同事项.md @@ -720,3 +720,35 @@ - **工具调用记录**：你们说它比未读更重要、理由是「**回看这条回复时能不能看到它当时调了什么**」——**完全同意**，这正是我们的判断。 - **我们那六条依赖逐条「保持现状 + 改前登记」**：**收到，这就是我们要的答复**。其中第 2 条你们补的那句「**先 ack 后生成是契约**」——我们把它当硬约束用。 - **`CyreneRoute` 那条取证约定**：「**不从对端日志反推『没发出去的请求』**」——很高兴你们也采纳；这条我们今天是用三次误判换来的。 + +--- + +## 客户端答复（2026-10-06 早 · 回 `回执二十四·补`：① 推迟 → 照办；② 两个口径确认 + 一个反向问题） + +### 一、① 工具回看面**推迟** ⇒ 收到，**照办**，并且我们不会踩那条坑 + +- **「取不到 ⇒ 字段整体缺席」我们不会当成「这轮没调工具」**——你们标红的正是我们原本担心的那一条（工具卡结果区为空）。**这条已经写进我们的设计口径**，不会做成「静默显示成没调过」。 +- **我们不再按消息字面 join `turnId`**。你们那张对照表（消息行 `turn-<16 位 hex>` = 编排器随机路标识；图行 `-<轮次>` = `trace.FlowGraph.ID`、**进程内递增、重启归零**）我们记下了；「按时间窗硬凑」我们也同意是猜，不做。 +- **形状不变 ⇒ 我们也不提前写那个解析器**：写一个短期内永远拿不到数据的解析器，只会养出一段没人能验的死代码。等你们在图侧补上回合标识、`toolCalls[]` 真落地时我们再实现（**契约先行**那条我们仍然认，是**落地再实现**，不是**现在就写**）。 + +### 二、② 未读面：**维持 `omitempty` 即可，不必改**（这是回答你们的那个问题） + +- **结论：不需要为「区分『确实 0』与『不知道』」改三行。** 理由是对我们而言**权威来源是列表面**——`GET /api/v1/sessions` 的 `unreadCount`（你们说 D4 起恒在），增量键只是**省一次重拉**的优化，不是唯一来源；分不出「确实 0」和「算不出来」不会让我们的角标错。 +- **我们接入口径就按你们说的写**：**键在 ⇒ 用它的值改角标；键缺席 ⇒ 什么都不做**（绝不把缺席当 0 覆盖本端角标）。 +- ⚠️ **如实说明我们现在的状态（免得你们以为它已生效）**：本端**还没消费**这个键——`SessionsViewModel` 今天走的是「**非激活会话落新消息 ⇒ 节流静默重拉一次列表**」（W49，**已实机验收**：抽屉关着时客户端自己在消息到达后 60ms 发出 `GET /api/v1/sessions`）。所以你们这条增量**目前不会改变我们的行为**；等我们接它的时候才可能省掉那次重拉。 + +### 三、两条澄清 ⇒ 收到（其中一条对我们零影响） + +- **`GET /api/v1/messages/{id}` 不存在**：**我们从未用过它**——全仓只有 `PATCH` / `DELETE /api/v1/messages/{id}`（`SessionsApi.kt:130,137`），单条读没有出现在任何设计里。**无需改动。** +- **`tool_execution` 选 (a) 维持、不补 `.update`**：收到，保持。 + +### 四、反过来问你们一件**与回看面无关**的事：`.end` 能不能带一个结果摘要？ + +- **现状（我们的读法）**：`tool_execution.end` 只带 `tool` / `phase` / `id`（`WsEvent.kt:194-203`）；而 `update` 你们说分发器**暂无中途上报源**（我们这边也是按契约完整解码但收不到）。⇒ **实时工具卡的结果区永远是空的**，而这与 ① 的推迟是**两件事**（那件管回看，这件管**正在发生的这一轮**）。 +- **问**：能否给 `tool_execution.end` 加一个**可选**的结果摘要键（例如 `resultSummary`，**截断到几百字符**，取不到就**整键缺席**）？ + 这是**投入最小**的一条（一处字段 + 一处赋值），能让我们在**实时**就画出「这轮调了什么、结果是什么」，**不必等图侧的 `0023` 迁移**。 +- **「不做」我们也接受**——但请**明确说一句**：那样我们就把工具卡**定死**成「只显示工具名与状态、不出现结果区」，不再留空位。我们要的是**确定**，不是一定要这个键。 + +### 五、一条告知（不需要你们动作） + +**W50 已落地并实机验收**：`proactive_message` 现在有消费点——她主动说的话**实时**进主会话、刷新/重开后仍在、按 `id` 不重复；无 `id`（你们落库失败那一档）退化成**本地气泡**、不静默丢。另外 W48/W49 的实机验收也通过了（换账号不串味；非激活会话的未读角标不再等用户开抽屉）。