0e834fc8549f546ef43433da9dcca3307db261fb
6
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 AskaEth
|
2fbf24a675 |
feat(voice): 接收侧语音消息 —— 显示 + 播放（W62 / 契约 v0.79 §4.4 与 §1.2 U19）
别的客户端（QQ / 微信）发来的语音，现在能正确显示并播放。只做接收侧，不做本端录音/发送。
契约口径（逐条落地，不自己发明键名）：
- **判据 = `voice` 键存在**：绝不从 `content` 正文里认媒体类型（`[语音]` 占位标记自 v0.67 起不再
下发，正文里也可能有用户自己打的同样字样）；
- **按 `status` 分支**（`transcribed` / `empty` / `failed` 三态），正文一律照常显示、一个字不改；
- **`name` / `mime` / `size` / `url` 四者同生共死** ⇒ 凑不齐就**不画播放控件**（不给必然失败的按钮）；
- **`durationMs` 缺席就不显示时长**（不反算、不显示 `0:00` 冒充）；
- **不在 WS 实时帧上等 `voice`**（覆盖率：只有四个 REST 读取面填充）—— 实时到达的先按普通文本显示，
由既有的「按 id 合并、新到的胜出」在下一次拉取时自动升级成语音气泡（新增单测钉住这条依赖）。
改了什么：
- `VoiceDto`（7 个键逐字照抄）+ `HistoryMessageDto.voice: VoiceDto? = null`（缺席与 null 同一件事）；
- `domain/chat/VoiceMessage.kt`：判据与展示换算的**唯一落点**（`isVoiceMessage` / `voiceAudio` /
`voiceDurationLabel` / `voiceNote` / `voiceMediaUrl` / `voicePlaybackFailureMessage`）；
- `domain/chat/VoicePlayback.kt`：播放通道的纯状态机（Idle / Loading / Playing / Failed），
每次转换都按 `messageId` 比对 ⇒ 迟到回调不许改状态；
- `ui/chat/VoicePlayer.kt`：`android.media.MediaPlayer`（平台 API，**不引任何新依赖**）驱动那条通道，
三处收干净：换目标先停旧、换会话换实例、组合销毁 `onDispose` 释放；
- `ui/chat/VoiceBubble.kt`：`[播放/暂停] 语音 · 时长` + `empty` 那句补充说明 + 失败提示（一行，error 色）；
图标用 AAR 里真实存在的 `MiuixIcons.Play` / `Pause`（extended 包，basic 那 7 枚里没有）；
- `data/api/MediaApi.kt` + `data/repository/VoiceStore.kt`：`GET {当前地址}{voice.url}`（自带的
Bearer + 401 续期走 `ApiClientFactory`），字节落 `cacheDir/media/<存储名>`（复用 `DocumentCache`
的名字判据 / 命中判定 / 原子落盘；**不落 `documents/`**，那是 FileProvider 唯一暴露的根）；
- `MessageBubble` 渲染语音形态；`isContentlessUserMessage` 加一条「语音消息不算什么都没有」
（否则空转写的语音会被扣上「内容没有被传过来」那顶**假**帽子）；
- `devtools/fake-backend/`：新增语音夹具（`__control/messages?voice=&duration=` + 真 2 秒 WAV 的
`/api/v1/media/{name}`）—— 生产库里一条带 `voice` 的真消息都没有，设备验收只能靠造。
为什么这么改：`MediaPlayer` 不 `release()` 会一直占着解码器与音频通路，而语音是唯一「会出声」的
消息形态，生命周期必须有一处说清楚（写在 `VoicePlayer` 的 KDoc）；播放失败必须可见（按钮回未播 +
一行短提示），一条点了没反应的语音在用户眼里就是坏的。
验收：`assembleDebug` 通过；`testDebugUnitTest` 120 suites / 1458 tests / 0 failures / 0 errors
（基线 115 / 1405，新增 5 个套件 53 条）。
|
||
|
AskaEth
|
4c938c7330 |
docs(devtools): 假后端补「主动消息」验收配方（proactive_inject.py + README 场景五）
改了什么： - 新增 devtools/fake-backend/proactive_inject.py：按真后端 SendProactive 的顺序 （先落库、再发帧）造一条主动消息 —— 落一行 assistant 历史行，再广播带同一 id/createdAt 的 proactive_message 帧。--without-id 是另一档（落库失败）：不落行、帧上不带 id。 - README 新增「场景五」：完整命令序列 + 帧形状 + App 侧三条判据；端点速查/形状出处/已知不确定 各补一条。 - 更正两处过时内容：§1 的工作目录还是旧 worktree 名 Cyrene-Android-FB；§8 说「客户端 W41 起先探 /health」——W45 已把那整套删掉（SendFallback.kt:120），这个端点客户端不再消费。 - 记录踩到的坑：ws_probe.py --listen N 单独用只有 1 秒（ws_probe.py:201 是 min(listen, 1.0)）， 不带 --send/--ping 时连接会先关掉，之后所有广播都是 delivered=0。 为什么： - 真后端没有任何 HTTP 入口能按需触发一次主动推送（backthink 只由心跳/事件决定，路由里只有一个 GET /admin/backthink），所以「她主动说的话」在客户端这一段的验收只能自己造帧。真后端只把 proactive_message 广播给在线连接、没有离线补发，帧壳又不带 sessionId（客户端必须自己钉主会话） —— 形状抄错或漏掉落库那条腿，验出来的结论就是假的。落成脚本 + 文档，下次不必重推。 |
||
|
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。 |
||
|
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，否则本机跑假后端时这条阶梯会退化成直接排队。 |
||
|
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 节，并在开关表、控制端点表、记录文件节、已知不确定节各补了对应内容。
|
||
|
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 均正常。
|