AskaEth/Cyrene-For-Android
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
316 Commits 3 Branches 5 Tags
8babd1d2bb14f543581b3c7a5ea6ecc0b098b385
Commit Graph
7 Commits
Author SHA1 Message Date
AskaEth 8babd1d2bb W76：把「分享批量投递零声明」提成可单测的纯函数 + 假后端 http.jsonl 记请求体摘要 
两件事都是为了让「分享 3 张图 = 3 条消息、零 interrupt」这条结论有据可查——
一条是代码侧的构造性保证，一条是设备侧的证据工具。

1) ShareRules.declaresSendPreference(fromShare, index)（纯函数）
   「这一次投递要不要按『她忙时发消息』偏好声明 interrupt / parallel」原先分在两处手写：
   ChatViewModel.sendShared 传 false、emitPlannedMessages 里 && index == 0。两处各是半个判据、
   一处都单测不到，而这条边界正是 W25 修掉的「分享多图自相打断」（第 2 张把第 1 张刚起的回合
   打掉，见 02 的 F4 与 05 那一节）。提成一处判据后语义不变，穷举整批（0..MAX_IMAGES-1 及越界）
   由 ShareSendDeclarationTest 钉住：分享恒 false、手打只在第 0 条 true。
   ChatViewModel 不在本次 scope，接线那一行没动（已作为 finding 上报，纯函数暂为唯一出处）。

2) 假后端 out/http.jsonl 记请求体摘要（不只是 headers）
   分享多图走 REST 不走 WS（ChatSendRouting.channelFor：hasImage ⇒ Rest），所以「发了几条、
   每条带的是正文还是图、有没有 parallel」只能从 HTTP 流水里读。此前它只记 headers，
   现在加 body 摘要：结构照留（键 / 布尔 / 数组长度），超过 200 字符的字符串换成 <N chars>，
   非 JSON 记 {bytes, note}——图片的 base64 只留长度，不会把一行撑到几 MB。
   _read_body 顺带加了缓存：body 只能从 rfile 读一次，先记录再让 handler 读会得到空串。

assembleDebug + testDebugUnitTest 全绿：1674 测试 / 0 失败 / 0 错误 / 0 跳过（134 个测试类）。
 2026-10-26 22:17:44 +08:00
AskaEth a94e310cd7 W72 纯附件消息也有气泡外侧时间 
时间原本挂在「这条消息**最后一个有正文的气泡**」外侧（W69），而纯附件消息（`documents`
或 `image` 非空、`content` 为空）解析出来的那个占位气泡 `body` 也是空，`Bubble` 见空
`body` 什么都不画 ⇒ 那条时间**整条没被画出来**（主人 2026-10-07 验收 W69 时发现的缺口）。

- 判据抽成纯函数 `messageTimeCarrier(message, bubbles)`：先找最后一个有正文的气泡（W69
  原本那一档，一个字都不改）；一个都没有时按「谁最后画」往回退（语音形态 → 图片 →
  附件芯片排），落点用 `MessageTimeCarrier` 表示。真的空气泡（`isContentlessUserMessage`）
  仍由 `ContentlessNote` 那条路自己画时间，与 W69 一致，未改。
- 附件芯片排 / 图片 / 语音形态三块改为经 `BubbleWithTime` 渲染：**不是落点时 `time = null`，
  连 `Box` 都不建** ⇒ 与 W69 之前逐像素相同。贴哪一侧、宽度预扣（时间不参与 weight）、
  底对齐全部复用 W69 那一个组件，没有第二份布局逻辑。
- 新增 `MessageTimeCarrierTest` 11 条：纯附件 / 纯图片 / 无转写语音 / 角色无关 /
  多块时的优先序 / 有正文时 W69 口径不变 / 真空消息返回 null；`MessageTimeLabelTest`
  16 条一条未动。
- 假后端补夹具：`/__control/messages` 的 `text=`（**空串** = 这条没有正文）与 `documents=`
  （`extracted` / `listed` / `unreadable`）。此前「纯附件消息」在本机**根本造不出来**
  ——工具不实现 upload 摄取链路，`PATCH` 又要求 `content` 非空——设备验收因此无从做起。
  README 补 §8.3 与端点表。

验收：`assembleDebug` 通过；`testDebugUnitTest` **129 suites / 1636 tests / 0 failures /
0 errors**（基线 128 / 1625）。
 2026-10-07 19:16:25 +08:00
AskaEth e962489520 feat(preview): 预览内容下方加一行格式元数据（行数 / 编码 / 分辨率 / EXIF 拍摄日期） 
主人要的是「在预览界面下方拿小字放一点简要的格式元数据」。组装全收进一个纯函数
（`PreviewMetadata`，36 档穷举单测），两个预览弹层只负责取证据 + 画一行
（`footnote2` + `onSurfaceVariantSummary`，与项目里 footer / 角标同一套）。

- **文本 / Markdown**：行数（从正文重算；本端被截断时报「显示 N 行 / 共 M 行」，只说
  「显示 N 行」会让人以为文件就这么长）· 字符数（服务端 `chars` 在时报它并写明
  「服务端注入口径」，否则报本端码点数并写明「本端预览内容」——两个数不是一回事）·
  `UTF-8（本端解码口径）`（**只敢写本端口径**：客户端拿不到文件的真实编码，裸写一个
  UTF-8 等于替文件下结论）· 服务端 `truncated` 时「正文被截断（进上下文的部分）」。
- **图片**：格式（复用 `ImageOpenTypes.openType`，退化成「图片通配」时**整项不报**）·
  分辨率（`BitmapFactory.Options(inJustDecodeBounds = true)`，不整图解码）· 体积 ·
  「拍摄于 …」（`android.media.ExifInterface(InputStream)`，系统 API，**不引新依赖**；
  日期严格校验，`0000:00:00 00:00:00` 这类占位符判非法 ⇒ 整项缺席）。
- **非文本（PDF 这类）**：只有服务端字节嗅探所得的 mime。体积 / 服务端状态 / 「读不到」的
  原因原话各自已经在芯片行与正文区那句人话里，**不在这里重复**——宁可少一项，不要一句废话。
- **拿不到的项一律缺席**：不留占位符、不写「未知」、不写 `--`；一项证据都没有就整行不画。

`devtools/fake-backend` 补一个 `image_file` 灌图参数：服务端库里没有任何带 `image` 键的
历史消息可灌，而相册选择器会把选中项**转码**、把 EXIF 丢掉（实测：41 KB 带 EXIF 的 JPEG
经它拿到手变成 23 KB 且没有 APP1），没有它「拍摄日期」这一项在设备上根本验不到。

验收：`assembleDebug` 通过；`testDebugUnitTest` **127 suites / 1600 tests / 0 failures /
0 errors**（基线 126 / 1564，新增 36 条）；真机（emulator-5554, API 37）实测：文本那条看到
「5 行 · 70 字（本端预览内容） · UTF-8（本端解码口径）」，图片那条看到
「image/jpeg · 1280 × 720 · 23.0 KB」（该源图不含 EXIF，所以「拍摄于」这一项按设计缺席）。
 2026-10-07 19:07:00 +08:00
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 条）。
 2026-10-07 11:14:28 +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 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 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