AskaEth/Cyrene-For-Android
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Compare commits

base: AskaEth/Cyrene-For-Android:Alpha_v0.1.0
AskaEth/Cyrene-For-Android:main AskaEth/Cyrene-For-Android:android AskaEth/Cyrene-For-Android:dev
AskaEth/Cyrene-For-Android:Alpha_v0.1.0_4 AskaEth/Cyrene-For-Android:Alpha_v0.1.0_3 AskaEth/Cyrene-For-Android:Alpha_v0.1.0_2 AskaEth/Cyrene-For-Android:Alpha_v0.1.0_1 AskaEth/Cyrene-For-Android:Alpha_v0.1.0
..
compare: AskaEth/Cyrene-For-Android:aace581fb0a9a29cdf2d743d76686d896b88e466
AskaEth/Cyrene-For-Android:android AskaEth/Cyrene-For-Android:dev AskaEth/Cyrene-For-Android:main
AskaEth/Cyrene-For-Android:Alpha_v0.1.0_4 AskaEth/Cyrene-For-Android:Alpha_v0.1.0_3 AskaEth/Cyrene-For-Android:Alpha_v0.1.0_2 AskaEth/Cyrene-For-Android:Alpha_v0.1.0_1 AskaEth/Cyrene-For-Android:Alpha_v0.1.0
229 Commits
Alpha_v0.1.0 .. aace581fb0
Author SHA1 Message Date
AskaEth aace581fb0 merge: W52C —— 退出登录从小图标按钮改成带文字的危险行条目，图标换 Remove 2026-10-06 15:50:31 +08:00
AskaEth 27116fa434 merge: W52DE —— 降级气泡不再给删改入口（proactive-local: 前缀屏蔽服务端动作）；空态补一枚显式「重试」 2026-10-06 15:50:30 +08:00
AskaEth 85818105ce feat(settings): 退出登录从小图标按钮改成带文字的危险行条目，图标换 Remove（W52C） 
设置页最底部原来是一枚居中、无文字的图标按钮，图标用的还是「返回」箭头（MiuixIcons.Back），
真机上看着就是返回键——主人为此翻半天才找到登出在哪。这是本次改动的由来。

- 改成 Miuix 行条目（BasicComponent + 外层 PreferenceCard，与同页其它条目同形），文字「退出登录」，
  标题与图标都用 MiuixTheme.colorScheme.error 危险色。
- 图标换成 MiuixIcons.Remove：Miuix 里没有专门的登出/退出字形（Basic 只有 7 个图标），
  extended 里只有它画的是「箭头离开方框」，语义最接近「退出」；Back 是本条要修的毛病，
  Import 方向相反（箭头进方框＝导入/登录），Delete/Refresh 之类会被误读成删号或重来。
- 图标 contentDescription 置 null：文字已经把这条读出来了，图标再报一遍只会让读屏重复。

行为一字不变：仍然点了就登出（onLogout 一路接到 CyreneApp 里的 authManager.logout()），
没有新增确认流程。
 2026-10-06 15:48:54 +08:00
AskaEth 74a46bd2e3 fix(chat): 降级气泡不再给删改入口（W52/D）；空态补一枚显式「重试」（W52/E） 
## D —— W50 留下的窄尾巴：服务端不存在的那条气泡没有动作入口

`proactive_message` 落库失败那一档，客户端会画一条**只活在本端内存里**的气泡，它的 id 由本端自铸
（`proactive-local:` 前缀，见 `ProactiveIngest`）。而删除入口的判据 `canDeleteMessage` 只看 role ⇒
它是 assistant 行、长按能删 ⇒ 拿一个服务端没见过的 id 打 `DELETE`，最好的结果是 404。

修法按主人拍的口径收在 **UI 层**：新增 `ui/chat/MessageServerActions.kt`，在角色口径之上再叠一道
「这条消息在服务端存在吗」（判据只有 `id` 前缀这一条），组合成
`canEditMessageOnServer` / `canDeleteMessageOnServer`；气泡（菜单 + 「⋯」两个入口）与 VM 里那道闸
（`startEdit` / `startDelete`）**共用同一份**，不存在两套口径。
- **不动** `ChatDisplayItem`、数据模型与 `mergeMessages` 语义（原方案要加「是否服务端行」标志位，
  会连带动气泡渲染，超出范围）。
- 动作菜单里**只有**编辑与删除两个（一个 PATCH、一个 DELETE），都是打服务端的 ⇒ 降级气泡整菜单不出现，
  正是要的效果。**文本选择 / 复制不受影响**：它走 `SelectionContainer` 那条独立的路，`onLongPress`
  为 null 时反而不再与选字抢长按。

## E —— 首屏失败时给一个显式「重试」

登记在案的缺口：**REST 首屏失败、而 WS 从头到尾没断过**。这时没有任何状态变化可挂（连接没变过、
也没有断线窗口要补），屏幕会停在空态，直到用户切走再回来或上拉。

- `ChatViewModel.retryFirstPage()`：**只是转调** W51 提好的 `loadFirstPage()`（首屏唯一的一份实现，
  与连接恢复时补的那一次共用），**一个状态位都不自己写** —— `firstPageState` 的两个出口仍然只有那一处，
  W51 的 `reconnectPull` 判据依赖这条纪律。刻意**不是**定时器：项目从 W38 起就定死「状态驱动，不按时间轮」，
  而且反复重试会把「首屏失败」这个事实擦成 `Loading`。
- 空态那一档拆成两种真相（纯函数 `shouldOfferRetryOnEmpty`：不在加载中 + 挂着一个错误 + 列表为空）：
  「还没有消息」照旧；「消息没能加载出来」配一枚 Miuix `TextButton`（`CenterHint` 多一个可选 `onRetry`）。
  其余时刻一个像素都不多画。

## 测试

- 新增 `MessageServerActionsTest`（6 条）：钉住降级气泡两个入口都没有（并断言**旧判据确实说「能删」**，
  把「为什么需要这道闸」写进断言）、前缀与角色无关、只认**开头**的前缀、服务端行行为逐字不变、
  未知 role 仍 fail-closed。
- 新增 `FirstPageRetryTest`（5 条）：正题一格成立；正常空会话 / 首屏在飞 / 屏幕上有东西（含乐观与流式气泡）
  都不给；三个布尔八种组合穷举，钉住「有且只有一格成立」。
- `./gradlew.bat --console=plain assembleDebug testDebugUnitTest`：**95 suite / 1216 tests / 0 失败 / 0 error**
  （基线 93 / 1205，+2 suite +11 tests，全为新增）。
- 真机验收未做（任务书禁碰 adb）：按钮的位置与观感、以及长按降级气泡能选字，只能真机看。
 2026-10-06 15:47:49 +08:00
AskaEth d0b8c5f2f7 docs(05): 写死纪律——不准用 WaitFor 等子代理（会把回合锁住，主人无法插话） 
为什么：主人当场打断我的 WaitFor 并明确「纪律是不准用 WaitFor」。这条在后端仓库 AGENTS.md §10 里原本
就有，本项目文档此前没写、我因此重犯了一次。正确做法：派完就结束回合，等待期间只做不冲突的并行工作
或停手。
 2026-10-06 15:46:40 +08:00
AskaEth 4fce12249e docs(05): S7② 与 S3 的真机验收结清（S7② 通过；S3 在「在线冷启动进有内容次级会话」场景下否证） 
S7②（通过）：补洞请求打在已摘除的会话上 ⇒ 404 ⇒ sessionGone；那句 8 秒的告知抓到（[33,378][1047,480]）；
select(主会话) 的副作用 POST /sessions/web/read 两轮都观测到。⚠️ 同时**修正我自己写的判据**：原先要求
「read 出现在 GET /sessions 之前」——实测顺序不确定（两条协程各起），该顺序判据不成立；真正该验的
「refresh 失败时也能回去」本轮没做。

S3（否证）：screenrecord + ffmpeg fps=8 抽帧 + 逐帧量两块区域的深色墨迹（不改生产代码）。时间线是
启动画面（新版图标）→ 「加载中…」 → 内容，**没有出现「还没有消息」空态**。局限：8fps 采样（<125ms
的闪烁会漏）、单场景、单 build，不写成「S3 不存在」。

方法论：别用墨迹的 x 宽度猜那是哪句话——我一开始据此误判，抽帧一看是「加载中…」。
 2026-10-06 14:24:45 +08:00
AskaEth 9f04fc4304 docs(05): S7②/S3 第二轮受阻记录 —— 模拟器劣化与主机被占、不依赖 dump 的验证套路、收工状态 
为什么：这一轮 S7② 仍未验（进次级会话那一步没成），但花掉的时间都是环境问题而非代码问题，
必须把「先看主机在跑什么」「盲点 + 用服务端流水判结果」这两条写下来，下一轮别再重摸。
 2026-10-06 14:16:55 +08:00
AskaEth 0583b1bc31 docs(05): 补记 S7② 为什么这轮没验成 + 下次的干净起手（含判据与两个坑：表单错位、dump 陈旧缓存） 
为什么：S7② 需要「App 停在已删会话里」才能造场景，而登录表单被前几轮实验搞乱（地址栏残留 W48 的
坏值、字段错位），input text 落不进目标字段；uiautomator dump 还会返回陈旧缓存（同一交互前后两张
dump 的地址栏展开态互相矛盾）。把判据与干净起手写下来，下一轮别再重摸。
 2026-10-06 13:57:53 +08:00
AskaEth b604fefbd4 docs(05): 锚点补记二十九 —— W51 合并、S2/S7① 设备验收结论，并更正补记十九里 S7 那句写错的前提 
改了什么：
- 新增锚点补记二十九：W51 做了什么（S2 的纯判据与「首屏从没成功过」这个判据为什么这么定、S7① 的
  GoneSessions、S7② 真正的缺口是「出路不能依赖网络」）；设备验收结论（S2 通过：恢复网络后客户端自己
  补拉并显示出消息；S7① 通过：删掉会话后真踢一次 WS，重连窗口里没有注定 404 的补拉，而握手证明通路
  活着）；以及 S3 / S7② **未验**（如实写明，不写成「没问题」）。
- 更正补记十九里 S7 那句「`sessionGone` 位没有消费者」：消费者一直都在（ChatScreen.kt:165-166 →
  ChatHomeScreen.kt:109 的 onSessionGone），由 b5c0b13（2026-10-04、该行所依据提交 ff699f5 的祖先）
  引入，已用 git merge-base --is-ancestor 验证。这句是我写错的，W51 的任务书因此也带着错前提。
- 记下这次同类教训（第二次）：真机「没生效」时**先核设备上 APK 的 lastUpdateTime 与本地 APK 的时间**
  —— 我就是拿上一版 APK 测了半天；另记「撤 adb reverse 不会掐断已建立连接，要真抖 WS 用假后端的
  /__control/ws-close」。
 2026-10-06 09:20:40 +08:00
AskaEth 620a4e77fa merge: W51 —— 次级会话连接恢复自己补拉（S2）；已删会话不再发注定 404 的补拉、sessionGone 的出路不再依赖网络（S7） 2026-10-06 09:04:09 +08:00
AskaEth 9980fb2b28 fix(chat): 次级会话补上「连接恢复自己补拉」（S2）；已删会话不再发注定 404 的补拉（S7） 
## S2 —— 次级会话没有握手 history 这第二条安全网

- 新增纯判据 `ui/chat/ReconnectPull.kt`：连接恢复那一刻该补哪一段
  （Forward / FirstPage / Nothing）。判据只看四样：会话 id、首屏状态、掉线游标、
  「本端已知它没了」。
- `ChatViewModel`：把 init 那次首屏 `loadLatest` 提成 `loadFirstPage()`，init 与补拉
  **共用一份代码**（补出来的结果必须与首屏逐字段同形）；新增 `FirstPageState` 作为判据输入。

为什么这么定：
- **为什么不是照抄主会话的 history**：服务端固定回放主会话（`ws_hub_conn.go`），要它回放
  次级会话就是改契约面。次级走的是本项目已有的那条 REST 口径（拉最新一页）。
- **为什么用「首屏从没成功过」而不是「本端有没有数据」**：服务端真的没有消息时列表**也是空的**，
  拿空列表当判据会让每一个空次级会话在每次重连都被整表重拉 —— 那正是 S4/S7 这一类问题的成因。
- **为什么 Loading 不算失败**：首屏还在飞时再发一次同样的请求会与它抢跑，还会改掉
  「history 帧一到就 loading=false」那段时序（S3 本轮**一个字节都不动**）。
- **为什么主会话排除在外**：它有 history 兜底，在那里再补一条 REST 就是给同一件事造第二套口径。
  主会话的兜底行为因此**逐字不变**（有洞走 Forward，其余 Nothing）。
- 补拉那一次把 `loading` 翻回真：屏幕上原本是「还没有消息」停在原地，如实应该是「加载中…」。

## S7 ① —— 注定 404 的补拉不再发生

- 新增 `core/session/GoneSessions.kt`（进程级、**不持久化**、登出/换账号时清空）：本端已知
  「服务端没有这个会话」的 id 集合。写入口是 `SessionsViewModel.deleteSession` 成功那一刻
  （本端唯一的删除入口），读入口是**每一个** `ChatViewModel`。
- 判据第 1 条：已知它没了 ⇒ 什么都不发。于是本地删过的会话从此**零次**注定失败的往返；
  已经 404 过的会话从「每次重连各撞一次」收敛成**恰好一次**（`sessionGone` 同时成为补拉的闸）。

## S7 ② —— sessionGone 的出路不再依赖网络

那个位的消费者**一直都在**（`ChatScreen` 按它触发的 `LaunchedEffect` → `ChatHomeScreen` 的
`onSessionGone`：一句如实告知 + 带回主会话），所以本轮补的是它真正的缺口 —— 原来只靠 `refresh`
**成功**之后的 `resolveActiveSession` 回落（拉失败、或列表为空时刻意不回落 ⇒ 什么都不动）。
于是「已切回主会话」在网络不稳 / 服务端抖一下时是一句**做不到的话**，用户被留在已经没了的会话上、
没有任何出路。现在先在本端 `select(主会话)`（与用户点抽屉里那一行走的是**同一条**路，不另造机制），
`refresh` 退回本职：与服务端对齐、把抽屉里那条去掉。

## 未做 / 未验

- **没有真机验收**（任务书禁碰 adb）：S2 的「连接恢复后次级会话自己补上」只有纯判据单测。
- 「REST 首屏失败、但 WS 从头到尾没断（因此没有任何状态变化可挂）」这一格**不在本轮范围内**，
  仍是已知缺口。
- 全程未碰 S3、主会话兜底与游标口径、W48 的 VM key、W49 的节流判据、W50 的主动消息消费路径。
 2026-10-06 09:03:22 +08:00
AskaEth a9cc3c5737 chore(gitignore): 忽略仓库根的 IMG_*.png（主人从手机丢进来的素材，只用不存） 
为什么：主人明确「原图不进仓库」——换图标用的 IMG_20261006_081803.png（5.8MB）留在工作树即可，
加一条只作用于仓库根的忽略规则挡住误提交（只挡 IMG_*.png，不影响别处的图片资源）。
 2026-10-06 08:57:27 +08:00
AskaEth a025624798 feat(icon): 应用图标换成主人提供的新版画作（昔涟特写） 
改了什么：
- mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/ic_launcher.png：新画作按 48/72/96/144/192 缩放（lanczos）。
- 同目录 ic_launcher_round.png：同一画作按圆形 alpha 掩膜裁出（ffmpeg geq），供圆形掩膜的启动器。
- 同目录 ic_launcher_foreground.png：自适应图标前景按 108dp 画布全出血（108/162/216/324/432 像素）。
  第一版把画心缩到 76/108，实测在这台启动器上会露出背景一圈；改成铺满画布后任何掩膜下都不会露底。
- values/colors.xml：ic_launcher_background #F8F8F8 → #FFE6E0（用 ffmpeg 对源图左上角 300×300 取平均色得到，
  与画作底色同调；前景已铺满，这个底色只在极端掩膜下才可能露出）。

为什么：主人把新版图标源图放在仓库根（IMG_20261006_081803.png，5033×5033、5.8MB），要求替换应用图标。
**源图不进仓**（仍是未跟踪状态），只提交生成物；构建与安装均通过，实机底栏图标已是新版。
 2026-10-06 08:30:53 +08:00
AskaEth 1d150cce85 docs(02): 客户端答复 —— 回执二十四·补：①推迟照办、②未读口径确认（维持 omitempty）、两条澄清，并反问 .end 能否带结果摘要 
改了什么（只加了我们这一节，未碰他们那一节）：
- ① 工具回看面推迟：照办。明确写死两条口径——不把「toolCalls[] 缺席」当「这轮没调工具」；
  不再按消息字面 join turnId（两者不是同一套标识）。也说明我们**不提前写**那个解析器。
- ② 未读面：回答他们的问题——**维持 omitempty 即可**，因为对我们权威来源是列表面（GET /sessions 恒带
  unreadCount），增量键只是省一次重拉的优化；接入口径按他们说的「键在才改、缺席什么都不做」。
  同时如实说明本端**还没消费**这个键（今天走的是 W49 的重拉，已实机验收），免得他们误以为已生效。
- 两条澄清：GET /api/v1/messages/{id} 我们从未用过（只有 PATCH/DELETE，SessionsApi.kt:130,137）；
  tool_execution (a) 维持收到。
- 反问一件与回看面无关的事：能否给 tool_execution.end 加可选 resultSummary（截断、缺席语义）——
  因为 .end 只带 tool/phase/id、update 又没有生产者，实时工具卡的结果区结构性为空；这是投入最小的一条。
  明确说「不做也接受，但请明说」，我们要的是确定而不是一定要这个键。
- 告知 W50/W48/W49 已落地并实机验收（不需要他们动作）。

为什么：他们那条回执标红了「别把缺席当没调过」，并直接问我们要不要区分「确实 0 / 不知道」——
这两个都是会决定他们改不改代码的问题，必须当场答清。
 2026-10-06 08:24:50 +08:00
AskaEth b23948bed0 docs(05/07): 锚点补记二十八 —— W48/W49 设备验收通过（换环境串味 / 抽屉未读角标） 
改了什么：
- 05 新增锚点补记二十八：W48 的判别法（先清空服务端主会话再换账号，否则两账号同一份历史看不出串味）与结果
  （A 的本地气泡与持久行在 B 账号下都 0 次、抽屉残留 0 次）；W49 的机制证据（抽屉关着时客户端自己在
  消息到达后 60ms 发出 GET /api/v1/sessions）与可见结果（次级会话行 未读 1、正在看的主会话无角标）；
  并更正一处认知：红点是抽屉内会话行的未读角标，菜单图标上没有点。
- 07 的坑清单补两条：① 登录页地址栏留空时 App 会回落到上次记住的地址（我因此白追一小时「请求怎么打到
  真后端」）；②「登出」是设置页最底部的图标按钮（图标是 MiuixIcons.Back、只有 contentDescription），
  截图上像「返回」很难找。

为什么：这批验收原来只有单测覆盖，结清后 05 的待办里不再挂着它；两条坑都是这次真实花掉时间的，
写下来避免下次重演。
 2026-10-06 08:24:00 +08:00
AskaEth c905a47d6f docs(05/07): 锚点补记二十七 —— W50 落地并设备验收通过；细节单开 07（证据与避坑） 
改了什么：
- 05 新增锚点补记二十七：结论（afee5f6 已推 / 1193 测试真跑 0 失败 / APK 尺寸）、四条硬要求逐条
  对应实现处、红线核对、设备四条判据全绿、环境坑一句话版、真后端那条主动路径是活的（副产品）、
  待办变化（W48/W49 验收环境已就绪；W50 的窄尾巴）。
- 新增 devdocs/07-W50-主动消息-验收与避坑.md：验收判据与逐条证据、完整环境坑（含绕法与命令）、
  复现整套验收的最短路径、随批次修掉的 timestamp 解码缺陷、以及「落库失败档」那条尾巴的收口建议。

为什么单开 07：05 已 1400+ 行，验收的操作细节与避坑属参考材料而非状态；05 只留结论与指针，
下一个我读 05 就能接手，需要动手复现时再翻 07。
 2026-10-06 08:11:26 +08:00
AskaEth afee5f612d merge: W50 —— 她主动说的话实时进主会话（proactive_message 消费 + 帧解码修复 timestamp 类型不符） 2026-10-06 07:51:26 +08:00
AskaEth 8b5d15bdb6 fix(chat): 她主动说的话实时进主会话（W50 proactive_message 消费 + 帧解码修复） 
缺口：她主动说的话既是实时帧、也是主会话历史里的一条 assistant 行，而安卓端实时看不到 ——
ChatViewModel.onEvent 里没有 ProactiveMessage 分支（落到 else -> Unit），另两个下行消费者也不认它；
而且帧里只解了 messageId（IM 侧的号），落库行的 id / createdAt 被 ignoreUnknownKeys 静默丢弃。
后端这条 Web 路由只发这一帧、不补 message_persisted，所以没有别的路能把它带进来。

一、帧解码（data/ws/WsEvent.kt）
- ProactiveData 与 ProactiveMessage 补上 id 与 createdAt（落库行的权威 id 与时间戳，同现同省）。
- 顺带修掉一个把整帧弄没的缺陷：载荷里的 timestamp 服务端是 Go time.Time，线上是 RFC3339 字符串，
  而本端按 Long? 解 ⇒ 解码抛异常、被 parse 的 runCatching 吞成 null，帧在成形之前就没了
  （所以只加一条 onEvent 分支根本碰不到它）。改成按线上的字面量收，数字形状也照样读出。

二、为什么按已落库行并入，而不是画一个只活在 UI 的气泡
真相是服务端历史里的那一行，实时帧只是它早到一步的副本：按 HistoryMessageDto.id 走既有的
mergeMessages 并入 ⇒ 实时能看到，且刷新 / 重开 / 切会话拉历史之后她的话仍在；同一条
（实时帧 + 握手回放 + 分页）无论到几次都只有一行，不需要任何额外去重。
判据抽成纯函数 proactiveIngestFor（ui/chat/ProactiveIngest.kt），可单测。

三、为什么必须自己钉死主会话
proactive_message 帧壳不带 sessionId（服务端构造这一帧时没设它，且该键是 omitempty），
而 isForSession 对空 sessionId 的口径是放行 ⇒ 这一帧会投给每一个活着的 ChatViewModel。
不钉就会在每个次级会话里都冒出一条她的话（比看不到更糟）。判据是等值比较、不是前缀：
主会话 web 与次级会话 web:xxx 是两个会话。

四、无 id 时为什么退化而不是丢弃
id 与 createdAt 一起缺席 = 服务端那一步落库失败了（它自己就说了这条没有历史行）。这时画一条
本地气泡，如实显示、不假装已落库：本地 id 用帧里已有的稳定键（IM 消息号，其次时间字面量），
同一个键第二次到达（重推 / 重放）也只是 upsert，不会成两个气泡。KDoc 写明它不在历史里、
刷新 / 重开后不会再有。
无 id 且无正文（帧里没有任何可显示的东西）才整帧跳过 —— 那一条画的是空气泡，只会让人以为出了别的事。

五、抽屉红点（复用 W49 那条路，不新写取数路径）
服务端不为这条路补 message_persisted ⇒ W49 的「非激活会话落新消息 ⇒ 节流静默重拉」不会被触发，
主会话的红点会停在她开口之前。SessionsViewModel 用同一个 persistedRoute 把这一帧接进同一条路
（复用 requestSilentRefresh 与既有的 InactiveSessionMessage 成因，不动节流判据本身）：
停在别的会话 ⇒ 节流静默重拉一次（红点亮）；正看着主会话 ⇒ 与 message_persisted 同一档
「看到即已读」，免得抽屉为她刚说的话亮一个红点。无 id 那一档不拉（历史里没有行，未读面上无事可做）。

测试
- 新增 WsEventProactiveFrameTest：真实帧形状（id / createdAt / RFC3339 的 timestamp）、数字形状容忍、
  落库失败那一档、以及「帧壳没有 sessionId ⇒ 会话闸对每个会话的 VM 都放行」这条事实。
- 新增 ProactiveIngestTest：归属（次级会话不并入、id 按等值比）、身份（有 id = 已落库行）、
  退化（本地气泡 / 空帧跳过）、不重复（重发与历史页都收敛成一行）。
- InactiveSessionPullTest 补一条钉子：她主动说的话该走拉列表还是「看到即已读」这条路。
 2026-10-06 07:50:33 +08:00
AskaEth 5520d6015d docs(05): 更正代理旧路径引用（工具已在 devtools/ws-block-proxy/，历史条目不改写） 2026-10-06 07:45:31 +08:00
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（客户端必须自己钉主会话）
  —— 形状抄错或漏掉落库那条腿，验出来的结论就是假的。落成脚本 + 文档，下次不必重推。
 2026-10-06 07:44:31 +08:00
AskaEth d9b7c22ecb docs(05): 锚点补记二十六——续接锚点（现状/环境/设备驱动协议/W50 在飞与合并检查清单/W38~W49 索引/待办排序/与后端状态/方法论教训），供下一会话直接接手 2026-10-06 07:38:29 +08:00
AskaEth d5d2feee36 docs(05): 锚点补记二十五——W48（账号指纹进 VM key 修 S1 + 搜索 VM 同类缺陷 + 5 处错注释 + 代理挪进 devtools）与 W49（非激活会话节流静默重拉修 S6，3 秒窗口 + 结构性 trailing + 一处刻意偏差）落地；合并后 1177 测试全绿 2026-10-05 22:30:08 +08:00
AskaEth 5dc6408bb9 merge: W49 —— 非激活会话落新消息时节流静默重拉（3 秒窗口 + 结构性 trailing），让抽屉红点在不开抽屉时也能出现 2026-10-05 22:28:39 +08:00
AskaEth 93cf3e359a fix(sessions): 非激活会话落新消息时自愈式节流重拉，抽屉红点不再等用户开一次抽屉（S6） 
现象：App 停在主会话时，次级会话落了新消息 ⇒ 抽屉红点不出现，必须打开一次抽屉
（那次静默 refresh）才补上。

根因：message_persisted 只在 sessionId == activeSessionId 时才推进 / 更新，非激活
会话那一帧直接 return；而会话列表更新的触发点此前只有抽屉打开 / 新建 / 删除 / init
四处，于是「别的会话攒了新消息」没有任何人会去发现。

为什么是客户端自愈而不是等后端：这一帧不带 unreadCount（契约面缺一个增量），而本端
没有逐条时间线 —— 自己累加出来的数会与编辑 / 删除 / 别端操作漂移，那是造数不是修复。
帧壳本身已经说清「某个会话有新消息落库」这件事，所以本端只是据此去问一次服务端，
走的是与抽屉打开时那次完全相同的路径（refresh(silent = true)，含已读游标遮罩），
只是不需要用户先开一次抽屉。后端把增量补上之后这条路可以退成不必走，但在此之前它
是唯一能把红点点亮的路。

节流窗口 3 秒，理由：
- 够快：3 秒落在「看起来就是刚发生的」这个感知里；5 秒往上就开始像卡了一下才补上；
- 够粗：一次静默重拉是两个请求（refresh 里还跟着一次角色目录），而播出方是按每条
  消息推帧的 —— 3 秒能把人手连打 5 条（约 2~4 秒）或一轮回复的连续落库收进同一个
  窗口，收到 1 秒就会漏成两三次请求；
- 不另立尺子：3 秒正是本项目已有的「等够久才值得为一次等待开口」那个量级
  （ChatScreen 的 SHARE_WAIT_NOTICE_MILLIS）。

trailing 怎么保证：窗口内的第二条起不拉，但排一次「窗口到点补拉」（等待时长 =
窗口 - 已过时间），到点直接拉一次并把窗口重开；同一时刻最多一个补拉任务（已排上时
后续成因只更新账本、不重排），所以最后一条之后必定还会再拉一次，红点不会停在旧值。
另外「正好等于窗口」算窗口已过（>= 而不是 >），补拉到点那一刻不会被自己刚开的窗口
挡回去。

哪几种情况不拉：当前打开的那个会话落新消息（那条路本来就有「看到即已读」，多拉一次
列表就是白花两个请求）；同一窗口内的后续消息；窗口内且补拉已经排上。另外切会话那条
路刻意不接进来 —— select 紧接着就发推进已读游标的请求，此时重拉会与还没落地的游标
抢跑、把刚清掉的角标闪回来（抽屉打开时那一次紧跟在游标之后，本来就会补上这一拉）。

判据抽成纯函数（新增 InactiveSessionPull.kt）：persistedRoute 决定这一帧走哪条路，
silentRefreshStep 决定这一刻该不该拉、拉完账本怎么走；时钟由调用方喂，不用 sleep
也就能穷举边界。

顺带把身份变化（重登成另一个账号 / 换了服务器地址）也接进这条路径，用 ContextChanged
绕过节流窗口 —— 那份列表换了主人，等满一个为「别的会话又攒了几条」而设的窗口没有
道理；登出时把账本与补拉任务一起作废（否则补拉会带着一个已经没有令牌的身份发请求）。
抽屉打开时那次 refresh、activeSessionId 的推进、已读游标的既有行为都没动。

验证：gradlew.bat assembleDebug testDebugUnitTest —— BUILD SUCCESSFUL；
1171 条单测 failures 0 / errors 0 / skipped 0，其中新增 InactiveSessionPullTest 13 条。
 2026-10-05 22:28:19 +08:00
AskaEth e589ab303d merge: W48 —— 聊天页 VM key 带上账号指纹（修换环境后仍显示上个环境的会话）+ 注释纠错 + 把 WS 拦截代理挪进 devtools 2026-10-05 22:26:44 +08:00
AskaEth 40dac87dda docs(05): 补记二十四附——本轮两个决定（P1 主动消息消费我方接、tool_execution 选 a 并要 toolCalls[] 回看面带输出）与推送暂不接的口径 2026-10-05 22:26:09 +08:00
AskaEth 766843fdbd docs(02): 客户端答复回执二十二·补的四问——主动消息「不会两次」但真缺口是「我们没消费那帧 ⇒ 实时看不到」；tool_execution 选 (a) 并附取舍；纠正「每屏一条 WS」过时前提；推送暂不接并说明「应用内提示」在客户端零实现 2026-10-05 22:25:59 +08:00
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 a4ac11a1c1 docs(05): 锚点补记二十四——流程教训：动 02 之前除 git status 还要 diff 它最新几十行（我差点在没读后端回执的情况下给后端写信）；并登记后端正在等我们回的四件事与「每屏一条 WS」这个过时前提 2026-10-05 22:23:44 +08:00
AskaEth 7d1c56e03b docs(02): 给后端一份「我方实际依赖的线形状」清单（clientMsgId 幂等是我们敢重发的唯一安全基础、REST stream 回执必须仍是小 JSON、鉴权失败只认 401…）+ 两条已登记缺口的提醒 + 告知客户端已不再调 /health + 提供 CyreneRoute 日志作为联调取证 2026-10-05 22:22:58 +08:00
AskaEth c09c40388b docs(05): 锚点补记二十三——登记在飞的两个 worktree（W48 修 S1+注释纠错+工具归位；W49 修 S6 客户端自愈）与合并纪律 2026-10-05 22:21:49 +08:00
AskaEth 324be57c7a docs(02): 客户端登记——「非激活会话红点不实时增长」缺一个未读增量面（message_persisted 不带 unreadCount），并说明我方先用客户端自愈顶着、它不能替代增量面 2026-10-05 22:21:48 +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
AskaEth a84d473e2f docs: 收下后端回执十（契约 v0.63：documents[].reason + messages 对已删会话回 404）+ 答复 sess-* 提问 + 锚点补记两条新待办 2026-10-04 21:51:08 +08:00
AskaEth 9f92a8ade5 docs(05): 恢复锚点更新 —— 记上凭据落地位置（dev-secrets.local.md，gitignore）、新 HEAD、模拟器启动参数 2026-10-04 21:50:31 +08:00
AskaEth d2169c6174 chore(gitignore): 忽略 dev-secrets.local.md（本机开发凭据，主人授权落地但不进仓库） 2026-10-04 21:48:37 +08:00
AskaEth 92ee7fedbd docs(05): 落「恢复锚点」（当前状态 / 已完成模块清单 / 待办 / 家务）—— 便于上下文压缩后接续 2026-10-04 21:46:56 +08:00
AskaEth 647cf47cf2 docs(05): 更正 ① W16 搜索的结论 —— 本来就是好的，先前「设备上不可用」是我的测量假象（含教训：动代码前先用像素确认症状） 2026-10-04 21:46:26 +08:00
AskaEth 3ff4f45166 docs: 更正文档里的日期标注 —— 本轮都发生在 2026-10-04 深夜，之前误写成 10-05（含后端回执九那一行） 2026-10-04 21:42:37 +08:00
AskaEth c67aa2da48 docs(05): 存档本轮装机验收的设备证据（W18/W15/W19 通过、W16 确认不可用、四条新坑） 2026-10-04 21:41:45 +08:00
AskaEth e8c6389fde docs(02): 收下后端 GC 策略与回复 + 更正 knowledge 工具失败的范围（纯文本也复现）+ 一条 adb reverse 方法论 2026-10-04 21:41:20 +08:00
AskaEth df6378395e merge: W21 — 重试记忆加 10 分钟时间上界（多槽不会跨小时误撞旧键） 2026-10-04 21:40:23 +08:00
AskaEth 8938fffd08 feat(chat): 重试记忆的槽加 10 分钟时间上界 —— 别把用户新打的同内容当成重试 
多槽让失败记录跨很多次发送存活，于是开了个单槽时代没有的窗口：用户几小时前失败过一句
「你好」，之后新打一遍「你好」（心里当的是一条新消息），指纹却与那条旧记录一字不差，
keyFor 命中旧键 ⇒ 服务端回 duplicate ⇒ 这条新消息根本不发出去，屏幕上看着像「按了没反应」。
给每个槽加一道时间上界，窗口就被限死在 10 分钟内；而「刚失败完，用户马上再按一次发送」
这个真正需要幂等的场景一秒都没被削掉。

- RetryKeyMemory: 新增公开常量 SLOT_TTL_MILLIS = 10 分钟（测试拿它做断言，不硬编码）；
  RetryKeySlot 增 atMillis；remember(fingerprint, localId, atMillis) 与
  keyFor(fingerprint, nowMillis, mint) 都在入口先按时间淘汰过期槽、再做自己那件事，
  写入时最后才看条数上限（过期槽不占 8 条的额度）；同指纹重复失败更新键与时刻而不是留两条；
  forget(localId) 与时间无关，签名与行为不变；FIFO 上限 8 与 TTL 两条规则同时生效。
- 边界口径：正好等于 TTL 不算过期（判据是 now - atMillis > TTL，严格大于），理由写在类注释里，
  测试把它钉住。
- ChatViewModel: 只改两个调用点，喂 System.currentTimeMillis()（emitAndDeliver 的 keyFor、
  rememberRetryKey 的 remember；forget 的三处不动），并按新语义更新相关 KDoc。
- RetryKeyMemoryTest: 既有用例补上时刻；新增 7 条覆盖「过期槽不复用且被淘汰」「TTL 边界」
  「remember 刷新时间戳」「过期的 A 不影响新鲜的 B」「TTL 先于 FIFO 上限生效」。
 2026-10-04 21:37:45 +08:00
AskaEth 7a6f6b0863 chore: .gitignore 补 .kotlin/（Kotlin 构建产物，之前没忽略，git add -A 会误扫） 2026-10-04 21:29:14 +08:00
AskaEth ea16f48be2 merge: W19 — 单条消息的编辑与删除（D3） 2026-10-04 21:28:22 +08:00
AskaEth 351891714a feat(chat): 单条消息的编辑与删除（D3） 
契约 §1 行 6a/6b 的两个端点与 §3.8 的两帧，整条链接完（不含「重发」——契约
明确没有重发端点，客户端用编辑后的内容再 POST /chat 即可，本模块不做）。

数据层
- SessionsApi 增 PATCH / DELETE api/v1/messages/{id}（与既有消息端点同源，因此
  MessageRepository 能直接复用、不必动 AppContainer），MessageRepository 增
  editMessage / deleteMessage，走既有 apiCall / Result 风格。
- 响应形状照契约不照旧文：PATCH 的 data 直接就是消息 DTO（没有 message 包一层），
  DELETE 回 {deleted: id}；编辑内容按「非空、≤4000 rune（码点，不是 length）」
  预校验，不合格一个请求都不发。

帧解析
- WsEvent 增 message_edited / message_deleted，形态照 message_persisted 那一套：
  会话归属先取帧壳、其次取消息自身的 sessionId，未知键安全、未知帧与坏帧安静忽略、
  永不抛。
- message_edited 的 data 就是消息本身（与 message_persisted 的 data.message 不同形），
  照抄那一套会解出 null——这一点由单测钉住。

VM
- 按 id 原位改 content / 原位移除。两条路各自只有一个落地出口：本端 PATCH/DELETE 的
  成功回执与随后到达的广播都调同一对纯函数，而它们幂等（同一内容做两次返回同一实例）
  ⇒ 「响应 + 广播」双到达收敛成一次，不需要去重表、也不会出现两套状态源。
- 编辑只对 role == user 开放、删除对 user 与 assistant 都开放，判据是同一份纯函数，
  气泡（隐藏入口）与 VM（再挡一次）共用。
- 失败一律如实：弹层还开着就留在弹层里（输入不丢、可原地重试），弹层已被关掉就挂到
  页面顶部那行横幅，绝不静默。

UI
- 长按气泡打开动作菜单；由于正文包在 SelectionContainer 里、长按正文同时也是选字手势
  （两者抢同一个长按，谁先消费由运行时决定），另给一枚看得见的「⋯」
  （content-desc 消息操作）作为同一条入口，避免只有知道的人才会用。
- 编辑弹层：原始 content 作初值 + 码点计数 + 取消/保存；删除必须二次确认。
- ChatScreen 只加 24 行接线（两个回调 + 两个弹层的渲染）。

测试 +49（766 → 815，全绿）：帧解析 14、纯逻辑 15、Retrofit 层 7、失败文案与落点 13。
 2026-10-04 21:26:52 +08:00
AskaEth 5d8ab15c0e docs(02): 登记 unreadable 缺原因字段 + 文本层 PDF 的措辞别扭（均已如实处理，未替服务端编话） 2026-10-04 21:18:05 +08:00
AskaEth 1f9d1dde01 merge: W18 — App 内预览对非文本拒收（跟上 v0.61 的 .pdf） 2026-10-04 21:17:21 +08:00
AskaEth 48e41886ba feat(documents): App 内预览对非文本拒收 —— 跟上 v0.61 的 .pdf 
后端 v0.61 把文档白名单 22 → 23 项（新增 .pdf）并改成（扩展名, 字节嗅探）成对裁决，
读侧 MIME 如实下发 application/pdf。而 W11 的附件预览是把字节当 UTF-8 文本渲染的
（那时白名单里除 .pdf 外全是文本类）⇒ 一旦点开别的端发来的 PDF 附件，预览就是一整屏
二进制乱码，像文件坏了。这次堵的是这个兼容洞，不是新功能。

- 选文件器加 application/pdf：原先刻意不列（那时必被后端 415 拒），现在 PDF 在选择器里
  不该是灰的，服务端收得下。
- 新增 DocumentPreviewGate（纯函数）：mime 非空时只看服务端那次字节嗅探（以 text/ 开头
  判为文本，其余一律非文本，未知 mime 也判非文本——两侧代价不对称，误判成文本正是本闸
  要消灭的乱码）；mime 缺失/空白时按扩展名兜底（白名单里只有 .pdf 是非文本），这条兜底
  服务的是待发附件（它只有本地 URI 与显示名）。大小写不敏感并剥掉 ; charset 参数。
- 弹层新增 plan 参数：判为非文本时正文区留空、只留一句人话并指路两条出口——弹层照常打开，
  文件名/体积/字数/状态与两条出口一个不少，也绝不假装加载失败（字节其实是取回来的，
  只是本端不渲染它）。
- 两条出口刻意未动：打开用 DTO 的 mime（PDF 就该交给 PDF 阅读器，不用通配符），保存继续
  传 */*（W11 实测结论：SAF 会按 mime 给文件名补扩展名）。
- 测试 766 → 775（DocumentPreviewTest 新增 9 条：闸的判定矩阵、扩展名兜底与大小写、
  未知 mime 拒收、待发附件接线、以及 PDF 的打开类型不是通配符）。

未做（缺口留给主代理登记 02）：DTO 只有 status=unreadable，没有服务端那句原因文案
（含「图片型/无文本层 PDF，需要 OCR」）⇒ 客户端沿用既有通用文案「读不到」，
不自己拼一句假装是服务端说的。
 2026-10-04 21:16:29 +08:00
AskaEth 020687a82b docs(02): 收下后端回执八（v0.60 存储端点 / v0.61 PDF 文本层 / K1 API Key 落盘 / 两条行为变化） 2026-10-04 21:13:14 +08:00
AskaEth 440e441b31 merge: W17 — 重试记忆改多槽（每条失败各留自己的幂等键） 2026-10-04 21:12:19 +08:00
AskaEth d3fc0c8005 feat(chat): 重试记忆改多槽 —— 每条失败各留自己的幂等键 
RetryKeyMemory 从单槽改成多槽（slots: List<RetryKeySlot>，上限 MAX_SLOTS = 8，FIFO 淘汰最旧）。
单槽只记得最近一次失败那条，而用户的重试顺序不必和失败顺序一致：他重试 A 又失败、再回头去重试
更早失败的 B 时，B 的槽早被顶掉，那次重发只能铸新键 —— 而 B 那次失败完全可能是「服务端已经收下、
客户端没看见」，于是又落成第二条消息，正是本机制要消灭的重复。

- remember：同指纹先摘掉旧的、再追加到末尾（同一条又失败一次是更新它的键，不是并列两条），
  超过上限从头部丢最旧的，且刚写进去的那条一定留得住。
- forget：按 localId 清；一条都对不上就原样返回同一个实例；同 localId 万一有多条则一并清掉。
- keyFor：命中只消费那一条、其余槽全部保留；未命中铸新键且一条槽也不清 —— 单槽时代「未命中也要
  清空」在多槽下会把别的失败记录一起抹掉，这条已显式写进 KDoc 以防后人照着旧注释改回去。
- ChatViewModel：代码逻辑一个字节没动（三个调用点的签名都没变），只把提到「单槽」「下一次发送就
  被消费」的 KDoc 改成与新实现一致；值比较指纹、正文不归一、晚到的 message_persisted 刻意不清键
  这几条 W15 纪律原样保留。
- 测试：RetryKeyMemoryTest 由 10 条重写为 16 条。删掉「未命中即清空记忆」那两条旧断言（新语义下
  不再成立），新增：两条失败各自原样重试都落回自己的键（两种重试顺序各一条）、重试 A 不抹掉 B 的槽、
  同指纹重复 remember 只留一条且键是最新的、超上限 FIFO 淘汰最旧且刚写的仍在、未命中时全部槽保留、
  命中消费后其余槽保留。

验证：assembleDebug 与 testDebugUnitTest 均通过（--rerun-tasks 全量重跑）：760 → 766 测试 / 0 失败 / 0 错误。
 2026-10-04 21:11:45 +08:00
AskaEth b579732db6 docs: 落 W15/W16 批次（重试复键的取舍、会话内搜索的形状）+ 六条契约口径登记 2026-10-04 20:50:23 +08:00
AskaEth 46ac15a538 merge: W16 — 会话内消息搜索（顶栏入口 + 搜索面板 + 点结果定位） 2026-10-04 20:45:09 +08:00
AskaEth 23b46f9310 feat(chat): 会话内消息搜索 D2 —— 顶栏入口 + 搜索态面板 + 点结果定位 
改了什么
- data/api/SessionsApi.kt：messages 端点加可选 q（契约 §1 行 6：q 是同一个端点上的
  查询参数，不是新端点）。不传 q 时 Retrofit 整个省掉该参数，既有调用线上请求逐字不变
  —— 这条用真 HTTP 服务端读原始 URI 钉住，而不是靠读代码相信。
- data/repository/MessageRepository.kt：新增 search()（走既有 apiCall/Result 风格，
  倒序返回统一转成升序的 PagedMessages），以及 normalizeSearchQuery（只 trim：
  不转义 % _ \、不改大小写 —— 这两件事服务端已做，两边都做必然错一边）。
  空查询不发请求（契约里空 q = 未传，那会把整段历史当成搜索结果回给调用方）。
- ui/chat/SessionSearchModel.kt（新）：全部纯逻辑 —— 命中片段投影（先过 domain/parse
  这一处解析器再拼回纯文本，绝不把标记当富文本；标记里才有的词只显示不高亮）、
  结果合并去重排序（倒序，与聊天页的升序 MessageOrder 刻意相反）、游标推进、
  「这条在不在窗口里」的判定、失败文案。
- ui/chat/SessionSearchViewModel.kt（新）：只属于聊天页搜索态的小 VM，带代际号，
  连打两次回车时慢的那个请求回来不会顶掉新关键词的结果。
- ui/chat/SessionSearchPanel.kt（新）：全屏搜索面板 —— 自动聚焦输入框（IME 搜索键与
  放大镜都能提交）+ 结果列表（角色 / 时间 / 命中片段，BasicComponent 包 PreferenceCard）
  + 往下翻加载更早的命中 + 未搜/搜索中/空结果/失败 四态分开渲染。
- ui/chat/ChatScreen.kt：只加接线 —— 顶栏搜索入口、面板叠层、返回键先关搜索、
  点结果之后的如实告知。

为什么这么做
- 搜索态独立成小 VM：ChatViewModel 正被另一个并行模块改动，而搜索不改消息窗、不发消息、
  不碰 WS，没有任何理由挤进去。
- 面板叠在聊天页之上而不是替换它：底下的 LazyColumn 必须保持挂载，点一条命中要
  animateScrollToItem 定位，而 LazyColumn 一旦被移出组合，滚动就落空。
- 命中不在「已加载窗口」里时不插一条临时气泡，而是如实提示（比一个假的跳转诚实）：
  聊天列表是升序倒过来喂给 reverseLayout 的，凭空插一条几千条之前的消息会出现在列表最底
  ——也就是「刚刚发出的位置」——与它自己的时间戳矛盾，还会带偏跟随底部的判断；
  而把消息真的并进窗口要改 ChatViewModel，本模块不许。
- 失败绝不渲染成「没有找到」：两者都是一张空列表，但一个该换关键词、一个该修网络或权限。
- 返回键先关搜索：新处理器注册在 ChatHomeScreen 那几条之后（优先级更高），
  且搜索没开时是 disabled，抽屉 / 管理页 / 设置页的既有层级不变。

测试 706 -> 737（+31：纯逻辑 25 + 数据层 6）
 2026-10-04 20:44:03 +08:00
AskaEth 8b907036db merge: W15 — 手动重试同一条内容时复用原幂等键（改过的内容照旧铸新键） 2026-10-04 20:28:40 +08:00
AskaEth af11a94614 fix(chat): 手动重试同一条内容时复用原幂等键，改过的内容照旧铸新键 
W13 顺手查出的「文档与实现不符」：PendingMessage 的 KDoc 一直写着「重试复用同一个
localId」，而 emitAndDeliver 每次发送都新铸 localId —— 若某次失败其实是「服务端已经收下、
客户端判成失败」（队列满 / 超时 / 回执丢失），用户手动重试就会铸新键、被服务端当成第二条
消息落库，用户看到重复。这正是幂等键（契约 v0.56 §3.13 / 协同 G4）要防的事。

- 新增 domain/chat/MessageFingerprint.kt：正文 + 图片本地 URI + 附件本地 URI 的内容指纹。
  用纯值相等而不是哈希（摘要碰撞会让两条不同消息共用一个键，后一条被服务端判重丢掉），
  正文一个字都不归一（只改一个空白字符也算改过 —— 归一正是会把两条真实消息并成一条的操作）。
  附件只看本地引用：displayName / sizeBytes 是元数据，同一份文件两次查询之间可能一次报得出
  一次报不出。
- 新增 domain/chat/RetryKeyMemory.kt：单槽重试记忆，三个纯函数（remember / keyFor / forget）
  加一个判定结果类型。remember 只在回滚时调用；keyFor 是唯一的消费点，指纹相等即复用、
  不等则铸新键（两支架都消费掉记录）；forget 按 localId 清，避免两条同时在飞时互相踩。
- ChatViewModel：所有回滚路径（发送失败、队列满被拒、附件与图片上传失败、图片处理失败、
  附件超限……）本来就汇到一个 rollback，现在在那里按指纹记下那条的键；队列满判定的 Rollback
  档同样记、Adopt 档清。emitAndDeliver 改用 keyFor 取键。完成回执与 duplicate / 收编按
  localId 清（正常那一路在发送时已消费，这几步是兜底）。落库消息到达时刻意不清：一条晚到的
  message_persisted 恰恰是「服务端其实收下了」的证据，留着键才能让重试真正幂等。
- duplicate 路径复用既有 alignDuplicate / applyQueueFull 的 Adopt 档，没有另造对齐逻辑。
- 测试 706 → 729（+23，0 失败）：指纹 13 条（正文空白 / 换图 / 增删与换序附件 / 元数据不算
  内容 / 快照语义），重试记忆 10 条（复用只在指纹相等时发生、用掉即消费、编辑后不再复用、
  forget 只清得动那一条、以及 duplicate 收口的端到端那条）。
 2026-10-04 20:27:00 +08:00
AskaEth 76d49b73d1 docs(05): 落 W13/W14 批次与实机验收、W13 的两条文档不符、W14 取字节无 logcat 的证据改法、回执七要点 2026-10-04 19:52:57 +08:00
AskaEth f10984622c merge: W14 — 点气泡里的图片进全屏查看，并接上「用其它应用打开 / 保存到下载目录」 2026-10-04 19:48:52 +08:00
AskaEth 557ef3f524 feat(chat): 点气泡里的图片进全屏查看，并接上「用其它应用打开 / 保存到下载目录」 
气泡里的图以前点了没有任何反应。现在点图进一个铺满全屏的弹层：fit-center 渲染、双指捏合
缩放（以双指中点为不动点）与单指拖动平移、双击在 1x 与 2x 之间切换（以双击点为不动点）。
位移与缩放全部按内容边界钳制——fit 态下拖不动（内容没超出容器）、放大后拖不到露出空白、
缩放恒在 1x..3x（下界比任务书的 0.5x 更紧：1x 就是「整张图刚好放得下」，再缩只是变小加留白）。
双击或关闭即复位（缩放状态活在弹层的组合里）。退出有右上角关闭按钮与系统返回键。

弹层底部两条出口与 W11 的附件预览同源，缓存与落盘复用 DocumentCache：图片也落在
cacheDir/documents/ 下，所以 FileProvider 的暴露面一个字节都没变（file_paths.xml 只改了注释，
没有新增暴露路径）。
- 用其它应用打开：声明图片自己的 mime（字节嗅探优先，其次平台声明的 image/ 前缀、名字扩展名，
  兜底 image 通配），经 FileProvider 交出去并带 FLAG_GRANT_READ_URI_PERMISSION；系统里没有
  应用能开时如实说一句并指路保存，绝不静默失败。
- 保存到下载目录：CreateDocument 一律传通配类型，否则 SAF 会按具体 mime 给文件名补扩展名
  （W11 实机抓到的 .md 变 .md.txt 那个坑；图片这边同样会变成 x.jpg.png）。

字节来源分三条，判定只发生在一处（ImageSource.of）：服务端能力 URL（GET /api/v1/files/{name}，
读侧免鉴权，所以用一条裸 OkHttp 客户端，而不是挂了 AuthInterceptor 的那条链——把 token 发给
一个免鉴权端点只多一个泄漏面）、内联 data: URI（字节就在字符串里，不联网）、本地 content 或
file 协议 URI（现读并拷进缓存，因此自己刚发的那张本地图也能交给别的 App）。

缓存名从服务端 URL 推，但要先过安全闸：单段、非 . / ..、不含分隔符与 NUL、不含百分号、扩展名
在图片白名单里；任何一条不满足就回落到按字节内容寻址——绝不拿一个不可信的名字拼路径。

加载态 / 失败态 / 就绪三者分明：取字节失败给一句话加一个重试入口；字节拿到了但解码不出来
（例如服务端被代理换成了 HTML 错误页）另给一句话，绝不画成一张空白图。重试把两条路都重来一遍。

测试 634 到 676（+42）：来源判定、缓存名的安全闸、字节嗅探、打开与保存的类型选择、失败文案、
缩放平移的全部数学，以及图片缓存层的命中 / 回落 / 失败不留残留文件 / 真的走一次本地 HTTP
（JDK 自带的 HttpServer，验 200 / 404 / 0 字节三种响应）。纯装配部分（Dialog、手势识别、
Intent 投递、SAF 落盘）没有单测，留给实机验收。
 2026-10-04 19:48:18 +08:00
AskaEth 9e039863fa docs(02): 收下后端的回执七（大附件护栏修复上线、API Key 仅内存表、IM 文件边界、v0.60 预告） 2026-10-04 19:43:52 +08:00
AskaEth 9854cc477d merge: W13 — 队列满时定位并处置那条待发气泡（pending_full / 定向 chat_busy 的 clientMsgId） 2026-10-04 19:42:49 +08:00
AskaEth 3b4a790e30 feat(ws): 队列满时定位并处置那条待发气泡（契约 v0.59 / 协同 G5） 
WS 上行没有 REST 那样的同步回执：队列满时服务端只广播一条 pending_full，而载荷里既没有
「被拒的是哪一条」也没有任何可对齐的键，于是那条乐观气泡永远挂「发送中…」，用户不知道它
其实根本没发出去。后端 v0.59（G5）已经把这两件事补齐：pending_full 载荷新增两个可选键
clientMsgId（被拒那条消息的幂等键，未携带则整键缺席）与 messageId（仅当该消息此前已落库 /
已认领时才回填，服务端绝不在此新铸 id），并新增一条只发发送者的定向帧
error{code:"chat_busy"}，与 REST 的 409 chat_busy 同码。本端把这两条接上。

data/ws/WsEvent
- PendingFull 增 clientMsgId / messageId：缺席就是 null，绝不拍成空串（否则收编路径会去
  对齐一条不存在的消息）。
- Error 帧增 code / clientMsgId / messageId，并从 data.sessionId 取会话归属（定向帧的帧壳
  上没有 sessionId）。code 是开放集合：未知码原样保留，不抛、也不吞掉整帧。
  未给定向 error 另立事件类——它与既有 error 是同一个 type，一个 type 无法用两个类表达；
  两者语义的分叉放在下面的判定函数里，保持「一个帧类型一个事件类」的既有约定。
- PendingFullData / ErrorData 同步扩键，全部可选且默认 null。

ui/chat/ChatViewModel
- 新增纯函数 queueFullOutcome（判定）与 ChatUiState.applyQueueFull / rollbackPending
  （状态迁移），两者都不碰协程，逻辑不埋在协程里、可直接单测。既有 rollback 改为委托
  rollbackPending，行为逐字不变。
- 判定顺序即证据强度：clientMsgId 命中时，messageId 非空 => 收编（复用 alignDuplicate：那条
  其实早就落库了，不是失败、不回滚、不把正文/图片/附件退回输入栏），缺席 => 回滚那一条并把
  内容还给输入栏；clientMsgId 有值但不命中 => 放手（键只属于某一次具体发送，回滚任何一条都是
  误伤）；clientMsgId 缺席（老服务端）=> 沿用 toolExecutionTargetIndex 的先例，只在待发恰好
  一条时回滚它，两条及以上不猜、但也不装作没事，只如实提示一句。
- 广播 pending_full 与定向 error{chat_busy} 会同时到达发送者，两者共用 onQueueFull；
  幂等靠状态本身——第一次已把气泡移出待发列表，第二次判定自然落到 Ignore，不会回滚两次、
  也不会提示两遍。
- REST 409 chat_busy 的文案与 WS 侧合并成同一句（契约把两条入口定为同一个 code），
  并点明「这条没发出去、请手动重试」：全链路没有自动重试。

测试 +30（634 -> 664，0 失败 / 0 错误）
- WsEventPendingFullTest：两个新键的有/无、老形状仍可解析、会话闸、无载荷与坏帧不抛。
- WsEventErrorFrameTest：chat_busy 定向帧全字段、可选键缺席为 null、未知 code 原样保留、
  只带 code 的帧仍可解、只有 message 的老帧行为不变、坏帧不抛。
- QueueFullOutcomeTest：三种事实各自的判定与状态迁移（收编不动输入栏 / 回滚归还正文图片附件 /
  不猜时一个气泡都不动），以及键对不上、空键、同一帧处理两次的幂等。

未验证：本端没有设备也没打过真后端，队列满的实机触发路径见交接报告；VM 里
「判定 -> 既有动作」的映射只由编译与纯函数单测覆盖（构造 ChatViewModel 需要 Android
环境的 AppContainer，单测里没有先例）。
 2026-10-04 19:41:40 +08:00
AskaEth 8633ec9f06 docs(05): 落 W11/W12 批次与实机验收、SAF 双扩展名 bug 的修复、GMS ANR 与 dump 重试两个新坑 2026-10-04 19:28:53 +08:00
AskaEth ffa7ed2661 fix(chat): 保存附件时不要被 SAF 补成双扩展名 
实机复现（2026-10-05）：把服务端附件 `809320…e.md` 保存到下载目录，落盘成了
`809320…e.md.txt` —— 因为 `CreateDocument` 传的是服务端**字节嗅探所得的基类型**
（`.md` 也会报 `text/plain`），而 SAF 的 Downloads provider 会按该 mime 给文件名**补扩展名**。

改为传 `*/*`：没有可补的扩展名，原扩展名因此保真。
**「用其它应用打开」那条路刻意不改** —— 那里要的正是「能读懂这段内容的类型」，照旧用嗅探所得的 mime。

实机复核：同一枚附件保存后落盘为 `809320…e.md`（95 字节，与源一致），不再出现 `.md.txt`。
 2026-10-04 19:27:53 +08:00
AskaEth 60b0eacafd merge: W11 — 附件芯片可点开预览 + 「用其它应用打开 / 保存到下载目录」两条出口（FileProvider） 2026-10-04 19:22:25 +08:00
AskaEth 27b6910009 feat(chat): 附件芯片可点开预览，并给「用其它应用打开 / 保存到下载目录」两条出口 
点一枚附件芯片此前完全没有反应。现在点它会开一个 App 内预览弹层，弹层里再给两条出口。

- FileProvider（authority = ${applicationId}.fileprovider，res/xml/file_paths.xml 只暴露
  cacheDir/documents/）：把 file:// 交给别的 App 在 API 24+ 会抛 FileUriExposedException，
  必须走 content://；因此 cacheDir 下真正要交出去的那一层才被开出来。
- 新增 data/repository/DocumentCache.kt：缓存路径推导 / 命中判定 / 原子落盘是可单测的纯逻辑；
  DocumentCacheStore 把「服务端按存储名下载」与「本地待发附件」两条来源汇成同一份文件 + 字节。
  服务端存储名是内容寻址（sha256[:32]+ext）且读侧响应 immutable，所以命中即永不失效、命中时
  一个请求都不发；先写 .part 再改名、失败删干净——半截文件被下一次「命中」当成完整内容，
  是最坏的一种静默错误。
- 新增 domain/chat/DocumentPreview.kt（纯逻辑）：截断（首 256 KB 或 5000 行，先到者为准；
  字节切点不切坏多字节 UTF-8）、正文分块（200 行一块）、来源判定（服务端 vs 本地，只有一处）、
  打开用的 MIME（只用 DTO 里字节嗅探所得的 mime，绝不按扩展名猜）、「没有 App 能开」的裁决与
  文案、取字节失败的分类文案。
- 新增 ui/chat/DocumentPreviewDialog.kt：Compose Dialog + Miuix 内容。正文用 LazyColumn 分块渲染
  （5000 行不塞进单个 Text），每块各自 SelectionContainer；加载态与失败态分明（失败给重试，
  绝不渲染成空文件）；截断明写「只显示前 N，完整内容请用…」，不静默截断；复用 DocumentChips
  显示类型/体积/字数/状态，不另写一套标签；status 为 unreadable 不挡预览（那是模型读不到，
  文件本体一直在）。
- ui/chat/MessageBubble.kt：芯片整枚可点（点击区是那枚芯片本身，不是里面的两行文字），
  并带 contentDescription「查看附件 <name>」。
- ui/chat/ChatScreen.kt：预览状态 + 取字节 + SAF 保存 + ACTION_VIEW 打开。没有 App 能开时
  如实告知并指路保存，绝不静默失败。

契约缺口（需登记 02）：服务端按内容寻址落盘，DTO 里没有原始文件名，保存到下载目录只能用
<32hex>.<ext>——弹层里已把这一点写在界面上，没有替用户编一个假名字。

测试 567 → 610（+29 DocumentPreviewTest / +14 DocumentCacheTest），0 失败 0 错误。
 2026-10-04 19:21:31 +08:00
AskaEth a0d6e3479f docs(02): logs REST 已接上（闭环）+ 五条契约口径建议补写 + 铸不出 viewer 账号的验收缺口 2026-10-04 19:20:15 +08:00
AskaEth a7dbee847e merge: W12 — 「最近日志」接上 logs REST 引导读取（补齐只显示进页面之后那段日志的缺口） 2026-10-04 19:19:18 +08:00
AskaEth 642bdb13f0 feat(admin): 「最近日志」接上 logs REST 引导读取 —— 补齐 W10 只显示进页面之后那段日志的缺口 
W10 接上的 `observability_log` 帧以「订阅那一刻的最新条目」为锚、不回灌历史，而客户端没有
`GET /api/v1/admin/observability/logs` 的接入 ⇒ 概览页的「最近日志」只能显示进页面**之后**产生的
条目。本次把 REST 引导读取补上，并把 W10 那条取舍（「一帧都没到过 → 整段不渲染」，为的是不把
「没有推送」说成「没有数据」）改成契约要求的「**REST 成功即渲染、帧是增量**」。

- **取数**：`AdminApi` + `AdminRepository` 接上该端点，显式发 `limit=200`（与客户端保留窗口、
  帧的单帧上限同源）；**不暴露** `?level=`——它是服务端「最低等级」过滤，只在服务端裁剪一次，
  会饿死界面上那排要来回切换的等级档，所以一律取全量、由客户端本地过滤（契约 §3.12 亦然）。
- **DTO 统一**：REST 与帧同形（后端同一个 `gateway.AdminLogEntry`），因此把
  `data/ws/ObservabilityLogEntry.kt` 挪进 `data/api/dto/AdminDto.kt` 并改名 `AdminLogEntryDto`
  （顺带与 `AdminMetricsDto` / `AdminTraceSpanDto` 对齐），删掉旧文件——不留下两份等价形状。
- **合并纯函数**：日志改成「去重 → 按 `time` 倒序 → 截窗口」。三步顺序不能换：窗口是**位置**
  截断，先截再排会让一条更旧的条目挤掉更新的那条；排序用解析出的 epoch 秒 + **稳定排序**保住
  同秒条目的到达顺序（服务端 `time` 只有秒精度）；时间判不出来的条目落到尾部但**不丢**。
  trace 那条路径不动（span 有服务端写入序号，重排反而把顺序排乱）。
- **界面**：`logs` 改为可空——null = 还没有基线（不渲染）；非 null（含空列表）= REST 读过且成功
  ⇒ 渲染，于是「加载中 / 不可用 / 暂无日志 / 列表」四种表现分明，未知等级条目照旧一律保留。
  三路的失败原因也分开记了：日志挂了不再让 trace 那块显示「不可用」（那是把一次成功说成失败）。
- **角色分档**：新增纯函数 `canReadObservabilityLogHistory`（日志历史与概览页同档，
  v0.40 的 viewerAuth 只读监控档 ⇒ **viewer 也读得到**），与只发 owner/admin 的帧门刻意不对称。
  ⇒ viewer 看得见历史、收不到增量，界面不得因此报错或报空（区块是否渲染只看历史这条门）。

测试 567 → 591（DTO 边界、合并去重/排序/窗口、角色分档、仓库线级请求与 501/403/坏载荷）。
`assembleDebug` 与 `testDebugUnitTest` 均通过（591 测试 / 0 失败 / 0 错误）。未做真机与真后端验收。
 2026-10-04 19:18:42 +08:00
AskaEth c94ea09b59 docs(02): 登记纯附件回合（Android 端首测）没有助手消息 + 两次 knowledge 工具失败 2026-10-04 19:12:52 +08:00
AskaEth e59ef08cf9 docs(05): 落 W8–W10 批次状态、模拟器与该轮自动化的坑、契约 v0.59、附件预览欠账 2026-10-04 19:09:10 +08:00
AskaEth ca5596a732 fix(chat): 附件芯片改换行排布 —— 多附件不再被裁到屏幕外 
主人 2026-10-04 在主会话里发现「用户消息显示有问题」：带 2~3 个附件的用户消息里，
第一枚芯片就吃掉了整排——服务端存储名是 32 位十六进制 + 扩展名（如 `36a4aba0…5524808.txt`），
一枚约 267dp，而芯片排是「横向可滚的单行 + `widthIn(max = 320.dp)`」，于是第二枚只剩一条边
露在屏幕外。看的人不知道还有别的附件，也看不出那一行可以滚。

改为 `FlowRow` 换行排布（用户消息整排贴右 `alignEnd`），N 枚芯片全部可见；代价是 5 枚会占
2~3 行——比「藏起来」值。去掉随之失效的 `CHIP_ROW_MAX_WIDTH` 与两个 import，
并同步 `ChatScreen` 里待发芯片排的注释（同一处行为）。

实机复核：主会话那条三附件消息现在渲染为三行，三枚芯片与各自的
「TXT · 4 B · 4 字 · 已读入」全部可见（截图 `app/build/e2e-shots/chips-after.png`）。
 2026-10-04 19:08:26 +08:00
AskaEth 2369dd2115 meta(docs): devdocs/ 纳入版本库 —— 交接与协同文档不再只存在于本机 
主人 2026-10-04 指示「项目仓库也可以写进去」。因此把 devdocs/ 从 .gitignore 移除并首次入库：

- `05-开发进度与交接.md` —— 跨会话交接锚点：当前状态、易忘的实现约定、踩过的坑、实机验收方法
- `02-前后端协同事项.md` —— 与后端会话的**交换文档**（两边都会读写：我们登记缺口，对面写回执）
- `01/03/04/06/07` + `DESIGN.md` —— 路线、客户端细化方案、构建环境、迁移说明、给后端会话的交接

**凭据扫描已过**：无账号口令、无 token/refreshToken 明文、无 API key 或私钥。
文档里只记「登录凭据不写进文档，问主人」这条口径本身。

（此前忽略它的理由已不成立：文档现在承担跨会话交接与前后端协同两件正事，
只留在本机磁盘会随机器丢失，而这批内容的价值恰恰在「后来人读得到」。）
 2026-10-04 19:00:18 +08:00
AskaEth 29733914a4 docs(documents): 契约 v0.59 已发布 —— 更正 W6 那批「未发布/待发布」的过时注释 
Cyrene_v2/Docs/api-client.md 已发布 v0.59（§1.2「文档存储与摄取契约」+ 端点表 16/17），
而 W6 那批文件的 KDoc 仍写着「契约尚未发布 / 待发布」，会误导后来人以为形状没有契约背书。

已逐条核对：我们实现的形状与已发布契约**完全一致** —— multipart 部件名 `file`、
201 首次 / 200 + `deduped:true` 去重、单文件 20 MiB、单回合 ≤5 条、上行只收 `name`、
`url` 是相对路径、`mime` 是嗅探基类型、`documents` 数组含 `chars`/`truncated`/`status`、
0 个附件时该键省略、4 个错误码。白名单在契约里也已更正为 22 项（与代码一致）。

纯注释更正，零行为变更。
 2026-10-04 18:53:10 +08:00
AskaEth ab76798bff merge: W9 — 文档附件接到 UI 与发送链路（选文件 / 待发芯片 / chat.documents / 分享分流） 2026-10-04 18:48:42 +08:00
AskaEth 30180ab1e5 feat(chat): 文档附件接到 UI 与发送链路（选文件 / 待发芯片 / chat.documents / 分享分流） 
把 W6 做好的「文档进对话」数据层接上 UI 与发送路径，产品决定按 05 的定案执行：
**不做长正文自动转文件**、**附件与正文各自独立存在**、上行**只给服务端存储名 `name`、≤5 条**、
带附件一律走 REST。

改了什么（按清单）：
- AppContainer：照 cachedUploadApi 的写法加 documentsApi + documentRepository，**与 chatApi 同
  baseUrl / 同 token·401 策略**（上传拿到的 name 要交给同一个后端的 /chat，不同源必然 404）。
- domain/chat/DocumentAttachment.kt（新）：DraftDocument（待发附件，只带本地引用，**不带字节**）、
  admit()（去重 → 20 MiB 单份预检 → 5 份上限，被挡下的**都计数**、绝不静默裁）、
  readBounded()（超限回 null、IO 异常原样抛——「太大」与「读不到」必须分得开）。
- domain/chat/DocumentChip.kt（新）：附件芯片的展示换算（类型 / 体积 / 注入字数 / 状态），
  unreadable（读不到）与 truncated（注入被预算截断）**两句文案分开**，未知 status 原样显示。
- domain/chat/DocumentDelivery.kt：加 planForCount(text, 份数)——同一套判定矩阵，但只看份数，
  因为 VM 手上还没有字节（最多 5×20 MiB 一次性读进内存不可接受）。plan() 委托给它，行为不变。
- ChatViewModel：ChatUiState 加 draftDocuments / attachmentNotice；send() → deliver() 走
  DocumentDelivery 判定 → 逐份上传（保留扩展名、200+deduped 当成功）→ payload(names) 为 null
  时**提示而不截断** → sendViaRest 带 documents；失败与正文、图片一起回滚（附件还给输入栏）。
- ChatScreen：SAF OpenMultipleDocuments 入口（MiuixIcons.File + contentDescription「添加文件附件」），
  MIME 列表贴近后端文本白名单的语义（含 octet-stream 以免「后端收得下、用户选不到」），
  输入栏上方一排可移除芯片；发送按钮在只有附件时也可用（纯附件回合服务端支持）。
- MessageBubble：documents 渲染成芯片（名字中略保住扩展名 / 类型·体积·字数·状态），
  unreadable 整枚转灰并明写「读不到」；空列表不占位。PendingBubble 显示本地待发件。
- ShareIntake + ShareRules：EXTRA_STREAM 按 ContentResolver.getType 分流——image/ 前缀走既有
  图片路，其余（含 null）走**文档路**（拷进 cache、带显示名与真实字节数）。此前一律当图片拷，
  一份 .md 只能得到「图片处理失败」。**Manifest 一行未改**：后端明令拒绝 html/SVG/zip/脚本，
  声明全通配会造出「点进去必然失败」的入口，text/plain 已能接住 .txt/.md/.log。

测试：485 → 536（+51，0 失败 0 错误）。
 2026-10-04 18:44:23 +08:00
AskaEth 93941cd1ea merge: W10 — 接上可观测性下行帧（概览页实时刷新 metrics / trace / 日志） 2026-10-04 18:42:58 +08:00
AskaEth b5e6f78910 feat(admin): 接上可观测性下行帧，概览页实时刷新指标 / trace / 日志 
契约 v0.55 §3.12 的三帧（`observability_metrics` / `observability_trace` / `observability_log`）
此前在本端没有 handler，落到未知帧被静默丢弃，概览页只能「进页面 / 手动刷新各拉一次 REST」。

- 解析（data/ws）：三个事件类 + `dispatchObservability` 分支，载荷按契约逐字对齐
  （metrics = 扁平本体、trace = `{spans}`、log = `{entries}`），帧壳 `sessionId` 有就透传。
  载荷缺席时**整帧安全忽略**——metrics 回落成默认值就是一份全零快照，会把界面上的真实指标
  擦成 0；未知帧、坏帧仍安静丢弃（回归用例钉住，绝不抛）。
- 消费（ui/admin）：AdminViewModel 自持一条 socket（照 SessionsViewModel 的做法：登录且
  角色够档时连、登出 / 角色降档 / onCleared 关），把三帧合并进概览状态。REST 仍是兜底真源：
  进页面与手动刷新照旧各拉一次全量；每次「连上」（含首次连接与断线重连）后再重读一次——
  断线窗口里的帧永久丢失，而服务端只为「有在线 owner/admin 连接」的凭据保留订阅，
  重读同时也重建订阅（契约 §3.12：读取即订阅握手）。
- 角色门在客户端也判（domain/admin 新增纯函数 `canReceiveObservabilityFrames`）：这三帧服务端
  fail-closed 只发 owner + admin，与概览页自身的 Monitor 档是两条门，viewer 既不开连接也不合帧。
- 日志只有推送这一个来源（本端没有 logs REST 端点）：一帧都没到过时整段不渲染——不写
  「暂无日志」，那等于把「没有推送」说成「没有数据」；等级过滤按契约在客户端本地做。
- 合并与过滤是 ui/admin 下的纯函数（新帧在前、按业务键去重、窗口 100/200），单测覆盖。

测试 485 → 514（+29），0 失败 0 错误；`assembleDebug` 通过。
 2026-10-04 18:42:23 +08:00
AskaEth f24877d53b merge: W8 — 设置页「版本」行可点进「关于」页（含作者署名） 2026-10-04 18:35:11 +08:00
AskaEth 3ed2377b3c feat(设置): 「版本」行可点进「关于」页 
设置页的「关于」分组里，「版本」此行此前点了没反应——它是全页唯一
没有 onClick 的行。现在它带 ChevronForward（与管理员入口行同一种「可
进子页」提示）并可点，进入新的「关于」页。

「关于」页只有四项：应用名（Cyrene）、版本、一句话简介、作者
（AskaEth），自己带 Scaffold + 返回按钮，观感与设置页一致。版本号复用
BuildConfig，不写死；页面里不放任何链接 / 邮箱 / 版权年份——这些信息
没有人提供过。

返回层级照项目既有的手写布尔状态 + 分层 BackHandler 模式（本项目无导航
库），新增 showAbout：
- 关于 → 设置 → 聊天；
- 设置页的处理器条件是 showSettings && !showAbout（与关于页互斥），
  所以在关于页按返回只退一层，不会一步跳回聊天；
- 抽屉 / 设置 / 管理页既有层级未动。

版本文本抽成纯函数 versionText(versionName, versionCode)，设置页与关于页
共用一份格式，并由 VersionTextTest 钉住输出。

测试：485 → 487（新增 VersionTextTest 2 条），0 失败 / 0 错误；
assembleDebug 通过。
 2026-10-04 18:31:03 +08:00
AskaEth a6b4bae2a0 merge: W4 — 概览页「按路径」分组折叠（可读性） 2026-10-04 18:09:18 +08:00
AskaEth a80dac7a7e merge: W6 — 文档进对话数据层（/documents + chat.documents，v0.59 形状） 2026-10-04 18:08:20 +08:00
AskaEth f91a8558ea feat(admin): 概览「按路径」改成分组可折叠列表 —— 26 条路径不再挤成一行 
`perPath`（真实响应 26 条）此前被 `formatCounts` 压成一行右对齐文本，手机上极密。
本次只改呈现层，取数（DTO / Retrofit / ViewModel）一字未动。

- domain/admin/AdminPathStats.kt（新增，纯函数）：分组键 = **剥掉 `/api/v1` 后的首段**
  （`/api/v1/admin/llm/catalog` → `/admin`，`/sw.js` → `/sw.js`，`/` → `/`）。
  规则是纯字符串推导、**没有任何路径清单**：服务端加路由不用改客户端
  （`/api/v1/quantum/*` 自动成 `/quantum` 组）；逐段比较，`/api/v1x/foo` 不会被误剥成 `/x`。
  剥离只作用于分组键，行里显示的仍是完整路径。
  排序：组按命中次数倒序、组内同样倒序，**两处同数都按路径升序**——指标页每次刷新都会重排，
  没有稳定次序读者就跟丢了。`hits`（次数）与 `pathCount`（条数）分开，是组头的两个数。
  长路径（段数 > 4）展示时折叠中间段、保留尾部 3 段：`…/admin/observability/metrics`；
  尾部才是区分同类路径的部分，整串在手机上会被尾部省略号吃掉、两条路径就长得一样了。
- ui/admin/AdminOverviewScreen.kt：「按路径」从 `countRows` 里挪出来单独成块——
  区块标题给「26 条 · 326 次」，卡片内一行一组，组头「N 条 · M 次」+ 可旋转箭头，
  整行可点即展开/收起；组内一行一条路径，右侧计数右对齐、路径等宽字体 + 中间省略。
  **条数 > 4 的组默认收起**（真实数据里 15 条 admin 路径收成一行组头），小分组默认展开省一次点击；
  折叠状态只记**用户动过的组**（`remember { mutableStateMapOf() }`，放在 LazyColumn 之外），
  刷新拿到新数据不会被上一轮点按锁死。
  只用 Miuix 现成组件（`PreferenceCard` + `BasicComponent` + `HorizontalDivider` +
  `MiuixIcons.ChevronForward` 旋转 90°），**没有自造折叠控件**；路径行用内容重载自己画 Text
  才能拿到 `maxLines = 1` + `MiddleEllipsis`（收 `String` 的那个重载只会尾部省略）。
  失败态不变：`metrics` 缺席时整块不渲染（上面那张「指标不可用」卡已经说明了原因），
  只有 `perPath` **请求成功且为空**时才给「暂无路径统计」。

测试：353 → 370 全绿（+17，AdminPathStatsTest）：空输入 / 单条（不产生组头）/ 真实 26 条 →
10 组且总次数 326 = 同一份真实响应里的 `totalRequests`（分组不吞路径也不重算次数）/
未知前缀自动成组 / 基址逐段剥离的边界（`/api/v1x/foo`、基址本身）/ 组与组内的排序与并列次序 /
长路径折叠（两条兄弟路径折叠后仍不同）/ 折叠默认值的阈值边界（4 条展开、5 条收起）/
显式切换双向覆盖默认。

未验证（无模拟器、也不许碰 adb，只有构建 + 单测）：
- 观感（组头取 `primary`、路径等宽字号取 `footnote1`、子行缩进 12dp、箭头旋转）**没有截图**，
  取舍待主人拍板；
- `BasicComponent` 对长路径会不会折行没有实机确认，所以路径文本额外做了「段级中间折叠」，
  不依赖库的省略行为；
- 深色模式未单独验证，颜色全部取自 `MiuixTheme.colorScheme`（与页面其它卡片同源）。
 2026-10-04 18:07:22 +08:00
AskaEth 557cdb213d merge: W5 — 新建会话时选角色（POST /sessions {personaId}） 2026-10-04 18:07:03 +08:00
AskaEth 095d6e781e feat(data,domain): 文档进对话数据层（v0.59 待发布形状 + 该不该走文件判定） 
契约 v0.59 尚未发布（api-client.md 最新仍是 v0.58），形状依据
devdocs/02 回执五「契约形状修正」，并用后端已落库切片逐字段核对：
407c934（S1 存储端点）、a4789ec（S3-B 网关入口）、5b2b385（S3.5 多值化）。

新增：
- data/api/DocumentsApi.kt：POST /api/v1/documents（multipart 字段 file）、
  GET /api/v1/documents/{name}（Bearer owner|admin；@Streaming 取字节）
- data/api/dto/DocumentDto.kt：文档形状的唯一落点（v0.59 若不同只改这里）
- data/repository/DocumentRepository.kt：200 + deduped:true 当成功；url 是相对
  路径故不做图片那套绝对化校验；不做本地白名单/大小上限（服务端才是裁决者）
- domain/chat/DocumentDelivery.kt：该不该走文件的判定 + chat.documents 载荷构造
- domain/chat/DocumentStatus.kt / DocumentFailure.kt：状态与四个错误码的可分支映射

改动：
- ChatDto.ChatRequest 增 documents（默认空列表 ⇒ 旧请求逐字节不变，有字面量钉子）
- MessageDto.HistoryMessageDto 增 documents（缺键与空数组都解成空列表，覆盖
  后端「0 个」尚未定死的两种形状；WS message_persisted / history 回放共用该 DTO）
- ChatSendRouting.channelFor 增 hasDocuments（默认 false）：带附件强制 REST，
  因为 WS 帧 4096 字节硬上限超限是直接断连，且文档一律走 REST

为什么不做 UI/VM：UI 与 ViewModel 文件由并行的分享入口模块占用，接线由主代理统一做。

测试：353 → 413（+60：DTO 12 / Repository 17 / Delivery 21 / Failure 10），
assembleDebug 与 testDebugUnitTest 均通过。
 2026-10-04 18:06:27 +08:00
AskaEth 4834905b24 merge: W7 — 分享到 App（ACTION_SEND / SEND_MULTIPLE + 进程级暂存，登录后落地） 2026-10-04 18:06:17 +08:00
AskaEth 217cfe3d5f W5: 新建会话时选角色（persona） 
改了什么：
- `POST /api/v1/sessions` 支持可选 `personaId`：null（或全空白）走**不带 body** 的重载
  （与选角之前逐字节相同），非空才发 `{"personaId":"…"}`；新增 CreateSessionRequest /
  CreateSessionResponse.personaId / SessionSummaryDto.personaId。
- 新增**用户侧**角色目录取数：PersonaApi + UserPersonaDto + PersonaRepository（沿用 apiCall/Result）。
  刻意不用 admin 的 PersonaSummaryDto/AdminApi：用户侧不下发 admin 专属 thinking，admin 端点还要管理档。
- 抽屉「＋」不再直接建会话，而是先开角色弹层（「默认角色」+ 各角色，角色名 + character 简述，
  失败/加载中各自有话说）；确认后按所选创建。角色表拿不到时降级为「只有默认角色」，不挡建会话。
- 会话行摘要前缀该会话绑定的角色名：能拿到角色表就显示名字，拿不到就原样显示 id，未绑就不显示。

为什么：
- 此前 createSession 完全没有 body，新建的会话一律是默认角色，后端 v0.42 起的多角色能力用不上。
- 会话角色**创建后不可变**（`PATCH /sessions/{id}` 一旦收到 personaId 就 400），所以选角这一步
  只在建会话时问一次，也必须在建会话时问。

测试 353 → 385（+32），assembleDebug 与 testDebugUnitTest 均通过。
变异验证：把仓库改回「null 也发 body」后，SessionRepositoryCreateTest 有 2 条断言 FAIL。
 2026-10-04 18:06:11 +08:00
AskaEth ae4e4e53f6 feat(share): 接入系统分享入口 —— 分享文本 / 图片进会话（未登录先暂存，登录后落地） 
主人 2026-10-04 提出的「分享到 App」的客户端半边。触发面就是系统分享菜单的
ACTION_SEND / ACTION_SEND_MULTIPLE；发送侧**完全复用既有路径**（短文本 WS、
长文本与图片 REST、大图先 /upload），不另起一套。

- Manifest：MainActivity 加 SEND / SEND_MULTIPLE 的 intent-filter，MIME 只声明
  text/plain 与 image/*。刻意不声明 */*：对话路径上今天没有「文件」这个表示
  （协同 02/F1 三缺），声明 */* 等于给出一个点进去必然失败的入口；收窄之后非图片
  文件干脆不进分享菜单。另加 launchMode=singleTop 与 label（分享菜单里显示 Cyrene，
  图标沿用应用启动图标，不另设一份会漂移的来源）。
- MainActivity：冷启动（onCreate）与热启动（onNewIntent + setIntent）两条路都接。
  冷启动只在 savedInstanceState==null 时接 intent —— Activity 因旋转 / 深色切换重建
  时系统会把同一个 intent 再送一遍，照单全收就会把同一条分享发第二次。
- 新增 domain/share（纯逻辑，可单测）：
  - ShareRules.extract：文本 / 单图 / 多图 / 空内容 / 只有 MIME 没有内容 /
    EXTRA_STREAM 缺席时回落到 ClipData；去重与空白条目在**截断之前**处理
    （重复项既不该挤掉真图，也不该被算成「截掉了」）。一次最多接 4 张，超出的
    条数如实计数，不静默丢。正文一个字都不加（来源标记走独立 RoleSystem 消息 +
    SenderName，拼进正文即违反红线，见 02/F4）。
  - ShareRules.cacheFileName：文件名只由本端 token + 序号 + MIME 白名单扩展名构成，
    外部 URI 的路径 / 显示名绝不参与（纯函数里连本端 token 都不信，非法字符折成 _）。
  - PendingShareHolder：待落地内容的队列，take() 是原子出队 —— 一条内容只能被消费
    一次（消费它的地方都会被重建：重组、切会话、Activity 重建），同时不把先后两条
    挤在同一窗口的那次分享丢掉。
- 新增 app/ShareIntake：进程级单例（不塞 AppContainer，避免碰别的并行改动）。
  图片在收到的那一刻就拷进 cacheDir 并换成**本端 file://**（content:// 的读授权活不过
  登录 / 切页，拷不动的那几张如实计入「未发送」）；进程启动清一次缓存目录
  （那份副本只对产生它的进程有意义），运行期间不回收 —— 发送失败回滚到输入框之后
  仍要读它。
- ChatViewModel：sendShared 与输入框的 send 共用 emitAndDeliver（同一套乐观气泡 /
  幂等键 / 回滚），差别只有「不动用户草稿」（分享不是用户按的发送键）。一条消息只能
  带一张图 ⇒ N 张图 = N 条消息，第一条带分享的正文；顺序在同一个协程里串起来。
  长文本不截断，由既有 ChatSendRouting 判据改走 REST（WS 帧 4096 字节是断连不是报错）。
- ChatScreen：仅当**当前会话**的组合存在时认领（已访问过的会话 VM 都还活着，UI 层
  认证才不会让旧会话抢走），落地前先等 WS 连接、上限 3 秒（冷启动必然撞上握手；超时
  也照发，让「没网」退化成内容回到输入框这种看得见的结果，而不是停在看不见的地方）。
  截断 / 读不到 / 空内容用 shareNotice 如实告知（8 秒后自动收走），与 error 分开。
- 测试 +23（ShareExtractionTest 18 / PendingShareHolderTest 5）：文本、单图、多图、
  空、只有 MIME、ClipData 兜底与去重、截断计数、超大文本不截断且落 REST、
  文件名不可穿越、原子出队（并发 64 取 64 条不重不漏）。assembleDebug 绿，
  testDebugUnitTest 353 → 376 全绿（failures/errors 皆 0）。
 2026-10-04 18:05:27 +08:00
AskaEth 664fd8dcef merge: W3 — B1 /upload（大图走上传，历史只留 URL） 2026-10-04 17:44:23 +08:00
AskaEth b44e8d96b9 merge: W2 — A2 interrupt scope（传输层 + 设置项） 2026-10-04 17:44:21 +08:00
AskaEth 51ea890684 merge: W1 — D4 未读（抽屉角标 + 已读游标） 2026-10-04 17:44:21 +08:00
AskaEth f413f8db55 feat(sessions): 接上 D4 未读 —— 抽屉角标 + 已读游标（进入即读、看着就点已读） 
后端 v0.37 起 `GET /sessions` 每条会话恒下发 `unreadCount`、`POST /sessions/{id}/read`
可推进**账号级**已读游标（只前进，`MAX(read_at, before)`）、成功后广播 `session_read`，
客户端一直没接。本次补齐：列表能看见未读、看完真的会消、别的端读了本端也消。

- data/api/dto/SessionDto.kt：`SessionSummaryDto.unreadCount`（**默认 0**——
  `SessionPreferences` 把整份列表原样持久化，非默认值会让升级后第一次启动整份快照
  解码失败、列表先空一下；默认 0 只会让角标少显示一会儿）；
  新增 `ReadSessionRequest`（`before` 缺席 = 现在，`explicitNulls=false` 保证序列化成
  `{}`，正是服务端接受的形状）与 `ReadSessionResponse`
- data/api/SessionsApi.kt + data/repository/SessionRepository.kt：`markRead(sessionId, before)`
  —— 不传 0（服务端对 0/负数回 400），null 即「现在」
- data/ws/WsEvent.kt：新增 `SessionRead`（`{type:"session_read", sessionId, data:{readAt}}`）。
  会话归属**只在帧壳**上（data 里没有 sessionId）；`readAt` 缺席回落 0，而 0 在上层是
  「无从判断」——坏帧因此天然退化成什么都不改
- ui/sessions/SessionsViewModel.kt：`SessionItem` 多出 `unreadCount` 与 `lastMessageAt`
  （后者只用于游标比对）；两条调和规则方向相反且都写成纯函数——
  `withReadCursor(readAt)` **有依据**地清（游标只前进，本地最新消息不比游标新才算真已读；
  若有更新的消息则保留旧计数，不能把真实未读藏起来），`markRead(id)` 无条件清（用户就在这一行）
- 已读策略：① `select()`（点开 = 进入）以「现在」推进——聊天页紧接着会加载并显示最新一页，
  比推本地可能陈旧的 `lastMessage.createdAt` 更诚实，且先就地清零，角标不等网络往返；
  ② `message_persisted` 且会话是**当前打开**的那一个时，以该消息 `createdAt` 推进
  （只标它及其之前，同时落库的更晚消息仍算未读），否则「自己正看着的会话」会攒出角标。
  不该标的绝不乱标：别的会话攒未读是正确行为，本端不做「替服务端数未读」（增量会漂移，
  抽屉每次打开都会静默重拉，以服务端为准）。失败**静默**——服务端游标是唯一真源
- `session_read` 帧按帧里的会话 id **逐行**定位（刻意不用 `isForSession`：那道闸是给
  「一个 VM 只关心一个会话」的 ChatViewModel 用的，本 VM 持有整个列表，按 activeSessionId
  过滤会把「别的会话被读了」这一帧丢掉，那正是最该处理的一半）
- 另记一份本地已知游标（只取服务端口径：read 响应的 readAt / 帧的 readAt / 落库消息的
  createdAt），在整表替换时把「本地已知没有更新消息」的行压回 0——否则一次竞态中的
  GET（快照早于本端刚发起的 read）会把角标闪回来；登出时随快照一起清（游标是账号级的）
- ui/sessions/SessionDrawerContent.kt：角标用 Miuix 自带 `Badge`（错误色药丸 + onError 文字），
  且**放在标题行里**而不是 `endActions`：抽屉固定 300dp，卡片与内边距之后只剩约 244dp，
  `endActions` 已有三个 40dp 图标（120dp）且被库内 60% 硬上限卡着，再塞角标会把图标挤到裁剪。
  改成标题行的 `[标题][角标]` 后角标不占额外列宽；标题/摘要同时收紧为 `maxLines = 1` +
  省略号（长标题不再在约 116dp 里折成两三行把卡片撑高）；`99+` 收敛、`0` 不画

测试：305 全绿（272 → +33）：角标文本（0/负数不画、99 精确、100 与 1234 收敛 `99+`）、
两条调和规则的各种边界（游标等于/新于/旧于最新消息、无消息会话、坏帧 readAt=0、
按会话逐行定位、遮罩只压记过游标的行）、`toItem` 映射、`session_read` 帧解码
（生产者逐字取自后端 `gateway/session_read.go:broadcastSessionRead`）、DTO 真载荷
（`GET /sessions` 抓包里主会话 unreadCount=6、次级=0）与**旧快照无该键仍解得开**、
read 请求体序列化（`{}` / `{"before":…}`）。

未验证（无模拟器，也不许碰 adb，只有构建 + 单测）：
- 角标与标题的**实际观感**没截图。宽度是按 Miuix 0.9.3 源码算的（抽屉 300dp − 卡片边距 24
  − 组件内边距 32 = 244dp；endActions 120dp < 60% 上限，标题列约 116dp，角标约 16~32dp）。
  LazyColumn 里角标与标题的具体落位（紧贴标题还是行尾）取决于 Row 的权重分配细节，两种都成立、
  都不遮蔽文字，但真机上可能想微调间距
- 「进入即读」在 UI 上没端到端跑过：POST /sessions/{id}/read 是否 200、`session_read` 帧
  是否真的清掉另一端的角标，只有单测与契约（后端源码）支撑，没有真机往返
- 已知近似：判断「正在看这个会话」只用 `activeSessionId`，而它是**活动页**的会话 id——
  用户切到设置 / 管理页时 ChatScreen 已卸载，此时落库的消息也会被标记已读（他会回来看到，
  但角标已经消了）。信息不足，如实记在这里

架构代价（需主人裁决）：`session_read` / `message_persisted` 只在 WS 上，而 `AppContainer`
只提供 `createChatSocket()`（每次新建，**没有进程级共享连接**），`ChatSocket` / `ChatViewModel`
/ `AppContainer` 都在别人的改动范围里 —— 本 VM 因此自持一条连接（登录后连、登出断开、
销毁断开）。这是既有遗留问题「每 VM 一条 socket、旧 socket 不关」之上再加一条；服务端支持
同账号多连接（多端本来如此），收不到帧也只是退回「下次 GET /sessions 收敛」。共享一条
app 级连接是更好的终局，但那要动 AppContainer / ChatSocket。
 2026-10-04 17:42:31 +08:00
AskaEth cc2f266564 feat(chat): 大图改走 /upload，历史里只留 URL 
服务端把 `chat.image` **原样落库**，于是内联的 base64 会在**每一页历史**与**每一次
WS `history` 回放**里重传一遍（协同 G3）。B1 的 `POST /api/v1/upload` 早就有了，客户端
一直没用——本次把它接进发送路径。

- `data/api/UploadApi.kt` / `data/api/dto/UploadDto.kt` / `data/repository/UploadRepository.kt`：
  upload 三件套。multipart 字段名 `file`（Go 只认这个名，且只把带 `filename` 的部件当文件，
  已对着在线后端实测：字段名不对回 `400 {"code":"bad_request","message":"file is required"}`）；
  走 `apiCall`（这台端点的状态码不承载额外语义，`413`/`415` 的区分在 `error.code` 里）。
  仓库另拦两种「服务端帮不了」的情况：`url` 为空**或不是绝对 http(s) 地址**就判解析失败
  ——视觉层只把 `http(s)://` 当 URL，裸路径会被当成 base64，照发等于把这一轮扔进黑洞。
- `app/AppContainer.kt`：按 baseUrl 缓存接线，与 chatApi 同源（上传产物 URL 必须交给同一个后端）。
- `domain/chat/ChatImageDelivery.kt`：内联 vs 上传的**唯一判据**（纯函数）。
  阈值为重编码后的 **64 KiB（含等于内联）**：内联的代价是每次历史取数再多 4/3 × B，
  64 KiB 即 +85 KB/次（20 张这种图的会话每次冷启动/重连回放就多传 ≥1.7 MB），而上传只是
  多一次往返（局域网毫秒级）——从第二次取数起就稳赚；≤64 KiB 的缩略图省下的量与一次往返同量级，
  不值得多一个失败面。阈值必须严格小于本端 1 MiB 预算，否则上传分支是死代码（有测试钉住）。
- `ui/chat/ChatViewModel.kt`：图片发送路径分流（小图内联、大图上传换 URL 再发 REST）。
  **上传失败不回退内联**：回退会把「省历史重量」当场作废、还是在用户看不见时换了一条语义不同的路；
  这里按上一步骤给可重试文案，并把图与文本还给输入框（`uploadFailureMessage`，纯函数可单测）。
- `data/image/ChatImagePreparer.kt`：产物改为同时给出 `data:` URI 与**同一份**字节，
  上传因此不必把刚编出来的东西再 base64 解一遍。

阈值依据、以及「URL 形态到底受不受 5 MiB 上限约束」的核查结论写在 `ChatImageDelivery`
与 `UploadRepository` 的注释里（结论：URL 形态**不受**解码后 5 MiB 约束——网关
`checkChatImageSize` 量的是 `image` 字符串长度，URL 才几十字符；URL 到视觉层才被取回，
上限是 `vision.maxFetchedBody` = 50 MiB。所以走上传**不是**为了绕开上限，本端 1 MiB 预算离
两个 5 MiB 上限都还差两个数量级）。

测试：309 全绿（272 → +37）：上传响应/错误体的真实形状（错误体是在线抓包原文）、
multipart 线级形状（部件名、filename、字节原样）、内联阈值与两条不变量、上传失败文案。
`assembleDebug` 通过。**未实测**（本端无模拟器、且不给在线后端留测试文件）：
真机上的上传成功链路与 Coil 渲染远程 URL——已静态确认 `coil-network-okhttp` 带
`META-INF/services/coil3.util.FetcherServiceLoaderTarget`（默认 ImageLoader 会自动注册网络
fetcher）、`network_security_config` 放行明文（同源 http URL 可取），但没跑过真机。
 2026-10-04 17:40:12 +08:00
AskaEth b7806951eb feat(ws): interrupt 支持 scope，并按偏好选「追加队列 / 打断」（协同 A2） 
契约 v0.56/A2（api-client §3.1）：interrupt{sessionId, scope?}，取值域 {"", "all", "current"}——省略 / 空串 / "all" 同义（取消在跑回合 + 清空待处理队列，逐字不变的旧行为），"current" = 只取消在跑回合、保留待处理队列（队列消息按编排器续跑规则继续执行，一条不丢）；其余取值服务端定向回 error{bad_request}、不打断任何会话。

- WsOutbound.Interrupt 增可选 scope：null = 整键省略（服务端视同 all），默认帧因此与今天逐字节相同；传输层不校验取值、不补默认、不改写别名（开放取值域由服务端裁决，客户端替它纠正只会换来一次没解释的打断）。
- ChatSocket.sendInterrupt(sessionId, scope = null)：把 scope 交给调用方从偏好取值；今天仍无调用方——「打断」触发点在聊天区（属另一轮），本 API 先把传输面备好，KDoc 如实标注。
- 新偏好 InterruptMode（DataStore cyrene_app/interrupt_mode）：AppendQueue（默认，省略 scope = all）与 Interrupt（scope:"current"）；未知/缺省值一律解回默认档，绝不悄悄换成更激进的一档。偏好经 AppPrefs → LocalAppPrefs 下发，聊天区按既有方式读取。
- 设置页新增「她忙时发消息」分组：沿用主题那套 Miuix PreferenceCard + BasicComponent + ✓；两行文案说清唯一差别——忙时那条排队消息还在不在（看不懂效果的偏好比没有更糟）。
- 测试新增 11 条（WsOutboundInterruptTest 6 / InterruptModeTest 5）：钉死默认档与旧帧逐字节相同、current 原样透传、"all"/""/未知取值都原样发出、两档不在线上打成同一种形状。工作树 assembleDebug 绿，testDebugUnitTest 283 条 0 失败（基线 272 + 新增 11）。
 2026-10-04 17:36:22 +08:00
AskaEth feeb49ebeb fix(sessions): 刷新后校验当前会话是否还在，别一直指着已删会话 
会话在**别处**被删掉（Web 面板 / 别的设备 / 直接调 API）时客户端无法感知：`refresh()`
成功后会整体替换 `sessions`，却**不校验 `activeSessionId` 是否还在新列表里**，
于是当前会话会一直指着一个已删会话——聊天页对着空会话，而且这个陈旧 id 会被
`prefs.setActive` 持久化下去，重启后依然是它。

本端自己的删除已经处理过（`deleteSession` 会主动切回主会话），漏的正是「别处删除」这一路。

- ui/sessions/SessionsViewModel.kt：新增纯函数 `resolveActiveSession(activeId, fetchedIds)`
  —— 不在列表里就回落主会话；**列表为空时不回落**（那是异常响应，不该拿它改用户的选择）。
  `refresh()` 成功分支调用它，值变化时同步持久化

测试：272 全绿（269 → +3）：已删会话回落主会话 / 仍在列表则保留 / 空列表不覆盖用户选择。

实测：会话在别处删除后 force-stop 重开（重走 init 与刷新），
`cyrene_sessions.preferences_pb` 里 **`web:<sub>` 残留彻底消失**、`active_session_id` 回落 `web`；
界面回到主会话对话，不再出现已删会话的幽灵行。
 2026-10-04 17:10:26 +08:00
AskaEth e642b0c18c feat(chat): 加 REST 发送路径 —— 长文与图片（含 clientMsgId 幂等与归一） 
客户端此前**只有 WS** 发送，而 WS 帧硬上限 4096 字节、**超限是直接断连**（不是报个错），
所以长文发不出去、图完全发不了。v0.56 给 REST 流式补齐了明确响应面与 clientMsgId，
本次照它接入。

- data/api：ChatApi + ChatDto（窄请求体，不回环整条会话）+ ChatRepository
  —— **刻意不走 `apiCall`**：它把 4xx/5xx 一律折进 `Result.failure` 并丢掉状态码，
  那样 `202`（已排队）与 `409`（队满）的差别会在那一刻消失；改为映射成 ChatAck 密封结果
  （Accepted / Queued / QueueFull / Duplicate / Unavailable / Rejected）
- domain/chat/ChatSendRouting：纯函数路由 —— **UTF-8 字节数 ≤ 3584 且无图 → WS，否则 REST**。
  阈值按**字节**不按字符（中文 1 字 3 字节）；预留 512 字节覆盖帧壳。短文本仍走 WS 是刻意的：
  那条路**绕开有损总线**，而超 WS 上限的代价是**断连**而非报错，两边风险不对称
- domain/chat/ChatImageBudget + data/image/ChatImagePreparer：解码 → 等比缩放 → 重编码为
  JPEG/PNG data URI；超预算自动降尺寸重来；**失败返回 null，绝不退回原图 base64**
- clientMsgId：每次发送 `"local-" + UUID`（**随机不自增**——服务端判重窗口是**整个会话历史
  且无过期清理**，进程重启后复用旧值会让那条消息永远发不出去）；REST 与 WS 两路都带
- 归一：带 clientMsgId 的消息**只按 id 匹配**（文本不同也命中；匹配不到就什么都不吃，
  **绝不回落到文本**——那会吃掉一条无关气泡）；不带键的老行才回落「第一条同文本」
- ack 分支：200 已受理（等 message_persisted）/ 202 已排队（出「已排队 N 条」）/
  **409 既未受理也未落库 → 回滚气泡并把文本与图片还回输入框**（不能当「已排队」，
  那会让气泡永远挂着「发送中…」）/ duplicate 不是错误（收气泡；本地没有该 messageId 就补拉一页）/
  500、503 回滚 / 400 image_too_large 换短文案
- 接下行帧 `chat_duplicate`；图片一律走 REST（`WsOutbound.Chat.image` 仍无生产者）

测试：269 全绿（218 → +51）。含真实抓包的四段响应（200 / 202 / duplicate / 400 image_too_large，
且服务端文案里的 6990572 与本端 SERVER_MAX_CHARS 做成对断言）、路由阈值边界
（1194 汉字 = 3582 字节走 WS、1195 = 3585 走 REST，并直接断言阈值处真实
`WsOutbound.Chat(...)` 序列化后 ≤ 4096 字节）、归一规则、六种 ack 映射。

真机（真后端 127.0.0.1:10942）：**图片全链路通过** —— 选图 → 重编码（源 7.8 KB PNG →
1 KB JPEG，magic ffd8ffe0）→ `POST /api/v1/chat`（1558 字节体）→
`200 {"data":{"stream":true}}` → 气泡由「发送中…」归一为「来自 安卓」→ 昔涟回复**准确描述了那张图**。
另 WS 短文本路径未回归（无 POST，且 clientMsgId 被 v0.56 原样回填）。

未验证：`409 chat_busy` 与 `500` 非真实抓包（要填满主人后端的待处理队列、等于真跑 5 个回合，
判断不值得；形状与文案逐字取自后端源码，测试注释里已写明）；UI 上的 202/409 未端到端跑过；
降尺寸「减半重来」那步未在设备上跑过（测试图 64×64 只走到重编码）。
 2026-10-04 16:57:22 +08:00
AskaEth 4c14028c70 fix(tools): 接上 tool_execution 三事件，并改用 id 关联工具卡 
客户端此前**只映射了 `tool_execution.update`**——恰好是后端**没有生产者**的那一帧
（后端回执亦确认：`.start`/`.end` 有真实生产者，`.update` 运行期可能永不来）。
真正会发出的 `.start` / `.end` 落进 `else -> null` 被**静默丢弃**，所以
**工具执行状态从未到过界面**：工具卡能显示调用与参数，却永远不显示「执行中 / 完成 / 失败」。

后端 v0.50 已把 `tool_execution` 拆成三帧、载荷为 `{tool, phase, id?}`——刻意**不带
`index` / `streamId`**（WS bridge 注释明写「tool_execution.* 不属于某一次模型流」），
关联键是 **`id`**（与同轮 `tool_call.*` 同一个 provider 调用 id）。所以旧实现按 `index`
归属本身就是错的。

- data/ws/WsEvent.kt：三个事件类型承载 `tool` / `phase` / 可空 `id` / `delta`（仅 update）；
  新增私有 `ToolExecutionData`（**无 `index`**）；三个帧名都进 `dispatchStreaming`
- ui/chat/ChatViewModel.kt：`ToolPhase { Running, Done, Error }` + `toolPhaseOf`；
  `ToolCallState` 扩 `tool` 与可空 `phase`；新增两个纯函数
  `toolExecutionTargetIndex` / `applyToolExecution`；三帧经既有 `isForSession` 会话闸
- ui/chat/StreamingBlocks.kt：工具卡标题与配色由 `phase` 驱动（`执行 <tool>…` /
  `工具调用 · <tool>` / `工具调用失败 · <tool>`，失败用 error 色）

关联策略是「**不确定就不挂**」，绝不默认 0：`id` 非空 → 精确匹配，找不到返回 -1
（宁可不挂也不挂错）；`id` 缺失 → 仅当「恰好一张卡 id 为空」或「整个列表只有一张卡」
才挂，否则 -1。`applyToolExecution` 不建卡、不动别的卡；`tool` 空白保留已有名字、
`phase` 无法识别保留已有阶段、`delta` 为空不改输出。`.update` 那条路也实现并测了。

测试：218 全绿（194 → +24）。新增 10 条三帧解码（按真实 `toolExecutionData` 形状：
id 有/无、phase running/done/error、update 带/不带 delta、多余 `streamId` 被忽略、
旧单帧形状可容忍、会话闸）+ 14 条关联规则与 phase/name/delta 应用。

实机：只读 WS 探针抓到真实帧
`tool_execution.start {"id":"call_00_o9Q…","phase":"running","tool":"calculator"}` 与
`.end {…,"phase":"done","tool":"calculator"}`，`tool_call.*` 共享同一 id、执行帧确实
没有 `index`/`streamId`；屏幕录制抓到渲染出的「工具调用 · calculator」——工具名只可能
来自 `tool_execution.*`，故端到端成立。全程只见 `.start`/`.end`，印证 `.update` 无生产者。

未覆盖：`phase:"running"`（内置工具太快）与 `phase:"error"`（无法诱发）的瞬时态，
仅单测覆盖。
 2026-10-04 16:28:22 +08:00
AskaEth d12a920096 fix(ws): 流式帧按 sessionId 收敛，修跨会话串台并退役 A1/D14 
服务端从 v0.36 起就在结构化流帧（message.* / thinking.* / tool_call.* /
tool_execution.*）上带了 sessionId + turnId，而本端 WsEvent.parse 把这两个字段
**丢掉了**——所以「同一时刻只有一个会话在流式」这条长期约束（A1/D14）其实是
客户端自己造成的，不是后端限制。

而广播是发给**每条已认证连接**、不按会话订阅；每个 ChatScreen 的 VM 又各建一条
ChatSocket，切会话后旧 socket 与旧 VM 都还活着——于是旧 VM 会拿新会话的 delta
跑自己的流式状态机，思维链/工具卡/正文全线串台。

- data/ws/WsEvent.kt：基类开 open val sessionId（子类按帧壳覆盖），透传到 10 个
  结构化事件类型；新增纯函数 isForSession()——**只排除「明确属于别的会话」的帧**，
  空值视为「无法判定」而放行（与 historyForSession 对空值的处理一致）
- ui/chat/ChatViewModel.kt：onEvent 顶部加一道会话闸；history 帧**刻意豁免**，
  它的归属由帧内每条消息的 sessionId 判定（比帧壳更细，即 2a49c25 的语义）
- data/ws/ChatSocket.kt：改掉那段描述「同一时刻只允许一个会话在流式」的过时 KDoc

顺带核实：**没有任何代码实现过 D14**（切会话时不拦截，sendInterrupt 更是零调用点），
它只是文档假设 + 解析器丢字段的副作用 → 因此 D14 退役、A1 闭环。

测试：194 全绿（178 → +16）。新增 WsEventSessionScopeTest：12 种帧类型的解码
（按真实帧壳形状）、向后兼容（缺字段 / 显式 null）、实抓的 history 帧、isForSession 规则。

未验证项：跨会话修复只由单测 + 后端自带的 ws_hub_stream_scope_test 覆盖，
没有实跑「两个会话同时流式」。
 2026-10-04 14:19:24 +08:00
AskaEth 2a49c25e1b fix(chat): WS history 帧按会话过滤，修次级会话串进主会话消息 
WS 首帧 history 是**主会话**最近 50 条的回放，但连接是全局的、帧会被投给任意
ChatViewModel；onEvent 此前把它**原样**并进当前消息列表，导致进次级会话会看到
主会话的消息混在一起——是数据串台，不是显示问题。

- data/repository/PagedMessages.kt：新增纯函数 historyForSession(messages, sessionId)，
  按**消息自身的 sessionId** 过滤；sessionId 为空的帧视为「无法判定」放行，
  不因缺一个字段就整段丢掉历史（保持既有行为）
- ui/chat/ChatViewModel.kt：history 分支先收敛到本会话再合并

为什么按 sessionId 而不是「只有主会话才收 history」：前者更耐将来——
服务端哪天开始给次级会话回放，这里无需改动。

测试：178 全绿（175 → +3），新增三条：主会话回放不得泄漏进次级会话、
缺 sessionId 的帧放行、过滤不修改入参。
 2026-10-04 14:05:38 +08:00
AskaEth c09a21136c feat(sessions): 会话列表用服务端标题 + 置顶 + 最后消息预览（A4/D5/B3） 
列表此前显示的是本地硬生成的「会话 N」，因为后端 title 恒空。后端后来做了
「首条用户消息自动命名」+ PATCH 改名/置顶 + lastMessage 预览，本轮接入，
并把本地那套序号机器整块删掉。

- data：SessionSummaryDto 补 pinned / lastMessage（均带默认值，老快照仍能解）；
  新增 UpdateSessionRequest / Response 与 @PATCH api/v1/sessions/{id}
- core/prefs：**整块退役**本地序号机器（order / KEY_ORDER / OrderSerializer /
  decodeOrder / ensureOrder / 「会话 ?」）——有了服务端标题，本地序号永远不会一致，
  且 id 没有序号时会渲染出字面的「会话 ?」
- 标题规则：服务端标题非空白即原样显示，否则兜底（主会话「与昔涟」/ 次级「新会话」）。
  主会话刻意保留「与昔涟」而不采用服务端自己的「主会话」
- 顺序**完全信任服务端**（pinned DESC, main DESC, created_at ASC），客户端不重排；
  因此置顶的次级会排在主会话之前——顺带修正 SessionDto 里「主会话恒首位」的过时注释
- 置顶：主会话与次级都可置顶（契约允许）；先就地翻转拿即时反馈 → PATCH →
  成功后静默重拉（服务端才是顺序权威，快照顺带修正）→ 失败回滚并报错
- 改名：长按行打开对话框（预填当前标题 + n/80 计数），不做乐观更新（服务端会 trim 后
  回写，等静默重拉取权威值）；**不提供「恢复自动命名」**——服务端无法表达（空白即 400）
- **刷新触发（前置条件，不是锦上添花）**：列表此前只在 VM 初始化 / 新建 / 删除时拉取，
  所以自动标题与预览要重启 App 才可见。现改为**打开抽屉时静默刷新**，
  且不闪「同步中…」横幅
- 顺带修同文件里两个既有缺陷：① **快照的指纹闸门其实没实现**（fingerprint 写了却从不
  比较、clear() 是死代码）→ 现按 baseUrl+username 指纹过滤，并把 clear() 接到登出
  （否则换账号后第一帧会闪上个账号的会话列表）；已实测确认指纹与写入时逐字节一致，
  不会误丢老快照。② 预览剥标签时旁白与正文会粘连（看截图发现的排版瑕疵）→
  标签改替成空格再折叠空白

测试：175 全绿（153 → +22）。含真实抓取响应体的 DTO 契约测试、标题兜底与预览规则的
纯函数测试、指纹闸门测试。
 2026-10-04 13:55:52 +08:00
AskaEth f5576540b4 feat(auth): 接入 /auth/refresh，不再把登录口令落盘 
客户端此前把明文口令存进 EncryptedSharedPreferences，用于过期后的静默重登
（当时后端没有 refresh 端点）。后端现在有 /auth/refresh + /auth/logout 了，
本轮改为存 refresh token，口令在首次成功认证后即被抹掉。

关键约束：服务端的 refresh 是**单次使用 + 原子旋转 + 无宽限期**——同一个 token
第二次使用立刻 invalid_grant；而本端并发 401 是常态（管理概览页两个请求并发、
聊天页 REST 与 WS 同时起步）。因此：

- core/auth/TokenRefresher.kt：单飞刷新 + 代际守卫（等锁期间别人已换好令牌就直接
  复用，绝不用同一个 refresh token 打第二次）+ 终态记忆（被 invalid_grant 拒过的
  token 记下来，一次失效里只打一次注定失败的请求；Transient 不记忆以保留重试）
- 用应用层 Interceptor 而非 OkHttp Authenticator：后者对**任何** 401 都会被调用
  （含不带令牌的登录请求），且由 RetryAndFollowUp 内部循环驱动（上限 20 次跟进），
  持续 401 的令牌会打出刷新风暴。应用层拦截器只在「带了令牌仍 401」时介入，且严格
  重试一次
- 可恢复的 401 不再登出：Transient（网络/5xx）原样交回 401 并保留会话；只有
  Unrecoverable，或「换上刚签发的令牌仍 401」，才判终态
- WS 握手 401：先尝试一次续期再重连，终态才登出
- 登出补调 POST /auth/logout（此前从不调用，服务端 grant 会白活 30 天）
- 主动 skew（60s）刷新 + 兜底重试；刷新请求走不带令牌的客户端，不会递归回本路径

迁移对用户无感、绝不强制重登：启动时若「无 refresh token 但有旧口令」，用旧路径
静默登录一次换到 refresh token，随即 commit() 抹掉口令；离线失败就下次启动再试，
且不清会话。另外鉴权过期时也走一次续期——否则去掉口令会把会话砍到 24h，比改动前
更差。

HttpLoggingInterceptor 保持 BASIC 不动：/auth/refresh 与 /auth/logout 把 refresh
token 放在**请求体**里，再高一级就会把凭据打进 logcat。

测试：153 全绿（115 → +38）。含真实抓取响应体的 DTO 契约测试、TokenRefresher 的
并发/代际/终态单测、bootstrap 迁移单测，以及走真实 OkHttp + Retrofit + 回环
HttpServer 的端到端测试（证明只重试一次）。未新增任何依赖。

未验证项：主动/被动续期路径本身没能真机触发（唯一输入是加密存储里的 expires_at，
shell 写不进去；而 tokenTTL 是 24h 常量），仅由回环端到端测试覆盖。
 2026-10-04 13:34:53 +08:00
AskaEth 09a3222b7b feat(enums): 接入 /meta/enums 权威枚举表，删掉客户端硬编码映射 
客户端此前自带 platform / mood / mode 三张硬编码标签表，会与服务端漂移——
实测已经漂了：客户端把 `web` 显示成「Web」，权威表里是「网页」。

- data：MetaApi（GET /api/v1/meta/enums）+ MetaDto + MetaRepository，
  经 ApiClientFactory 创建以复用既有 token / 401 处理
- domain/enums/EnumCatalog.kt：标签查找器，**不含任何硬编码兜底表**；
  不在表内的取值一律原样返回（api-client §1.1 的未知值回落红线）；
  platformLabelOrNull 供 deviceId 前缀这类「认识/不认识要走不同回落」的调用方用；
  空 id 或空 label 一律不入表（否则角标会显示空白，或查空串凭空借到别人的标签）
- core/prefs/EnumPreferences.kt：last-good 快照，baseUrl+username 指纹闸门，
  换服务器/账号即作废，登出清空
- EnumCatalogViewModel + LocalEnumCatalog：在 CyreneRoot 注入（与 LocalAppPrefs 同套路），
  聊天角标与管理页共读同一份
- 删除 platformLabels / personaModeLabels / moodLabels；MessageSource 与 AdminFormat
  改为查表，并保留各自原有的原样回落

为什么不留硬编码兜底表：没有登录就看不到任何消息，而权威表在登录前后即会拉取，
所以 last-good 快照几乎总是存在；留着硬编码表等于把「漂移」重新引进来，而且是无声的——
旧标签和新鲜标签长得一模一样。

不转换的：trace kind/status、memory scope、thinking.mode、WS session_busy 的 mode 集合——
它们都不在 /meta/enums 内，且原本就已按原样回落。

测试：115 全绿（88 → +27：MetaDtoRealPayload 8 / EnumCatalog 7 / EnumPrefs 3 /
MessageSource 8，AdminFormatTest 改写并 +1），其中 /meta/enums 与登录响应一样
用真实抓取的响应体做夹具。
 2026-10-04 13:19:34 +08:00
AskaEth 9f054aad28 fix(admin): 后台思考 conclusion 的 <p>/<action> 标记被原样显示 
现象：后台思考页把服务端 conclusion 里的 Web 端标记当纯文本打印，真机截图里
能看到 `<p></p><p></p><p>亲爱的…</p>` 和 `<action>轻轻戳了戳你</action>` 这样的
原始标记，部分记录开头还有一串空 `<p></p>`。

为什么：backthink 的 conclusion 与聊天消息是同一套标记，而 AdminBackthinkScreen
只是把它拼进 body 字符串，从未解析。

改法：复用项目已有的 domain/parse/ChatContentParser.parse()（不新写正则），
在 domain/admin/AdminFormat.kt 加纯函数 conclusionParagraphs()——按
head → 正文 → tail 产出段落、丢弃无有效片段的空段落（这才是消掉空 <p></p> 的关键）；
UI 侧新增 AdminRichTextCard，Text 正常渲染，Action/Narration 走聊天页同一套
灰斜体旁白样式（对齐 MessageBubble.AnnotationLine 的既有约定）。
AdminTextCard 行为不变（表头抽成共享的 AdminCardHeader），已回访记忆页确认无回归。

测试：新增 7 例（AdminFormatTest 13→20，用真实抓取的 conclusion 做夹具，并断言
渲染模型里不残留 <p>/</p>/<action>/< 或 > 任何一项），全套 88 例全绿。
 2026-10-04 13:02:09 +08:00
AskaEth acff289887 test(admin): 用真实后端响应锁定管理端 DTO 契约 
原先 AdminDtoDecodingTest 用的是手写的合成 JSON，等于拿「我以为的形状」自证，
证明不了真实契约。新增 AdminDtoRealPayloadTest，把 5 个管理端点的真实响应体
（登录后从本机 10942 实抓）过一遍生产用的 Json 实例。

顺带把真实数据里几个容易翻车的形状钉死：
- trace.durationNs 必须是 Long（真实 ~1.17e9 ns，超过 Int 上限就炸）——
  真实值恰好塞得进 Int，所以额外用一例 3e9 的边界值才真正证明它是 Long
- 根 span 没有 parentId 键 → null
- 未配置人格的 thinking 键完全不出现 → null（不得变成全零对象）
- persona 的 mode / memoryNamespace 是空串，而非缺键
- backthink.id 是 JSON 字符串（"487"），at 是数字（Unix 毫秒）
- props / events 同一个 map 里混着数字与字符串

为什么：C-2 的 DTO 此前只经「编译通过」这一层，从未被真实响应验证过。
真实响应全部一次解出，无需改动生产代码。

测试：新增 7 例（AdminDtoRealPayloadTest），全套 81 例全绿。
 2026-10-04 13:02:08 +08:00
AskaEth a7b3452e6d feat(admin): 新增 C-2 管理员只读监控（概览/人格/记忆/后台思考） 
侧边栏「管理员监控」进入的独立管理区 + 独立 Scaffold，四页全部只读，
不调用任何 /admin/* 写端点。

- data：AdminApi（5 条只读 GET）+ AdminDto + AdminRepository，
  经 ApiClientFactory 创建以复用既有 token / 401 处理
- domain：AdminAccess.kt 为权限真源（纯函数，便于单测）；
  AdminFormat.kt 把 RFC3339 与 Unix 毫秒两种时间形状分开解析
- ui：AdminHomeScreen 做成可加页的壳（加页 = AdminPage 加一条枚举），
  四个子页 + 统一失败态；列表项一律 PreferenceCard + BasicComponent
- RBAC：后端契约要求客户端自行降级（api-client §2.0），按矩阵分档——
  viewer 只能进概览/人格；入口禁用 + ViewModel 短路（不发请求）+
  服务端 403 也渲染「无权限」态，三层 fail-closed；
  任何失败都不渲染成「暂无数据」

为什么：M0–M5 + 设置页 C-1 已完成，C-2 是路线上的下一项；后端 5 个读端点
均已实现（非 501），且手机端后续要走「全功能管理」（后端工作小结 主线②，
凭据前置已完成），故管理区做成可扩展的壳而非只读死胡同。

测试：74 个单测全绿，其中新增 29 个
（AdminAccessTest 9 / AdminFormatTest 13 / AdminDtoDecodingTest 7）
 2026-10-03 21:31:09 +08:00
AskaEth 9bc45dc315 fix(ui): PreferenceCard 补 padding import 2026-09-08 23:17:06 +08:00
AskaEth 664fb2d9ed style(ui): PreferenceCard 补左右外边距 12dp 2026-09-08 23:16:23 +08:00
AskaEth cf291b58ab style(ui): 列表项加卡片容器；登出移到设置页底部；按钮改矢量图标 
新增 PreferenceCard（BasicComponent 本身无背景/圆角）；抽屉去掉登出、新建与删除改图标按钮；设置页返回改 ChevronBackward、底部新增登出图标。
 2026-09-08 23:13:00 +08:00
AskaEth df2a26701c style(ui): 列表项改用 Miuix BasicComponent（MD3 圆角卡片） 
抽屉的会话行/入口行、设置页的主题选项统一换成 BasicComponent，间距 8dp，选中态用 ✓ 标记。
 2026-09-08 22:55:29 +08:00
AskaEth 00856eeaf7 fix(ui): 浅色模式系统栏图标改深色；返回键逐层回退 
CyreneRoot 用 WindowInsetsControllerCompat 跟随主题切换系统栏明暗；ChatHomeScreen 为设置页与抽屉各加 BackHandler，避免直接回桌面。
 2026-09-08 22:45:20 +08:00
AskaEth 61214a18fa feat(settings): C 起步——App 设置页（主题/旁白/思维链默认展开/关于） 
新增 AppSettings（DataStore）与 LocalAppPrefs；CyreneRoot 按偏好决定 Miuix 主题模式并下发偏好；设置页从侧边栏进入，返回回聊天。旁白开关与思维链默认展开已接入渲染层。
 2026-09-08 22:41:37 +08:00
AskaEth 91117986e4 feat(chat): 改为文本选择模式，全选仅作用于当前气泡 
用 SelectionContainer 包住气泡/旁白/思维链/工具卡的正文，长按可拖选；移除长按整段复制的实现与其工具文件。
 2026-09-08 22:38:28 +08:00
AskaEth 33770d87a6 feat(chat): 回车发送 + 长按气泡复制 
输入框 imeAction=Send（回车即发送）；长按气泡体复制原文到剪贴板并 Toast 提示。
 2026-09-08 22:08:52 +08:00
AskaEth 0ea41f5815 fix(chat): 补 LaunchedEffect import 2026-09-08 21:57:43 +08:00
AskaEth 5a5b02f6fb feat(chat): 思维链保留 10 分钟并自动折叠；输入栏下方留白承载忙碌提示 
流式结束后把思维链挂到落库消息上，10 分钟后自动清除；ThinkingCard 在 active 变 false 时自动折叠，历史思维链默认折叠。输入栏底部预留 22dp 避开屏幕圆角，顶栏副标题只留连接状态，忙碌提示移到输入栏下方（带左缩进）。
 2026-09-08 21:56:55 +08:00
AskaEth 5975827aea fix(chat): Column 同时传 content 与尾随 lambda 导致编译失败 2026-09-08 21:50:54 +08:00
AskaEth 7faa604fd0 feat(chat): M4 思维链卡片 + 工具卡 + 图片 
thinking.*/tool_call.*/tool_execution.update 累积进流式状态并渲染为可折叠卡片（思维链默认展开）；历史消息的 thinking（来自 REST /messages）同样展示；image 用 Coil 3 加载。
 2026-09-08 21:48:40 +08:00
AskaEth 5ac0ea3c3b fix(chat): 输入法弹出时输入框被顶到顶部 
窗口默认 adjustUnspecified 会先做 pan，叠加 imePadding 后高度被算两次；改为 adjustResize。
 2026-09-08 21:42:36 +08:00
AskaEth 5d71c6a2ab fix(ui): 移除聊天页顶栏登出按钮；抽屉内容避开系统栏 
登出已收进侧边栏；抽屉面板保留全高背景，内容用 systemBars inset 避开状态栏/导航栏。
 2026-09-08 21:34:10 +08:00
AskaEth e72621db94 feat(sessions): M5 侧边栏抽屉 + 会话列表（切换/新建/删除） 
自研 MiuixDrawer（draggable+Animatable，关闭态不拦截触摸）；DataStore 持久化会话快照/序号映射/当前会话；SessionsViewModel 先快照后刷新；次级会话删除二次确认，主会话禁删。
 2026-09-08 21:29:24 +08:00
AskaEth e04995a84d fix(chat): 新消息自动跟随底部（微信/QQ 式） 
reverseLayout 会锚定原可见项，导致新消息插到视口外。改为：滚动结束时记录是否贴底（容差 64px），最新一项变化且处于跟随状态时 animateScrollToItem(0)；用户上滑查看历史时不再强制滚动。
 2026-09-08 21:16:49 +08:00
AskaEth 67ed0479e4 feat(chat): M3 发送与流式渲染 
输入框 + 发送（WS chat 上行，deviceId=voiceassist:cyrene:v1）；乐观消息先上屏，message_persisted 到达后按文本归一；message.start/delta/end + stream_end 走流式增量解析，末尾带光标；发送失败回滚文本到输入框。
 2026-09-08 21:09:37 +08:00
AskaEth a8a422c4e1 fix(chat): 来源角标改挂到消息组末尾 
角标应紧随它标注的那条消息（主人右下、昔涟左下），放在上方会显得在标注下一条。
 2026-09-08 21:06:42 +08:00
AskaEth 6323f89b5b fix(chat): 气泡间距 6dp；来源文案按角色区分「来自 / 发送至」 
主人发的显示「来自 X」，昔涟发的显示「发送至 X」。
 2026-09-08 21:04:32 +08:00
AskaEth 01b5f980a5 fix(chat): 来源角标移到消息组顶部；IM deviceId 显示友好平台名 
角标挂底部会视觉贴到下一条消息上；微信等 IM 的 deviceId 形如 <平台名>:<配置id>:<uid>，只取平台名显示「来自微信」。
 2026-09-08 21:03:33 +08:00
AskaEth 63fe9a12a6 feat(chat): 接入 <p> 多气泡与 <action>/<narration> 旁白渲染 
chat 模式消息按 <p> 拆成多个气泡；<action>/<narration> 解析为灰斜体小字依附气泡上/下；来源角标只在最后一条气泡显示一次。非 chat 模式原样渲染。
 2026-09-08 21:01:48 +08:00
AskaEth 171f6ff59a fix(net): 放行明文 HTTP，修复自部署地址报「网络不可用」 
Android 9+ 默认禁止 cleartext，OkHttp 抛 UnknownServiceException 被映射为无网。新增 network_security_config.xml（放行 cleartext + 信任用户 CA），并给该异常单独的提示文案。
 2026-09-08 20:56:06 +08:00
AskaEth 0587f5a45f chore: devdocs 移出版本控制 
设计/协作文档只保留在本地，不再随仓库分发。
 2026-09-08 20:50:40 +08:00
AskaEth 253913ad82 chore: 机器特定的构建配置移出仓库 
aapt2FromMavenOverride（ARM64 专用绝对路径）与 sdkDownload 移到本机 ~/.gradle/gradle.properties，仓库配置保持跨平台可用。
 2026-09-08 20:49:00 +08:00
AskaEth 84de51c7b7 feat: 初始化 Android 客户端（M0 骨架 + M1 登录 + M2 基础模块） 
M0：Gradle 9.7.1 / AGP 9.2.1 / Kotlin 2.4 / Miuix 0.9.3，minSdk 33，compileSdk 37。
M1：登录页（服务器地址可配、服务端/本地错误分流、EncryptedSharedPreferences、自动登录与静默重登、401 登出）。
M2 基础模块：消息内容解析器（<p>/<action>/<narration> + 流式增量）、WebSocket 客户端、REST 数据层与分页去重。
45 个单元测试全绿，真机验证通过（登录页 + 启动图标）。
devdocs/ 收录设计文档、前后端协同事项与细化方案。
 2026-09-08 20:40:58 +08:00
345 changed files with 48646 additions and 9778 deletions
Expand all files Collapse all files

No files matched your search

.gitignore
+8 -30
View File
@@ -1,36 +1,14 @@
# ---> Android
# Gradle files
*.iml
.gradle/
build/
# Local configuration file (sdk path, etc)
.kotlin/
# 本机开发凭据（主人授权落地的测试用 key 等）——只在本机，绝不进仓库
dev-secrets.local.md
local.properties
# Log/OS Files
*.log
# Android Studio generated files and folders
.idea/
.DS_Store
captures/
.externalNativeBuild/
.cxx/
*.apk
output.json
# IntelliJ
*.iml
.idea/
misc.xml
deploymentTargetDropDown.xml
render.experimental.xml
# Keystore files
*.jks
*.keystore
# Google Services (e.g. APIs or Firebase)
google-services.json
# Android Profiling
*.hprof
keystore.properties
# 主人从手机丢进仓库根当素材用的图（例如换图标用的原图）——只用不存，绝不进仓库
/IMG_*.png
LICENSE
-73
View File
@@ -1,73 +0,0 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
Copyright 2026 AskaEth
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
README.md
-182
View File
@@ -1,182 +0,0 @@
# Cyrene for Android
昔涟在安卓设备上的载体 —— 随时随地与昔涟对话、操控 IoT 设备、接收实时通知。
## 概述
Cyrene for Android 是 [Cyrene（昔涟）](https://github.com/Cyrene/Cyrene) 项目的官方 Android 客户端。Cyrene 是一个开源的基于 LLM 平台的智能体，提供多人格对话、IoT 设备操控、记忆管理、自动化规则、知识库、语音交互等功能。
Android 客户端的目标是成为用户的**默认语音助手**，完全替代系统自带的助手（Google Assistant / Bixby 等），同时提供：
- **系统级语音助手** — 注册为 `VoiceInteractionService`，可通过长按 Home / 侧滑呼出
- **语音唤醒** — 息屏热词唤醒、免提交互（类似 "Hey Google"，使用 "昔涟" 等唤醒词）
- **随时对话** — 通过文字或语音与昔涟交流
- **IoT 控制** — 远程操控家中的智能设备
- **实时通知** — 接收昔涟的主动消息、提醒、IoT 状态变更
- **后台连接** — 即使 APP 在后台，仍保持通知推送与语音服务就绪
## 开发状态
> **当前阶段**：项目初始化，尚未开始正式开发。
根据主项目的[开发路线图](../docs/dev-plan/00-development-roadmap.md)，Android 客户端计划在 **Phase 5（v1.5 → v2.0）** 开始开发，预计时间窗口为 **2027 Q2-Q3**。
## 技术栈 (规划)
| 层 | 技术 |
|----|------|
| 语言 | Kotlin |
| UI 框架 | Jetpack Compose + Material Design 3 |
| 架构 | MVVM + Repository |
| 网络 | OkHttp / Retrofit + WebSocket |
| 本地存储 | Room (SQLite) + DataStore |
| 推送 | FCM (Firebase Cloud Messaging) |
| 语音 | VoiceInteractionService + 热词唤醒 + STT + TTS |
| 构建 | Gradle (Kotlin DSL) |
## 功能路线图
- [ ] 用户认证与登录
- [ ] 实时文字对话 (WebSocket)
- [ ] VoiceInteractionService 注册（替换系统语音助手）
- [ ] 间接启动悬浮窗（VoiceInteractionSession 全屏覆盖层）
- [ ] 热词唤醒（息屏 / 亮屏）+ 唤醒词自定义
- [ ] 语音识别 (STT)
- [ ] 语音合成 (TTS)
- [ ] IoT 设备控制面板
- [ ] 推送通知 (FCM)
- [ ] 后台连接与通知
- [ ] 锁屏 / 息屏语音交互
- [ ] PWA 保底方案 (短期替代)
## 交互模式
APP 有两种界面呈现方式，根据启动来源自动切换：
| 启动方式 | 界面模式 | 说明 |
|---------|---------|------|
| 桌面图标 / 最近任务 | **全屏 Activity** | 常规 APP 模式，完整功能入口 |
| 语音唤醒 / 长按 Home / 侧滑 / 长按电源键 / 耳机按键 | **悬浮窗 (VoiceInteractionSession)** | 全屏覆盖层，半透明背景透出底层 APP，不影响当前任务栈 |
悬浮窗模式的要点：
- 借助 `VoiceInteractionSession` 系统窗口，不压入 Activity 返回栈
- 对话结束后窗口收起，用户回到触发前的界面
- 底层 APP 内容半透明可见（模糊遮罩），让用户保持上下文感知
- 窗口高度自适应对话内容，类似 Google Assistant 的卡片式覆盖
## 设计规范
- **设计语言**：Material Design 3 (Material You)
- **主题**：动态配色（Dynamic Color），跟随系统壁纸或手动选择主题色
- **暗黑模式**：支持 Light / Dark 双主题，跟随系统或手动切换
- **组件**：全面使用 `androidx.compose.material3` 组件库
- **图标**：Material Icons + 自定义图标
- **动效**：遵循 MD3 动效规范（过渡动画、涟漪效果、Shared Elements）
- **字体**：系统默认字体（Roboto / Google Sans），支持动态字体缩放
## 项目结构 (规划)
```
android/
├── app/
│ ├── src/main/
│ │ ├── java/com/cyrene/app/
│ │ │ ├── ui/ # Compose UI 层
│ │ │ ├── viewmodel/ # ViewModel 层
│ │ │ ├── repository/ # 数据仓库层
│ │ │ ├── data/ # 数据模型 & API 接口
│ │ │ ├── service/ # VoiceInteractionService & WebSocket & FCM
│ │ │ ├── voice/ # 热词唤醒 (Hotword) & STT & TTS
│ │ │ └── di/ # 依赖注入
│ │ └── res/ # 资源文件
│ └── build.gradle.kts
├── build.gradle.kts
├── settings.gradle.kts
└── gradle.properties
```
## 环境要求
- Android Studio Hedgehog (2023.1.1) 或更高版本
- Kotlin 2.0+
- JDK 17+
- Android SDK (target: 34+, min: 26+)
## 网络配置（中国大陆用户）
Gradle、Google Maven、Maven Central 等服务器在国内访问缓慢或不可达，首次同步前需配置镜像。
### Gradle Wrapper
`gradle/wrapper/gradle-wrapper.properties`：
```properties
# 将 services.gradle.org 替换为腾讯/阿里镜像
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip
# 或阿里: https\://mirrors.aliyun.com/macports/distfiles/gradle/gradle-8.7-bin.zip
```
### 仓库镜像
`settings.gradle.kts` 顶部添加：
```kotlin
pluginManagement {
repositories {
maven { url = uri("https://mirrors.cloud.tencent.com/gradle/plugins") }
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") }
google()
mavenCentral()
}
}
```
### Gradle 属性
`gradle.properties`：
```properties
# HTTP 代理（如使用 Clash/V2Ray，通常不需要）
# systemProp.http.proxyHost=127.0.0.1
# systemProp.http.proxyPort=7890
# systemProp.https.proxyHost=127.0.0.1
# systemProp.https.proxyPort=7890
```
### Android SDK Proxy
若 Android SDK Manager 也下载缓慢，可在 Android Studio 中设置：
**Settings → Appearance & Behavior → System Settings → HTTP Proxy**
配置为 `mirrors.cloud.tencent.com` 或 `mirrors.neusoft.edu.cn`，端口 `80`。
## 快速开始
> 项目尚未包含可构建的源码，以下为后续开发的参考步骤。
1. 用 Android Studio 打开 `android/` 目录
2. 按上述"网络配置"替换国内镜像
3. 等待 Gradle 同步完成
4. 启动主项目后端服务（参考[主项目 README](../README.md)）
5. 在 `local.properties` 中配置 `baseUrl` 指向 Gateway 地址
6. 选择模拟器或设备，点击 Run
## 相关链接
- [Cyrene 主项目](../) — 后端服务、前端、部署文档
- [开发路线图](../docs/dev-plan/00-development-roadmap.md)
- [多平台接入方案](../docs/dev-plan/03-multi-platform-integration.md)
- [语音系统计划](../docs/dev-plan/04-voice-system-plan.md)
## License
Apache-2.0
app/build.gradle.kts
+36 -75
View File
@@ -1,58 +1,30 @@
import java.util.Properties
plugins {
alias(libs.plugins.android.application)
alias(libs.plugins.kotlin.android)
alias(libs.plugins.kotlin.compose)
alias(libs.plugins.ksp)
}
val keystorePropertiesFile = rootProject.file("keystore.properties")
val keystoreProperties = Properties()
if (keystorePropertiesFile.exists()) {
keystoreProperties.load(keystorePropertiesFile.inputStream())
alias(libs.plugins.kotlin.serialization)
}
android {
signingConfigs {
if (keystorePropertiesFile.exists()) {
create("release") {
storeFile = rootProject.file(keystoreProperties["storeFile"] as String)
storePassword = keystoreProperties["storePassword"] as String
keyAlias = keystoreProperties["keyAlias"] as String
keyPassword = keystoreProperties["keyPassword"] as String
}
}
}
namespace = "top.yeij.cyrene"
compileSdk = 36
compileSdk = 37
buildToolsVersion = "37.0.0"
defaultConfig {
applicationId = "top.yeij.cyrene"
minSdk = 26
targetSdk = 36
minSdk = 33
targetSdk = 37
versionCode = 1
versionName = "0.1.0"
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
}
buildTypes {
release {
if (keystorePropertiesFile.exists()) {
signingConfig = signingConfigs.getByName("release")
}
isMinifyEnabled = true
isMinifyEnabled = false
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
"proguard-rules.pro",
)
}
debug {
isMinifyEnabled = false
}
}
compileOptions {
@@ -60,58 +32,47 @@ android {
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}
buildFeatures {
compose = true
buildConfig = true
}
}
kotlin {
compilerOptions {
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
}
}
dependencies {
// Compose BOM
val composeBom = platform(libs.compose.bom)
implementation(composeBom)
implementation(libs.compose.ui)
implementation(libs.compose.ui.graphics)
implementation(libs.compose.ui.tooling.preview)
implementation(libs.compose.material3)
implementation(libs.compose.material.icons)
debugImplementation(libs.compose.ui.tooling)
implementation(libs.androidx.core.ktx)
implementation(libs.androidx.lifecycle.runtime.ktx)
implementation(libs.androidx.lifecycle.viewmodel.compose)
implementation(libs.androidx.activity.compose)
// Activity & Navigation
implementation(libs.compose.activity)
implementation(libs.compose.navigation)
implementation(platform(libs.androidx.compose.bom))
implementation(libs.androidx.compose.ui)
implementation(libs.androidx.compose.ui.graphics)
implementation(libs.androidx.compose.ui.tooling.preview)
implementation(libs.androidx.compose.foundation)
// Lifecycle
implementation(libs.lifecycle.runtime)
implementation(libs.lifecycle.viewmodel)
implementation(libs.miuix.ui)
implementation(libs.miuix.icons)
implementation(libs.miuix.preference)
// Room
implementation(libs.room.runtime)
implementation(libs.room.ktx)
ksp(libs.room.compiler)
// Network
implementation(libs.retrofit)
implementation(libs.retrofit.gson)
implementation(libs.retrofit.kotlinx.serialization)
implementation(libs.okhttp)
implementation(libs.okhttp.logging)
implementation(libs.kotlinx.serialization.json)
implementation(libs.kotlinx.coroutines.android)
implementation(libs.androidx.security.crypto)
implementation(libs.androidx.datastore.preferences)
implementation(libs.coil.compose)
implementation(libs.coil.network.okhttp)
// Koin DI
implementation(libs.koin.android)
implementation(libs.koin.compose)
debugImplementation(libs.androidx.compose.ui.tooling)
// DataStore
implementation(libs.datastore)
// Coroutines
implementation(libs.coroutines)
// Core
implementation(libs.core.ktx)
// Biometric
implementation(libs.biometric)
testImplementation(libs.junit)
}
app/proguard-rules.pro
Vendored
+9 -26
View File
@@ -1,27 +1,10 @@
# Cyrene ProGuard Rules
# kotlinx-serialization：保留 @Serializable 类的序列化器（M2 起启用）
-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.**
# Retrofit
-keepattributes Signature
-keepattributes *Annotation*
-keep class top.yeij.cyrene.data.remote.dto.** { *; }
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
# Gson
-keep class com.google.gson.** { *; }
-keepattributes EnclosingMethod
# OkHttp
-dontwarn okhttp3.**
-dontwarn okio.**
# Room
-keep class * extends androidx.room.RoomDatabase
-dontwarn androidx.room.paging.**
# Koin
-keep class org.koin.** { *; }
# Coroutines
-keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
-keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
-keepclassmembers class **$$serializer {
*** descriptor;
}
-keepclasseswithmembers class ** {
kotlinx.serialization.KSerializer serializer(...);
}
app/src/main/AndroidManifest.xml
+41 -70
View File
@@ -1,89 +1,60 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<!-- 网络 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 语音助手核心 -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.CAPTURE_AUDIO_HOTWORD" />
<!-- 后台服务 -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<!-- 推送 -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<!-- 锁屏交互 -->
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
<!-- 查询其他应用（检查默认助手设置） -->
<queries>
<intent>
<action android:name="android.service.voice.VoiceInteractionService" />
</intent>
</queries>
<application
android:name=".CyreneApplication"
android:allowBackup="true"
android:name=".app.CyreneApplication"
android:allowBackup="false"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:networkSecurityConfig="@xml/network_security_config"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/Theme.Cyrene"
android:usesCleartextTraffic="true">
android:theme="@style/Theme.Cyrene">
<!-- 全屏主界面 -->
<!--
launchMode="singleTop"：App 已经开着时从别的 App 分享过来，系统不再新建一个实例，
改成回调 onNewIntent（见 MainActivity）。不写它就会起第二个 Activity 实例、
两个实例各持一套 ViewModel / socket。
-->
<activity
android:name=".MainActivity"
android:name=".app.MainActivity"
android:exported="true"
android:launchMode="singleTask"
android:theme="@style/Theme.Cyrene">
android:label="@string/app_name"
android:launchMode="singleTop"
android:windowSoftInputMode="adjustResize">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<!--
分享入口：只声明本端真能落地的两类 MIME（纯文本 / 图片）。
刻意不声明 */*——对话路径上今天没有「文件」这个表示（协同文档 02/F1 的三缺），
声明了就等于给出一个点进去必然失败的入口。标签沿用应用名（活动不设自己的
label / icon 时，分享菜单取的就是 Cyrene 的名字与启动图标）。
-->
<intent-filter>
<action android:name="android.intent.action.SEND" />
<category android:name="android.intent.category.DEFAULT" />
<data android:mimeType="text/plain" />
<data android:mimeType="image/*" />
</intent-filter>
<!-- 多图分享只收图片：多条纯文本的 EXTRA_TEXT（SEND_MULTIPLE + text/plain）本端不接。 -->
<intent-filter>
<action android:name="android.intent.action.SEND_MULTIPLE" />
<category android:name="android.intent.category.DEFAULT" />
<data android:mimeType="image/*" />
</intent-filter>
</activity>
<!-- VoiceInteractionService：系统语音助手 -->
<service
android:name=".service.CyreneVoiceInteractionService"
android:exported="true"
android:permission="android.permission.BIND_VOICE_INTERACTION">
<meta-data
android:name="android.voice_interaction"
android:resource="@xml/voice_interaction_config" />
<intent-filter>
<action android:name="android.service.voice.VoiceInteractionService" />
</intent-filter>
</service>
<!-- VoiceInteractionSessionService -->
<service
android:name=".service.CyreneSessionService"
android:exported="true"
android:permission="android.permission.BIND_VOICE_INTERACTION" />
<!-- AccessibilityService：读取屏幕内容 -->
<service
android:name=".service.CyreneAccessibilityService"
android:exported="true"
android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
<intent-filter>
<action android:name="android.accessibilityservice.AccessibilityService" />
</intent-filter>
<meta-data
android:name="android.accessibilityservice"
android:resource="@xml/accessibility_config" />
</service>
<!-- FileProvider：日志分享 -->
<!--
附件预览的「用其它应用打开 / 保存」出口：`cacheDir/documents/` 下的文件要交给
系统里别的 App 读，就必须是 content:// 而不是 file://——API 24 起把 file:// 交出去
会直接抛 FileUriExposedException（且 StrictMode 下同样致命）。
路径范围见 res/xml/file_paths.xml：只暴露 cacheDir/documents/ 这一层，
exported="false" + 按次授权（grantUriPermissions）保证这份缓存不对外常开。
-->
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
app/src/main/java/top/yeij/cyrene/CyreneApplication.kt
-100
View File
@@ -1,100 +0,0 @@
package top.yeij.cyrene
import android.app.Activity
import android.app.Application
import android.os.Bundle
import android.util.Log
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.launch
import org.koin.android.ext.koin.androidContext
import org.koin.core.context.GlobalContext
import org.koin.core.context.startKoin
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.AuthInterceptor
import top.yeij.cyrene.data.remote.DynamicUrlInterceptor
import top.yeij.cyrene.data.repository.ChatRepositoryImpl
import top.yeij.cyrene.di.appModule
import top.yeij.cyrene.util.NotificationHelper
import top.yeij.cyrene.util.RuntimeLog
import java.util.concurrent.atomic.AtomicInteger
class CyreneApplication : Application() {
private val initScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
private val activityCount = AtomicInteger(0)
@Volatile
private var notificationHelper: NotificationHelper? = null
override fun onCreate() {
super.onCreate()
RuntimeLog.general("app", "Application onCreate")
startKoin {
androidContext(this@CyreneApplication)
modules(appModule)
}
// Track foreground/background state
registerActivityLifecycleCallbacks(object : ActivityLifecycleCallbacks {
override fun onActivityStarted(activity: Activity) {
if (activityCount.incrementAndGet() == 1) {
RuntimeLog.general("app", "App in foreground")
notificationHelper?.cancelAll()
getRepo()?.onAppForeground()
}
}
override fun onActivityStopped(activity: Activity) {
if (activityCount.decrementAndGet() == 0) {
RuntimeLog.general("app", "App in background")
getRepo()?.onAppBackground()
}
}
override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
override fun onActivityResumed(activity: Activity) {}
override fun onActivityPaused(activity: Activity) {}
override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
override fun onActivityDestroyed(activity: Activity) {}
})
// Set up background notification callback once Koin is ready
initScope.launch {
val helper = NotificationHelper(this@CyreneApplication)
notificationHelper = helper
val repo = getRepo()
repo?.setNotificationCallback { message ->
helper.showMessageNotification(message)
}
}
initScope.launch {
val koin = GlobalContext.get()
val prefs: PreferencesDataStore = koin.get()
val urlInterceptor: DynamicUrlInterceptor = koin.get()
val authInterceptor: AuthInterceptor = koin.get()
prefs.baseUrl.firstOrNull()?.let { url ->
if (url.isNotBlank()) urlInterceptor.baseUrl = url
}
prefs.token.firstOrNull()?.let { token ->
authInterceptor.token = token
}
}
}
private fun getRepo(): ChatRepositoryImpl? {
return try {
GlobalContext.get().get()
} catch (_: Exception) {
null
}
}
companion object {
private const val TAG = "CyreneApp"
}
}
app/src/main/java/top/yeij/cyrene/MainActivity.kt
-78
View File
@@ -1,78 +0,0 @@
package top.yeij.cyrene
import android.content.ComponentName
import android.content.Intent
import android.os.Bundle
import android.provider.Settings
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.navigation.compose.rememberNavController
import org.koin.compose.koinInject
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.service.CyreneVoiceInteractionService
import top.yeij.cyrene.ui.navigation.CyreneNavGraph
import top.yeij.cyrene.ui.navigation.Routes
import top.yeij.cyrene.ui.theme.CyreneTheme
import top.yeij.cyrene.util.Constants
class MainActivity : ComponentActivity() {
private val isDefaultAssistant = mutableStateOf(false)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
isDefaultAssistant.value = checkIsDefaultAssistant()
setContent {
val prefs: PreferencesDataStore = koinInject()
val themeMode by prefs.themeMode.collectAsState(initial = null)
val darkTheme = when (themeMode) {
"light" -> false
"dark" -> true
else -> isSystemInDarkTheme()
}
CyreneTheme(darkTheme = darkTheme) {
val navController = rememberNavController()
CyreneNavGraph(
navController = navController,
startDestination = Routes.MAIN,
isDefaultAssistant = isDefaultAssistant.value,
onOpenAssistantSettings = { openAssistantSettings() },
)
}
}
}
override fun onResume() {
super.onResume()
isDefaultAssistant.value = checkIsDefaultAssistant()
}
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
setIntent(intent)
}
private fun checkIsDefaultAssistant(): Boolean {
// Standard Android check
val flat = ComponentName(this, CyreneVoiceInteractionService::class.java).flattenToString()
val current = Settings.Secure.getString(contentResolver, "voice_interaction_service")
if (current == flat) return true
// Fallback for COS and other custom OS: check persisted flag from service
if (CyreneVoiceInteractionService.wasEverActive(this)) return true
return false
}
private fun openAssistantSettings() {
startActivity(Intent(Settings.ACTION_VOICE_INPUT_SETTINGS))
}
}
app/src/main/java/top/yeij/cyrene/data/local/AppDatabase.kt
-39
View File
@@ -1,39 +0,0 @@
package top.yeij.cyrene.data.local
import android.content.Context
import androidx.room.Database
import androidx.room.Room
import androidx.room.RoomDatabase
import top.yeij.cyrene.data.local.dao.ConversationDao
import top.yeij.cyrene.data.local.dao.MessageDao
import top.yeij.cyrene.data.local.entity.ConversationEntity
import top.yeij.cyrene.data.local.entity.MessageEntity
@Database(
entities = [ConversationEntity::class, MessageEntity::class],
version = 1,
exportSchema = false,
)
abstract class AppDatabase : RoomDatabase() {
abstract fun conversationDao(): ConversationDao
abstract fun messageDao(): MessageDao
companion object {
@Volatile
private var INSTANCE: AppDatabase? = null
fun getInstance(context: Context): AppDatabase {
return INSTANCE ?: synchronized(this) {
INSTANCE ?: Room.databaseBuilder(
context.applicationContext,
AppDatabase::class.java,
"cyrene.db",
)
.fallbackToDestructiveMigration()
.build()
.also { INSTANCE = it }
}
}
}
}
app/src/main/java/top/yeij/cyrene/data/local/PreferencesDataStore.kt
-138
View File
@@ -1,138 +0,0 @@
package top.yeij.cyrene.data.local
import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
private val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "cyrene_prefs")
class PreferencesDataStore(private val context: Context) {
companion object {
private val KEY_TOKEN = stringPreferencesKey("jwt_token")
private val KEY_REFRESH_TOKEN = stringPreferencesKey("refresh_token")
private val KEY_BASE_URL = stringPreferencesKey("base_url")
private val KEY_THEME = stringPreferencesKey("theme_mode")
private val KEY_WAKE_WORD = stringPreferencesKey("wake_word")
private val KEY_USERNAME = stringPreferencesKey("username")
private val KEY_CLIENT_ID = stringPreferencesKey("client_id")
private val KEY_DEVICE_NAME = stringPreferencesKey("device_name")
private val KEY_CURRENT_SESSION_ID = stringPreferencesKey("current_session_id")
private val KEY_DASHSCOPE_API_KEY = stringPreferencesKey("dashscope_api_key")
private val KEY_DASHSCOPE_ENDPOINT = stringPreferencesKey("dashscope_endpoint")
private val KEY_DASHSCOPE_MODEL = stringPreferencesKey("dashscope_model")
private val KEY_LAST_CLEARED_TIMESTAMP = stringPreferencesKey("last_cleared_timestamp")
private val KEY_PROFILE_USER_ID = stringPreferencesKey("profile_user_id")
private val KEY_PROFILE_NICKNAME = stringPreferencesKey("profile_nickname")
private val KEY_PROFILE_IS_ADMIN = stringPreferencesKey("profile_is_admin")
private val KEY_PROFILE_CREATED_AT = stringPreferencesKey("profile_created_at")
private val KEY_AUTO_SCREEN_CONTEXT = booleanPreferencesKey("auto_screen_context")
}
val token: Flow<String?> = context.dataStore.data.map { it[KEY_TOKEN] }
val refreshToken: Flow<String?> = context.dataStore.data.map { it[KEY_REFRESH_TOKEN] }
val baseUrl: Flow<String?> = context.dataStore.data.map { it[KEY_BASE_URL] }
val themeMode: Flow<String?> = context.dataStore.data.map { it[KEY_THEME] }
val wakeWord: Flow<String?> = context.dataStore.data.map { it[KEY_WAKE_WORD] }
val username: Flow<String?> = context.dataStore.data.map { it[KEY_USERNAME] }
val clientId: Flow<String?> = context.dataStore.data.map { it[KEY_CLIENT_ID] }
val deviceName: Flow<String?> = context.dataStore.data.map { it[KEY_DEVICE_NAME] }
val currentSessionId: Flow<String?> = context.dataStore.data.map { it[KEY_CURRENT_SESSION_ID] }
val dashScopeApiKey: Flow<String?> = context.dataStore.data.map { it[KEY_DASHSCOPE_API_KEY] }
val dashScopeEndpoint: Flow<String?> = context.dataStore.data.map { it[KEY_DASHSCOPE_ENDPOINT] }
val dashScopeModel: Flow<String?> = context.dataStore.data.map { it[KEY_DASHSCOPE_MODEL] }
suspend fun saveToken(token: String) {
context.dataStore.edit { it[KEY_TOKEN] = token }
}
suspend fun saveRefreshToken(token: String) {
context.dataStore.edit { it[KEY_REFRESH_TOKEN] = token }
}
suspend fun saveBaseUrl(url: String) {
context.dataStore.edit { it[KEY_BASE_URL] = url }
}
suspend fun saveThemeMode(mode: String) {
context.dataStore.edit { it[KEY_THEME] = mode }
}
suspend fun saveWakeWord(word: String) {
context.dataStore.edit { it[KEY_WAKE_WORD] = word }
}
suspend fun saveUsername(username: String) {
context.dataStore.edit { it[KEY_USERNAME] = username }
}
suspend fun saveDashScopeApiKey(key: String) {
context.dataStore.edit { it[KEY_DASHSCOPE_API_KEY] = key }
}
suspend fun saveDashScopeEndpoint(endpoint: String) {
context.dataStore.edit { it[KEY_DASHSCOPE_ENDPOINT] = endpoint }
}
suspend fun saveDashScopeModel(model: String) {
context.dataStore.edit { it[KEY_DASHSCOPE_MODEL] = model }
}
suspend fun saveClientId(id: String) {
context.dataStore.edit { it[KEY_CLIENT_ID] = id }
}
suspend fun saveDeviceName(name: String) {
context.dataStore.edit { it[KEY_DEVICE_NAME] = name }
}
suspend fun saveCurrentSessionId(id: String) {
context.dataStore.edit { it[KEY_CURRENT_SESSION_ID] = id }
}
val lastClearedTimestamp: Flow<String?> = context.dataStore.data.map { it[KEY_LAST_CLEARED_TIMESTAMP] }
suspend fun saveLastClearedTimestamp(timestamp: Long) {
context.dataStore.edit { it[KEY_LAST_CLEARED_TIMESTAMP] = timestamp.toString() }
}
// Cached profile for offline / local-first rendering
val profileUserId: Flow<String?> = context.dataStore.data.map { it[KEY_PROFILE_USER_ID] }
val profileNickname: Flow<String?> = context.dataStore.data.map { it[KEY_PROFILE_NICKNAME] }
val profileIsAdmin: Flow<String?> = context.dataStore.data.map { it[KEY_PROFILE_IS_ADMIN] }
val profileCreatedAt: Flow<String?> = context.dataStore.data.map { it[KEY_PROFILE_CREATED_AT] }
suspend fun saveProfileCache(userId: String, nickname: String, isAdmin: Boolean, createdAt: String) {
context.dataStore.edit {
it[KEY_PROFILE_USER_ID] = userId
it[KEY_PROFILE_NICKNAME] = nickname
it[KEY_PROFILE_IS_ADMIN] = isAdmin.toString()
it[KEY_PROFILE_CREATED_AT] = createdAt
}
}
val autoScreenContext: Flow<Boolean> = context.dataStore.data.map { it[KEY_AUTO_SCREEN_CONTEXT] ?: false }
suspend fun saveAutoScreenContext(enabled: Boolean) {
context.dataStore.edit { it[KEY_AUTO_SCREEN_CONTEXT] = enabled }
}
suspend fun clearProfileCache() {
context.dataStore.edit {
it.remove(KEY_PROFILE_USER_ID)
it.remove(KEY_PROFILE_NICKNAME)
it.remove(KEY_PROFILE_IS_ADMIN)
it.remove(KEY_PROFILE_CREATED_AT)
}
}
suspend fun clearAll() {
context.dataStore.edit { it.clear() }
}
}
app/src/main/java/top/yeij/cyrene/data/local/dao/ConversationDao.kt
-30
View File
@@ -1,30 +0,0 @@
package top.yeij.cyrene.data.local.dao
import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import kotlinx.coroutines.flow.Flow
import top.yeij.cyrene.data.local.entity.ConversationEntity
@Dao
interface ConversationDao {
@Query("SELECT * FROM conversations ORDER BY updatedAt DESC")
fun getAll(): Flow<List<ConversationEntity>>
@Query("SELECT * FROM conversations ORDER BY updatedAt DESC")
suspend fun getAllSnapshot(): List<ConversationEntity>
@Query("SELECT * FROM conversations WHERE id = :id")
suspend fun getById(id: String): ConversationEntity?
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun upsert(conversation: ConversationEntity)
@Query("DELETE FROM conversations WHERE id = :id")
suspend fun deleteById(id: String)
@Query("DELETE FROM conversations")
suspend fun deleteAll()
}
app/src/main/java/top/yeij/cyrene/data/local/dao/MessageDao.kt
-33
View File
@@ -1,33 +0,0 @@
package top.yeij.cyrene.data.local.dao
import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import kotlinx.coroutines.flow.Flow
import top.yeij.cyrene.data.local.entity.MessageEntity
@Dao
interface MessageDao {
@Query("SELECT * FROM messages WHERE conversationId = :conversationId ORDER BY timestamp ASC")
fun getByConversation(conversationId: String): Flow<List<MessageEntity>>
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun upsert(message: MessageEntity)
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun upsertAll(messages: List<MessageEntity>)
@Query("DELETE FROM messages WHERE conversationId = :conversationId")
suspend fun deleteByConversation(conversationId: String)
@Query("UPDATE messages SET conversationId = :newId WHERE conversationId = :oldId")
suspend fun migrateConversationId(oldId: String, newId: String)
@Query("DELETE FROM messages WHERE id = :id")
suspend fun deleteById(id: String)
@Query("DELETE FROM messages")
suspend fun deleteAll()
}
app/src/main/java/top/yeij/cyrene/data/local/entity/ConversationEntity.kt
-14
View File
@@ -1,14 +0,0 @@
package top.yeij.cyrene.data.local.entity
import androidx.room.Entity
import androidx.room.PrimaryKey
@Entity(tableName = "conversations")
data class ConversationEntity(
@PrimaryKey val id: String,
val title: String,
val lastMessage: String?,
val lastMessageType: String?,
val updatedAt: Long,
val createdAt: Long,
)
app/src/main/java/top/yeij/cyrene/data/local/entity/MessageEntity.kt
-27
View File
@@ -1,27 +0,0 @@
package top.yeij.cyrene.data.local.entity
import androidx.room.Entity
import androidx.room.ForeignKey
import androidx.room.Index
import androidx.room.PrimaryKey
@Entity(
tableName = "messages",
foreignKeys = [
ForeignKey(
entity = ConversationEntity::class,
parentColumns = ["id"],
childColumns = ["conversationId"],
onDelete = ForeignKey.CASCADE,
),
],
indices = [Index("conversationId")],
)
data class MessageEntity(
@PrimaryKey val id: String,
val conversationId: String,
val role: String,
val content: String,
val msgType: String,
val timestamp: Long,
)
app/src/main/java/top/yeij/cyrene/data/remote/ApiService.kt
-62
View File
@@ -1,62 +0,0 @@
package top.yeij.cyrene.data.remote
import retrofit2.Response
import retrofit2.http.Body
import retrofit2.http.DELETE
import retrofit2.http.GET
import retrofit2.http.POST
import retrofit2.http.Path
import retrofit2.http.Query
import top.yeij.cyrene.data.remote.dto.AuthRequest
import top.yeij.cyrene.data.remote.dto.AuthResponse
import top.yeij.cyrene.data.remote.dto.ProfileResponse
import top.yeij.cyrene.data.remote.dto.CreateSessionRequest
import top.yeij.cyrene.data.remote.dto.DeviceDto
import top.yeij.cyrene.data.remote.dto.IoTControlRequest
import top.yeij.cyrene.data.remote.dto.MessagesListResponse
import top.yeij.cyrene.data.remote.dto.RefreshTokenRequest
import top.yeij.cyrene.data.remote.dto.SessionDto
import top.yeij.cyrene.data.remote.dto.SessionsListResponse
interface ApiService {
// Auth
@POST("api/v1/auth/login")
suspend fun login(@Body request: AuthRequest): Response<AuthResponse>
@POST("api/v1/auth/refresh")
suspend fun refreshToken(@Body request: RefreshTokenRequest): Response<AuthResponse>
@GET("api/v1/profile")
suspend fun getProfile(): Response<ProfileResponse>
// Sessions
@GET("api/v1/sessions")
suspend fun getSessions(): Response<SessionsListResponse>
@POST("api/v1/sessions")
suspend fun createSession(@Body request: CreateSessionRequest): Response<SessionDto>
@DELETE("api/v1/sessions/{id}")
suspend fun deleteSession(@Path("id") id: String): Response<Unit>
@DELETE("api/v1/sessions/{id}/messages")
suspend fun clearSessionMessages(@Path("id") sessionId: String): Response<Unit>
@GET("api/v1/sessions/{id}/messages")
suspend fun getSessionMessages(
@Path("id") sessionId: String,
@Query("limit") limit: Int = 50,
@Query("offset") offset: Int = 0,
): Response<MessagesListResponse>
// IoT — 注意：网关 API 文档未列出 IoT 端点，需确认网关是否代理了 /api/v1/iot/*
@GET("api/v1/iot/devices")
suspend fun getDevices(): Response<List<DeviceDto>>
@POST("api/v1/iot/devices/{id}/control")
suspend fun controlDevice(
@Path("id") deviceId: String,
@Body request: IoTControlRequest,
): Response<DeviceDto>
}
app/src/main/java/top/yeij/cyrene/data/remote/AuthInterceptor.kt
-21
View File
@@ -1,21 +0,0 @@
package top.yeij.cyrene.data.remote
import okhttp3.Interceptor
import okhttp3.Response
class AuthInterceptor : Interceptor {
@Volatile
var token: String? = null
override fun intercept(chain: Interceptor.Chain): Response {
val request = if (!token.isNullOrEmpty()) {
chain.request().newBuilder()
.addHeader("Authorization", "Bearer $token")
.build()
} else {
chain.request()
}
return chain.proceed(request)
}
}
app/src/main/java/top/yeij/cyrene/data/remote/DynamicUrlInterceptor.kt
-37
View File
@@ -1,37 +0,0 @@
package top.yeij.cyrene.data.remote
import android.util.Log
import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
import okhttp3.Interceptor
import okhttp3.Response
class DynamicUrlInterceptor : Interceptor {
companion object {
private const val TAG = "DynamicUrlInterceptor"
}
@Volatile
var baseUrl: String = "http://10.0.2.2:8080/"
override fun intercept(chain: Interceptor.Chain): Response {
val originalRequest = chain.request()
val originalUrl = originalRequest.url
val targetBase = baseUrl.trimEnd('/')
val parsed = targetBase.toHttpUrlOrNull()
if (parsed == null) {
Log.e(TAG, "Invalid baseUrl: '$baseUrl'")
return chain.proceed(chain.request())
}
val newUrl = originalUrl.newBuilder()
.scheme(parsed.scheme)
.host(parsed.host)
.port(parsed.port)
.build()
Log.d(TAG, "Rewriting ${originalUrl} → $newUrl (base: $targetBase)")
return chain.proceed(originalRequest.newBuilder().url(newUrl).build())
}
}
app/src/main/java/top/yeij/cyrene/data/remote/RetrofitClient.kt
-38
View File
@@ -1,38 +0,0 @@
package top.yeij.cyrene.data.remote
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import java.util.concurrent.TimeUnit
object RetrofitClient {
fun provideOkHttpClient(
authInterceptor: AuthInterceptor,
dynamicUrlInterceptor: DynamicUrlInterceptor,
tokenAuthenticator: TokenAuthenticator,
): OkHttpClient {
val logging = HttpLoggingInterceptor().apply {
level = HttpLoggingInterceptor.Level.BODY
}
return OkHttpClient.Builder()
.addInterceptor(dynamicUrlInterceptor)
.addInterceptor(authInterceptor)
.authenticator(tokenAuthenticator)
.addInterceptor(logging)
.connectTimeout(30, TimeUnit.SECONDS)
.readTimeout(60, TimeUnit.SECONDS)
.writeTimeout(30, TimeUnit.SECONDS)
.build()
}
fun provideRetrofit(okHttpClient: OkHttpClient): Retrofit {
return Retrofit.Builder()
.baseUrl("http://localhost/")
.client(okHttpClient)
.addConverterFactory(GsonConverterFactory.create())
.build()
}
}
app/src/main/java/top/yeij/cyrene/data/remote/TokenAuthenticator.kt
-84
View File
@@ -1,84 +0,0 @@
package top.yeij.cyrene.data.remote
import com.google.gson.Gson
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
import okhttp3.Authenticator
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import okhttp3.Route
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.dto.AuthResponse
import top.yeij.cyrene.data.remote.dto.RefreshTokenRequest
import android.util.Log
class TokenAuthenticator(
private val authInterceptor: AuthInterceptor,
private val preferencesDataStore: PreferencesDataStore,
private val dynamicUrlInterceptor: DynamicUrlInterceptor,
) : Authenticator {
private val gson = Gson()
private val client = OkHttpClient()
override fun authenticate(route: Route?, response: okhttp3.Response): Request? {
if (response.code != 401) return null
synchronized(this) {
// Double-check: if token changed while we were waiting for lock, use it
val currentToken = authInterceptor.token
val requestAuthHeader = response.request.header("Authorization")
if (requestAuthHeader != null && currentToken != null &&
requestAuthHeader != "Bearer $currentToken"
) {
return response.request.newBuilder()
.header("Authorization", "Bearer $currentToken")
.build()
}
// Try refresh
return try {
val refreshToken = runBlocking { preferencesDataStore.refreshToken.firstOrNull() }
?: return null
val baseUrl = dynamicUrlInterceptor.baseUrl.trimEnd('/')
val refreshUrl = "$baseUrl/api/v1/auth/refresh"
val jsonBody = gson.toJson(RefreshTokenRequest(refreshToken))
val body = jsonBody.toRequestBody("application/json".toMediaType())
val refreshRequest = Request.Builder()
.url(refreshUrl)
.post(body)
.build()
val refreshResponse = client.newCall(refreshRequest).execute()
if (refreshResponse.isSuccessful) {
val authResponse = gson.fromJson(
refreshResponse.body?.string(),
AuthResponse::class.java
)
authInterceptor.token = authResponse.token
runBlocking {
preferencesDataStore.saveToken(authResponse.token)
authResponse.refreshToken?.let {
preferencesDataStore.saveRefreshToken(it)
}
}
Log.i("TokenAuthenticator", "Token refreshed successfully")
response.request.newBuilder()
.header("Authorization", "Bearer ${authResponse.token}")
.build()
} else {
Log.w("TokenAuthenticator", "Token refresh failed: ${refreshResponse.code}")
null
}
} catch (e: Exception) {
Log.e("TokenAuthenticator", "Token refresh error: ${e.message}", e)
null
}
}
}
}
app/src/main/java/top/yeij/cyrene/data/remote/dto/AuthDtos.kt
-29
View File
@@ -1,29 +0,0 @@
package top.yeij.cyrene.data.remote.dto
import com.google.gson.annotations.SerializedName
data class AuthRequest(
@SerializedName("username") val username: String,
@SerializedName("password") val password: String,
)
data class AuthResponse(
@SerializedName("token") val token: String,
@SerializedName("refresh_token") val refreshToken: String?,
@SerializedName("username") val username: String?,
@SerializedName("nickname") val nickname: String?,
@SerializedName("user_id") val userId: String?,
@SerializedName("expires") val expires: Long? = null,
)
data class RefreshTokenRequest(
@SerializedName("refresh_token") val refreshToken: String,
)
data class ProfileResponse(
@SerializedName("user_id") val userId: String,
@SerializedName("username") val username: String,
@SerializedName("nickname") val nickname: String?,
@SerializedName("is_admin") val isAdmin: Boolean? = false,
@SerializedName("created_at") val createdAt: String? = null,
)
app/src/main/java/top/yeij/cyrene/data/remote/dto/DeviceDto.kt
-26
View File
@@ -1,26 +0,0 @@
package top.yeij.cyrene.data.remote.dto
import com.google.gson.annotations.SerializedName
data class DeviceDto(
@SerializedName("id") val id: String,
@SerializedName("name") val name: String,
@SerializedName("type") val type: String,
@SerializedName("state") val state: DeviceState,
@SerializedName("room") val room: String?,
)
data class DeviceState(
@SerializedName("power") val power: Boolean?,
@SerializedName("brightness") val brightness: Int?,
@SerializedName("temperature") val temperature: Float?,
@SerializedName("humidity") val humidity: Float?,
@SerializedName("colorTemp") val colorTemp: Int?,
@SerializedName("locked") val locked: Boolean?,
@SerializedName("open") val open: Boolean?,
)
data class IoTControlRequest(
@SerializedName("action") val action: String,
@SerializedName("value") val value: Any? = null,
)
app/src/main/java/top/yeij/cyrene/data/remote/dto/SessionDtos.kt
-38
View File
@@ -1,38 +0,0 @@
package top.yeij.cyrene.data.remote.dto
import com.google.gson.annotations.SerializedName
// POST /api/v1/sessions — request body
data class CreateSessionRequest(
@SerializedName("session_id") val sessionId: String? = null,
@SerializedName("title") val title: String = "新的对话",
@SerializedName("is_main") val isMain: Boolean = false,
)
// GET /api/v1/sessions — response wrapper
data class SessionsListResponse(
@SerializedName("sessions") val sessions: List<SessionDto>,
)
data class SessionDto(
@SerializedName("id") val id: String,
@SerializedName("user_id") val userId: String?,
@SerializedName("title") val title: String,
@SerializedName("is_main") val isMain: Boolean?,
@SerializedName("created_at") val createdAt: Long,
@SerializedName("updated_at") val updatedAt: Long,
)
// GET /api/v1/sessions/{id}/messages — response wrapper
data class MessagesListResponse(
@SerializedName("messages") val messages: List<SessionMessageDto>,
)
data class SessionMessageDto(
@SerializedName("id") val id: String,
@SerializedName("session_id") val sessionId: String,
@SerializedName("role") val role: String,
@SerializedName("msg_type") val msgType: String?,
@SerializedName("content") val content: String,
@SerializedName("created_at") val createdAt: Long,
)
app/src/main/java/top/yeij/cyrene/data/remote/dto/WSDtos.kt
-86
View File
@@ -1,86 +0,0 @@
package top.yeij.cyrene.data.remote.dto
import com.google.gson.annotations.SerializedName
// --- Client → Server ---
data class WSClientMessage(
@SerializedName("type") val type: String,
@SerializedName("session_id") val sessionId: String? = null,
@SerializedName("mode") val mode: String? = null,
@SerializedName("content") val content: String? = null,
@SerializedName("audio_data") val audioData: String? = null,
@SerializedName("attachments") val attachments: List<WSAttachment>? = null,
@SerializedName("timestamp") val timestamp: Long? = null,
@SerializedName("client_id") val clientId: String? = null,
@SerializedName("device_name") val deviceName: String? = null,
@SerializedName("user_agent") val userAgent: String? = null,
)
data class WSAttachment(
@SerializedName("type") val type: String,
@SerializedName("url") val url: String? = null,
@SerializedName("thumbnail_url") val thumbnailUrl: String? = null,
@SerializedName("filename") val filename: String? = null,
@SerializedName("width") val width: Int? = null,
@SerializedName("height") val height: Int? = null,
@SerializedName("size") val size: Long? = null,
@SerializedName("description") val description: String? = null,
)
// --- Server → Client ---
data class WSClientInfo(
@SerializedName("client_id") val clientId: String? = null,
@SerializedName("device_name") val deviceName: String? = null,
)
data class WSServerMessage(
@SerializedName("type") val type: String?,
@SerializedName("message_id") val messageId: String? = null,
@SerializedName("text") val text: String? = null,
@SerializedName("content") val content: String? = null,
@SerializedName("role") val role: String? = null,
@SerializedName("msg_type") val msgType: String? = null,
@SerializedName("session_id") val sessionId: String? = null,
@SerializedName("error") val error: String? = null,
@SerializedName("review_messages") val reviewMessages: List<WSReviewMessage>? = null,
@SerializedName("messages") val messages: List<WSHistoryMessage>? = null,
@SerializedName("multi_message") val multiMessages: List<WSMultiItem>? = null,
@SerializedName("tool_progress") val toolProgress: WSToolProgress? = null,
@SerializedName("thinking_status") val thinkingStatus: String? = null,
@SerializedName("thinking_content") val thinkingContent: String? = null,
@SerializedName("timestamp") val timestamp: Long? = null,
@SerializedName("client_info") val clientInfo: WSClientInfo? = null,
)
data class WSReviewMessage(
@SerializedName("role") val role: String?,
@SerializedName("text") val text: String?,
@SerializedName("content") val content: String?,
@SerializedName("msg_type") val msgType: String?,
@SerializedName("delay_ms") val delayMs: Long? = 0,
)
data class WSHistoryMessage(
@SerializedName("id") val id: String?,
@SerializedName("role") val role: String?,
@SerializedName("content") val content: String?,
@SerializedName("msg_type") val msgType: String?,
@SerializedName("timestamp") val timestamp: Long?,
@SerializedName("name") val name: String?,
)
data class WSMultiItem(
@SerializedName("role") val role: String?,
@SerializedName("content") val content: String?,
@SerializedName("msg_type") val msgType: String?,
)
data class WSToolProgress(
@SerializedName("tool_name") val toolName: String?,
@SerializedName("status") val status: String?,
@SerializedName("detail") val detail: String?,
@SerializedName("message") val message: String?,
@SerializedName("progress") val progress: Int? = null,
)
app/src/main/java/top/yeij/cyrene/data/repository/AuthRepositoryImpl.kt
-50
View File
@@ -1,50 +0,0 @@
package top.yeij.cyrene.data.repository
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.ApiService
import top.yeij.cyrene.data.remote.AuthInterceptor
import top.yeij.cyrene.data.remote.dto.AuthRequest
import top.yeij.cyrene.domain.model.AuthResult
import top.yeij.cyrene.domain.repository.AuthRepository
import kotlinx.coroutines.flow.firstOrNull
class AuthRepositoryImpl(
private val apiService: ApiService,
private val preferencesDataStore: PreferencesDataStore,
private val authInterceptor: AuthInterceptor,
) : AuthRepository {
override suspend fun login(username: String, password: String): Result<AuthResult> {
return try {
val response = apiService.login(AuthRequest(username, password))
if (response.isSuccessful) {
val body = response.body()!!
authInterceptor.token = body.token
preferencesDataStore.saveToken(body.token)
body.refreshToken?.let { preferencesDataStore.saveRefreshToken(it) }
val displayName = body.nickname ?: body.username ?: body.userId ?: "开拓者"
preferencesDataStore.saveUsername(displayName)
Result.success(
AuthResult(
token = body.token,
refreshToken = body.refreshToken,
username = displayName,
)
)
} else {
Result.failure(Exception("登录失败: ${response.code()}"))
}
} catch (e: Exception) {
Result.failure(e)
}
}
override suspend fun logout() {
authInterceptor.token = null
preferencesDataStore.clearAll()
}
override suspend fun isLoggedIn(): Boolean {
return preferencesDataStore.token.firstOrNull() != null
}
}
app/src/main/java/top/yeij/cyrene/data/repository/ChatRepositoryImpl.kt
-692
View File
@@ -1,692 +0,0 @@
package top.yeij.cyrene.data.repository
import android.util.Log
import kotlinx.coroutines.CoroutineExceptionHandler
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.launch
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.withTimeoutOrNull
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.local.dao.ConversationDao
import top.yeij.cyrene.data.local.dao.MessageDao
import top.yeij.cyrene.data.local.entity.ConversationEntity
import top.yeij.cyrene.data.local.entity.MessageEntity
import top.yeij.cyrene.data.remote.ApiService
import top.yeij.cyrene.data.remote.dto.CreateSessionRequest
import top.yeij.cyrene.data.remote.dto.WSServerMessage
import top.yeij.cyrene.domain.model.Conversation
import top.yeij.cyrene.domain.model.Message
import top.yeij.cyrene.domain.repository.ChatRepository
import top.yeij.cyrene.service.WebSocketService
import top.yeij.cyrene.util.RuntimeLog
import java.util.UUID
class ChatRepositoryImpl(
private val conversationDao: ConversationDao,
private val messageDao: MessageDao,
private val webSocketService: WebSocketService,
private val apiService: ApiService,
private val preferencesDataStore: PreferencesDataStore,
) : ChatRepository {
private val exceptionHandler = CoroutineExceptionHandler { _, e ->
Log.e("ChatRepository", "Unhandled exception", e)
}
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO + exceptionHandler)
private val _connectionState = MutableStateFlow(false)
override val connectionState: StateFlow<Boolean> = _connectionState.asStateFlow()
override val connectionError: StateFlow<String?> = webSocketService.connectionError
private val _incomingMessages = MutableSharedFlow<Message>(extraBufferCapacity = 64)
override fun observeMessages(): Flow<Message> = _incomingMessages
private val _messageClearEvents = MutableSharedFlow<Unit>(extraBufferCapacity = 4)
override val messageClearEvents: Flow<Unit> = _messageClearEvents
private val _isAssistantStreaming = MutableStateFlow(false)
override val isAssistantStreaming: StateFlow<Boolean> = _isAssistantStreaming.asStateFlow()
private var streamingContent = ""
private var streamingMessageId: String? = null
override var currentSessionId: String? = null
private var isAppInForeground = false
private var onBackgroundNotification: ((Message) -> Unit)? = null
private var historyRequested = false
private val notifiedMessageIds = mutableSetOf<String>()
// Duplicate suppression: track items from review/multi_message to skip wrapping response
private val recentParsedContents = mutableListOf<String>()
private var lastParsedTime = 0L
// Track last response to clean up if review/multi_message arrives after
private var lastResponseId: String? = null
private var lastResponseContent: String? = null
private var lastResponseTime = 0L
fun setNotificationCallback(callback: ((Message) -> Unit)?) {
onBackgroundNotification = callback
}
override fun onAppForeground() {
isAppInForeground = true
notifiedMessageIds.clear()
if (!_connectionState.value) {
webSocketService.forceReconnect()
}
// Always request history on foreground to catch cross-device messages
scope.launch {
val sid = currentSessionId ?: return@launch
RuntimeLog.general("app", "Foreground — requesting history for session=$sid")
requestHistoryViaWs(sid)
}
}
override fun onAppBackground() {
isAppInForeground = false
}
init {
// Restore persisted session ID, then connect and load history
scope.launch {
val persistedSid = preferencesDataStore.currentSessionId.firstOrNull()
if (!persistedSid.isNullOrBlank()) {
currentSessionId = persistedSid
}
RuntimeLog.ws("init", "Connecting WebSocket session=$currentSessionId")
webSocketService.connect(currentSessionId)
loadConversationsFromServer()
}
scope.launch {
webSocketService.isConnected.collect { connected ->
_connectionState.value = connected
RuntimeLog.ws("connection", "Connected=$connected")
}
}
scope.launch {
webSocketService.incomingMessages.collect { wsMsg ->
try {
RuntimeLog.ws("receive", "type=${wsMsg.type} msgId=${wsMsg.messageId ?: "-"}")
handleServerMessage(wsMsg)
} catch (e: Exception) {
Log.e("ChatRepository", "Error handling ${wsMsg.type}: ${e.message}", e)
RuntimeLog.ws("error", "Handle error type=${wsMsg.type}: ${e.message}")
}
}
}
}
override fun getConversations(): Flow<List<Conversation>> {
return conversationDao.getAll().map { entities ->
entities.map { it.toDomain() }
}
}
override suspend fun getMessages(conversationId: String): Flow<List<Message>> {
return messageDao.getByConversation(conversationId).map { entities ->
entities.map { it.toDomain() }
}
}
override suspend fun deleteConversation(id: String) {
conversationDao.deleteById(id)
try { apiService.deleteSession(id) } catch (_: Exception) { }
}
override suspend fun clearLocalMessages() {
val now = System.currentTimeMillis()
messageDao.deleteAll()
preferencesDataStore.saveLastClearedTimestamp(now)
// Also clear server-side messages for all known sessions
try {
val sessions = conversationDao.getAllSnapshot()
sessions.forEach { session ->
try {
apiService.clearSessionMessages(session.id)
RuntimeLog.chat("clear", "Server messages cleared for session=${session.id}")
} catch (_: Exception) { }
}
} catch (_: Exception) { }
_messageClearEvents.tryEmit(Unit)
RuntimeLog.chat("clear", "Local messages cleared, timestamp=$now")
Log.i("ChatRepository", "Local messages cleared, timestamp: $now")
}
private suspend fun changeSessionId(newId: String) {
val oldId = currentSessionId
if (oldId != null && oldId != newId) {
messageDao.migrateConversationId(oldId, newId)
conversationDao.deleteById(oldId)
}
currentSessionId = newId
preferencesDataStore.saveCurrentSessionId(newId)
}
override suspend fun connectWebSocket(sessionId: String?) {
currentSessionId = sessionId
webSocketService.connect(sessionId)
}
override suspend fun reconnectWebSocket() {
webSocketService.disconnect()
webSocketService.connect(currentSessionId)
}
override suspend fun ensureConnected() {
if (_connectionState.value) return
webSocketService.forceReconnect()
}
override suspend fun sendMessage(content: String, sessionId: String?) {
val messageId = UUID.randomUUID().toString()
val now = System.currentTimeMillis()
val sid = sessionId ?: currentSessionId ?: "default"
if (currentSessionId == null) {
currentSessionId = sid
scope.launch { preferencesDataStore.saveCurrentSessionId(sid) }
}
RuntimeLog.chat("send", "session=$sid msgId=$messageId content=${content.take(80)}")
conversationDao.upsert(
ConversationEntity(
id = sid,
title = "对话",
lastMessage = content,
lastMessageType = "chat",
updatedAt = now,
createdAt = now,
)
)
messageDao.upsert(
MessageEntity(
id = messageId,
conversationId = sid,
role = "user",
content = content,
msgType = "chat",
timestamp = now,
)
)
emitMessage(
id = messageId,
sessionId = sid,
role = "user",
content = content,
msgType = "chat",
timestamp = now,
isStreaming = false,
)
webSocketService.sendMessage(content, sid)
}
override suspend fun loadConversationsFromServer() {
try {
val response = apiService.getSessions()
if (response.isSuccessful) {
response.body()?.sessions?.forEach { dto ->
conversationDao.upsert(
ConversationEntity(
id = dto.id,
title = dto.title,
lastMessage = "",
lastMessageType = "chat",
updatedAt = dto.updatedAt,
createdAt = dto.createdAt,
)
)
}
}
} catch (_: Exception) { }
}
override suspend fun sendScreenContext(content: String) {
webSocketService.sendScreenContext(content, currentSessionId)
}
override suspend fun sendVoiceInput(audioBase64: String, mode: String) {
webSocketService.sendVoiceInput(audioBase64, currentSessionId, mode)
}
override suspend fun initializeSession(): String {
// Try to find an existing main session on the server
try {
val response = apiService.getSessions()
if (response.isSuccessful) {
val sessions = response.body()?.sessions ?: emptyList()
val mainSession = sessions.find { it.isMain == true }
if (mainSession != null) {
currentSessionId = mainSession.id
preferencesDataStore.saveCurrentSessionId(mainSession.id)
Log.i("ChatRepository", "Found main session: ${mainSession.id}")
return mainSession.id
}
}
} catch (_: Exception) { }
// No main session found on server, create one with deterministic ID
val sessionId = "session_admin_main"
try {
apiService.createSession(
CreateSessionRequest(
sessionId = sessionId,
title = "主对话",
isMain = true,
)
)
Log.i("ChatRepository", "Created main session: $sessionId")
} catch (e: Exception) {
Log.w("ChatRepository", "Failed to create main session: ${e.message}")
}
currentSessionId = sessionId
preferencesDataStore.saveCurrentSessionId(sessionId)
return sessionId
}
override suspend fun loadMessagesFromServer(sessionId: String): List<Message> {
currentSessionId = sessionId
return try {
val response = apiService.getSessionMessages(sessionId)
if (response.isSuccessful) {
val messageDtos = response.body()?.messages ?: emptyList()
val lastCleared = preferencesDataStore.lastClearedTimestamp.firstOrNull()
?.toLongOrNull() ?: 0L
val filteredDtos = messageDtos.filter { it.createdAt > lastCleared }
ensureConversation(sessionId)
filteredDtos.forEach { dto ->
messageDao.upsert(
MessageEntity(
id = "db_${dto.id}",
conversationId = sessionId,
role = dto.role,
content = dto.content,
msgType = dto.msgType ?: "chat",
timestamp = dto.createdAt,
)
)
}
RuntimeLog.http("loadMessages", "HTTP loaded ${filteredDtos.size} messages for session=$sessionId")
filteredDtos.map { dto ->
Message(
id = "db_${dto.id}",
conversationId = sessionId,
role = dto.role,
content = dto.content,
msgType = dto.msgType ?: "chat",
timestamp = dto.createdAt,
)
}.removeWrappingDuplicates()
} else {
RuntimeLog.http("loadMessages", "HTTP failed: ${response.code()} ${response.message()}, trying WS")
requestHistoryViaWs(sessionId)
emptyList()
}
} catch (e: Exception) {
RuntimeLog.http("loadMessages", "HTTP error: ${e.message}, trying WS")
requestHistoryViaWs(sessionId)
emptyList()
}
}
private suspend fun requestHistoryViaWs(sessionId: String) {
// Wait up to 5s for WS to connect
if (!webSocketService.isConnected.value) {
withTimeoutOrNull(5000) {
webSocketService.isConnected.first { it }
}
}
webSocketService.requestHistory(sessionId)
}
private suspend fun ensureConversation(sessionId: String, lastMessage: String = "") {
val existing = conversationDao.getById(sessionId)
if (existing == null) {
val now = System.currentTimeMillis()
conversationDao.upsert(
ConversationEntity(
id = sessionId,
title = "对话",
lastMessage = lastMessage,
lastMessageType = "chat",
updatedAt = now,
createdAt = now,
)
)
}
}
private suspend fun handleServerMessage(wsMsg: WSServerMessage) {
when (wsMsg.type) {
"stream_start" -> {
streamingContent = ""
streamingMessageId = wsMsg.messageId ?: "stream_${System.currentTimeMillis()}"
_isAssistantStreaming.value = true
RuntimeLog.chat("stream", "Stream start msgId=$streamingMessageId")
}
"stream_chunk" -> {
val delta = wsMsg.content ?: wsMsg.text ?: return
streamingContent += delta
emitMessage(
id = streamingMessageId ?: "s_${System.currentTimeMillis()}",
sessionId = wsMsg.sessionId ?: currentSessionId ?: "default",
role = "assistant",
content = streamingContent,
msgType = "chat",
isStreaming = true,
)
}
"stream_end" -> {
val msgId = wsMsg.messageId ?: streamingMessageId ?: "s_${System.currentTimeMillis()}"
val content = streamingContent.ifEmpty { wsMsg.content ?: wsMsg.text ?: "" }
streamingContent = ""
streamingMessageId = null
val sid = wsMsg.sessionId ?: currentSessionId ?: "default"
if (currentSessionId == null || (wsMsg.sessionId != null && wsMsg.sessionId != currentSessionId)) {
changeSessionId(sid)
}
val ts = wsMsg.timestamp ?: System.currentTimeMillis()
if (content.isNotBlank()) {
ensureConversation(sid, content)
messageDao.upsert(
MessageEntity(
id = msgId,
conversationId = sid,
role = "assistant",
content = content,
msgType = "chat",
timestamp = ts,
)
)
}
emitMessage(id = msgId, sessionId = sid, role = "assistant", content = content, msgType = "chat", timestamp = ts, isStreaming = false, shouldNotify = true)
_isAssistantStreaming.value = false
RuntimeLog.chat("stream", "Stream end msgId=$msgId content=${content.take(80)}")
}
"response" -> {
val text = wsMsg.content ?: wsMsg.text ?: return
val role = wsMsg.role ?: "assistant"
val replyMsgType = wsMsg.msgType ?: "chat"
val msgId = wsMsg.messageId ?: "r_${System.currentTimeMillis()}"
val sid = wsMsg.sessionId ?: currentSessionId ?: "default"
// Suppress response if it wraps recently emitted review/multi_message items
val timeSinceParsed = System.currentTimeMillis() - lastParsedTime
if (timeSinceParsed < 3000 && recentParsedContents.isNotEmpty()) {
val allContained = recentParsedContents.all { text.contains(it) }
if (allContained) {
RuntimeLog.chat("dedup", "Suppressed wrapping response, ${recentParsedContents.size} items already shown")
recentParsedContents.clear()
return
}
}
recentParsedContents.clear()
if (currentSessionId == null || (wsMsg.sessionId != null && wsMsg.sessionId != currentSessionId)) {
changeSessionId(sid)
}
val ts = wsMsg.timestamp ?: System.currentTimeMillis()
ensureConversation(sid, text)
messageDao.upsert(
MessageEntity(
id = msgId,
conversationId = sid,
role = role,
content = text,
msgType = replyMsgType,
timestamp = ts,
)
)
lastResponseId = msgId
lastResponseContent = text
lastResponseTime = System.currentTimeMillis()
emitMessage(id = msgId, sessionId = sid, role = role, content = text, msgType = replyMsgType, timestamp = ts, isStreaming = false, shouldNotify = true)
RuntimeLog.chat("receive", "Response msgId=$msgId role=$role msgType=$replyMsgType content=${text.take(80)}")
}
"review" -> {
recentParsedContents.clear()
wsMsg.reviewMessages?.forEach { review ->
val text = review.content ?: review.text ?: return@forEach
val role = review.role ?: "action"
val rvMsgType = review.msgType ?: review.role ?: "action"
val msgId = "rv_${System.currentTimeMillis()}_${review.hashCode()}"
recentParsedContents.add(text)
emitMessage(id = msgId, sessionId = wsMsg.sessionId ?: currentSessionId ?: "default", role = role, content = text, msgType = rvMsgType, isStreaming = false)
}
if (recentParsedContents.isNotEmpty()) lastParsedTime = System.currentTimeMillis()
// Clean up wrapping response that arrived before this review
cleanupWrappingResponse()
}
"thinking" -> {
val text = wsMsg.thinkingContent ?: wsMsg.content ?: wsMsg.text
if (text != null) {
emitMessage(
id = wsMsg.messageId ?: "think_${System.currentTimeMillis()}",
sessionId = wsMsg.sessionId ?: currentSessionId ?: "default",
role = "assistant",
content = text,
msgType = "thinking",
isStreaming = false,
)
}
}
"tool_progress" -> {
val detail = wsMsg.toolProgress?.message
?: wsMsg.toolProgress?.detail
?: wsMsg.toolProgress?.toolName
?: "正在执行操作..."
emitMessage(
id = wsMsg.messageId ?: "tool_${System.currentTimeMillis()}",
sessionId = wsMsg.sessionId ?: currentSessionId ?: "default",
role = "system",
content = detail,
msgType = "tool_progress",
isStreaming = false,
)
}
"error" -> {
RuntimeLog.chat("error", "Server error: ${wsMsg.error ?: "未知错误"}")
emitMessage(
id = "err_${System.currentTimeMillis()}",
sessionId = wsMsg.sessionId ?: currentSessionId ?: "default",
role = "system",
content = wsMsg.error ?: "未知错误",
msgType = "system_info",
isStreaming = false,
)
}
"voice_transcript" -> {
val text = wsMsg.text ?: wsMsg.content ?: return
val sid = wsMsg.sessionId ?: currentSessionId ?: "default"
val ts = wsMsg.timestamp ?: System.currentTimeMillis()
val msgId = wsMsg.messageId ?: "vt_${System.currentTimeMillis()}"
ensureConversation(sid)
messageDao.upsert(
MessageEntity(
id = msgId,
conversationId = sid,
role = "user",
content = text,
msgType = "chat",
timestamp = ts,
)
)
emitMessage(id = msgId, sessionId = sid, role = "user", content = text, msgType = "chat", timestamp = ts, isStreaming = false)
}
"history_response" -> {
val sid = wsMsg.sessionId ?: currentSessionId ?: "default"
if (currentSessionId == null || (wsMsg.sessionId != null && wsMsg.sessionId != currentSessionId)) {
changeSessionId(sid)
}
ensureConversation(sid)
val messages = wsMsg.messages ?: return
val messageList = messages.map { hist ->
val msgId = hist.id ?: "hist_${System.currentTimeMillis()}_${hist.hashCode()}"
Message(
id = msgId,
conversationId = sid,
role = hist.role ?: "system",
content = hist.content ?: "",
msgType = hist.msgType ?: "chat",
timestamp = hist.timestamp ?: System.currentTimeMillis(),
)
}
val deduped = messageList.removeWrappingDuplicates()
deduped.forEach { msg ->
messageDao.upsert(
MessageEntity(
id = msg.id,
conversationId = msg.conversationId,
role = msg.role,
content = msg.content,
msgType = msg.msgType,
timestamp = msg.timestamp,
)
)
emitMessage(
id = msg.id,
sessionId = msg.conversationId,
role = msg.role,
content = msg.content,
msgType = msg.msgType,
timestamp = msg.timestamp,
isStreaming = false,
shouldNotify = false,
)
}
RuntimeLog.chat("history", "Loaded ${deduped.size} messages from server history")
}
"multi_message" -> {
recentParsedContents.clear()
wsMsg.multiMessages?.forEach { item ->
val content = item.content ?: ""
recentParsedContents.add(content)
emitMessage(
id = "mm_${System.currentTimeMillis()}_${item.hashCode()}",
sessionId = wsMsg.sessionId ?: currentSessionId ?: "default",
role = item.role ?: "assistant",
content = content,
msgType = item.msgType ?: "chat",
timestamp = wsMsg.timestamp ?: System.currentTimeMillis(),
isStreaming = false,
)
}
if (recentParsedContents.isNotEmpty()) lastParsedTime = System.currentTimeMillis()
cleanupWrappingResponse()
}
}
}
private suspend fun cleanupWrappingResponse() {
val respId = lastResponseId ?: return
val respContent = lastResponseContent ?: return
val timeSinceResponse = System.currentTimeMillis() - lastResponseTime
if (timeSinceResponse > 5000 || recentParsedContents.size < 2) return
val allContained = recentParsedContents.all { respContent.contains(it) }
if (allContained) {
messageDao.deleteById(respId)
RuntimeLog.chat("dedup", "Cleaned up wrapping response from DB id=$respId")
}
}
private fun emitMessage(
id: String,
sessionId: String,
role: String,
content: String,
msgType: String,
isStreaming: Boolean = false,
timestamp: Long = System.currentTimeMillis(),
shouldNotify: Boolean = false,
) {
if (content.isBlank() && msgType == "chat") return
val message = Message(
id = id,
conversationId = sessionId,
role = role,
content = content,
msgType = msgType,
timestamp = timestamp,
isStreaming = isStreaming,
)
_incomingMessages.tryEmit(message)
if (shouldNotify && !isAppInForeground && role == "assistant" && !isStreaming) {
if (notifiedMessageIds.add(id)) {
onBackgroundNotification?.invoke(message)
}
}
}
/**
* Remove wrapper messages whose content contains the content of 2+ other messages.
* This handles the case where the server sends both a combined "response" and
* parsed "review"/"multi_message" items for the same turn.
*/
private fun List<Message>.removeWrappingDuplicates(): List<Message> {
if (size < 3) return this
val toRemove = mutableSetOf<String>()
for (msg in this) {
val containedCount = count { other ->
other.id != msg.id &&
other.content.isNotBlank() &&
other.content.length < msg.content.length &&
msg.content.contains(other.content) &&
kotlin.math.abs(other.timestamp - msg.timestamp) < 2000
}
if (containedCount >= 2) {
toRemove.add(msg.id)
}
}
return if (toRemove.isEmpty()) this else filter { it.id !in toRemove }
}
private fun ConversationEntity.toDomain() = Conversation(
id = id,
title = title,
lastMessage = lastMessage,
lastMessageType = lastMessageType,
updatedAt = updatedAt,
createdAt = createdAt,
)
private fun MessageEntity.toDomain() = Message(
id = id,
conversationId = conversationId,
role = role,
content = content,
msgType = msgType,
timestamp = timestamp,
)
}
app/src/main/java/top/yeij/cyrene/data/repository/IoTRepositoryImpl.kt
-70
View File
@@ -1,70 +0,0 @@
package top.yeij.cyrene.data.repository
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import top.yeij.cyrene.data.remote.ApiService
import top.yeij.cyrene.data.remote.dto.IoTControlRequest
import top.yeij.cyrene.domain.model.Device
import top.yeij.cyrene.domain.model.DeviceState
import top.yeij.cyrene.domain.model.DeviceType
import top.yeij.cyrene.domain.repository.IoTRepository
class IoTRepositoryImpl(
private val apiService: ApiService,
private val webSocketService: top.yeij.cyrene.service.WebSocketService,
) : IoTRepository {
private val _devices = MutableStateFlow<List<Device>>(emptyList())
override fun getDevices(): Flow<List<Device>> = _devices.asStateFlow()
override suspend fun controlDevice(
deviceId: String,
action: String,
value: Any?,
): Result<Device> {
return try {
val response = apiService.controlDevice(deviceId, IoTControlRequest(action, value))
if (response.isSuccessful) {
val updated = response.body()!!.toDomain()
_devices.value = _devices.value.map {
if (it.id == deviceId) updated else it
}
Result.success(updated)
} else {
Result.failure(Exception("设备控制失败: ${response.code()}"))
}
} catch (e: Exception) {
Result.failure(e)
}
}
override suspend fun refreshDevices() {
try {
val response = apiService.getDevices()
if (response.isSuccessful) {
_devices.value = response.body()!!.map { it.toDomain() }
}
} catch (_: Exception) { }
}
private fun top.yeij.cyrene.data.remote.dto.DeviceDto.toDomain() = Device(
id = id,
name = name,
type = try {
DeviceType.valueOf(type.uppercase())
} catch (_: Exception) {
DeviceType.UNKNOWN
},
state = DeviceState(
power = state.power,
brightness = state.brightness,
temperature = state.temperature,
humidity = state.humidity,
colorTemp = state.colorTemp,
locked = state.locked,
open = state.open,
),
room = room,
)
}
app/src/main/java/top/yeij/cyrene/di/AppModule.kt
-80
View File
@@ -1,80 +0,0 @@
package top.yeij.cyrene.di
import org.koin.android.ext.koin.androidContext
import org.koin.core.module.dsl.viewModel
import org.koin.dsl.module
import top.yeij.cyrene.data.local.AppDatabase
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.ApiService
import top.yeij.cyrene.data.remote.AuthInterceptor
import top.yeij.cyrene.data.remote.DynamicUrlInterceptor
import top.yeij.cyrene.data.remote.RetrofitClient
import top.yeij.cyrene.data.remote.TokenAuthenticator
import top.yeij.cyrene.data.repository.AuthRepositoryImpl
import top.yeij.cyrene.data.repository.ChatRepositoryImpl
import top.yeij.cyrene.data.repository.IoTRepositoryImpl
import top.yeij.cyrene.domain.repository.AuthRepository
import top.yeij.cyrene.domain.repository.ChatRepository
import top.yeij.cyrene.domain.repository.IoTRepository
import top.yeij.cyrene.domain.usecase.GetConversationsUseCase
import top.yeij.cyrene.domain.usecase.LoginUseCase
import top.yeij.cyrene.domain.usecase.SendMessageUseCase
import top.yeij.cyrene.service.WebSocketService
import top.yeij.cyrene.viewmodel.ChatViewModel
import top.yeij.cyrene.viewmodel.IoTViewModel
import top.yeij.cyrene.viewmodel.OverlayViewModel
import top.yeij.cyrene.viewmodel.ProfileViewModel
import top.yeij.cyrene.viewmodel.SettingsViewModel
import top.yeij.cyrene.util.VoiceRecorder
import top.yeij.cyrene.voice.stt.BackendSttProvider
import top.yeij.cyrene.voice.stt.DashScopeSttService
import top.yeij.cyrene.voice.stt.SpeechRecognizer
import top.yeij.cyrene.voice.stt.SttManager
import top.yeij.cyrene.voice.tts.TextToSpeechEngine
val appModule = module {
// DataStore
single { PreferencesDataStore(androidContext()) }
// Database
single { AppDatabase.getInstance(androidContext()) }
single { get<AppDatabase>().conversationDao() }
single { get<AppDatabase>().messageDao() }
// Network interceptors
single { AuthInterceptor() }
single { DynamicUrlInterceptor() }
single { TokenAuthenticator(get(), get(), get()) }
single { RetrofitClient.provideOkHttpClient(get(), get(), get()) }
single { RetrofitClient.provideRetrofit(get()) }
single { get<retrofit2.Retrofit>().create(ApiService::class.java) }
// WebSocket
single { WebSocketService(get()) }
// Voice
single { VoiceRecorder(androidContext()) }
single { SpeechRecognizer(androidContext()) }
single { TextToSpeechEngine(androidContext()) }
single { DashScopeSttService(androidContext()) }
single { BackendSttProvider(androidContext(), get()) }
single { SttManager(get(), get(), get()) }
// Repositories
single<AuthRepository> { AuthRepositoryImpl(get(), get(), get()) }
single<ChatRepository> { ChatRepositoryImpl(get(), get(), get(), get(), get()) }
single<IoTRepository> { IoTRepositoryImpl(get(), get()) }
// UseCases
factory { LoginUseCase(get()) }
factory { SendMessageUseCase(get()) }
factory { GetConversationsUseCase(get()) }
// ViewModels
viewModel { ChatViewModel(get(), get()) }
viewModel { IoTViewModel(get()) }
viewModel { OverlayViewModel(get(), get(), get()) }
viewModel { ProfileViewModel(get(), get(), get()) }
single { SettingsViewModel(get(), get(), get(), get(), get()) }
}
app/src/main/java/top/yeij/cyrene/domain/model/AuthResult.kt
-7
View File
@@ -1,7 +0,0 @@
package top.yeij.cyrene.domain.model
data class AuthResult(
val token: String,
val refreshToken: String?,
val username: String,
)
app/src/main/java/top/yeij/cyrene/domain/model/Conversation.kt
-10
View File
@@ -1,10 +0,0 @@
package top.yeij.cyrene.domain.model
data class Conversation(
val id: String,
val title: String,
val lastMessage: String?,
val lastMessageType: String?,
val updatedAt: Long,
val createdAt: Long,
)
app/src/main/java/top/yeij/cyrene/domain/model/Device.kt
-28
View File
@@ -1,28 +0,0 @@
package top.yeij.cyrene.domain.model
data class Device(
val id: String,
val name: String,
val type: DeviceType,
val state: DeviceState,
val room: String?,
)
enum class DeviceType {
LIGHT,
AC,
CURTAIN,
SENSOR,
DOOR_LOCK,
UNKNOWN,
}
data class DeviceState(
val power: Boolean? = null,
val brightness: Int? = null,
val temperature: Float? = null,
val humidity: Float? = null,
val colorTemp: Int? = null,
val locked: Boolean? = null,
val open: Boolean? = null,
)
app/src/main/java/top/yeij/cyrene/domain/model/Message.kt
-11
View File
@@ -1,11 +0,0 @@
package top.yeij.cyrene.domain.model
data class Message(
val id: String,
val conversationId: String,
val role: String,
val content: String,
val msgType: String,
val timestamp: Long,
val isStreaming: Boolean = false,
)
app/src/main/java/top/yeij/cyrene/domain/repository/AuthRepository.kt
-12
View File
@@ -1,12 +0,0 @@
package top.yeij.cyrene.domain.repository
import top.yeij.cyrene.domain.model.AuthResult
interface AuthRepository {
suspend fun login(username: String, password: String): Result<AuthResult>
suspend fun logout()
suspend fun isLoggedIn(): Boolean
}
app/src/main/java/top/yeij/cyrene/domain/repository/ChatRepository.kt
-46
View File
@@ -1,46 +0,0 @@
package top.yeij.cyrene.domain.repository
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.StateFlow
import top.yeij.cyrene.domain.model.Conversation
import top.yeij.cyrene.domain.model.Message
interface ChatRepository {
val connectionState: StateFlow<Boolean>
val connectionError: StateFlow<String?>
val isAssistantStreaming: StateFlow<Boolean>
val messageClearEvents: Flow<Unit>
var currentSessionId: String?
fun getConversations(): Flow<List<Conversation>>
suspend fun getMessages(conversationId: String): Flow<List<Message>>
suspend fun deleteConversation(id: String)
suspend fun connectWebSocket(sessionId: String?)
suspend fun sendMessage(content: String, sessionId: String?)
fun observeMessages(): Flow<Message>
suspend fun loadConversationsFromServer()
suspend fun loadMessagesFromServer(sessionId: String): List<Message>
suspend fun initializeSession(): String
suspend fun reconnectWebSocket()
suspend fun ensureConnected()
suspend fun sendScreenContext(content: String)
suspend fun sendVoiceInput(audioBase64: String, mode: String = "voice_msg")
suspend fun clearLocalMessages()
fun onAppForeground()
fun onAppBackground()
}
app/src/main/java/top/yeij/cyrene/domain/repository/IoTRepository.kt
-13
View File
@@ -1,13 +0,0 @@
package top.yeij.cyrene.domain.repository
import kotlinx.coroutines.flow.Flow
import top.yeij.cyrene.domain.model.Device
interface IoTRepository {
fun getDevices(): Flow<List<Device>>
suspend fun controlDevice(deviceId: String, action: String, value: Any? = null): Result<Device>
suspend fun refreshDevices()
}
app/src/main/java/top/yeij/cyrene/domain/usecase/GetConversationsUseCase.kt
-11
View File
@@ -1,11 +0,0 @@
package top.yeij.cyrene.domain.usecase
import kotlinx.coroutines.flow.Flow
import top.yeij.cyrene.domain.model.Conversation
import top.yeij.cyrene.domain.repository.ChatRepository
class GetConversationsUseCase(
private val chatRepository: ChatRepository,
) {
operator fun invoke(): Flow<List<Conversation>> = chatRepository.getConversations()
}
app/src/main/java/top/yeij/cyrene/domain/usecase/LoginUseCase.kt
-15
View File
@@ -1,15 +0,0 @@
package top.yeij.cyrene.domain.usecase
import top.yeij.cyrene.domain.model.AuthResult
import top.yeij.cyrene.domain.repository.AuthRepository
class LoginUseCase(
private val authRepository: AuthRepository,
) {
suspend operator fun invoke(username: String, password: String): Result<AuthResult> {
if (username.isBlank() || password.isBlank()) {
return Result.failure(IllegalArgumentException("用户名和密码不能为空"))
}
return authRepository.login(username, password)
}
}
app/src/main/java/top/yeij/cyrene/domain/usecase/SendMessageUseCase.kt
-13
View File
@@ -1,13 +0,0 @@
package top.yeij.cyrene.domain.usecase
import top.yeij.cyrene.domain.repository.ChatRepository
class SendMessageUseCase(
private val chatRepository: ChatRepository,
) {
suspend operator fun invoke(content: String, sessionId: String? = null) {
if (content.isNotBlank()) {
chatRepository.sendMessage(content, sessionId)
}
}
}
app/src/main/java/top/yeij/cyrene/service/CyreneAccessibilityService.kt
-67
View File
@@ -1,67 +0,0 @@
package top.yeij.cyrene.service
import android.accessibilityservice.AccessibilityService
import android.view.accessibility.AccessibilityEvent
import android.view.accessibility.AccessibilityNodeInfo
class CyreneAccessibilityService : AccessibilityService() {
companion object {
@Volatile
private var instance: CyreneAccessibilityService? = null
fun getScreenContent(): String {
return instance?.captureScreenContent() ?: ""
}
fun isRunning(): Boolean = instance != null
}
override fun onServiceConnected() {
super.onServiceConnected()
instance = this
}
override fun onAccessibilityEvent(event: AccessibilityEvent?) {}
override fun onInterrupt() {}
override fun onDestroy() {
instance = null
super.onDestroy()
}
private fun captureScreenContent(): String {
val root = rootInActiveWindow ?: return ""
return try {
val sb = StringBuilder()
collectNodeText(root, sb, depth = 0)
sb.toString().trim()
} finally {
root.recycle()
}
}
private fun collectNodeText(node: AccessibilityNodeInfo, sb: StringBuilder, depth: Int) {
// Skip the root decor view itself content, and limit depth
if (depth > 16) return
val text = node.text?.toString()?.trim()
val contentDesc = node.contentDescription?.toString()?.trim()
if (!text.isNullOrEmpty() && text != contentDesc) {
if (sb.isNotEmpty()) sb.append("\n")
sb.append(text)
} else if (!contentDesc.isNullOrEmpty() && depth > 0) {
// Only include content descriptions for non-root nodes
if (sb.isNotEmpty()) sb.append("\n")
sb.append(contentDesc)
}
for (i in 0 until node.childCount) {
val child = node.getChild(i) ?: continue
collectNodeText(child, sb, depth + 1)
child.recycle()
}
}
}
app/src/main/java/top/yeij/cyrene/service/CyreneRecognitionService.kt
-33
View File
@@ -1,33 +0,0 @@
package top.yeij.cyrene.service
import android.service.voice.VoiceInteractionService
import android.util.Log
/**
* Recognition service for always-on hotword detection.
*
* In API 36, AlwaysOnHotwordDetector was removed from the public SDK.
* The system manages low-level hotword detection internally and invokes
* the session service declared in voice_interaction_config.xml when triggered.
* For custom hotword models (Porcupine / openWakeWord), integrate via
* a foreground service with microphone capture instead.
*/
class CyreneRecognitionService : VoiceInteractionService() {
override fun onReady() {
super.onReady()
isActive = true
Log.i(TAG, "Recognition service ready")
}
override fun onShutdown() {
isActive = false
super.onShutdown()
}
companion object {
private const val TAG = "CyreneRecognition"
var isActive: Boolean = false
private set
}
}
app/src/main/java/top/yeij/cyrene/service/CyreneSessionService.kt
-27
View File
@@ -1,27 +0,0 @@
package top.yeij.cyrene.service
import android.content.Intent
import android.os.Bundle
import android.service.voice.VoiceInteractionSessionService
import android.util.Log
class CyreneSessionService : VoiceInteractionSessionService() {
override fun onCreate() {
super.onCreate()
Log.i(TAG, "Session service created")
}
override fun onNewSession(args: Bundle?): CyreneVoiceInteractionSession {
return CyreneVoiceInteractionSession(this)
}
override fun onDestroy() {
super.onDestroy()
Log.i(TAG, "Session service destroyed")
}
companion object {
private const val TAG = "CyreneSession"
}
}
app/src/main/java/top/yeij/cyrene/service/CyreneVoiceInteractionService.kt
-60
View File
@@ -1,60 +0,0 @@
package top.yeij.cyrene.service
import android.content.Intent
import android.os.Bundle
import android.service.voice.VoiceInteractionService
import android.util.Log
import top.yeij.cyrene.MainActivity
import top.yeij.cyrene.util.Constants
class CyreneVoiceInteractionService : VoiceInteractionService() {
override fun onCreate() {
super.onCreate()
Log.i(TAG, "Service created")
}
override fun onReady() {
super.onReady()
isActive = true
getSharedPreferences(PREF_NAME, MODE_PRIVATE)
.edit().putBoolean(KEY_WAS_ACTIVE, true).apply()
Log.i(TAG, "Service ready")
}
override fun onPrepareToShowSession(args: Bundle, showFlags: Int) {
Log.i(TAG, "onPrepareToShowSession")
}
override fun onShowSessionFailed(args: Bundle) {
Log.e(TAG, "onShowSessionFailed")
}
override fun onLaunchVoiceAssistFromKeyguard() {
Log.i(TAG, "onLaunchVoiceAssistFromKeyguard")
val intent = Intent(this, MainActivity::class.java).apply {
addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
putExtra(Constants.EXTRA_VOICE_ASSIST, true)
}
startActivity(intent)
}
override fun onShutdown() {
isActive = false
super.onShutdown()
Log.i(TAG, "Service shutdown")
}
companion object {
var isActive: Boolean = false
private set
private const val TAG = "CyreneVIS"
private const val PREF_NAME = "cyrene_assistant"
private const val KEY_WAS_ACTIVE = "was_assistant_active"
fun wasEverActive(context: android.content.Context): Boolean {
return context.getSharedPreferences(PREF_NAME, android.content.Context.MODE_PRIVATE)
.getBoolean(KEY_WAS_ACTIVE, false)
}
}
}
app/src/main/java/top/yeij/cyrene/service/CyreneVoiceInteractionSession.kt
-138
View File
@@ -1,138 +0,0 @@
package top.yeij.cyrene.service
import android.content.Context
import android.content.Intent
import android.os.Bundle
import android.service.voice.VoiceInteractionSession
import android.util.Log
import android.view.View
import android.view.WindowManager
import androidx.compose.ui.platform.ComposeView
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.setViewTreeLifecycleOwner
import androidx.savedstate.SavedStateRegistry
import androidx.savedstate.SavedStateRegistryController
import androidx.savedstate.SavedStateRegistryOwner
import androidx.savedstate.setViewTreeSavedStateRegistryOwner
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
import org.koin.core.context.GlobalContext
import top.yeij.cyrene.MainActivity
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.ui.overlay.OverlayContent
import top.yeij.cyrene.ui.theme.CyreneTheme
import top.yeij.cyrene.util.Constants
import top.yeij.cyrene.util.RuntimeLog
import top.yeij.cyrene.viewmodel.OverlayViewModel
class CyreneVoiceInteractionSession(context: Context) :
VoiceInteractionSession(context), LifecycleOwner, SavedStateRegistryOwner {
private val lifecycleRegistry = LifecycleRegistry(this)
override val lifecycle: Lifecycle get() = lifecycleRegistry
private val savedStateRegistryController = SavedStateRegistryController.create(this)
override val savedStateRegistry: SavedStateRegistry get() = savedStateRegistryController.savedStateRegistry
// Resolved eagerly with fallback — lazy would silently crash composition on failure
private var overlayViewModel: OverlayViewModel? = null
private set
init {
savedStateRegistryController.performAttach()
savedStateRegistryController.performRestore(null)
}
private fun resolveViewModel(): OverlayViewModel? {
return try {
GlobalContext.get().get<OverlayViewModel>()
} catch (e: Exception) {
Log.e(TAG, "Failed to resolve OverlayViewModel from Koin", e)
null
}
}
override fun onCreateContentView(): View {
Log.d(TAG, "onCreateContentView called")
RuntimeLog.general("overlay", "onCreateContentView")
overlayViewModel = resolveViewModel()
if (overlayViewModel == null) {
Log.w(TAG, "ViewModel unavailable — overlay will be static")
RuntimeLog.general("overlay", "ViewModel unavailable, overlay static")
}
lifecycleRegistry.currentState = Lifecycle.State.CREATED
val vm = overlayViewModel
return ComposeView(context).apply {
setViewTreeLifecycleOwner(this@CyreneVoiceInteractionSession)
setViewTreeSavedStateRegistryOwner(this@CyreneVoiceInteractionSession)
setContent {
CyreneTheme {
if (vm != null) {
OverlayContent(
onDismiss = { finish() },
onNavigateToMain = {
val intent = Intent(context, MainActivity::class.java).apply {
addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}
context.startActivity(intent)
},
viewModel = vm,
)
}
}
}
}
}
override fun onShow(args: Bundle?, showFlags: Int) {
super.onShow(args, showFlags)
RuntimeLog.general("overlay", "onShow, vm=${overlayViewModel != null}")
lifecycleRegistry.currentState = Lifecycle.State.STARTED
// Configure window: extend behind status bar, don't resize for IME
configureWindow()
// Only read screen content if user enabled it in settings (default off)
val autoScreenContext = try {
val prefs: PreferencesDataStore = GlobalContext.get().get()
runBlocking { prefs.autoScreenContext.firstOrNull() } ?: false
} catch (_: Exception) {
false
}
if (autoScreenContext) {
val screenContent = CyreneAccessibilityService.getScreenContent()
if (screenContent.isNotBlank()) {
overlayViewModel?.sendScreenContext(screenContent)
RuntimeLog.general("overlay", "Screen context sent, len=${screenContent.length}")
}
}
}
private fun configureWindow() {
try {
val method = VoiceInteractionSession::class.java.getDeclaredMethod("getWindow")
method.isAccessible = true
val w = method.invoke(this) as? android.view.Window ?: return
w.addFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS)
w.addFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION)
w.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_NOTHING)
Log.d(TAG, "Window configured: translucent status/nav, adjust nothing for IME")
} catch (e: Exception) {
Log.w(TAG, "Failed to configure window: ${e.message}")
}
}
override fun onHide() {
RuntimeLog.general("overlay", "onHide")
lifecycleRegistry.currentState = Lifecycle.State.DESTROYED
super.onHide()
overlayViewModel?.finish()
}
companion object {
private const val TAG = "CyreneVIS-Session"
}
}
app/src/main/java/top/yeij/cyrene/service/WebSocketService.kt
-309
View File
@@ -1,309 +0,0 @@
package top.yeij.cyrene.service
import android.os.Build
import android.util.Log
import com.google.gson.Gson
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.launch
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.Response
import okhttp3.WebSocket
import okhttp3.WebSocketListener
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.dto.WSClientMessage
import top.yeij.cyrene.data.remote.dto.WSServerMessage
import java.net.URLEncoder
import java.util.concurrent.TimeUnit
import java.util.concurrent.atomic.AtomicInteger
class WebSocketService(
private val preferencesDataStore: PreferencesDataStore,
) {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
private val httpClient = OkHttpClient.Builder()
.readTimeout(0, TimeUnit.MILLISECONDS)
.writeTimeout(0, TimeUnit.MILLISECONDS)
.callTimeout(0, TimeUnit.MILLISECONDS)
.pingInterval(25, TimeUnit.SECONDS)
.build()
private val gson = Gson()
private var webSocket: WebSocket? = null
private var heartbeatJob: Job? = null
private var reconnectJob: Job? = null
private var shouldReconnect = true
private var currentSessionId: String? = null
private val connectionId = AtomicInteger(0)
private var clientId: String = ""
private var deviceName: String = ""
private val _isConnected = MutableStateFlow(false)
val isConnected: StateFlow<Boolean> = _isConnected.asStateFlow()
private val _connectionError = MutableStateFlow<String?>(null)
val connectionError: StateFlow<String?> = _connectionError.asStateFlow()
private val _incomingMessages = MutableSharedFlow<WSServerMessage>(extraBufferCapacity = 64)
val incomingMessages: SharedFlow<WSServerMessage> = _incomingMessages.asSharedFlow()
private suspend fun initClientIdentity() {
clientId = preferencesDataStore.clientId.firstOrNull() ?: run {
val id = "cl_" + System.currentTimeMillis().toString(36) + "_" +
(100000..999999).random().toString(36)
preferencesDataStore.saveClientId(id)
id
}
deviceName = preferencesDataStore.deviceName.firstOrNull() ?: run {
val name = "Android " + (Build.MODEL ?: "Device")
preferencesDataStore.saveDeviceName(name)
name
}
}
fun getClientId(): String = clientId
fun getDeviceName(): String = deviceName
suspend fun connect(sessionId: String? = null) {
currentSessionId = sessionId
shouldReconnect = true
initClientIdentity()
val baseUrl = preferencesDataStore.baseUrl.firstOrNull()
?: "http://10.0.2.2:8080"
val token = preferencesDataStore.token.firstOrNull() ?: ""
val wsBase = baseUrl
.replace("https://", "wss://")
.replace("http://", "ws://")
.trimEnd('/')
val urlBuilder = StringBuilder("$wsBase/ws/chat")
val params = mutableListOf<String>()
if (token.isNotBlank()) {
params.add("token=" + encode(token))
}
sessionId?.let {
if (it.isNotBlank()) params.add("session_id=" + encode(it))
}
if (clientId.isNotBlank()) {
params.add("client_id=" + encode(clientId))
}
if (deviceName.isNotBlank()) {
params.add("device_name=" + encode(deviceName))
}
if (params.isNotEmpty()) {
urlBuilder.append("?")
urlBuilder.append(params.joinToString("&"))
}
val url = urlBuilder.toString()
val connId = connectionId.incrementAndGet()
Log.i(TAG, "[#$connId] Connecting to $url")
val request = Request.Builder()
.url(url)
.header("User-Agent", "Cyrene-Android/${Build.MODEL ?: "Device"}")
.build()
// Close previous socket silently
try { webSocket?.close(1000, "Reconnecting") } catch (_: Exception) { }
cancelHeartbeat()
webSocket = httpClient.newWebSocket(request, object : WebSocketListener() {
override fun onOpen(webSocket: WebSocket, response: Response) {
if (connectionId.get() != connId) {
Log.d(TAG, "[#$connId] onOpen ignored (stale)")
return
}
Log.i(TAG, "[#$connId] Connected")
_isConnected.value = true
_connectionError.value = null
startHeartbeat()
}
override fun onMessage(webSocket: WebSocket, text: String) {
if (connectionId.get() != connId) return
try {
val msg = gson.fromJson(text, WSServerMessage::class.java)
_incomingMessages.tryEmit(msg)
} catch (e: Exception) {
Log.w(TAG, "[#$connId] Failed to parse message: ${e.message}")
}
}
override fun onClosing(webSocket: WebSocket, code: Int, reason: String) {
if (connectionId.get() != connId) return
Log.i(TAG, "[#$connId] Server closing: code=$code reason=$reason")
_isConnected.value = false
cancelHeartbeat()
}
override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
if (connectionId.get() != connId) return
Log.i(TAG, "[#$connId] Closed: code=$code reason=$reason")
_isConnected.value = false
cancelHeartbeat()
scheduleReconnect()
}
override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
if (connectionId.get() != connId) return
val httpCode = response?.code
Log.e(TAG, "[#$connId] Failure: ${t.message} (http=$httpCode)", t)
_isConnected.value = false
cancelHeartbeat()
val errorMsg = when (httpCode) {
403 -> {
Log.e(TAG, "[#$connId] WebSocket 403: 仅管理员用户可连接。请使用管理员账户登录。")
"仅管理员用户可连接"
}
401 -> "认证失败，请重新登录"
else -> null
}
if (errorMsg != null) {
_connectionError.value = errorMsg
}
// onClosed will always follow, which triggers scheduleReconnect
}
})
}
private fun encode(value: String): String = URLEncoder.encode(value, "UTF-8")
private fun buildMessage(
type: String,
sessionId: String? = null,
mode: String? = null,
content: String? = null,
): WSClientMessage = WSClientMessage(
type = type,
sessionId = sessionId ?: currentSessionId,
mode = mode,
content = content,
timestamp = System.currentTimeMillis(),
clientId = clientId.ifBlank { null },
deviceName = deviceName.ifBlank { null },
userAgent = "Cyrene-Android/${Build.MODEL ?: "Device"}",
)
fun sendMessage(content: String, sessionId: String? = null, mode: String = "text") {
val msg = buildMessage("message", sessionId, mode, content)
webSocket?.send(gson.toJson(msg))
}
fun requestHistory(sessionId: String?) {
val msg = buildMessage("history", sessionId)
if (webSocket != null) {
webSocket?.send(gson.toJson(msg))
Log.i(TAG, "History requested for session=$sessionId")
} else {
Log.w(TAG, "Cannot request history: WebSocket is null")
}
}
fun sendPing() {
val msg = buildMessage("ping")
webSocket?.send(gson.toJson(msg))
}
fun sendScreenContext(content: String, sessionId: String? = null) {
val msg = buildMessage("message", sessionId, mode = "text", content = content)
webSocket?.send(gson.toJson(msg))
}
fun sendVoiceInput(audioBase64: String, sessionId: String? = null, mode: String = "voice_msg") {
val msg = WSClientMessage(
type = "voice_input",
sessionId = sessionId ?: currentSessionId,
mode = mode,
audioData = audioBase64,
timestamp = System.currentTimeMillis(),
clientId = clientId.ifBlank { null },
deviceName = deviceName.ifBlank { null },
userAgent = "Cyrene-Android/${Build.MODEL ?: "Device"}",
)
webSocket?.send(gson.toJson(msg))
}
fun forceReconnect() {
shouldReconnect = true
reconnectJob?.cancel()
reconnectJob = null
scope.launch {
if (!_isConnected.value) {
try {
connect(currentSessionId)
} catch (_: Exception) { }
}
}
}
fun disconnect() {
shouldReconnect = false
reconnectJob?.cancel()
reconnectJob = null
cancelHeartbeat()
try { webSocket?.close(1000, "User disconnected") } catch (_: Exception) { }
webSocket = null
_isConnected.value = false
}
private fun startHeartbeat() {
cancelHeartbeat()
heartbeatJob = scope.launch {
while (_isConnected.value) {
delay(30_000)
if (_isConnected.value) {
sendPing()
}
}
}
}
private fun cancelHeartbeat() {
heartbeatJob?.cancel()
heartbeatJob = null
}
private fun scheduleReconnect() {
if (reconnectJob?.isActive == true || !shouldReconnect) return
reconnectJob = scope.launch {
var attempt = 0
while (shouldReconnect && !_isConnected.value) {
val delayMs = minOf(
(Math.pow(2.0, attempt.toDouble()) * 1000).toLong(),
30_000L
)
Log.i(TAG, "Reconnecting in ${delayMs}ms (attempt ${attempt + 1})")
delay(delayMs)
attempt++
if (shouldReconnect && !_isConnected.value) {
try {
connect(currentSessionId)
} catch (e: Exception) {
Log.e(TAG, "Reconnect attempt $attempt failed: ${e.message}", e)
}
}
}
Log.i(TAG, "Reconnect loop ended (connected=${_isConnected.value}, shouldReconnect=$shouldReconnect)")
}
}
companion object {
private const val TAG = "CyreneWS"
}
}
app/src/main/java/top/yeij/cyrene/ui/components/ChatBubble.kt
-204
View File
@@ -1,204 +0,0 @@
package top.yeij.cyrene.ui.components
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.background
import androidx.compose.foundation.combinedClickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.widthIn
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ContentCopy
import androidx.compose.material3.DropdownMenu
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalClipboardManager
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import java.text.SimpleDateFormat
import java.util.Date
import java.util.Locale
@Composable
fun ChatBubble(
content: String,
role: String,
msgType: String,
timestamp: Long,
modifier: Modifier = Modifier,
) {
val isUser = role == "user"
val formattedTime = SimpleDateFormat("HH:mm", Locale.getDefault()).format(Date(timestamp))
when (msgType) {
"chat" -> ChatMessageBubble(content, isUser, formattedTime, modifier)
"action" -> ActionMessage(content, modifier)
"thinking" -> ThinkingBubble(content, modifier)
"tool_progress" -> ToolProgressBubble(content, modifier)
"system_info" -> SystemInfoBubble(content, modifier)
else -> ChatMessageBubble(content, isUser, formattedTime, modifier)
}
}
@OptIn(ExperimentalFoundationApi::class)
@Composable
private fun ChatMessageBubble(
content: String,
isUser: Boolean,
time: String,
modifier: Modifier = Modifier,
) {
var showMenu by remember { mutableStateOf(false) }
val clipboardManager = LocalClipboardManager.current
Row(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 4.dp),
horizontalArrangement = if (isUser) Arrangement.End else Arrangement.Start,
) {
Column(
horizontalAlignment = if (isUser) Alignment.End else Alignment.Start,
) {
Box {
Surface(
shape = MaterialTheme.shapes.large,
color = if (isUser)
MaterialTheme.colorScheme.primary
else
MaterialTheme.colorScheme.surfaceVariant,
shadowElevation = 2.dp,
modifier = Modifier
.widthIn(max = 300.dp)
.combinedClickable(
onClick = {},
onLongClick = { showMenu = true },
),
) {
Text(
text = content,
modifier = Modifier.padding(12.dp),
color = if (isUser)
MaterialTheme.colorScheme.onPrimary
else
MaterialTheme.colorScheme.onSurfaceVariant,
)
}
DropdownMenu(
expanded = showMenu,
onDismissRequest = { showMenu = false },
) {
DropdownMenuItem(
text = { Text("复制") },
leadingIcon = {
Icon(Icons.Default.ContentCopy, contentDescription = null)
},
onClick = {
showMenu = false
clipboardManager.setText(AnnotatedString(content))
},
)
}
}
Text(
text = time,
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
modifier = Modifier.padding(top = 2.dp),
)
}
}
}
@Composable
private fun ActionMessage(content: String, modifier: Modifier = Modifier) {
Row(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 2.dp),
horizontalArrangement = Arrangement.Start,
) {
Text(
text = content,
style = MaterialTheme.typography.bodyMedium.copy(
fontStyle = androidx.compose.ui.text.font.FontStyle.Italic,
),
color = MaterialTheme.colorScheme.onSurfaceVariant,
textAlign = TextAlign.Start,
)
}
}
@Composable
private fun ThinkingBubble(content: String, modifier: Modifier = Modifier) {
Box(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 2.dp)
.background(
color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.5f),
shape = MaterialTheme.shapes.medium,
),
) {
Text(
text = content,
modifier = Modifier.padding(10.dp),
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}
@Composable
private fun ToolProgressBubble(content: String, modifier: Modifier = Modifier) {
Row(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 2.dp),
horizontalArrangement = Arrangement.Start,
) {
Surface(
shape = MaterialTheme.shapes.small,
color = MaterialTheme.colorScheme.tertiaryContainer.copy(alpha = 0.6f),
) {
Text(
text = content,
modifier = Modifier.padding(horizontal = 10.dp, vertical = 6.dp),
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onTertiaryContainer,
)
}
}
}
@Composable
private fun SystemInfoBubble(content: String, modifier: Modifier = Modifier) {
Row(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 2.dp),
horizontalArrangement = Arrangement.Center,
) {
Text(
text = content,
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.error,
textAlign = TextAlign.Center,
)
}
}
app/src/main/java/top/yeij/cyrene/ui/components/DeviceCard.kt
-98
View File
@@ -1,98 +0,0 @@
package top.yeij.cyrene.ui.components
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Switch
import androidx.compose.material3.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.AcUnit
import androidx.compose.material.icons.filled.Curtains
import androidx.compose.material.icons.filled.Lightbulb
import androidx.compose.material.icons.filled.Lock
import androidx.compose.material.icons.filled.Sensors
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import top.yeij.cyrene.domain.model.Device
import top.yeij.cyrene.domain.model.DeviceType
@Composable
fun DeviceCard(
device: Device,
onTogglePower: () -> Unit,
modifier: Modifier = Modifier,
) {
Card(
modifier = modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 6.dp),
elevation = CardDefaults.cardElevation(defaultElevation = 2.dp),
) {
Row(
modifier = Modifier
.fillMaxWidth()
.padding(16.dp),
verticalAlignment = Alignment.CenterVertically,
horizontalArrangement = Arrangement.SpaceBetween,
) {
Row(
verticalAlignment = Alignment.CenterVertically,
horizontalArrangement = Arrangement.spacedBy(12.dp),
) {
Icon(
imageVector = device.type.toIcon(),
contentDescription = device.type.name,
tint = if (device.state.power == true)
MaterialTheme.colorScheme.primary
else
MaterialTheme.colorScheme.onSurfaceVariant,
)
Column {
Text(
text = device.name,
style = MaterialTheme.typography.titleMedium,
)
device.room?.let {
Text(
text = it,
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
device.state.temperature?.let { temp ->
Text(
text = "${"%.1f".format(temp)}°C",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}
}
if (device.state.power != null) {
Switch(
checked = device.state.power,
onCheckedChange = { onTogglePower() },
)
}
}
}
}
private fun DeviceType.toIcon() = when (this) {
DeviceType.LIGHT -> Icons.Filled.Lightbulb
DeviceType.AC -> Icons.Filled.AcUnit
DeviceType.CURTAIN -> Icons.Filled.Curtains
DeviceType.SENSOR -> Icons.Filled.Sensors
DeviceType.DOOR_LOCK -> Icons.Filled.Lock
DeviceType.UNKNOWN -> Icons.Filled.Sensors
}
app/src/main/java/top/yeij/cyrene/ui/components/StatusIndicator.kt
-94
View File
@@ -1,94 +0,0 @@
package top.yeij.cyrene.ui.components
import androidx.compose.animation.core.RepeatMode
import androidx.compose.animation.core.animateFloat
import androidx.compose.animation.core.infiniteRepeatable
import androidx.compose.animation.core.rememberInfiniteTransition
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Circle
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
enum class CyreneStatus {
ONLINE,
THINKING,
SPEAKING,
OFFLINE,
}
@Composable
fun StatusIndicator(
status: CyreneStatus,
modifier: Modifier = Modifier,
) {
Row(
modifier = modifier,
verticalAlignment = Alignment.CenterVertically,
horizontalArrangement = Arrangement.spacedBy(6.dp),
) {
when (status) {
CyreneStatus.ONLINE -> {
Icon(
Icons.Filled.Circle,
contentDescription = null,
modifier = Modifier.size(8.dp),
tint = Color(0xFF4CAF50),
)
Text("昔涟", style = MaterialTheme.typography.labelLarge)
}
CyreneStatus.THINKING -> {
PulsingDot(Color(0xFFFFA726))
Text("思考中…", style = MaterialTheme.typography.labelLarge)
}
CyreneStatus.SPEAKING -> {
PulsingDot(Color(0xFF42A5F5))
Text("正在说话…", style = MaterialTheme.typography.labelLarge)
}
CyreneStatus.OFFLINE -> {
Icon(
Icons.Filled.Circle,
contentDescription = null,
modifier = Modifier.size(8.dp),
tint = Color(0xFF9E9E9E),
)
Text("昔涟 · 离线", style = MaterialTheme.typography.labelLarge)
}
}
}
}
@Composable
private fun PulsingDot(color: Color) {
val infiniteTransition = rememberInfiniteTransition(label = "pulse")
val alpha by infiniteTransition.animateFloat(
initialValue = 0.3f,
targetValue = 1f,
animationSpec = infiniteRepeatable(
animation = tween(600),
repeatMode = RepeatMode.Reverse,
),
label = "pulse_alpha",
)
Box(
modifier = Modifier
.size(8.dp)
.alpha(alpha)
.background(color, CircleShape),
)
}
app/src/main/java/top/yeij/cyrene/ui/components/TypingIndicator.kt
-77
View File
@@ -1,77 +0,0 @@
package top.yeij.cyrene.ui.components
import androidx.compose.animation.core.RepeatMode
import androidx.compose.animation.core.animateFloat
import androidx.compose.animation.core.infiniteRepeatable
import androidx.compose.animation.core.rememberInfiniteTransition
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.unit.dp
@Composable
fun TypingIndicator(modifier: Modifier = Modifier) {
val infiniteTransition = rememberInfiniteTransition(label = "typing")
Row(
modifier = modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 4.dp),
horizontalArrangement = Arrangement.Start,
) {
Surface(
shape = MaterialTheme.shapes.large,
color = MaterialTheme.colorScheme.surfaceVariant,
shadowElevation = 1.dp,
) {
Row(
modifier = Modifier.padding(horizontal = 14.dp, vertical = 10.dp),
verticalAlignment = Alignment.CenterVertically,
horizontalArrangement = Arrangement.spacedBy(4.dp),
) {
Text(
text = "昔涟正在输入",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
repeat(3) { index ->
val alpha by infiniteTransition.animateFloat(
initialValue = 0.2f,
targetValue = 1f,
animationSpec = infiniteRepeatable(
animation = tween(
durationMillis = 400,
delayMillis = index * 200,
),
repeatMode = RepeatMode.Reverse,
),
label = "dot_$index",
)
Box(
modifier = Modifier
.size(5.dp)
.alpha(alpha)
.background(
MaterialTheme.colorScheme.onSurfaceVariant,
CircleShape,
),
)
}
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/navigation/NavGraph.kt
-160
View File
@@ -1,160 +0,0 @@
package top.yeij.cyrene.ui.navigation
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.statusBarsPadding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.Chat
import androidx.compose.material.icons.filled.DevicesOther
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.NavigationRail
import androidx.compose.material3.NavigationRailItem
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.navigation.NavHostController
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import top.yeij.cyrene.ui.screens.chat.ChatScreen
import top.yeij.cyrene.ui.screens.iot.IoTScreen
import top.yeij.cyrene.ui.screens.login.LoginScreen
import top.yeij.cyrene.ui.screens.about.AboutScreen
import top.yeij.cyrene.ui.screens.profile.ProfileScreen
import top.yeij.cyrene.ui.screens.settings.SettingsScreen
object Routes {
const val LOGIN = "login"
const val MAIN = "main"
const val CHAT = "chat"
const val IOT = "iot"
const val SETTINGS = "settings"
const val ABOUT = "about"
}
@Composable
fun CyreneNavGraph(
navController: NavHostController,
startDestination: String,
isDefaultAssistant: Boolean,
onOpenAssistantSettings: () -> Unit,
) {
NavHost(
navController = navController,
startDestination = startDestination,
) {
composable(Routes.LOGIN) {
LoginScreen(
onLoginSuccess = {
navController.navigate(Routes.MAIN) {
popUpTo(Routes.LOGIN) { inclusive = true }
}
},
)
}
composable(Routes.MAIN) {
MainScreen(
navController = navController,
isDefaultAssistant = isDefaultAssistant,
onOpenAssistantSettings = onOpenAssistantSettings,
)
}
composable(Routes.SETTINGS) {
SettingsScreen(
onBack = { navController.popBackStack() },
)
}
composable(Routes.ABOUT) {
AboutScreen(
onBack = { navController.popBackStack() },
)
}
}
}
data class BottomNavItem(
val label: String,
val icon: @Composable () -> Unit,
val route: String,
)
@Composable
fun MainScreen(
navController: NavHostController,
isDefaultAssistant: Boolean,
onOpenAssistantSettings: () -> Unit,
) {
val items = listOf(
BottomNavItem(
label = "对话",
icon = { Icon(Icons.AutoMirrored.Filled.Chat, contentDescription = "对话") },
route = Routes.CHAT,
),
BottomNavItem(
label = "设备",
icon = { Icon(Icons.Filled.DevicesOther, contentDescription = "设备") },
route = Routes.IOT,
),
BottomNavItem(
label = "我的",
icon = { Icon(Icons.Filled.Person, contentDescription = "我的") },
route = "profile",
),
)
var selectedTab by rememberSaveable { mutableIntStateOf(0) }
Row(
modifier = Modifier
.fillMaxSize()
.statusBarsPadding(),
) {
NavigationRail {
items.forEachIndexed { index, item ->
NavigationRailItem(
selected = selectedTab == index,
onClick = { selectedTab = index },
icon = item.icon,
label = { Text(item.label) },
)
}
}
Box(
modifier = Modifier
.weight(1f)
.fillMaxHeight()
.background(MaterialTheme.colorScheme.background),
) {
when (selectedTab) {
0 -> ChatScreen()
1 -> IoTScreen()
2 -> ProfileScreen(
onNavigateToSettings = { navController.navigate(Routes.SETTINGS) },
onNavigateToAbout = { navController.navigate(Routes.ABOUT) },
onLogout = {
navController.navigate(Routes.LOGIN) {
popUpTo(Routes.MAIN) { inclusive = true }
}
},
onNavigateToLogin = {
navController.navigate(Routes.LOGIN)
},
isDefaultAssistant = isDefaultAssistant,
onOpenAssistantSettings = onOpenAssistantSettings,
)
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/overlay/OverlayContent.kt
-600
View File
@@ -1,600 +0,0 @@
package top.yeij.cyrene.ui.overlay
import android.content.res.Configuration
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.animation.fadeIn
import androidx.compose.animation.slideInVertically
import androidx.compose.animation.slideOutVertically
import androidx.compose.animation.fadeOut
import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.gestures.detectDragGesturesAfterLongPress
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.OpenInNew
import androidx.compose.material.icons.automirrored.filled.Send
import androidx.compose.material.icons.filled.Close
import androidx.compose.material.icons.filled.KeyboardVoice
import androidx.compose.material.icons.filled.Lock
import androidx.compose.material.icons.filled.Mic
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.IntOffset
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.delay
import org.koin.compose.koinInject
import top.yeij.cyrene.domain.model.Message
import top.yeij.cyrene.ui.components.ChatBubble
import top.yeij.cyrene.ui.components.TypingIndicator
import top.yeij.cyrene.util.RecordState
import top.yeij.cyrene.viewmodel.OverlayState
import top.yeij.cyrene.viewmodel.OverlayViewModel
import kotlin.math.min
@Composable
private fun AnimatedChatBubble(
message: Message,
animIndex: Int,
) {
var visible by remember { mutableStateOf(false) }
LaunchedEffect(Unit) {
delay(min(animIndex, 10) * 60L)
visible = true
}
AnimatedVisibility(
visible = visible,
enter = fadeIn(animationSpec = androidx.compose.animation.core.tween(300)) +
slideInVertically(
animationSpec = androidx.compose.animation.core.tween(300),
initialOffsetY = { it / 4 },
),
) {
ChatBubble(
content = message.content,
role = message.role,
msgType = message.msgType,
timestamp = message.timestamp,
)
}
}
@Composable
fun OverlayContent(
onDismiss: () -> Unit,
onNavigateToMain: () -> Unit,
viewModel: OverlayViewModel = koinInject(),
) {
val state by viewModel.state.collectAsState()
val messages by viewModel.messages.collectAsState()
val inputText by viewModel.inputText.collectAsState()
val recordState by viewModel.voiceRecordState.collectAsState()
val recordDurationMs by viewModel.voiceRecordDurationMs.collectAsState()
val animIndex by viewModel.messageAnimIndex.collectAsState()
val listState = rememberLazyListState()
val isProcessing = state == OverlayState.PROCESSING
val recordSec = recordDurationMs / 1000f
val isRecording = recordState == RecordState.RECORDING
val isLocked = recordState == RecordState.LOCKED
// Animated "昔涟正在输入..." dots
val typingDots = remember { mutableStateOf("") }
LaunchedEffect(isProcessing) {
if (isProcessing) {
val dots = arrayOf("", ".", "..", "...")
var i = 0
while (true) {
typingDots.value = dots[i % 4]
i++
delay(400)
}
} else {
typingDots.value = ""
}
}
val configuration = LocalConfiguration.current
val isLandscape = configuration.orientation == Configuration.ORIENTATION_LANDSCAPE
// Manual status bar height — Compose WindowInsets may not work in VoiceInteractionSession
val context = androidx.compose.ui.platform.LocalContext.current
val statusBarHeight = remember {
val resourceId = context.resources.getIdentifier("status_bar_height", "dimen", "android")
if (resourceId > 0) context.resources.getDimensionPixelSize(resourceId) else 0
}
val statusBarPaddingDp = with(androidx.compose.ui.platform.LocalDensity.current) {
statusBarHeight.toDp()
}
// Manual nav bar height
val navBarHeight = remember {
val resourceId = context.resources.getIdentifier("navigation_bar_height", "dimen", "android")
if (resourceId > 0) context.resources.getDimensionPixelSize(resourceId) else 0
}
val navBarPaddingDp = with(androidx.compose.ui.platform.LocalDensity.current) {
navBarHeight.toDp()
}
LaunchedEffect(messages.size) {
if (messages.isNotEmpty()) {
listState.animateScrollToItem(messages.size - 1)
}
}
LaunchedEffect(state) {
if (state == OverlayState.IDLE) {
viewModel.finish()
onDismiss()
}
}
AnimatedVisibility(
visible = state != OverlayState.IDLE,
enter = fadeIn() + slideInVertically { it },
exit = fadeOut() + slideOutVertically { it },
) {
Box(
modifier = Modifier
.fillMaxSize()
.padding(top = statusBarPaddingDp, bottom = navBarPaddingDp),
) {
if (isLandscape) {
LandscapeContent(
state = state,
messages = messages,
inputText = inputText,
isProcessing = isProcessing,
listState = listState,
recordSec = recordSec,
isRecording = isRecording,
isLocked = isLocked,
typingDots = typingDots.value,
animIndex = animIndex,
onDismiss = onDismiss,
onNavigateToMain = onNavigateToMain,
viewModel = viewModel,
)
} else {
PortraitContent(
state = state,
messages = messages,
inputText = inputText,
isProcessing = isProcessing,
listState = listState,
recordSec = recordSec,
isRecording = isRecording,
isLocked = isLocked,
typingDots = typingDots.value,
animIndex = animIndex,
onDismiss = onDismiss,
onNavigateToMain = onNavigateToMain,
viewModel = viewModel,
)
}
}
}
}
@Suppress("LongParameterList")
@Composable
private fun PortraitContent(
state: OverlayState,
messages: List<Message>,
inputText: String,
isProcessing: Boolean,
listState: androidx.compose.foundation.lazy.LazyListState,
recordSec: Float,
isRecording: Boolean,
isLocked: Boolean,
typingDots: String,
animIndex: Map<String, Int>,
onDismiss: () -> Unit,
onNavigateToMain: () -> Unit,
viewModel: OverlayViewModel,
) {
Box(
modifier = Modifier
.fillMaxSize()
.clickable(
indication = null,
interactionSource = remember { MutableInteractionSource() },
) { /* consume clicks */ },
) {
// Messages + top bar stay fixed at top
Column(modifier = Modifier.fillMaxSize()) {
MessageTopBar(onDismiss = onDismiss, onNavigateToMain = onNavigateToMain)
LazyColumn(
modifier = Modifier
.fillMaxWidth()
.weight(1f),
state = listState,
) {
if (messages.isNotEmpty()) {
items(messages, key = { it.id }) { message ->
AnimatedChatBubble(
message = message,
animIndex = animIndex[message.id] ?: 0,
)
}
}
if (isProcessing) {
item(key = "typing_indicator") {
TypingIndicator()
}
}
}
}
// Input area at bottom, imePadding pushes it above full-screen IME
InputArea(
state = state,
inputText = inputText,
viewModel = viewModel,
modifier = Modifier
.align(Alignment.BottomCenter)
.fillMaxWidth()
.imePadding(),
recordSec = recordSec,
isRecording = isRecording,
isLocked = isLocked,
typingDots = typingDots,
)
}
}
@Suppress("LongParameterList")
@Composable
private fun LandscapeContent(
state: OverlayState,
messages: List<Message>,
inputText: String,
isProcessing: Boolean,
listState: androidx.compose.foundation.lazy.LazyListState,
recordSec: Float,
isRecording: Boolean,
isLocked: Boolean,
typingDots: String,
animIndex: Map<String, Int>,
onDismiss: () -> Unit,
onNavigateToMain: () -> Unit,
viewModel: OverlayViewModel,
) {
Row(
modifier = Modifier
.fillMaxSize()
.clickable(
indication = null,
interactionSource = remember { MutableInteractionSource() },
) { /* consume clicks */ },
) {
// Messages + top bar on the left, stay fixed
Column(modifier = Modifier.weight(1f)) {
MessageTopBar(onDismiss = onDismiss, onNavigateToMain = onNavigateToMain)
LazyColumn(
modifier = Modifier
.fillMaxWidth()
.weight(1f),
state = listState,
) {
if (messages.isNotEmpty()) {
items(messages, key = { it.id }) { message ->
AnimatedChatBubble(
message = message,
animIndex = animIndex[message.id] ?: 0,
)
}
}
if (isProcessing) {
item(key = "typing_indicator") {
TypingIndicator()
}
}
}
}
Box(
modifier = Modifier
.width(1.dp)
.fillMaxHeight()
.background(MaterialTheme.colorScheme.outlineVariant.copy(alpha = 0.3f))
)
Box(
modifier = Modifier
.weight(1f)
.fillMaxHeight(),
contentAlignment = Alignment.BottomCenter,
) {
InputArea(
state = state,
inputText = inputText,
viewModel = viewModel,
modifier = Modifier
.fillMaxWidth()
.imePadding(),
recordSec = recordSec,
isRecording = isRecording,
isLocked = isLocked,
typingDots = typingDots,
)
}
}
}
@Composable
private fun MessageTopBar(
onDismiss: () -> Unit,
onNavigateToMain: () -> Unit,
) {
Row(
modifier = Modifier
.fillMaxWidth()
.background(MaterialTheme.colorScheme.surface.copy(alpha = 0.3f))
.padding(horizontal = 8.dp, vertical = 4.dp),
verticalAlignment = Alignment.CenterVertically,
) {
IconButton(onClick = onDismiss) {
Icon(Icons.Filled.Close, contentDescription = "关闭")
}
Spacer(modifier = Modifier.weight(1f))
IconButton(onClick = onNavigateToMain) {
Icon(
Icons.AutoMirrored.Filled.OpenInNew,
contentDescription = "进入主界面",
tint = MaterialTheme.colorScheme.primary,
)
}
}
}
@Composable
private fun InputArea(
state: OverlayState,
inputText: String,
viewModel: OverlayViewModel,
modifier: Modifier = Modifier,
recordSec: Float = 0f,
isRecording: Boolean = false,
isLocked: Boolean = false,
typingDots: String = "",
) {
// Gesture tracking state — local to InputArea
var isDragging by remember { mutableStateOf(false) }
var dragOffsetX by remember { mutableStateOf(0f) }
var dragOffsetY by remember { mutableStateOf(0f) }
val inCancelZone = isDragging && dragOffsetY < -120f
val inLockZone = isDragging && dragOffsetX > 60f
val isProcessing = state == OverlayState.PROCESSING
Surface(
modifier = modifier.fillMaxWidth(),
shape = RoundedCornerShape(topStart = 24.dp, topEnd = 24.dp),
shadowElevation = 8.dp,
color = MaterialTheme.colorScheme.surface,
) {
Column(
modifier = Modifier
.fillMaxWidth()
.padding(12.dp),
) {
// "昔涟正在输入..." indicator
if (isProcessing && typingDots.isNotEmpty()) {
Text(
text = "昔涟正在输入$typingDots",
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier
.fillMaxWidth()
.padding(bottom = 4.dp),
textAlign = TextAlign.Start,
)
}
Row(
modifier = Modifier.fillMaxWidth(),
verticalAlignment = Alignment.CenterVertically,
) {
if (isRecording && isDragging) {
// Recording with drag — show recording indicator
Box(
modifier = Modifier
.weight(1f)
.clip(RoundedCornerShape(12.dp))
.background(
if (inCancelZone) MaterialTheme.colorScheme.errorContainer
else MaterialTheme.colorScheme.surfaceVariant
)
.padding(horizontal = 16.dp, vertical = 14.dp),
contentAlignment = Alignment.Center,
) {
Text(
text = when {
inCancelZone -> "松手取消"
inLockZone -> "松手录音"
else -> "%.1f\" 上滑取消 右滑松手".format(recordSec)
},
style = MaterialTheme.typography.bodyMedium,
color = if (inCancelZone) MaterialTheme.colorScheme.error
else MaterialTheme.colorScheme.onSurfaceVariant,
)
}
Box(
modifier = Modifier
.padding(start = 8.dp)
.size(48.dp)
.clip(CircleShape)
.background(MaterialTheme.colorScheme.primary)
.offset { IntOffset(dragOffsetX.toInt(), dragOffsetY.toInt()) },
contentAlignment = Alignment.Center,
) {
Icon(
Icons.Filled.Mic,
contentDescription = "录音中",
tint = MaterialTheme.colorScheme.onPrimary,
)
}
} else if (isLocked) {
// Locked (hands-free) mode
Box(
modifier = Modifier
.weight(1f)
.clip(RoundedCornerShape(12.dp))
.background(MaterialTheme.colorScheme.primaryContainer)
.padding(horizontal = 16.dp, vertical = 14.dp),
contentAlignment = Alignment.Center,
) {
Row(verticalAlignment = Alignment.CenterVertically) {
Icon(
Icons.Filled.Lock,
contentDescription = null,
modifier = Modifier.size(16.dp),
tint = MaterialTheme.colorScheme.onPrimaryContainer,
)
Spacer(modifier = Modifier.width(8.dp))
Text(
text = "%.1f\" 松手录音中 — 点击结束".format(recordSec),
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onPrimaryContainer,
)
}
}
IconButton(onClick = { viewModel.finishRecord() }) {
Icon(
Icons.AutoMirrored.Filled.Send,
contentDescription = "发送",
tint = MaterialTheme.colorScheme.primary,
)
}
} else {
// Normal input mode
OutlinedTextField(
value = inputText,
onValueChange = { viewModel.onInputChanged(it) },
placeholder = { Text("输入消息...") },
modifier = Modifier.weight(1f),
maxLines = 3,
shape = MaterialTheme.shapes.medium,
)
Spacer(modifier = Modifier.width(8.dp))
if (inputText.isNotBlank()) {
IconButton(
onClick = { viewModel.sendText() },
enabled = !isProcessing,
) {
Icon(
Icons.AutoMirrored.Filled.Send,
contentDescription = "发送",
tint = MaterialTheme.colorScheme.primary,
)
}
} else {
Box(
modifier = Modifier
.size(48.dp)
.pointerInput(Unit) {
detectDragGesturesAfterLongPress(
onDragStart = { _ ->
isDragging = true
dragOffsetX = 0f
dragOffsetY = 0f
viewModel.startRecord()
},
onDrag = { change, dragAmount ->
change.consume()
dragOffsetX += dragAmount.x
dragOffsetY += dragAmount.y
},
onDragEnd = {
isDragging = false
when {
dragOffsetY < -120f -> viewModel.cancelRecord()
dragOffsetX > 60f -> viewModel.lockRecord()
else -> viewModel.finishRecord()
}
dragOffsetX = 0f
dragOffsetY = 0f
},
onDragCancel = {
isDragging = false
viewModel.cancelRecord()
dragOffsetX = 0f
dragOffsetY = 0f
},
)
},
contentAlignment = Alignment.Center,
) {
Icon(
Icons.Filled.KeyboardVoice,
contentDescription = "按住录音",
tint = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}
}
}
// Status hint
val hint = when {
isLocked -> ""
isRecording && isDragging -> ""
else -> when (state) {
OverlayState.LISTENING -> "我在听..."
OverlayState.PROCESSING -> "思考中..."
OverlayState.SPEAKING -> "正在说话..."
OverlayState.WAITING -> "长按麦克风开始说话"
OverlayState.IDLE -> ""
}
}
if (hint.isNotEmpty()) {
Text(
text = hint,
style = MaterialTheme.typography.labelMedium,
modifier = Modifier
.fillMaxWidth()
.padding(top = 4.dp),
textAlign = TextAlign.Center,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/screens/about/AboutScreen.kt
-191
View File
@@ -1,191 +0,0 @@
package top.yeij.cyrene.ui.screens.about
import android.content.Intent
import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.automirrored.filled.OpenInNew
import androidx.compose.material.icons.filled.Code
import androidx.compose.material.icons.filled.Info
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.CenterAlignedTopAppBar
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AboutScreen(onBack: () -> Unit) {
val context = LocalContext.current
Scaffold(
topBar = {
CenterAlignedTopAppBar(
title = { Text("关于") },
navigationIcon = {
IconButton(onClick = onBack) {
Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "返回")
}
},
)
},
) { padding ->
Column(
modifier = Modifier
.fillMaxSize()
.padding(padding)
.verticalScroll(rememberScrollState()),
) {
Text(
text = "Cyrene",
style = MaterialTheme.typography.headlineLarge.copy(
fontWeight = FontWeight.Bold,
fontSize = 28.sp,
),
color = MaterialTheme.colorScheme.primary,
textAlign = TextAlign.Center,
modifier = Modifier
.fillMaxWidth()
.padding(top = 24.dp),
)
Text(
text = "昔涟",
style = MaterialTheme.typography.titleMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
textAlign = TextAlign.Center,
modifier = Modifier.fillMaxWidth(),
)
Text(
text = "v0.1.0",
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = 0.7f),
textAlign = TextAlign.Center,
modifier = Modifier
.fillMaxWidth()
.padding(top = 4.dp),
)
Spacer(modifier = Modifier.height(24.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "信息",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
)
ListItem(
headlineContent = { Text("简介") },
leadingContent = {
Icon(Icons.Filled.Info, contentDescription = null)
},
supportingContent = {
Text(
text = "Cyrene 是一款基于 Android 的智能语音助手，支持实时对话、IoT 设备管理和语音交互。",
style = MaterialTheme.typography.bodyMedium,
)
},
)
ListItem(
headlineContent = { Text("开发者") },
leadingContent = {
Icon(Icons.Filled.Person, contentDescription = null)
},
supportingContent = { Text("AskaEth") },
)
HorizontalDivider(modifier = Modifier.padding(horizontal = 16.dp))
ListItem(
headlineContent = { Text("源代码") },
leadingContent = {
Icon(Icons.Filled.Code, contentDescription = null)
},
supportingContent = { Text("git.yeij.top/AskaEth/Cyrene-For-Android") },
trailingContent = {
Icon(
Icons.AutoMirrored.Filled.OpenInNew,
contentDescription = null,
modifier = Modifier.size(20.dp),
)
},
modifier = Modifier
.fillMaxWidth()
.clickable {
val intent = Intent(Intent.ACTION_VIEW).apply {
data = Uri.parse("https://git.yeij.top/AskaEth/Cyrene-For-Android")
}
context.startActivity(intent)
},
)
Spacer(modifier = Modifier.height(24.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "技术栈",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
)
val techStack = listOf(
"Kotlin" to "主语言",
"Jetpack Compose" to "UI 框架",
"Material Design 3" to "设计系统",
"Room" to "本地数据库",
"OkHttp + Retrofit" to "网络请求",
"WebSocket" to "实时通信",
"Koin" to "依赖注入",
)
techStack.forEach { (name, desc) ->
ListItem(
headlineContent = { Text(name) },
supportingContent = { Text(desc) },
)
}
Spacer(modifier = Modifier.height(24.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "© 2026 AskaEth. All rights reserved.",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = 0.5f),
textAlign = TextAlign.Center,
modifier = Modifier
.fillMaxWidth()
.padding(vertical = 16.dp),
)
Spacer(modifier = Modifier.height(32.dp))
}
}
}
app/src/main/java/top/yeij/cyrene/ui/screens/chat/ChatScreen.kt
-370
View File
@@ -1,370 +0,0 @@
package top.yeij.cyrene.ui.screens.chat
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.animation.fadeIn
import androidx.compose.animation.slideInVertically
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.detectDragGesturesAfterLongPress
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.navigationBarsPadding
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.Send
import androidx.compose.material.icons.filled.KeyboardVoice
import androidx.compose.material.icons.filled.Lock
import androidx.compose.material.icons.filled.Mic
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.pulltorefresh.PullToRefreshBox
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.layout.onGloballyPositioned
import androidx.compose.ui.layout.positionInRoot
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.IntOffset
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.delay
import org.koin.androidx.compose.koinViewModel
import top.yeij.cyrene.domain.model.Message
import top.yeij.cyrene.ui.components.ChatBubble
import top.yeij.cyrene.ui.components.CyreneStatus
import top.yeij.cyrene.ui.components.StatusIndicator
import top.yeij.cyrene.ui.components.TypingIndicator
import top.yeij.cyrene.util.RecordState
import top.yeij.cyrene.viewmodel.ChatViewModel
import kotlin.math.min
@Composable
private fun AnimatedChatBubble(
message: Message,
animIndex: Int,
) {
var visible by remember { mutableStateOf(false) }
LaunchedEffect(Unit) {
delay(min(animIndex, 10) * 60L)
visible = true
}
AnimatedVisibility(
visible = visible,
enter = fadeIn(animationSpec = androidx.compose.animation.core.tween(300)) +
slideInVertically(
animationSpec = androidx.compose.animation.core.tween(300),
initialOffsetY = { it / 4 },
),
) {
ChatBubble(
content = message.content,
role = message.role,
msgType = message.msgType,
timestamp = message.timestamp,
)
}
}
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ChatScreen(
viewModel: ChatViewModel = koinViewModel(),
) {
val messages by viewModel.currentMessages.collectAsState()
val inputText by viewModel.inputText.collectAsState()
val isStreaming by viewModel.isStreaming.collectAsState()
val isConnected by viewModel.isConnected.collectAsState()
val isRefreshing by viewModel.isRefreshing.collectAsState()
val recordState by viewModel.voiceRecordState.collectAsState()
val recordDurationMs by viewModel.voiceRecordDurationMs.collectAsState()
val animIndex by viewModel.messageAnimIndex.collectAsState()
val listState = rememberLazyListState()
// Gesture tracking state
var isDragging by remember { mutableStateOf(false) }
var dragOffsetX by remember { mutableStateOf(0f) }
var dragOffsetY by remember { mutableStateOf(0f) }
var recordButtonY by remember { mutableStateOf(0f) }
val recordSec = recordDurationMs / 1000f
val isRecording = recordState == RecordState.RECORDING
val isLocked = recordState == RecordState.LOCKED
val inCancelZone = isDragging && dragOffsetY < -120f
val inLockZone = isDragging && dragOffsetX > 60f
LaunchedEffect(messages.size, isStreaming) {
if (messages.isNotEmpty()) {
val targetIndex = if (isStreaming) messages.size else messages.size - 1
listState.animateScrollToItem(targetIndex)
}
}
// Animated "昔涟正在输入..." dots
val typingDots = remember { mutableStateOf("") }
LaunchedEffect(isStreaming) {
if (isStreaming) {
val dots = arrayOf("", ".", "..", "...")
var i = 0
while (true) {
typingDots.value = dots[i % 4]
i++
delay(400)
}
} else {
typingDots.value = ""
}
}
val status = when {
isStreaming -> CyreneStatus.THINKING
isConnected -> CyreneStatus.ONLINE
else -> CyreneStatus.OFFLINE
}
Scaffold(
topBar = {
Row(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp, vertical = 8.dp),
verticalAlignment = Alignment.CenterVertically,
) {
StatusIndicator(status = status)
}
},
bottomBar = {
Column(
modifier = Modifier
.fillMaxWidth()
.navigationBarsPadding(),
) {
// "昔涟正在输入..." indicator
if (isStreaming) {
Text(
text = "昔涟正在输入${typingDots.value}",
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp, vertical = 2.dp),
textAlign = TextAlign.Start,
)
}
Row(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 12.dp, vertical = 8.dp),
verticalAlignment = Alignment.CenterVertically,
) {
if (isRecording && isDragging) {
// Recording state with drag — show recording indicator
Box(
modifier = Modifier
.weight(1f)
.clip(RoundedCornerShape(12.dp))
.background(
if (inCancelZone) MaterialTheme.colorScheme.errorContainer
else MaterialTheme.colorScheme.surfaceVariant
)
.padding(horizontal = 16.dp, vertical = 14.dp),
contentAlignment = Alignment.Center,
) {
Text(
text = when {
inCancelZone -> "松手取消"
inLockZone -> "松手录音"
else -> "%.1f\" 上滑取消 右滑松手".format(recordSec)
},
style = MaterialTheme.typography.bodyMedium,
color = if (inCancelZone) MaterialTheme.colorScheme.error
else MaterialTheme.colorScheme.onSurfaceVariant,
)
}
// Record button (drag anchor)
Box(
modifier = Modifier
.padding(start = 8.dp)
.size(48.dp)
.clip(CircleShape)
.background(MaterialTheme.colorScheme.primary)
.offset { IntOffset(dragOffsetX.toInt(), dragOffsetY.toInt()) },
contentAlignment = Alignment.Center,
) {
Icon(
Icons.Filled.Mic,
contentDescription = "录音中",
tint = MaterialTheme.colorScheme.onPrimary,
)
}
} else if (isLocked) {
// Locked (hands-free) mode
Box(
modifier = Modifier
.weight(1f)
.clip(RoundedCornerShape(12.dp))
.background(MaterialTheme.colorScheme.primaryContainer)
.padding(horizontal = 16.dp, vertical = 14.dp),
contentAlignment = Alignment.Center,
) {
Row(verticalAlignment = Alignment.CenterVertically) {
Icon(
Icons.Filled.Lock,
contentDescription = null,
modifier = Modifier.size(16.dp),
tint = MaterialTheme.colorScheme.onPrimaryContainer,
)
Spacer(modifier = Modifier.width(8.dp))
Text(
text = "%.1f\" 松手录音中 — 点击结束".format(recordSec),
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onPrimaryContainer,
)
}
}
IconButton(onClick = { viewModel.finishRecord() }) {
Icon(
Icons.AutoMirrored.Filled.Send,
contentDescription = "发送",
tint = MaterialTheme.colorScheme.primary,
)
}
} else {
// Normal input mode
OutlinedTextField(
value = inputText,
onValueChange = { viewModel.onInputChanged(it) },
placeholder = { Text("输入消息...") },
modifier = Modifier.weight(1f),
maxLines = 4,
shape = MaterialTheme.shapes.medium,
)
// Voice record button with long-press gesture
Box(
modifier = Modifier
.padding(start = 4.dp)
.size(48.dp)
.onGloballyPositioned { recordButtonY = it.positionInRoot().y }
.pointerInput(Unit) {
detectDragGesturesAfterLongPress(
onDragStart = { offset ->
isDragging = true
dragOffsetX = 0f
dragOffsetY = 0f
viewModel.startRecord()
},
onDrag = { change, dragAmount ->
change.consume()
dragOffsetX += dragAmount.x
dragOffsetY += dragAmount.y
},
onDragEnd = {
isDragging = false
when {
dragOffsetY < -120f -> viewModel.cancelRecord()
dragOffsetX > 60f -> viewModel.lockRecord()
else -> viewModel.finishRecord()
}
dragOffsetX = 0f
dragOffsetY = 0f
},
onDragCancel = {
isDragging = false
viewModel.cancelRecord()
dragOffsetX = 0f
dragOffsetY = 0f
},
)
},
contentAlignment = Alignment.Center,
) {
Icon(
Icons.Filled.KeyboardVoice,
contentDescription = "按住录音",
tint = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
// Send button (only when text present)
if (inputText.isNotBlank()) {
IconButton(
onClick = { viewModel.sendMessage() },
enabled = !isStreaming,
) {
if (isStreaming) {
CircularProgressIndicator(
modifier = Modifier.size(24.dp),
strokeWidth = 2.dp,
)
} else {
Icon(Icons.AutoMirrored.Filled.Send, contentDescription = "发送")
}
}
}
}
}
}
},
) { padding ->
PullToRefreshBox(
isRefreshing = isRefreshing,
onRefresh = { viewModel.refreshMessages() },
modifier = Modifier
.fillMaxSize()
.padding(padding),
) {
if (messages.isEmpty() && !isStreaming) {
Box(
modifier = Modifier.fillMaxSize(),
contentAlignment = Alignment.Center,
) {
Text(
text = "开始和昔涟对话吧",
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
} else {
LazyColumn(
modifier = Modifier.fillMaxSize(),
state = listState,
) {
items(messages, key = { it.id }) { message ->
AnimatedChatBubble(
message = message,
animIndex = animIndex[message.id] ?: 0,
)
}
if (isStreaming) {
item(key = "typing_indicator") {
TypingIndicator()
}
}
}
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/screens/iot/IoTScreen.kt
-59
View File
@@ -1,59 +0,0 @@
package top.yeij.cyrene.ui.screens.iot
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.pulltorefresh.PullToRefreshBox
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import org.koin.androidx.compose.koinViewModel
import top.yeij.cyrene.ui.components.DeviceCard
import top.yeij.cyrene.viewmodel.IoTViewModel
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun IoTScreen(
viewModel: IoTViewModel = koinViewModel(),
) {
val devices by viewModel.devices.collectAsState()
val isLoading by viewModel.isLoading.collectAsState()
PullToRefreshBox(
isRefreshing = isLoading,
onRefresh = { viewModel.refreshDevices() },
modifier = Modifier.background(MaterialTheme.colorScheme.background),
) {
if (devices.isEmpty() && !isLoading) {
Box(
modifier = Modifier.fillMaxSize().padding(32.dp),
contentAlignment = Alignment.Center,
) {
Text(
text = "暂无设备数据\n请确认已连接到服务器",
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
} else {
LazyColumn {
items(devices, key = { it.id }) { device ->
DeviceCard(
device = device,
onTogglePower = { viewModel.togglePower(device) },
)
}
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/screens/login/LoginScreen.kt
-165
View File
@@ -1,165 +0,0 @@
package top.yeij.cyrene.ui.screens.login
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.filled.Visibility
import androidx.compose.material.icons.filled.VisibilityOff
import androidx.compose.material3.Button
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Scaffold
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.launch
import org.koin.compose.koinInject
import top.yeij.cyrene.domain.usecase.LoginUseCase
import top.yeij.cyrene.viewmodel.SettingsViewModel
@Composable
fun LoginScreen(
onLoginSuccess: () -> Unit,
loginUseCase: LoginUseCase = koinInject(),
settingsViewModel: SettingsViewModel = koinInject(),
) {
var username by remember { mutableStateOf("") }
var password by remember { mutableStateOf("") }
var showPassword by remember { mutableStateOf(false) }
var isLoading by remember { mutableStateOf(false) }
val snackbarHostState = remember { SnackbarHostState() }
val scope = rememberCoroutineScope()
Scaffold(
snackbarHost = { SnackbarHost(snackbarHostState) },
) { padding ->
Column(
modifier = Modifier
.fillMaxSize()
.padding(padding)
.padding(horizontal = 32.dp),
horizontalAlignment = Alignment.CenterHorizontally,
) {
Spacer(modifier = Modifier.height(80.dp))
Icon(
imageVector = Icons.Filled.Person,
contentDescription = null,
modifier = Modifier.size(64.dp),
tint = MaterialTheme.colorScheme.primary,
)
Spacer(modifier = Modifier.height(16.dp))
Text(
text = "Cyrene",
style = MaterialTheme.typography.displayLarge,
color = MaterialTheme.colorScheme.primary,
)
Text(
text = "昔涟",
style = MaterialTheme.typography.titleMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Spacer(modifier = Modifier.height(48.dp))
OutlinedTextField(
value = username,
onValueChange = { username = it },
label = { Text("用户名") },
modifier = Modifier.fillMaxWidth(),
keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
singleLine = true,
shape = MaterialTheme.shapes.medium,
)
Spacer(modifier = Modifier.height(12.dp))
OutlinedTextField(
value = password,
onValueChange = { password = it },
label = { Text("密码") },
modifier = Modifier.fillMaxWidth(),
shape = MaterialTheme.shapes.medium,
visualTransformation = if (showPassword)
VisualTransformation.None
else
PasswordVisualTransformation(),
keyboardOptions = KeyboardOptions(
keyboardType = KeyboardType.Password,
imeAction = ImeAction.Done,
),
singleLine = true,
trailingIcon = {
IconButton(onClick = { showPassword = !showPassword }) {
Icon(
if (showPassword) Icons.Filled.VisibilityOff else Icons.Filled.Visibility,
contentDescription = if (showPassword) "隐藏密码" else "显示密码",
)
}
},
)
Spacer(modifier = Modifier.height(24.dp))
Button(
onClick = {
isLoading = true
scope.launch {
loginUseCase(username, password).fold(
onSuccess = {
isLoading = false
onLoginSuccess()
},
onFailure = { error ->
isLoading = false
scope.launch {
snackbarHostState.showSnackbar(
error.message ?: "登录失败",
)
}
},
)
}
},
modifier = Modifier.fillMaxWidth().height(50.dp),
enabled = username.isNotBlank() && password.isNotBlank() && !isLoading,
) {
if (isLoading) {
CircularProgressIndicator(
modifier = Modifier.size(20.dp),
strokeWidth = 2.dp,
color = MaterialTheme.colorScheme.onPrimary,
)
} else {
Text("登录")
}
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/screens/profile/ProfileScreen.kt
-394
View File
@@ -1,394 +0,0 @@
package top.yeij.cyrene.ui.screens.profile
import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material.icons.automirrored.filled.Help
import androidx.compose.material.icons.filled.AdminPanelSettings
import androidx.compose.material.icons.filled.CalendarMonth
import androidx.compose.material.icons.filled.ChevronRight
import androidx.compose.material.icons.filled.Circle
import androidx.compose.material.icons.filled.Info
import androidx.compose.material.icons.filled.Notifications
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.filled.Settings
import androidx.compose.material.icons.filled.Tag
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import org.koin.compose.koinInject
import top.yeij.cyrene.viewmodel.ProfileViewModel
@Composable
fun ProfileScreen(
onNavigateToSettings: () -> Unit,
onLogout: () -> Unit,
onNavigateToLogin: () -> Unit,
onNavigateToAbout: () -> Unit = {},
isDefaultAssistant: Boolean = false,
onOpenAssistantSettings: () -> Unit = {},
profileViewModel: ProfileViewModel = koinInject(),
) {
val profile by profileViewModel.profile.collectAsState()
var showLogoutDialog by remember { mutableStateOf(false) }
LaunchedEffect(Unit) {
profileViewModel.fetchFreshProfile()
}
if (showLogoutDialog) {
AlertDialog(
onDismissRequest = { showLogoutDialog = false },
title = { Text("退出登录") },
text = { Text("确定要退出登录吗？") },
confirmButton = {
TextButton(
onClick = {
showLogoutDialog = false
profileViewModel.logout()
onLogout()
},
colors = ButtonDefaults.textButtonColors(
contentColor = MaterialTheme.colorScheme.error,
),
) {
Text("退出")
}
},
dismissButton = {
TextButton(onClick = { showLogoutDialog = false }) {
Text("取消")
}
},
)
}
Column(
modifier = Modifier
.fillMaxSize()
.background(MaterialTheme.colorScheme.background)
.verticalScroll(rememberScrollState()),
) {
// Profile header
Column(
modifier = Modifier
.fillMaxWidth()
.padding(24.dp),
horizontalAlignment = Alignment.CenterHorizontally,
) {
// Avatar
val initials = if (profile.nickname.isNotBlank()) {
profile.nickname.take(1)
} else if (profile.username.isNotBlank()) {
profile.username.take(1)
} else {
"?"
}
Box(
modifier = Modifier
.size(80.dp)
.clip(CircleShape)
.background(MaterialTheme.colorScheme.primaryContainer),
contentAlignment = Alignment.Center,
) {
Text(
text = initials,
style = MaterialTheme.typography.headlineLarge,
color = MaterialTheme.colorScheme.onPrimaryContainer,
fontWeight = FontWeight.Bold,
)
}
Spacer(modifier = Modifier.height(16.dp))
if (profile.isLoading) {
CircularProgressIndicator(modifier = Modifier.size(24.dp))
} else if (!profile.isLoggedIn) {
Text(
text = "未登录",
style = MaterialTheme.typography.headlineMedium,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.clickable { onNavigateToLogin() },
)
Text(
text = "点击登录以查看个人信息",
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
} else {
// Nickname
Text(
text = profile.nickname.ifEmpty { profile.username },
style = MaterialTheme.typography.headlineMedium,
fontWeight = FontWeight.Bold,
color = MaterialTheme.colorScheme.onBackground,
)
// Username
if (profile.nickname.isNotBlank() && profile.nickname != profile.username) {
Text(
text = "@${profile.username}",
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
// Admin badge
if (profile.isAdmin) {
Spacer(modifier = Modifier.height(8.dp))
Surface(
shape = RoundedCornerShape(16.dp),
color = MaterialTheme.colorScheme.primaryContainer,
) {
Row(
modifier = Modifier.padding(horizontal = 12.dp, vertical = 4.dp),
verticalAlignment = Alignment.CenterVertically,
) {
Icon(
Icons.Filled.AdminPanelSettings,
contentDescription = null,
modifier = Modifier.size(14.dp),
tint = MaterialTheme.colorScheme.onPrimaryContainer,
)
Spacer(modifier = Modifier.width(4.dp))
Text(
text = "管理员",
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.onPrimaryContainer,
)
}
}
}
}
}
HorizontalDivider()
if (profile.isLoggedIn) {
// User info card
Spacer(modifier = Modifier.height(12.dp))
Text(
text = "账号信息",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
)
ProfileInfoCard(
items = listOf(
ProfileInfoItem(Icons.Filled.Tag, "用户 ID", profile.userId),
ProfileInfoItem(Icons.Filled.CalendarMonth, "注册时间", profile.createdAt.ifEmpty { "未知" }),
),
)
Spacer(modifier = Modifier.height(16.dp))
HorizontalDivider()
}
Spacer(modifier = Modifier.height(8.dp))
// Assistant status
Text(
text = "助手",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
)
Surface(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
shape = RoundedCornerShape(16.dp),
color = if (isDefaultAssistant)
Color(0xFF4CAF50).copy(alpha = 0.1f)
else
MaterialTheme.colorScheme.errorContainer.copy(alpha = 0.5f),
) {
Row(
modifier = Modifier.padding(16.dp),
verticalAlignment = Alignment.CenterVertically,
) {
Icon(
Icons.Filled.Circle,
contentDescription = null,
modifier = Modifier.size(10.dp),
tint = if (isDefaultAssistant) Color(0xFF4CAF50) else Color(0xFFFF5722),
)
Spacer(modifier = Modifier.width(12.dp))
Column(modifier = Modifier.weight(1f)) {
Text(
text = if (isDefaultAssistant) "已设为默认助手" else "未设为默认助手",
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onSurface,
)
if (!isDefaultAssistant) {
Text(
text = "设为默认助手后，长按电源键或Home键即可呼出昔涟",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}
if (!isDefaultAssistant) {
TextButton(onClick = onOpenAssistantSettings) {
Text("去设置")
}
}
}
}
Spacer(modifier = Modifier.height(16.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(8.dp))
// Menu items
Text(
text = "其他",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
)
ListItem(
headlineContent = { Text("设置") },
leadingContent = { Icon(Icons.Filled.Settings, contentDescription = null) },
trailingContent = { Icon(Icons.Filled.ChevronRight, contentDescription = null) },
modifier = Modifier.clickable { onNavigateToSettings() },
)
ListItem(
headlineContent = { Text("提醒") },
leadingContent = { Icon(Icons.Filled.Notifications, contentDescription = null) },
trailingContent = { Icon(Icons.Filled.ChevronRight, contentDescription = null) },
)
HorizontalDivider(modifier = Modifier.padding(horizontal = 16.dp))
ListItem(
headlineContent = { Text("关于") },
leadingContent = { Icon(Icons.Filled.Info, contentDescription = null) },
supportingContent = { Text("Cyrene v0.1.0") },
modifier = Modifier.clickable { onNavigateToAbout() },
)
ListItem(
headlineContent = { Text("使用帮助") },
leadingContent = { Icon(Icons.AutoMirrored.Filled.Help, contentDescription = null) },
)
Spacer(modifier = Modifier.height(16.dp))
// Logout
if (profile.isLoggedIn) {
ListItem(
headlineContent = {
Text(
text = "退出登录",
color = MaterialTheme.colorScheme.error,
)
},
leadingContent = {
Icon(
Icons.AutoMirrored.Filled.ExitToApp,
contentDescription = null,
tint = MaterialTheme.colorScheme.error,
)
},
modifier = Modifier.clickable { showLogoutDialog = true },
)
}
Spacer(modifier = Modifier.height(32.dp))
}
}
private data class ProfileInfoItem(
val icon: ImageVector,
val label: String,
val value: String,
)
@Composable
private fun ProfileInfoCard(items: List<ProfileInfoItem>) {
Surface(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
shape = RoundedCornerShape(16.dp),
color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.5f),
) {
Column {
items.forEachIndexed { index, item ->
Row(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp, vertical = 12.dp),
verticalAlignment = Alignment.CenterVertically,
) {
Icon(
item.icon,
contentDescription = null,
modifier = Modifier.size(20.dp),
tint = MaterialTheme.colorScheme.onSurfaceVariant,
)
Spacer(modifier = Modifier.width(12.dp))
Column(modifier = Modifier.weight(1f)) {
Text(
text = item.label,
style = MaterialTheme.typography.labelSmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
Text(
text = item.value,
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant,
)
}
}
if (index < items.size - 1) {
HorizontalDivider(
modifier = Modifier.padding(horizontal = 16.dp),
color = MaterialTheme.colorScheme.outlineVariant.copy(alpha = 0.5f),
)
}
}
}
}
}
app/src/main/java/top/yeij/cyrene/ui/screens/settings/SettingsScreen.kt
-578
View File
@@ -1,578 +0,0 @@
package top.yeij.cyrene.ui.screens.settings
import android.widget.Toast
import androidx.biometric.BiometricManager
import androidx.biometric.BiometricPrompt
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.Check
import androidx.compose.material.icons.filled.DarkMode
import androidx.compose.material.icons.filled.DeleteForever
import androidx.compose.material.icons.filled.LightMode
import androidx.compose.material.icons.filled.Palette
import androidx.compose.material.icons.filled.SettingsBrightness
import androidx.compose.material.icons.filled.Share
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.CenterAlignedTopAppBar
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FilledTonalIconButton
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Tab
import androidx.compose.material3.TabRow
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.core.content.ContextCompat
import androidx.fragment.app.FragmentActivity
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.launch
import org.koin.compose.koinInject
import top.yeij.cyrene.util.LogCategory
import top.yeij.cyrene.util.RuntimeLog
import top.yeij.cyrene.viewmodel.SettingsViewModel
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SettingsScreen(
onBack: () -> Unit,
viewModel: SettingsViewModel = koinInject(),
) {
val baseUrl by viewModel.baseUrl.collectAsState()
val themeMode by viewModel.themeMode.collectAsState()
val wakeWord by viewModel.wakeWord.collectAsState()
val dashScopeApiKey by viewModel.dashScopeApiKey.collectAsState()
val dashScopeEndpoint by viewModel.dashScopeEndpoint.collectAsState()
val dashScopeModel by viewModel.dashScopeModel.collectAsState()
val autoScreenContext by viewModel.autoScreenContext.collectAsState()
val context = LocalContext.current
val scope = rememberCoroutineScope()
fun sanitizeUrl(raw: String): String? {
var url = raw.trim()
if (url.isEmpty()) return null
val hasScheme = url.contains("://")
if (!hasScheme) url = "http://$url"
return try {
val parsed = java.net.URL(url)
val host = parsed.host ?: return null
if (host.isEmpty()) return null
val scheme = parsed.protocol
val port = if (parsed.port > 0) ":${parsed.port}" else ""
val path = parsed.path?.trimEnd('/') ?: ""
val query = parsed.query?.let { "?$it" } ?: ""
"$scheme://$host$port$path$query"
} catch (_: Exception) {
null
}
}
Scaffold(
topBar = {
CenterAlignedTopAppBar(
title = { Text("设置") },
navigationIcon = {
IconButton(onClick = onBack) {
Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "返回")
}
},
)
},
) { padding ->
Column(
modifier = Modifier
.fillMaxSize()
.padding(padding)
.verticalScroll(rememberScrollState()),
) {
// Server
Text(
text = "服务器",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(16.dp),
)
OutlinedTextField(
value = baseUrl,
onValueChange = { viewModel.updateBaseUrlInput(it) },
label = { Text("服务器地址") },
placeholder = { Text("http://192.168.1.x:8080") },
singleLine = true,
shape = MaterialTheme.shapes.medium,
keyboardOptions = KeyboardOptions(
keyboardType = KeyboardType.Uri,
imeAction = ImeAction.Done,
),
keyboardActions = KeyboardActions(
onDone = {
scope.launch {
val sanitized = sanitizeUrl(baseUrl)
if (sanitized != null) {
viewModel.saveBaseUrl(sanitized)
Toast.makeText(context, "地址已保存", Toast.LENGTH_SHORT).show()
}
}
},
),
trailingIcon = {
FilledTonalIconButton(onClick = {
val sanitized = sanitizeUrl(baseUrl)
if (sanitized != null) {
viewModel.saveBaseUrl(sanitized)
Toast.makeText(context, "地址已保存", Toast.LENGTH_SHORT).show()
} else {
Toast.makeText(context, "地址格式无效", Toast.LENGTH_SHORT).show()
}
}) {
Icon(Icons.Filled.Check, contentDescription = "确认")
}
},
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
)
Spacer(modifier = Modifier.height(16.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(16.dp))
// Appearance
Text(
text = "外观",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(16.dp),
)
val themeLabel = when (themeMode) {
"light" -> "浅色模式"
"dark" -> "深色模式"
else -> "跟随系统"
}
val themeIcon = when (themeMode) {
"light" -> Icons.Filled.LightMode
"dark" -> Icons.Filled.DarkMode
else -> Icons.Filled.SettingsBrightness
}
ListItem(
headlineContent = { Text("主题") },
supportingContent = { Text(themeLabel) },
leadingContent = { Icon(themeIcon, contentDescription = null) },
modifier = Modifier.clickable {
val next = when (themeMode) {
"light" -> "dark"
"dark" -> "auto"
else -> "light"
}
viewModel.saveThemeMode(next)
},
)
ListItem(
headlineContent = { Text("主题色") },
supportingContent = { Text("昔涟紫") },
leadingContent = { Icon(Icons.Filled.Palette, contentDescription = null) },
)
Spacer(modifier = Modifier.height(16.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(16.dp))
// Voice
Text(
text = "语音",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(16.dp),
)
OutlinedTextField(
value = wakeWord,
onValueChange = { viewModel.saveWakeWord(it) },
label = { Text("唤醒词") },
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
shape = MaterialTheme.shapes.medium,
)
Spacer(modifier = Modifier.height(8.dp))
ListItem(
headlineContent = { Text("自动读取屏幕内容") },
supportingContent = { Text("电源键唤起助手时自动截取当前屏幕内容并加入对话上下文") },
trailingContent = {
androidx.compose.material3.Switch(
checked = autoScreenContext,
onCheckedChange = { viewModel.saveAutoScreenContext(it) },
)
},
modifier = Modifier.clickable { viewModel.saveAutoScreenContext(!autoScreenContext) },
)
Spacer(modifier = Modifier.height(16.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(16.dp))
// DashScope STT
Text(
text = "语音识别 (DashScope)",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(16.dp),
)
OutlinedTextField(
value = dashScopeApiKey,
onValueChange = { viewModel.updateDashScopeApiKeyInput(it) },
label = { Text("API Key") },
placeholder = { Text("sk-xxxxxxxxxxxxxxxx") },
singleLine = true,
shape = MaterialTheme.shapes.medium,
keyboardOptions = KeyboardOptions(
keyboardType = KeyboardType.Password,
imeAction = ImeAction.Done,
),
keyboardActions = KeyboardActions(
onDone = {
scope.launch {
viewModel.saveDashScopeApiKey(dashScopeApiKey)
Toast.makeText(context, "API Key 已保存", Toast.LENGTH_SHORT).show()
}
},
),
trailingIcon = {
FilledTonalIconButton(onClick = {
scope.launch {
viewModel.saveDashScopeApiKey(dashScopeApiKey)
Toast.makeText(context, "API Key 已保存", Toast.LENGTH_SHORT).show()
}
}) {
Icon(Icons.Filled.Check, contentDescription = "保存")
}
},
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
)
Spacer(modifier = Modifier.height(8.dp))
OutlinedTextField(
value = dashScopeEndpoint,
onValueChange = { viewModel.updateDashScopeEndpointInput(it) },
label = { Text("WebSocket 端点") },
placeholder = { Text("wss://dashscope.aliyuncs.com/api-ws/v1/inference") },
singleLine = true,
shape = MaterialTheme.shapes.medium,
keyboardOptions = KeyboardOptions(
keyboardType = KeyboardType.Uri,
imeAction = ImeAction.Done,
),
keyboardActions = KeyboardActions(
onDone = {
scope.launch {
viewModel.saveDashScopeEndpoint(dashScopeEndpoint)
Toast.makeText(context, "端点已保存", Toast.LENGTH_SHORT).show()
}
},
),
trailingIcon = {
FilledTonalIconButton(onClick = {
scope.launch {
viewModel.saveDashScopeEndpoint(dashScopeEndpoint)
Toast.makeText(context, "端点已保存", Toast.LENGTH_SHORT).show()
}
}) {
Icon(Icons.Filled.Check, contentDescription = "保存")
}
},
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
)
Spacer(modifier = Modifier.height(8.dp))
OutlinedTextField(
value = dashScopeModel,
onValueChange = { viewModel.updateDashScopeModelInput(it) },
label = { Text("模型") },
placeholder = { Text("fun-asr-realtime") },
singleLine = true,
shape = MaterialTheme.shapes.medium,
keyboardOptions = KeyboardOptions(
imeAction = ImeAction.Done,
),
keyboardActions = KeyboardActions(
onDone = {
scope.launch {
viewModel.saveDashScopeModel(dashScopeModel)
Toast.makeText(context, "模型已保存", Toast.LENGTH_SHORT).show()
}
},
),
trailingIcon = {
FilledTonalIconButton(onClick = {
scope.launch {
viewModel.saveDashScopeModel(dashScopeModel)
Toast.makeText(context, "模型已保存", Toast.LENGTH_SHORT).show()
}
}) {
Icon(Icons.Filled.Check, contentDescription = "保存")
}
},
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp),
)
Spacer(modifier = Modifier.height(12.dp))
Text(
text = "未配置 API Key 时，语音输入将自动使用后端服务处理。",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
modifier = Modifier.padding(horizontal = 16.dp),
)
Spacer(modifier = Modifier.height(24.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(16.dp))
// Data management
Text(
text = "数据",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(16.dp),
)
var showClearDialog by remember { mutableStateOf(false) }
ListItem(
headlineContent = { Text("清空本地消息记录") },
supportingContent = { Text("仅清除本地数据库，服务器消息仍保留。下次加载将只获取清除时间之后的消息。") },
leadingContent = { Icon(Icons.Filled.DeleteForever, contentDescription = null, tint = MaterialTheme.colorScheme.error) },
modifier = Modifier.clickable { showClearDialog = true },
)
if (showClearDialog) {
AlertDialog(
onDismissRequest = { showClearDialog = false },
title = { Text("确认清空") },
text = { Text("将清空所有本地消息记录。服务器上的消息不会被删除，但下次加载历史时将只获取本次清除之后的消息。") },
confirmButton = {
TextButton(
onClick = {
showClearDialog = false
val activity = context as? FragmentActivity
if (activity == null) {
viewModel.clearLocalMessages()
Toast.makeText(context, "本地消息已清空", Toast.LENGTH_SHORT).show()
return@TextButton
}
val biometricManager = BiometricManager.from(context)
val canAuth = when (biometricManager.canAuthenticate(
BiometricManager.Authenticators.BIOMETRIC_STRONG or
BiometricManager.Authenticators.DEVICE_CREDENTIAL
)) {
BiometricManager.BIOMETRIC_SUCCESS -> true
else -> false
}
if (!canAuth) {
viewModel.clearLocalMessages()
Toast.makeText(context, "本地消息已清空", Toast.LENGTH_SHORT).show()
return@TextButton
}
val prompt = BiometricPrompt(
activity,
ContextCompat.getMainExecutor(context),
object : BiometricPrompt.AuthenticationCallback() {
override fun onAuthenticationSucceeded(
result: BiometricPrompt.AuthenticationResult,
) {
viewModel.clearLocalMessages()
Toast.makeText(context, "本地消息已清空", Toast.LENGTH_SHORT).show()
}
override fun onAuthenticationFailed() {
Toast.makeText(context, "验证失败", Toast.LENGTH_SHORT).show()
}
override fun onAuthenticationError(
errorCode: Int,
errString: CharSequence,
) {
Toast.makeText(context, "验证取消", Toast.LENGTH_SHORT).show()
}
},
)
prompt.authenticate(
BiometricPrompt.PromptInfo.Builder()
.setTitle("身份验证")
.setSubtitle("需要验证身份后才能清空消息记录")
.setAllowedAuthenticators(
BiometricManager.Authenticators.BIOMETRIC_STRONG or
BiometricManager.Authenticators.DEVICE_CREDENTIAL
)
.build(),
)
},
colors = ButtonDefaults.textButtonColors(contentColor = MaterialTheme.colorScheme.error),
) {
Text("清空")
}
},
dismissButton = {
TextButton(onClick = { showClearDialog = false }) {
Text("取消")
}
},
)
}
Spacer(modifier = Modifier.height(24.dp))
HorizontalDivider()
Spacer(modifier = Modifier.height(16.dp))
// Runtime logs
Text(
text = "运行日志",
style = MaterialTheme.typography.labelLarge,
color = MaterialTheme.colorScheme.primary,
modifier = Modifier.padding(16.dp),
)
val logEntries by RuntimeLog.entries.collectAsState()
var selectedTab by remember { mutableStateOf(0) }
val tabs = listOf("全部") + LogCategory.entries.map { it.label }
val allCategories = LogCategory.entries.toList()
// Scroll to bottom
val scrollState = rememberScrollState()
androidx.compose.runtime.LaunchedEffect(logEntries.size, selectedTab) {
if (logEntries.isNotEmpty()) {
scrollState.animateScrollTo(scrollState.maxValue)
}
}
TabRow(selectedTabIndex = selectedTab) {
tabs.forEachIndexed { index, label ->
Tab(
selected = selectedTab == index,
onClick = { selectedTab = index },
text = { Text(label, maxLines = 1) },
)
}
}
val filteredLogs = if (selectedTab == 0) {
logEntries
} else {
val cat = allCategories.getOrNull(selectedTab - 1)
if (cat != null) logEntries.filter { it.category == cat } else emptyList()
}
val currentCategory = if (selectedTab == 0) null else allCategories.getOrNull(selectedTab - 1)
Row(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp, vertical = 8.dp),
horizontalArrangement = Arrangement.spacedBy(8.dp),
) {
OutlinedButton(
onClick = {
val file = RuntimeLog.exportToFile(context, currentCategory)
RuntimeLog.shareFile(context, file)
},
) {
Icon(Icons.Filled.Share, contentDescription = null, modifier = Modifier.size(16.dp))
Spacer(modifier = Modifier.width(4.dp))
Text(if (currentCategory != null) "导出${currentCategory.label}" else "导出全部")
}
OutlinedButton(
onClick = {
val file = RuntimeLog.exportAllAsZip(context)
RuntimeLog.shareFile(context, file)
},
) {
Icon(Icons.Filled.Share, contentDescription = null, modifier = Modifier.size(16.dp))
Spacer(modifier = Modifier.width(4.dp))
Text("打包全部")
}
OutlinedButton(
onClick = { RuntimeLog.clear() },
colors = ButtonDefaults.outlinedButtonColors(contentColor = MaterialTheme.colorScheme.error),
) {
Text("清空")
}
}
if (filteredLogs.isEmpty()) {
Text(
text = "暂无${tabs[selectedTab]}日志",
style = MaterialTheme.typography.bodySmall,
color = MaterialTheme.colorScheme.onSurfaceVariant,
modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
)
} else {
Column(
modifier = Modifier
.fillMaxWidth()
.padding(horizontal = 16.dp)
.weight(1f, fill = false),
) {
Column(
modifier = Modifier.verticalScroll(scrollState),
) {
filteredLogs.takeLast(500).forEach { entry ->
Text(
text = entry.formatted(),
style = MaterialTheme.typography.bodySmall,
fontFamily = androidx.compose.ui.text.font.FontFamily.Monospace,
color = MaterialTheme.colorScheme.onSurfaceVariant,
modifier = Modifier.padding(vertical = 1.dp),
)
}
}
}
}
Spacer(modifier = Modifier.height(80.dp))
}
}
}
app/src/main/java/top/yeij/cyrene/ui/theme/Color.kt
-58
View File
@@ -1,58 +0,0 @@
package top.yeij.cyrene.ui.theme
import androidx.compose.ui.graphics.Color
// Light theme
val LightPrimary = Color(0xFF6D3BC0)
val LightOnPrimary = Color(0xFFFFFFFF)
val LightPrimaryContainer = Color(0xFFEEDCFF)
val LightOnPrimaryContainer = Color(0xFF250058)
val LightSecondary = Color(0xFF625B71)
val LightOnSecondary = Color(0xFFFFFFFF)
val LightSecondaryContainer = Color(0xFFE8DEF8)
val LightOnSecondaryContainer = Color(0xFF1E192B)
val LightTertiary = Color(0xFF7E5260)
val LightOnTertiary = Color(0xFFFFFFFF)
val LightTertiaryContainer = Color(0xFFFFD9E3)
val LightOnTertiaryContainer = Color(0xFF31101D)
val LightBackground = Color(0xFFFFFBFF)
val LightOnBackground = Color(0xFF1C1B1F)
val LightSurface = Color(0xFFFFFBFF)
val LightOnSurface = Color(0xFF1C1B1F)
val LightSurfaceVariant = Color(0xFFE7E0EC)
val LightOnSurfaceVariant = Color(0xFF49454F)
val LightError = Color(0xFFBA1A1A)
val LightOutline = Color(0xFF79747E)
val LightOutlineVariant = Color(0xFFCAC4D0)
// Dark theme
val DarkPrimary = Color(0xFFD3BBFF)
val DarkOnPrimary = Color(0xFF3D0089)
val DarkPrimaryContainer = Color(0xFF541BA6)
val DarkOnPrimaryContainer = Color(0xFFEEDCFF)
val DarkSecondary = Color(0xFFCBC2DC)
val DarkOnSecondary = Color(0xFF332D41)
val DarkSecondaryContainer = Color(0xFF4A4458)
val DarkOnSecondaryContainer = Color(0xFFE8DEF8)
val DarkTertiary = Color(0xFFEFB8C8)
val DarkOnTertiary = Color(0xFF4A2532)
val DarkTertiaryContainer = Color(0xFF633B48)
val DarkOnTertiaryContainer = Color(0xFFFFD9E3)
val DarkBackground = Color(0xFF1C1B1F)
val DarkOnBackground = Color(0xFFE6E1E5)
val DarkSurface = Color(0xFF1C1B1F)
val DarkOnSurface = Color(0xFFE6E1E5)
val DarkSurfaceVariant = Color(0xFF49454F)
val DarkOnSurfaceVariant = Color(0xFFCAC4D0)
val DarkError = Color(0xFFFFB4AB)
val DarkOutline = Color(0xFF938F99)
val DarkOutlineVariant = Color(0xFF49454F)
// Preset seed colors for manual theme selection
val SeedColors = mapOf(
"default" to 0xFF6D3BC0, // Lavender
"sakura" to 0xFFFFB4C8, // Pink
"ocean" to 0xFF6BA4FF, // Blue
"forest" to 0xFF6BCF7C, // Green
"sunset" to 0xFFFF9E6B, // Orange
)
app/src/main/java/top/yeij/cyrene/ui/theme/Shape.kt
-13
View File
@@ -1,13 +0,0 @@
package top.yeij.cyrene.ui.theme
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Shapes
import androidx.compose.ui.unit.dp
val CyreneShapes = Shapes(
extraSmall = RoundedCornerShape(8.dp),
small = RoundedCornerShape(12.dp),
medium = RoundedCornerShape(16.dp),
large = RoundedCornerShape(24.dp),
extraLarge = RoundedCornerShape(32.dp),
)
app/src/main/java/top/yeij/cyrene/ui/theme/Theme.kt
-101
View File
@@ -1,101 +0,0 @@
package top.yeij.cyrene.ui.theme
import android.app.Activity
import android.os.Build
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.dynamicDarkColorScheme
import androidx.compose.material3.dynamicLightColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.SideEffect
import androidx.compose.ui.graphics.toArgb
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.platform.LocalView
import androidx.core.view.WindowCompat
private val LightColorScheme = lightColorScheme(
primary = LightPrimary,
onPrimary = LightOnPrimary,
primaryContainer = LightPrimaryContainer,
onPrimaryContainer = LightOnPrimaryContainer,
secondary = LightSecondary,
onSecondary = LightOnSecondary,
secondaryContainer = LightSecondaryContainer,
onSecondaryContainer = LightOnSecondaryContainer,
tertiary = LightTertiary,
onTertiary = LightOnTertiary,
tertiaryContainer = LightTertiaryContainer,
onTertiaryContainer = LightOnTertiaryContainer,
background = LightBackground,
onBackground = LightOnBackground,
surface = LightSurface,
onSurface = LightOnSurface,
surfaceVariant = LightSurfaceVariant,
onSurfaceVariant = LightOnSurfaceVariant,
error = LightError,
outline = LightOutline,
outlineVariant = LightOutlineVariant,
)
private val DarkColorScheme = darkColorScheme(
primary = DarkPrimary,
onPrimary = DarkOnPrimary,
primaryContainer = DarkPrimaryContainer,
onPrimaryContainer = DarkOnPrimaryContainer,
secondary = DarkSecondary,
onSecondary = DarkOnSecondary,
secondaryContainer = DarkSecondaryContainer,
onSecondaryContainer = DarkOnSecondaryContainer,
tertiary = DarkTertiary,
onTertiary = DarkOnTertiary,
tertiaryContainer = DarkTertiaryContainer,
onTertiaryContainer = DarkOnTertiaryContainer,
background = DarkBackground,
onBackground = DarkOnBackground,
surface = DarkSurface,
onSurface = DarkOnSurface,
surfaceVariant = DarkSurfaceVariant,
onSurfaceVariant = DarkOnSurfaceVariant,
error = DarkError,
outline = DarkOutline,
outlineVariant = DarkOutlineVariant,
)
@Composable
fun CyreneTheme(
darkTheme: Boolean = isSystemInDarkTheme(),
dynamicColor: Boolean = true,
content: @Composable () -> Unit,
) {
val colorScheme = when {
dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
val context = LocalContext.current
if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
}
darkTheme -> DarkColorScheme
else -> LightColorScheme
}
val view = LocalView.current
if (!view.isInEditMode) {
SideEffect {
val window = (view.context as Activity).window
window.statusBarColor = colorScheme.background.toArgb()
window.navigationBarColor = colorScheme.background.toArgb()
window.decorView.setBackgroundColor(colorScheme.background.toArgb())
WindowCompat.getInsetsController(window, view).apply {
isAppearanceLightStatusBars = !darkTheme
isAppearanceLightNavigationBars = !darkTheme
}
}
}
MaterialTheme(
colorScheme = colorScheme,
typography = CyreneTypography,
shapes = CyreneShapes,
content = content,
)
}
app/src/main/java/top/yeij/cyrene/ui/theme/Type.kt
-54
View File
@@ -1,54 +0,0 @@
package top.yeij.cyrene.ui.theme
import androidx.compose.material3.Typography
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.sp
val CyreneTypography = Typography(
displayLarge = TextStyle(
fontWeight = FontWeight.Normal,
fontSize = 57.sp,
lineHeight = 64.sp,
),
headlineMedium = TextStyle(
fontWeight = FontWeight.Normal,
fontSize = 28.sp,
lineHeight = 36.sp,
),
titleLarge = TextStyle(
fontWeight = FontWeight.Normal,
fontSize = 22.sp,
lineHeight = 28.sp,
),
titleMedium = TextStyle(
fontWeight = FontWeight.Medium,
fontSize = 16.sp,
lineHeight = 24.sp,
),
bodyLarge = TextStyle(
fontWeight = FontWeight.Normal,
fontSize = 16.sp,
lineHeight = 24.sp,
),
bodyMedium = TextStyle(
fontWeight = FontWeight.Normal,
fontSize = 14.sp,
lineHeight = 20.sp,
),
labelLarge = TextStyle(
fontWeight = FontWeight.Medium,
fontSize = 14.sp,
lineHeight = 20.sp,
),
labelMedium = TextStyle(
fontWeight = FontWeight.Medium,
fontSize = 12.sp,
lineHeight = 16.sp,
),
labelSmall = TextStyle(
fontWeight = FontWeight.Medium,
fontSize = 11.sp,
lineHeight = 16.sp,
),
)
app/src/main/java/top/yeij/cyrene/util/Constants.kt
-15
View File
@@ -1,15 +0,0 @@
package top.yeij.cyrene.util
object Constants {
const val DEFAULT_WAKE_WORD = "昔涟"
const val SILENCE_TIMEOUT_MS = 10_000L
const val WS_RECONNECT_MAX_ATTEMPTS = 5
const val WS_PING_INTERVAL_SECONDS = 30L
const val HOTWORD_INACTIVITY_TIMEOUT_MINUTES = 10L
const val OVERLAY_ANIM_DURATION_MS = 300
const val STT_SILENCE_THRESHOLD_MS = 1500L
// Intent extras
const val EXTRA_VOICE_ASSIST = "voice_assist"
const val EXTRA_START_LISTENING = "start_listening"
}
app/src/main/java/top/yeij/cyrene/util/NotificationHelper.kt
-68
View File
@@ -1,68 +0,0 @@
package top.yeij.cyrene.util
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.PendingIntent
import android.content.Context
import android.content.Intent
import android.os.Build
import androidx.core.app.NotificationCompat
import top.yeij.cyrene.MainActivity
import top.yeij.cyrene.domain.model.Message
class NotificationHelper(private val context: Context) {
private val notificationManager = context.getSystemService(NotificationManager::class.java)
init {
createChannel()
}
private fun createChannel() {
val channel = NotificationChannel(
CHANNEL_ID,
"消息通知",
NotificationManager.IMPORTANCE_HIGH,
).apply {
description = "昔涟的新消息通知"
enableVibration(true)
setShowBadge(true)
}
notificationManager.createNotificationChannel(channel)
}
fun showMessageNotification(message: Message) {
val intent = Intent(context, MainActivity::class.java).apply {
flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
}
val pendingIntent = PendingIntent.getActivity(
context, 0, intent,
PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
)
val preview = if (message.content.length > 50) {
message.content.take(50) + "..."
} else {
message.content
}
val notification = NotificationCompat.Builder(context, CHANNEL_ID)
.setSmallIcon(android.R.drawable.ic_dialog_info)
.setContentTitle("昔涟")
.setContentText(preview)
.setAutoCancel(true)
.setContentIntent(pendingIntent)
.setPriority(NotificationCompat.PRIORITY_HIGH)
.build()
notificationManager.notify(message.id.hashCode(), notification)
}
fun cancelAll() {
notificationManager.cancelAll()
}
companion object {
private const val CHANNEL_ID = "cyrene_messages"
}
}
app/src/main/java/top/yeij/cyrene/util/RuntimeLog.kt
-126
View File
@@ -1,126 +0,0 @@
package top.yeij.cyrene.util
import android.content.Context
import android.content.Intent
import androidx.core.content.FileProvider
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import java.io.File
import java.text.SimpleDateFormat
import java.util.Date
import java.util.Locale
import java.util.zip.ZipEntry
import java.util.zip.ZipOutputStream
enum class LogCategory(val label: String) {
CHAT("聊天"),
WS("WebSocket"),
STT("语音识别"),
GENERAL("通用"),
HTTP("网络"),
VOICE("语音"),
}
data class LogEntry(
val timestamp: Long,
val category: LogCategory,
val tag: String,
val message: String,
) {
fun formatted(): String {
val sdf = SimpleDateFormat("HH:mm:ss.SSS", Locale.getDefault())
return "[${sdf.format(Date(timestamp))}] [${category.name}] [$tag] $message"
}
}
object RuntimeLog {
private const val MAX_ENTRIES = 2000
private val _entries = MutableStateFlow<List<LogEntry>>(emptyList())
val entries: StateFlow<List<LogEntry>> = _entries.asStateFlow()
private val buffer = ArrayDeque<LogEntry>(MAX_ENTRIES)
@Synchronized
fun log(category: LogCategory, tag: String, message: String) {
val entry = LogEntry(System.currentTimeMillis(), category, tag, message)
if (buffer.size >= MAX_ENTRIES) {
buffer.removeFirst()
}
buffer.addLast(entry)
_entries.value = buffer.toList()
}
fun chat(tag: String, message: String) = log(LogCategory.CHAT, tag, message)
fun ws(tag: String, message: String) = log(LogCategory.WS, tag, message)
fun stt(tag: String, message: String) = log(LogCategory.STT, tag, message)
fun general(tag: String, message: String) = log(LogCategory.GENERAL, tag, message)
fun http(tag: String, message: String) = log(LogCategory.HTTP, tag, message)
fun voice(tag: String, message: String) = log(LogCategory.VOICE, tag, message)
@Synchronized
fun getByCategory(category: LogCategory): List<LogEntry> {
return buffer.filter { it.category == category }
}
@Synchronized
fun exportAsText(category: LogCategory): String {
val entries = buffer.filter { it.category == category }
val header = "=== Cyrene ${category.label}日志 导出时间: ${
SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault()).format(Date())
} ===\n\n"
return header + entries.joinToString("\n") { it.formatted() }
}
@Synchronized
fun exportAllAsText(): String {
val header = "=== Cyrene 全部日志 导出时间: ${
SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault()).format(Date())
} ===\n\n"
val byCategory = buffer.groupBy { it.category }
return header + byCategory.entries.joinToString("\n\n") { (cat, entries) ->
"--- ${cat.label} (${cat.name}) ---\n" + entries.joinToString("\n") { it.formatted() }
}
}
fun exportToFile(context: Context, category: LogCategory? = null): File {
val text = if (category != null) exportAsText(category) else exportAllAsText()
val label = category?.name?.lowercase() ?: "all"
val dateStr = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.getDefault()).format(Date())
val file = File(context.cacheDir, "cyrene_log_${label}_$dateStr.txt")
file.writeText(text)
return file
}
fun exportAllAsZip(context: Context): File {
val dateStr = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.getDefault()).format(Date())
val zipFile = File(context.cacheDir, "cyrene_logs_$dateStr.zip")
ZipOutputStream(zipFile.outputStream().buffered()).use { zos ->
LogCategory.entries.forEach { cat ->
val text = exportAsText(cat)
zos.putNextEntry(ZipEntry("${cat.name.lowercase()}.txt"))
zos.write(text.toByteArray(Charsets.UTF_8))
zos.closeEntry()
}
}
return zipFile
}
fun shareFile(context: Context, file: File) {
val uri = FileProvider.getUriForFile(context, "${context.packageName}.fileprovider", file)
val intent = Intent(Intent.ACTION_SEND).apply {
type = if (file.extension == "zip") "application/zip" else "text/plain"
putExtra(Intent.EXTRA_STREAM, uri)
addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
}
context.startActivity(Intent.createChooser(intent, "导出日志"))
}
@Synchronized
fun clear() {
buffer.clear()
_entries.value = emptyList()
}
}
app/src/main/java/top/yeij/cyrene/util/VoiceRecorder.kt
-158
View File
@@ -1,158 +0,0 @@
package top.yeij.cyrene.util
import android.content.Context
import android.media.MediaRecorder
import android.os.Build
import android.util.Base64
import android.util.Log
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import java.io.File
enum class RecordState {
IDLE,
RECORDING,
LOCKED, // hands-free mode
CANCELLING,
}
class VoiceRecorder(private val context: Context) {
private var recorder: MediaRecorder? = null
private var outputFile: File? = null
private var timerJob: Job? = null
private val _state = MutableStateFlow(RecordState.IDLE)
val state: StateFlow<RecordState> = _state.asStateFlow()
private val _durationMs = MutableStateFlow(0L)
val durationMs: StateFlow<Long> = _durationMs.asStateFlow()
fun start() {
if (_state.value != RecordState.IDLE) return
try {
outputFile = File(context.cacheDir, "voice_${System.currentTimeMillis()}.aac")
outputFile?.delete()
recorder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
MediaRecorder(context)
} else {
@Suppress("DEPRECATION")
MediaRecorder()
}
recorder?.apply {
setAudioSource(MediaRecorder.AudioSource.MIC)
setOutputFormat(MediaRecorder.OutputFormat.AAC_ADTS)
setAudioEncoder(MediaRecorder.AudioEncoder.AAC)
setAudioSamplingRate(16000)
setAudioEncodingBitRate(32000)
setAudioChannels(1)
setOutputFile(outputFile?.absolutePath)
prepare()
start()
}
_state.value = RecordState.RECORDING
startTimer()
Log.i(TAG, "Recording started: ${outputFile?.absolutePath}")
} catch (e: Exception) {
Log.e(TAG, "Failed to start recording: ${e.message}", e)
cleanup()
}
}
fun lock() {
if (_state.value == RecordState.RECORDING) {
_state.value = RecordState.LOCKED
}
}
fun stop(): File? {
if (_state.value == RecordState.IDLE) return null
val file = outputFile
try {
recorder?.apply {
try { stop() } catch (_: Exception) { }
try { release() } catch (_: Exception) { }
}
} catch (e: Exception) {
Log.e(TAG, "Error stopping recorder: ${e.message}", e)
}
recorder = null
cancelTimer()
_state.value = RecordState.IDLE
_durationMs.value = 0L
Log.i(TAG, "Recording stopped: ${file?.absolutePath}, size=${file?.length()}")
return if (file != null && file.exists() && file.length() > 0) file else null
}
fun cancel() {
val file = outputFile
try {
recorder?.apply {
try { stop() } catch (_: Exception) { }
try { release() } catch (_: Exception) { }
}
} catch (e: Exception) { }
recorder = null
file?.delete()
cancelTimer()
_state.value = RecordState.IDLE
_durationMs.value = 0L
Log.i(TAG, "Recording cancelled")
}
fun cleanup() {
try { recorder?.release() } catch (_: Exception) { }
recorder = null
outputFile?.delete()
outputFile = null
cancelTimer()
_state.value = RecordState.IDLE
_durationMs.value = 0L
}
fun getBase64(): String? {
val file = outputFile ?: return null
if (!file.exists()) return null
return try {
val bytes = file.readBytes()
Base64.encodeToString(bytes, Base64.NO_WRAP)
} catch (e: Exception) {
Log.e(TAG, "Failed to encode audio: ${e.message}", e)
null
}
}
fun deleteFile() {
outputFile?.delete()
outputFile = null
}
private fun startTimer() {
cancelTimer()
val startTime = System.currentTimeMillis()
timerJob = CoroutineScope(Dispatchers.Main).launch {
while (true) {
delay(100)
_durationMs.value = System.currentTimeMillis() - startTime
}
}
}
private fun cancelTimer() {
timerJob?.cancel()
timerJob = null
}
companion object {
private const val TAG = "VoiceRecorder"
}
}
app/src/main/java/top/yeij/cyrene/viewmodel/ChatViewModel.kt
-281
View File
@@ -1,281 +0,0 @@
package top.yeij.cyrene.viewmodel
import android.util.Log
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import top.yeij.cyrene.domain.model.Conversation
import top.yeij.cyrene.domain.model.Message
import top.yeij.cyrene.domain.repository.ChatRepository
import top.yeij.cyrene.util.RecordState
import top.yeij.cyrene.util.RuntimeLog
import top.yeij.cyrene.util.VoiceRecorder
private fun List<Message>.deduplicate(): List<Message> {
if (isEmpty()) return this
val result = mutableListOf(this[0])
for (i in 1 until size) {
val prev = result.last()
val curr = this[i]
val isDuplicate = curr.id == prev.id ||
(curr.role == prev.role && curr.content == prev.content && curr.msgType == prev.msgType)
if (!isDuplicate) {
result.add(curr)
}
}
return result
}
private fun List<Message>.removeWrappingDuplicates(): List<Message> {
if (size < 3) return this
val toRemove = mutableSetOf<String>()
for (msg in this) {
val containedCount = count { other ->
other.id != msg.id &&
other.content.isNotBlank() &&
other.content.length < msg.content.length &&
msg.content.contains(other.content) &&
kotlin.math.abs(other.timestamp - msg.timestamp) < 2000
}
if (containedCount >= 2) {
toRemove.add(msg.id)
}
}
return if (toRemove.isEmpty()) this else filter { it.id !in toRemove }
}
class ChatViewModel(
private val chatRepository: ChatRepository,
private val voiceRecorder: VoiceRecorder,
) : ViewModel() {
val isConnected: StateFlow<Boolean> = chatRepository.connectionState
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), false)
val connectionError: StateFlow<String?> = chatRepository.connectionError
val conversations: StateFlow<List<Conversation>> = chatRepository.getConversations()
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
private val _currentMessages = MutableStateFlow<List<Message>>(emptyList())
val currentMessages: StateFlow<List<Message>> = _currentMessages.asStateFlow()
private val _inputText = MutableStateFlow("")
val inputText: StateFlow<String> = _inputText.asStateFlow()
private val _isSending = MutableStateFlow(false)
val isStreaming: StateFlow<Boolean> = kotlinx.coroutines.flow.combine(
_isSending,
chatRepository.isAssistantStreaming,
) { sending, assistant -> sending || assistant }
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), false)
private val _isRefreshing = MutableStateFlow(false)
val isRefreshing: StateFlow<Boolean> = _isRefreshing.asStateFlow()
// Voice recording state
val voiceRecordState: StateFlow<RecordState> = voiceRecorder.state
val voiceRecordDurationMs: StateFlow<Long> = voiceRecorder.durationMs
// Animation ordering for message bubbles
private var animCounter = 0
private val _messageAnimIndex = MutableStateFlow<Map<String, Int>>(emptyMap())
val messageAnimIndex: StateFlow<Map<String, Int>> = _messageAnimIndex.asStateFlow()
private var currentSessionId: String? = null
private var dbObserverJob: Job? = null
init {
// Phase 1: find/create main session, reconnect WS, load server history
viewModelScope.launch {
try {
val sessionId = chatRepository.initializeSession()
currentSessionId = sessionId
chatRepository.currentSessionId = sessionId
chatRepository.ensureConnected()
loadMessagesFromDb(sessionId)
val serverMessages = chatRepository.loadMessagesFromServer(sessionId)
if (serverMessages.isNotEmpty()) {
val serverIds = serverMessages.map { it.id }.toSet()
_currentMessages.update { current ->
val localOnly = current.filter { it.id !in serverIds }
(serverMessages + localOnly)
.sortedBy { it.timestamp }
.deduplicate()
.removeWrappingDuplicates()
}
}
} catch (_: Exception) { }
}
// Observe incoming live messages with atomic dedup
viewModelScope.launch {
chatRepository.observeMessages().collect { message ->
try {
_currentMessages.update { list ->
val updated = list.toMutableList()
val existingIdx = updated.indexOfLast { it.id == message.id }
if (existingIdx >= 0) {
updated[existingIdx] = message
} else {
val isDup = updated.any {
it.role == message.role && it.content == message.content && it.msgType == message.msgType
}
if (!isDup) {
updated.add(message)
val idx = _messageAnimIndex.value.toMutableMap()
idx[message.id] = animCounter++
_messageAnimIndex.value = idx
}
}
updated.deduplicate()
}
} catch (e: Exception) {
Log.e("ChatViewModel", "Error processing message: ${e.message}", e)
}
}
}
// Observe message clear events
viewModelScope.launch {
chatRepository.messageClearEvents.collect {
_currentMessages.value = emptyList()
_messageAnimIndex.value = emptyMap()
animCounter = 0
}
}
// Reset user-side sending state when server starts responding
viewModelScope.launch {
chatRepository.isAssistantStreaming.collect { streaming ->
if (streaming) _isSending.value = false
}
}
}
// --- Voice recording (WeChat-style gesture) ---
fun startRecord() {
voiceRecorder.start()
}
fun lockRecord() {
voiceRecorder.lock()
}
fun finishRecord() {
val file = voiceRecorder.stop() ?: return
val base64 = voiceRecorder.getBase64()
voiceRecorder.deleteFile()
if (base64.isNullOrBlank()) return
viewModelScope.launch {
chatRepository.sendVoiceInput(base64, "voice_msg")
RuntimeLog.chat("voice", "Voice message sent, duration=${file.length()}")
}
}
fun cancelRecord() {
voiceRecorder.cancel()
}
private fun loadMessagesFromDb(sessionId: String) {
dbObserverJob?.cancel()
dbObserverJob = viewModelScope.launch {
try {
chatRepository.getMessages(sessionId).collect { messages ->
_currentMessages.update { current ->
val live = current.associateBy { it.id }
val db = messages.associateBy { it.id }
(db + live).values
.sortedBy { it.timestamp }
.deduplicate()
.removeWrappingDuplicates()
}
val idx = _messageAnimIndex.value.toMutableMap()
messages.forEach { m ->
if (m.id !in idx) idx[m.id] = animCounter++
}
_messageAnimIndex.value = idx
}
} catch (e: Exception) {
Log.e("ChatViewModel", "Error loading messages: ${e.message}", e)
}
}
}
fun onInputChanged(text: String) {
_inputText.value = text
}
fun sendMessage() {
val text = _inputText.value.trim()
if (text.isEmpty()) return
_inputText.value = ""
_isSending.value = true
val sid = currentSessionId
viewModelScope.launch {
chatRepository.sendMessage(text, sid)
}
}
fun switchSession(sessionId: String) {
currentSessionId = sessionId
chatRepository.currentSessionId = sessionId
_currentMessages.value = emptyList()
_messageAnimIndex.value = emptyMap()
animCounter = 0
viewModelScope.launch {
chatRepository.connectWebSocket(sessionId)
chatRepository.loadMessagesFromServer(sessionId)
}
loadMessagesFromDb(sessionId)
}
fun refreshMessages() {
val sid = currentSessionId ?: return
viewModelScope.launch {
_isRefreshing.value = true
try {
if (!isConnected.value) {
chatRepository.ensureConnected()
}
val serverMessages = chatRepository.loadMessagesFromServer(sid)
if (serverMessages.isNotEmpty()) {
val serverIds = serverMessages.map { it.id }.toSet()
_currentMessages.update { current ->
val localOnly = current.filter { it.id !in serverIds }
(serverMessages + localOnly)
.sortedBy { it.timestamp }
.deduplicate()
.removeWrappingDuplicates()
}
}
} catch (_: Exception) { }
_isRefreshing.value = false
}
}
fun deleteConversation(id: String) {
viewModelScope.launch {
chatRepository.deleteConversation(id)
}
}
fun clearLocalMessages() {
viewModelScope.launch {
chatRepository.clearLocalMessages()
_currentMessages.value = emptyList()
_messageAnimIndex.value = emptyMap()
animCounter = 0
}
}
}
app/src/main/java/top/yeij/cyrene/viewmodel/IoTViewModel.kt
-59
View File
@@ -1,59 +0,0 @@
package top.yeij.cyrene.viewmodel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import top.yeij.cyrene.domain.model.Device
import top.yeij.cyrene.domain.repository.IoTRepository
class IoTViewModel(
private val ioTRepository: IoTRepository,
) : ViewModel() {
val devices: StateFlow<List<Device>> = ioTRepository.getDevices()
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
private val _isLoading = MutableStateFlow(false)
val isLoading: StateFlow<Boolean> = _isLoading.asStateFlow()
private val _error = MutableStateFlow<String?>(null)
val error: StateFlow<String?> = _error.asStateFlow()
init {
refreshDevices()
}
fun refreshDevices() {
viewModelScope.launch {
_isLoading.value = true
ioTRepository.refreshDevices()
_isLoading.value = false
}
}
fun controlDevice(deviceId: String, action: String, value: Any? = null) {
viewModelScope.launch {
_isLoading.value = true
_error.value = null
ioTRepository.controlDevice(deviceId, action, value).fold(
onSuccess = { },
onFailure = { _error.value = it.message },
)
_isLoading.value = false
}
}
fun togglePower(device: Device) {
val action = if (device.state.power == true) "off" else "on"
controlDevice(device.id, action)
}
fun clearError() {
_error.value = null
}
}
app/src/main/java/top/yeij/cyrene/viewmodel/OverlayViewModel.kt
-237
View File
@@ -1,237 +0,0 @@
package top.yeij.cyrene.viewmodel
import android.util.Log
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import top.yeij.cyrene.domain.model.Message
import top.yeij.cyrene.domain.repository.ChatRepository
import top.yeij.cyrene.util.Constants
import top.yeij.cyrene.util.RecordState
import top.yeij.cyrene.util.VoiceRecorder
import top.yeij.cyrene.voice.tts.TextToSpeechEngine
private fun List<Message>.deduplicate(): List<Message> {
if (isEmpty()) return this
val result = mutableListOf(this[0])
for (i in 1 until size) {
val prev = result.last()
val curr = this[i]
val isDuplicate = curr.id == prev.id ||
(curr.role == prev.role && curr.content == prev.content && curr.msgType == prev.msgType)
if (!isDuplicate) {
result.add(curr)
}
}
return result
}
private fun List<Message>.removeWrappingDuplicates(): List<Message> {
if (size < 3) return this
val toRemove = mutableSetOf<String>()
for (msg in this) {
val containedCount = count { other ->
other.id != msg.id &&
other.content.isNotBlank() &&
other.content.length < msg.content.length &&
msg.content.contains(other.content) &&
kotlin.math.abs(other.timestamp - msg.timestamp) < 2000
}
if (containedCount >= 2) {
toRemove.add(msg.id)
}
}
return if (toRemove.isEmpty()) this else filter { it.id !in toRemove }
}
enum class OverlayState {
IDLE,
LISTENING,
PROCESSING,
SPEAKING,
WAITING,
}
class OverlayViewModel(
private val chatRepository: ChatRepository,
private val voiceRecorder: VoiceRecorder,
private val ttsEngine: TextToSpeechEngine,
) : ViewModel() {
private val _state = MutableStateFlow(OverlayState.WAITING)
val state: StateFlow<OverlayState> = _state.asStateFlow()
private val _messages = MutableStateFlow<List<Message>>(emptyList())
val messages: StateFlow<List<Message>> = _messages.asStateFlow()
private val _inputText = MutableStateFlow("")
val inputText: StateFlow<String> = _inputText.asStateFlow()
val voiceRecordState: StateFlow<RecordState> = voiceRecorder.state
val voiceRecordDurationMs: StateFlow<Long> = voiceRecorder.durationMs
// Animation ordering for message bubbles
private var animCounter = 0
private val _messageAnimIndex = MutableStateFlow<Map<String, Int>>(emptyMap())
val messageAnimIndex: StateFlow<Map<String, Int>> = _messageAnimIndex.asStateFlow()
private var silenceTimer: Job? = null
private var lastAssistantMessageId: String? = null
init {
viewModelScope.launch {
chatRepository.observeMessages().collect { message ->
_messages.update { list ->
val updated = list.toMutableList()
val idx = updated.indexOfLast { it.id == message.id }
if (idx >= 0) {
updated[idx] = message
} else {
val isDup = updated.any {
it.role == message.role && it.content == message.content && it.msgType == message.msgType
}
if (!isDup) {
updated.add(message)
val animIdx = _messageAnimIndex.value.toMutableMap()
animIdx[message.id] = animCounter++
_messageAnimIndex.value = animIdx
}
}
updated.deduplicate()
}
if (message.role == "assistant" && !message.isStreaming && message.msgType == "chat") {
if (message.id != lastAssistantMessageId && message.content.isNotBlank()) {
lastAssistantMessageId = message.id
speakResponse(message.content)
}
}
}
}
viewModelScope.launch {
ttsEngine.onDone.collect {
if (_state.value == OverlayState.SPEAKING) {
setWaiting()
}
}
}
viewModelScope.launch {
chatRepository.messageClearEvents.collect {
_messages.value = emptyList()
_messageAnimIndex.value = emptyMap()
animCounter = 0
}
}
}
fun onInputChanged(text: String) {
_inputText.value = text
}
fun sendText() {
val text = _inputText.value.trim()
if (text.isEmpty()) return
_inputText.value = ""
_state.value = OverlayState.PROCESSING
cancelSilenceTimer()
viewModelScope.launch {
chatRepository.sendMessage(text, null)
}
}
// --- Voice recording (WeChat-style gesture) ---
fun startRecord() {
voiceRecorder.start()
_state.value = OverlayState.LISTENING
cancelSilenceTimer()
}
fun lockRecord() {
voiceRecorder.lock()
}
fun finishRecord() {
val file = voiceRecorder.stop() ?: return
val base64 = voiceRecorder.getBase64()
voiceRecorder.deleteFile()
if (base64.isNullOrBlank()) return
_state.value = OverlayState.PROCESSING
viewModelScope.launch {
chatRepository.sendVoiceInput(base64, "voice_msg")
}
}
fun cancelRecord() {
voiceRecorder.cancel()
setWaiting()
}
fun cancelCurrentAction() {
if (voiceRecorder.state.value == RecordState.LOCKED) {
voiceRecorder.cancel()
setWaiting()
}
}
private fun speakResponse(text: String) {
if (text.isBlank()) return
_state.value = OverlayState.SPEAKING
ttsEngine.speak(text)
}
private fun setWaiting() {
_state.value = OverlayState.WAITING
startSilenceTimer()
}
fun stopSpeaking() {
ttsEngine.stop()
if (_state.value == OverlayState.SPEAKING) {
setWaiting()
}
}
fun sendScreenContext(content: String) {
if (content.isBlank()) return
viewModelScope.launch {
chatRepository.sendScreenContext(content)
}
}
fun finish() {
_state.value = OverlayState.IDLE
cancelSilenceTimer()
voiceRecorder.cancel()
ttsEngine.stop()
}
private fun startSilenceTimer() {
cancelSilenceTimer()
silenceTimer = viewModelScope.launch {
delay(Constants.SILENCE_TIMEOUT_MS)
if (_state.value == OverlayState.WAITING) {
_state.value = OverlayState.IDLE
}
}
}
private fun cancelSilenceTimer() {
silenceTimer?.cancel()
silenceTimer = null
}
override fun onCleared() {
voiceRecorder.cancel()
ttsEngine.shutdown()
super.onCleared()
}
}
app/src/main/java/top/yeij/cyrene/viewmodel/ProfileViewModel.kt
-120
View File
@@ -1,120 +0,0 @@
package top.yeij.cyrene.viewmodel
import android.util.Log
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.launch
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.ApiService
import top.yeij.cyrene.domain.repository.AuthRepository
data class ProfileState(
val userId: String = "",
val username: String = "",
val nickname: String = "",
val isAdmin: Boolean = false,
val createdAt: String = "",
val isLoading: Boolean = false,
val isLoggedIn: Boolean = false,
)
class ProfileViewModel(
private val apiService: ApiService,
private val authRepository: AuthRepository,
private val prefs: PreferencesDataStore,
) : ViewModel() {
private val _profile = MutableStateFlow(ProfileState())
val profile: StateFlow<ProfileState> = _profile.asStateFlow()
private var loadedFromCache = false
init {
viewModelScope.launch {
_profile.value = _profile.value.copy(isLoggedIn = authRepository.isLoggedIn())
if (_profile.value.isLoggedIn) {
loadCachedProfile()
fetchFreshProfile()
}
}
}
/**
* Show cached profile immediately for instant UI.
*/
private suspend fun loadCachedProfile() {
val userId = prefs.profileUserId.firstOrNull() ?: return
val nickname = prefs.profileNickname.firstOrNull() ?: ""
val isAdmin = prefs.profileIsAdmin.firstOrNull()?.toBoolean() ?: false
val createdAt = prefs.profileCreatedAt.firstOrNull() ?: ""
val username = prefs.username.firstOrNull() ?: ""
_profile.value = ProfileState(
userId = userId,
username = username,
nickname = nickname,
isAdmin = isAdmin,
createdAt = createdAt,
isLoggedIn = true,
)
loadedFromCache = true
}
/**
* Fetch fresh profile from server. On success, update cache and UI.
* On failure, keep showing cached data — no error, no UI disruption.
*/
fun fetchFreshProfile() {
viewModelScope.launch {
if (!loadedFromCache) {
_profile.value = _profile.value.copy(isLoading = true)
}
try {
val response = apiService.getProfile()
if (response.isSuccessful) {
val body = response.body()
if (body != null) {
val dateStr = body.createdAt?.take(10) ?: ""
val nickname = body.nickname ?: body.username
_profile.value = ProfileState(
userId = body.userId,
username = body.username,
nickname = nickname,
isAdmin = body.isAdmin == true,
createdAt = dateStr,
isLoading = false,
isLoggedIn = true,
)
loadedFromCache = true
// Update local cache
prefs.saveProfileCache(body.userId, nickname, body.isAdmin == true, dateStr)
}
} else if (!loadedFromCache) {
_profile.value = _profile.value.copy(isLoading = false)
}
// On error with cache already shown: silently ignore
} catch (e: Exception) {
Log.w("ProfileVM", "Failed to fetch fresh profile: ${e.message}")
if (!loadedFromCache) {
_profile.value = _profile.value.copy(isLoading = false)
}
// If cached data is showing, keep it silently
}
}
}
fun logout() {
viewModelScope.launch {
authRepository.logout()
prefs.clearProfileCache()
_profile.value = ProfileState()
loadedFromCache = false
}
}
}
app/src/main/java/top/yeij/cyrene/viewmodel/SettingsViewModel.kt
-180
View File
@@ -1,180 +0,0 @@
package top.yeij.cyrene.viewmodel
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import top.yeij.cyrene.data.local.PreferencesDataStore
import top.yeij.cyrene.data.remote.DynamicUrlInterceptor
import top.yeij.cyrene.domain.repository.AuthRepository
import top.yeij.cyrene.domain.repository.ChatRepository
import top.yeij.cyrene.voice.stt.SttManager
class SettingsViewModel(
private val authRepository: AuthRepository,
private val preferencesDataStore: PreferencesDataStore,
private val dynamicUrlInterceptor: DynamicUrlInterceptor,
private val chatRepository: ChatRepository,
private val sttManager: SttManager,
) {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
private val _baseUrl = MutableStateFlow("")
val baseUrl: StateFlow<String> = _baseUrl.asStateFlow()
private val _themeMode = MutableStateFlow("auto")
val themeMode: StateFlow<String> = _themeMode.asStateFlow()
private val _wakeWord = MutableStateFlow("昔涟")
val wakeWord: StateFlow<String> = _wakeWord.asStateFlow()
private val _username = MutableStateFlow("")
val username: StateFlow<String> = _username.asStateFlow()
private val _dashScopeApiKey = MutableStateFlow("")
val dashScopeApiKey: StateFlow<String> = _dashScopeApiKey.asStateFlow()
private val _dashScopeEndpoint = MutableStateFlow("wss://dashscope.aliyuncs.com/api-ws/v1/inference")
val dashScopeEndpoint: StateFlow<String> = _dashScopeEndpoint.asStateFlow()
private val _dashScopeModel = MutableStateFlow("fun-asr-realtime")
val dashScopeModel: StateFlow<String> = _dashScopeModel.asStateFlow()
private val _autoScreenContext = MutableStateFlow(false)
val autoScreenContext: StateFlow<Boolean> = _autoScreenContext.asStateFlow()
private val _isLoggedIn = MutableStateFlow(false)
val isLoggedIn: StateFlow<Boolean> = _isLoggedIn.asStateFlow()
init {
scope.launch {
_isLoggedIn.value = authRepository.isLoggedIn()
}
// Single collector for all DataStore preferences — avoids subscriber explosion
scope.launch {
preferencesDataStore.autoScreenContext.collect { value ->
_autoScreenContext.value = value
}
}
scope.launch {
combine(
preferencesDataStore.baseUrl,
preferencesDataStore.themeMode,
preferencesDataStore.wakeWord,
preferencesDataStore.username,
combine(
preferencesDataStore.dashScopeApiKey,
preferencesDataStore.dashScopeEndpoint,
preferencesDataStore.dashScopeModel,
) { apiKey, endpoint, model ->
Triple(apiKey, endpoint, model)
},
) { baseUrl, themeMode, wakeWord, username, dashScope ->
baseUrl?.let { url ->
if (url.isNotBlank()) {
_baseUrl.value = url
dynamicUrlInterceptor.baseUrl = url
}
}
themeMode?.let { _themeMode.value = it }
wakeWord?.let { word ->
if (word.isNotBlank()) _wakeWord.value = word
}
username?.let { _username.value = it }
val (apiKey, endpoint, model) = dashScope
apiKey?.let { key ->
if (key.isNotBlank()) _dashScopeApiKey.value = key
sttManager.updateDashScopeApiKey(key)
}
endpoint?.let { ep ->
if (ep.isNotBlank()) _dashScopeEndpoint.value = ep
}
model?.let { m ->
if (m.isNotBlank()) _dashScopeModel.value = m
}
// Push full config to STT
sttManager.configureDashScope(
apiKey = _dashScopeApiKey.value,
endpoint = _dashScopeEndpoint.value,
model = _dashScopeModel.value,
)
}.collect { }
}
}
fun updateBaseUrlInput(url: String) {
_baseUrl.value = url
}
fun saveBaseUrl(url: String) {
_baseUrl.value = url
dynamicUrlInterceptor.baseUrl = url
scope.launch {
preferencesDataStore.saveBaseUrl(url)
chatRepository.reconnectWebSocket()
}
}
fun saveThemeMode(mode: String) {
_themeMode.value = mode
scope.launch { preferencesDataStore.saveThemeMode(mode) }
}
fun saveWakeWord(word: String) {
_wakeWord.value = word
scope.launch { preferencesDataStore.saveWakeWord(word) }
}
fun updateDashScopeApiKeyInput(key: String) {
_dashScopeApiKey.value = key
}
fun saveDashScopeApiKey(key: String) {
_dashScopeApiKey.value = key
sttManager.updateDashScopeApiKey(key)
scope.launch { preferencesDataStore.saveDashScopeApiKey(key) }
}
fun updateDashScopeEndpointInput(endpoint: String) {
_dashScopeEndpoint.value = endpoint
}
fun saveDashScopeEndpoint(endpoint: String) {
_dashScopeEndpoint.value = endpoint
sttManager.configureDashScope(_dashScopeApiKey.value, endpoint, _dashScopeModel.value)
scope.launch { preferencesDataStore.saveDashScopeEndpoint(endpoint) }
}
fun updateDashScopeModelInput(model: String) {
_dashScopeModel.value = model
}
fun saveDashScopeModel(model: String) {
_dashScopeModel.value = model
sttManager.configureDashScope(_dashScopeApiKey.value, _dashScopeEndpoint.value, model)
scope.launch { preferencesDataStore.saveDashScopeModel(model) }
}
fun saveAutoScreenContext(enabled: Boolean) {
_autoScreenContext.value = enabled
scope.launch { preferencesDataStore.saveAutoScreenContext(enabled) }
}
fun clearLocalMessages() {
scope.launch {
chatRepository.clearLocalMessages()
}
}
fun logout() {
scope.launch {
authRepository.logout()
_isLoggedIn.value = false
}
}
}
app/src/main/java/top/yeij/cyrene/voice/hotword/HotwordDetector.kt
-27
View File
@@ -1,27 +0,0 @@
package top.yeij.cyrene.voice.hotword
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
class HotwordDetector {
private val _isListening = MutableStateFlow(false)
val isListening = _isListening.asStateFlow()
private val _onDetected = MutableStateFlow(false)
val onDetected = _onDetected.asStateFlow()
fun startListening(wakeWord: String) {
_isListening.value = true
// Integrate system AlwaysOnHotwordDetector or Porcupine SDK here
}
fun stopListening() {
_isListening.value = false
}
fun updateWakeWord(newWord: String) {
stopListening()
startListening(newWord)
}
}
app/src/main/java/top/yeij/cyrene/voice/stt/BackendSttProvider.kt
-160
View File
@@ -1,160 +0,0 @@
package top.yeij.cyrene.voice.stt
import android.Manifest
import android.content.Context
import android.content.pm.PackageManager
import android.media.AudioFormat
import android.media.AudioRecord
import android.media.MediaRecorder
import android.util.Base64
import android.util.Log
import androidx.core.content.ContextCompat
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import top.yeij.cyrene.domain.repository.ChatRepository
import java.io.ByteArrayOutputStream
class BackendSttProvider(
private val context: Context,
private val chatRepository: ChatRepository,
) : SttProvider {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
private var audioRecord: AudioRecord? = null
private var recordingJob: Job? = null
private val audioBuffer = ByteArrayOutputStream()
private val _partialResult = MutableStateFlow("")
override val partialResult: StateFlow<String> = _partialResult.asStateFlow()
private val _finalResult = MutableSharedFlow<SttResult>(extraBufferCapacity = 8)
override val finalResult: SharedFlow<SttResult> = _finalResult.asSharedFlow()
private val _onError = MutableSharedFlow<String>(extraBufferCapacity = 8)
override val onError: SharedFlow<String> = _onError.asSharedFlow()
private val _isListening = MutableStateFlow(false)
override val isListening: StateFlow<Boolean> = _isListening.asStateFlow()
private val sampleRate = 16000
private val audioFormat = AudioFormat.ENCODING_PCM_16BIT
private val channelConfig = AudioFormat.CHANNEL_IN_MONO
private val bufferSize: Int = AudioRecord.getMinBufferSize(sampleRate, channelConfig, audioFormat)
.coerceAtLeast(3200)
override fun start() {
if (ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO)
!= PackageManager.PERMISSION_GRANTED
) {
_onError.tryEmit("缺少录音权限")
return
}
cancel()
_isListening.value = true
_partialResult.value = ""
audioBuffer.reset()
try {
audioRecord = AudioRecord(
MediaRecorder.AudioSource.VOICE_RECOGNITION,
sampleRate,
channelConfig,
audioFormat,
bufferSize,
).also {
if (it.state != AudioRecord.STATE_INITIALIZED) {
Log.e(TAG, "AudioRecord init failed")
_onError.tryEmit("麦克风初始化失败")
_isListening.value = false
return
}
it.startRecording()
}
val readBuffer = ByteArray(bufferSize)
recordingJob = scope.launch {
while (isActive && _isListening.value) {
val bytesRead = audioRecord?.read(readBuffer, 0, readBuffer.size) ?: -1
if (bytesRead > 0) {
audioBuffer.write(readBuffer, 0, bytesRead)
} else if (bytesRead < 0) break
}
}
} catch (e: SecurityException) {
_onError.tryEmit("缺少录音权限")
_isListening.value = false
} catch (e: Exception) {
Log.e(TAG, "Recording error", e)
_onError.tryEmit("录音失败: ${e.message}")
_isListening.value = false
}
}
override fun stop() {
if (!_isListening.value) return
Log.d(TAG, "Stopping recording")
stopRecording()
val audioBytes = audioBuffer.toByteArray()
if (audioBytes.isEmpty()) {
Log.w(TAG, "No audio data recorded")
_isListening.value = false
_onError.tryEmit("未录制到语音")
return
}
_isListening.value = false
scope.launch {
try {
val base64 = Base64.encodeToString(audioBytes, Base64.NO_WRAP)
chatRepository.sendVoiceInput(base64, "voice_msg")
Log.d(TAG, "Sent ${audioBytes.size} bytes of audio to backend")
} catch (e: Exception) {
Log.e(TAG, "Failed to send voice input", e)
_onError.tryEmit("发送语音失败: ${e.message}")
}
}
}
override fun cancel() {
if (!_isListening.value) return
Log.d(TAG, "Cancelling recording")
stopRecording()
audioBuffer.reset()
_isListening.value = false
_partialResult.value = ""
}
private fun stopRecording() {
recordingJob?.cancel()
recordingJob = null
try {
audioRecord?.stop()
audioRecord?.release()
} catch (e: Exception) {
Log.w(TAG, "Error releasing AudioRecord: ${e.message}")
}
audioRecord = null
}
fun shutdown() {
cancel()
scope.cancel()
}
companion object {
private const val TAG = "BackendSTT"
}
}
app/src/main/java/top/yeij/cyrene/voice/stt/DashScopeSttService.kt
-355
View File
@@ -1,355 +0,0 @@
package top.yeij.cyrene.voice.stt
import android.Manifest
import android.content.Context
import android.content.pm.PackageManager
import android.media.AudioAttributes
import android.media.AudioFormat
import android.media.AudioRecord
import android.media.MediaRecorder
import android.util.Log
import androidx.core.content.ContextCompat
import com.google.gson.Gson
import com.google.gson.annotations.SerializedName
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.Response
import okhttp3.WebSocket
import okhttp3.WebSocketListener
import okio.ByteString
import java.util.UUID
import java.util.concurrent.TimeUnit
import java.util.concurrent.atomic.AtomicInteger
class DashScopeSttService(
private val context: Context,
) : SttProvider {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
private val gson = Gson()
private val connectionId = AtomicInteger(0)
private var webSocket: WebSocket? = null
private var audioRecord: AudioRecord? = null
private var recordingJob: Job? = null
private var taskId: String = ""
private val _partialResult = MutableStateFlow("")
override val partialResult: StateFlow<String> = _partialResult.asStateFlow()
private val _finalResult = MutableSharedFlow<SttResult>(extraBufferCapacity = 16)
override val finalResult: SharedFlow<SttResult> = _finalResult.asSharedFlow()
private val _onError = MutableSharedFlow<String>(extraBufferCapacity = 8)
override val onError: SharedFlow<String> = _onError.asSharedFlow()
private val _isListening = MutableStateFlow(false)
override val isListening: StateFlow<Boolean> = _isListening.asStateFlow()
// Configurable via settings
var apiKey: String = ""
var endpoint: String = "wss://dashscope.aliyuncs.com/api-ws/v1/inference"
var model: String = "fun-asr-realtime"
var enableInterimResults: Boolean = true
private val sampleRate = 16000
private val audioFormat = AudioFormat.ENCODING_PCM_16BIT
private val channelConfig = AudioFormat.CHANNEL_IN_MONO
private val bytesPerSample = 2
private val chunkMs = 100
private val bufferSize: Int = AudioRecord.getMinBufferSize(sampleRate, channelConfig, audioFormat)
.coerceAtLeast(sampleRate * bytesPerSample * chunkMs / 1000)
override fun start() {
if (apiKey.isBlank()) {
Log.w(TAG, "DashScope API key not configured")
_onError.tryEmit("请先配置 DashScope API Key")
return
}
if (ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO)
!= PackageManager.PERMISSION_GRANTED
) {
_onError.tryEmit("缺少录音权限")
return
}
cancel()
taskId = UUID.randomUUID().toString()
_isListening.value = true
_partialResult.value = ""
connectWebSocket()
startRecording()
}
override fun stop() {
if (!_isListening.value) return
Log.d(TAG, "Stopping recognition, taskId=$taskId")
stopRecording()
sendFinishTask()
}
override fun cancel() {
if (!_isListening.value) return
Log.d(TAG, "Cancelling recognition, taskId=$taskId")
stopRecording()
closeWebSocket()
_isListening.value = false
_partialResult.value = ""
}
private fun connectWebSocket() {
val client = OkHttpClient.Builder()
.readTimeout(0, TimeUnit.MILLISECONDS)
.writeTimeout(0, TimeUnit.MILLISECONDS)
.callTimeout(0, TimeUnit.MILLISECONDS)
.build()
val request = Request.Builder()
.url(endpoint)
.header("Authorization", "Bearer $apiKey")
.build()
val connId = connectionId.incrementAndGet()
Log.i(TAG, "[#$connId] Connecting to DashScope: $endpoint")
webSocket = client.newWebSocket(request, object : WebSocketListener() {
override fun onOpen(webSocket: WebSocket, response: Response) {
if (connectionId.get() != connId) return
Log.i(TAG, "[#$connId] Connected, sending run-task")
sendRunTask()
}
override fun onMessage(webSocket: WebSocket, text: String) {
if (connectionId.get() != connId) return
handleServerMessage(text)
}
override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
if (connectionId.get() != connId) return
Log.e(TAG, "[#$connId] WebSocket failure: ${t.message}", t)
_isListening.value = false
_onError.tryEmit("语音识别连接失败: ${t.message}")
}
override fun onClosing(webSocket: WebSocket, code: Int, reason: String) {
if (connectionId.get() != connId) return
Log.d(TAG, "[#$connId] Server closing: $code $reason")
}
override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
if (connectionId.get() != connId) return
Log.d(TAG, "[#$connId] Closed: $code $reason")
_isListening.value = false
}
})
}
private fun sendRunTask() {
val msg = mapOf(
"header" to mapOf(
"action" to "run-task",
"task_id" to taskId,
"streaming" to "duplex",
),
"payload" to mapOf(
"model" to model,
"parameters" to mapOf(
"format" to "pcm",
"sample_rate" to sampleRate,
),
"input" to emptyMap<String, String>(),
),
)
val json = gson.toJson(msg)
Log.d(TAG, "Sending run-task: $json")
webSocket?.send(json)
}
private fun sendFinishTask() {
val msg = mapOf(
"header" to mapOf(
"action" to "finish-task",
"task_id" to taskId,
),
"payload" to emptyMap<String, String>(),
)
val json = gson.toJson(msg)
Log.d(TAG, "Sending finish-task: $json")
webSocket?.send(json)
}
private fun handleServerMessage(text: String) {
try {
val response = gson.fromJson(text, DashScopeResponse::class.java)
val header = response.header ?: return
val event = header.event ?: return
when (event) {
"result-generated" -> {
val sentence = response.payload?.output?.sentence ?: return
val sentenceText = sentence.text ?: return
_partialResult.value = sentenceText
val sttResult = SttResult(
text = sentenceText,
isFinal = sentence.sentenceEnd ?: true,
)
if (sttResult.isFinal) {
_finalResult.tryEmit(sttResult)
} else if (enableInterimResults) {
_finalResult.tryEmit(sttResult)
}
}
"task-finished" -> {
Log.i(TAG, "Task finished: $taskId")
// If no result-generated was received, emit what we have
val partial = _partialResult.value
if (partial.isNotBlank()) {
_finalResult.tryEmit(SttResult(text = partial, isFinal = true))
}
closeWebSocket()
_isListening.value = false
}
"task-failed" -> {
val error = header.errorMessage ?: "语音识别失败"
Log.e(TAG, "Task failed: $error")
_onError.tryEmit(error)
closeWebSocket()
_isListening.value = false
}
}
} catch (e: Exception) {
Log.w(TAG, "Failed to parse server message: ${e.message}")
}
}
private fun startRecording() {
try {
audioRecord = AudioRecord(
MediaRecorder.AudioSource.VOICE_RECOGNITION,
sampleRate,
channelConfig,
audioFormat,
bufferSize,
).also {
if (it.state != AudioRecord.STATE_INITIALIZED) {
Log.e(TAG, "AudioRecord initialization failed")
_onError.tryEmit("麦克风初始化失败")
_isListening.value = false
return
}
it.startRecording()
}
Log.d(TAG, "Recording started, bufferSize=$bufferSize")
val readBuffer = ByteArray(bufferSize)
recordingJob = scope.launch {
while (isActive && _isListening.value) {
val bytesRead = audioRecord?.read(readBuffer, 0, readBuffer.size) ?: -1
if (bytesRead > 0) {
val data = readBuffer.copyOf(bytesRead)
webSocket?.let { ws ->
try {
ws.send(ByteString.of(*data))
} catch (e: Exception) {
Log.w(TAG, "Failed to send audio: ${e.message}")
}
}
} else if (bytesRead < 0) {
Log.w(TAG, "AudioRecord read error: $bytesRead")
break
}
}
}
} catch (e: SecurityException) {
Log.e(TAG, "Missing RECORD_AUDIO permission", e)
_onError.tryEmit("缺少录音权限")
_isListening.value = false
} catch (e: Exception) {
Log.e(TAG, "Failed to start recording", e)
_onError.tryEmit("录音启动失败: ${e.message}")
_isListening.value = false
}
}
private fun stopRecording() {
recordingJob?.cancel()
recordingJob = null
try {
audioRecord?.stop()
audioRecord?.release()
} catch (e: Exception) {
Log.w(TAG, "Error releasing AudioRecord: ${e.message}")
}
audioRecord = null
Log.d(TAG, "Recording stopped")
}
private fun closeWebSocket() {
try {
webSocket?.close(1000, "Done")
} catch (_: Exception) { }
webSocket = null
}
fun shutdown() {
cancel()
scope.cancel()
}
companion object {
private const val TAG = "DashScopeSTT"
}
}
// --- JSON DTOs for DashScope WebSocket protocol ---
data class DashScopeResponse(
@SerializedName("header") val header: DashScopeHeader?,
@SerializedName("payload") val payload: DashScopePayload?,
)
data class DashScopeHeader(
@SerializedName("task_id") val taskId: String?,
@SerializedName("event") val event: String?,
@SerializedName("action") val action: String?,
@SerializedName("error_message") val errorMessage: String?,
)
data class DashScopePayload(
@SerializedName("output") val output: DashScopeOutput?,
@SerializedName("usage") val usage: Map<String, Any>?,
)
data class DashScopeOutput(
@SerializedName("sentence") val sentence: DashScopeSentence?,
)
data class DashScopeSentence(
@SerializedName("text") val text: String?,
@SerializedName("sentence_end") val sentenceEnd: Boolean?,
@SerializedName("sentence_id") val sentenceId: Int?,
@SerializedName("begin_time") val beginTime: Long?,
@SerializedName("end_time") val endTime: Long?,
@SerializedName("words") val words: List<Map<String, Any>>?,
@SerializedName("emo_tag") val emoTag: String?,
)
app/src/main/java/top/yeij/cyrene/voice/stt/SpeechRecognizer.kt
-118
View File
@@ -1,118 +0,0 @@
package top.yeij.cyrene.voice.stt
import android.content.Context
import android.content.Intent
import android.os.Bundle
import android.speech.RecognitionListener
import android.speech.RecognizerIntent
import android.speech.SpeechRecognizer
import android.util.Log
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
class SpeechRecognizer(private val context: Context) : SttProvider {
private var recognizer: android.speech.SpeechRecognizer? = null
private val _isListening = MutableStateFlow(false)
override val isListening: StateFlow<Boolean> = _isListening.asStateFlow()
private val _partialResult = MutableStateFlow("")
override val partialResult: StateFlow<String> = _partialResult.asStateFlow()
private val _finalResult = MutableSharedFlow<SttResult>(extraBufferCapacity = 8)
override val finalResult: SharedFlow<SttResult> = _finalResult.asSharedFlow()
private val _onError = MutableSharedFlow<String>(extraBufferCapacity = 8)
override val onError: SharedFlow<String> = _onError.asSharedFlow()
override fun start() {
if (!android.speech.SpeechRecognizer.isRecognitionAvailable(context)) {
Log.w(TAG, "Speech recognition not available on this device")
_onError.tryEmit("语音识别不可用")
return
}
cancel()
recognizer = android.speech.SpeechRecognizer.createSpeechRecognizer(context).apply {
setRecognitionListener(object : RecognitionListener {
override fun onReadyForSpeech(params: Bundle?) {
_isListening.value = true
_partialResult.value = ""
}
override fun onBeginningOfSpeech() {}
override fun onRmsChanged(rmsdB: Float) {}
override fun onBufferReceived(buffer: ByteArray?) {}
override fun onEndOfSpeech() {}
override fun onError(error: Int) {
_isListening.value = false
val msg = when (error) {
android.speech.SpeechRecognizer.ERROR_NETWORK -> "网络连接失败"
android.speech.SpeechRecognizer.ERROR_NETWORK_TIMEOUT -> "网络超时"
android.speech.SpeechRecognizer.ERROR_AUDIO -> "音频录制错误"
android.speech.SpeechRecognizer.ERROR_SERVER -> "服务器错误"
android.speech.SpeechRecognizer.ERROR_CLIENT -> "客户端错误"
android.speech.SpeechRecognizer.ERROR_SPEECH_TIMEOUT -> "未检测到语音"
android.speech.SpeechRecognizer.ERROR_NO_MATCH -> "未能识别"
android.speech.SpeechRecognizer.ERROR_RECOGNIZER_BUSY -> "语音引擎忙碌"
android.speech.SpeechRecognizer.ERROR_INSUFFICIENT_PERMISSIONS -> "缺少录音权限"
else -> "未知错误 ($error)"
}
Log.w(TAG, "Recognition error: $msg")
_onError.tryEmit(msg)
}
override fun onResults(results: Bundle?) {
_isListening.value = false
val matches = results?.getStringArrayList(android.speech.SpeechRecognizer.RESULTS_RECOGNITION)
if (!matches.isNullOrEmpty()) {
_finalResult.tryEmit(SttResult(text = matches[0], isFinal = true))
}
}
override fun onPartialResults(partialResults: Bundle?) {
val matches = partialResults?.getStringArrayList(android.speech.SpeechRecognizer.RESULTS_RECOGNITION)
if (!matches.isNullOrEmpty()) {
_partialResult.value = matches[0]
}
}
override fun onEvent(eventType: Int, params: Bundle?) {}
})
val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
putExtra(RecognizerIntent.EXTRA_LANGUAGE, "zh-CN")
putExtra(RecognizerIntent.EXTRA_PARTIAL_RESULTS, true)
putExtra(RecognizerIntent.EXTRA_MAX_RESULTS, 1)
}
startListening(intent)
}
}
override fun stop() {
recognizer?.stopListening()
_isListening.value = false
}
override fun cancel() {
recognizer?.cancel()
recognizer?.destroy()
recognizer = null
_isListening.value = false
_partialResult.value = ""
}
companion object {
private const val TAG = "CyreneSTT"
}
}
app/src/main/java/top/yeij/cyrene/voice/stt/SttManager.kt
-128
View File
@@ -1,128 +0,0 @@
package top.yeij.cyrene.voice.stt
import android.util.Log
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asSharedFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import top.yeij.cyrene.util.RuntimeLog
class SttManager(
private val dashScopeService: DashScopeSttService,
private val backendProvider: BackendSttProvider,
private val systemRecognizer: SpeechRecognizer,
) {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
private val _isListening = MutableStateFlow(false)
val isListening: StateFlow<Boolean> = _isListening.asStateFlow()
private val _partialResult = MutableStateFlow("")
val partialResult: StateFlow<String> = _partialResult.asStateFlow()
private val _finalResult = MutableSharedFlow<SttResult>(extraBufferCapacity = 16)
val finalResult: SharedFlow<SttResult> = _finalResult.asSharedFlow()
private val _onError = MutableSharedFlow<String>(extraBufferCapacity = 8)
val onError: SharedFlow<String> = _onError.asSharedFlow()
private var activeProvider: SttProvider? = null
private var dashScopeFailed = false
fun start() {
cancel()
val provider = if (dashScopeService.apiKey.isNotBlank() && !dashScopeFailed) {
Log.d(TAG, "Using DashScope STT")
RuntimeLog.stt("start", "Using DashScope provider")
dashScopeService.also { dashScopeFailed = false }
} else {
Log.d(TAG, "Using Backend STT (fallback)")
RuntimeLog.stt("start", "Using Backend provider (fallback)")
backendProvider
}
activeProvider = provider
_isListening.value = true
_partialResult.value = ""
collectFrom(provider)
provider.start()
}
fun stop() {
RuntimeLog.stt("stop", "Stopping STT")
activeProvider?.stop()
_isListening.value = false
}
fun cancel() {
RuntimeLog.stt("cancel", "Cancelling STT")
activeProvider?.cancel()
activeProvider = null
_isListening.value = false
_partialResult.value = ""
}
fun configureDashScope(apiKey: String, endpoint: String, model: String) {
dashScopeService.apiKey = apiKey
dashScopeService.endpoint = endpoint
dashScopeService.model = model
dashScopeFailed = false
}
fun updateDashScopeApiKey(apiKey: String) {
dashScopeService.apiKey = apiKey
if (apiKey.isNotBlank()) dashScopeFailed = false
}
fun shutdown() {
cancel()
dashScopeService.shutdown()
backendProvider.shutdown()
scope.cancel()
}
private fun collectFrom(provider: SttProvider) {
scope.launch {
provider.partialResult.collect { text ->
if (provider == activeProvider && text.isNotEmpty()) {
_partialResult.value = text
}
}
}
scope.launch {
provider.finalResult.collect { result ->
if (provider == activeProvider) {
RuntimeLog.stt("result", "Final result: isFinal=${result.isFinal} text=${result.text.take(80)}")
_finalResult.tryEmit(result)
}
}
}
scope.launch {
provider.onError.collect { error ->
if (provider == activeProvider) {
Log.w(TAG, "STT error: $error")
RuntimeLog.stt("error", error)
_onError.tryEmit(error)
if (provider == dashScopeService) {
dashScopeFailed = true
RuntimeLog.stt("fallback", "DashScope failed, will use backend next time")
Log.i(TAG, "DashScope failed, will use backend next time")
}
}
}
}
}
companion object {
private const val TAG = "SttManager"
}
}
app/src/main/java/top/yeij/cyrene/voice/stt/SttProvider.kt
-23
View File
@@ -1,23 +0,0 @@
package top.yeij.cyrene.voice.stt
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.StateFlow
enum class SttProviderType { DASHSCOPE, BACKEND, SYSTEM }
data class SttResult(
val text: String,
val isFinal: Boolean,
val isError: Boolean = false,
)
interface SttProvider {
val partialResult: StateFlow<String>
val finalResult: SharedFlow<SttResult>
val onError: SharedFlow<String>
val isListening: StateFlow<Boolean>
fun start()
fun stop()
fun cancel()
}
app/src/main/java/top/yeij/cyrene/voice/tts/TextToSpeechEngine.kt
-97
View File
@@ -1,97 +0,0 @@
package top.yeij.cyrene.voice.tts
import android.content.Context
import android.media.AudioAttributes
import android.media.AudioFocusRequest
import android.media.AudioManager
import android.os.Build
import android.speech.tts.TextToSpeech
import android.speech.tts.UtteranceProgressListener
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import java.util.Locale
class TextToSpeechEngine(private val context: Context) {
private var tts: TextToSpeech? = null
private val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
private val _isSpeaking = MutableStateFlow(false)
val isSpeaking = _isSpeaking.asStateFlow()
private val _onDone = MutableStateFlow(false)
val onDone = _onDone.asStateFlow()
fun initialize(onReady: () -> Unit) {
tts = TextToSpeech(context) { status ->
if (status == TextToSpeech.SUCCESS) {
tts?.language = Locale.CHINESE
tts?.setSpeechRate(0.9f)
tts?.setPitch(1.1f)
tts?.setOnUtteranceProgressListener(object : UtteranceProgressListener() {
override fun onStart(utteranceId: String?) {
requestAudioFocus()
_isSpeaking.value = true
}
override fun onDone(utteranceId: String?) {
_isSpeaking.value = false
_onDone.value = true
abandonAudioFocus()
}
override fun onError(utteranceId: String?) {
_isSpeaking.value = false
abandonAudioFocus()
}
})
onReady()
}
}
}
fun speak(text: String, utteranceId: String = System.currentTimeMillis().toString()) {
tts?.speak(text, TextToSpeech.QUEUE_FLUSH, null, utteranceId)
}
fun stop() {
tts?.stop()
_isSpeaking.value = false
}
fun shutdown() {
tts?.stop()
tts?.shutdown()
}
private fun requestAudioFocus() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
val focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
.setAudioAttributes(
AudioAttributes.Builder()
.setUsage(AudioAttributes.USAGE_ASSISTANT)
.setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
.build()
)
.build()
audioManager.requestAudioFocus(focusRequest)
} else {
@Suppress("DEPRECATION")
audioManager.requestAudioFocus(
null,
AudioManager.STREAM_MUSIC,
AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE,
)
}
}
private fun abandonAudioFocus() {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
// Focus released with the request
} else {
@Suppress("DEPRECATION")
audioManager.abandonAudioFocus(null)
}
}
}
app/src/main/kotlin/top/yeij/cyrene/app/AppContainer.kt
+247
View File
@@ -0,0 +1,247 @@
package top.yeij.cyrene.app
import android.content.Context
import top.yeij.cyrene.core.auth.AuthManager
import top.yeij.cyrene.core.auth.SessionStore
import top.yeij.cyrene.core.prefs.AppSettings
import top.yeij.cyrene.core.prefs.EnumPreferences
import top.yeij.cyrene.core.prefs.SessionPreferences
import top.yeij.cyrene.core.session.GoneSessions
import top.yeij.cyrene.data.api.AdminApi
import top.yeij.cyrene.data.api.ApiClientFactory
import top.yeij.cyrene.data.api.ChatApi
import top.yeij.cyrene.data.api.DocumentsApi
import top.yeij.cyrene.data.api.MetaApi
import top.yeij.cyrene.data.api.PersonaApi
import top.yeij.cyrene.data.api.SessionsApi
import top.yeij.cyrene.data.api.UploadApi
import top.yeij.cyrene.data.repository.AdminRepository
import top.yeij.cyrene.data.repository.ChatRepository
import top.yeij.cyrene.data.repository.DocumentRepository
import top.yeij.cyrene.data.repository.MessageRepository
import top.yeij.cyrene.data.repository.MetaRepository
import top.yeij.cyrene.data.repository.PersonaRepository
import top.yeij.cyrene.data.repository.SessionRepository
import top.yeij.cyrene.data.repository.UploadRepository
import top.yeij.cyrene.data.ws.ChatSocket
/** 手写 DI 容器（D：不引 Hilt）。 */
class AppContainer(context: Context) {
/** 应用上下文：给需要在 ViewModel 里读本地资源（图片解码等）的组件用。 */
val appContext: Context = context.applicationContext
val sessionStore: SessionStore = SessionStore(context.applicationContext)
val sessionPreferences: SessionPreferences = SessionPreferences(context.applicationContext)
val enumPreferences: EnumPreferences = EnumPreferences(context.applicationContext)
val appSettings: AppSettings = AppSettings(context.applicationContext)
val authManager: AuthManager = AuthManager(sessionStore)
/**
* 本端已知「服务端没有这个会话」的那几个 id（**进程级**，与 [chatSocket] 同一层）。
*
* 跨两个 VM 的唯一共享面：写它的是 `SessionsViewModel`（本端唯一的删除入口），读它的是
* **每一个** `ChatViewModel`（它们各留一个常驻 VM，删会话不回收）。它拦下的是那一轮注定
* `404 session_not_found` 的补拉 —— 理由与「为什么不持久化」见 [GoneSessions] 的类注释。
*/
val goneSessions: GoneSessions = GoneSessions()
private var cachedBaseUrl: String? = null
private var cachedSessionsApi: SessionsApi? = null
/** 会话/消息 REST 客户端；baseUrl 变化时自动重建。 */
val sessionsApi: SessionsApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedSessionsApi
if (cached != null && cachedBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = SessionsApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedBaseUrl = baseUrl
cachedSessionsApi = created
return created
}
val sessionRepository: SessionRepository get() = SessionRepository(sessionsApi)
val messageRepository: MessageRepository get() = MessageRepository(sessionsApi)
private var cachedChatApi: ChatApi? = null
private var cachedChatBaseUrl: String? = null
/** 发送端点（`POST /api/v1/chat`）；与 [sessionsApi] 同源（同一 baseUrl、同一 token/401 处理）。 */
val chatApi: ChatApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedChatApi
if (cached != null && cachedChatBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = ChatApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedChatBaseUrl = baseUrl
cachedChatApi = created
return created
}
val chatRepository: ChatRepository get() = ChatRepository(chatApi)
private var cachedUploadApi: UploadApi? = null
private var cachedUploadBaseUrl: String? = null
/**
* 图片上传端点（`POST /api/v1/upload`）；与 [chatApi] 同源（同一 baseUrl、同一 token/401 处理）——
* 上传的产物 URL 就是要交给 `POST /api/v1/chat` 的 `image` 字段的，两者必须在同一个后端上。
*/
val uploadApi: UploadApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedUploadApi
if (cached != null && cachedUploadBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = UploadApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedUploadBaseUrl = baseUrl
cachedUploadApi = created
return created
}
val uploadRepository: UploadRepository get() = UploadRepository(uploadApi)
private var cachedDocumentsApi: DocumentsApi? = null
private var cachedDocumentsBaseUrl: String? = null
/**
* 文档存储端点（`POST /api/v1/documents` 上传、`GET /api/v1/documents/{name}` 取字节）；
* 与 [chatApi] **必须同源**（同一 baseUrl、同一 token/401 处理）——上传拿到的存储名就是要交给
* 同一个后端的 `POST /api/v1/chat` 的 `documents[].name`，两条链路不在同一台机器上就必然 404。
*
* Bearer 与 401 续期不用在这里做额外事：[ApiClientFactory.create] 按 **OkHttpClient**
* 挂 `AuthInterceptor`，文档读侧那点「与图片读侧刻意相反」的鉴权要求因此天然满足。
*/
val documentsApi: DocumentsApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedDocumentsApi
if (cached != null && cachedDocumentsBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = DocumentsApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedDocumentsBaseUrl = baseUrl
cachedDocumentsApi = created
return created
}
val documentRepository: DocumentRepository get() = DocumentRepository(documentsApi)
private var cachedAdminApi: AdminApi? = null
private var cachedAdminBaseUrl: String? = null
/** 管理只读监控客户端；与 [sessionsApi] 同源（同一 baseUrl、同一 token/401 处理）。 */
val adminApi: AdminApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedAdminApi
if (cached != null && cachedAdminBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = AdminApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedAdminBaseUrl = baseUrl
cachedAdminApi = created
return created
}
val adminRepository: AdminRepository get() = AdminRepository(adminApi)
private var cachedMetaApi: MetaApi? = null
private var cachedMetaBaseUrl: String? = null
/** 枚举权威表客户端；同样与 [sessionsApi] 同源（同一 baseUrl、同一 token/401 处理）。 */
val metaApi: MetaApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedMetaApi
if (cached != null && cachedMetaBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = MetaApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedMetaBaseUrl = baseUrl
cachedMetaApi = created
return created
}
val metaRepository: MetaRepository get() = MetaRepository(metaApi)
private var cachedPersonaApi: PersonaApi? = null
private var cachedPersonaBaseUrl: String? = null
/** 用户侧角色目录（`GET /api/v1/personas`）；与 [metaApi] 同源（同一 baseUrl、同一 token/401 处理）。 */
val personaApi: PersonaApi
get() {
val baseUrl = authManager.currentBaseUrl
val cached = cachedPersonaApi
if (cached != null && cachedPersonaBaseUrl == baseUrl) return cached
val created = ApiClientFactory.create(
baseUrl = baseUrl,
service = PersonaApi::class.java,
tokenProvider = authManager::currentToken,
unauthorizedPolicy = authManager.unauthorizedPolicy,
)
cachedPersonaBaseUrl = baseUrl
cachedPersonaApi = created
return created
}
val personaRepository: PersonaRepository get() = PersonaRepository(personaApi)
/**
* 进程内**唯一**的实时通道连接（`GET /ws/chat`）：所有需要收下行帧的 ViewModel 共用这一条。
*
* ## 为什么可以共享（不是「省点资源」，是**逐帧等价**）
* 服务端是**广播**：下行帧发给**每一条**已认证连接、**不按会话订阅**（见 [ChatSocket] 类注释
* 「会话归属」）。于是改前「N 条连接，每条都收到全部帧 ⇒ 每个 VM 都收到全部帧 ⇒ 各 VM 靠
* [top.yeij.cyrene.data.ws.WsEvent.isForSession] 收敛到自己的会话」与改后「一条连接收到全部帧
* ⇒ **每个 VM 仍然收到全部帧**」是**同一个语义**：帧集合逐帧相同，过滤与事件分支一个字都不用改。
* 这次变的只是「连接有几条」，不是「帧怎么走」。
*
* ## 为什么必须唯一
* 每个 `ChatSocket` 都自带一个 `OkHttpClient`（各自的连接池 / ping / 重连循环）。改前
* `ChatViewModel`（**每个会话一个 VM**）、[top.yeij.cyrene.ui.sessions.SessionsViewModel]、
* [top.yeij.cyrene.ui.admin.AdminViewModel] 各自建了一条（`ChatViewModel.start()`、
* 两个 VM 的 init）⇒ 访问 N 个会话 = N+2 条连接、N+2 个 `OkHttpClient`；而 VM 活在 Activity 级
* `ViewModelStore` 里，**切走 / 删会话都不回收**。现在这里就是唯一的持有者（`by lazy`，只此一份），
* 调用方只订阅 [ChatSocket.events] / [ChatSocket.state]。
*
* ## 开与关只有一个主人
* [top.yeij.cyrene.ui.sessions.SessionsViewModel] 的登录态订阅：`LoggedIn → connect()`、
* `LoggedOut → close()`（为什么是它，见那个类的 KDoc）。`connect()` 幂等，baseUrl / token 都是
* 每次重连现读 ⇒ 登出重登、换账号**不需要**重建本实例。**任何 ViewModel 都不许关它**——
* 细节与理由写在 [ChatSocket.close]。
*/
val chatSocket: ChatSocket by lazy {
ChatSocket(
baseUrlProvider = { authManager.currentBaseUrl },
tokenProvider = authManager::currentToken,
onAuthRecover = authManager::recoverSocketAuth,
onAuthFailed = authManager::onSessionExpired,
)
}
}
app/src/main/kotlin/top/yeij/cyrene/app/CyreneApp.kt
+32
View File
@@ -0,0 +1,32 @@
package top.yeij.cyrene.app
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.rememberCoroutineScope
import kotlinx.coroutines.launch
import top.yeij.cyrene.core.auth.SessionState
import top.yeij.cyrene.ui.chat.ChatHomeScreen
import top.yeij.cyrene.ui.common.LoadingScreen
import top.yeij.cyrene.ui.login.LoginScreen
@Composable
fun CyreneApp(container: AppContainer) {
val state by container.authManager.state.collectAsState()
val scope = rememberCoroutineScope()
LaunchedEffect(Unit) {
container.authManager.bootstrap()
}
when (state) {
SessionState.Unknown -> LoadingScreen()
SessionState.LoggedOut -> LoginScreen(container)
is SessionState.LoggedIn -> ChatHomeScreen(
container = container,
// 登出要先把服务端的 refresh 授权吊销掉，所以是挂起的；UI 不因为它在主线程等待。
onLogout = { scope.launch { container.authManager.logout() } },
)
}
}
app/src/main/kotlin/top/yeij/cyrene/app/CyreneApplication.kt
+14
View File
@@ -0,0 +1,14 @@
package top.yeij.cyrene.app
import android.app.Application
class CyreneApplication : Application() {
lateinit var container: AppContainer
private set
override fun onCreate() {
super.onCreate()
container = AppContainer(this)
}
}
app/src/main/kotlin/top/yeij/cyrene/app/CyreneRoot.kt
+72
View File
@@ -0,0 +1,72 @@
package top.yeij.cyrene.app
import android.app.Activity
import android.content.Context
import android.content.ContextWrapper
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.SideEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.platform.LocalView
import androidx.core.view.WindowCompat
import androidx.lifecycle.viewmodel.compose.viewModel
import androidx.lifecycle.viewmodel.initializer
import androidx.lifecycle.viewmodel.viewModelFactory
import top.yeij.cyrene.core.prefs.AppPrefs
import top.yeij.cyrene.core.prefs.LocalAppPrefs
import top.yeij.cyrene.core.prefs.ThemeMode
import top.yeij.cyrene.core.theme.CyreneTheme
import top.yeij.cyrene.domain.enums.LocalEnumCatalog
import top.yukonga.miuix.kmp.theme.ColorSchemeMode
/**
* 应用根：读 App 偏好 → 决定 Miuix 主题模式 → 通过 [LocalAppPrefs] / [LocalEnumCatalog] 下发给渲染层，
* 同时把系统栏图标明暗跟着主题走（否则浅色模式下白字白底看不见）。
*/
@Composable
fun CyreneRoot(container: AppContainer) {
val prefs by container.appSettings.data.collectAsState(initial = AppPrefs())
val enumCatalogViewModel: EnumCatalogViewModel = viewModel(
factory = viewModelFactory { initializer { EnumCatalogViewModel(container) } },
)
val catalog by enumCatalogViewModel.catalog.collectAsState()
val darkTheme = when (prefs.themeMode) {
ThemeMode.System -> isSystemInDarkTheme()
ThemeMode.Light -> false
ThemeMode.Dark -> true
}
val view = LocalView.current
if (!view.isInEditMode) {
SideEffect {
val window = view.context.findActivity()?.window ?: return@SideEffect
WindowCompat.getInsetsController(window, view).apply {
isAppearanceLightStatusBars = !darkTheme
isAppearanceLightNavigationBars = !darkTheme
}
}
}
CompositionLocalProvider(
LocalAppPrefs provides prefs,
LocalEnumCatalog provides catalog,
) {
CyreneTheme(mode = prefs.themeMode.toColorSchemeMode()) {
CyreneApp(container)
}
}
}
private fun ThemeMode.toColorSchemeMode(): ColorSchemeMode = when (this) {
ThemeMode.System -> ColorSchemeMode.System
ThemeMode.Light -> ColorSchemeMode.Light
ThemeMode.Dark -> ColorSchemeMode.Dark
}
private tailrec fun Context.findActivity(): Activity? = when (this) {
is Activity -> this
is ContextWrapper -> baseContext.findActivity()
else -> null
}
app/src/main/kotlin/top/yeij/cyrene/app/EnumCatalogViewModel.kt
+53
View File
@@ -0,0 +1,53 @@
package top.yeij.cyrene.app
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.launch
import top.yeij.cyrene.core.auth.SessionState
import top.yeij.cyrene.domain.enums.EnumCatalog
/**
* 枚举权威表（api-client §1.1）的应用级持有者：先用本地快照渲染，再拉一次权威表。
*
* - 登录 / 静默重登后拉取；**拉取失败保持现状**（快照或原样 id），绝不因此清空角标；
* - 快照按 `baseUrl + username` 指纹认领：换服务器/账号即作废；
* - 登出时落盘快照与内存标签一并清掉（此时界面只剩登录页，不会闪空角标）。
*/
class EnumCatalogViewModel(private val container: AppContainer) : ViewModel() {
private val _catalog = MutableStateFlow(EnumCatalog.Empty)
val catalog: StateFlow<EnumCatalog> = _catalog.asStateFlow()
init {
viewModelScope.launch {
container.authManager.state.collect { state ->
if (state == SessionState.LoggedOut) {
container.enumPreferences.clear()
_catalog.value = EnumCatalog.Empty
return@collect
}
val fingerprint = fingerprint()
// 先用快照渲染（没有就原样显示 id），拉取不阻塞首帧
val snapshot = container.enumPreferences.data.first()
_catalog.value = EnumCatalog.of(snapshot.tableFor(fingerprint))
if (state is SessionState.LoggedIn) refresh(fingerprint)
}
}
}
private fun refresh(fingerprint: String) {
viewModelScope.launch {
container.metaRepository.enums().onSuccess { table ->
container.enumPreferences.save(table, fingerprint)
_catalog.value = EnumCatalog.of(table)
}
}
}
private fun fingerprint(): String =
"${container.authManager.currentBaseUrl}|${container.sessionStore.load().username.orEmpty()}"
}
app/src/main/kotlin/top/yeij/cyrene/app/MainActivity.kt
+38
View File
@@ -0,0 +1,38 @@
package top.yeij.cyrene.app
import android.content.Intent
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
enableEdgeToEdge()
super.onCreate(savedInstanceState)
// 冷启动的两步：先清掉上一进程遗留的分享缓存（它已经没有主了），再接这次带来的分享。
// 顺序不能反——反过来会把刚拷进来的图一起删掉。
ShareIntake.reset(this)
// 只在**真正的冷启动**接 intent：Activity 因旋转 / 深色切换而重建时，系统会把原来那个
// intent 再送一遍，照单全收就会把同一条分享发第二次。重建带 savedInstanceState，
// 冷启动不带——这就是判据。
if (savedInstanceState == null) {
intent?.let { ShareIntake.accept(this, it) }
}
val container = (application as CyreneApplication).container
setContent {
CyreneRoot(container)
}
}
/**
* 热启动（`launchMode="singleTop"`）：App 已经开着时系统不再新建实例，只回调这里。
* 不接这一路的话，「从浏览器分享 → 回到已经开着的 Cyrene」会一点反应都没有。
*/
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
// 让 getIntent() 与新到的 intent 一致（系统不会自己更新它），否则后续读到的还是旧的那个。
setIntent(intent)
ShareIntake.accept(this, intent)
}
}
app/src/main/kotlin/top/yeij/cyrene/app/ShareIntake.kt
+346
View File
@@ -0,0 +1,346 @@
package top.yeij.cyrene.app
import android.content.Context
import android.content.Intent
import android.net.Uri
import android.provider.OpenableColumns
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import kotlinx.coroutines.flow.StateFlow
import top.yeij.cyrene.domain.chat.DocumentAttachments
import top.yeij.cyrene.domain.chat.DocumentDelivery
import top.yeij.cyrene.domain.chat.DraftDocument
import top.yeij.cyrene.domain.share.PendingShareHolder
import top.yeij.cyrene.domain.share.ShareRules
import top.yeij.cyrene.domain.share.SharedContent
import top.yeij.cyrene.domain.share.SharedDocument
import java.io.File
import java.util.UUID
/**
* 「分享到 App」的接收入口（`ACTION_SEND` / `ACTION_SEND_MULTIPLE`）。
*
* ## 它为什么是一个进程级单例
* 分享进来时可能还没登录、ChatScreen 甚至还没被组合出来，而登录之后消费它的又是**另一个**
* Compose 实例。内容因此必须待在一个不属于任何 UI / ViewModel 的地方——见
* [PendingShareHolder]。不塞进 `AppContainer` 是因为那个文件同时被别的并行改动占用，
* 这里没有任何依赖需要它：本对象只需要一个 `Context`（读 URI、写 cache）。
*
* ## 图片为什么在收到的那一刻就落盘
* `content://` 的读授权只给到**接收它的那个 Activity / 任务**，登录（可能十几秒、还可能切页）
* 之后再去读，拿到的多半是 `SecurityException` / 打不开。所以字节在这里立刻拷进 `cacheDir`，
* 之后一律用本端自己的 `file://` 路径——**外部 Uri 只在这个方法里出现一次**。文件（非图片）同理。
*
* ## 分流：图片还是文件
* 逐条 URI 看 `ContentResolver.getType`（判定见 [top.yeij.cyrene.domain.share.classifySharedStream]）：
* MIME 以 `image/` 开头走既有图片路，**其余一律走文档路**。此前一律当图片拷、当图片解码，
* 一份 `.md` 因此只有两种结局——「图片处理失败」或者被当成一张读不出来的图。
*
* ⚠️ **Manifest 刻意不声明全通配或文本通配 MIME**：后端**明令拒绝** `text/html` / SVG / XML /
* 压缩包 / 脚本，放宽声明会造出一堆「点进去必然失败」的入口。所以这里能接到的**文件**只有
* 系统按 `text/plain` 投过来那些（`.txt` / `.md` / `.log` 这类文件管理器确实会报 `text/plain`）；
* 报成 `text/markdown` 之类的分享**根本不会**出现在 Cyrene 的分享菜单里。
*
* ⚠️ **provider 不报 MIME（`getType` 回 null）时按文档路走**，这是刻意的：本端不猜类型，
* 猜错等于替用户把一个合规文件变成一次失败；代价是「图片但 provider 没报 MIME」会落到文档路、
* 被服务端按 `415` 拒（有如实文案）。画廊 / 相机 / MediaStore 都会报图片那一类，风险面很小。
*
* ## 清理
* 缓存副本只对**产生它的那个进程**有意义（持有者在内存里，进程没了就没人认领），所以
* 进程启动时整目录删一次（[reset]）。运行期间不做细粒度回收：那些文件在发送失败被回滚到
* 输入框之后**仍然要用**（用户可能过一会儿才点发送），提前删掉就会让预览变空图。
* 目录因此以「一次进程生命周期内的分享份数」为界（图片 4 + 文件 5，另加 [stageTextAsDocument]
* 为超长正文落下的那一份 `.txt`），另有系统的 cache 回收兜底。
*/
object ShareIntake {
private const val DIR_NAME = "share-intake"
private val holder = PendingShareHolder<SharedContent>()
/** 待落地的分享内容；消费侧（ChatScreen）订阅它。 */
val pending: StateFlow<List<SharedContent>> = holder.pending
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
/** 进程启动时调用一次：把上一进程遗留的分享缓存清干净。 */
fun reset(context: Context) {
if (cleanedThisProcess) return
cleanedThisProcess = true
runCatching { shareDir(context).deleteRecursively() }
}
/**
* 「本进程已经清过一次」的标记。
*
* Activity 会因为旋转 / 分屏 / 深色切换而**重建**，重建就会再走一次 `onCreate`——
* 那时清缓存会把用户刚分享进来、还摆在输入框里的那张图删掉（预览变空图、发送也没有字节）。
* 缓存副本只对「产生它的进程」有意义，所以判据是**进程**而不是 Activity 实例。
*/
private var cleanedThisProcess = false
/**
* 接收一个分享 Intent（冷启动在 `onCreate`、热启动在 `onNewIntent`）。
*
* 提取是纯函数（[ShareRules.extract]），拷字节是重活，所以在 IO 线程做：`content://` 的读
* 授权绑的是 Activity 而不是某一次调用栈，异步读一样有效。
*/
fun accept(context: Context, intent: Intent) {
val appContext = context.applicationContext
// EXTRA_STREAM 一次读原始值、按**形态**分派（规范形态 + 字符串兼容形态），见 [shareStreamExtrasOf]：
// 挨个 getParcelableExtra / getParcelableArrayListExtra 去问的话，遇到字符串形态只会拿到两行
// `ClassCastException` 加一个 `null`——那正是「分享进来什么都没发生」的来处。
val rawStream = intent.streamExtraValue()
val streamExtras = shareStreamExtrasOf(rawStream)
val extracted = ShareRules.extract(
action = intent.action,
text = intent.getCharSequenceExtra(Intent.EXTRA_TEXT),
// 单值 / 列表两个字段都喂进去（本端不再按 action 猜该读哪个，见 [ShareRules.extract]）。
stream = streamExtras.uriForms.firstOrNull(),
streams = streamExtras.uriForms,
streamStrings = streamExtras.stringForms,
// 「里面躺着值」这件事只有这里知道（纯函数看不到原始值）：形态认不出的那种也算带着内容，
// 否则「分享点下去什么都没发生」会从那条缝里回来。
streamPresent = rawStream != null,
clipUris = intent.clipUris(),
// 分流就发生在这一处：读不到类型（null）也按文档路走，见类 KDoc。
mimeOf = { uri ->
runCatching { context.contentResolver.getType(Uri.parse(uri)) }.getOrNull()
},
)
// 没什么值得往下走的就到此为止（判据是 [SharedContent.worthDelivering]：有可落地的内容，
// 或者有丢件 / 读不进来要对用户说清的事）。整条分享里什么都没有时静默是对的；而
// 「带着内容迹象却一条都没读进来」必须继续往下走——那条告知在下游 `shareNoticeFor` 里等它。
if (!extracted.worthDelivering) return
scope.launch {
val dir = shareDir(appContext).apply { mkdirs() }
val copied = extracted.images.mapIndexedNotNull { index, uri ->
copyToCache(appContext, dir, uri, index)
}
val documents = extracted.documents.mapIndexedNotNull { index, document ->
copyDocumentToCache(appContext, dir, document, index)
}
holder.put(
extracted.copy(
images = copied,
documents = documents,
// 拷不动的那些如实计入「没发送」：宁可界面上说一句，也不要静默少一张。
failedImages = extracted.failedImages + (extracted.images.size - copied.size),
failedDocuments = extracted.failedDocuments + (extracted.documents.size - documents.size),
),
)
}
}
/**
* 取走一条待落地内容（原子出队，只有取到它的那个调用方会去发）；队列为空回 `null`。
*
* 出队是**唯一的认领方式**：消费它的地方会被重建（重组 / 切会话 / Activity 重建），
* 所以「已经发过了」这件事不能记在消费方身上（见 [PendingShareHolder]）。
*/
fun take(): SharedContent? = holder.take()
private fun shareDir(context: Context): File = File(context.cacheDir, DIR_NAME)
/**
* 把一段**分享进来的超长正文**落成 cache 里的 `.txt`，返回可当附件用的待发文档；写不进去回 `null`。
*
* ## 为什么走本对象
* 落成附件的那份字节必须有个**本端的本地地址**才能进既有发送链（芯片要显示它、上传要按 URI
* 现读字节、发送失败回滚后用户还可能要点开看）：`DraftDocument` 只带引用不带字节。而写进
* 「分享缓存」这个目录、跟着同一条清理规则（进程启动整目录删一次）是最省事也最一致的做法——
* 与外部分享进来的文件**同一处落地、同一条生命周期**，不另造一个没人回收的目录。
* 本函数只负责「落盘 + 报一个可用的引用」，**不判断**要不要转（那是
* [DocumentDelivery.planSharedText] 的事）。
*
* 文件名用 [ShareRules.documentCacheFileName] 生成（**只由本端 token 与序号拼路径**，
* 外部字符串一个字符都进不了文件名），但对**服务端**报的名字是
* [DocumentDelivery.TEXT_DOCUMENT_FILE_NAME] ——服务端只取扩展名（白名单里的 `.txt`），
* 其余部分会被内容寻址丢弃。
*
* @return 待发文档（含 `file://` 地址、显示名与**真实字节数**）；任何一步失败都回 `null`，
* 由调用方按「内容一字不丢」的原则退回内联正文（见 `ChatViewModel.sendShared`）。
*/
suspend fun stageTextAsDocument(context: Context, text: String): DraftDocument? = withContext(Dispatchers.IO) {
val staged = runCatching { DocumentDelivery.textAsFile(text) }.getOrNull() ?: return@withContext null
val dir = shareDir(context.applicationContext).apply { mkdirs() }
val target = File(
dir,
ShareRules.documentCacheFileName(UUID.randomUUID().toString(), 0, staged.fileName),
)
try {
target.writeBytes(staged.bytes)
val size = target.length()
if (size > 0L) {
DraftDocument(
uri = Uri.fromFile(target).toString(),
displayName = staged.fileName,
sizeBytes = size,
)
} else {
target.delete()
null
}
} catch (_: Exception) {
// 半截文件不能留下：它会被当成一份真附件去读，报出的错会指向错的地方。
target.delete()
null
}
}
/**
* 把一份非图片分享文件的字节拷进 cache，返回**本端自己的** `file://` 地址 + 显示名 + 真实字节数；
* 失败回 `null`。
*
* 显示名必须先取（拷完之后外部 URI 就只在这个调用栈里了），取不到就回落 URI 最后一段——
* 它是**上传部件的名字**，服务端只从中取扩展名（判定白名单），空名字则由仓库层兜
* `document.txt`。
*/
private fun copyDocumentToCache(
context: Context,
dir: File,
document: SharedDocument,
index: Int,
): SharedDocument? {
val parsed = runCatching { Uri.parse(document.uri) }.getOrNull() ?: return null
if (parsed.scheme.isNullOrBlank()) return null
val name = displayNameOf(context, parsed)
val target = File(dir, ShareRules.documentCacheFileName(UUID.randomUUID().toString(), index, name))
return try {
val source = context.contentResolver.openInputStream(parsed) ?: return null
source.use { input -> target.outputStream().use { output -> input.copyTo(output) } }
val size = target.length()
if (size > 0L) {
document.copy(uri = Uri.fromFile(target).toString(), displayName = name, sizeBytes = size)
} else {
target.delete()
null
}
} catch (_: Exception) {
// 半截文件不能留下：下一次发送会把它当一份真文件去读，报出的错会指向错的地方。
target.delete()
null
}
}
/** provider 报的显示名优先；拿不到就回落到 URI 最后一段（都不给就留空，不猜扩展名）。 */
private fun displayNameOf(context: Context, uri: Uri): String {
val fromProvider = runCatching {
context.contentResolver.query(uri, null, null, null, null)?.use { cursor ->
if (!cursor.moveToFirst()) return@use null
val index = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
if (index < 0 || cursor.isNull(index)) null else cursor.getString(index)
}
}.getOrNull()
return fromProvider?.takeIf { it.isNotBlank() }
?: DocumentAttachments.fallbackDocumentName(uri.toString())
}
/**
* 把一个外部 URI 的字节拷进 cache，返回本端自己的 `file://` URI；失败回 `null`。
*
* 必须是 `file://` 而不是裸路径：`ContentResolver.openInputStream` 认 `file` scheme，
* 但裸路径没有 scheme，会走到「找 content provider」那条路并抛 `FileNotFoundException`。
*/
private fun copyToCache(context: Context, dir: File, uri: String, index: Int): String? {
val parsed = runCatching { Uri.parse(uri) }.getOrNull() ?: return null
if (parsed.scheme.isNullOrBlank()) return null
val target = File(
dir,
ShareRules.cacheFileName(
token = UUID.randomUUID().toString(),
index = index,
mime = runCatching { context.contentResolver.getType(parsed) }.getOrNull(),
),
)
return try {
val source = context.contentResolver.openInputStream(parsed) ?: return null
source.use { input -> target.outputStream().use { output -> input.copyTo(output) } }
if (target.length() > 0L) {
Uri.fromFile(target).toString()
} else {
target.delete()
null
}
} catch (_: Exception) {
// 半截文件不能留下：下一次发送会把它当一张真图去解码，报出的错会指向错的地方。
target.delete()
null
}
}
/**
* `EXTRA_STREAM` 的原始值（**故意读原始值**，理由见 [ShareStreamExtras]）。
*
* `Bundle.get` 在 API 33 起被打上废弃：它绕过类型安全。这里要的正是「绕过类型安全」——要判的
* 就是「这个值到底是什么形态」。逐类型的 `getXxxExtra` 遇到别的形态只会往 logcat 打一句
* `ClassCastException` 再把值扔掉，那正是本次要修的那个静默。
*/
@Suppress("DEPRECATION")
private fun Intent.streamExtraValue(): Any? = extras?.get(Intent.EXTRA_STREAM)
/**
* `ClipData` 各条目的 URI（部分 App 只填它）；纯文本条目的 URI 是 `null`。
*
* 这里刻意**保留**没有 URI 的条目（用 `null` 占位）而不是就地滤掉：条目本身就是「这次分享带着
* 内容」的证据——只有纯文本条目时本端一个字节都读不到（本端不读 `ClipData` 里的文本），那种
* 情形必须能说出口，见 [SharedContent.contentUnreadable]。
*/
private fun Intent.clipUris(): List<String?> {
val clip = clipData ?: return emptyList()
return (0 until clip.itemCount).map { clip.getItemAt(it).uri?.toString() }
}
}
/**
* `EXTRA_STREAM` 一条**原始值** ⇒ 里面能读出来的地址，按形态分成两组。
*
* ## 为什么读原始值而不是挨个 `getXxxExtra` 去问
* `EXTRA_STREAM` 在真实世界里有三种形态：规范推荐的 `Uri`（多选时 `ArrayList<Uri>`）、`String[]`、
* `ArrayList<String>`。后两种（历史遗留 / 跨平台壳应用常见）此前**完全认不出**：`getParcelableExtra`
* 对 `String[]` 只会往 logcat 打一句
* `ClassCastException: Cannot cast [Ljava.lang.String; to android.net.Uri` 然后回 `null`，
* `getParcelableArrayListExtra` 同理——于是整次分享「什么都没发生」，连一句告知都没有。读原始值再按
* 类型分派是一次判完三种形态，顺带也不再往 logcat 里丢那两行噪声（`Bundle.get` 不做类型检查，
* 正是这里需要的；`getXxxExtra` 那一套是查完再 cast，查不中就把值扔了）。
*
* ## 形态决定信任级别
* - [uriForms]：`Uri`，以及数组 / 列表里的 `Uri`。对方是把 URI **对象**写进去的，这是规范路径；
* 本端维持既有口径不动（不看 scheme）。
* - [stringForms]：`String` / `CharSequence` 及其数组 / 列表。这是本端新开的一条读入口，所以开得窄
* ——能不能用由 [ShareRules.stringStreamUri] 逐条判（只认 `content://`）。
*
* 认不出形态的原始值（别的 `Parcelable` / 数字 / 映射……）**不猜**：两边都不收。
*/
internal data class ShareStreamExtras(
val uriForms: List<String>,
val stringForms: List<String>,
)
/** 见 [ShareStreamExtras]：把 `EXTRA_STREAM` 的原始值按形态摊平成两组地址（纯逻辑，可单测）。 */
internal fun shareStreamExtrasOf(raw: Any?): ShareStreamExtras {
val uriForms = mutableListOf<String>()
val stringForms = mutableListOf<String>()
fun collect(value: Any?) {
when (value) {
null -> Unit
is Uri -> uriForms += value.toString()
// 含 String。`Spanned` 之类也走这一条：它照样要过 scheme 白名单，不是「因为它是
// CharSequence 就信」。
is CharSequence -> stringForms += value.toString()
is Array<*> -> value.forEach { collect(it) }
is Iterable<*> -> value.forEach { collect(it) }
else -> Unit
}
}
collect(raw)
return ShareStreamExtras(uriForms = uriForms, stringForms = stringForms)
}
app/src/main/kotlin/top/yeij/cyrene/core/auth/AuthManager.kt
+254
View File
@@ -0,0 +1,254 @@
package top.yeij.cyrene.core.auth
import top.yeij.cyrene.core.error.CyreneError
import top.yeij.cyrene.data.api.ApiClientFactory
import top.yeij.cyrene.data.api.ApiErrorEnvelope
import top.yeij.cyrene.data.api.CyreneApi
import top.yeij.cyrene.data.api.dto.LoginRequest
import top.yeij.cyrene.data.api.dto.LogoutRequest
import top.yeij.cyrene.data.api.dto.RefreshRequest
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeoutOrNull
import java.io.IOException
import java.net.ConnectException
import java.net.SocketTimeoutException
import java.net.UnknownHostException
import javax.net.ssl.SSLException
sealed interface SessionState {
data object Unknown : SessionState
data object LoggedOut : SessionState
data class LoggedIn(val baseUrl: String, val role: String) : SessionState
}
/**
* 会话生命周期：登录、静默恢复、续期、登出。
*
* B2 起密码**不再落盘**：长期凭据是 refresh token，访问令牌过期时用它续期，
* 续期由 [TokenRefresher] 单飞协调（并发 401 只会真的刷一次——服务端轮换无宽限期）。
*
* @param apiFactory 认证接口的构造方式。默认走真实 Retrofit；单测注入假实现即可覆盖
* 登录 / 迁移 / 登出路径，既不需要网络也不需要新增依赖。
*/
class AuthManager(
private val store: SessionStorage,
private val apiFactory: (String) -> CyreneApi = { ApiClientFactory.create(baseUrl = it) },
) {
private val _state = MutableStateFlow<SessionState>(SessionState.Unknown)
val state: StateFlow<SessionState> = _state.asStateFlow()
@Volatile
var currentBaseUrl: String = ""
private set
private val refresher = TokenRefresher(store, ::refreshCall)
/** 不带令牌的认证客户端（登录 / 刷新 / 登出），按 baseUrl 缓存。可被 OkHttp 线程读到。 */
@Volatile
private var authApi: CyreneApi? = null
@Volatile
private var authApiBaseUrl: String? = null
/**
* 401 处置：能续期就用新令牌重试一次，明确被拒才判终态。
* 暂时性失败（网络 / 5xx）**绝不清会话**——见 B2 §6。
*/
val unauthorizedPolicy: UnauthorizedPolicy = object : UnauthorizedPolicy {
override fun renew(usedToken: String): AuthRecovery = refresher.renew(usedToken)
override fun onSessionEnded() = onSessionExpired()
}
/** tokenProvider 与 WS 握手用：临近过期时阻塞地先换令牌。 */
fun currentToken(): String? = refresher.ensureToken()
/**
* WS 握手 401 的一次性恢复：换一次令牌让上层重连。
* 与 401 拦截器共用同一条单飞路径，因此 REST 与 WS 同时失效也只会打一次刷新。
*/
fun recoverSocketAuth(): AuthRecovery = refresher.renew(store.load().token)
/**
* 启动时恢复会话（D12 + B2 迁移）。顺序即优先级：
*
* 1. **迁移**：没有 refresh token 却还留着旧版的明文密码 → 用旧凭据静默登录一次换 refresh token，
* 成功后立刻把它抹掉；失败（例如离线）保留原值、**不登出**，下次启动再试。
* 2. 已经有 refresh token → 任何残留的明文密码立刻抹掉。
* 3. 访问令牌过期 → 用 refresh token 续期。密码没了以后，这是唯一的静默恢复途径；
* 没有了它，隔一天再打开就要重新输密码（比旧版还差）。
* 4. 仍然拿不到有效令牌 → 回登录页（username 仍预填）。
*/
suspend fun bootstrap() = withContext(Dispatchers.IO) {
var session = store.load()
currentBaseUrl = session.baseUrl
val legacyUser = session.username?.takeIf(String::isNotBlank)
val legacyPassword = session.password?.takeIf(String::isNotBlank)
if (session.refreshToken.isNullOrBlank() && legacyUser != null && legacyPassword != null) {
doLogin(session.baseUrl, legacyUser, legacyPassword)
session = store.load()
} else if (!session.password.isNullOrBlank()) {
store.purgePassword()
session = store.load()
}
if (!session.hasValidToken() && !session.refreshToken.isNullOrBlank()) {
refresher.renew(session.token)
session = store.load()
}
_state.value = if (session.hasValidToken()) {
SessionState.LoggedIn(session.baseUrl, session.role.orEmpty())
} else {
SessionState.LoggedOut
}
}
suspend fun login(rawBaseUrl: String, username: String, password: String): CyreneError? =
withContext(Dispatchers.IO) {
doLogin(ApiClientFactory.normalizeBaseUrl(rawBaseUrl), username, password)
}
/**
* 主动登出：先尽力吊销服务端的 refresh 授权（否则本地「登出」之后那条授权还能活 30 天），
* 再抹掉本地一切。吊销失败、超时、离线都不阻断本地清理，所以离线登出依然干净。
*/
suspend fun logout() = withContext(Dispatchers.IO) {
val refreshToken = store.load().refreshToken?.takeIf(String::isNotBlank)
if (refreshToken != null) {
// 吊销请求不能拖住登出：给一个短上限，超时就当离线处理。
withTimeoutOrNull(REVOKE_TIMEOUT_MS) {
try {
authApi(sessionBaseUrl()).logout(LogoutRequest(refreshToken))
} catch (e: CancellationException) {
throw e
} catch (_: Exception) {
// 尽力而为：离线 / 服务端报错也必须把本地清干净。
}
}
}
store.clearAll()
authApi = null
authApiBaseUrl = null
_state.value = SessionState.LoggedOut
}
/** 会话终结（refresh 不可能或明确被拒）：清令牌回登录页；username 保留以便预填。 */
fun onSessionExpired() {
store.clearSession()
_state.value = SessionState.LoggedOut
}
private suspend fun doLogin(url: String, username: String, password: String): CyreneError? {
return try {
val response = authApi(url).login(LoginRequest(username, password))
val data = response.body()?.data
when {
response.isSuccessful && data != null -> {
store.saveLogin(url, data.token, data.expiresAt, data.role, username, data.refreshToken)
// B2 红线：不再写明文密码。拿到长期凭据后，把历史遗留的那一份也一并抹掉。
if (!data.refreshToken.isNullOrBlank()) store.purgePassword()
currentBaseUrl = url
_state.value = SessionState.LoggedIn(url, data.role)
null
}
response.isSuccessful -> CyreneError.Local(CyreneError.LocalKind.Parse)
else -> {
val parsed = parseError(response.errorBody()?.string())
if (response.code() == HTTP_UNAUTHORIZED) {
CyreneError.Unauthorized(parsed?.code.orEmpty(), parsed?.message.orEmpty())
} else {
CyreneError.Server(
code = parsed?.code.orEmpty(),
message = parsed?.message.orEmpty(),
httpStatus = response.code(),
)
}
}
}
} catch (e: Exception) {
mapException(e)
}
}
/**
* [TokenRefresher] 注入的阻塞刷新调用。
*
* 它跑在 OkHttp 的调用线程上（拦截器 / tokenProvider），所以这里用 `runBlocking` 就地驱动
* Retrofit 的挂起接口——那正是此刻需要的语义：同步等结果。
*
* 客户端**不带令牌**，镜像 [doLogin]：既不会让过期令牌搭车，也不会把刷新的 401 送回
* 本类的过期处理路径（那两个客户端用的是 [NoUnauthorizedPolicy]）。
*/
private fun refreshCall(refreshToken: String): RefreshCall {
val baseUrl = sessionBaseUrl()
if (baseUrl.isBlank()) return RefreshCall.Failed
return try {
val response = runBlocking { authApi(baseUrl).refresh(RefreshRequest(refreshToken)) }
val data = response.body()?.data
when {
response.isSuccessful && data != null ->
RefreshCall.Ok(data.token, data.expiresAt, data.refreshToken)
// 200 但解不动：不拿会话去赌，当暂时性失败。
response.isSuccessful -> RefreshCall.Failed
// 该接口唯一的 401 就是 invalid_grant（未知 / 已吊销 / 已过期 / 已被用掉）。
response.code() == HTTP_UNAUTHORIZED -> RefreshCall.Rejected
else -> RefreshCall.Failed
}
} catch (_: Exception) {
RefreshCall.Failed
}
}
private fun authApi(baseUrl: String): CyreneApi {
val cached = authApi
if (cached != null && authApiBaseUrl == baseUrl) return cached
val created = apiFactory(baseUrl)
authApi = created
authApiBaseUrl = baseUrl
return created
}
private fun sessionBaseUrl(): String = currentBaseUrl.ifBlank { store.load().baseUrl }
private fun StoredSession.hasValidToken(): Boolean =
!token.isNullOrBlank() && expiresAt * 1000 > System.currentTimeMillis()
private fun parseError(body: String?) = body
?.takeIf { it.isNotBlank() }
?.let {
runCatching {
ApiClientFactory.json.decodeFromString(ApiErrorEnvelope.serializer(), it).error
}.getOrNull()
}
private fun mapException(e: Throwable): CyreneError = when (e) {
is UnknownHostException -> CyreneError.Local(CyreneError.LocalKind.Dns)
is SSLException -> CyreneError.Local(CyreneError.LocalKind.Tls)
is SocketTimeoutException -> CyreneError.Local(CyreneError.LocalKind.Timeout)
is ConnectException -> CyreneError.Local(CyreneError.LocalKind.ConnectFailed)
is java.net.UnknownServiceException -> CyreneError.Local(CyreneError.LocalKind.CleartextBlocked)
is IOException -> CyreneError.Local(CyreneError.LocalKind.NoNetwork)
else -> CyreneError.Local(CyreneError.LocalKind.Unknown)
}
private companion object {
const val HTTP_UNAUTHORIZED = 401
/** 吊销授权的最长等待：到点就当离线，本地照样清干净。 */
const val REVOKE_TIMEOUT_MS = 3_000L
}
}
app/src/main/kotlin/top/yeij/cyrene/core/auth/SessionStore.kt
+137
View File
@@ -0,0 +1,137 @@
package top.yeij.cyrene.core.auth
import android.content.Context
import android.content.SharedPreferences
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
data class StoredSession(
val baseUrl: String,
val token: String?,
val expiresAt: Long,
val role: String?,
val username: String?,
/** 长期凭据（B2）；B2 之前登录的安装没有这一项，因此可能为 null。 */
val refreshToken: String?,
/**
* **遗留字段**：B2 之前的版本把登录密码落在这里。
* 只读用于一次性迁移，绝不再写入；见 [SessionStorage.purgePassword]。
*/
val password: String?,
)
/**
* 会话存储契约。[SessionStore] 是唯一的生产实现（EncryptedSharedPreferences）；
* 单元测试用内存假实现顶替，避免把 Android 的加密存储拖进 JVM 测试。
*/
interface SessionStorage {
fun load(): StoredSession
/** 登录成功：整份会话落盘。**不写密码**（B2 红线）。 */
fun saveLogin(
baseUrl: String,
token: String,
expiresAt: Long,
role: String,
username: String,
refreshToken: String?,
)
/**
* 只替换令牌三元组，保留 baseUrl / username / role。
* [refreshToken] 为 null 表示沿用原值——`AUTH_REFRESH_ROTATE_DISABLED=true` 时服务端不下发新的，
* 此时旧凭据仍然有效，绝不能丢掉。
*/
fun updateTokens(token: String, expiresAt: Long, refreshToken: String?)
/**
* 确定性抹掉历史遗留的明文密码。
* 用 `commit()` 而不是 `apply()`：这是红线清除，必须在下一次读取之前就落到磁盘上。
*/
fun purgePassword()
/** 会话失效：清 token 与 refresh token，保留 username 以便登录页预填。 */
fun clearSession()
/** 主动登出：整份清空。 */
fun clearAll()
}
/** JWT 与登录凭据的加密存储（红线：不落明文密码、不打日志）。 */
class SessionStore(context: Context) : SessionStorage {
private val prefs: SharedPreferences = EncryptedSharedPreferences.create(
context,
FILE_NAME,
MasterKey.Builder(context).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build(),
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
)
override fun load(): StoredSession = StoredSession(
baseUrl = prefs.getString(KEY_BASE_URL, "").orEmpty(),
token = prefs.getString(KEY_TOKEN, null),
expiresAt = prefs.getLong(KEY_EXPIRES_AT, 0L),
role = prefs.getString(KEY_ROLE, null),
username = prefs.getString(KEY_USERNAME, null),
refreshToken = prefs.getString(KEY_REFRESH_TOKEN, null),
// 只读：迁移路径靠它判断「这是升级前的安装」，不再写入。
password = prefs.getString(KEY_PASSWORD, null),
)
override fun saveLogin(
baseUrl: String,
token: String,
expiresAt: Long,
role: String,
username: String,
refreshToken: String?,
) {
val editor = prefs.edit()
.putString(KEY_BASE_URL, baseUrl)
.putString(KEY_TOKEN, token)
.putLong(KEY_EXPIRES_AT, expiresAt)
.putString(KEY_ROLE, role)
.putString(KEY_USERNAME, username)
if (!refreshToken.isNullOrBlank()) editor.putString(KEY_REFRESH_TOKEN, refreshToken)
editor.apply()
}
override fun updateTokens(token: String, expiresAt: Long, refreshToken: String?) {
val editor = prefs.edit()
.putString(KEY_TOKEN, token)
.putLong(KEY_EXPIRES_AT, expiresAt)
// 轮换关闭时服务端不下发新凭据，旧的那一份继续有效，必须保留。
if (!refreshToken.isNullOrBlank()) editor.putString(KEY_REFRESH_TOKEN, refreshToken)
editor.apply()
}
override fun purgePassword() {
prefs.edit().remove(KEY_PASSWORD).commit()
}
override fun clearSession() {
prefs.edit()
.remove(KEY_TOKEN)
.remove(KEY_EXPIRES_AT)
.remove(KEY_ROLE)
.remove(KEY_REFRESH_TOKEN)
.apply()
}
override fun clearAll() {
prefs.edit().clear().apply()
}
private companion object {
const val FILE_NAME = "cyrene_session"
const val KEY_BASE_URL = "base_url"
const val KEY_TOKEN = "token"
const val KEY_EXPIRES_AT = "expires_at"
const val KEY_ROLE = "role"
const val KEY_USERNAME = "username"
const val KEY_REFRESH_TOKEN = "refresh_token"
const val KEY_PASSWORD = "password"
}
}
app/src/main/kotlin/top/yeij/cyrene/core/auth/TokenRefresher.kt
+132
View File
@@ -0,0 +1,132 @@
package top.yeij.cyrene.core.auth
/** 一次令牌续期的结果。 */
sealed interface AuthRecovery {
/** 已拿到可用的访问令牌：可能是刚签发的，也可能是别的线程刚换好的。 */
data class Renewed(val token: String) : AuthRecovery
/**
* 无法续期：本地没有 refresh token，或被服务端以 `invalid_grant` 拒绝
* （未知 / 已吊销 / 已过期 / 已被用掉，服务端把这四种情况折叠成一个码）。
* 这是终态——必须重新登录。
*/
data object Unrecoverable : AuthRecovery
/** 暂时性失败：网络不通、5xx、响应解不动。会话可能仍然有效，稍后再试。 */
data object Transient : AuthRecovery
}
/**
* [TokenRefresher] 注入的刷新调用结果。
* 把 HTTP 细节挡在协调逻辑之外，单飞与代际守卫因此可以纯 JVM 单测。
*/
sealed interface RefreshCall {
/** 200：新的访问令牌；[refreshToken] 为 null 表示服务端关闭了轮换、旧凭据继续有效。 */
data class Ok(val token: String, val expiresAt: Long, val refreshToken: String?) : RefreshCall
/** `401 invalid_grant`。 */
data object Rejected : RefreshCall
/** 网络 / 5xx / 解析失败。 */
data object Failed : RefreshCall
}
/**
* 单飞（single-flight）刷新协调器。
*
* ## 为什么必须单飞
* 服务端 `RefreshStore.Rotate` 是**原子且无宽限期**的：同一个 refresh token 被第二次使用会立刻
* 拿到 `invalid_grant`（防重放）。而本端并发 401 是常态——管理概览页两个请求并发、聊天页 REST 与
* WS 同时起步。所以同一时刻只允许一个线程真正发刷新请求，其余线程在锁上等待后复用结果。
*
* ## 代际守卫
* 拿到锁之后**重新读一次存储**：如果已存的访问令牌既不是自己手里那份（[renew] 的 `staleToken`）、
* 又还没到过期点，说明等在锁上的这段时间里别的线程已经换好了令牌——直接复用，绝不刷第二次。
*
* ## 线程模型
* 全部逻辑跑在**调用方线程**上（OkHttp 的调用线程 / WS 重连协程），用 JVM 监视器锁串行化。
* 因此这里没有、也不能用协程 `Mutex`——调用点根本没有 suspend 上下文。
* 真实的刷新请求由调用方用**不带令牌**的客户端发出（见 `AuthManager.refreshCall`），
* 不会递归回本类。
*
* @param store 会话读写；实现必须让写入立刻对下一次 [SessionStorage.load] 可见。
* @param call 真正发刷新请求的阻塞调用。
* @param now 当前毫秒时间戳，可注入以便单测。
*/
class TokenRefresher(
private val store: SessionStorage,
private val call: (refreshToken: String) -> RefreshCall,
private val now: () -> Long = System::currentTimeMillis,
) {
private val lock = Any()
/**
* 已经确定无效的那个 refresh token。`invalid_grant` 对该值而言是**永久**结论，
* 记下来可以让同一次失效里的其它并发 401 直接得到终态，不必各打一次注定失败的请求。
* 值本身随机且每次轮换都变，因此不需要额外失效逻辑。
*/
private var rejectedRefreshToken: String? = null
/** 距过期不足 [SKEW_MS] 就算「该提前换令牌了」。 */
fun isNearExpiry(session: StoredSession): Boolean =
session.expiresAt * 1000 - now() <= SKEW_MS
/**
* 阻塞地给出一个当下可用的访问令牌；临近过期时先走一次单飞刷新。
* 供 OkHttp 的 tokenProvider 与 WS 握手使用（每次重连都会重新读）。
*
* 刷新失败时**仍然返回手里那份令牌**——它可能还没真的过期，401 交给兜底路径处理；
* 在这里返回 null 会让整条请求链断掉，比让服务端来裁决更糟。
*/
fun ensureToken(): String? {
val session = store.load()
val token = session.token?.takeIf(String::isNotBlank) ?: return null
if (!isNearExpiry(session)) return token
return when (val recovery = renew(token)) {
is AuthRecovery.Renewed -> recovery.token
AuthRecovery.Unrecoverable, AuthRecovery.Transient -> token
}
}
/**
* 单飞刷新：同一时刻只有一个线程真正发请求，其余线程在锁上等待并复用结果。
*
* @param staleToken 触发续期的那次请求实际携带的令牌；null 表示只知道「手上没有可用的令牌」。
*/
fun renew(staleToken: String?): AuthRecovery = synchronized(lock) {
val session = store.load()
// 代际守卫：等在锁上的这段时间里，别的线程已经换好了令牌 → 复用，绝不用同一个 refresh token 打第二次。
val current = session.token
if (!current.isNullOrBlank() && current != staleToken && !isNearExpiry(session)) {
return@synchronized AuthRecovery.Renewed(current)
}
val refreshToken = session.refreshToken?.takeIf(String::isNotBlank)
?: return@synchronized AuthRecovery.Unrecoverable
if (refreshToken == rejectedRefreshToken) return@synchronized AuthRecovery.Unrecoverable
when (val result = call(refreshToken)) {
is RefreshCall.Ok -> {
rejectedRefreshToken = null
store.updateTokens(result.token, result.expiresAt, result.refreshToken)
AuthRecovery.Renewed(result.token)
}
RefreshCall.Rejected -> {
rejectedRefreshToken = refreshToken
AuthRecovery.Unrecoverable
}
RefreshCall.Failed -> AuthRecovery.Transient
}
}
private companion object {
/** 提前量：24h 的访问令牌留 60s 余量，避免踩着过期边界发请求。 */
const val SKEW_MS = 60_000L
}
}
app/src/main/kotlin/top/yeij/cyrene/core/auth/UnauthorizedPolicy.kt
+29
View File
@@ -0,0 +1,29 @@
package top.yeij.cyrene.core.auth
/**
* 「带了令牌仍然 401」的处置策略。
*
* 由 `ApiClientFactory` 的拦截器在 **OkHttp 的调用线程上同步调用**，所以实现必须是
* 阻塞且线程安全的——那里没有 suspend 上下文，协程 `Mutex` 帮不上忙。
*/
interface UnauthorizedPolicy {
/**
* 尝试把被服务端拒绝的令牌换成可用的新令牌。
*
* @param usedToken 触发这次 401 的请求实际携带的访问令牌。
* @return [AuthRecovery.Renewed] 时调用方会用新令牌重试一次；另外两种都不重试。
*/
fun renew(usedToken: String): AuthRecovery
/** 终态：续期不可能（没有 refresh token）或明确被拒（`invalid_grant`）——必须重新登录。 */
fun onSessionEnded()
}
/** 不带令牌的客户端（登录 / 刷新 / 登出）用：永不续期，也永不判终态。 */
object NoUnauthorizedPolicy : UnauthorizedPolicy {
override fun renew(usedToken: String): AuthRecovery = AuthRecovery.Unrecoverable
override fun onSessionEnded() = Unit
}
app/src/main/kotlin/top/yeij/cyrene/core/error/CyreneError.kt
+53
View File
@@ -0,0 +1,53 @@
package top.yeij.cyrene.core.error
/**
* 统一错误模型：区分「服务端有响应」与「本地/网络层失败」。
* 约定（S1.1）：已建立连接时用服务端 `error.message`，本地错误由客户端负责文案。
*/
sealed interface CyreneError {
val userMessage: String
data class Server(
val code: String,
val message: String,
val httpStatus: Int,
) : CyreneError {
override val userMessage: String
get() = message.ifBlank { "服务端错误（HTTP $httpStatus）" }
}
data class Unauthorized(
val code: String,
val message: String,
) : CyreneError {
override val userMessage: String
get() = message.ifBlank { "用户名或密码不正确" }
}
data class Local(val kind: LocalKind) : CyreneError {
override val userMessage: String
get() = when (kind) {
LocalKind.InvalidUrl -> "服务器地址格式不对，示例：http://192.168.1.10:8080"
LocalKind.NoNetwork -> "网络不可用，请检查连接"
LocalKind.Dns -> "找不到服务器，请检查服务器地址"
LocalKind.Tls -> "证书校验失败（自签证书暂不支持）"
LocalKind.Timeout -> "连接超时，服务器没有响应"
LocalKind.ConnectFailed -> "无法连接到服务器"
LocalKind.CleartextBlocked -> "系统禁止明文 HTTP 访问"
LocalKind.Parse -> "服务器返回的数据无法识别"
LocalKind.Unknown -> "发生未知错误"
}
}
enum class LocalKind {
InvalidUrl,
NoNetwork,
Dns,
Tls,
Timeout,
ConnectFailed,
CleartextBlocked,
Parse,
Unknown,
}
}
app/src/main/kotlin/top/yeij/cyrene/core/prefs/AppSettings.kt
+134
View File
@@ -0,0 +1,134 @@
package top.yeij.cyrene.core.prefs
import android.content.Context
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
private val Context.appDataStore: DataStore<Preferences> by preferencesDataStore("cyrene_app")
enum class ThemeMode { System, Light, Dark }
/**
* 她忙时发消息的行为（协同项 A2，契约 v0.56 §3.1 的 `interrupt.scope`；忙时并行规范 §2.2 的
* `chat.parallel`）。
*
* 类型名与落盘键（`interrupt_mode`）都是**历史名字**：第三档「并行」接上来之后它管的不再只是打断，
* 但改类型名 / 键名 / 既有档位的 `name` 都会让已存偏好读不出来并**静默回落**默认档——所以三个名字
* 一个都不动（见 [toInterruptMode] 与 `InterruptModeTest` 的「落盘名稳定」那几条）。
*
* 一档同时表达**两个上行声明**：[wireScope] 与 [wireParallel]。三档各占一种组合——打断占前者、
* 并行占后者、追加队列两个都不占，**没有任何一档同时给两个**。
*
* @property wireScope 上行 `interrupt` 帧的 `scope` 取值；`null` = **不发打断帧**。注意它不是
* 「发一条省略 scope 的帧」——那在服务端是 `"all"`（连待处理队列一起清），是完全不同的语义。
* @property wireParallel 这条 `chat` 要不要声明 `parallel:true`；`false` = **一个字节都不带**。
*/
enum class InterruptMode(val wireScope: String?, val wireParallel: Boolean) {
/**
* 追加队列（默认）：忙时只把消息排进队列，不打断也不并行。
*
* 该模式**两个声明都不发**（`interruptScopeForSend` 恒为「不发」、`parallelForSend` 恒为
* `false`）：默认档的线上请求与本偏好存在之前**逐字节相同**。
*/
AppendQueue(wireScope = null, wireParallel = false),
/**
* 打断：只取消在跑回合、**保留**待处理队列（`scope:"current"`）。
* 队列里的消息按编排器正常续跑规则继续执行，一条都不丢。
*/
Interrupt(wireScope = "current", wireParallel = false),
/**
* 并行：忙时**不打断**在跑的那一路，本条**另起一路**同时处理（`chat.parallel=true`）；
* 服务端并发额度满时**不报错**，这一条落回排队。
*
* [wireScope] 为 `null` 不是因为「这一档没什么要发的东西」（它当然要发东西，发的是
* `chat.parallel`），而是因为**并行与打断互斥**：这一档**绝不允许**产生 `interrupt` 帧——
* 一产生就等于先把要并行的那一路砍掉。
*
* 代价：两路各算一遍 ⇒ 峰值算力 / token 近翻倍（主人 2026-10-05 裁决 4：不分摊、优先性能），
* 所以设置页这一栏的 summary 把这句代价明说出来。
*/
Parallel(wireScope = null, wireParallel = true),
}
/**
* 落盘字符串 → 档位（`AppSettings` 的 `interrupt_mode` 键读取口；抽成顶层函数是为了能单测——
* `AppSettings` 本体要 Android + DataStore，单测里起不来）。
*
* 缺省 / 旧版本遗留的未知值一律解成默认档（追加队列），绝不悄悄换成更激进的档位。
*/
fun String?.toInterruptMode(): InterruptMode = when (this) {
InterruptMode.Interrupt.name -> InterruptMode.Interrupt
InterruptMode.Parallel.name -> InterruptMode.Parallel
else -> InterruptMode.AppendQueue
}
/**
* App 级偏好（非机密）。
*
* @param themeMode 主题深浅
* @param showNarration 是否显示 `<action>` / `<narration>` 旁白
* @param thinkingExpanded 思维链卡片默认是否展开
* @param interruptMode 她正忙时按发送的行为（默认追加队列）
*/
data class AppPrefs(
val themeMode: ThemeMode = ThemeMode.System,
val showNarration: Boolean = true,
val thinkingExpanded: Boolean = true,
val interruptMode: InterruptMode = InterruptMode.AppendQueue,
)
/** 全局注入 App 偏好，供聊天渲染等深层组件读取。 */
val LocalAppPrefs = staticCompositionLocalOf { AppPrefs() }
class AppSettings(context: Context) {
private val store: DataStore<Preferences> = context.applicationContext.appDataStore
val data: Flow<AppPrefs> = store.data.map { prefs ->
AppPrefs(
themeMode = prefs[KEY_THEME_MODE].toThemeMode(),
showNarration = prefs[KEY_SHOW_NARRATION] ?: true,
thinkingExpanded = prefs[KEY_THINKING_EXPANDED] ?: true,
interruptMode = prefs[KEY_INTERRUPT_MODE].toInterruptMode(),
)
}
suspend fun setThemeMode(mode: ThemeMode) {
store.edit { it[KEY_THEME_MODE] = mode.name }
}
suspend fun setShowNarration(enabled: Boolean) {
store.edit { it[KEY_SHOW_NARRATION] = enabled }
}
suspend fun setThinkingExpanded(enabled: Boolean) {
store.edit { it[KEY_THINKING_EXPANDED] = enabled }
}
suspend fun setInterruptMode(mode: InterruptMode) {
store.edit { it[KEY_INTERRUPT_MODE] = mode.name }
}
private fun String?.toThemeMode(): ThemeMode = when (this) {
ThemeMode.Light.name -> ThemeMode.Light
ThemeMode.Dark.name -> ThemeMode.Dark
else -> ThemeMode.System
}
private companion object {
val KEY_THEME_MODE = stringPreferencesKey("theme_mode")
val KEY_SHOW_NARRATION = booleanPreferencesKey("show_narration")
val KEY_THINKING_EXPANDED = booleanPreferencesKey("thinking_expanded")
val KEY_INTERRUPT_MODE = stringPreferencesKey("interrupt_mode")
}
}
app/src/main/kotlin/top/yeij/cyrene/core/prefs/EnumPreferences.kt
+63
View File
@@ -0,0 +1,63 @@
package top.yeij.cyrene.core.prefs
import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import top.yeij.cyrene.data.api.ApiClientFactory
import top.yeij.cyrene.data.api.dto.EnumTableDto
private val Context.enumDataStore: DataStore<Preferences> by preferencesDataStore("cyrene_enums")
/**
* 枚举权威表的本地回退快照（§1.1）。
*
* @param table 上次成功拉取的权威表；拉取失败时先用它渲染（绝不因此清空角标）
* @param fingerprint `baseUrl + username`：换服务器/账号后快照作废
*/
data class EnumPrefs(
val table: EnumTableDto? = null,
val fingerprint: String = "",
) {
/** 指纹匹配才认这份快照——绝不把别的服务器/账号的标签拿来用。 */
fun tableFor(fingerprint: String): EnumTableDto? = table?.takeIf { this.fingerprint == fingerprint }
}
class EnumPreferences(context: Context) {
private val json = ApiClientFactory.json
private val store: DataStore<Preferences> = context.applicationContext.enumDataStore
val data: Flow<EnumPrefs> = store.data.map { prefs ->
EnumPrefs(
table = prefs[KEY_TABLE].decodeTable(),
fingerprint = prefs[KEY_FINGERPRINT].orEmpty(),
)
}
suspend fun save(table: EnumTableDto, fingerprint: String) {
store.edit { prefs ->
prefs[KEY_TABLE] = json.encodeToString(EnumTableDto.serializer(), table)
prefs[KEY_FINGERPRINT] = fingerprint
}
}
/** 登出 / 切换服务器时清空。 */
suspend fun clear() {
store.edit { it.clear() }
}
private fun String?.decodeTable(): EnumTableDto? = this
?.let { runCatching { json.decodeFromString(EnumTableDto.serializer(), it) }.getOrNull() }
private companion object {
val KEY_TABLE = stringPreferencesKey("enum_table")
val KEY_FINGERPRINT = stringPreferencesKey("enum_fingerprint")
}
}
app/src/main/kotlin/top/yeij/cyrene/core/prefs/SessionPreferences.kt
+109
View File
@@ -0,0 +1,109 @@
package top.yeij.cyrene.core.prefs
import android.content.Context
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.longPreferencesKey
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import kotlinx.serialization.builtins.ListSerializer
import top.yeij.cyrene.data.api.ApiClientFactory
import top.yeij.cyrene.data.api.dto.SessionSummaryDto
private val Context.sessionDataStore: DataStore<Preferences> by preferencesDataStore("cyrene_sessions")
/**
* 会话列表的本地回退快照与显示态（§3.1）。
*
* @param snapshot 上次成功拉取的会话列表；服务端不可用时用它先渲染
* @param snapshotAt 快照时间（用于「同步于 N 分钟前」）
* @param fingerprint [accountFingerprint]：换服务器/账号后快照作废
* @param activeSessionId 上次停留的会话
*/
data class SessionPrefs(
val snapshot: List<SessionSummaryDto> = emptyList(),
val snapshotAt: Long = 0L,
val fingerprint: String = "",
val activeSessionId: String = SessionSummaryDto.MAIN_SESSION_ID,
) {
/** 指纹匹配才认这份快照——绝不把别的服务器/账号的会话列表拿来用。 */
fun snapshotFor(fingerprint: String): List<SessionSummaryDto> =
snapshot.takeIf { this.fingerprint == fingerprint }.orEmpty()
}
/**
* 账号指纹（纯函数）：`baseUrl + username`。回答的是「**这份本地状态属于哪个环境**」。
*
* 抽成一个函数的理由是**全仓只能有一份口径**：这类判据一旦各拼一套字符串，差一个分隔符
* 就会在某个闸门上漏过去——而漏过去的后果是把别的服务器/账号的内容摆到屏幕上。
* 现在的两个消费者是 [SessionPrefs.snapshotFor]（会话快照作不作废）与聊天页的 VM key
* （`chatViewModelKey`：那个 VM 是不是本环境的）。改口径就是改**两者**，不要就地另拼。
*
* 取用户名而不是角色：角色是同一个人在服务端被授的权限，账号身份由**服务器地址 + 用户名**
* 共同确定；要让指纹对不上，只能是换了服务器或换了账号，那两件事都该让本地状态作废。
*/
internal fun accountFingerprint(baseUrl: String, username: String?): String =
"$baseUrl|${username.orEmpty()}"
class SessionPreferences(context: Context) {
private val json = ApiClientFactory.json
private val store: DataStore<Preferences> = context.applicationContext.sessionDataStore
val data: Flow<SessionPrefs> = store.data.map { prefs ->
SessionPrefs(
snapshot = prefs[KEY_SNAPSHOT].decodeSessions(),
snapshotAt = prefs[KEY_SNAPSHOT_AT] ?: 0L,
fingerprint = prefs[KEY_FINGERPRINT].orEmpty(),
activeSessionId = prefs[KEY_ACTIVE] ?: SessionSummaryDto.MAIN_SESSION_ID,
)
}
/** 拉取成功：整体替换快照（不做 merge，避免已删除的会话变成幽灵）。 */
suspend fun saveSnapshot(sessions: List<SessionSummaryDto>, fingerprint: String) {
store.edit { prefs ->
prefs[KEY_SNAPSHOT] = json.encodeToString(SessionsSerializer, sessions)
prefs[KEY_SNAPSHOT_AT] = System.currentTimeMillis()
prefs[KEY_FINGERPRINT] = fingerprint
}
}
suspend fun setActive(sessionId: String) {
store.edit { prefs -> prefs[KEY_ACTIVE] = sessionId }
}
/** 删除会话：必要时把 active 退回主会话，并同步从快照里剔除。 */
suspend fun removeSession(sessionId: String) {
store.edit { prefs ->
if (prefs[KEY_ACTIVE] == sessionId) {
prefs[KEY_ACTIVE] = SessionSummaryDto.MAIN_SESSION_ID
}
val remaining = prefs[KEY_SNAPSHOT].decodeSessions().filterNot { it.id == sessionId }
prefs[KEY_SNAPSHOT] = json.encodeToString(SessionsSerializer, remaining)
}
}
/** 登出时清空：快照、指纹、active 一起走，下次登录不会先闪一份旧列表。 */
suspend fun clear() {
store.edit { it.clear() }
}
private fun String?.decodeSessions(): List<SessionSummaryDto> = this
?.let { runCatching { json.decodeFromString(SessionsSerializer, it) }.getOrNull() }
.orEmpty()
private companion object {
val KEY_SNAPSHOT = stringPreferencesKey("sessions_snapshot")
val KEY_SNAPSHOT_AT = longPreferencesKey("sessions_snapshot_at")
val KEY_FINGERPRINT = stringPreferencesKey("sessions_fingerprint")
val KEY_ACTIVE = stringPreferencesKey("active_session_id")
val SessionsSerializer = ListSerializer(SessionSummaryDto.serializer())
}
}
app/src/main/kotlin/top/yeij/cyrene/core/session/GoneSessions.kt
+47
View File
@@ -0,0 +1,47 @@
package top.yeij.cyrene.core.session
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.update
/**
* 本端**已经知道服务端没有这个会话**的那几个会话 id（进程级、只在内存里、只增不减）。
*
* ## 它回答的是哪一个问题
* 「这个 id 还值不值得我发一次请求」。`ChatViewModel` 每个访问过的会话各留一个常驻 VM
* （切走 / 删会话都不回收），而它们都订阅同一条共享连接 ⇒ **每次重连各自会去补拉一轮**。会话
* 在本端被删掉之后，那个 VM 并不知道（它没有别的渠道知道），于是**每一个**重连都发一次注定
* `404 session_not_found` 的补拉，404 被静默吞掉（S7 登记的那一条）。
*
* 补拉**事前**就能判掉它，靠的就是这里：删除是**本端自己做的**，那一刻就已经知道结果了，
* 没有任何理由等下一条请求回来才「发现」。于是这一位把「已知不存在」从「一次注定失败的往返」
* 提前成「一次本地查询」——**不是**「重连时少拉一点」的省流量优化，而是不让一个注定失败的请求
* 上路（它会占一条连接、写一行日志、并把 `sessionGone` 变成一个只能靠 404 才置得起来的位）。
*
* ## 为什么是进程级、为什么**不**持久化
* - 进程级（挂在 `AppContainer` 上，与那条共享连接同一层）：写它的是 `SessionsViewModel`
* （本端唯一的删除入口），读它的是**别的** VM —— 两个 VM 之间没有别的共享面。
* - **不持久化**：它只是「这一趟进程里已经知道的事」。重启之后本端的会话列表会重新从服务端拉
* （[top.yeij.cyrene.core.prefs.SessionPreferences] 那份快照本来就会整体替换），「这个会话还在不在」
* 以那一次服务端答复为准；把 id 落盘只会让一份陈旧记忆挡掉重启后的第一次拉取。
* - **换账号要清**（[clear]）：id 是服务端铸的，理论上不会跨账号撞车，但这一位说的是「本端
* 已经知道」，而换账号之后本端**什么都不知道** —— 留着上个环境的结论，是那种「差一个分隔符
* 就漏过去」的同一类错误（先例：`accountFingerprint` 的注释）。
*/
class GoneSessions {
private val ids = MutableStateFlow<Set<String>>(emptySet())
/** 记下「服务端已经没有这个会话了」。空串当无效值丢掉（那不是任何会话的 id）。 */
fun mark(sessionId: String) {
if (sessionId.isBlank()) return
ids.update { it + sessionId }
}
/** 本端是否**已经知道**它没了。只回答「知道不知道」，不回答「在不在」——不知道的一律 `false`。 */
fun contains(sessionId: String): Boolean = sessionId in ids.value
/** 换账号 / 登出：本端重新回到「什么都不知道」。 */
fun clear() {
ids.value = emptySet()
}
}
app/src/main/kotlin/top/yeij/cyrene/core/theme/CyreneTheme.kt
+16
View File
@@ -0,0 +1,16 @@
package top.yeij.cyrene.core.theme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import top.yukonga.miuix.kmp.theme.ColorSchemeMode
import top.yukonga.miuix.kmp.theme.MiuixTheme
import top.yukonga.miuix.kmp.theme.ThemeController
@Composable
fun CyreneTheme(
mode: ColorSchemeMode = ColorSchemeMode.System,
content: @Composable () -> Unit,
) {
val controller = remember(mode) { ThemeController(mode) }
MiuixTheme(controller = controller, content = content)
}
app/src/main/kotlin/top/yeij/cyrene/data/api/AdminApi.kt
+54
View File
@@ -0,0 +1,54 @@
package top.yeij.cyrene.data.api
import top.yeij.cyrene.data.api.dto.AdminBackthinkItemDto
import top.yeij.cyrene.data.api.dto.AdminLogEntryDto
import top.yeij.cyrene.data.api.dto.AdminMetricsDto
import top.yeij.cyrene.data.api.dto.AdminTraceSpanDto
import top.yeij.cyrene.data.api.dto.MemorySummaryDto
import top.yeij.cyrene.data.api.dto.PersonaSummaryDto
import retrofit2.Response
import retrofit2.http.GET
import retrofit2.http.Query
/**
* 管理只读监控端点（api-client §2，全部 `GET`，无写操作）。
*
* RBAC 由服务端兜底（`viewer` 对 ②③ 档一律 403），客户端按 §2.0 权限矩阵**自行降级**，
* 见 [top.yeij.cyrene.domain.admin.AdminAccess]；这里只负责取数，不做权限判断。
*/
interface AdminApi {
/** 网关请求指标；`qps` 为近 1 秒窗口计数。 */
@GET("api/v1/admin/observability/metrics")
suspend fun metrics(): Response<ApiEnvelope<AdminMetricsDto>>
/** 最近 trace span，服务端按时间倒序（最新在前）；`limit` 缺省 50、上限 500。 */
@GET("api/v1/admin/observability/trace")
suspend fun trace(@Query("limit") limit: Int? = null): Response<ApiEnvelope<List<AdminTraceSpanDto>>>
/**
* 后端日志 tail（api-client §2「可观测性契约」，v0.35）：`{"data":[{time,level,source,msg}]}`，
* **最新在前**；`limit` 缺省 200、上限 1000（≤0 或非法回落缺省）。
*
* 不暴露契约里的 `?level=`：它是**最低等级**过滤，只在服务端裁剪一次结果——而界面上那排
* 等级档要能在同一份数据上来回切换（契约 §3.12 也明确推送帧的过滤只能本地做），
* 所以这里一律取全量、由客户端本地过滤（`ui/admin/AdminOverviewMerge.kt`）。
*
* RBAC 是 v0.40 的 `viewerAuth`：**viewer** 也读得到（owner / admin 本来就可以），
* 与 `trace` / `metrics` 同档。
*/
@GET("api/v1/admin/observability/logs")
suspend fun logs(@Query("limit") limit: Int? = null): Response<ApiEnvelope<List<AdminLogEntryDto>>>
/** 人格列表（含 admin 专属 `thinking`）。 */
@GET("api/v1/admin/personas")
suspend fun personas(): Response<ApiEnvelope<List<PersonaSummaryDto>>>
/** 私人记忆正文；`viewer` 会拿到 403。 */
@GET("api/v1/admin/memories")
suspend fun memories(): Response<ApiEnvelope<List<MemorySummaryDto>>>
/** 后台思考记录；`viewer` 会拿到 403。 */
@GET("api/v1/admin/backthink")
suspend fun backthink(): Response<ApiEnvelope<List<AdminBackthinkItemDto>>>
}
app/src/main/kotlin/top/yeij/cyrene/data/api/ApiClientFactory.kt
+163
View File
@@ -0,0 +1,163 @@
package top.yeij.cyrene.data.api
import top.yeij.cyrene.BuildConfig
import top.yeij.cyrene.core.auth.AuthRecovery
import top.yeij.cyrene.core.auth.NoUnauthorizedPolicy
import top.yeij.cyrene.core.auth.UnauthorizedPolicy
import kotlinx.serialization.json.Json
import okhttp3.Interceptor
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.Response
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory
import java.util.concurrent.TimeUnit
/**
* **连接超时**（毫秒）：解析 DNS + 建立 TCP 连接（以及 TLS 握手）这一段的预算，**全端共用这一个值**。
*
* ## 为什么从 10 秒缩到 2.5 秒（W45）
* 它就是「**完全无网时快速进队列**」这条性质的唯一依据。W41 把这条性质寄托在一个 2.5 秒的探针上
* （W41 那个探针 client 的 `callTimeout`），而那个探针**从不复用连接池**、每次都要现做一次冷握手
* ——于是真机上出现了「探了，但请求一个字节都没写出去」，而它与「压根没探」在外部完全同形，推断
* 不出是哪一档。W45 删掉探测、改成**直接试 REST** 之后，这条性质改由**连接超时**承担：连不上就在 2.5 秒
* 内失败，消息进队列（内容一个字节都不丢，重发仍是同一个 `clientMsgId`）。
*
* 取值 2.5 秒：正常网络下一次 TCP 握手是毫秒到几十毫秒量级（局域网、ZeroTier / Tailscale 也远达
* 不到秒级），2.5 秒是「人开始觉得卡」之前的量级，也与 W41 那 2.5 秒的探针预算**对齐**——换成直接
* 试 REST 之后，「无网时用户最多等多久」因此没有变长。**绝不许**再回到 10 秒：那会让每一条离线
* 消息的用户都白等十倍的时间，换来的只是「极端慢网下多一次成功的机会」。
*
* ## 它不管什么
* 「连上了但服务端一直不回话」（半死的代理、接住连接却不回应）不是它的事——那是读 / 写超时
* （[READ_TIMEOUT_SECONDS]）与回落那一次投递自己的整通上限
* （[top.yeij.cyrene.ui.chat.REST_FALLBACK_TIMEOUT_MILLIS]）的事。两个闸各管一段，合起来才是
* 「没网时用户最多等多久」。
*/
const val CONNECT_TIMEOUT_MILLIS = 2_500L
/** 读 / 写超时（秒）：真请求（长文本、内联图片、文档字节）的耐心，与 [CONNECT_TIMEOUT_MILLIS] 分开。 */
private const val READ_TIMEOUT_SECONDS = 60L
object ApiClientFactory {
val json: Json = Json {
ignoreUnknownKeys = true
explicitNulls = false
coerceInputValues = true
}
/** 登录 / 刷新 / 登出接口（不注入 token、不参与续期）。 */
fun create(
baseUrl: String,
tokenProvider: () -> String? = { null },
unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
): CyreneApi = create(baseUrl, CyreneApi::class.java, tokenProvider, unauthorizedPolicy)
/**
* 通用入口：按需构建任意 Retrofit service。
*
* 超时**只有两个值**，都由文件顶上的常量解释：连接 [CONNECT_TIMEOUT_MILLIS]（短，保证「完全
* 无网时快速失败」）、读 / 写 [READ_TIMEOUT_SECONDS]（长，真请求的耐心）。**刻意不设
* `callTimeout`**：那会把文档字节下载与图片上传一并框住，而它们本来就是长请求；哪一次投递需要
* 整通上限，就写在哪一次投递的调用点上（例：回落那一次的
* [top.yeij.cyrene.ui.chat.REST_FALLBACK_TIMEOUT_MILLIS]）。
*
* DEBUG 下挂 BASIC 日志（`logcat -s OkHttp`）：`-->` 打在 `chain.proceed()` **之前**，所以
* 「这条请求有没有发出去」与「死在连接还是死在回执」当场可分——回落那条路下一轮要靠它取证。
* 不动 `Authorization`（BASIC 根本不打印任何头），级别**绝不许**再往上调：`/auth/refresh` 与
* `/auth/logout` 把 refresh token 放在请求体里。
*/
fun <T : Any> create(
baseUrl: String,
service: Class<T>,
tokenProvider: () -> String? = { null },
unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
): T {
val client = OkHttpClient.Builder()
// 连接这一段刻意短（理由见 [CONNECT_TIMEOUT_MILLIS]）：它是「无网时消息快速进队列」的
// 唯一依据，所以它**不含**任何整通上限的意味。
.connectTimeout(CONNECT_TIMEOUT_MILLIS, TimeUnit.MILLISECONDS)
.readTimeout(READ_TIMEOUT_SECONDS, TimeUnit.SECONDS)
.writeTimeout(READ_TIMEOUT_SECONDS, TimeUnit.SECONDS)
.addInterceptor(AuthInterceptor(tokenProvider, unauthorizedPolicy))
.apply {
if (BuildConfig.DEBUG) {
addInterceptor(
HttpLoggingInterceptor().apply {
// BASIC 是上限：`/auth/refresh` 与 `/auth/logout` 把 refresh token 放在**请求体**里，
// 再高一级就会把凭据打进 logcat。
level = HttpLoggingInterceptor.Level.BASIC
redactHeader("Authorization")
},
)
}
}
.build()
return Retrofit.Builder()
.baseUrl(normalizeBaseUrl(baseUrl))
.client(client)
.addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
.build()
.create(service)
}
/** Retrofit 要求 baseUrl 以 `/` 结尾；用户没写 scheme 时补 `http://`。 */
fun normalizeBaseUrl(raw: String): String {
var url = raw.trim()
if (url.isEmpty()) return url
if (!url.startsWith("http://") && !url.startsWith("https://")) {
url = "http://$url"
}
if (!url.endsWith("/")) url += "/"
return url
}
/**
* 注入 `X-API-Version` 与 `Authorization`，并兜住「**带了令牌仍然** 401」：
* 先向策略要一次新令牌，拿到就用它**重试一次**；明确被拒才判终态。
*
* 为什么是应用层拦截器而不是 OkHttp `Authenticator`：
* `Authenticator` 对**任何** 401 都会被调用（包括不带令牌的登录请求），而且它由
* RetryAndFollowUp 在内部循环里驱动，重试次数（上限 20 次）不受本类控制——一个持续 401 的
* 令牌会打出一串刷新风暴。应用层拦截器只在带令牌时介入，且重试严格一次
* （OkHttp 允许应用层拦截器多次 `proceed()`，`calls != 1` 的检查只对网络拦截器生效）。
*/
private class AuthInterceptor(
private val tokenProvider: () -> String?,
private val unauthorizedPolicy: UnauthorizedPolicy,
) : Interceptor {
override fun intercept(chain: Interceptor.Chain): Response {
val token = tokenProvider()
var response = chain.proceed(chain.request().withAuth(token))
// 只有「带了 token 仍 401」才算会话被拒；登录/刷新本身不带 token，不受影响。
if (response.code != HTTP_UNAUTHORIZED || token == null) return response
when (val recovery = unauthorizedPolicy.renew(token)) {
is AuthRecovery.Renewed -> {
response.close()
response = chain.proceed(chain.request().withAuth(recovery.token))
// 换上刚签发的令牌仍然 401：服务端根本不接受这个账号，再刷也没有意义，判终态。
if (response.code == HTTP_UNAUTHORIZED) unauthorizedPolicy.onSessionEnded()
}
AuthRecovery.Unrecoverable -> unauthorizedPolicy.onSessionEnded()
// 网络 / 5xx：会话可能还好着，原样把 401 交回去，绝不清会话。
AuthRecovery.Transient -> Unit
}
return response
}
private fun Request.withAuth(token: String?): Request = newBuilder()
.header("X-API-Version", "1")
.apply { if (token != null) header("Authorization", "Bearer $token") }
.build()
}
private const val HTTP_UNAUTHORIZED = 401
}
app/src/main/kotlin/top/yeij/cyrene/data/api/ApiEnvelope.kt
+21
View File
@@ -0,0 +1,21 @@
package top.yeij.cyrene.data.api
import kotlinx.serialization.Serializable
/** 后端统一信封：成功 `{data}`，失败 `{error:{code,message}}`。 */
@Serializable
data class ApiEnvelope<T>(
val data: T? = null,
val error: ApiError? = null,
)
@Serializable
data class ApiErrorEnvelope(
val error: ApiError? = null,
)
@Serializable
data class ApiError(
val code: String = "",
val message: String = "",
)
app/src/main/kotlin/top/yeij/cyrene/data/api/ApiErrorMapper.kt
+76
View File
@@ -0,0 +1,76 @@
package top.yeij.cyrene.data.api
import top.yeij.cyrene.core.error.CyreneError
import kotlinx.coroutines.CancellationException
import kotlinx.serialization.SerializationException
import retrofit2.Response
import java.io.IOException
import java.net.ConnectException
import java.net.SocketTimeoutException
import java.net.UnknownHostException
import javax.net.ssl.SSLException
/**
* 统一错误映射（S1.1）：已建连接用服务端 `error`，本地异常按类型分类。
* 供所有 REST 仓库复用；不要在各个仓库里各写一份。
*/
object ApiErrorMapper {
/** 有 HTTP 响应：401 → [CyreneError.Unauthorized]，其余 → [CyreneError.Server]。 */
fun fromHttp(httpStatus: Int, errorBody: String?): CyreneError {
val error = parseErrorEnvelope(errorBody)
val code = error?.code.orEmpty()
val message = error?.message.orEmpty()
return if (httpStatus == 401) {
CyreneError.Unauthorized(code = code, message = message)
} else {
CyreneError.Server(code = code, message = message, httpStatus = httpStatus)
}
}
/** 本地/网络异常 → [CyreneError.Local]。 */
fun fromThrowable(throwable: Throwable): CyreneError = when (throwable) {
is UnknownHostException -> CyreneError.Local(CyreneError.LocalKind.Dns)
is SSLException -> CyreneError.Local(CyreneError.LocalKind.Tls)
is SocketTimeoutException -> CyreneError.Local(CyreneError.LocalKind.Timeout)
is ConnectException -> CyreneError.Local(CyreneError.LocalKind.ConnectFailed)
is SerializationException -> CyreneError.Local(CyreneError.LocalKind.Parse)
is IOException -> CyreneError.Local(CyreneError.LocalKind.NoNetwork)
else -> CyreneError.Local(CyreneError.LocalKind.Unknown)
}
/** 解析 `{"error":{code,message}}`；非信封 / 空白 / 解析失败均返回 null。 */
fun parseErrorEnvelope(errorBody: String?): ApiError? = errorBody
?.takeIf { it.isNotBlank() }
?.let {
runCatching {
ApiClientFactory.json.decodeFromString(ApiErrorEnvelope.serializer(), it).error
}.getOrNull()
}
}
/** 把 [CyreneError] 塞进 Kotlin `Result` 的载体，便于 `Result<T>` 统一传递失败。 */
class CyreneException(val error: CyreneError) : Exception(error.userMessage)
/**
* 执行一次信封调用并把结果收敛成 `Result<T>`：
* 成功且 `data != null` → success；成功但 `data == null` → Parse；否则走 [ApiErrorMapper]。
*/
suspend fun <T : Any> apiCall(block: suspend () -> Response<ApiEnvelope<T>>): Result<T> =
try {
val response = block()
val data = response.body()?.data
when {
response.isSuccessful && data != null -> Result.success(data)
response.isSuccessful -> Result.failure(CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)))
else -> Result.failure(
CyreneException(
ApiErrorMapper.fromHttp(response.code(), response.errorBody()?.string()),
),
)
}
} catch (e: CancellationException) {
throw e
} catch (e: Exception) {
Result.failure(CyreneException(ApiErrorMapper.fromThrowable(e)))
}
app/src/main/kotlin/top/yeij/cyrene/data/api/ChatApi.kt
+23
View File
@@ -0,0 +1,23 @@
package top.yeij.cyrene.data.api
import top.yeij.cyrene.data.api.dto.ChatAckDto
import top.yeij.cyrene.data.api.dto.ChatRequest
import retrofit2.Response
import retrofit2.http.Body
import retrofit2.http.POST
/**
* 发送一条消息（`POST /api/v1/chat`，api-client §1 行 3）。权限 `owner|admin`。
*
* 与会话只读的 [SessionsApi]、管理面 [AdminApi] 分开：这是**写**路径，且它的失败面比只读端点
* 复杂得多（`202` / `409` / `500` / `503` 都是编排器的真实回执，不是「请求错了」），
* 放在一起会让只读端点的调用方以为错误处理是同一种。
*
* 返回原始 [Response]（而不是直接返回信封）：状态码本身是语义的一部分——
* `202` 排队 与 `409` 排队满 必须能被调用方分开，折进 `Result` 前就先丢了。
*/
interface ChatApi {
@POST("api/v1/chat")
suspend fun sendChat(@Body body: ChatRequest): Response<ApiEnvelope<ChatAckDto>>
}
app/src/main/kotlin/top/yeij/cyrene/data/api/CyreneApi.kt
+23
View File
@@ -0,0 +1,23 @@
package top.yeij.cyrene.data.api
import top.yeij.cyrene.data.api.dto.LoginRequest
import top.yeij.cyrene.data.api.dto.LoginResponse
import top.yeij.cyrene.data.api.dto.LogoutRequest
import top.yeij.cyrene.data.api.dto.LogoutResponse
import top.yeij.cyrene.data.api.dto.RefreshRequest
import top.yeij.cyrene.data.api.dto.RefreshResponse
import retrofit2.Response
import retrofit2.http.Body
import retrofit2.http.POST
interface CyreneApi {
@POST("api/v1/auth/login")
suspend fun login(@Body body: LoginRequest): Response<ApiEnvelope<LoginResponse>>
@POST("api/v1/auth/refresh")
suspend fun refresh(@Body body: RefreshRequest): Response<ApiEnvelope<RefreshResponse>>
@POST("api/v1/auth/logout")
suspend fun logout(@Body body: LogoutRequest): Response<ApiEnvelope<LogoutResponse>>
}
app/src/main/kotlin/top/yeij/cyrene/data/api/DocumentsApi.kt
+68
View File
@@ -0,0 +1,68 @@
package top.yeij.cyrene.data.api
import okhttp3.MultipartBody
import okhttp3.ResponseBody
import retrofit2.Response
import retrofit2.http.GET
import retrofit2.http.Multipart
import retrofit2.http.POST
import retrofit2.http.Part
import retrofit2.http.Path
import retrofit2.http.Streaming
import top.yeij.cyrene.data.api.dto.DocumentUploadResponse
/**
* 文档存储端点（契约 **v0.59 已发布（api-client.md §1.2「文档存储与摄取契约」）**，形状依据见 `02-前后端协同事项.md` 回执五 §一 S1）。
* 权限 `owner|admin`。与图片链路（[UploadApi] + `/api/v1/files/{name}`）**刻意分离**：
*
* | | 图片 | 文档 |
* |---|---|---|
* | 上传字段名 | `file` | `file`（同） |
* | 上限 | 5 MiB | 20 MiB（`CHAT_DOCUMENT_MAX_BYTES` 默认，**与图片上限解耦**） |
* | 读侧鉴权 | **不需要**（名字即凭据，供 `<img>`/provider 直接取） | **要 Bearer `owner|admin`** |
* | 读侧响应 | 可内联渲染 | `Content-Disposition: attachment` + `nosniff`（**永不渲染**） |
* | 成功载荷的 url | **绝对**同源地址，可直接当 `chat.image` | **相对**路径，客户端要的是 `name` |
*
* 为什么文档读侧要鉴权而图片不要：文档的摄取在**服务端**完成（正文进上下文），
* 客户端不需要把一个「名字即凭据」的读侧打开；图片则必须被 `<img>` 与 provider 直接消费。
*
* ## 鉴权拦截器这一侧没问题的依据
* Bearer 不是按接口挂的，而是**按 OkHttpClient** 挂的：[ApiClientFactory.create] 给每个
* 客户端都装了 `AuthInterceptor`（`Authorization: Bearer <token>` + 401 单飞续期），
* 因此只要 [DocumentRepository] 拿到的 `DocumentsApi` 是从 `ApiClientFactory.create` 建的
* （`AppContainer` 里照 [UploadApi] 的写法），**两个端点都自带 Bearer**，不需要额外加头。
*/
interface DocumentsApi {
/**
* 上传一份文档。
*
* @param file **部件名必须是 `file`**（服务端 `r.FormFile("file")`）；**文件名必须带扩展名**，
* 且该扩展名要落在服务端的 deny-by-default 白名单里——与图片不同，这里的名字
* **真的参与裁决**（白名单扩展名 + 字节嗅探**合取**，两者都过才放行）。
* 服务端随后丢弃该名字，按内容寻址重命名为 `<sha256[:32]><ext>`，所以名字里
* 除了扩展名以外的内容不会被采用（也不会进路径）。
*
* 返回原始 [Response]：**`200` 不是错误**——同一份字节重复上传回 `200` + 同一个 `name` +
* `deduped:true`，客户端必须当成功。状态码本身不承载额外语义（`413`/`415` 的区分在
* `error.code` 里），所以仓库层可以直接走 [apiCall]。
*/
@Multipart
@POST("api/v1/documents")
suspend fun upload(@Part file: MultipartBody.Part): Response<ApiEnvelope<DocumentUploadResponse>>
/**
* 取回一份文档的原始字节。
*
* 它**不是信封**（响应体就是文件本身），所以返回 [ResponseBody]：解码器只处理
* `application/json`，这里必须自己读字节并在仓库层负责关闭。
* [Streaming] 让 Retrofit 不把响应体一次性读进内存（单份最大 20 MiB，边界情况不小）。
*
* @param name 服务端存储名（`<32hex>.<ext>`）。形态非法 / 不存在服务端都回
* `404 document_not_found`（不区分「非法」与「没有」），因此这里不做本地形态校验、
* 也不拿它拼任何本地路径。
*/
@Streaming
@GET("api/v1/documents/{name}")
suspend fun download(@Path("name") name: String): Response<ResponseBody>
}
app/src/main/kotlin/top/yeij/cyrene/data/api/MetaApi.kt
+16
View File
@@ -0,0 +1,16 @@
package top.yeij.cyrene.data.api
import top.yeij.cyrene.data.api.dto.EnumTableDto
import retrofit2.Response
import retrofit2.http.GET
/**
* 共享枚举权威表端点（api-client §1.1 / api-reference §3.7）。
* 任意已认证角色可读（与 `GET /sessions` 同级），无 token 回 `401`；
* 纯内存投影，没有其它错误码。按本工程惯例单独成接口。
*/
interface MetaApi {
@GET("api/v1/meta/enums")
suspend fun enums(): Response<ApiEnvelope<EnumTableDto>>
}
Loaded 100 of 345 files, more files were not shown because too many files have changed in this diff. Show more