AskaEth/Cyrene-For-Android
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
198 Commits 3 Branches 5 Tags
4f860aa49976181b81df85ed25c5b56b13724940
Commit Graph
100 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
AskaEth 4f860aa499 fix(chat): W48 聊天页 VM key 带上账号指纹，修换环境后仍显示上个环境的会话 
缺陷：换账号或换服务器后，聊天页仍然摆着上一个环境的消息。成因是 ChatScreen 里那个
ChatViewModel 的 owner 是 Activity 级的 ViewModelStore，而登出只是把 ChatHomeScreen
移出组合、并不清理那个 store（ChatViewModel.onCleared 是空的，全仓也没有 ViewModelStore.clear()）。
key 里只有 sessionId 时，换环境再进来 viewModel() 会把上一个环境那个还活着的实例原样取回来，
它继续收着那个环境的帧，屏幕上就是别的服务器的消息。主会话的 id 恒为 web，两次登录必然撞上
同一个 key，所以这不是理论风险。

为什么 VM key 要带账号指纹：指纹回答的是「这份本地状态属于哪个环境」。把它抽成纯函数
accountFingerprint(baseUrl, username)，与 SessionPreferences 判断快照作废、
SessionsViewModel 落盘快照用的是同一份口径（SessionsViewModel 原本就地拼的那串改成调用
同一个函数，免得两套判据分叉——分叉的那一侧就是漏出去的那一侧）。同一个环境里切会话，
key 未变，各会话的状态照旧各留一份（这正是「切回来状态还在」依赖的）；环境一变（换了服务器
或换了账号），key 就变，取到的一定是新实例。

会话内搜索那个小 VM 是同一类残留：它持有的命中就是消息正文，换环境后在主会话上重开搜索，
面板里就是别的服务器的消息。它的 key 同样带上指纹。

为什么本轮不回收旧 VM：要真正回收掉上一个环境那个实例，得自定义 ViewModelStoreOwner 或直接
清 store，而「切回来状态还在」这条体验正绑在 store 不清这件事上，属于要主人拍板的设计取舍。
本轮只保证换环境后取到的是新 VM，回收这件事不动。

顺带的零成本纠错（只改注释的成因描述，行为一字未动）：ChatHomeScreen / ChatScreen /
ChatViewModel 里几处「onSessionGone 一被调用，那个会话的 VM 连同它的状态立刻被销毁」是错的——
变的是 key，被销毁的只是承载横幅的那段组合；VM 实例仍在 Activity 级的 store 里活着并继续收帧。
「横幅必须挂在上一层」那条结论本身是对的，原样保留；改的只是它前面的理由。
同时把 devtools 里那个窄代理的路径写对（此前注释指向一个并不存在的路径）。

开发工具挪出会被 clean 扫掉的位置：app/build/e2e-shots/ws_block_proxy.py 躺在 gitignored 的
app/build/ 里，一次 gradlew clean 就没了。挪进 devtools/ws-block-proxy/（与 fake-backend
同级同风格）并配 README，写清用途、用法（python ws_block_proxy.py 18098 10942，配
adb reverse tcp:10942 tcp:18098）与它最有价值的判据：调试时 Web 前端直连后端、不经过
adb reverse，所以代理日志里的每一行都只可能来自 App。脚本行为未改，也没有硬编码任何凭据。

新增单测 ChatViewModelKeyTest 钉住拼法：同账号同地址 => 同 key；换地址 / 换账号 / 换会话
=> 不同 key；username 缺失时退化成 baseUrl 一段，换地址仍然分得开。

验证：gradlew.bat assembleDebug 与 gradlew.bat testDebugUnitTest，
BUILD SUCCESSFUL；单测 1164 条，failures 0、errors 0、skipped 0。
 2026-10-05 22:25:57 +08:00
AskaEth df8df67742 docs(05): 锚点补记二十二——③ 结案：阶梯机制正常（两次有效观测 route=Rest 且落库），W45 那轮异常未复现也因当时无 CyreneRoute 日志而无法定论；并写死一套可靠的设备驱动协议（确认前台→确认文字落点→从 dump 取发送键坐标） 2026-10-05 22:12:16 +08:00
AskaEth f2075c1f49 docs(05): 锚点补记二十一——移除键补验有效（附我复用旧坐标点空的教训与布局回流说明）；③ 的第一次尝试没跑成（CyreneRoute 为空、代理无 POST、库无该条 ⇒ 发送没触发），并写明下一轮必须三步确认的做法 2026-10-05 22:10:00 +08:00
AskaEth df20a21fb5 docs(05): 锚点补记二十——W42 图片多选设备验收通过（多选器是真多选、计数「添加（2 项）」正确、输入栏出现两枚带移除键的缩略图），并登记移除键位置这处观感待主人定 + 两个未验的邻近格 2026-10-05 22:05:21 +08:00
AskaEth 669d05b781 docs(05): 锚点补记十九——子会话流程变成清单（S1~S9，每条带文件:行号与归类），先纠正我自己两条错前提，附 12 步设备验收骨架、优先级建议与 ws_block_proxy.py 不在 git 里的提醒 2026-10-05 22:01:20 +08:00
AskaEth ff699f5079 docs(05): 锚点补记十八——W47 静默按事故复位（清零点收进一个纯判据、事故=队列空到空），含为什么不选「只在成功时清零」与三条验收体验 2026-10-05 20:25:58 +08:00
AskaEth 3a07e94180 merge: W47 —— 队列静默改为按事故复位（队列排空即清零），不再只在补发成功时清零 2026-10-05 20:25:23 +08:00
AskaEth ce50bd2c24 feat(chat): 静默告知改为按事故复位，队列排空即清零 
W43 的静默规则只在「补发真的成功一次」时把 queuedResendFailures 清零。若一段坏网络的
队列以回滚或被收编收场（一次都没成功发出去），这一格就永远挂着 ⇒ 之后连接恢复、再断
一次、用户又发消息时，那句解释再也说不出口。那不是减少噪音，是把解释永久关掉（主人
2026-10-06 裁决：哪个体验好用哪个）。

改成按事故复位：一个「事故」= 队列从空到非空、再回到空，结束就复位，不管它是怎么结束
的——发出去了、回滚了（内容退回输入栏）、还是被收编了（气泡换成权威消息）。清零点因此
有两个：补发成功一次（原样保留），以及队列排空（既有钩子 forgetQueuedNoticeIfDrained，
回滚那条路也走这里，它是队列清空的唯一两个入口之一）。

这样不会在长期断网时刷屏：阈值仍是 3；「一批从空到非空只说一次」仍由 queuedNoticeTold
管着；纯网络故障下消息会堆积在队列里 ⇒ 队列不清空 ⇒ 不算新事故、计数不复位 ⇒ 不会每条
消息都弹一次横幅。而事故一旦结束，下一次断线又能重新解释。

判据提为纯函数 queuedResendFailuresAfterDelivery（VM 与测试共用，跟
queuedSendNoticeAllowed 同一个写法），单测钉住：队列排空即复位（哪怕这一批一条都没成功
发出去）、队列还有货则计数保留、补发成功照旧清零、一个事故里失败 0/1/2 次仍允许告知而
到阈值静默、下一个事故重新告知。静默不动队列：那条既有用例（判定那一刻队列仍在、下一步
仍是发这条）一字未改。

只动告知判据与它的记账。队列与出队逻辑、sendRouteFor / 三档路由 / W38 分享落地 / W45
直接试 REST / W46 的 CyreneRoute 日志全部未碰。

验证：gradlew.bat clean assembleDebug 与 gradlew.bat testDebugUnitTest，
failure / error 均为 0。
 2026-10-05 20:25:00 +08:00
AskaEth 798c6ee907 docs(05): 锚点补记十七——W45 阶梯设备验证通过（route=Rest、代理见 200、落库 1 条），附我连续三次误判的共同点与三条设备验证纪律，以及工具卡缺口的根因与登记位置 2026-10-05 19:53:16 +08:00
AskaEth 16699c4958 merge: W46 —— 发送路由判据带上原因，并加一行 CyreneRoute 诊断日志（DEBUG） 2026-10-05 19:50:59 +08:00
AskaEth d546f31755 feat(W46): 发送路由带上原因，并加一行 CyreneRoute 诊断日志 
为什么要把「原因」也带出来
- 结果只有 Ws / Rest / Queue 三档，而「为什么是这一档」在设备上完全看不见。W45 那轮真机回归
  就卡在这里：那条消息进了补发队列、网络侧一条请求都没有，而「零请求 + 进队列」在判据里只可能
  来自 Queue 那一档；可顶栏同时显示「重连中…」。两者都只是结论，事后无法分辨「判据读到
  Offline」与「判据读了别的值」。
- 于是把判据抽成 sendRouteDecisionFor(wsDispatched, connection) -> (route, reason)：reason 就是
  原来那三条规则各自的分支标识（FrameDispatched / ConnectionOffline / ConnectionNotReady）。
  sendRouteFor 现在读它的 route，所以两处不可能分叉。判据、优先级、行为逐字未改。

那一行日志（tag = CyreneRoute，Log.d，只在 DEBUG 构建打）
- 打点：ChatViewModel.sendThroughLadder 一进入就一笔，覆盖阶梯的三个分支（帧交出去 / 试 REST /
  直接进队列），一行 key=value、空格分隔：
  wsDispatched=... socket=<ChatSocket.state.value，权威值> mirror=<顶栏读的那个镜像>
  wsObject=<present|absent> route=... reason=... outcome=... fromQueue=...
- socket 与 mirror 必须同时打出来：mirror 是 collect 过来的一格，只会滞后、不会超前，两者不一致
  就说明顶栏那一刻显示的是上一格 —— 这正是「顶栏重连中…」与「这条进了队列」能同时出现的形态。
- 这是开发期诊断仪，不是产品行为：字段增删不构成兼容问题、不为它写测试（要钉的是纯函数那张全表）。
  不打 token / 请求体 / 正文 / localId。

顺带（同一轮的可观测性）
- ChatSocket 新增只读属性 hasLiveSocket（webSocket != null），只喂日志，不是产品逻辑的输入。
- 复核 WsState.Offline 的写点：ChatSocket 里只有两处（runConnectionLoop 的 ConfigMissing，以及
  endWithAuthFailure），close() 写的是 Idle；非 401 的握手失败（代理回 503）走 Closed ->
  Reconnecting，进不了这一档。

测试
- SendFallbackTest 新增两例：五档连接状态 × wsDispatched 真假的全表逐个钉住结果 + 原因，并钉住
  sendRouteFor 与判定同值；另一个钉住三个 reason 都可达、没有第四种组合。全量 1155 例，
  0 失败 0 错误。
 2026-10-05 19:50:28 +08:00
AskaEth b8399b5949 docs(02): 客户端登记——工具调用记录在回合结束后消失，根因是落库消息没有工具字段（数据面缺失），并给出要补的四点与影响面 
排查证据：助手行落库时客户端会为流式思维链做「打捞 + 滞留」，而工具没有字段可打捞、连同流式路一起被丢弃；后端其实已把工具调用落进 flow_graphs，缺的是取出来给聊天端。
 2026-10-05 19:44:53 +08:00
AskaEth b18d864145 docs(05): 锚点补记十六——W45 把探测换成直接试 REST（判据/两个超时/被证伪的那条担心/删除与测试承接），并把本文件里所有关于探测的描述显式标为作废 2026-10-05 18:34:56 +08:00
AskaEth 1d548ddcda merge: W45 —— 发送阶梯改成直接试 REST，删掉 W41 的连通性探测（少一个端点、一套超时预算与一个失败面） 2026-10-05 18:34:15 +08:00
AskaEth ec8d54f3a5 feat(W45): 发送阶梯改成直接试 REST，删掉 W41 的连通性探测 
为什么换成直接尝试
- W41 的阶梯是「WS 未就绪 ⇒ 先探 GET /api/v1/health ⇒ 通才走 REST」。
- 真机回归（devtools/ws_block_proxy.py 只掐 /ws/chat，HTTP 全放行）发现消息进了队列而不是回落
  REST；而 ProbeClientTest 证明那条链在 JVM 上是通的，Unreachable 生在连接之前，三种成因
  （建 client 抛 / 连上但一个字没写 / ConnectException）在外同形，那一轮无法定论。
- 结论：不该有探测。探测只是「能不能连上」的替身，而真正的 REST 请求本身就是最直接的检验
  ——试成了消息还顺手发出去了；试败了进队列（内容一个字节不丢，重发仍是同一个 clientMsgId）。
  探测唯一省下的是「完全无网时少发一个注定失败的请求」，代价却是一个独立 client、一套独立超时
  预算和一整套新的失败面。那个探针 client 还不复用连接池，每次都要现做一次冷握手，预算比主链路
  紧 4 倍（2.5 秒整通 vs 10 秒连接）——今天这个 bug 的形态就长在这上面。

改了什么
- 路由：wsDispatched ⇒ Ws（成功路径逐字不变）；Offline ⇒ Queue；其余三档未就绪 ⇒ 直接试 REST。
- 直接试 REST 走既有的 REST 发送路径与请求体（同一份 chatRequest / 同一个 clientMsgId）：服务端
  收下（200 stream:true / 202 queued / 200 duplicate）⇒ 完成、不进队列；网络类失败与没等到裁决
  ⇒ 进队列；服务端给过裁决（409 / 500 / 503 / 400 与 401）⇒ 回滚 + 既有文案，口径不变。
- 判据纯函数化：sendRouteFor 去掉探测入参；新增 restAttemptLanding（Result<ChatAck>? ⇒ 四档落点）；
  ChatAck.isAccepted 从 ChatViewModel 的私有方法搬到判据文件。
- 删掉探测那一套：ConnectivityRepository / HealthApi / HealthDto / ApiClientFactory.createProbe /
  PROBE_TIMEOUT_MILLIS / Reachability / reachabilityOf / ChatViewModel.probeReachability /
  AppContainer 的接线（删前逐个确认过没有别的调用方）。
- 超时：一个 client、两个超时。client 上的连接超时 10 秒改成 2.5 秒；回落那一次投递的整通上限仍然
  是 10 秒（REST_FALLBACK_TIMEOUT_MILLIS 一个数都没动）。
- 测试：SendFallbackTest 按新事实重写；ProbeClientTest 删掉，其中仍然成立的事实搬到新的
  RestAttemptClientTest（真 OkHttp + 真 Retrofit + JDK HttpServer）。

为什么是这两个超时值
- 连接超时 2.5 秒：正常网络下一次 TCP 握手是毫秒到几十毫秒量级，2.5 秒是「人开始觉得卡」之前的
  量级，也与 W41 那 2.5 秒的探针预算对齐 ⇒ 换成直接试 REST 之后「无网时用户最多等多久」没有变长
  （完全无网时 ≤ ~2.5 秒进队列）。绝不许回到 10 秒：那会让每一条离线消息的用户都白等十倍的时间。
- 整通上限 10 秒：它管的是另一档——「连上了但一直不回话」（半死的代理、接住连接却不回应的
  服务端），到点也按网络类失败进队列。它同时是用户干等时间的上界，不许拉长。
- 整通上限放在调用点而不是 client 的 callTimeout：这个 client 是共用的，长文本 / 内联图片那两条
  本来就该走 REST 的路用的是同一个，client 级 callTimeout 会把它们一并框住，等于给一条本轮不打算
  碰的路引入新失败面。

为什么 Offline 仍然不试（保留 W41 的决定）
- 该档的语义是「握手 401 且续期也失败」（终态、不自动重连），会话已知是死的：试 REST 只会拿到
  401 并落到「回滚 + 一句误导人的鉴权错误」，把「已排队不会丢」换成更差的结果。W41 的理由
  （不鉴权的健康端点必然回 200 ⇒ 假通）随探测一起消失了，但结论换到直接试这边一字不用改。

验证
- gradlew.bat assembleDebug：BUILD SUCCESSFUL
- gradlew.bat testDebugUnitTest：1153 个用例，failures=0，errors=0
  （SendFallbackTest 14 例、RestAttemptClientTest 6 例全绿）

未做
- 没有 push。devdocs/05 的 W41 / W44 段落仍写着探测（那份由主会话维护，本轮只在回复里点出过时
  的句子，没有改它）。
 2026-10-05 18:33:32 +08:00
AskaEth 2bee0b52b0 merge: W44 —— 判定 W41 缺口：A（503 判成 Offline）已否；B 只到形态，那个 Unreachable 生在连接之前，需一次设备取证（含 ProbeClientTest 与 createProbe 的 DEBUG 日志） 2026-10-05 15:50:19 +08:00
AskaEth 06028cc352 test(probe)+docs: W44 判定 W41 缺口——A（把 503 判成 Offline）已否；B 只到形态（那个 Unreachable 生在连接之前，三种成因在外面同形，需一次设备取证） 
判定 A：否。ChatSocket.isAuthFailure 只认 HTTP 401（ChatSocket.kt:320-323），非 101 的握手响应
（代理回 503）走 SessionEnd.Closed ⇒ Reconnecting 退避重连（ChatSocket.kt:301-304 / 230-235）；
而顶栏「重连中…」正是 Reconnecting 的文案（ChatScreen.kt:918，Offline 那档是「离线」）。
⇒ 那一刻 socket 真值就是 Reconnecting，sendRouteFor 在这一档会看探测结论，镜像也没滞后。

判定 B：形态成立，但「这条链根本发不出请求」不成立。
- 调用点是无条件求值的实参（ChatViewModel.kt:1614）⇒ Queued 这一档必然调用探测，
  连 Offline 那档也会（sendRouteFor 只是把结论丢掉，与本轮前的 KDoc 说法相反，已改）。
- 新增 ProbeClientTest（6 例，真 OkHttp + 真 Retrofit + JDK HttpServer）：这条链能在真 socket 上
  留下 GET /api/v1/health、不带 Authorization、200 ⇒ Reachable、503 ⇒ Unreachable、
  2xx 但回执解析不出来 ⇒ Unreachable、黑洞服务端在 2.5 秒整通上限处失败
  ⇒「探测压根发不出去」不是代码事实。
- 真机代理日志里一条 health 都没有 ⇒ 那个 Unreachable 生在连接之前。三种成因在外面完全同形：
  (甲) 建 client 就抛（baseUrl 空/非法，Retrofit.baseUrl 直接抛）；
  (乙) 连上了但一个字都没写（callTimeout 是整通上限含连接，而探测不复用连接池 ⇒ 每次冷握手，
       预算只有 2.5 秒，比共用客户端的 10 秒连接预算紧 4 倍）；
  (丙) 请求出去了、回执非 2xx（只有这一档在对端留痕）。
  ⇒「代理日志没有 health 那一行」推不出「App 没探过」；(甲)(乙) 都不留痕。

本轮改动（除一处 DEBUG 日志外全是文档与测试，无行为变化）：
- 新增 app/src/test/kotlin/top/yeij/cyrene/data/api/ProbeClientTest.kt（6 例）。
- ApiClientFactory.createProbe：DEBUG 下挂 BASIC 日志（与通用 create 同一约定）。这是本轮要的
  诊断仪——--> 打在连接之前，让「到底有没有探」与「死在连接还是死在回执」当场可分；探测不带令牌、
  没有请求体，日志不涉凭据。
- KDoc 修正「连探测都不做」这处失真（SendFallback 的 sendRouteFor、ChatViewModel 的调用点与
  probeReachability），把「三种成因 + logcat 判据」写进 ConnectivityRepository 类注释，
  并给 WsState.Offline 补上「非 401 的握手失败不属于这一档」。
- sendRouteFor 的 fail-closed、探测的 2.5 秒上限、三档路由一个字都没改；下一步要设备取证，
  步骤写在 devdocs/05 的 W44 一节。

验证：assembleDebug 成功；testDebugUnitTest 1156 例 / 0 失败 / 0 错误（新增 6 例全绿）。
 2026-10-05 15:49:48 +08:00
AskaEth 866a3c37cd docs(05): 补记十五·补——W41 回归重跑成功并找到一个真缺口：WS 断/HTTP 通时消息进了队列而不是回落 REST，且探测请求根本没发出（含 dump 决定性判据与下一步该查的位置） 2026-10-05 15:29:54 +08:00
AskaEth 4460ca9277 docs(05): 锚点补记十五——W43（中性文案逐字 + 重试静默的阈值/记账/清零口径与一处待过目边界）、主人四条裁决的落点、以及一次没跑成的 W41 回归（如实记为未验证，附可复用的 WS 拦截代理与教训） 2026-10-05 15:23:04 +08:00
AskaEth 3c1d3fd44c merge: W43 —— 超限告知改入口中性措辞，补发反复失败就静默（静默不等于丢弃） 2026-10-05 15:22:34 +08:00
AskaEth 5556573986 feat(chat): W43 超限告知改入口中性措辞，补发反复失败就静默 
① 超限告知（ShareRules.truncatedImagesNotice）改成**入口中性**措辞
原句以「分享的图片」开头，那是一句只对其中一条路成立的限定：W42 起这个函数同时被图片入口
用着（图片按钮已改多选），而图片入口里根本没有「分享」这件事。所以句子不再指认动作的来处，
只说两条路都成立的三件事：**有上限（4 张）、超出的没发、发出去的是前 N 张**。新句逐字：
「一次最多 4 张，超出的没发，只发送前 N 张」，N 就是真发出去的张数。
刻意不写「失败」「错误」：被上限截掉不是一次错误，是上限本身，那族措辞会让用户以为丢了东西。
两条路仍然共用同一句（只有一个出处），没有为此分裂成两份文案。

② 补发「多次重试失败就静默」（主人 2026-10-06 定案）
W40/W41 之后未连接时普通发送会进补发队列并给一句柔和告知，连接恢复后自动补发；主人新加的
规矩是**不要一直刷屏**：同一条（或同一批）反复重试都失败时，停止再弹告知，静静地等。
- 判据抽成纯函数 queuedSendNoticeAllowed(toldThisRound, failedResends)：**静默闸优先**，其次是
  既有的「一轮从空到空只说一次」（W40 那条一字未改）。它只回答该不该说，从不碰队列。
- 阈值 QUEUED_RESEND_SILENCE_THRESHOLD = 3。理由：不许取 1~2（那等于根本没告知）；第 1 次失败
  就是「刚进队列」那一刻，必须说；第 2、3 次仍允许开口（连接抖动后还是没连上，用户需要重新
  知道）；第 3 次仍未成功说明已在反复失败里，再说只是把同一件事刷第二遍，从此停下。
- 记账口径：本会话的一个**补发批次**（= 队列从空到非空的那一段），与告知本身的记账同口径，
  不新造第二个概念；按单条记账会漏掉「每条只失败一两次、整批却一直没发出去」这种要静默的情形。
  落在 ChatViewModel 的实例字段上：VM 是按会话建的，所以天然按会话，也不引入全局单例——别的
  会话的反复失败不该把本会话的告知掐掉。
- 计什么：只计「补发没能上路、内容仍留在队列里」那种失败（它是唯一会反复发生的一种）；已被
  服务端裁决 / 已回滚的那两类是一次性了结（内容退回输入栏并给了明确原因），不计数。
- 清零时机：**补发真的成功一次**就归零（WS 帧交出去、或回落 REST 被服务端收下）⇒「静默之后
  连接恢复并补发成功」之后，下一次离线**又能重新告知**，不会永久闭嘴。
- 静默不等于丢弃：这一个数只影响说不说，队列内容与补发的下一步一个字节都没动，连接一好照旧
  按序补发（W38/W40/W41 那条硬要求照旧成立）；气泡上「排队中 · 还没连上」的小标也一直挂着。

既有的两句队列告知（排队中那一句 / 离线那一句）一字未改。

测试：ShareNoticeTest 与 ImageSendPlanTest 的超限断言改成新事实（不删断言）；新增
QueuedSendSilenceTest 钉住那条规则的四个边（第一次失败告知、阈值前仍告知、阈值后静默、成功后
清零）以及「阈值不许取 1~2」「静默不动队列」两条性质。
assembleDebug 成功；testDebugUnitTest 1150 测试 / 0 失败 / 0 错误（基线 1143，本批新增 7）。
 2026-10-05 15:21:24 +08:00
AskaEth f3ee2e0d7b docs(05): 锚点补记十四——W42 图片入口改多选（N 张按既有切分落成 N 条消息、切分抽成唯一纯函数由输入栏与分享共用），并登记两处待主人过目（N>=2 时偏好只套第一条、超限文案带「分享的」字样） 2026-10-05 14:42:20 +08:00
AskaEth 4355ebddea merge: W42 —— 图片入口改多选，N 张图按既有切分落成 N 条消息 2026-10-05 14:41:46 +08:00
AskaEth 5a9f52a069 feat(chat): 图片入口改多选，N 张图按既有切分落成 N 条消息 
主人 2026-10-05 定案「那肯定要多选」：图片按钮从 PickVisualMedia（单选、回一个 Uri）换成
PickMultipleVisualMedia（系统 Photo Picker 的多选形态，仍然零权限，不退回落 SAF / 存储权限）。
文件按钮那条 OpenMultipleDocuments 一个字没动。

为什么复用分享路径那一段（不另起一套发送逻辑）：
分享落地（ChatViewModel.sendShared）早就把「一条消息只能带一张图 ⇒ N 张图 = N 条消息」做完了，
那段切分本来内联在它自己的 forEach 里，不是可复用的纯函数。这次把判据抽成纯函数 imageSendPlan
（ui/chat/ImageSendPlan.kt，跟 SharePayload.kt 与 SendQueue.kt 一样的写法，可单测），投递抽成
emitPlannedMessages（私有），输入栏那条路与分享落地那条路共用同一段：两处各写一份循环，迟早会在
「哪条带正文 / 哪条带附件 / 哪条清草稿 / 超过上限怎么办」上分叉。每张图各自的解码 / 缩放 / 重编码
与「内联还是上传」的取舍仍旧逐张走既有实现（deliver 与 deliverImage），一行没改。

为什么 N 张 = N 条（而不是一条带多张）：
契约里 chat.image 是单图字段，一次上行只能带一张，所以多选进来的 N 张只能落成 N 条消息：
第一条带正文 + 第一张图 + 全部附件，其余每条一张图，顺序 = 用户在多选器里选的顺序。契约与服务端
一个字没动。

上限与告知沿用分享路径的口径：
上限仍是 ShareRules.MAX_IMAGES（4）。超限那几张不静默丢，如实告知；那句文案抽成
ShareRules.truncatedImagesNotice，分享入口与选图入口共用同一句（逐字未改，ShareNoticeTest 钉住）。
系统选择器自己会把可选张数卡在 4 上，只有回落成 ACTION_OPEN_DOCUMENT 的设备（它表达不了最多几张）
以及「草稿里已有几张、再选几张」这两种情形会真超，那时由入口与投递两处说出同一句。

其余口径与今天一致：
输入栏最多攒 4 张（到顶后不再显示图片入口），每张各自可移除；取消选择什么都不做；
发送时第一条带正文并清草稿（N 条是一次发送，草稿只清一次），失败的那一条只把自己那一张还给输入栏。
一次发送切出的多条里只有第一条套用「她忙时发消息」偏好——第 2 条起声明打断就是打断自己刚起的
上一轮（与分享路径不声明同一条理由），N = 1 时与今天逐字节相同。

顺带：
- ChatUiState.draftImage（String?）改为 draftImages（List<String>），rollbackPending 把失败那张补回
  待发列表（不再覆盖），输入栏渲染成每张各自带移除键的一排预览；
- QueueFullOutcomeTest 里断言单图的四处改成新事实（断言一条没删）；
- 新增 ImageSendPlanTest，覆盖 N = 0 / 1 / 2 / 4 / 5（超限），并钉住附件只跟第一条、顺序不重排、
  超限那句与分享路径同一句。
 2026-10-05 14:41:21 +08:00
AskaEth 97992bdb6b docs(05): 锚点补记十三——W41 三级阶梯（未连接先探 health，通就回落 REST 发出去、不通才进队列），含 Offline 为何不探测、gapCursor 那个被补掉的洞、以及图/附件走不到这条路的边界 2026-10-05 14:35:14 +08:00
AskaEth eb22521269 merge: W41 —— 未连接时先探 health，通就回落 REST 发出去，不通才进队列（三级阶梯） 2026-10-05 14:34:12 +08:00
AskaEth 9f77fb469c feat(chat): W41 未连接时先探一次健康端点，通就回落 REST 发出去，不通才进队列 
主人第二次定案：「未连接状态你就不能拿 httpAPI 尝试吗？」→ 明确为「可以走 health 端点
验证连通性」。W40 的「未连接就进队列」保留为最后一级，队列、气泡小标与那套柔和告知原样复用。

## 为什么先探测再决定，而不是直接排队
网关只有一条：POST /api/v1/chat 与 /ws 是同一个端口上的两条车道。握手被挡（代理不转发
Upgrade、中间设备掐长连接）时 REST 往往是通的，直接排队等于把「WS 这条车道暂时不通」当成
「后端不可用」，让用户白等一次重连——而那一刻这条消息本来就能发出去。

## 三级阶梯（判据是纯函数 sendRouteFor，见 ui/chat/SendFallback.kt）
1. WS 就绪 → 照旧走 WS。成功路径的字节与状态机一个字没变：sendThroughLadder 的第一件事
   仍然是 sendChat，前面不加任何判断、不挂任何起点。
2. 未就绪 → 探一次 GET /api/v1/health（2.5 秒整通上限，只看 2xx；失败 / 超时 / 抛异常一律
   按不通处理，fail-closed）。通 → 用既有的 POST /api/v1/chat 把这条发出去（短文本也走
   REST）；不通 → 进队列。
3. 回落 REST 失败：网络类与超时 → 进队列；服务端给过裁决的（明确拒绝、401）与配置类错误
   （证书 / 明文被禁 / 地址格式 / 解析不出来）仍旧回滚加文案，不装成「还没连上」。
4. 补发走同一个函数（fromQueue=true）：阶梯只有一份实现，两条路不会分叉成两种行为。

Offline 那一档直接进队列、连探测都不做：它的语义是握手 401 且续期也失败（会话已知是死的），
而健康端点不鉴权（Cyrene_v2/internal/services/gateway/routes.go:51）必然回 200 —— 探了只会
发出一次注定 401 的 REST，把 W40 那句「已排队不会丢」换成一次回滚加一句误导人的鉴权错误。

## 为什么重发是安全的
回落与补发用的都是那条乐观气泡的 localId，也就是上行幂等键 clientMsgId，一个字节都不新铸。
服务端按 (session_id, client_msg_id) 唯一索引仲裁：重复到达只回 chat_duplicate /
duplicate:true，不再落库、不再起回合（契约 v0.56 §3.13）。于是「超时了但服务端其实已经
收下」这种最难判的情况不需要本端猜。

## 回复怎么回来
那一刻没有 WS 连接，内容帧没人收，靠重连时的正向增量补回来（gapCursor → catchUp →
loadAfter → absorb）。本 VM 从没连上过时 gapCursor 是 null、重连那一步什么都不会拉，所以
回落发出去且服务端已受理之后补记一次游标（armGapCursorForFallback，只在它还是 null 时补）。

## 其他
- 探测结果不缓存，每条消息最多探一次（只有 WS 没把帧交出去才问）；WS 就绪那条路上一次探测
  都不发。
- 补发从同步循环改成单飞协程：阶梯里要探测、要发 REST，会挂起，「两个触发点都在主线程上
  所以不可能交错」这条旧论证不成立 ⇒ 改用 drainingQueue 单飞闸加串行出队，出队仍在有结论
  之后。
- 离线时的上界：探测不通就直接进队列、一次 REST 都不会发，用户最多等探测那一段（约 2.5 秒）；
  回落那一次 REST 另有 10 秒上限（stream:true 的回执本该毫秒级回来）。
- 新增测试 SendFallbackTest（17 例）：优先级、fail-closed、Offline 不探测、回落失败分档、
  探测超时落在 2 到 3 秒、有图或有附件的消息压根不进这层阶梯。
- devtools/fake-backend 补上 GET /api/v1/health，否则本机跑假后端时这条阶梯会退化成直接排队。
 2026-10-05 14:33:34 +08:00
AskaEth 7b981dd88a docs(05): 补记十二补齐——W40「未连接进队列」的真机回归结果（断线时不退回不报错、恢复后只补发一条），并记下新 AVD 的实测点击坐标 2026-10-05 14:08:28 +08:00
AskaEth 3611455357 docs(05): 锚点补记十二——AVD 调参第二轮（缩小到 1080x2340、vCPU 降到 5、删 skin 才让 hw.lcd 生效），并记下「无窗口会降级成软件 GL，反而更慢」这条与直觉相反的实测 2026-10-05 14:00:56 +08:00
AskaEth 31e8e31679 merge: W40 —— 普通发送未连接时进队列（不再回滚），连接恢复后按发送顺序自动补发 2026-10-05 14:00:10 +08:00
AskaEth 67b2e58fdf docs(05): 锚点补记十一——W40 普通发送未连接时进队列（主人定案落地），并登记 REST 未覆盖与三条待办 
记下这一批的口径与证据，供下一个会话接续：

- 分支 feat/W40-send-queue-offline（基线 e60ae7a），代码与测试提交 df9fc85；未合并、未推送。
- 证据：assembleDebug 成功；testDebugUnitTest 1118 / 0 失败 / 0 错误 / 0 跳过（83 套件）。
  本批没有真机回归。
- 判据：wsSendOutcome 三档（Dispatched / Queued / Failed）；补发触发点是连接状态流变成
  Connected 那一刻，无轮询；顺序 = 用户发送先后顺序；只发一次的保证点是队头加出队恰好一次，
  第二道是复用同一个 clientMsgId。
- 状态表达：不新增第七态（等连接仍是 ③ 排队中），气泡小标加成「排队中 · 还没连上」，
  另有一条柔和的 sendQueueNotice 告知（一轮队列只说一次，Offline 那一档说的是
  重新登录 / 检查服务器地址）。
- REST 通道（长文 / 图片 / 附件）本批未覆盖，仍走回滚加既有网络错误文案，理由与影响面写在
  补记里。
- 待办里更新了四条：真机回归、REST 要不要也排队（需主人定案）、Offline 立刻告知、
  以及那一处刻意未动的失败文案字面量。
 2026-10-05 13:58:20 +08:00
AskaEth df9fc85f76 feat(chat): 普通发送未连接时进队列（不再回滚），连接恢复后按发送顺序自动补发 
主人 2026-10-05 裁决：普通发送在「未连接」时进队列。

此前 deliver 拿到 sent=false 就 rollback：气泡摘掉、正文退回输入栏，外加一句「还没连上，
这条没发出去，请稍后手动重试」。内容是没丢，但把「网络还没好」说成了一次要用户自己负责的
失败，而且他还得对着输入栏再发一遍。这一批按 W38「分享落地等连接」那套语义重做普通发送：
不报错、内容不丢、连接恢复后自动补发。W38 的落地时机、PendingShareHolder.take() 的原子语义、
ChatSocket 的连接状态机一个字都没动。

① 三档处置：未就绪就排队（新纯函数 wsSendOutcome，ui/chat/SendQueue.kt）
判据的输入只有两个：sendChat 的回值，以及这一刻 socket 自己的连接状态。sent=true ⇒ Dispatched
（帧已经交给 socket，成功路径一个字没动：不打标记、不说告知、不写任何状态）；sent=false 且
连接就绪 ⇒ Failed（连接是好的，那 false 只可能来自 socket 对象已空 / 已被 cancel / 序列化抛
异常，「发送失败」在这一刻是事实 ⇒ 走今天那条 rollback + SEND_FAILED_MESSAGE）；sent=false 且
未就绪 ⇒ Queued（ChatSocket.send 第一行就按状态挡掉，帧连序列化都没做、服务端一个字节都收不到，
所以既不回滚也不进 error 横幅）。未就绪四档（Idle / Connecting / Reconnecting / Offline）
一视同仁：主人的原话是「未连接就进队列」，Offline 只是不会自己变好，内容仍然一个字节都不会丢，
两档的差别只在告知措辞（这一点与 W39 给分享落地定的规矩一致）。

② 队列与补发：顺序与「只发一次」的保证点
deliver 的 WS 分支只改了「未就绪」这一支：queueForConnection 把这条留在待发态
（ChatUiState.queuedForConnection，条目只有 localId 与投递那一刻定下的并行声明；正文 / 图片 /
附件仍从那条气泡上现取，同一件事不留第二份真相源，也就不存在两条真相分叉）。触发点只有一个：
socket 状态变成 Connected 那一刻（onConnectionChanged，由状态流驱动、没有任何轮询），外加
入队之后的一次竞态兜底（连接恰好在投递与入队之间就绪时，那一次补发会扑空）。补发从队头开始，
FIFO 顺序 = 用户发送的先后顺序。
「只发一次」的保证点是「队头 + 出队恰好一次」：队头只在这一步有了结论（发出去了 / 真失败 /
气泡已经不在了）之后才被 dropQueuedSend 摘掉，所以重复的触发拿到的是同一个键、不会多出第二次
出队；flushQueuedSends 是同步函数（一个挂起点都没有），两个触发点在主线程上不可能交错。
第二道保证在服务端：补发复用同一个 clientMsgId（绝不铸第二个），真重复到达也只会被回
chat_duplicate，不会落成第二条消息。补发又失败时按今天的失败路径处理（回滚 + 文案），
绝不静默吞掉。已知边界（写在 KDoc 里）：打断声明不随补发重放——补发时在跑的那一轮早就不是
用户按发送时看到的那一个了，隔半分钟再去打断可能毁掉他没见过的一轮。

③ 状态表达：仍是六态，③ 里多一句更准的话
不新增第七态：等连接的这条走六态里的 ③ 排队中（phaseOf 的判据从「收到过入队回执」扩为
「收到过回执，或本端因未连接把它留住了」），两类排队的区别由气泡小标说清——新纯函数
pendingBubbleFooter 给 ③ 加四个字：「排队中 · 还没连上」。为什么挂在气泡上而不只是那句告知：
告知八秒就收走，而这是个会持续几十秒的状态，牌子撤掉之后光看「排队中」分不出是「她已经收下、
前面还排着队」还是「连都没连上、一个字节都没上路」。柔和告知走新通道 ChatUiState.sendQueueNotice
（与 shareNotice 分开：两条描述的是不同的动作，可以同时挂着），文案 SEND_QUEUED_NOTICE 是
「还没连上，这条排队等着，连上后自动发出」；Offline 那一档换 SEND_QUEUED_OFFLINE_NOTICE
「现在处于离线，需要重新登录或检查服务器地址；这条还没发出去，已排队不会丢」——不提「连上」
「自动发」，那一档没有会自动到来的连接。不刷屏：一轮「队列从空到空」只说一次（连续几条离线
消息不会每按一次发送就弹一遍），记账在 queueForConnection。

④ 未覆盖：REST 通道（长文 / 图片 / 附件）保持今天的行为
POST /api/v1/chat 那条路仍是失败回滚 + 既有网络错误文案，本批不动。两条理由：一是它给不出
「未连接」这个信号（拿到的只是一次网络错误，而请求可能已被服务端收到、也可能没有），
判据不可靠；二是要补发就得重跑图片重编码与附件上传换存储名，而本地 URI 的读授权可能已经失效。
代价：未连接时发长文 / 图片 / 附件仍要用户手动重发一次；影响面仅这一条通道，WS 那条（短文本，
日常绝大多数消息）已经覆盖。

⑤ 未连接时不再有的那句话
「还没连上，这条没发出去，请稍后手动重试」（W39 加的 SEND_NOT_CONNECTED_MESSAGE）与它的判据
sendFailureMessage 一并删除：回滚那条路现在只在连接就绪时才走，这句话已经没有出口，留着就是
一段描述旧行为的死文案。SendFailureMessageTest 的断言改成新事实（未就绪 ⇒ 排队，而不是回滚
加那句话）并连同新的队列判据并入 SendQueueTest，一条断言都没删。另把「空输入什么都不发生」
这条边界抽成纯函数 hasSendableContent，输入栏的 send 与投递口的 emitAndDeliver 共用同一条判据
（行为不变，只是原本写在两处的同一个 if 现在可单测，也不会再分叉）。

测试：新增 SendQueueTest（21 条：三档判据穷举 WsState.entries、两档告知措辞、队列顺序与出队
恰好一次、气泡小标与六态、空输入边界）。assembleDebug 成功；testDebugUnitTest 1118 条
（1101 减 4 加 21），failures 0 / errors 0。
 2026-10-05 13:57:54 +08:00
AskaEth e60ae7aecc docs(05): 锚点补记十——W39 三处措辞不诚实已修（告知不再两句叠加 / 未连接与发失败分开说 / Offline 不再承诺自动发出），并登记两处刻意未做与一条主人定案项 2026-10-05 13:43:01 +08:00
AskaEth b55d220e28 merge: W39 —— 分享告知不再两句叠加；未连接与发送失败分开说；Offline 不再承诺「连上后自动发出」 2026-10-05 13:42:15 +08:00
AskaEth a763592ace fix(chat): 分享告知不再两句叠加；未连接与发送失败分开说；Offline 不再承诺「连上后自动发出」 
三处「对用户不够诚实」的措辞缺陷，各自独立修复。行为上只多了一处「少说一句」，
其余语义一字未改。

① 分享告知两句叠加（ChatScreen.shareNoticeFor）
实机读到的原文是「有 2 个文件读不到，未发送；分享的内容是空的，没有可发送的内容」，
读起来像两个不同的问题。可这两句说的是不同的免责，而「认下了地址却读不到」本身就蕴含
「没有可发送的内容」——叠上去一个字都没多说。故丢件计数为真时不再追加「内容是空的」那句；
其余组合保持今天的行为（只有丢件计数时只说丢件计数；「读不进来」与丢件计数说的是两件事，
照样并列）。KDoc 里记下了这一档今天的真实出口：worthDelivering 要求 isEmpty 的分享必须
有丢件计数或 contentUnreadable 才值得往下走，而后者已被「读不进来」那一档接走，
所以那句加了前提之后一次都不会再出现。

② deliver 的 WS 分支：连接未就绪不等于发送失败（ChatViewModel）
sendChat 回 false 有三种成因（连接状态不是 Connected / socket 对象已空或已被 cancel /
序列化抛了异常），此前共用一句「发送失败，请重试」，用户无从分辨「这条根本没上路」
与「发出去了但失败了」，而后者在连接未就绪时不是事实。现在按失败那一刻的连接状态分开说：
不是 Connected 时说「还没连上，这条没发出去，请稍后手动重试」，仍是 Connected 时逐字保持
「发送失败，请重试」。回滚照旧（摘掉气泡、内容退回输入栏、记下幂等键），没有自动重发，
普通发送的其它语义没动。判据抽成纯函数 sendFailureMessage(WsState)，用例覆盖
WsState.entries 的每一个取值。连接状态取 socket 自己的 StateFlow——那正是 sendChat 判的值，
不用界面镜像过来的 ChatUiState.connection，免得晚一帧读到 Connected 反而说错话。

③ WsState.Offline 不再等一句永不到来的「连上」（ShareLanding / ChatScreen）
Offline 是终态（握手 401 且续不上、或缺少 token / 服务器地址），它不会自动重连。
对它说「连上后自动发出」，用户等的是一个永远不会到来的连接——拿一句不兑现的承诺糊住
一个需要他动手的状况，比不说更糟。新增 ShareLanding.TellOffline：等够久、同一轮只说一次
这些时机与可恢复的那几档完全一致，只有措辞不同：「现在处于离线，需要重新登录或检查
服务器地址；分享的内容一个字节都没发出去，不会丢」。W38 的落地时机一个字没改：
仍然不 take()、不发送，连接恢复后照旧自动补发。哪档配哪句由纯函数 shareWaitingNotice 定，
不再散在 Compose 的 when 里，于是「Offline 换口径」这件事不需要组合界面就能测。

测试：ShareNoticeTest 把「两句都在」的断言改成新事实并穷举同族组合；ShareLandingTest 新增
Offline 的差异、时机与文案用例；新增 SendFailureMessageTest 覆盖每一种 WsState。
assembleDebug 成功；testDebugUnitTest 1101 条，failures 0 / errors 0。
 2026-10-05 13:41:52 +08:00
AskaEth 4eaee04255 docs(05): 补记九补齐 W38 的真机回归——断线分享得到柔和告知且内容不丢，恢复连接后自动补发且只发一次 2026-10-05 13:25:08 +08:00
AskaEth f15f0bf9bc docs(05): 锚点补记九——W38 分享「等连接」缺陷已修（四态纯判据 + 只在该发时才取走内容）、W37 设备验证通过、并行误标的设备证据、以及两条测量教训 
顺带登记三处未修的小账：告知文案两句叠加、deliver 对未就绪与发失败仍不分、WsState.Offline 缺少专门的措辞。
 2026-10-05 13:22:10 +08:00
AskaEth d8228fb315 merge: W38 —— 分享落地必须等到连接就绪：超时不再等于发送失败，内容不再从队列丢失，连接恢复后自动补发 2026-10-05 13:21:26 +08:00
AskaEth aeb37458e8 fix(chat): 分享落地必须等到连接就绪，超时不再等于发送失败 
为什么超时不能等于发送失败
WS 还没连上时投递的分享（ACTION_SEND）此前走成了「发送失败，请重试」，内容还从待发队列里
永久消失。来处是「等连接」那句 withTimeoutOrNull 的返回值被丢掉了：超时与成功走同一条下游，
照样 take() 再 sendShared → deliver → ChatSocket.sendChat 回 false ⇒ ChatViewModel 落到
rollback(localId, "发送失败，请重试")。实机取证（2026-10-05 11:56）：GET /ws/chat status=200
前后的窗口里投递分享，界面上是失败横幅 + 正文退回输入栏，而后端零请求（POST /api/v1/chat
一条都没有，也没有任何 error 帧）——那条横幅把「一次都没尝试发出去」说成了「发送失败」。
ShareIntake.take() 是原子出队且没有归还路径：那一次「其实一次都没发出去」的失败之后，内容
既不在 holder 里、也不在服务端，只剩回滚进输入栏的那一份（多图分享里除首条之外，连输入栏
都回不去）。重试资格因此一起丢了。所以判据只有一条：没连上就一个字节都别动——不 take()、
不发送、不产生任何 error 横幅。

为什么取走时机必须晚于连接就绪
短文本走 WS chat 帧，而分享冷启动必然撞上握手还没完成；帧发不发得出去完全取决于握手结果。
所以等待里不再有「到点就照发」这一档，只有「连上才发」：连接恢复之后由连接状态自己把这条
落地重新触发一遍。

改法
- 判据抽成纯函数 shareLanding（ui/chat/ShareLanding.kt，可单测）：没有待发 ⇒ Nothing；已连接
  ⇒ Send（压过后两条，且返回的是单值动作，所以发送与告知不可能同时发生）；未就绪且还没等够
  ⇒ KeepWaiting；未就绪、已等够、还没说过 ⇒ TellWaiting；已经说过 ⇒ KeepWaiting（不刷屏）。
- ChatScreen 的那个 effect 把连接状态并进键，连接后来就绪会自动重跑、自动补发；「不会重复
  发送」仍然由 ShareIntake.take() 的原子性兜住——哪怕某一次拿着已经过期的快照进来，take()
  给出的也只是队列里的下一条或 null。
- 等太久只做一件事：经既有的柔和通道 ChatViewModel.showShareNotice 说一句「还没连上，分享的
  内容会留着，连上后自动发出」（不是带 X 的 error 横幅），同一次等待只说一次。
- SHARE_CONNECT_TIMEOUT_MILLIS 改名 SHARE_WAIT_NOTICE_MILLIS：它不再是发送的时限，只是
  「等多久才值得说那一句」；「等够久」的计时只跟「队列里有没有东西」与「连上了没有」走，
  连接在 Connecting / Reconnecting 之间抖动不重置它。
- 普通发送路径（输入框、图片、附件）一行未动。

测试
- ShareLandingTest（新，7 条）：未就绪在任何连接状态下都恒不 Send（不取、不发）；未就绪且没
  等够恒 KeepWaiting（也不告知）；等够了只说一次、说过了就不再刷屏；已连接恒 Send（压过告知）；
  无待发恒 Nothing（任何连接状态下都不做事）；文案必须说清「还没连上」与「自动发出」，且不含
  「失败」「重试」。

assembleDebug 与 testDebugUnitTest 全绿（1091 tests / 0 failures / 0 errors）。
 2026-10-05 13:21:09 +08:00
AskaEth 44b58db58a docs(05): 锚点补记八——分享路径设备验证成绩单（文本热/冷启动、超长走文件三条通过；图片受阻于工具）+ W37 说明 + 三条新环境坑（黑屏/adb root 冲掉 reverse/system_server 崩）+ 并行误标问题的取证结论 
把「adb 造不出带授权的 URI intent，别再花时间」与「黑屏会让 input tap 全部落空、先确认屏幕是亮的」写成纪律。
 2026-10-05 13:13:05 +08:00
AskaEth a2350a6d5f merge: W37 —— 分享认下字符串形态的 EXTRA_STREAM（String[] / ArrayList<String>），并在一条内容都没读进来时如实告知，不再静默 2026-10-05 13:09:22 +08:00
AskaEth 0764bc269c docs(02): 客户端答复回执十九——给出那次分享失败的精确时间锚点（11:56:08 握手成功后 ~10 秒内）与「无 error 帧、帧根本没发出」的证据链，并采纳「把允许发送绑在握手完成之后」 
同时确认 kind/leg 的用法边界（kind 只做展示、归属只看 messageIds），以及语音按 v0.67「契约先行、未落地」处理。
 2026-10-05 13:09:18 +08:00
AskaEth 6cdf111419 fix(share): 认下字符串形态的 EXTRA_STREAM,并在一条内容都没读进来时如实告知 
为什么字符串形态必须认
真实世界里 EXTRA_STREAM 有三种形态:规范推荐的 Uri(多选时 ArrayList<Uri>)、String[]、
ArrayList<String>。Android 上确实有一部分发送方(历史遗留 / 跨平台壳应用)在用后两种,而本端
此前完全认不出:getParcelableExtra 遇到 String[] 只往 logcat 打一句 ClassCastException 再回
null,getParcelableArrayListExtra 同理。实测 am start ... --esa android.intent.extra.STREAM
uri1,uri2 投两张图进来就是这个样子。

为什么静默是 bug
上面那次分享的结局是:后端零请求、库里零新增、界面连一句软告知都没有。用户点了分享,没有任何
东西告诉他"没读进来"还是"在路上"——这是最糟的那种失败形态,所以本次一并消灭:带着内容迹象却
一条可用内容都没提取出来时,走既有的柔和通道说一句"这次分享的内容没能读进来,没有发送任何内容"。
EXTRA_TEXT 与 EXTRA_STREAM 都为空(用户确实没分享任何东西)时仍然保持静默,那条边界有测试钉住。

做了什么
- ShareIntake 改成读 EXTRA_STREAM 的原始值再按形态分派(Bundle.get 不做类型检查),Uri / Uri
  数组 / String / CharSequence / 数组 / 列表一并摊平;顺带不再往 logcat 丢那两行 ClassCastException。
- 字符串形态只认 content://:那是本端新开的一条读入口,送进来的只是一段文本,没有任何框架级担保。
  file:// 等于让发送方替本端指定一个本地路径、由本端拿自己的权限去读它;http(s):// 是网络地址,
  收下它等于让第三方的一行文本指定一个 URL 由本应用代取。被拒的条目逐条跳过,不让整次分享失败。
- 优先顺序与去重不变:EXTRA_STREAM 的规范形态 -> 字符串兼容形态 -> ClipData(仅前者全为空时兜底),
  trim / 去空 / 去重,先来的先算;重复项既不算截断,也不把真图挤到上限之外。
- 「带着内容迹象」的判据取 EXTRA_STREAM 的原始值(由调用方读了原始值判出来,含形态本端认不出的那种),
  不是「认下来的地址」——否则「有值但一条都认不出」恰恰会被判成「什么都没分享」而继续静默。
- SharedContent 新增 contentUnreadable 与 worthDelivering:后者是唯一判据,ShareIntake 用它决定
  要不要往下接,shareNoticeFor 用它守卫"什么都没有就一个字都不说"那条边界,两处不会走岔。
- 分类(图片 vs 文档)、落 cache、截断与拷贝失败的既有语义一概不动。

测试
- ShareExtractionTest:字符串形态的顺序与逐条跳过、两种形态并存去重、scheme 白名单表、
  读不进来 / 形态认不出 / 静默三条边界。
- ShareStreamExtrasTest(新):按真实对象验形态分派(String[] / ArrayList<String> / String /
  CharSequence / 认不出的形态不猜但照样算带着内容),并接到提取层验一次端到端。
- ShareNoticeTest(新):"没能读进来"成句且不说成发送失败、正常落地一个字不说、空白分享仍然静默。

assembleDebug 与 testDebugUnitTest 全绿(1084 tests / 0 failures / 0 errors)。
 2026-10-05 13:05:20 +08:00
AskaEth ef257c3167 docs(05): 锚点补记七——并行两路实机验通（三条判据）+ leg 误报并行已修（W36）+ 假后端横幅两档验过 + 模拟器调参（iowait 196%→14%）+ 分享接入其实早已实现 
把「别用 leg 判并行、只看 turn_begin.kind」写成纪律，并记下 ANR 判据的正确做法（拉 trace 看主线程栈，别先怀疑代码）。
 2026-10-05 12:01:18 +08:00
AskaEth 405388e325 docs(02): 客户端答复——回执十八那两个问题的答案（都不解析正文标记、单段样式零差异）、把 turn_begin.kind 立为形状依赖（角标已改以 kind 为准）、并行两路实机验通、分享发送失败一次的观察 
为什么不提交后端会话的在途追加：他们正往 02 里写回执十八（未提交），按 02 的协作纪律处理——先另存他们的补丁、把文件还原到 HEAD、只提交我方这一节，随后再把他们的内容原样贴回末尾。两边都不丢，也不把他人的在途工作算作我的提交。
 2026-10-05 12:01:14 +08:00
AskaEth 39a63f8d30 fix(chat): 并行路角标改以 turn_begin.kind 为准，不再拿 leg 冒充并行 
leg 是服务端**会话内的路序号**：beginLegLocked 对每一条新路都自增 legSeq，
普通串行回合照样占号——会话里发第二条普通消息，leg 就是 2。而角标旧判据是
leg >= 2，于是那条串行消息被挂上「并行路 2」，凭空声称存在并不存在的并行。
「是不是并行路」真正的判据是 turn_begin.kind（turn = 普通串行回合，
parallel = 忙时另起的一路）；解析层本来就把它读出来了，只是绑定时丢掉了。

- TurnBinding 新增 parallel；withTurnBegin 收下 kind，由 isParallelLegKind
  判定：只有逐字等于 parallel 才算，turn、缺席、空串、大小写不同一律不算。
- 合并规则：新建按 kind 定；同 turnId 重复到达时取或（old.parallel || 本帧
  是并行），一旦为 true 就永远是 true。与 closed 同一条纪律——单调的既成事实
  不许被后到的帧翻回去；也顾及 steer_ack 可能先建一条没有 kind 的占位表、
  随后才由这一路自己的 turn_begin 补上并行的现实顺序。
- 降级：kind 不来的老服务端上 parallel 恒为 false，角标一枚都不挂——宁可少挂
  一枚，也不拿 leg 去猜、去多说一句假话。
- legBadgeOf 改成同时看 parallel 与 leg，三处调用点（提问侧、回复侧、流式气泡）
  都跟着传 parallel；文案仍是「并行路 N」。

测试：ParallelTurnsTest 补 kind=turn / kind=parallel / kind 缺席三档、重复帧的
合并（含「已收口的并行路不被重新打开也不被降级」）；TurnStreamsTest 把
「leg>=2 就挂标」的断言改成以 kind 为准，并补上那条真机回归——会话里第二条
普通消息（leg=2、kind=turn）在提问侧与回复侧都不挂角标。
 2026-10-05 11:59:21 +08:00
AskaEth 6e00697110 feat(chat): 分享进来的消息加一枚「用户分享」渲染层角标 
背景：ACTION_SEND 分享进来的内容在会话里与手打的完全看不出区别，主人要求「可识别」。
与后端定过的红线（devdocs/02 的 F4、ShareRules 的「为什么正文一个字都不加」）要求人类可见
标记只能放在客户端渲染层，所以本次正文、content 与任何上行字段一个字节都没动。

改了什么：
- ChatViewModel 的 emitAndDeliver 多一个 localIdPrefix 参数（默认 local-，手打那条路逐字不变），
  sendShared 的每一条投递都传 share-：多张图会发多条消息，它们都是分享进来的，所以每条都带。
  前缀只加在幂等键前面，后面仍是随机 UUID，唯一性不受影响。
- MessageSource.kt 新增两个常量与两个纯函数：isSharedClientMsgId 只认 share- 且要求后面还有尾巴
  （恰好 share- 一律 false：本端铸键永远是 share-uuid，没有尾巴的键不是本端铸的，不能替一条
  来路不明的消息声明「这是你分享的」）；isSharedMessage 在它之上加一道只认 user 侧的闸。
- MessageBubble 的 bubbleFooter 多一个 shared 参数，角标 [用户分享] 紧挨来源角标拼在角标行里，
  沿用这行既有的字级与颜色，不新造样式、不用 Material3，也只对用户侧气泡出现。
- 新增 SharedMessageBadgeTest：判据的六类边界取值与角标行里的落位。

为什么用幂等键而不是正文标记：clientMsgId 由服务端原样回填，是客户端读得回来的既有字段，
「这条怎么进来的」写在它上面不用新增任何协议，也不污染用户正文。
 2026-10-05 11:30:56 +08:00
AskaEth 5d4888ab71 docs: 历史回填决策落地——做（带三条约束：先 dry-run / 留回滚点 / 一次性不留常驻逻辑），02 给后端请求、05 记决策 2026-10-05 11:17:15 +08:00
AskaEth 108feefac4 docs(05): 锚点补记六——文档已拆分（含新的文件地图与写回规则）+ <p> 规整上线（5de708a，我方零改动）+ 三件待办 + 一条待主人拍板（历史回填） 2026-10-05 11:15:53 +08:00
AskaEth 681ae96a9c docs(02): 收下后端会话的追加（回执十七·补2：<p> 规整已落地 5de708a，写入侧收口、我方零改动）+ 合并 W34 的拆分 2026-10-05 11:14:22 +08:00
AskaEth 95e657e704 merge: W34 —— 拆分 02/05 两份过长协作文档（历史部分归档，内容零丢失） 2026-10-05 11:14:16 +08:00
AskaEth 98b2274e68 docs(devdocs): 二次瘦身——02 里已确认完结的登记条目整块归档，05 收回两段纪律 
02-前后端协同事项.md：860 行 -> 454 行；02-archive-历史回执.md：1274 行 -> 1681 行
- 把已确认完结的登记条目整块搬进归档：A（A1~A5）、B（B1~B6）、C（C1~C3）、D（D1~D5）、E（E1~E6）、F3~F5、G1~G4、H1，共 8 块 30 条，按原顺序插在归档前言之后、回执一之前
- 主文件保留：标题与用途、顶部 P0 置顶块、归档说明、登记规范、仍未闭环的登记（F1/F2/F6 与 G5）、附：状态一览表、最近 5 条往来
- 唯一改动原文处：状态表 C1 行的指针「见本文 §C1」改成「见 02-archive-历史回执.md §C1」
- 归档前言新增一行，说明这批条目的来路，以及 F/G 两节的主标题与未闭环条目仍在主文件

05-开发进度与交接.md：601 行 -> 624 行；05-archive-历史批次.md：437 行 -> 418 行
- 从归档里捞回两段纪律（本轮新增约定/坑、派 agent 进 worktree 的硬规矩），放进「坑与勘误」节末尾，各加一个小标题
- 锚点节里加一行指针：历史批次的细节已移到 05-archive-历史批次.md

零丢失的证据
- 逐行多重集比对（对基线 b0b73d0）：02 的非空行 1560 -> 1568，正好 +8，即新增的说明行；C1 那处是同一行整行替换，一删一增净零
- 05 的非空行 846 -> 851，正好 +5，即 2 个小标题 + 1 行锚点指针 + 2 行归档前言
- 除上述新增行与空行计数漂移外，行集合与原文件完全一致，无任何内容行丢失或重复
- 12 个代表字符串的 grep -c 拆分前后相等，含跨主文件与归档的 pinned DESC 排序串、834ef36、title must not be blank 三条
- 搬迁全程用 sed 按行区间原样切割、未改写文字；行尾统一 CRLF

未跑 Gradle（纯文档搬运），未 push。
 2026-10-05 11:13:28 +08:00
AskaEth cb5fc0c605 docs(devdocs): 拆分 02/05 两份过长协作文档，历史部分归档，内容零丢失 
02-前后端协同事项.md：2126 行 → 860 行
- 历史回执（回执一~十六及同时段已闭环的登记）整体搬到新建 devdocs/02-archive-历史回执.md（1274 行）
- 主文件保留：标题与用途、顶部「待后端处理的 P0」置顶块、登记规范、A~I 全部登记条目、附：状态一览表、仍未闭环的登记（2026-10-04 深夜续那条待主人拍板的口径冲突）、最近 5 条往来
- 置顶块之后新增 5 行归档说明：历史回执去向 / 新回执照旧写在本文末尾 / 已闭环的老登记会定期挪进归档 / 本文旧指针去归档里找对应小节
- 不动置顶块、不动状态一览表、不动未闭环的登记，后端会话仍可照旧在本文末尾追加回执

05-开发进度与交接.md：1035 行 → 601 行
- 历史批次细节与已过时的验收现场记录搬到新建 devdocs/05-archive-历史批次.md（437 行）：本轮追加（W4–W7）、W8–W10、W11–W12、W13–W14、W15–W16、装机验收轮、分享到 App 验收轮、W27
- 主文件保留全部「★ 恢复锚点」性质的节（当前状态与待办、锚点补记一~五、纪律补记）与当下要用的节（当前状态、构建、验证方式、凭据处理红线、环境要点、后端、模拟器、易忘的实现约定、管理区约定、C-2 验证结论、坑与勘误、后端协同、实机验收方法、三条待拍板项定案）

零丢失的证据
- 全部搬运用 sed 按行区间原样切割，未改写任何既有文字；新增内容只有 02 主文件那 5 行归档说明与两份归档文件开头的 2 行说明
- 逐行多重集比对（awk 计数 + diff）：除上述新增行与个别空行外，原文件与新「主文件+归档」的行集合完全一致，无增无删
- 8 个代表字符串的 grep -c 拆分前后相等：679cee0 3=3、18381f6 1=1、guardrail_input 3=3、internal/config/runtimeconfig/models.go:300-311 1=1、回执十七标题 1=1、devtools/fake-backend/ 4=4、W15-retry-2-EDITED 3=3、ChatImageBudget.SERVER_MAX_CHARS 1=1
- 行尾统一为 CRLF（与 devdocs 下其余文件一致）

未跑 Gradle（本次纯文档搬运），未 push。
 2026-10-05 11:10:03 +08:00
AskaEth b0b73d063b docs(05): 补一条硬纪律——合并 worktree 后当场清理（本批 8 个全残留、主人先发现的）+ 假后端进程同样是遗留 2026-10-05 10:44:27 +08:00
AskaEth 54e7b35e60 docs(02): 回执十七答复——p 半包裁定=b 写入侧规整（我方零改动、历史一起变好）；思考流等「在哪开」；⏳ 帧已上线 ⇒ 视为阻塞解除，开始真机验证 2026-10-05 10:35:50 +08:00
AskaEth 9e6a6b395c docs(02): 把「标签包裹」从观察升级为明确请求——主人要求问「能不能修」，附三条可选路径与必须的裁定 2026-10-05 10:26:43 +08:00
AskaEth 83ea5ddff7 docs(02): 请后端确认两件事——思考流（reasoning.kind 在 anthropic 组上非法，开关在协议原生 thinking 形状里，谁决定？）+ 一条回复没拆气泡（产出侧 <p> 包裹不完整，非客户端解析问题） 2026-10-05 10:25:28 +08:00
AskaEth e1223fdee5 docs(05): 锚点补记五——忙时并行整批（W28-W33 + FB2）+ 思考流排查结论（reasoning 键在 anthropic 组上非法，开关在协议原生 thinking 形状里，待查）+ 环境与教训 2026-10-05 10:23:54 +08:00
AskaEth c3cfef75bb merge: FB2 —— 假后端加 --hold-replies（收到消息不自动落库），让「忙时被拒」的横幅可稳定复现 2026-10-05 10:23:40 +08:00
AskaEth c73dd532ff feat(devtools): 假后端加上行挂起开关 --hold-replies，让「忙时被拒 / 排队 / 队列满」可稳定复现 
为什么
客户端手里还挂着一条没发出去的乐观气泡时，收到「队列满 / 忙时被拒」会怎样，判据是
ChatViewModel.queueFullOutcome（本会话待发 0 条 ⇒ 刻意什么都不说、1 条 ⇒ 回滚 + 横幅、
≥2 条 ⇒ 一个气泡都不动、只提示「可能没发出去」）。但假后端收到上行 chat 或
POST /api/v1/chat 时会立刻把那条用户消息落库并广播 message_persisted，客户端拿
clientMsgId 一比就把乐观气泡收走（consumePendingFor）—— 一个往返之后待发列表就空了，
那三档里只剩「0 条」能凑出来。真后端忙时是先排队或先拒绝、不会立刻落库，所以这是假后端的
建模缺陷，本次修它。

加了什么（只动 devtools/fake-backend/，不碰 app/ devdocs/ 构建文件）
- 启动开关 --hold-replies（默认关）：收到上行消息只记录、不落库、不广播 message_persisted。
  上行帧照常进 out/upstream.jsonl、state.wsUpstreamByType 照常计数；回复路径
  （--stream-chunk / --auto-reply / /__control/reply 自己的 persist）一概不受影响 ——
  关的只是「上行那条的落库」这一件事。
- 运行期开关 POST /__control/hold-replies?on=1|0，便于在同一个进程里做「先挂着 → 再落库」两段。
- 显式补落库 POST /__control/persist?session=&id=<holdId|messageId|clientMsgId>&index=N：
  不给选择器就按 FIFO 落最旧那条；落库时才盖 createdAt、才认领幂等键（与「队列满的判定发生在
  认领之前」一致），广播的 message_persisted 与默认路径同形状。挂起列表在 GET /__control/state
  的 heldMessages 里。
- 挂起的消息在挂起时先占号（msg-xxxxxx），所以 REST 回执里的 messageId 与之后真正落库的是同一个。

三处 message_persisted 广播点各自改成了什么
- 原 :657（WS 上行 chat 之后那条）与 原 :1235（REST POST /api/v1/chat 之后那条）：受本开关控制，
  挂起时整条跳过（仍记录上行帧）。
- 原 :773（send_reply_round 里助手消息的落库）刻意不动：那是回复路径，本来就有自己的 persist
  开关，本开关不去关它 —— 任务里也明说不要把回复路径一并关掉。已实跑验证：开关打开时
  reply?persist=0 不落库、reply?persist=1 照旧广播 message_persisted。

拒绝场景（任务第 2 项）：不需要新造
/__control/pending-full（载荷 {sessionId,mode,max,clientMsgId?,messageId?}，与客户端
PendingFullData 逐字对应）、/__control/error?code=chat_busy（带 clientMsgId/messageId）与能发
任意帧的 /__control/frame 早就在了，形状也不缺东西。本次只实跑复核（三帧都在探针那边看到原样帧体、
回执 delivered=1）并写进 README，没有改它们的形状。

默认行为未变
--hold-replies 默认关，state.holdReplies=false、heldMessages=[]；关着时三处广播、add_message 的
id 分配（新增的 message_id 参数只在挂起补落库时给值）、REST 回执形状逐字与改动前一致。

验证（本机实跑，端口 18099/18098，绝不用真后端的 10942）
挂起档：ws_probe 发 chat 后 2 秒里零回帧、out/downstream.jsonl 里 message_persisted 计数 0，
而 upstream.jsonl 与 wsUpstreamByType.chat 都记到了；POST /__control/persist?id=local-1 之后才在
活着的连接上收到 message_persisted（delivered=1，id 正是挂起时先占的 msg-000001）。REST 路径同理：
/api/v1/chat 的 202 回执时刻下游流水没有那一帧，2 秒后 persist 才有（时间戳可对）。pending_full /
error{chat_busy} / __control/frame 三帧都投递成功。运行期 on=0 → 立刻落库、on=1 → 挂住，双向有效。
默认档回归：立即落库、灌消息分页、复位都照旧。

README
新增第 6 节「场景四：忙时被拒 —— 让『待发气泡还挂着』可复现（--hold-replies）」：写清乐观气泡被
一个往返收走这个机制、开关怎么用、一条可复制的命令序列（起服务 → 发 chat 挂住 → 注入 pending_full →
期望的横幅文案），以及帧上带不带 clientMsgId/messageId 时客户端四种不同的处置。原第 6-10 节顺延为
7-11 节，并在开关表、控制端点表、记录文件节、已知不确定节各补了对应内容。
 2026-10-05 10:23:09 +08:00
AskaEth 1f6c16c590 merge: W33 —— parallel_limit 提示加「本端确在并行档」的闸 + 查证并发额度横幅（结论：代码无缺，是验证条件问题） 2026-10-05 10:13:08 +08:00
AskaEth f2fbdff9a7 W33：并行落回排队的告知加一道本端档位闸 + 忙时被拒那条横幅的只读查证 
一、改了什么
加一道闸：pending_ack{reason:"parallel_limit"} 那句降级告知（「她正忙，这条没能另起
一路…」），只在本端当前的「她忙时发消息」档位确实处于「并行」档（InterruptMode.Parallel）
时才给。判据扩了既有纯函数 parallelLimitNoticeFor 的签名（reason + mode 一起判），
本端不在并行档时一律返回 null；调用点在 onEvent 的 PendingAck 分支，档位沿用
currentInterruptMode() 现读（偏好是用户在设置页当场切的东西，缓存住就留一个静默不生效
的窗口），因为 onEvent 不是 suspend 函数，这一句起一个协程去读（与 ensureMessageKnown
同一形态），不起常驻订阅。

二、为什么
pending_ack 是广播帧，每条已认证连接都收得到。极端情况下「别的端在同一会话声明并行
又落回排队、而本端并未选并行」时，本端也会收到这一帧并说那句话 —— 这就是误报。
可那件事与本端无关：用户没选并行时，他这条消息本来就是普通排队、他预期的就是排队
⇒ 落回排队不是意外 ⇒ 不说并不构成静默（与「绝不静默」不冲突）。反过来，在那个时刻
说一句「这条没能另起一路」会让用户以为是自己刚发的那条出了岔子；误报会教用户不信任
这条提示，代价比少说一句大。

三、只读查证（主人点名：忙时被拒那条横幅到底会不会出现）
结论：不缺，pending_full 不带 clientMsgId 时共三档落位，其中两档都写 error，横幅照常
渲染 ——
  · 恰好一条待发气泡 ⇒ 回滚档，error = QUEUE_FULL_MESSAGE（她正忙且队列已满，这条没
    发出去，请稍后手动重试）；
  · 两条及以上 ⇒ 说不准档，error = QUEUE_FULL_UNKNOWN_MESSAGE（她忙不过来，这条可能
    没发出去），两个气泡一个都不动；
  · 两档都带 errorIsQueueFullNotice = true（柔和档配色），横幅由 ChatScreen 同一条
    error 通道渲染。
只有「零条待发气泡」那一档是 Ignore，按设计什么都不写：没有气泡会挂住，也就没有要说
的，不能凭空弹一句 —— 理由在 queueFullOutcome 的 KDoc 与 QueueFullOutcomeTest 的两条
测试里（既有，非本次新增）。即「没带 clientMsgId」不等于「说不准档」，本次查证没有
发现需要改代码的地方。

四、测试
新增 3 条（ParallelLimitNoticeTest）：追加队列档 + 该 reason ⇒ 不提示；打断档 + 该
reason ⇒ 不提示；再加一条把三档一起摆出来的汇总断言（只有并行档给文案）。「并行档 +
该 reason ⇒ 提示」由既有的那条测试覆盖（现在显式传 InterruptMode.Parallel）。总测试
1030 → 1033，0 失败 0 错误。
 2026-10-05 10:12:41 +08:00
AskaEth 79fcd803a0 merge: W32 —— 忙时被拒那条横幅调柔和（只调那一档，真错误仍红）+ 并行额度落回排队时如实说一句 2026-10-05 09:56:22 +08:00
AskaEth e85209eebb fix(chat): 忙时被拒那条横幅调柔和（只它，真错误照旧红）+ 补 pending_ack 的并行降级告知 
一、忙时被拒的横幅改用柔和档颜色（它不是错误，不该刺眼）
改了什么：那句告知（她正忙且队列已满，这条没发出去，请稍后手动重试）一直走 state.error 这一条通道，
ChatScreen 里那条 Banner 的调用点对所有 error 一律用 colorScheme.error（正红）。现在给 ChatUiState
加一位 errorIsQueueFullNotice（只决定配色），忙时被拒的两条入口（WS 广播 pending_full 与定向
error{chat_busy} 的队列满处置、REST 409 chat_busy 的回滚）把这一位写成 true，ChatScreen 那一处调用
据此在 onSurfaceVariantSummary（同文件里分享/附件/定位三条告知用的那档柔和色）与 error 之间选色。
为什么：主人裁决形态不变（摘乐观气泡 + 顶部横幅如实告知 + 正文/图片/附件还给输入栏 + 重发复用幂等键），
但红色不要太醒目——忙时被拒不是坏了，是真没排上，红得像故障会吓人。而它与真错误（登录失效、网络失败、
服务端 4xx、图片与附件处理失败……）共用 error 这同一条通道，直接改那个调用点的颜色会把真错误一并调柔和，
所以先分档再选色：写 error 的每一处都显式带着这一位，边界写进了 ChatUiState.errorIsQueueFullNotice
与 Banner 的 KDoc，免得后来人统一改色。

二、消费 pending_ack 的 reason，如实告知「并行没排上、已按普通排队走」
改了什么：reason 字段在解析层早就原样保留（WsEvent.kt 的 PendingAck.reason），但一直没有任何地方消费它
——收到它时界面与普通排队毫无区别。新增纯函数 parallelLimitNoticeFor(reason)（已知值给一句话，未知值 /
缺席 / 空白给 null，不为不认识的 reason 编文案）、常量 PARALLEL_LIMIT_REASON 与 PARALLEL_LIMIT_NOTICE，
以及状态位 ChatUiState.parallelLimitNotice（与 shareNotice / attachmentNotice 同一套机制：8 秒自动收走、
用柔和色、不给关闭按钮），在 WS 的 PendingAck 分支里接上。
为什么：设置页新增并行档之后，开关 ON 不等于一定起第二路——服务端 CHAT_MAX_PARALLEL_TURNS 小于 2 或
额度已满时会让它落回排队，并回 pending_ack{reason:"parallel_limit"}。用户选了并行却看不出区别就是静默，
违反项目铁律「绝不静默」；而这条不是错误、是降级，所以措辞把三件事说清（并行没排上、这条没丢、她做完
手上这句就轮到它），配色与上面那条忙时告知同一档。

测试：新增 ParallelLimitNoticeTest 8 条（reason 的三档穷举 + 横幅温度的边界：忙时被拒为柔和、真错误不
继承那份柔和）。assembleDebug 与 testDebugUnitTest 全绿：1030 个测试，0 失败 0 错误（基线 1022，新增 8）。
 2026-10-05 09:55:53 +08:00
AskaEth bb4bb583d5 docs(02): 收下回执十六（形态冲突裁决=调柔和 / turn_id 要加 / 并行开关归前端 / 三处更正经核对均不影响我方 / 文档搬家）+ 我方答复五条 2026-10-05 09:51:01 +08:00
AskaEth 4847d74d87 merge: W31 —— 设置栏「她忙时发消息」追加第三档「并行」（忙时上行 chat.parallel=true，绝不发 interrupt） 2026-10-05 09:38:00 +08:00
AskaEth a776e9f608 feat(settings): 设置页「她忙时发消息」追加第三档「并行」——忙时不打断、另起一路（chat.parallel=true） 
主人要求：在既有的「追加队列 / 打断」之下再追加一档「并行」。三档语义互补——追加队列进队列等
（默认档，逐字节不变）、打断先发 interrupt 再发这条、并行不打断、另起一路同时处理。

改了什么：
- AppSettings：InterruptMode 加第三个值 Parallel(wireScope = null, wireParallel = true)，并给枚举
  补出第二根线 wireParallel（wireScope 只管 interrupt 的 scope，表达不了「要声明并行」这件事）。
  既有两个值的 name 与落盘键 interrupt_mode 一个字未动——改名会让已存偏好读不出来并静默回落默认档。
  落盘字符串 → 档位的映射抽成顶层纯函数 toInterruptMode（AppSettings 本体要 Android + DataStore，
  单测里起不来），新增的第三个名字能正确读回，未知字符串仍回落 AppendQueue（既有行为未变）。
- 判据抽成纯函数 parallelForSend(mode, busy) 与 parallelWireValue(declare)：前者与
  interruptScopeForSend 共用同一个忙判据（ChatUiState.busyMode != null），只在会话正忙时为真。
  规范 §2.2 没写空闲时要不要也声明——空闲时这条本来就是它自己的回合，声明与不声明在服务端是同一
  件事，故取与打断同一个判据（最小惊讶：空闲时三档逐字节完全相同）。
- 两条互斥由枚举取值本身保证，不是靠约定：并行档 wireScope 是 null ⇒ 绝不发 interrupt；另外两档
  wireParallel 是 false ⇒ 绝不带 parallel 键。默认档「追加队列」线上零差异由此结构性成立。
- 发送路径接线：ChatViewModel.deliver 只读一次偏好、同时喂给两个判据（读两次会在用户切档的瞬间
  出现「既打断又并行」）；ChatSocket.sendChat 与 ChatRequest 各加一个 parallel 参数，false 一律
  翻成整键省略——显式 false 会被序列化成 parallel:false，那是「显式否认」而不是「未声明」，
  默认档就不再逐字节不变。
- 设置页：新选项标题「并行」，summary 说清后果——不打断她正在说的这一句、两路各算一遍会多花一份
  算力与 token（主人裁决：峰值 token 近翻倍可接受，但用户有权知道）。UI 仍是 Miuix，与同栏另外
  两条逐字同形，勾选标记位置相同。
- 分享路径同样不套用这一档偏好（W26 的 allowInterrupt 因此更名为 applySendPreference，它现在管
  的是整档偏好）：分享是批量投递，逐条索要并行会被服务端 2 路额度把同一次分享劈成两种待遇，且每
  条各算一遍；用户也没按过发送键说这条要并行。单张图时同样不声明，规则才能一句话说清。

为什么：主人 2026-10-05 的裁决（真两路并行）需要客户端有一个显式声明入口；W30 已备好 chat.parallel
的线上形状（默认 null = 整键省略），本次只把设置页这一档与发送路径接通，上行仍是纯增量——没选
「并行」的用户线上一个字节都不变。

验收：assembleDebug 通过；testDebugUnitTest 通过（1022 测试 / 0 失败 / 0 错误；基线 1004，新增 18：
ParallelForSendTest 13 条 + InterruptScopeTest 1 条 + InterruptModeTest 4 条）。
 2026-10-05 09:37:26 +08:00
AskaEth 82d3ca3953 docs(02): W30 客户端半边登记（结构性降级保证）+ 一条与规范的形态冲突请后端裁决（被拒消息：红气泡 vs 我方既有的横幅+回滚）+ 三条待确认 2026-10-05 09:12:20 +08:00
AskaEth 005720575a merge: W30 —— 忙时并行的客户端半边（六态 + 灰态 + (sessionId,turnId) 两级分桶），帧侧全部可降级 2026-10-05 09:11:19 +08:00
AskaEth 29299b190e feat(chat): 忙时并行回合的客户端半边 —— 六态 + 灰态 + (sessionId, turnId) 两级分桶 + 新帧消费（全部可降级） 
依据：Cyrene_v2/DevDocs/_specs/忙时并行-规范草案.md（§1 行为 / §2 接口 / §4 主人裁决）。
后端 v0.65 尚未落地这些帧，所以本次的新键与新帧全部按可降级实现：帧不来、字段缺席时，
App 在今天的真后端上行为与改前逐字相同（下面的「降级保证」逐条给了证据）。

一、改了哪些文件

新增（纯逻辑，可单测）
- app/src/main/kotlin/top/yeij/cyrene/domain/chat/ParallelTurns.kt
  两级分桶键 TurnBucket(sessionId, turnId) 与 turnBucketOf / closingBucketOf；
  六态枚举 TurnPhase 与 turnPhaseOf；灰态收口判据 closesAnswering；
  消息↔回合绑定 TurnBinding 及其纯函数（withTurnBegin / withSteeredMessage / closingTurn /
  allClosed / bindingOfMessage）；路小标文案 legBadgeOf。
- app/src/main/kotlin/top/yeij/cyrene/ui/chat/TurnStreams.kt
  StreamingLeg(bucket, StreamingState) 与 withLeg / beginLeg / finishingLeg / withoutLeg；
  六态在状态上的推导 ChatUiState.phaseOf(消息 / 乐观气泡)；
  路小标与「跳到提问」的查表 legBadgeForMessage / legBadgeForTurn / jumpIndexForTurn。

修改
- data/api/dto/MessageDto.kt：HistoryMessageDto 增可选 turnId（历史行 / 落库行都用它）。
- data/api/dto/ChatDto.kt：ChatRequest 增可选 parallel（REST 与 WS chat 同形）。
- data/ws/WsOutbound.kt：chat 增可选 parallel、interrupt 增可选 turnId，省略即整键不进线上。
- data/ws/WsEvent.kt：新增 turn_begin / turn.end / steer_ack 三个事件与其载荷；
  session_busy / session_idle / pending_drain 增可选 activeTurns，session_interrupted 增
  activeTurns + cancelledTurns，pending_ack 增可选 reason。
- ui/chat/ChatViewModel.kt：流式解析器与「本回合见过结构化正文帧」由单值升为按桶的 map/set，
  新增「本会话最近见过的 turnId」锚点；消费 turn_begin / steer_ack / turn.end；
  助手落库行按其 turnId 收口灰态并只摘掉它自己那一路的流式气泡；排队回执记进 queuedKeys。
- ui/chat/MessageBubble.kt：MessageBubble / PendingBubble 增 phase 与 legBadge，
  正文气泡增灰态配色，新增并行路小标（可点即跳）；角标文案抽成纯函数 bubbleFooter。
- ui/chat/ChatScreen.kt：按桶取每一路的流式状态并渲染；传入六态与小标；忙碌行加「并行 N 路」。
- 新增 4 个测试文件（共 82 条）：ParallelTurnsTest、TurnStreamsTest、
  WsEventTurnFramesTest、WsOutboundParallelTest。

二、为什么这么做

- 界面必须按 (sessionId, turnId) 两级分桶（规范 §1.7 第 1 件硬要求）：两路并行时两个不同
  turnId 的 message.delta / thinking.delta / tool_call 会交错到达，照老代码「一律累加到当前那
  一个流式气泡」会把两条回复糊成一条（规范 §1.4 点名的那件事）。现在每一路各有一份解析器、
  一份思维链、一份工具卡表、一个流式气泡。
- 灰态（④ 已读、未答）的唯一权威收口事件是 turn.end（规范 §1.2）。本端另外在 stream_end
  （既有的「整轮结束」帧，v0.36 起带 turnId）与「同 turnId 的助手落库行」上也收口：
  前者在 turn.end 到位之前是唯一能收口的帧，后者是规范给的兜底。三者顺序不定、重复到达都无害
  （纯函数幂等）。
- 六态判定与收口判据的不变量都抽成纯函数，可直接单测；判定顺序即证据强度：
  被拒 > 已绑定未收口 > 已绑定已收口 > 本地乐观气泡 > 排队回执。

三、字段缺失时的降级保证（本次最要紧的一条）

- 全链路没有一处「turnId 为空就不渲染」。turnBucketOf 在帧壳没给 turnId 时先回落本会话最近
  见过的 turnId、再回落匿名桶（turnId 为空串）⇒ 所有无 turnId 的帧落在同一个桶里，
  那就是老代码那唯一一个流式气泡。
- turn_begin / steer_ack.turnId / turn.end 不来 ⇒ 一条绑定都建不起来 ⇒ 六态里只可能出现
  ①②③⑤，灰态根本不会进入；界面与改前逐字相同。
- activeTurns 缺席时不动这个计数（null 是「不知道」，0 是「确实空闲」，两件事不许互相顶替）；
  pending_ack.reason 缺席就是 null，绝不伪造。
- 上行三个新字段（chat.parallel、interrupt.turnId、ChatRequest.parallel）本端今天一个字节都
  不发：真并行要用户显式声明，而声明入口不在本次范围内。服务端照旧走排队 + 回合内 steer。
- 已被单测钉住的证据：
  ParallelTurnsTest「所有无 turnId 的帧落进同一个桶」「两个空白 turnId 不算匹配，绝不收口」；
  TurnStreamsTest「单路时长度恒为 1」「没有任何 turn 帧时已落库=②、本地气泡=①」；
  WsEventTurnFramesTest「老形状的帧解出来新键一律为 null（不是 0、不是空串）」；
  WsOutboundParallelTest「省略时那条帧逐字节相同，且不带该键」。

四、等 v0.65 的部分

- turn_begin / steer_ack.turnId / turn.end 的真实到达，历史行的可选 turnId，activeTurns /
  pending_ack.reason / cancelledTurns 的真实取值。
- 真并行的触发入口（谁在什么时候把 chat.parallel 置 true）——本次只备好线上形状，不接 UI。
- 仍未决且影响客户端的两项：graph_update 两路互相顶掉（规范未决 10，等 design/19 裁决）；
  按 turnId 单独核算用量（规范未决 14，可选）。

五、规范里与本端既有定案冲突的一处（如实登记）

规范 §1.1 ⑥「被拒」要求气泡带红色「未送达 · 会话正忙」并可重试；本端被拒（pending_full /
定向 chat_busy）的既有定案是摘掉乐观气泡 + 横幅如实告知 + 正文还给输入栏（可再按一次发送，
幂等键保证不会落成第二条消息）。既有行为由现有测试钉住，本次不改；六态判定里保留了 Rejected
档并由单测直接覆盖，只是本端的现实路径走的是回滚那一支。

验证：assembleDebug 绿 + testDebugUnitTest 绿（0 失败 0 错误 0 跳过）。
 2026-10-05 09:10:45 +08:00
AskaEth d0bb43c87c docs(02): 收下后端回执十五（忙时并行规范已定稿 + 主人三条裁决 + 语音切片上线 + Docs 同步中）+ 我方答复：已开工，帧侧全部做成可降级 2026-10-05 08:58:44 +08:00
AskaEth 5e6dc76ae8 docs(02): 转达主人的第三种「忙时发消息」方案（并行两路）+ 流程要求（开工前先定行为与接口规范，客户端在此之前不动代码）+ 三条 API 文档过期的可核查证据 2026-10-05 08:28:58 +08:00
AskaEth 0d50bc82ca docs(02): 收下后端回执十四（IM 文件的 documents 缺口已修 679cee0 / viewer 永久不做 / 语音只差 SILK 样本）+ 我方答复五条 2026-10-05 08:26:10 +08:00
AskaEth ac3f63f8c8 merge: W29 —— stream_chunk 改整段语义 + 空壳消息如实说一句 + 分享超长走文件 + 图片 URL 兜 host 2026-10-05 08:15:27 +08:00
AskaEth be1c372d99 fix(W29): stream_chunk 语义订正、空壳消息如实说明、分享长正文走文件、图片 URL 兜住 host 
一、stream_chunk 由「增量」订正为「整段」（后端回执十三 §1）
   后端确认三件事：生产里已无生产者、delta 是整段 res.Text、不会与结构化帧并存。
   W26 那版照 message.delta 把 delta 追加进同一气泡是错的——真到达会把同一段内容追加成重影。
   改法：同一回合内已经收到过结构化帧（message.start / message.delta）就整帧忽略；否则先用
   StreamingContentParser.reset 清缓冲，再把这一整段喂进去，即用它整段替换当前流式气泡的正文。
   兜底分支保留（后端明确不建议删：那是未知帧不丢内容的兼容路径）。顺带把「回退路径没有
   message.start、所以 freshTurnIfFinished 不触发」这条边界在同一个分支里补上（一行级别的收口）。

二、空壳消息不再渲染成空气泡
   主人报的 bug 根因在服务端（微信发来的文件没有挂到消息的 documents 上，content 也是空），
   已登记后端；但客户端拿到的确实是一条什么都没有的消息，此前渲染成空气泡，用户只能猜。
   新增纯函数 isContentlessUserMessage（role 是 user 且 content 空、无 image、无 documents、
   无 thinking 才成立，任何一项有内容都不成立，assistant 一律不成立），成立时在气泡位置改为
   一句如实说明「这条消息的内容没有被传过来」：灰底灰字（沿用文件里既有的灰态小字），措辞只陈述
   本端确定的事实，不猜原因。判据放渲染层（MessageBubble），因为它纯属显示，服务端说什么就存什么，
   不在组装层改 DTO。

三、分享进来的超长正文走文件（主人已拍板）
   分享的文本超过现成的 TEXT_AS_DOCUMENT_RUNE_LIMIT 时，落成一份 .txt：写进分享缓存目录、
   上传 POST /documents、随 chat.documents 发，正文那一栏留空。判据抽成纯函数
   DocumentDelivery.planSharedText（正文是否超阈值 + 附件位是否还有空）。
   附件位被分享进来的文件占满（一个回合 5 份）时不做转换：正文照正文发，并在提示里说清
   「本想作为文件发送，但附件位已占满」——绝不为了塞下 .txt 挤掉用户明确要发的文件。
   落盘失败同样退回内联并说一句。组合与图片的关系：那份 .txt 就落在正文原来所在的那一条上
   （第一条带图，其余每条一张）。
   明确不动的：用户自己在输入框里打的字那条路，长正文照旧按正文发（devdocs/05 的定案第 3 条），
   这两件事不是同一件。

四、历史图片的同源绝对地址按当前 baseUrl 兜住 host（F6①）
   POST /upload 的 url 是按请求时的 r.Host 拼的绝对地址且原样落库，换服务器地址后旧图取不回；
   后端明确认可客户端做「保留 path、替换 host」。新增纯函数 ImageHostRebase.apply：只认
   http(s)://任意host/api/v1/files/一段名字 这一种形态，替换 scheme 与 authority、path 逐字节保留；
   第三方 CDN、data:、content:// 与 file://、相对路径、裸文件名、带查询串或百分号编码、多一段路径的
   一律原样返回。渲染历史图片前在 ChatScreen 传入 AuthManager.currentBaseUrl，全屏查看拿到的也是
   替换后的地址。逆作用写进 KDoc：换了指向不同数据的 host 会 404，那是诚实的失败，比永远取不回好。
   不改落库数据、不改上传、不碰 documents。

测试：新增 ImageHostRebaseTest 与 ContentlessMessageTest，DocumentDeliveryTest 补分享长正文的判据；
stream_chunk 那条分支是 VM 里的状态机分支，没有硬抽成纯函数（不为测试拧弯架构），改动写在 KDoc 里。
 2026-10-05 08:14:33 +08:00
AskaEth c0e78371cb docs(05): 锚点补记四——W28 共享 socket（含装机验收证据与两个固有代价）+ 假后端测试台 + 一条硬教训（问一句比猜一天值）+ 登录页 IME 结案 2026-10-05 08:08:19 +08:00
AskaEth 7b97440973 merge: W28 —— 进程内共享一条 ChatSocket（连接数 N+2 → 1），SessionsViewModel 为唯一 owner 2026-10-05 08:03:50 +08:00
AskaEth 276b01113b refactor(ws): 进程内共享一条 ChatSocket，访问 N 个会话不再留 N+2 条连接 
改了什么
- AppContainer：删掉「每次调用都新建」的 createChatSocket()，改成进程内唯一的 val chatSocket
  （by lazy）。三个调用方全部改取它，工厂方法一并删掉——不留「还能再造一份」的入口。
- ChatViewModel / SessionsViewModel / AdminViewModel：原本各自建一条连接，现在都改为订阅同一条。
- 连接的开与关收敛成唯一一处主人：SessionsViewModel 的登录态订阅
  （LoggedIn 则 connect()、LoggedOut 则 close()）。
  * ChatViewModel 不再 connect()（它随切会话就被销毁，不该掌握连接的生死）；
  * AdminViewModel 不再 connect() / close()，包括原来「viewer 时关掉自己那条连接」那条分支——
    这三帧服务端本就 fail-closed，本类另有逐帧角色门，断开连接多挡不掉什么，却会掐掉别的屏幕。
  * AdminViewModel 登出仍然只丢日志基线（行为不变）。
- 三个 VM 的 onCleared 一律不再 close（共享连接不能被任何 VM 关闭，否则切会话 / 关管理页会把
  主会话流式、抽屉未读、管理页三帧一起掐断）。
- KDoc 同步改：AppContainer（为什么可以共享 / 为什么必须唯一 / 开与关的主人是谁）、ChatSocket
  （它不是某个屏幕的私有连接、谁都不许 close；events 的 replay 恒为 0 从「安全」升为「必需」）、
  三个 VM 的类注释与 onCleared。

为什么行为不变
- 服务端广播、不按会话订阅：改前 N 条连接各收全部帧，改后一条连接收全部帧，每个 VM 收到的帧集合
  逐帧相同——这是本次重构安全的唯一依据。isForSession、各事件分支、重连与退避逻辑、下行帧语义、
  UI 一个字都没动。
- baseUrl / token 每次重连现读，connect() 幂等（wantConnection 已置位即返回），所以登出重登、
  换账号都不需要重建实例。
- 连接数量：改前访问 N 个会话 = N+2 条连接、N+2 个 OkHttpClient（每个连接自带一个），改后恒为 1 条。

如实记一处非逐帧等价的细节（已核过，无功能影响）：改前每条连接各自握手，服务端每次都会回一帧
history；改后只有首次连接会收到。晚于连接建立才创建的 VM 因此少收一帧 history，而该帧对非主会话
经 historyForSession 过滤后本来就是空（只用来收掉 loading），对主会话与 REST 首屏是同一份内容的
冗余来源，且新 VM 的 pending 为空、reconcilePending 是空操作。

验证：assembleDebug + testDebugUnitTest 全绿（891 个用例，0 失败 0 错误 0 跳过）。
 2026-10-05 08:03:09 +08:00
AskaEth 27d5680d21 merge: FB —— 可编程假后端测试台（devtools/fake-backend/，纯 Python 标准库），解锁 after 补洞 / 打断帧 / stream_chunk 三条端到端验证 2026-10-05 08:03:03 +08:00
AskaEth 86a2217858 feat(devtools): 新增可编程假后端（devtools/fake-backend），用来造「特定服务端行为」的端到端场景 
为什么要它
客户端有三类行为只在特定服务端行为下才验得到，而真后端不可编排、造场景的代价高到不可做：
1. after 正向增量补洞：要造「WS 握手只回放最近 50 条、库里却有 120 条」这个洞，用真后端得灌 51 条消息、
   每条跑一次模型回合。假后端可以精确、免费、可复现地造出来（--history-replay N）。
2. 打断帧：客户端在「设置=打断 + 会话正忙」时会发 interrupt{scope:"current"}。要验它真的发出去了，
   就得看上行帧——假后端把每条上行帧原样记进 out/upstream.jsonl，这是唯一的第一现场。
3. stream_chunk 回退路径：真后端可能永远不走那条路，假后端可以用 --stream-chunk 指定走。

加了什么
- devtools/fake-backend/fake_backend.py：纯 Python 3 标准库（无第三方依赖）。实现了客户端启动到渲染
  用得到的那一段 REST（login/refresh/logout、sessions 列表与增删改、messages 分页与搜索、read、
  messages 编辑删除、meta/enums、personas、chat）加一个手写 WebSocket（GET /ws/chat?token=…，
  握手后立刻发 history 帧）。鉴权头 X-API-Version / Authorization 一律不校验，但会记进 out/http.jsonl
  （Authorization 与 ?token 只留 sha256 指纹）。
- 控制端点 /__control/**（不碰 /api/v1/**）：灌消息（不调模型）、下发 session_busy/idle/interrupted、
  触发一轮回复、pending_full、定向 error、任意帧、踢掉客户端 WS、404 session_not_found、复位、看状态。
  目的是让「造场景」与「看结果」都不需要人手点 UI。
- devtools/fake-backend/ws_probe.py：最小 WebSocket 探针（标准库手写握手 + 帧收发 + ping），
  用来证明握手返回 101 / 收到 history 帧，并往连接上发任意上行帧对账。
- devtools/fake-backend/README.md：起法（Windows + Git Bash）、客户端怎么指过来（adb reverse +
  http://127.0.0.1:18080）、每个场景的可复制命令序列、端点速查、形状出处表、以及「它不做什么」。

边界（README 里也写明了）
不校验鉴权、不落盘成持久数据、不调模型、不是产品的一部分、不实现契约全集（admin 面、附件上传、
observability 推送等一律 404），并且不要拿它当后端行为的事实来源——所有响应形状都是照客户端代码
读出来的（README 第 9 节逐条列出文件:行号），不代表真后端真的这么回。
默认端口 18080，刻意避开真后端的 10942。

形状来源（举几个关键例子）：信封 ApiEnvelope.kt:8；鉴权头 ApiClientFactory.kt:115-118；
WS 地址 ChatSocket.kt:287-295；SessionSummaryDto 与排序 SessionDto.kt:16-50 加线上夹具
SessionDtoRealPayloadTest.kt:36-38；after 升序 / before 倒序 / q 与 after 互斥 SessionsApi.kt:71-101；
limit 默认 50 上限 200 MessageRepository.kt:149-150；枚举表逐字取自 MetaDtoRealPayloadTest.kt:24；
404 session_not_found ChatViewModel.kt:1802-1808；stream_chunk 回退 WsEvent.kt:205-228。

验证（本机实跑，输出见提交后的报告）
curl 打通 login/sessions/messages（limit/before/after/q 与三个 400 互斥面）、meta/enums、personas；
ws_probe 握手拿到 101 与匹配的 Sec-WebSocket-Accept，并收到 history 帧；灌 120 条后握手只回放最近 50 条
（msg-000071..msg-000120），用 after 游标正向走两页正好补回 msg-000021..msg-000120、第三页为空；
--stream-chunk 下下发的是 stream_chunk×3 + stream_end（没有 message.* 帧）；打断帧原样落进
out/upstream.jsonl；ping/pong 与 HTTP keep-alive 均正常。
 2026-10-05 08:01:48 +08:00
AskaEth a0085802dd docs(02): 把「微信文件任何客户端都看不到」提到文档最顶部的 P0 置顶块（主人亲自报的 bug）+ 补一个必须说清的分叉：字节到底落盘了还是只内联进上下文 2026-10-05 07:58:20 +08:00
AskaEth ae49853029 docs(02): 登记新需求——IM 渠道的语音消息要能被读到（前端那半我们做，IM 那半请后端比照 IM-1 做 ASR 入站） 2026-10-05 07:54:55 +08:00
AskaEth 691b073e32 docs(02): 回应后端回执十三（stream_chunk 改整段语义、F6① 客户端兜 host、viewer 摘项）+ 登记一条新 P0：IM 渠道的文件没有挂到消息的 documents 上 2026-10-05 07:54:45 +08:00
AskaEth 6c2cc57cdb docs(02): 状态表维护（C1/C3/D4 早已闭环）+ 新增一张「待后端回应」清单 
主人早上问「需要后端做的事都写进文档了吗、本地还有没有独立事件」，我借这次盘点把协作文档收口：

1. **状态表维护**：C1（语音轮次不落库）、C3（voice_output 字段）、D4（无未读状态）三行原写
   「待确认」，其实**早已解决**——C1/C3 由契约 v0.59 §3.15（语音改走与文本同一条编排路径、
   voice_output 补 sessionId/deviceId），D4 由 v0.37（unreadCount + 已读游标，客户端已接入）。
   按正文依据打勾，并写明「客户端至今没有语音 UI，所以 C1/C3 我们从未验证过」这一诚实边界。
   F6 那行从「待确认」改成「问过、后端尚未回应」，让「谁在等谁」一眼可见。

2. **新增「客户端待后端回应的清单」**（文档末尾）：只列我们问过、还没拿到明确答复的七条——
   stream_chunk 三点确认 / F6① upload url 绑 host / viewer 凭据路径或确认永远 501 /
   并行 tool_use 配对的 P0（他们说在修）/ llm_usage.session_id 接线（同上）/
   IM 入站文件的真机验证（只能主人做）/ 以及这次状态表维护本身请他们复核。

   每条都写了「要什么」与「我们这边的处置」：例如 F6① 明确**不做绕行**（不猜 base、不重写历史
   URL——那会把「服务端说是什么」变成「客户端以为是什么」）；viewer 那条给了二选一
   （给铸造路径，或明确永远 501，那我们就不再把它当验收项挂着）。

本次提交只动文档。
 2026-10-05 07:41:27 +08:00
AskaEth 219c50b7c2 docs: 自主推进一批的登记（假开关 / 静默丢正文 / 分享自打断 全修完 + 一条口径冲突要主人拍板） 
主人睡前说「按主线继续推，或者先按模块检查」，我把两件都做了：先做了一次只读自审
（假开关 / 死代码 / UI 规范 / 文档漂移，四张带「文件:行号」的清单），然后按清单修了一批。
本批全部是「界面上或文档上声称能做到、代码里其实没接线」这一类问题。

devdocs/05：新增「锚点补记三」，写清——
- 本批 5 条落地（W25 打断模式真接线 / W26 stream_chunk 不再静默丢正文、错误横幅可关闭、
  分享不再自相打断、两处死代码 / W27 删只被测试养的 API、公式去重、03 四处更正 /
  WsEvent KDoc 更正）；
- 三个「假开关 / 静默」的真相与各自的修法；
- 两条查完发现不是 bug 的（「抽屉最后消息预览不刷新」与「session_interrupted 丢弃 N 条」），
  附证据，免得下次返工；
- 装机验证：错误行的关闭叉验通（x2/x3 截图），以及一条我刻意没验的（登录页 IME ——
  要清空 App 数据才能回到登录页，万一登不回去今晚所有装机验证能力一起没了，风险不对称）；
- 本批没做的：连接所有权（共享 socket）只写设计要点与七条验收清单，不动手；
  DocumentDelivery 那组「正文转文件」API 不删也不接（口径冲突）；
- W26 留下的一条边界（回退路径没有 message.start，freshTurnIfFinished 不触发）。

devdocs/02：追加客户端登记三条——
1. 请后端确认 stream_chunk 今天还会不会发、delta 是增量还是整段、会不会与结构化帧并存
   （我们按契约的「非流式回退路径」实现，但那条路可能已经名存实亡）；
2. 告知我们开始发 interrupt{scope:"current"} 了（窄触发条件、默认档零变化、分享不打断、
   以及「两条道无强序」这个我们坦承的边界）；
3. 登记「超限走文件」的口径冲突（05 的定案说做的是「用户打的字自动变附件」不做，
   主人后来点名要做 —— 两者多半不是一件事），不替主人合并，所以那组 API 原样留着。

本次提交只动文档，无代码改动。
 2026-10-04 22:40:43 +08:00
AskaEth 85a922c01b docs(ws): 更正 SessionInterrupted.dropped 的过时 KDoc（本端全部路径下它恒为 0） 
原来的注释写「当前任务取消、pending 清空，dropped 为丢弃条数」——那是 `interrupt` 只有一种形状
（等价于今天的 `scope:"all"`）时的口径。契约 v0.56 起 `scope:"current"` 只取消在跑回合、**保留**
待处理队列，该档 `dropped` 恒为 0。

而本端「追加队列」档一个 interrupt 都不发、「打断」档发的是 `current`（见 feats/W25，cfdc094），
所以 `dropped` 在客户端的全部现实路径里恒为 0 —— 「已打断，丢弃 N 条」那句话在本端根本不可达。

注释里写明这一点，免得后来人照着一句不可达的文档去实现一个用不上的计数。

只改注释，无行为变化。
 2026-10-04 22:40:07 +08:00
AskaEth b7ac6b8853 merge: W27 —— 删只被测试养的 availablePages + 图片 base64 上限公式去重 + 03 四处文档更正 2026-10-04 22:37:25 +08:00
AskaEth 3c0ed16ee7 merge: W26 —— stream_chunk 不再静默丢正文 + 错误横幅可关闭 + 分享不再自相打断 + 两处死代码 2026-10-04 22:37:24 +08:00
AskaEth eacc65acc9 fix(chat): 四件可见修复 —— 回退正文不再丢 / 错误横幅可关 / 分享不自杀 / 清两处死码 
1) stream_chunk 不再被静默丢掉（整段正文丢失风险）
   - ChatViewModel.onEvent 新增 WsEvent.StreamChunk 分支，把 delta 照 MessageDelta 的同一形态喂进
     流式解析器。
   - 依据：后端契约写明「未映射/无法确定的事件仍走 stream_chunk + stream_end（非流式回退路径）」
     （Cyrene_v2/Docs/api-client.md §3.1）。原先它落到 onEvent 末尾的 else -> Unit 被静默吞掉 ——
     服务端一旦走进回退路径，整段回复正文一个字都不显示，而且没有任何信号说明正文丢了。
   - stream_chunk 不带 index（那是 message.start 的字段），所以不读 index；解析器与 MessageDelta
     一样按需创建，按「同一个当前流」处理。
   - 未改 WsEvent 的解析形状，只加消费分支。

2) 错误横幅可以关掉了（两个 dismissError 不再是死方法）
   - ChatViewModel.dismissError / SessionsViewModel.dismissError 原本全仓零调用方，现各接上关闭
     入口，并各补 KDoc 写明边界：清掉的是本端已经显示的那条错误，不代表服务端那边没事；不做自动
     消失。
   - ChatScreen.kt 的 private Banner 增加可选 onDismiss，有它时右侧挂 MiuixIcons.Basic.Close
     （带 contentDescription）；只有 state.error 那条传 viewModel::dismissError，分享 / 附件 /
     定位那几条如实告知保持原样（它们自己会收走）。
   - SessionDrawerContent.kt 的错误行改成行内布局 + 右侧关闭按钮，样式随它已有的行（footnote2、
     同一水平内边距、同款 IconButton 灰度）；新增参数 onDismissError，由 ChatHomeScreen 接
     sessionsViewModel::dismissError。
   - 错误内容本身、错误出现的时机、是否自动消失，一概未动。

3) 多图分享不再互相打断
   - 根因：W25 把「她正忙时按发送」接到发送路径后，deliver 每次投递前都会发一条 interrupt 帧
     （scope=current）；而分享 N 张图 = N 次投递，第 2 条起就把前一条刚起的回合取消掉了，
     最后只有最后一张被回答。
   - 改法：emitAndDeliver 增加 allowInterrupt: Boolean = true（默认值保持现状），deliver 按它决定
     是否调 interruptRunningTurn()；sendShared 的两条投递都传 false。
   - 只有一张图也传 false：分享是「一次把东西倒进去」的批量动作，自己打断自己一定是错的；
     「分享从不打断」是一句话，「超过一张才不打断」得先解释那个分界。
   - 单条发送（send）的口径一字未动。

4) 两处死代码
   - 删掉 ChatViewModel.clearDraftDocuments()（复核为全仓零调用方）。没选「在输入栏加清空全部入口」：
     附件芯片本来就每枚带叉、上限只有 5 枚，逐个移除已经覆盖全部场景；输入栏里再加一枚清空按钮是
     噪音，而留着一个没人接的公开方法只会让人误以为它是活的。
   - 删掉 ChatScreen 的 onLogout 参数（函数体内一次都没用到）与 ChatHomeScreen 的对应传参。
     真正的登出路径（CyreneApp -> ChatHomeScreen -> SettingsScreen）原样可用。

验证：assembleDebug 与 testDebugUnitTest 均 BUILD SUCCESSFUL；单测 892 条、0 失败 0 错误、0 跳过
（本次未新增测试：① 的判定是 when 的一个分支、抽不出自然的纯函数，不为测试把架构拧弯）。
 2026-10-04 22:36:47 +08:00
AskaEth 805d8b530a refactor+docs(W27): 删掉只被测试养着的 AdminAccess.availablePages，让 ChatImageBudget 的公式只留一处，并就地更正 devdocs/03 四处过时表述 
清理（零行为变化）
- 删 domain/admin/AdminAccess.kt 的 availablePages()：全仓（含 app/src/test）调用点 0 处 ——
  main 里只有它自己的声明、测试里 2 处（AdminAccessTest 那 1 条用例一并删掉）。它早已被
  ui/admin/AdminHomeScreen.kt 的做法取代：遍历 AdminPage.entries + 每行 canAccess 决定是否禁用。
- ChatImageBudget.SERVER_MAX_CHARS 原来把 base64Chars 的 ((n+2)/3)*4 又内联重写了一遍，
  改为 base64Chars(SERVER_MAX_DECODED_BYTES) + PREFIX_ALLOWANCE_CHARS（一处公式、一处真相）。
  代价：该常量由 const val 变 val（const 不允许调用函数）。取值逐位不变 = 6990572，由
  ChatSendPolicyTest 的独立重算断言与 ChatDtoRealPayloadTest 对服务端真实文案的断言继续钉住。

文档（devdocs/03，一律删除线保留原文 + 更正括注，不动别人的回执段落）
- §4 重连补全：02/A5 的 after 正向增量已接入（loadAfter + ChatViewModel.catchUp，28c3142）。
- §4 忙碌/队列 UI 映射：客户端只发 scope:"current"，该档 dropped 恒为 0、all 从不发，
  所以「已打断，丢弃 N 条」在今天的客户端里不可达。
- §5 mode 回落：mode 已落库（后端 b686d5f），MessageBubble 按 mode 分支。
- §4 打断模式：补上 W25 接线的依据 cfdc094 / feat/W25-interrupt-scope。

devdocs/05 追加 W27 小节；另记下 data/ws/WsEvent.kt:272 的同类过时 KDoc（不在本轮允许改动的
文件清单里，未动）。

验证：assembleDebug 通过；testDebugUnitTest 891 条 / 0 失败 / 0 错误（改动前 892，删掉 1 条）。
 2026-10-04 22:35:20 +08:00
AskaEth e4c6c7c72a merge: W25 —— 把设置页的「打断模式」真正接到发送路径（默认档零行为变化） 2026-10-04 22:31:52 +08:00
AskaEth cfdc094c30 fix(chat): 设置项「她正忙时按发送」不再空转 —— 发送前按偏好决定是否先打断 
设置页那个开关此前没有任何发送路径读它：interruptMode 全仓只出现在 AppSettings
（定义 / 读写）与 SettingsScreen（渲染文案），于是把它切成「打断」后行为与「追加队列」
一模一样，ChatSocket.sendInterrupt 更是零调用方（死 API）。这正是一直挂在文档
devdocs/02 协同项 A2 上的欠账（后端 v0.56 已支持 scope，客户端没接）。

现在按契约 v0.56 §3.1 接上，判据抽成与发送路由同类位置的纯函数
interruptScopeForSend(mode, busy: Boolean)：String?

1. 追加队列（默认档）⇒ 恒定返回 null，一个 interrupt 帧都不发，线上请求与今天逐字节相同；
2. 打断（wireScope = "current"）且会话正忙 ⇒ 这条消息之前先发 interrupt{scope:"current"}
   （只取消在跑回合、保留待处理队列，队列里的消息按编排器续跑，一条都不丢）；
3. 打断但会话空闲 ⇒ 不发（命中空闲会话是 no-op，白发一条帧只多一次往返，还会在 logcat
   里制造「这里打断过」的假象）。

「正忙」只认服务端 session_busy 帧给的 busyMode != null，不用 queueDepth——队列深度
非零不等于有回合在跑（pending_ack / pending_drain 也会动它）。

接线点在 ChatViewModel.deliver() 的通道分支之前（app/src/main/kotlin/top/yeij/cyrene/
ui/chat/ChatViewModel.kt）。放在那里而不是 emitAndDeliver 开头是刻意的：上面每一段本端
拒绝（附件超限 / 图片处理失败 / 附件上传失败 / 引用不合法）都会「回滚、什么都不发」，
先打断她的回合再什么都不发是凭空的破坏。每次投递只经过那里一次，所以一次投递最多一条
打断帧，任何后续分支与重试都不会重复发。

偏好每次发送现读（不缓存、不订阅 Flow）：「在设置页切成打断、然后立刻发的那一条」正是
本次要修的场景，缓存值要等 Flow 推到才更新，冷启动那一下必然没到——那就等于留了一个
静默不生效的窗口。读失败（IO / 损坏）回落默认档，也就是最少动作的那一档，与 AppSettings
把未知取值解成默认档是同一条纪律。

打断帧发不出去（只有「WS 未连接」一种原因）静默、不阻断本次发送：本次消息的成败与它
无关（REST 通道不看 WS 连接），且一直有既有的回执 / 回滚路径如实上报；反过来「打断失败」
没有对应得上的动作（重试等于把消息再发一遍，正是幂等键在防的事），喊一声只会误导。
于是打断没生效 = 行为退回默认档，是用户看得懂的状态，不是被藏起来的事。

测试：新增 InterruptScopeTest 8 条（两档 × 忙闲四格穷举 + 默认档零行为变化 + 偏好回落
方向），全仓 884 → 892。assembleDebug 与 testDebugUnitTest 全绿（0 失败 0 错误）。
设置页那两条文案原本就与 scope:current 的真实语义相符（「已排队的消息保留，继续依次
回答」），未改一个字。

文档：02 的 A2 状态表、05 的 A2 条目都写着「客户端尚未接入该字段」；03 里「打断模式 →
UI 限制一次只发一条」的前提（interrupt 会清空 pending）也随之失效，三处一并补记更正。
 2026-10-04 22:29:57 +08:00
AskaEth b8f0833137 docs: 收下后端回执十二 + 登记本轮三条接入结论 + 05 锚点补记二（含两条新教训） 
devdocs/02（与后端会话共用的协作文档）：
- 收下他们的**回执十二**：knowledge 的根因（参数角色缺席 + 收尾静默分支）与修法、并行
  tool_use/tool_result 配对的新 P0（客户端不需要适配）、契约 v0.64 的只读
  GET /admin/llm/usage、IM 入站文件「能拿到字节」（真机验证只能由主人做）、
  llm_usage.session_id 恒为 NULL。
- 追加**我方登记**：v0.63 那两条（reason / 404）都已接入并推送；after 正向增量的两条口径；
  及一条要他们确认的**我方主动口径** —— unreadable 且 mime 是 text/ 时让 reason 压过正文渲染。
- 他们点出的三处旧口径（1049/1110/1309 行）我核过，**都在他们自己的回执段落里**，按同一条规矩
  请他们自己更正，我们没有动手。

devdocs/05（我方进度与交接）：
- 锚点更新：HEAD、884 测试、本轮 5 条落地、待办重排、家务办完。
- 新增「本轮未验证的」一节：把**验过的**与**没验过的**分开写（404 兜底验通；after 只验到「真请求
  打出去了」、补洞端到端仍未验；W24/W23 的设备侧只验到能开的程度）。
- 两条新教训：① 那个「未响应弹窗」是模拟器/宿主机被拖垮（日志里系统自己的
  PointerEventDispatcher 卡了 37 秒），uiautomator dump 要省着用；② **一次性告知不能挂在会被销毁的
  状态上** —— 404 兜底第一版就是这么悄悄失效的，只有真机看一眼才能发现。

本次提交只动文档，无代码改动。代码侧本轮四个提交（28c3142 / 1794e53 / b5c0b13 / 2d382b1）都已推到
origin/android。
 2026-10-04 22:22:51 +08:00
AskaEth b5c0b13210 fix(chat): 「会话已删」那句解释必须由不会被销毁的那一层持有 
真机验收 404 兜底时发现的真问题：**切换本身是对的，但用户看不到任何解释**。

- logcat 链路完整：`GET /sessions/web:{已删}/messages?limit=50` → `404` →（约 0.9 秒后）
  `GET /sessions` → 界面切回主会话。也就是说「退回主会话 + 如实说一句」里的**前半句成了**。
- 但**后半句一个字都没显示**：那句横幅原来挂在 `ChatUiState.sessionGone` 上，而
  `onSessionGone` 一被调用，`activeSessionId` 就被收敛回主会话、`ChatScreen` 的 `key` 随之变化，
  承载它的那个 `ChatViewModel` 连同状态**立刻被销毁** —— 横幅来不及组合出来就没了。
  （这正是「把一次性告知放在会被销毁的状态里」的经典坑，值得单记一条。）

改法：
- `ChatUiState.sessionGone` 保留，但只当**触发信号**（KDoc 已改写说明这一点）；
- 文案由 `ChatHomeScreen` 的 `remember` 持有（它活得比会话 VM 久），通过新的
  `sessionNotice: String?` 参数注入 `ChatScreen`，仍然走页面上那同一排 `Banner`，
  8 秒后自己消失（它描述一次刚发生的动作，不是持续状态）；
- `onSessionGone` 里**先**立起告知、**再**刷新列表——顺序反了同样什么都看不到。

验证：装机复测通过，红字横幅如期出现在主会话页顶部
（证据 `app/build/e2e-shots/w7-gone-2.png`），logcat 链路 404 → `GET /sessions` 完整。
assembleDebug 与 testDebugUnitTest 全绿（884 测试 / 0 失败，与改动前同数：本次只动了接线与文案，
没有可新增的纯函数）。
 2026-10-04 22:20:59 +08:00
AskaEth 1794e53d1c merge: W24 —— 编辑弹层只显示纯文本（原文含标记时如实告知会被替换，绝不静默丢旁白） 2026-10-04 22:08:08 +08:00
AskaEth 2d382b11cd merge: W23 —— 接入契约 v0.63 的 documents[].reason（只在下发时原样显示，不做整句判断） 2026-10-04 22:08:06 +08:00
AskaEth 66c2291312 feat(chat): 编辑框只显示纯文本 —— 真有标记时才剥，且弹层明说会替换掉什么 
主人拍板：编辑单条消息时输入框里只放纯文本，不再让用户对着 <p> / <action> / <narration> 改字。
红线是「不许静默丢东西」，所以这次不是「把标记一剥了事」：

- 新增纯 Kotlin 模块 domain/chat/MessageEditText.kt（无 Android / Compose 依赖）。
  原文不含已知标签时逐字节恒等：不 trim、不折叠连续空行、不换换行符；含标签时用
  domain/parse（项目里唯一的解析器，不另写正则，免得两套口径分叉）按原始片段顺序拼出可见纯文本，
  正文与旁白/动作一并保留，气泡之间空一行；一个气泡都解析不出就回落成原文（宁可不剥）。
  hasMarkup 只在「保存真的会替换掉什么」时为 true。
- MessageActionState.Edit 新增 markupReplaced；startEdit 只算一次 editableMessageOf
  （不放进 state.update 的 lambda 里），draft 拿纯文本、markupReplaced 拿原文带不带标记。
- MessageEditDialog：markupReplaced 为 true 时在计数行下方多一行小字，写明「保存后这条消息只剩
  你写的这段文字，原来的旁白与动作会被替换掉」；为 false 时一行都不多显示。计数与保存禁用逻辑不变。
- 保存提交的就是 draft 本身，不把标记猜着装回去：任何回填都要先猜「旁白该插回哪一句之间」，
  猜错就是静默移动她说过的话，用户还看不出发生了什么（理由写在 submitEdit 与弹层的 KDoc 里）。
- 新增 MessageEditTextTest（21 例）：纯文本恒等（空串、首尾空白、连续三个换行、CRLF、
  以及 1 < 2 / <div> / <P> / <p2> 这类「有尖括号但不是标记」的普通文本）、线上真实标记串、
  纯旁白、带属性的 p 标签、head/tail 旁白的先后顺序、气泡间只空一行、畸形未闭合不丢字。

为什么这仍然值得做：主会话 64 条 user 消息全是纯文本，所以对今天的真实数据这是一条恒等变换——
它是防御性口径，不是修一个正在发生的 bug；也正因如此，纯文本路径必须逐字节不变。
 2026-10-04 22:07:40 +08:00
AskaEth e4915a6904 docs(02): 收下后端回执十一（四点确认 + knowledge 缺陷已立案 + IM-1/U1 在实施） 
后端会话直接写进了本机 devdocs/02（与主树共用同一份文件），这里把它落成一次提交，
免得长期挂在工作区、也便于将来对时间线。

回执十一的四点：sess-* 不加 404 例外（与我们的答复一致）；documents[].reason 他们不会擅自改文案
（要改会同时升契约并回执）；404 session_not_found 的用法确认；日期更正已互相认账。

另两条与我们相关的：
- 我们登记的 knowledge 工具失败（E2E-DOC 那条，纯文本也复现）他们已按更正后的口径立案排查，
  修复推库后会补一条回执（含根因文件:行）。他们同时要求「无论回合因何结束都落一条可见的
  assistant 消息」，边界保留：被 interrupt 取消 / 被 stale gen 取代 / 静默内部流程仍不落库。
- IM-1（各适配器入站内联受支持格式的文件字节）与 U1（llm_usage 落库 + 只读汇总端点
  GET /api/v1/admin/llm/usage，后续契约 v0.64）在实施中 —— 后者对我们只有将来做管理页时才算增量。

本次提交只增文档，无代码改动。
 2026-10-04 22:01:01 +08:00
AskaEth 28c314262e feat(chat): 接上 A5 正向增量 after，并用 404 session_not_found 把「会话已删」如实说出来 
改了什么：
- SessionsApi.listMessages 加可选 after（契约 §1 行 6）。before / q / after 三者互斥是服务端的
  硬约束，本端三个调用点各只给一个；after 为 null 时 Retrofit 整个省掉这个参数 ⇒ 既有三条路径
  的线上请求逐字节不变。
- MessageRepository 加 loadAfter：同一个端点，服务端按【升序】返回（与 before 的倒序相反），
  仍统一转成升序的 PagedMessages。顺手去掉 toPagedMessages 参数名里那个已经不对的 newestFirst。
- ChatViewModel：
  · 新增 newestKnownAt（从状态现算的 after 游标）与 absorb（只并消息与乐观气泡，不碰
    loading / loadingOlder / hasMore / error —— 一次静默补拉不该把上拉位置和错误横幅掀掉）。
  · 掉线那一刻记下游标、重新连上时用它做一次正向增量。记录时机必须在「掉线」而不是「重连后」：
    重连的 history 帧会把最近 50 条灌进来、游标随即被推到「现在」，那时再取就取不到那个洞了。
    「再拉一页最新」永远补不回中间断掉的那一段，这正是 after 存在的理由（02/A5 的欠账）。
  · ensureMessageKnown 先用增量（只要新来的那几条），还认不出来才退回整页重拉。
  · 循环推进抽成纯函数 loadForwardPages：游标必须严格前进（同毫秒并列且超过一页时推不动，
    契约 §A5 明写的已知边界）+ 轮数上限 20，两道防死循环的闸都由单测钉住。
- 404 session_not_found（契约 v0.63）：首屏 / 上拉 / 增量三条读路径都判，非主会话就置
  ChatUiState.sessionGone；ChatScreen 据此显示一句实话并回调 ChatHomeScreen 重拉会话列表
  （refresh 内部会把「指向已删会话」的 activeSessionId 收敛回主会话）。
  主会话不置位：那说明部署本身出了问题，该显示的是普通错误横幅，而不是一句假的「已切回主会话」。

为什么：
主人那次「图片凭空消失、别的端也看不到」的真相，就是会话在别处被删掉之后，客户端把它渲染成了
一条空会话 —— 让用户对着空白猜。现在有了机器可读的 404，就能如实说一句并把人带回主会话。
另一半是重连补洞：一直是「再拉一页最新」在顶着，断线期间超过 50 条必丢中间那一段。

验证：assembleDebug + testDebugUnitTest 全绿，846 测试 / 0 失败 / 0 错误。
较基线 831 新增 15 条（MessageAfterRepositoryTest 5 条走真 OkHttp 断言线上 URI；
ChatRecoveryTest 10 条钉住 404 判据与增量循环的两道闸）。
设备侧验证（点开看到那句实话、断线补洞）另行做，不在本次提交的断言范围内。
 2026-10-04 22:00:55 +08:00
AskaEth e5fa1b871f 接入契约 v0.63 的 documents[].reason：把「读不到的原因」原样送到附件预览弹层 
后端 902b6ee / 契约 v0.63 给 historyMessage.documents[] 的元素加了可选字段 reason：
只在 status == "unreadable" 时下发（Go omitempty，extracted 时整个键缺席），内容与后端
注入模型清单里的那 10 条是同一份字符串，最长的一条 40+ 字。

改了什么
- DocumentRefDto 加 reason: String? = null。documents[] 在 WS 握手 history、
  message_persisted、GET /messages 三处共用这一个 DTO，所以一处解析三条路全覆盖。
  KDoc 写明三条口径：可选、只在 unreadable 时下发、是后端原话所以客户端原样显示，
  且绝不做整句相等判断（需要分支只允许用稳定子串）。
- DocumentChipModel 加 reason，由 DocumentChips.of(ref) 取 ref.reason 去掉首尾空白后
  非空才留，否则归一成 null——一句空话会顶掉弹层里的通用说明，比没有更坏。
  芯片外观一个字没改：detail / statusLabel 保持现状（unreadable 仍显示「读不到」）。
  理由：那句话太长，塞进一行芯片只会被 Ellipsis 切掉半句，比不显示更糟。
- DocumentPreviewGate.plan 增加 reason 参数：非空白时直接作为正文区那句说明原样返回
  （NotText(reason)），压过本端按 mime / 扩展名的裁决；DocumentTarget.previewPlan 顺着
  chips.reason 把它带进裁决。预览弹层本身一行代码都没改——它渲染的就是 plan.message
  那句话，所以 reason 从 DTO 到用户看见的那句话整条链路上没有任何改写或截断。
- 配套单测 17 条。

为什么这么改
- 服务端那句原因已经断言「无法抽取正文」，它比本端按类型编的通用说明（只知道类型、
  不知道到底为什么）准确；替它改写、归纳或截断就是丢掉服务端唯一一次说清原因的机会。
- 它也不该与正文并存：服务端说正文抽不出来，本端再把字节当 UTF-8 渲染，产出的正是
  正文闸要消灭的「看着像文件坏了」。
- reason 缺席时（契约 v0.63 之前的历史消息）产出与改之前逐字相同：兜底那句话、判据、
  文案全都不动。

测试（新增 17 条）
- DocumentDtoTest +5：unreadable 带 reason 逐字解出；extracted 元素没有该键 -> null；
  v0.62 风格的缺键载荷 -> null（不解码失败、不替服务端编一句话）；清单外的未知分类原样
  保留；显式 null -> null。
- DocumentChipTest +5：reason 带进模型；句中标点与换行原样、只去首尾空白；空白串 ->
  null；绝不进芯片副行（detail 逐字不变）；待发附件恒为 null。
- DocumentPreviewTest +7：reason 逐字成为正文区那句话（含未知分类，不丢不改不换兜底）；
  只 trim 一次再原样显示；缺席时与改前逐字相同（拿 refusalMessage 对比）；
  空白 reason 不改任何行为；text mime + reason 不再假装有正文。
- assembleDebug 通过；testDebugUnitTest 848 个测试 0 失败 0 错误 0 跳过。

已知代价（已写进 KDoc，供人拍板）
服务端判为读不到、但字节其实下得动的附件（例如超限的纯文本）会失去 App 内预览，
「用其它应用打开」与「保存到下载目录」两条出口照旧完整可用——与「未知 mime 判为非文本」
是同一笔不对称账。
 2026-10-04 21:57:14 +08:00