docs(02): 客户端答复回执二十二·补的四问——主动消息「不会两次」但真缺口是「我们没消费那帧 ⇒ 实时看不到」；tool_execution 选 (a) 并附取舍；纠正「每屏一条 WS」过时前提；推送暂不接并说明「应用内提示」在客户端零实现

devdocs/02-前后端协同事项.md

@@ -663,3 +663,60 @@
 客户端现在有一行**路由日志**：`adb logcat -s CyreneRoute`（仅 debug 构建），一行打出
 `wsDispatched / socket / mirror / wsObject / route / reason / outcome / fromQueue`。
 以后要判断「客户端到底有没有尝试发、走的哪条路」，**直接问我们要那一行**，比从你们的入站日志反推可靠得多 —— 今天我们就因为**从对端日志反推**而误判了三次（对端看不到「没发出去的请求」）。
+
+---
+
+## 客户端答复（2026-10-06 凌晨 · 回 `回执二十二·补` 的四问 + 对 `回执二十三` 的确认）
+
+### 一、P1「主动消息会不会显示两次」⇒ **不会两次，但真实情况是相反的、而且更糟：我们根本没消费那帧**
+
+**逐条事实（都带文件:行号）**：
+
+1. **帧我们解析，但只取了错的 id**：`proactive_message` 有解析（`data/ws/WsEvent.kt:596-610`，`ProactiveData` 在 `:1048-1057`），但它**只解 `messageId`（IM 侧消息 id），没有解 `id`/`createdAt`**；而 `ignoreUnknownKeys = true`（`data/api/ApiClientFactory.kt:46-50`）⇒ **你们新加的 `id` 被静默丢弃**。
+   我们核对过：`messageId` 与落库行 `id` 是**两个不同的 id**（你们 `gateway/proactive.go:31` vs `:36`）⇒ 拿它当去重键**永远对不上历史**。
+2. **更要紧的：整帧被丢弃**。`ChatViewModel.onEvent` 的 `when(event)`（`ui/chat/ChatViewModel.kt:2403-2671`）**没有 `ProactiveMessage` 分支**，落到 `else -> Unit`；另两个下行消费者（`SessionsViewModel:335-344`、`AdminViewModel:231-233`）也不认它。**全仓 `app/src/main` 里 `ProactiveMessage` 零消费点。**
+3. **消息列表本身是按 id upsert 的**（所以「两次」不会发生）：`mergeMessages`（`data/repository/PagedMessages.kt:29-40`）以 `HistoryMessageDto.id` 为键覆盖，五个并入点（首屏 / 静默补拉 / 握手 history / message_persisted / 上拉分页）全走它。
+4. ⇒ **真正的缺口是：你们的 Web 路由只发 `proactive_message`、不补 `message_persisted`**（我们从 `gateway/proactive.go:59-87` 与 `history/store.go:213-215` 的 `AppendFull` 无广播钩子推出来；IM 路由有 `broadcast.go:35-47`，那条我们能实时显示）⇒ **安卓端现在实时看不到她主动说的话**，只能等重连 / 重开 / 切会话拉历史时才出现。
+   ⚠️ 这条是**从你们代码静态推的，我们没起服务实测**，若有误请纠正。
+
+**所以我们把这条 P1 的含义更正为**：不是「去重」，而是「**接上消费**」。修法在我们这侧（位置已定）：
+- `ProactiveData` 补 `id`/`createdAt`，`ProactiveMessage` 同步；
+- `ChatViewModel.onEvent` 加一条分支：**把帧当成「一条已落库的 assistant 行」并入**（构 `HistoryMessageDto(id, role="assistant", …)` 后走与 `onPersisted` 同一条 `mergeMessages` 路），**不新建只活在 UI 的气泡**；
+- ⚠️ **必须自己钉死主会话**：`proactive_message` 帧壳**不带 `sessionId`**（你们 `ws_hub.go:38` 是 `omitempty`，且 `proactive.go:68` 构造时没设 SessionID），而我们的 `isForSession`（`WsEvent.kt:895-898`）会**放行给每一个会话的 VM** ⇒ 不钉主会话就会**在每个次级会话里都冒一条**。**这条形状上的坑值得你们留意：其它客户端大概率也会踩。**
+- `id` 缺席（落库失败）时才退化成「只画一条本地气泡」。
+
+⇒ **我方排期：按 P1 接**（我们自己也想要「刷新后她的话还在」）。
+
+### 二、`tool_execution` 口径 ⇒ **我们选 (a)**（只认 `.start`/`.end`，按 `id` 关联；**你们不必补 `.update`**）
+
+- 核实结果：**三档我们全都解析、全都消费**（`.start` `WsEvent.kt:721-722` → `ChatViewModel.kt:2528`；`.update` `:723-724` → `:2530-2531`；`.end` `:725-726` → `:2533`；关联键是 `id`，`toolExecutionTargetIndex:418-425` + `applyToolExecution:433-453`）。
+- 你们听说的「只映射了 `.update`」是**过时信息**——那次已有回归测试钉住（`app/src/test/.../WsEventToolExecutionTest.kt:115-128`）。
+- **只发 `.start`/`.end` 够用**：工具卡的标题由 `phase` 驱动（`StreamingBlocks.kt:67-77`），`running → done/error` 这条链完整成立。
+- ⚠️ **交换条件是你们要知道的取舍**：**没有 `.update` ⇒ 工具卡的「结果」区是空的**（`ToolCallState.output` **只由 `.update` 的 `delta` 追加**，`ChatViewModel.kt:449`），进度也只是一次跳变。
+  **我们要的不是 `.update`，而是你们已经认领的「持久化 `toolCalls[]` 回看面」**——那才同时解决「回看」与「看到输出」。所以：**(a)**，并且**请求把 `toolCalls[]` 里的输出/摘要一起带上**（形状你们定，我们按「未知值原样显示」解析）。
+
+### 三、我们待办清单的现状（回你们的第 3 问；⚠️ 含一条**过时前提的纠正**）
+
+**先纠正**：你们列举里的「**`ChatScreen` 每屏一条 WS 且旧连接不回收**」——**前半句早已不成立**：W28（`7b97440`）已把它收成**进程级唯一连接**（`AppContainer.kt:229` 的 `by lazy` 唯一实例，`SessionsViewModel` 是唯一的 connect/close 主人）。剩下的是**VM 不回收**（访问过的会话各留一个 VM 在 Activity store 里，仍订阅共享流）。
+
+| 待办 | 现状 | 需要你们配合？ |
+|---|---|---|
+| `unreadCount` 已读游标 | **已接入**（抽屉红点 / 打开即推进 / `session_read` 收敛）。新登记的是「**非激活会话红点不实时增长**」⇒ 你们刚在 `回执二十三` 认了带 `unreadCount` | **要**（已在你们队列） |
+| `interrupt.scope` | **已接入**（设置页三档：追加队列 / 打断 / 并行；并行档忙时上行 `chat.parallel=true`、绝不发 `interrupt`） | 否 |
+| 图片大小策略 | **已接入**（≤64 KiB 内联 `data:`，否则走 `/upload` 换 URL） | 否 |
+| 每屏一条 WS | **已不是问题**（见上，W28 收成唯一连接） | 否 |
+| 工具调用记录 | 你们已认（排在未读面之前） | **要**（已在你们队列） |
+| 主动消息消费（本回执 §一） | **未做，本回执定为 P1，我方接** | 否（除了上面那条「帧壳无 `sessionId`」的形状提醒） |
+
+### 四、移动端系统推送 ⇒ **暂不接**（等主人自建推送）
+
+- 主人已定：**等他自建推送**再谈接入形状。
+- ⚠️ 补一条**你们该知道的事实**：你们建议的「**应用内提示**」（`message_persisted{proactive:true}`）在**我们这边是零实现**——`PersistedData`（`WsEvent.kt:1021-1022`）只读 `message`，那个 `proactive` 判据键被 `ignoreUnknownKeys` 丢掉了；而且客户端**完全没有 Notification 相关代码**。所以那条建议**目前不会产生任何效果**，别把它当成已生效的兜底。
+
+### 五、`回执二十三` 里你们认下的事 ⇒ **收到，逐条确认**
+
+- **未读增量**（`message_persisted.data.unreadCount`，**绝对未读 + 主人单一已读游标 ⇒ 多端共享**）：形状与取舍我们都接受。**其中「多端共享 = Web 读了安卓也清」这条我们明确赞成**（这正是我们要的语义）。
+  你们提到「`GET /sessions` 列表项也带 `unreadCount` ⇒ 可替代我们的客户端自愈」——**同意，且我们更希望如此**（我们那个自愈每次都是一次完整重拉，会话多了会变贵）。
+- **工具调用记录**：你们说它比未读更重要、理由是「**回看这条回复时能不能看到它当时调了什么**」——**完全同意**，这正是我们的判断。
+- **我们那六条依赖逐条「保持现状 + 改前登记」**：**收到，这就是我们要的答复**。其中第 2 条你们补的那句「**先 ack 后生成是契约**」——我们把它当硬约束用。
+- **`CyreneRoute` 那条取证约定**：「**不从对端日志反推『没发出去的请求』**」——很高兴你们也采纳；这条我们今天是用三次误判换来的。