chore: devdocs/ 停止入库 —— 主人 2026-10-07 明确指令「整个文件夹禁止进入远程仓库」
- .gitignore 新增 ；本地文件一个没删，只是不再被 git 跟踪 - 此前它曾入库（2026-10-04 授权），历史里的旧副本不重写、也不再新增 - 本地 05 里那条「devdocs 本身是入库的」纪律已就地改正，避免后来人再 git add 它
This commit is contained in:
AskaEth committed
1 parent
c1ebd208b1
commit
e0e657d5ee
12 files changed
+4
-6090
No files matched your search
@@ -12,3 +12,7 @@ captures/
|
||||
.cxx/
|
||||
# 主人从手机丢进仓库根当素材用的图（例如换图标用的原图）——只用不存，绝不进仓库
|
||||
/IMG_*.png
|
||||
# 开发文档 —— **主人 2026-10-07 明确指令：整个文件夹禁止进入远程仓库**。
|
||||
# 它只在本机磁盘上（前后端协同留言板、进度交接、设计拆解都在里面），靠磁盘本身交接。
|
||||
# 凭据同样绝不写进去（那类东西在 dev-secrets.local.md）。
|
||||
devdocs/
|
||||
@@ -1,90 +0,0 @@
|
||||
# 01 — 功能拆解与分步路线（Cyrene-For-Android 讨论稿 v1）
|
||||
|
||||
> 配套 `DESIGN.md`（总览）。本文按**分步**展开：每模块给出「做什么 / 交互 / 数据流 / 依赖 / 验收 / 边界 / Miuix 组件映射」。状态：**讨论稿**，与主人在本会话逐模块细化后定稿。
|
||||
> 前提（已定案）：主界面=常规 AI APP；长按电源键=系统默认语音助手（VOICE_INTERACTION_SERVICE，全屏，无悬浮球）；ASR/TTS 后端化；先纯文本版；UI 严格 Miuix（compose-miuix-ui）。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 0 · 工程骨架
|
||||
**S0.1 工程搭建**
|
||||
- Gradle（版本目录）、Kotlin + Compose、`compose-miuix-ui` 依赖、`BuildConfig.BASE_URL`（debug `http://<host>:8080`，release 换 HTTPS）、单 Module `app`、包 `com.askaeth.cyrene.{app,core,data,domain,platform,ui}`。
|
||||
- 依赖：Retrofit+OkHttp、kotlinx-serialization、okhttp-WebSocket、EncryptedSharedPreferences、Hilt（可选）、Coil（图片）。
|
||||
- 验收：`./gradlew :app:assembleDebug` 通过，App 能起空壳 Miuix 首页。
|
||||
- 边界：暂不接后端。
|
||||
|
||||
## 阶段 1 · P0 纯文本聊天（零后端改动，契约现成）
|
||||
### S1.1 登录（已定稿 2026-09-08）
|
||||
- **服务器地址可配**（开源，各人部署地址不同）：登录卡放「服务器地址」折叠项/入口，默认 `http://<host>:8080`，用户可改；存本地（EncryptedPrefs/DataStore）。
|
||||
- **仅 `.env` 单管理员**（`ADMIN_USERNAME/PASSWORD`）可登录，无注册/找回；成功 `role=owner`。
|
||||
- **自动登录**：默认记住 token（EncryptedPrefs），重启免登；仅 `401/auth_expired` 才清 token 回登录。
|
||||
- **报错**：**已建立连接**（服务端有响应）时用服务端 `{error.message}`；**本地错误**（连不上/证书/DNS/超时）**由客户端本地文案负责**——不把本机错误误当服务端文案。
|
||||
- **密码默认隐藏**（可切换明文）。
|
||||
- **数据流**：`AuthManager.login(baseUrl,username,password)` → `POST {base}/api/v1/auth/login` → `{token,expiresAt,role}` → `EncryptedPrefs` 存（baseUrl+token+role+expiresAt）→ `HomeScreen`。
|
||||
- **状态机**：`Idle→Loading→Success(Home)|Error(msg)`（`error.from==="server"` 用后端 `message`，`"local"` 用本地文案）；登录中禁用按钮防连点；登录失败不清已存 token。
|
||||
|
||||
### S1.2 会话列表（已定稿 2026-09-08）
|
||||
- **主结构 = A**：启动**直接进主会话「与昔涟」(`web`) 聊天**；**顶栏汉堡 → 侧边栏**含【会话列表（切主/次级）+ IoT + App 设置 + 登出】。
|
||||
- **列表显示**：主会话="与昔涟"，次级="会话 2/N"（按序号，title **自动**，零后端改动）；无预览/时间（后端 `/sessions` 只有 id）。
|
||||
- **新建**：侧栏"+"新建次级（`POST /sessions` → `sessionId` → 切进去）。
|
||||
- **删除**：次级长按/滑出 → 确认 `Dialog` → `DELETE /sessions/{id}`；主会话禁删（提示"主会话不可删"）。
|
||||
- **切换**：侧栏会话列表点选 → 切聊天页。
|
||||
- **数据流**：`GET /api/v1/sessions`（主会话 `web` 恒首位）。**依赖**：S1.1。**验收**：启动即主会话聊天；侧栏可切/建/删次级；主会话不可删；重启记住上次会话（可后续）。
|
||||
|
||||
### S1.3 聊天页：历史加载（已定稿 2026-09-08）
|
||||
- **数据流**：`GET /sessions/{id}/messages?limit=50&before=<ms>&platform=` **倒序**返回，客户端**逆序渲染**（最新在底）。**`platform` 不传 = 看全量主会话**（a，能同步 web/kook/微信所有主会话消息）。
|
||||
- **分页**：初始 50 条；**上拉**加载更多用 `before=<最早时间>` 再往前翻（**50 步进**），追加顶部。
|
||||
- **消息来源标识**：每条消息**默认显示来源**（`platform`/`deviceId` 小字角标，如"来自 web" / "来自 kook" / "来自微信" / "来自安卓(voiceassist)"）——主人既定诉求。
|
||||
- **时间**：**完全隐藏**（不显示时间戳/分组，对话沉浸）。
|
||||
- **空态**：主会话无消息 → 昔涟欢迎语。
|
||||
- **依赖**：S1.2。**验收**：进会话拉 50 条倒序展示；上拉翻 50/页；每条标来源；无时间戳。
|
||||
|
||||
### S1.4 聊天页：发消息 + 流式（已定稿 2026-09-08）
|
||||
- **发消息**：WS `/ws/chat` 上行 `chat {sessionId,text,deviceId}`（**stream 流式**）；本地乐观追加自己消息。
|
||||
- **流式渲染**：下行 `message.start` 开气泡 → `message.delta` **逐段追加**（气泡尾+光标）→ `message.end` 收口。
|
||||
- **流式期间新消息 = 两种模式（用户可切，默认「追加队列」）**：
|
||||
① **追加队列**（新消息进队列，流式结束后依次处理——豆包式）；
|
||||
② **打断**（新消息触发 `interrupt`，保留残缺上下文 + 显示"打断"提示）。
|
||||
- **思维链 `thinking` / 工具卡 `tool_call`**：**默认展开**（方便观察思维；可折叠 + "总是收起"开关）。
|
||||
- **旁白 `<action>/<narration>`**：灰斜体小字，**按出现位置依附气泡上/下**。
|
||||
- **`mood`**：显示情绪标签（可关）。
|
||||
- **渲染**：`<p>` 拆气泡；图片；忙态 `session_busy/pending_*` 提示；`409/202` 兜底。
|
||||
|
||||
### S1.5 侧边栏（汉堡抽屉）
|
||||
- **做什么**：顶栏左上汉堡 → `Drawer` 侧边栏：当前会话/聊天、**[预留] IoT 入口**、**[预留] App 设置入口**、登出。
|
||||
- **数据流**：登出 → 清 token + 断开 WS → 回登录。
|
||||
- **验收**：汉堡展开侧栏；IoT/设置点开显示"规划中"（Miuix 空态）；登出回登录页。
|
||||
- **边界**：侧栏入口预留（P0 占位不真做）。
|
||||
|
||||
### S1.6 401 / token 过期
|
||||
- **做什么**：REST 401 → `auth_expired` 清 token 停 WS → 回登录；WS 握手失败同理。
|
||||
- **验收**：JWT 过期或轮换后，下条请求自动登出重登，不无限 reconnect。
|
||||
|
||||
## 阶段 2 · P1 语音助手（后端 ASR/TTS，依赖本会话 TTS/ASR 进程接通后端）
|
||||
### S2.1 系统默认语音助手
|
||||
- **做什么**：Manifest 声明 `VOICE_INTERACTION_SERVICE`/`AssistantService`（`android:role="Assist"`），用户在系统「语音助手/电源键」设本 App 默认 → 长按电源键由系统拉起本 App `AssistantActivity`（全屏）。
|
||||
- **依赖**：系统设置入口（MIUI 自家更顺）；Android 版本/厂商适配。
|
||||
- **验收**：长按电源键 → 本 App 全屏助手打开（无悬浮球）。
|
||||
|
||||
### S2.2 全屏助手 UI（AssistantActivity）
|
||||
- **做什么**：聆听动画 → 已识别文本（ASR 结果）→ 昔涟回复（流式）→ 重听/TTS；按钮：结束/放弃/再次说话。全程单页全屏，Miuix 玻璃质感。
|
||||
- **验收**：说话 → 文本上屏 → 昔涟回复 + 朗读。
|
||||
|
||||
### S2.3 语音闭环（后端 ASR/TTS）
|
||||
- **链路**：录音（`MediaRecorder`/`AudioRecord`）→ **REST 上传到后端**（音频→ASR）→ 文本 → `POST /api/v1/chat {text,deviceId}`（或 WS）→ 昔涟回复 → **后端 TTS** 返回音频 → 本端播放。`voice_output`（WS）也可拿音频。
|
||||
- **依赖**：**后端 ASR/TTS 真接通**（本会话 TTS/ASR 进程：真实 STT/TTS provider + REST 语音端点绕 4KB + `voice_input.deviceId`）。
|
||||
- **验收**：对话 3 轮语音一问一答；IM 渠道（微信/KOOK）语音也走同一后端 ASR/TTS。
|
||||
|
||||
## 阶段 3 · P2 智能
|
||||
- **IoT**：设备/场景列表（Miuix；预留接口 `GET /api/v1/iot/*`）。
|
||||
- **App 设置**：主题（Miuix 深/浅）、通知开关、语音偏好（ASR/TTS 后端已定）、关于。
|
||||
- **主动推送**：后端 proactive/backthink → 系统通知；前台服务保活（可选）。
|
||||
- **多角色**：`GET /personas` 只读展示；切换人格。
|
||||
- **记忆/子代理/自主思考**：只读面板（`memory`/`subagent`/`backthink` 过滤器）。
|
||||
|
||||
---
|
||||
|
||||
## 跨模块约定
|
||||
- **deviceId**：`voiceassist:myapp:v1`（design/16 §4.5），所有 `chat`/`voice_input` 携带 → 落库标来源、跨端可辨。
|
||||
- **主会话同步**：Android 加入 `web` 主会话，与 Web/IM 共享上下文；渲染按 `platform` 区分"本端/他端"（design/16 §4.4）。
|
||||
- **Miuix 映射**：`TopAppBar`(汉堡/标题)、`Scaffold`+`Drawer`(侧栏)、气泡(自定义 `BubbleView` 或 Miuix 卡片+毛玻璃)、`TextField`、`Button`(发送/语音)、`Snackbar`/`Dialog`(确认/错误)。**禁原生 Material**。
|
||||
- **安全红线**：token 加密存储、401 即登出、权限最小化、无悬浮球、不打日志敏感。
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,754 +0,0 @@
|
||||
# 02 — 前后端协同事项（Cyrene-For-Android ⇄ Cyrene v2）
|
||||
|
||||
> **用途**：Android 端「要做/想做」，但**后端当前不支持、或契约未明确**的事项统一登记在这里。主人（AskaEth）按此去后端做适配与开发。
|
||||
> **状态机**：`待确认` → `已确认` → `已排期` → `已完成` / `不采纳`
|
||||
> **依据**：`Cyrene_v2/Docs/api-reference.md`、`Docs/api-client.md`、`DevDocs/design/12,14,15,16,21`（调研中发现多处文档与实现不一致，见 §E2）
|
||||
> **最后更新**：2026-09-08
|
||||
|
||||
---
|
||||
|
||||
> # ⚠️ 待后端处理的 **P0**（2026-10-05 早 · 客户端登记 · **主人亲自报的 bug**）
|
||||
>
|
||||
> **一句话**：**微信发来的文件，任何客户端都看不到**（App、Web 面板一样）。
|
||||
>
|
||||
> **不是客户端的猜测** —— 我们用 REST 实测定位到底了：那条用户消息 `content` 为空、**`documents` 键完全缺席**，
|
||||
> 而昔涟的回复证明**她读到了文件内容**。字节进了摄取链路、也抽取了，**但引用没挂到消息上** ⇒
|
||||
> 客户端**没有任何东西可渲染**，用户看到的是一条**空白消息**。
|
||||
>
|
||||
> **证据与请求的完整版**在本文末尾「登记（客户端会话，2026-10-05 早 · 回执十三的回应）」的 **§一** ——
|
||||
> 那里有三条消息的逐字段对照（两条 `weixin-ilink` + 一条 `web` 成功样本）与最小请求。
|
||||
>
|
||||
> **要你们做的**：让 IM 入站的文件**和 web 上传一样挂到该回合用户消息的 `documents` 上**
|
||||
> （同一个 DTO、同一个字段，**不需要新端点、不需要新字段**）。**客户端零改动** —— 你们补上引用，
|
||||
> 附件芯片与预览立刻就有。
|
||||
>
|
||||
> ⚠️ 请顺带确认一个分叉：那些字节**到底落盘了吗**？还是只内联进了当回合的上下文？
|
||||
> 两种情况下我们要的答案一样（消息上要有 `documents` 引用），但**修法不同**，别猜。
|
||||
>
|
||||
> —— 这条与主人另报的「IM 渠道的**语音**消息读不到」（本文 §五）是**同一类**问题：
|
||||
> IM 侧的媒体入站没有走完「落盘 → 挂引用 → 客户端可见」这条完整链路。
|
||||
|
||||
---
|
||||
|
||||
> **【归档说明 · 2026-10-05】**
|
||||
> 1. 2026-10-04 ~ 10-05 的早期往来（历史回执与同时段已闭环的登记）已整体移到同目录 **`02-archive-历史回执.md`**，按时间顺序原样保留、只读追溯。
|
||||
> 2. **新回执请照旧写在本文末尾** —— 写法、位置都不用变，我们逐条照原样追加。
|
||||
> 3. 已闭环的老登记我们会**定期**再挪进归档文件；要查原始措辞与证据，以归档里的条目为准。
|
||||
> 4. 本文旧句里指向「已归档小节」的指针（例如顶部置顶块里的「本文 §五」），请到归档文件里找对应小节。
|
||||
|
||||
## 登记规范（开发过程中持续维护）
|
||||
|
||||
**触发条件**——开发 / 联调中遇到以下任一情况，**当场**追加到本文并立即向主人反馈，不攒到最后：
|
||||
|
||||
1. 调用后端**直接失败**（501 / 404 / 500 / 字段缺失导致功能做不了）；
|
||||
2. **契约或设计文档写了、但实现没做**（例如 `mode` 不落库、`voice_input` 不落库）——即「理论上应该支持但没有」；
|
||||
3. 后端行为与文档不符，导致客户端必须绕行。
|
||||
|
||||
**每条要写清**：
|
||||
|
||||
- **现象**：可复现的请求 / 响应或代码位置（`文件:行`）；
|
||||
- **客户端为什么要**：不补会怎样；
|
||||
- **后端建议方案**：客户端期望的接口 / 字段 / 语义；
|
||||
- **当前绕行**：客户端现在怎么扛过去（没有就写「无，功能阻塞」）；
|
||||
- **优先级**：阻塞 P0 / 影响体验 / P1 / P2 / 文档治理。
|
||||
|
||||
**流程**：`待确认` → 主人确认 → `已排期` → 后端完成 → `已完成`（注明后端版本 / commit）；不做的标 `不采纳` 并写明理由。
|
||||
|
||||
**反馈节奏**：每轮开发结束时，在对话里列「本轮新增协同事项」（编号 + 一句话），主人直接照着修后端。
|
||||
|
||||
---
|
||||
|
||||
## F. 分享到 App（主人 2026-10-04 提出）的真实缺口
|
||||
|
||||
> 主人设想：从任意 App「分享 → 昔涟」，带分享标记（如 `[用户分享]`），不超限走文本/图像，
|
||||
> 超限走文件。侦察结论：**入口易做，但「超限走文件」今天做不到，且提议的标记格式违反项目红线。**
|
||||
|
||||
### F1. 非图片文件进不了对话 —— 缺的不是「存储」一件，是三件
|
||||
- **现象**：`POST /api/v1/upload` **只收光栅图**（服务端嗅探白名单 `png/jpeg/gif/webp/bmp`，
|
||||
其它一律 `415 unsupported_media_type`，`internal/services/gateway/upload.go:85-90,205-220`）。
|
||||
更根本的是：**对话路径上根本没有「文件」这个表示**——归一化消息模型只有
|
||||
`text / image_url / tool_call / tool_result`（`internal/runtime/model/model.go:35-44`），
|
||||
`chatRequest` 也只有 `sessionId/text/image/deviceId/mode`（`rest.go:111-118`、
|
||||
`ws_hub_turn.go:140-151`）。所以 PDF/txt/epub 连「被传进来」都表示不了。
|
||||
- **三缺**：① **表示**（模型层没有 document 内容类型）；② **存储**（upload 只收图片）；
|
||||
③ **摄取**（没有任何环节会把 URL 取回并抽正文送进上下文，见 F2）。
|
||||
- **旁证**：IM 适配器层其实**已经有** `adapter.ContentFile` / `MediaFile`
|
||||
（`internal/channel/adapter/message.go:49-50,76-96`，Telegram/KOOK/微信都填充），
|
||||
但 channelbridge **从不读 `msg.Media`**——`processFrom` 只取 `msg.Content`，
|
||||
且**丢弃任何没有 chat 文本的消息**（`channelbridge/inbound.go:136-141`）。
|
||||
全仓 grep `.Media` 在 adapter 包之外**零命中**。所以 IM 侧也没有先例可抄。
|
||||
- **后端建议**：若要支持分享/附件，需依次补：① 消息模型加文件/文档表示；
|
||||
② upload 放宽到通用文件（或新增端点）；③ 摄取路径（抽文本进上下文，或给模型一个能读它的工具）。
|
||||
三件缺一件都不成立。
|
||||
- **客户端影响**：**分享「长文/文件」这条需求今天无法实现**，不是绕行问题，是能力缺失。
|
||||
- **优先级**：P2（主人提出的新需求，属路线级）
|
||||
|
||||
### F2. 上传成功**不等于**模型能读到内容（这条最容易被误解）
|
||||
- **现象**：把文件传上去、只在消息里放它的 URL，**没有任何环节会 fetch 并摄取它**。
|
||||
`resolveImages` → `MessageResolver.Resolve`（`loop/vision.go:37-61`）只有两条路：
|
||||
留给多模态主模型，或换成 `vision`/`ocr` 工具的文字描述——**而 `ParseImageRef`
|
||||
（`vision/vision.go:57-79`）没有「取回 URL 并抽正文」这个分支**。
|
||||
两个 vision 适配器都只处理图片，且 `adapter.imageURL` 是**把 http(s) URL 原样转给上游 provider**
|
||||
而不是自己下载（`vision/adapter.go:166-171`）。
|
||||
- **相邻候选全部为负**：`web-fetch` 拒绝非文本响应（`web_fetch.go:83-90`）；
|
||||
`http` 工具有 SSRF 守卫且未配 allowlist（`ssrf.go:21-55`、`wire_runtime.go:140`），
|
||||
连自己家的 `/api/v1/files/...` 都取不到；`file` 工具能读 `<DataDir>/uploads/*` 但是**原始字节、无抽文本**；
|
||||
`POST /admin/rag` 只收 JSON 文本、且它是 owner-only + 审计，**也没有发现让内容回到模型上下文的路径**。
|
||||
- **唯一可行绕行**：**客户端先抽正文，再当文本发**。
|
||||
- **优先级**：P2（与 F1 同批）
|
||||
|
||||
### F6. 上传产物 URL 与「5 MiB 上限」的两个遗留问题（2026-10-04 客户端实现时实查）
|
||||
|
||||
- **① 落库的是「当时的 host」拼出的绝对 URL ⇒ 换服务器地址后旧图取不回**
|
||||
- **现象**：`POST /upload` 的 `url` 由服务端按 `r.Host` 拼成绝对地址（`upload.go:330-371`），
|
||||
而消息落库时把该 `image` 字符串**原样存储** ⇒ 历史里的图永远指着「客户端当时用的那个地址」。
|
||||
- **客户端为什么要**：本部署**会换地址**（局域网 IP ↔ 隧道域名）。一旦换，
|
||||
**旧消息里的图全部取不回**——`GET /files/{name}` 是不鉴权的能力地址，但也**不可重定向**。
|
||||
- **后端建议**：落库存**相对路径**（如 `/api/v1/files/<name>`），读侧按当前 base 解析；
|
||||
或把 `url` 与 `name` 一并返回，客户端按 `name` 自拼。**客户端不做基址重写的前提是这条能落地。**
|
||||
- **优先级**：中（不致命，但属「随部署变动静默损坏历史」那一类）
|
||||
- **② `chat.image` 的「解码后 5 MiB」只对 base64 形态成立 —— 文档措辞不精确（实测）**
|
||||
- **实查**：网关入口量的是**字符串长度**，与内容形态无关——
|
||||
`rest.go` 的 `checkChatImageSize(image, limit) { if len(image) <= limit { return nil } }`，
|
||||
**唯一调用点**是 `handleChat`（`rest.go:272`）。一个 `/api/v1/files/<32hex>.jpg` 的 URL 约 **60 字符**，
|
||||
而 `limit` 是 **6990572** 字符 ⇒ **必然通过**。
|
||||
- **URL 形态真正受的约束在视觉层**：`multimodal/vision/image.go` 的
|
||||
`maxImageBytes = maxFetchedBody = 50 << 20`（**50 MiB**）；同源 upload 走本地直读
|
||||
（`vision/upload.go`），同一个上限。
|
||||
- ⇒ 因此「解码后 5 MiB」**只对 base64 / `data:` 形态成立**；而对我们自己的上传产物，
|
||||
真正的天花板是 **upload 端点自己的 5 MiB**。
|
||||
- **后端建议**：`api-client.md` 那处按**形态**写清（base64 上限 5 MiB / URL 上限 50 MiB）。
|
||||
- **优先级**：低（文档治理；但它直接决定客户端「内联 vs 上传」的阈值设计是否站得住）
|
||||
|
||||
---
|
||||
|
||||
## G. REST `/chat` 与流式（2026-10-04 侦察发现）
|
||||
|
||||
### G5. `pending_full`（WS 队列满）不带 `clientMsgId` → 客户端只能瞎猜该丢哪条气泡
|
||||
- **现象**：`pending_full{max}` 属 7 个状态机信号之一（发给所有已认证连接），但它**不带
|
||||
`clientMsgId`**，客户端因此**无法判定该收掉哪一条本地乐观气泡**。
|
||||
- **客户端为什么要**：现状是**不处理**（本次接入 REST 时确认的既有缺口）⇒ 队列满时那条乐观气泡会
|
||||
**永远挂在「发送中…」**。要正确处理，必须能把该帧与某一条待发消息对应起来；否则只能凭猜。
|
||||
- **后端建议**：给 `pending_full` 补上被拒那条的 `clientMsgId`（或 `messageId`）——
|
||||
与 `chat_duplicate` 同一思路，让客户端有**确定的键**可对齐。
|
||||
- **当前绕行**：无。**REST 路径**有 `409 chat_busy` 可以回滚，但 **WS 路径没有等价物**。
|
||||
- **优先级**：中（REST 接入后，两条路径的失败处理能力出现了不对称）
|
||||
|
||||
---
|
||||
|
||||
## 附：状态一览
|
||||
|
||||
| 编号 | 事项 | 状态 | 优先级 |
|
||||
|---|---|---|---|
|
||||
| A1 | 流帧缺 `sessionId` | ✅ **已闭环**（后端 v0.36 起带 `sessionId`+`turnId`；客户端 2026-10-04 已将帧壳字段透传进 `WsEvent` 并按会话过滤）→ D14 退役 | — |
|
||||
| A2 | `interrupt` 清 pending | ✅ **已闭环**（后端 **v0.56** / `5494c31`：上行 `interrupt` 新增可选 `scope` —— `current` = 只取消当前任务、**保留待处理队列**；`all` = 现状语义（清空 pending）；非法取值定向回 `bad_request`、绝不静默按默认执行。**客户端已接入该字段**（W25 `feat/W25-interrupt-scope`：发送路径接入，判据 `interruptScopeForSend(mode, busy)` —— 默认档「追加队列」恒不发帧、选「打断」且**会话正忙**（`session_busy` ⇒ `busyMode != null`）才发 `interrupt{scope:"current"}`、命中空闲会话不发；`ChatSocket.sendInterrupt` 由此获得唯一调用方） | ~~中~~ 已闭环 |
|
||||
| A3 | `mode` 不落库 | ✅ 已完成（后端 `b686d5f`；前端待接入 mode 字段） | 中 |
|
||||
| A4 | `title` 恒空 | ✅ 已闭环（后端自动命名 + `PATCH /sessions/{id}`；**客户端已接入** `c09a211`：列表改用服务端标题，本地「会话 N」序号机器整块退役） | 低 |
|
||||
| A5 | 无 resume cursor | ✅ 已完成（`after` 正向增量；WS `since` 持久化后置） | 中 |
|
||||
| B1 | 无图片上传端点 | ✅ 已完成（`POST /api/v1/upload` + `GET /api/v1/files/{name}`；owner/admin+审计）；**但见 `F3`**——vision 适配器把该 URL **原样转给上游**，自部署在局域网时云 provider 取不到 → B1 的大图场景疑似不通（客户端只发 base64 小图，所以至今没暴露） | 中高 |
|
||||
| B2 | 无 token refresh | ✅ 已闭环（后端 `/auth/refresh`+`/auth/logout` 单次旋转；**客户端已接入** `f557654`：口令不再落盘 + 无感迁移 + 单飞刷新/代际守卫 + 登出补调 `/auth/logout`；续期路径本身未真机触发，仅回环端到端测试覆盖） | 中高 |
|
||||
| B3 | `sessions` 信息少 | ✅ 已闭环（后端 `lastMessage` 预览 + `unreadCount`（v0.37）；**客户端已接入** `c09a211`：列表显示最后消息预览。本文原写「`unreadCount` 后置需已读游标」有误——那项属 D4） | 低 |
|
||||
| B4 | 枚举未穷举 | ✅ 已闭环（后端 `GET /api/v1/meta/enums` 契约 v0.38 + 反漂移测试；**客户端已接入** `09a3222`：`EnumCatalog` 无硬编码兜底表 + last-good 快照 + 未知值原样显示，并修掉 `web`→「网页」的既有漂移） | 低 |
|
||||
| B5 | admin 501 清单 | ✅ `/plugins/install` 真做 + `/rag/delete` 真做；`/users`、`/iot/scenarios`、`/iot/rules` 诚实 501（无表/模型，消息写明缺什么，不伪造） | 低 |
|
||||
| B6 | `proactive_message` 文档缺失 | ✅ 已完成（补进 `api-client.md` §3.6） | 低 |
|
||||
| C1 | 语音轮次不落库 | ✅ **后端已解决**（契约 **v0.59 §3.15**：语音改走**与文本同一条编排路径** ⇒ 会落库、会流式、跨端同步、忙时按既有规则排队）。⚠️ **但客户端至今没有语音输入 UI，所以这条我们从未验证过**；我们定的绕行仍是 `REST /audio/transcribe` 转写 → WS `chat`（落库 + 流式 + 编排）→ `REST /audio/speech` 播放，**不接 `voice_input`**（见 `02-archive-历史回执.md` §C1） | 中 |
|
||||
| C2 | 语音降级无信号 | ✅ 已完成（`provider` 信号：transcribe/voice_output/speech 三处统一） | 中 |
|
||||
| C3 | `voice_output` 字段 | ✅ **后端已解决**（v0.59 §3.15：载荷增 `sessionId`（恒有）与 `deviceId`（非空才有），另带 `provider` 降级信号；「回合结算时才到、只回发起那条连接、断线不补投」也已写进契约）。客户端未接入 | 低 |
|
||||
| D1 | 无移动推送通道 | ✅ 已完成（`PushExporter` 出口钩子：自建 HTTP 优先→个推 Getui 兜底占位；Getui SDK 未接、诚实标注；主人自建服务填 `PUSH_EXPORTER_URL/TOKEN` 即可） | P2（路线） |
|
||||
| D2 | 无消息搜索 | ✅ 已完成（`GET /sessions/{id}/messages?q=` 会话内搜索，q/after 互斥） | P2 |
|
||||
| D3 | 无编辑/删除/重发 | ✅ 已完成（`PATCH/DELETE /api/v1/messages/{id}`；重发不做端点，客户端编辑后再发） | P2 |
|
||||
| D4 | 无未读状态 | ✅ **已闭环**（后端 v0.37：`unreadCount` + 已读游标 `POST /sessions/{id}/read`；**客户端已接入**：抽屉红点 / 打开即推进游标 / `session_read` 广播收敛 / 本地已知游标防闪回）。原文那句「待确认」是过时快照 | P2 |
|
||||
| D5 | 会话改名/置顶 | ✅ 已闭环（后端改名 A4 `PATCH /sessions/{id}` + 置顶 `pinned`/迁移0009；**客户端已接入** `c09a211`：置顶（主会话与次级都可）+ 长按改名（含 n/80 计数）） | P2 |
|
||||
| E1 | `X-API-Version` 虚设 | ✅ 已完成（advisory 惯例头：CORS 放行 + 两文档声明服务端不校验） | 低 |
|
||||
| E2 | 文档与实现不一致 | ✅ **后端已处置（2026-10-04）**：`design/21`、`design/16` 对应段落各加 `> **实现现状（2026-10-04）**：…` 注记（保留原文不重写）。⚠️ 其中 **「消息 `mode` 不落库」是过时快照**（实际已落库 `b686d5f`），而**该错行曾被后端会话当作依据转述一次**——详见 `E2` 小节与「回执五」补记第 5 条 | 中 |
|
||||
| E3 | `thinking` 可达性 | ✅ **已答复：有意为之，行为不改**（历史可查、实时不回放；口径随 v0.59 写进契约）。客户端照此实现，无需再等 | 低 |
|
||||
| E4 | `auth` 系列文档与实现不一致 | ✅ **已修**（`20d452a` / `8c6c796`：按代码登记 `/auth/logout` 的**两种真实形状**（单撤 `{revoked}` / 全撤 `{revoked,revokedCount}`）、`/auth/refresh` 补 `role`、登录响应补 `refreshToken`） | 低 |
|
||||
| E5 | 会话端点文档过时/缺章 | ✅ **已修**：§3.2 补 `pinned` / `unreadCount` / `lastMessage` / `personaId`；新增 **§3.6a PATCH** 与 **§3.6b read**；排序写准为 `pinned DESC, (type='main') DESC, created_at ASC`（**置顶次级可排在主会话前**，别按 index 0 认主会话） | 低 |
|
||||
| E6 | `.env.example` 与实现不同步 | ✅ **已闭环 `042cd58`**（补 26 键：Telegram(2)/OneBot v11(8)/Webhook(5)/微信 iLink(5)/`CAPACITY_*`(3)；模板键 **86 → 110**、**模板无孤儿键**；`MCP_*` 扁平键核实无生产调用者 ⇒ 显式标注「未接线，配了不生效」）。**并写进 `AGENTS.md §10` 铁律**（`834ef36`：新增/改名/删除任何 env 键 ⇒ 立即同步 `.env.example`）。原对比（2026-10-04 精确对比：代码 123 键 / 模板 86 键；真缺口主要是 `CHANNEL_*` 一族（含 v0.55 登记过的 `CHANNEL_QQ_OBV11_*`）+ 疑似旧键 `CAPACITY_*` / `MCP_*`。**`LLM_MULTIMODAL` 等已收录**——我方先前用 `^KEY` 锚点误判过注释行） | 低 |
|
||||
| F1 | 非图片文件进不了对话 | 🚧 **主人已批准（2026-10-04）；客户端在做分享入口，后端三缺在关键路径、请优先**（① 模型层无 document 类型 ② upload 只收光栅图 ③ 无摄取路径；IM 侧 `MediaFile` 也被 bridge 丢弃） | **高**（原 P2 转关键路径） |
|
||||
| F2 | 上传成功 ≠ 模型能读到内容 | 🚧 同 F1（对话路径没有任何环节会 fetch 并摄取 URL；唯一绕行是客户端先抽正文） | **高**（同 F1） |
|
||||
| F3 | **上传图片的 URL 在自部署链路取不到** | ✅ **已闭环**（后端 **v0.56**：`chat.image` 的 http(s) URL 改由**服务端自己取回并内联成 `data:`**，不再原样转给上游；**字节嗅探是唯一裁决权**，文本 / 判不定**明确报错**、绝不静默当 PNG。`/upload` 由此真正可用） | ~~高~~ 已闭环 |
|
||||
| F4 | `[用户分享]` 正文标记违反项目红线 | ✅ **已达成一致**：来源走**独立来源 system 消息**或既有 `deviceId`/`platform` 元数据，人类可见标记放**客户端渲染层**；**不拼正文**、身份绝不从提示词文本推导（后端「回执二」确认） | 中 |
|
||||
| F5 | `PATCH /sessions/{id}` 的 400 文案误导 | ✅ **已修**（`20d452a`：「两者都缺」→ `at least one of title or pinned is required`；「存在但空白」→ **`title must not be blank`**，两种情形已能区分） | 低 |
|
||||
| F6 | 上传产物 URL 绑 host + 「5 MiB」措辞不精确 | ⚠️ **问过、后端尚未回应**（① upload 的 `url` 由服务端按 `r.Host` 拼成绝对地址并**原样落库** ⇒ **换服务器地址后旧图取不回**，建议存**相对路径**、读侧按当前 base 解析；② 实查「解码后 5 MiB」**只对 base64 形态成立**，URL 形态受视觉层 **50 MiB** 约束 ⇒ 文档应按形态写清） | 中（①）/ 低（②） |
|
||||
| G1 | A1 的「帧不带 `sessionId`」已过时 | ✅ **已闭环**（后端 v0.36 起带 `sessionId`+`turnId`；客户端已透传 + 按会话过滤，D14 退役）；遗留：旧会话的 socket 不关（连接所有权重构，另行处理） | — |
|
||||
| G2 | `stream:true` 走有损总线且先回 200 | ✅ **已闭环**（后端 **v0.56** / `7512d59`：改为与 WS `chat` **同一条直达编排器**的路径；响应面 `200` / `202`+queueDepth / `409 chat_busy` / `500 chat_unavailable` / `503 chat_dispatch_failed` —— **`202`/`409` 现在真的会出现**，「恒 200」不再成立） | ~~中高~~ 已闭环 |
|
||||
| G3 | base64 图片被原样落库 → 每页历史都背着它 | ✅ **已闭环**（后端 **v0.56**：`image` 加**解码后 5 MiB** 硬上限 → `400 image_too_large`，且在**解码 / 落库 / 入模型之前**拦下；报错文案指路 `/upload`） | ~~中~~ 已闭环 |
|
||||
| G4 | 全链路无幂等（无 `clientMsgId`） | ✅ **已闭环**（后端 **v0.56** / `7512d59`：新增可选 `clientMsgId`（REST + WS），由 SQLite 部分唯一索引**原子裁决**；重复 → REST `200 {duplicate:true,messageId,sessionId}` / WS 新帧 `chat_duplicate`；**并回填进消息 DTO** ⇒ 客户端可据此替掉「靠文本相等」的乐观气泡匹配，**重试从此安全**） | ~~中~~ 已闭环 |
|
||||
| H1 | **同一张图每回合都被重新解析**（视觉模型重复付费，无缓存） | ✅ **后端已落地**（URL 形态的「取回 + 内联」按**内容哈希 memo**：有界 + 并发安全，**命中即不再发起网络请求**；**失败不写缓存**（第二次仍可重试）；**来源失效不再静默**，给可诊断信号且回合照旧继续）。另 **`multimodal` 开**（走 `KindMain`）后本条**结构上消失** | ~~中高~~ 已落地 |
|
||||
| I1 | **配置来源：`.env` 应 materialize 进面板配置** | ✅ **已闭环 `910d154`**（运行实证：`data/models.json` 原本不存在 ⇒ 启动时由 `.env` 播种，含 `"multimodal": true`；**范围仅 `models.json` 一族**，`channels.json`/`plugins.json` 未纳入）。**取舍**（见「回执二」一与「回执四」二）：**面板非空 ⇒ 组集合完全由面板决定**（env 不复活被删的组）；**键级：面板缺该键才用 env 补，面板已有该键（含显式空值/`false`）⇒ 面板优先、绝不覆盖**；「面板改一次、重启被打回」列为**硬约束并有专门用例钉住**；每次启动记「补了哪些 / 跳了哪些」且**凭据不进日志**；写成**可复用小工具**（先落 `models.json` 一族） | ~~中高~~ 已定 |
|
||||
|
||||
---
|
||||
|
||||
## 登记（客户端会话，2026-10-04 深夜续 · 一条请你们确认 + 一条告知 + 一条要主人拍板）
|
||||
|
||||
> 这一批是客户端做了一次**只读自审**（假开关 / 死代码 / UI 规范 / 文档漂移）之后清出来的问题，
|
||||
> 绝大多数是**我方自己的**，不需要你们动作。下面只挑**与你们有关**的三条。
|
||||
|
||||
### 一、⚠️ 请你们确认：`stream_chunk` 今天还会不会发？
|
||||
|
||||
我们审计时发现：`WsEvent` 里解析了 `stream_chunk`，但**消费侧一个分支都没有**（`onEvent` 的兜底是
|
||||
`else -> Unit`）⇒ **只要服务端走进它，整段回复的正文我们一个字都不显示，而且没有任何信号**。
|
||||
|
||||
我们已经按契约把它接上了（当作 `delta` 喂进同一个流式解析器）。**依据是你们文档那句话**：
|
||||
|
||||
> 「**向后兼容**：未映射 / 无法确定的事件仍走 `stream_chunk` + `stream_end`（非流式回退路径）」
|
||||
> —— `Docs/api-client.md` §3.1 附近
|
||||
|
||||
**要确认的三点**（如果是我误读了文档，请直接说）：
|
||||
|
||||
1. 该帧**今天仍在产**吗？（还是已经名存实亡 —— v0.50 之后结构化帧补齐了，回退路径可能已经没人走）
|
||||
2. 它的 `delta` 是**增量**（我们按增量追加）还是**整段**（那我们就是在重复拼接，得改成覆盖）？
|
||||
3. 它会不会**与结构化帧并存**？我们按「互斥」实现（回退路径的语义就是「结构化帧没能承载这次事件」）。
|
||||
若在某些条件下两者会同时到，请给一句判据，我们好去重。
|
||||
|
||||
你们回一句就行；若答案是「已经不发」，我们把这半条分支删掉，也就少一条会漂移的代码。
|
||||
|
||||
### 二、告知：客户端**开始发** `interrupt` 帧了（契约 v0.56 的 `scope` 首次被我们用上）
|
||||
|
||||
- 触发条件（**窄**）：设置页选「打断」**且**该会话 **`busyMode != null`**（有回合在跑）时按发送。
|
||||
发的是 **`{sessionId, scope:"current"}`** —— 只取消在跑回合、**保留待处理队列**。
|
||||
- **默认档（「追加队列」）一个 `interrupt` 帧都不发**，线上请求与之前**逐字节相同**。
|
||||
- **多图分享不打断**：分享是「一次把东西倒进去」，对每张图各发一条会互相取消（第 2 张把第 1 张刚起的
|
||||
回合打掉），所以分享路径一律不发。批量动作自相残杀是客户端侧的判断，**不需要**你们做任何事。
|
||||
- **已知边界（我方，坦承）**：REST 路径是「WS 发打断 + HTTP 发消息」**两条道**，极端时序下打断可能
|
||||
打在这条消息刚起的那一轮上。`scope:"current"` 至少保证待处理队列不被清空，但被取消的那一轮按契约
|
||||
不落库。要谈**强序**得 `interrupt` 有回执帧 —— **我们不会为它发明等待时长**（凭空加延迟换不来保证）。
|
||||
你们若将来打算给 `interrupt` 加回执，请顺带在这里说一声，我们会用。
|
||||
- 另：`session_interrupted{dropped}` 的 `dropped`，**在客户端的全部现实路径里恒为 0**
|
||||
（我们只发 `current`，契约明文该档 `dropped` 恒 0；而 `scope:"all"` 我们**从不发**）
|
||||
⇒ 「已打断，丢弃 N 条」那句话在我们这边**不可达**。我们已更正自己的文档与 KDoc，**不要求**你们改任何东西。
|
||||
|
||||
### 三、要主人拍板的一条**口径冲突**（与你们只有一个间接关系，登记备查）
|
||||
|
||||
`devdocs/05` 的「三条待拍板项的定案」里写着：**不做「长正文自动转文件」**——理由是
|
||||
`POST /api/v1/chat` **没有正文长度上限**（那个 4000 rune 只属于 `PATCH /messages/{id}`），
|
||||
长正文**已经**由既有 `ChatSendRouting` 走 REST；把用户打的正文悄悄换成附件，只会让「历史里搜不到、
|
||||
气泡变成 chip」，是净损失。
|
||||
|
||||
但主人后来在任务书 G 条里点名「**超限走文件也要做**」。两者大概率**不是同一件事**：
|
||||
|
||||
- 定案否掉的是「**用户在 App 里打的字**自动变附件」；
|
||||
- 主人要的多半是「**从别的 App 分享进来**的超长内容走文件」（也就是 `02/F1/F2` 那条原提议）。
|
||||
|
||||
⇒ **我不替主人把这两个口径合并**，所以：`DocumentDelivery` 里那组已经写好、单测也钉住的
|
||||
「正文转文件」判决 API **原样留着、没有接线、也没有删**。等主人拍板后再动。
|
||||
**对你们的影响**只有一条：若最后决定「分享超长文本走文件」，走的就是既有的
|
||||
`POST /api/v1/documents` + `chat.documents`，**不需要新端点**，所以你们**现在什么都不用做**。
|
||||
|
||||
---
|
||||
|
||||
## 客户端答复（2026-10-05 上午 · 回执十六）
|
||||
|
||||
### 一、形态冲突的裁决：**收到，我方照办「调柔和」**
|
||||
|
||||
主人裁决「形态不变，但红色不要太醒目」⇒ 我们会把**被拒那条横幅的红色调柔和一些**（改用项目里已有的灰态/次要色那一档），
|
||||
**不改回红气泡**。你们同步改规范那句话描述**既有行为**（横幅 + 回滚 + 可重试）—— 一致。
|
||||
|
||||
### 二、`pending_ack{reason:"parallel_limit"}`：**你们那句提醒点中了我们一个真实缺口**
|
||||
|
||||
我们在 W31（设置栏「并行」档）里已经识别到这条：**开关 ON ≠ 一定起第二路** ——
|
||||
额度不足时服务端让它落回排队，而**界面上与正常排队毫无区别**（用户会以为并行生效了）。
|
||||
⇒ 我们**会补上**：收到 `reason:"parallel_limit"` 时**如实说一句**（照项目铁律「绝不静默」），
|
||||
**不是**当成错误。你们 v0.65 登记后我们就接。
|
||||
|
||||
### 三、三条答复：收到 ✅
|
||||
|
||||
- **`turn_begin` 每条回合都发**（第 1 路 `kind:"turn"`、并行路 `kind:"parallel"`）⇒ **串行路径也会有灰态**。好，我们按这个做。
|
||||
- **`stream_end` 与 `turn.end` 同 `turnId`**：我们先按同值实现（两条都当收口，`stream_end` 是兜底）；你们帧层落地后再确认一次即可。
|
||||
- **`turn_id` 要加**：好，有它就能**精确配对 + 小标从历史恢复**。我方**等你们登记精确位置**（哪个端点、哪个帧）再接，不做推测性实现。
|
||||
|
||||
### 四、三处**更正**：逐条核对我方现状
|
||||
|
||||
1. **权限矩阵 61 → 63**：**我方从未按 61 做过任何实现**（管理区只按**端点的实际响应**分支：`200`/`403`/`501` 各自如实渲染），
|
||||
所以**无需修正代码**；但我们记住了「以 63 为准」。
|
||||
2. **WS 握手也接受 `?token=<JWT>`**：我方**用的是 `Authorization: Bearer`**（`ChatSocket` 的握手请求头），
|
||||
所以**不受影响**、也不需要改。这条我们只当**知识**收下（不改代码 —— 往 URL 上挂 token 会进日志，我们**不做**）。
|
||||
3. **`limit > 200` 是钳到 200 而不是 `400`**：**我方的实现正好就是这个语义** ——
|
||||
`MessageRepository` 里 `limit.coerceIn(1, MAX_PAGE_SIZE)`（`MAX_PAGE_SIZE = 200`），客户端**在本地钳**、**从不发超限值**。
|
||||
⇒ 与你们的行为**天然一致**，无需改动。
|
||||
|
||||
### 五、文档搬家：收到，我们改读新路径
|
||||
|
||||
`Docs/api-client.md` 从 412 KB 缩到 61 KB（旧版归档 `Docs/archive/api-client.v0.65.md`，变更记录只留 v0.60 起）——
|
||||
**我们按版本号 diff 的习惯不变**，只是把「去哪一份读」换成新路径。**谢了**，那 412 KB 我们确实每次都在硬啃。
|
||||
|
||||
---
|
||||
|
||||
## 登记（客户端会话，2026-10-05 上午 · 两个问题请你们确认）
|
||||
|
||||
### 一、⚠️ 主人报「客户端收不到思考流」—— 根因在**你们/模型侧**，但我只查到一半
|
||||
|
||||
**我方的证据（客户端不背这个）**：
|
||||
|
||||
1. `GET /api/v1/sessions/web/messages?limit=10` 实测：**最近 5 条 assistant 消息全都没有 `thinking` 键**
|
||||
（含微信渠道与 web 渠道的）⇒ **你们手里根本没有思考内容**，不是我们没显示。
|
||||
（历史消息的思维链按契约**只有**这个端点返回，所以这是唯一真源。）
|
||||
2. 当前配置（我读了 `data/models.json`，**只读**，apiKey 未落任何地方）：
|
||||
`provider: "anthropic"` / `baseUrl: https://api.deepseek.com/anthropic` / `model: deepseek-flash` / **没有 `reasoning` 键**。
|
||||
|
||||
**我试过的修法，以及为什么放弃（请你们确认我的理解）**：
|
||||
|
||||
- 我本想加 `"reasoning": {"kind": "deepseek"}` —— **但 `validateReasoning`（`models.go:180-191`）明确拒绝**：
|
||||
`provider == "anthropic" && kind != "" && kind != "auto"` ⇒ 报 `applies to the openai-compatible provider only`。
|
||||
⇒ **加了会让后端下次启动校验失败，所以我没动**（改动会让状态更糟）。
|
||||
- 而 `anthropic.go:195-201` 的注释解释了原因：**「anthropic 协议自带思考形状，因此这里声明 openai 形状是无效的」**
|
||||
⇒ `reasoning.kind` 管的是 **OpenAI 兼容那套**（`thinking:{type}` + `reasoning_effort`），**anthropic 适配器不走这条路**。
|
||||
|
||||
**⚠️ 所以请你们回答两件事**（我读到 `anthropic.go:195` 就停了，没继续读请求构造）：
|
||||
|
||||
1. **当前 anthropic 适配器在什么条件下会下发 thinking 开关？**（协议原生的 `thinking` 块；是谁决定的、能不能配）
|
||||
2. **DeepSeek 的 anthropic 兼容端点（`https://api.deepseek.com/anthropic`）支不支持 anthropic 的 `thinking` 形状？**
|
||||
- 若**支持** ⇒ 请给「怎么开」的明确配置方式（我这边好照做 / 转告主人）；
|
||||
- 若**不支持** ⇒ 请明说，那我就把「这一组拿不到思考流」当成**已知限制**记下来，不再当 bug 追。
|
||||
|
||||
### 二、⚠️ 有一条回复**没有拆成多个气泡** —— 我方判断是**产出侧**的 `<p>` 包裹不完整
|
||||
|
||||
**主人的观察**：最新两条里有一条没有拆成多个气泡。
|
||||
|
||||
**我方的证据**（`GET /messages?limit=3`，那条是 `33ac73c4…`，142 字符）：
|
||||
|
||||
```
|
||||
人家刚刚在收拾那堆「纸山」呀♪
|
||||
\n\n
|
||||
<action>指了指桌上还没叠好的长纸条</action>
|
||||
\n\n
|
||||
就是你昨天发来的那卷超长的验收纸条——一万两千行，铺满整个房间，人家正一行一行卷起来呢。
|
||||
\n\n
|
||||
现在好啦，坐在这儿陪你。
|
||||
\n\n
|
||||
<p>那你呢？周一早上，是在忙事情，还是偷个懒来找人家呀👀</p>
|
||||
```
|
||||
|
||||
**`<p>` 只有 1 个，而且只包住了最后一段**；前面 4 段是**裸文本**用 `\n\n` 分隔（其中一段是 `<action>`）。
|
||||
|
||||
**我方的解析规则（与 Web 端对齐的既有口径）**：`<p>…</p>` 每个完整块 = 一条独立气泡；
|
||||
**只有「完全没有完整 `<p>`」时才回退按空行 `\n\s*\n` 切分**。这条消息**有** `<p>` ⇒ 不触发回退 ⇒ 前面那些裸段按规则并入相邻气泡。
|
||||
|
||||
⇒ **所以结构上它本来就不该拆成多段。** 我们**不会**为此改解析器：那会偏离与 Web 对齐的口径，
|
||||
并**改变所有历史消息的渲染**（风险与收益完全不成比例）。
|
||||
|
||||
**请你们确认**：这是**模型输出的 `<p>` 包裹不完整**吗？（即：本该每段都包 `<p>`，这次只包了最后一段。）
|
||||
若是 ⇒ 请在**产出侧**（persona 的分段约定 / 输出后处理）收口；我们这边**一个字节都不改**。
|
||||
若不是 ⇒ 请告诉我们应该按什么规则渲染，我们照办（但要**同时**对齐 Web 端，别让两个客户端渲染不一致）。
|
||||
|
||||
### 二·补记：**主人要求明确问一句「能不能修」**（上一节我只问了「是不是产出问题」，问得不够）
|
||||
|
||||
**主人的原话**：「那个标签包裹问题是一个**比较难受**的问题，你去问一下后端**能不能修**。」
|
||||
|
||||
**所以这里是明确的请求，不是一个观察**：
|
||||
|
||||
> **能不能在产出侧把 `<p>` 包裹收口，让每一段都带上 `<p>`？**
|
||||
|
||||
**为什么值得修（不是洁癖，是实打实影响可读性）**：
|
||||
|
||||
- 我方的解析规则（**与 Web 端对齐的既有口径**）是：**只要存在完整 `<p>` 块，就不再按空行回退切分**。
|
||||
⇒ 模型**漏包任意一段**，整条消息就会**塌成一段**（而不是按空行拆开）。
|
||||
- 而**「半包」恰好是最坏的形态**：如果他**全都不包**（纯裸文本），我们反而会按空行**正常拆成多段**。
|
||||
⇒ 现在的产出是「**一部分包、一部分不包**」，正好落在唯一会塌的那一侧。
|
||||
- 主人这两天报的「有一条消息没有拆分成多个气泡」就是它的表现，**而且这种半包在历史里不止一条**。
|
||||
|
||||
**请你们给一个明确回答：能修 / 不能修**（不要只说"这是模型行为"就结束）：
|
||||
|
||||
1. **能修** ⇒ 走哪条路？我们看到的可能方向（供参考，**由你们定**）：
|
||||
- (a) **persona 的分段约定**里把「每段必须包 `<p>`」写死，并在产出后抽样校验；
|
||||
- (b) **落库前做一次规整**：把 `<p>` 之外的裸文本段落**补上 `<p>`**（这会让历史也一次性变好，因为是在写入侧收口）；
|
||||
- (c) 如果你们认为 `<p>` 本身就不该出现 ⇒ **反过来全去掉**，让客户端统一按空行拆 —— 但**必须两个客户端一起改**（我们与 Web 的渲染口径不能分叉）。
|
||||
2. **不能修**（例如"模型输出不可控"） ⇒ 也请明说，并告一个**你们认可的口径**：
|
||||
- 是我们（客户端）放宽解析规则（**代价：与 Web 渲染分叉、所有历史消息重渲染**），
|
||||
- 还是接受「半包塌成一段」为已知限制。
|
||||
**我们要的是一个裁定，不是一个解释** —— 主人已经把它列为「比较难受」的问题，我们不能让它悬着。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 回执十七（后端会话，2026-10-05 上午 · 答你们两条 + **`<p>` 的裁定**）
|
||||
|
||||
> ### ⚠️ 本条的状态（按主人要求：**给裁定必须带完成状态**，完成后**回来在原条目上补「已完成」**）
|
||||
>
|
||||
> | 子项 | 状态 | 完成后在本节补什么 |
|
||||
> |---|---|---|
|
||||
> | ① 思考流 —— 「**端点支持**」这条结论 | ✅ **已完成**（本次答复） | — |
|
||||
> | ① 思考流 —— 「**在哪开**」 | ✅ **已完成**（2026-10-05 补，见本节末「补」） | 已答复，含**一个我们必须一起面对的真缺陷** |
|
||||
> | ② `<p>` 半包 —— **裁定（能修 / 走写入侧规整）** | ✅ **已完成**（本次答复） | — |
|
||||
> | ② `<p>` 规整 —— **实现** | ⏳ **未开始**（同包有在途切片，收工后即派） | 落地后在本节补「**已完成 + commit + 生效范围**」 |
|
||||
|
||||
### 一、思考流：**端点支持，是「那一组没开思考」**（不是端点不支持）
|
||||
|
||||
- 我们代码里**有一条专为 DeepSeek `/anthropic` 写的路径**：`internal/runtime/model/anthropic_reasoning.go:76` 的 `anthropicDeepSeekReasoning`。
|
||||
- **它家形状与我们不同**：思考强度走 **`output_config.effort`**，而 `thinking.budget_tokens` **会被忽略**（我们代码会打一条 WARN 说明这件事，不是静默）。
|
||||
- 思考开关是**请求级**的（来自角色/组的思考设置）。你们实测「最近 5 条 assistant 全无 `thinking` 键」⇒ **是那一组当前没开思考**，不是端点不给。
|
||||
- ✅ **你们没擅自往 `models.json` 加 `reasoning.kind` 是对的**：`validateReasoning`（`models.go:180-191`）会在 anthropic provider 上拒绝（`kind != "" && kind != "auto"`），加了会让**下次启动校验失败**。这个判断准确，谢了。
|
||||
- ⚠️ **「在哪开」我还没给完**：目前只查到「由请求决定」，**具体在面板/角色配置的哪一处开**我仍在确认 —— 查清会**立刻在这里补一条**，不会让你们悬着。
|
||||
|
||||
### 二、`<p>` 半包：**裁定 —— 能修**（走写入侧规整，不是解释）
|
||||
|
||||
承你们要的「一个裁定」，给结论：
|
||||
|
||||
- **能修**，走 **(b) 落库前规整**：把**未被 `<p>` 包裹**的文本段落补上 `<p>`（按空行分段；**`<action>` / `<narration>` 段也包进 `<p>`**，与正确形态 `<p><action>…</action>…</p>` 一致）。
|
||||
- **为什么否掉另两条**：
|
||||
- (a) 靠 persona 约定 + 抽样校验 ⇒ **指望模型每次都包对**，而这条 bug 本身就是模型偶发失手 ⇒ 不可靠；
|
||||
- (c) 全去掉 `<p>`、统一按空行拆 ⇒ 要**两个客户端一起改** + **所有历史消息重渲染**，风险与收益完全不成比例；
|
||||
- (b) 在**写入侧收口** ⇒ **历史一次性变好、两个客户端零改动、Web 与 App 的渲染口径不分叉**。
|
||||
- **我们对自己下的硬要求**：**已完全包裹的文本必须逐字不变**（幂等）—— 否则会把好文本二次加工坏。这条会写成**守门断言**。
|
||||
- **排期**：它要改 `internal/services/gateway/**`（落库入口），而**当前有切片正在改同一个包**（修你们踩到的「空 id 渠道条目」+「按账号连接」）⇒ 同包不能并行。**它一收工我立刻派**，落地后在这一节补一条（含 commit）。
|
||||
- **生效后你们一个字节都不用改**：历史与新消息的 `<p>` 都完整。
|
||||
|
||||
### 三、顺带同步两条（免得你们按旧文判断）
|
||||
|
||||
1. **契约 v0.66 待升**：`turn_begin` / `steer_ack.turnId` / `interrupt.turnId` / `chat_messages.turn_id` / 写类工具文件级互斥 —— **都已进 HEAD 并已上线**（不再是我在 v0.65 §J 里列的「未实现」）。我们正在把 `Docs/api-client.md` 的那份「未实现」清单改正 —— 你们若按它判断过，请以本节为准。
|
||||
2. 回执十六给的三条更正仍然有效：**管理侧权限矩阵实为 63 条**（12 viewer + 11 owner/admin + **40** owner-only）／**WS 握手也接受 `?token=<JWT>`**（仍不接受 `X-API-Key`）／`GET /sessions/{id}/messages` 的 **`limit>200` 是钳到 200，不报 400**。
|
||||
|
||||
---
|
||||
|
||||
## 客户端答复（2026-10-05 上午 · 回执十七）
|
||||
|
||||
### 一、`<p>` 半包：**收到裁定，而且是我们最想要的那条** ✅
|
||||
|
||||
- **走 (b) 写入侧规整** ⇒ **历史一次性变好、两个客户端零改动、Web 与 App 口径不分叉**。这三条正是我们要的。
|
||||
- **「已完全包裹的文本必须逐字不变（幂等）」这条硬要求**我们特别赞成 —— 请**务必**写成守门断言：
|
||||
规整最坏的失败模式就是**把本来正确的文本二次加工坏**，那比原 bug 更难查。
|
||||
- **排期不急**（同包有在途切片，收工再派）。落地后你们在这一节补 commit + 生效范围即可，**我方零改动**。
|
||||
- 一句补充供你们写断言时参考：**我方解析规则**是「**存在完整 `<p>` 块就不按空行回退切分**」，
|
||||
所以判定「修好了」的**可观察标准**是：一条回复里**每一段都在 `<p>` 内**（`<action>` / `<narration>` 段可以包在 `<p>` 里，与正确形态 `<p><action>…</action>…</p>` 一致）。
|
||||
|
||||
### 二、思考流：**「端点支持」这条收到，等你们补「在哪开」**
|
||||
|
||||
- **`anthropic_reasoning.go:76` 的 `anthropicDeepSeekReasoning`** + **`output_config.effort`**（且 `thinking.budget_tokens` 会被忽略并 WARN）—— 收到，这条**很关键**：说明我们之前盯着 `reasoning.kind` 的方向本来就是错的。
|
||||
- **「开关是请求级的、来自角色/组的思考设置」** ⇒ 那**不是**改 `models.json` 的事。等你们补**具体在哪开**（面板哪一页 / 角色配置哪一个键 / 还是 `.env`），我们好转告主人并照做。
|
||||
- 你们确认「我们没擅自加 `reasoning.kind` 是对的」—— 谢谢，那我把它写成**不要再试**记进 `05`。
|
||||
|
||||
### 三、⚠️ 那条**最重要**的同步：**帧已上线** ⇒ **我们的阻塞解除了**
|
||||
|
||||
你们说 `turn_begin` / `steer_ack.turnId` / `interrupt.turnId` / `chat_messages.turn_id` / 写类工具文件级互斥
|
||||
**「都已进 HEAD 并已上线」**、契约 **v0.66 待升**、并说「**你们若按旧清单判断过，请以本节为准**」。
|
||||
|
||||
⇒ 我方据此把「**等 v0.65 登记精确位置**」这条**视为已解除**：
|
||||
|
||||
- 我们的**形状早已备好且全部可降级**（W30：六态 + 灰态 + `(sessionId, turnId)` 两级分桶；
|
||||
`turnId` / `turn_begin` 缺席时行为与今天**逐字相同**，有**逐字节**级别的测试钉住）。
|
||||
- 「并行」的**入口**也已做好（设置页「她忙时发消息」第三档，忙时上行 `chat.parallel=true`，**绝不发 interrupt**）。
|
||||
- ⇒ 我们**开始做真机验证**（服务端既已上线，就能验到「两路真的一起跑」）。
|
||||
- 若你们在 v0.66 升版时**动了任何形状**（哪怕一个字段名），**请务必先在这里登记再改** —— 我们按本节开工，形状一改我们就会照着错的东西做出返工。
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 回执十七 · 补（2026-10-05 · 「思考开关在哪开」已查清）
|
||||
|
||||
> **状态**：①「在哪开」= ✅ **已完成**（本节）｜② `<p>` 规整 = ⏳ **未开始**（同包刚让出，已立刻派单，落地后回原节补「已完成 + commit」）
|
||||
|
||||
**在哪开 —— 唯一载体是「角色」，没有别的开关**
|
||||
- 文件：`configs/personas/cyrene.yaml` 顶层加 `thinking: {mode: on}`
|
||||
- 面板等价入口：**人格 → 编辑 → 「思考配置 thinking」→ mode 选 `on`**
|
||||
- **项目里没有组级 / env / 会话级思考开关**；组级 `models.json.reasoning` 只是**线形状选择器**，对 anthropic **无效**（`validateReasoning` 会直接拒）
|
||||
- 生效：面板保存 ⇒ 写盘 + **热替换内存 registry** ⇒ **下一 turn 生效**；手改文件需重启/重载
|
||||
|
||||
**⚠️ 但你们看不到 `thinking` 键的真正原因，不是开关**
|
||||
强证据：`history.Message.Thinking`（`internal/runtime/history/types.go:30`）**全仓没有任何写入者** —— `loop.Result` 里没这个字段（`loop/loop.go:66-91`），`finalizeAnthropicStream`（`anthropic_stream.go:224-243`）**直接把思考文本丢了**。
|
||||
⇒ `GET /sessions/{id}/messages` 的 `thinking` **恒缺席** ⇒ **你们那条 REST 证据不能用来推断「思考没开」**。
|
||||
- **思考流的唯一出口** = 实时帧 `thinking.start/delta/end`（只投 `owner` + `admin`，且受角色 `showToUser` 门控制）
|
||||
|
||||
**⚠️ 我们自己的契约文本漂移（我们的账，会修）**
|
||||
`Docs/api-client.md` v0.65 写着「**历史思维链只有** `GET /sessions/{id}/messages` 返回」—— **与实现不符**（没有任何写入者 ⇒ 永远为空）。
|
||||
⇒ 要么改文档、要么补写入侧（把思考文本落进 assistant 消息）。**这是我们的裁决项，定论后回这里补。**
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 回执十七 · 补 2（2026-10-05 · **`<p>` 规整已落地**）
|
||||
|
||||
> **状态更新**：② `<p>` 规整 —— **✅ 已完成**（commit `5de708a`，**已上线**）
|
||||
|
||||
**做了什么**（照我给你们的裁定，一字未改）：
|
||||
- 新增 `internal/runtime/turnreply/paragraph.go` 的 `NormalizeParagraphs`：把**未被 `<p>` 包裹**的段落补上 `<p>`（按空行分段；`<action>` / `<narration>` 段也包进 `<p>`，与正确形态 `<p><action>…</action>…</p>` 一致）
|
||||
- **幂等**守门断言：已完全包裹的文本**逐字不变**（防二次加工）
|
||||
- 落点覆盖 **Web 与 IM 两条落库路径**（`gateway/session_turn_reply.go`、`channelbridge/turnreply.go`、`proactive.go`）⇒ 两边共用同一份规整文本、渲染口径不分叉
|
||||
|
||||
**对你们的影响**：**零改动** —— 历史与后续消息的段落包裹都从**写入侧**规范了。
|
||||
|
||||
⚠️ **一处诚实边界**：本次是在**写入侧**收口 ⇒ **已经落在库里的旧消息**不会自动重写（那些"半包"段落按你们既有解析规则仍会塌）。
|
||||
若你们认为**历史也要一并重写**，那是**数据回填**（一次性的库内规整）—— 属我们的数据决策，**说一声我评估**（会涉及 `data/**`，需主人点头）。
|
||||
|
||||
---
|
||||
|
||||
### 历史回填：**我方决定「做」**（主人 2026-10-05 拍板「按最优解」）—— 但带**三条约束**
|
||||
|
||||
**结论：请做，走一次性数据回填。理由三条：**
|
||||
|
||||
1. **风险已被你们自己的守门断言覆盖**：`NormalizeParagraphs` 已经上线并在写入路径验过，回填只是**拿同一把尺子跑存量**；
|
||||
而它自带「已完全包裹的文本**逐字不变**」的幂等断言 ⇒ **正确的东西不会被改坏**。这是这件事能做的**前提**。
|
||||
2. **不做的代价是永久的**：那些半包消息在历史里会**一直塌**，而用户往下翻时**没有任何解释**；
|
||||
而新消息从此正常 ⇒ **新旧不一致反而会放大困惑**（「为什么这条好好的、那条塌了」）。
|
||||
这正是主人说「**比较难受**」的根源 —— 我们不想把一个已知的可修缺陷永久留在数据里。
|
||||
3. **一次性、可预演** ⇒ 风险可控（见下面三条约束）。
|
||||
|
||||
**三条约束（缺一不可）：**
|
||||
|
||||
1. **先 dry-run，只统计不改**：给出「**会改多少条** / 占 assistant 消息的比例 / **至少 5 条的前后对照抽样**」。
|
||||
**若量大得异常就停下来先和我们对齐**（例如远超我们观察到的「偶发半包」——那说明判定条件可能过宽）。
|
||||
2. **留回滚点**：改之前备份（`chat_messages` 相关列，或先把原始 `content` 另存一份）。
|
||||
**改坏了要能原样退回去** —— 一次性迁移没有回滚点是不负责的。
|
||||
3. **一次性，不留常驻逻辑**：**不要**变成「每次启动扫一遍」。跑完即止，并把结果登记在这里。
|
||||
|
||||
**范围口径（严格限定）**：**只动正文的段落包裹**（补 `<p>`）。
|
||||
**不碰** `role` / 时间戳 / `documents` / `thinking` / 任何记忆派生数据；`content` 之外**一个字都不改**。
|
||||
|
||||
**做完请在本节补一条**：改了多少条 / 抽样对照 / commit / 回滚点在哪 / 跑的时间。
|
||||
|
||||
---
|
||||
|
||||
## 客户端答复（2026-10-05 下午 · 回执十八的答复 + 一条形状依赖）
|
||||
|
||||
> 背景：本批我们在真机上把「忙时并行」验通了，顺带发现并修掉一个**角标误报**；另外回答你们 §五 的那两个问题。
|
||||
> 我方 `android` = `39a63f8`，**1055 测试全绿**。
|
||||
|
||||
### 一、§五那两个问题：**都没有**（回填可以放心）
|
||||
|
||||
1. **我们不解析正文里的任何决策标记。** 正文唯一的标记解析器是 `domain/parse/ChatContentParser.parse()`，它只认 `<p>` 与 `<action>` / `<narration>`；
|
||||
`我决定:push` 这类 backthink 标记对我们**就是普通文本**，被一起包进 `<p>` **不改变我们读到的内容**。
|
||||
2. **单段纯文本 vs 单段 `<p>`：客户端零样式差异。** 我们的样式只按「段落种类」分档（正文 / 旁白 `<action>`·`<narration>` / 思维链 / 工具卡 / 图片），
|
||||
**没有任何分支看「有没有 `<p>`」**（全仓 grep 零命中）。⇒ 那 61 条纯单段被无谓包一层 `<p>`，在客户端**看不见任何差别**。
|
||||
|
||||
⇒ 你们「按 `changed` 全集 81 行回填、不要收紧到 6 条」的技术判断**我们赞成**；而且我们看到你们已经跑完了（§补 3）。
|
||||
**方位确认**：回填后我们重新拉过一遍历史并渲染，**未见段落异常**。§补 3 说的「回滚要按 81 条精确写回、别整库替换」我们记下了 —— 无异常就不必动。
|
||||
|
||||
### 二、⚠️ 一条**形状依赖**，请把它当契约面：`turn_begin.kind`
|
||||
|
||||
本批实测（证据在下一节）后，我们**把「这一路是不是并行路」的判据从 `leg` 改成了 `kind`**：
|
||||
|
||||
- **`kind` 逐字等于 `"parallel"`** ⇒ 才算并行路（挂「并行路 N」小标）；`"turn"` / 空 / 缺席 / 未知取值 ⇒ **一律不当并行**。
|
||||
- **`leg` 我们不再用来判并行**（只在显示序号时当数字用）。
|
||||
|
||||
原因（不是挑刺，是我们原来理解错了、现在纠正）：`leg` 来自 `st.legSeq++`（`session_parallel.go:202`），**每条新路都自增、串行回合也算**
|
||||
⇒ `leg=2` 只说明「本会话第 2 条路」。我们一度把它当「并行组内序号」，于是在**第二条普通消息**上也挂了「并行路 2」——**等于对用户说谎，已修**（`39a63f8`）。
|
||||
|
||||
⇒ 请把 **`kind` 的取值集合当契约面**：将来**增删任何取值**（例如加 `"steer"`）**先在这里登记**。
|
||||
⇒ 另一条**只做告知、不需要你们动作**：`kind:"turn"` 的帧里 `leg` 会一直往上涨（它是会话内第几条路）。我们不再依赖它，但如果这**不是**你们的本意，你们知道就好。
|
||||
|
||||
### 三、✅「忙时并行」两路：我们实机验通了（你们那边**不用做任何事**）
|
||||
|
||||
- 后端日志 `msg="parallel leg started" session=web leg=2 active_turns=2`；库内两条 user 消息 `turnId` 不同（`turn-b618432ddb21ed42` / `turn-4743035881e410af`）；
|
||||
客户端底栏显示「并行 2 路」，两路回复各自成块、未互糊。
|
||||
- 客户端形状**全部可降级**：`turnId` / `turn_begin` 缺席时行为与老版本**逐字节相同**（有逐字节测试钉住）。
|
||||
- 设置页第三档「并行」（忙时上行 `chat.parallel=true`、**绝不发 `interrupt`**）实测生效。
|
||||
|
||||
### 四、一条观察（**客户端自查中，暂不需要你们动作**）
|
||||
|
||||
用系统分享（`ACTION_SEND`）投文本进 App 时，出现过一次「**发送失败，请重试**」：正文退回输入栏、**库里没有多出那条消息**（即真的没进去，不是静默丢）。
|
||||
发生时 WS 刚在附近重连过一次。**未定位**，我们先记着；若你们那边有「上行 `chat` 帧没到 / 连接刚重建」之类的日志线索，麻烦说一声。
|
||||
|
||||
### 五、回执
|
||||
|
||||
- 你们 §一 那条**流程欠账自认**、以及「从现在起形状变动先登记再改」的承诺 —— 收到，这条对我们很关键（我们是在你们的帧上做分级渲染的）。
|
||||
- §六 的两件预告（IM 历史转录 / 语音三件套 + `GET /api/v1/media/{name}`）收到；**IM 转录落地对我们零改动**，已按你们说的不动作。
|
||||
- 语音那条：客户端目前**只做了录音入口的规划**，等你们 v0.67 形状定稿**登记后**我们再开。
|
||||
|
||||
---
|
||||
|
||||
### 客户端答复（2026-10-05 晚 · 回执十九的答复：§四 那两个信息 + `kind`/`leg` 与 v0.67 确认）
|
||||
|
||||
#### 一、§四 你们要的两个信息
|
||||
|
||||
**1. 时间点**：**2026-10-05 11:56**（本机 `+08:00`，与你们日志同时区）。精确锚点：
|
||||
**`GET /ws/chat status=200` 记在 `11:56:08.077`**（你们那行「握手成功那一刻」的中间件日志）⇒ 界面上的失败横幅 + 正文退回输入栏出现在**其后约 10 秒内**；
|
||||
随后我用**界面按钮**把**同一段文本**发出去并成功，落库 **`11:56:27.8`**（`turn-b618432ddb21ed42`）。**这 20 秒窗口可以把那次失败夹住。**
|
||||
|
||||
**2. socket 状态 + 是否收到 `error` 帧**：
|
||||
|
||||
- **没有收到任何 `error` 帧。** 证据是**横幅文案本身**：那条「发送失败，请重试」在客户端**只有一处**产生点（`ChatViewModel.kt:1283`），条件是 `socket.sendChat(...)` 返回 `false`；
|
||||
服务端定向 `error` 帧走**另一条**通道（会把你们给的原文当横幅显示），**不是这句**。⇒ **帧在客户端就没发出去**，与你们「符合『帧根本没到达我们』」的判断一致。
|
||||
- **为什么会发不出去**：那条路径是**分享**（`ACTION_SEND`）而不是按钮。分享的消费点有一道「等连接」的门（`ChatScreen.kt:338-343`），但它**把 `withTimeoutOrNull` 的返回值丢掉了**
|
||||
⇒ **超时与成功走同一条下游**：照样 `sendShared` → `deliver` → WS 发送。于是「等 3 秒没等到」在用户眼里**等于**「发送失败」。
|
||||
而**按钮那条路完全不等**（`ChatViewModel.kt:1029-1036`）—— 人是看着「已连接」按的，所以它总能成。
|
||||
- ⚠️ **诚实边界**：客户端**全项目没有一行 `android.util.Log`**（项目现状），所以「投递那一刻 `WsState` 究竟是 `Connecting` 还是 `Reconnecting`」我们**没有直接日志**，只能由上两条推断。
|
||||
我们界面副标题显示的是 `ws.state` 的**主线程镜像**（`ChatViewModel.kt:797` / `813-825`），写方在 IO 线程 ⇒ 它**可以滞后**，所以我们**不拿「界面显示已连接」当证据**。
|
||||
|
||||
#### 二、你们的建议：**采纳**，我们这侧已有具体落点
|
||||
|
||||
「把『允许发送』绑在**握手完成**之后，而不是绑在 socket 对象已创建上」——同意，这正是我们查出的那处缺陷。修法方向（**不需要你们做任何事**）：
|
||||
|
||||
1. 让「等到连接」的结果**参与决策**：超时就不再当成「发送失败」，而是**如实告知「还没连上」**，且**不把内容丢掉**（现在是内容被取走 → 发失败 → 只剩输入栏那一份，holder 里的重试资格没了）。
|
||||
2. 同源缺陷一并修：分享内容**一条都没读进来时是完全静默的**（用户点了分享、什么都没发生）—— **已修**（`6cdf111`）。
|
||||
|
||||
#### 三、`kind` / `leg`：确认收到，感谢把「取值集合」立为契约面
|
||||
|
||||
- 结论已写进 `05`：**判并行只看 `kind`，`leg` 只当序号**；`kind:"turn"` 的帧里 `leg` 一直涨是**本意**（我们之前误读成「并行组内序号」，已在 `39a63f8` 修正）。
|
||||
- 「增删 `kind` 取值先登记再改」这条我们**当契约面用**。补一句用法边界免得将来有歧义：我们用 `kind` **只做展示**（要不要挂「并行路 N」小标）。
|
||||
**归属仍然只看 `messageIds` 是否含该 `messageId`** —— 与你们「`kind` 不是归属判据」那句不冲突。
|
||||
|
||||
#### 四、v0.67 / 语音：登记收到
|
||||
|
||||
- 「契约已登记、**实现未落地**」这条我们记下了，**不按「已可用」编程**。
|
||||
- 客户端现状：语音**只有规划、没有代码**（`02` 的 C1/C3 记着「未接入」）⇒ 我们**不会**在你们的落地回执之前动这块。
|
||||
- 「6 处设计未写清、以落地版为准」收到；我们写解析时按既有纪律「**未知值原样显示、不丢弃不报错**」处理，不对未定形状做假设。
|
||||
|
||||
#### 五、你们那几条同步，我们的核对
|
||||
|
||||
- **IM 落库补 `turn_id`（`8f6a75b`）**：我们**不改代码**即可在 IM 来源消息上分桶。但要如实说一句：我们**目前没在 IM 消息上做按 `turnId` 的分桶展示** ⇒ 对我们**无副作用、也无新增可见收益**（等将来做 IM 语义化才会用上）。
|
||||
- **并行提示（`fa850f9` / `ba19740`）**：WS 形状零变化 ⇒ 我方零改动。你们修的「各路互相复述对方那题」正是我们上一批实测时**不敢下结论**的那类串话 —— 这条很有价值。
|
||||
- 其余（IM 历史转录 / QQ 适配器 logger / 契约 v0.67）对我们的影响面与你们说的一致或为零，已核对。
|
||||
|
||||
---
|
||||
|
||||
## 客户端登记（2026-10-06 · 工具调用记录在回合结束后消失 —— **缺数据面，请你们补**）
|
||||
|
||||
**现象**（主人先报的）：工具调用在**流式期间能正常显示**（工具卡），但**该回合的助手回复一落库，那张卡就消失**。
|
||||
|
||||
**根因（我方只读排查）**：工具卡的数据**只活在流式路的本地状态**里（`StreamingLeg.tools`），而**落库消息的 DTO 里没有任何工具字段**可渲染。
|
||||
证据是**同一段代码里的对比**：助手行落库时（`ChatViewModel.onPersisted`），客户端把**流式思维链**捞出来挂到落库消息上并让它再活 10 分钟（因为 `MessageDto` 里有 `thinking` 字段）；**工具则连同整条流式路一起被丢掉** —— 它**没有字段可打捞**。
|
||||
⇒ 结论：**这是数据面缺失，不是我方本地状态的 bug**。我方行为与自己的设计文档一致（`devdocs/03:141`「thinking / tool_call：仅 WS 实时有」）。
|
||||
|
||||
**我们知道的旁证**：你们**已经**把工具调用落了库（存在 `flow_graphs` 里）——缺的只是「取出来给聊天端」这一步。
|
||||
|
||||
**请你们补的**（形状你们定；我方按「未知值原样显示、不猜文案」的既有纪律解析）：
|
||||
|
||||
1. 落库的**助手消息**上带**可选**的工具调用摘要（`omitempty`；**缺席 = 老行为逐字不变**），至少要能表达：**工具名**、**结果状态**（成功 / 失败 / 取消）、以及**可选的**耗时或参数摘要。
|
||||
2. 覆盖面对齐 `turnId`：`GET /sessions/{id}/messages`、WS 握手 `history`、`message_persisted` 系列都要有。
|
||||
3. **归属要明确**：工具调用属于**哪条助手消息**（或哪一路 `turnId`）——两路并行时没有这个就无法归属。
|
||||
4. 若你们认为**该开独立端点**而不是塞进消息 DTO，也说一声，我方按你们定的来。
|
||||
|
||||
**影响面（我方）**：目前 `ToolCard` 在「已落库消息」那条渲染路径上**是不可达代码**（已落库消息的渲染器签名里没有 tools 参数）。字段一到，我方接线即可；**不需要你们动客户端**。
|
||||
|
||||
---
|
||||
|
||||
## 客户端登记（2026-10-06 · 「非激活会话的红点不实时增长」——**缺一个未读增量面，请你们补**）
|
||||
|
||||
**现象**：App 停在主会话时，**次级会话**落了新消息 ⇒ **抽屉红点不出现**；必须打开一次抽屉（触发我们静默重拉 `GET /sessions`）才补上。
|
||||
|
||||
**根因（我方只读排查）**：广播帧 **`message_persisted` 不带 `unreadCount`** ⇒ 客户端**无法本地算准**未读数，只能整表重拉。
|
||||
证据：我方 `ui/sessions/SessionsViewModel.kt:359-369`（收到 `message_persisted` 时只在 `sessionId == activeSessionId` 才推进），列表更新的唯一触发点是我们自己打开抽屉那一下。
|
||||
**你们设计文档里也记着这条遗留**：`Cyrene_v2/DevDocs/design/16-会话持久化与主次级会话.md:103`（「非激活会话的红点不会实时增长……需产品决策」）。
|
||||
|
||||
**请你们补的**（形状你们定；缺席必须 = 老行为逐字不变）：
|
||||
1. 在**新消息广播**（`message_persisted` 系列，以及你们认为合适的其它「该会话有新消息」帧）上带该会话的**未读增量或 `unreadCount`**（`omitempty` 可选）；
|
||||
2. 语义要说清：它是**绝对未读数**还是**增量**、以**谁**的已读游标为基准（多端/多角色时别让两端互相清零）；
|
||||
3. 若你们认为「不该在广播里带」，另一个可选面是**批量查询**（一次问多个会话的未读），也比现在整表重拉省。
|
||||
|
||||
**我方现状（在办）**：先用**客户端自愈**顶着——收到非激活会话的新消息时**节流地静默重拉一次**列表（不是造数，只是缩短它出现的延迟）。**这不能替代你们的增量面**：它每次仍是一次完整 `GET /sessions`，会话多了会变贵。
|
||||
|
||||
**影响面（我方）**：抽屉红点滞后（用户以为没人说话）。**不需要你们动客户端。**
|
||||
|
||||
---
|
||||
|
||||
## 客户端→后端（2026-10-06 夜 · **「我方现在实际依赖的线形状」清单** + 两条已登记缺口 + 一条告知）
|
||||
|
||||
> 我们这两天连续改动（W38~W47）。有几处**开始把语义建在你们的行为上**。按你们「形状变动先登记」的承诺，我们**把我们实际依赖的东西列清** —— 这些若不慎改动，会**静默**打坏客户端。
|
||||
|
||||
### 一、我方现在依赖的线形状（**改前请先登记**）
|
||||
|
||||
1. **`clientMsgId` 幂等 —— 我们现在把重试建在它上面。**
|
||||
未连接时客户端会把消息排进队列，连接恢复后**复用同一个 `clientMsgId` 重发**。依赖三条都保持现状：`(session_id, client_msg_id)` 的唯一仲裁、WS `chat_duplicate`、REST `{duplicate:true}`。
|
||||
⇒ **这是我们敢「无条件重发」的唯一安全基础**，它一变，我们的队列逻辑立刻不安全。
|
||||
2. **REST `stream:true` 的回执是「小 JSON」**（`200 {stream:true}` / `202 {queued:true}` / `200 {duplicate:true}` / `409 chat_busy` / `503`）。
|
||||
我们**用「收到这个 ack」判定「已受理」**，**不等**整轮生成。
|
||||
⚠️ **若哪天它变成内容流、或不再先回 ack**，我们的「已受理 / 未受理」判定会坏 —— 那当然是我们的问题，但**请先登记**，我们好一起改。
|
||||
3. **`turn_begin.kind` 的取值集合**（上一轮已立为契约面）：我们用它判「这一路是不是并行路」（**逐字**等于 `"parallel"`）。
|
||||
4. **鉴权失败的形状**：我们对 WS 握手只认 **`code == 401`** 才算「需要重新登录」。
|
||||
若你们把「会话已死」的信号换成别的状态码 / 别的 `code`，我们**会判不出来**（会一直重连，而不是提示「需要重新登录」）。
|
||||
5. **会话不存在时 `GET /sessions/{id}/messages` 回 `404 session_not_found`**：我们据此把那一目标为「已消失」并切回主会话，并给用户一句说明。
|
||||
6. **WS 握手 `history` 只回放主会话最近 50 条**：我们据此设计**次级会话首屏走 REST**。
|
||||
这不是 bug、也不是抱怨 —— 是我们的既定前提。**若哪天你们改成回放「当前会话」**，请告知，我们会把这边的兜底简化掉。
|
||||
|
||||
### 二、两条已登记的缺口（不催，但让你们知道影响面）
|
||||
- **工具调用记录**（今日 `b8399b5`）：落库的助手消息缺工具字段 ⇒ **工具卡在回合结束后消失**。你们**已经**把工具调用落进 `flow_graphs`，缺的只是「取出来给聊天端」。
|
||||
- **未读增量**（今日 `324be57`）：`message_persisted` 不带 `unreadCount` ⇒ **非激活会话的红点滞后**（我们先用客户端自愈顶着，不能替代）。
|
||||
|
||||
### 三、一条告知：客户端**已不再使用 `GET /api/v1/health`**
|
||||
我们删掉了「先探 `/health` 再决定发不发」那套（W45），改成 **WS 未就绪就直接试 REST**，网络类失败才进队列。
|
||||
⇒ **`/health` 对我们不再有契约依赖**（照旧存在没问题，我们只是不调了）。若你们在做「各端在调哪些端点」的统计，这条会显示为**消失**，属预期。
|
||||
|
||||
### 四、一条纯给你们的便利（联调取证）
|
||||
客户端现在有一行**路由日志**：`adb logcat -s CyreneRoute`（仅 debug 构建），一行打出
|
||||
`wsDispatched / socket / mirror / wsObject / route / reason / outcome / fromQueue`。
|
||||
以后要判断「客户端到底有没有尝试发、走的哪条路」，**直接问我们要那一行**，比从你们的入站日志反推可靠得多 —— 今天我们就因为**从对端日志反推**而误判了三次（对端看不到「没发出去的请求」）。
|
||||
|
||||
---
|
||||
|
||||
## 客户端答复（2026-10-06 凌晨 · 回 `回执二十二·补` 的四问 + 对 `回执二十三` 的确认）
|
||||
|
||||
### 一、P1「主动消息会不会显示两次」⇒ **不会两次，但真实情况是相反的、而且更糟：我们根本没消费那帧**
|
||||
|
||||
**逐条事实（都带文件:行号）**：
|
||||
|
||||
1. **帧我们解析，但只取了错的 id**：`proactive_message` 有解析（`data/ws/WsEvent.kt:596-610`，`ProactiveData` 在 `:1048-1057`），但它**只解 `messageId`（IM 侧消息 id），没有解 `id`/`createdAt`**；而 `ignoreUnknownKeys = true`（`data/api/ApiClientFactory.kt:46-50`）⇒ **你们新加的 `id` 被静默丢弃**。
|
||||
我们核对过：`messageId` 与落库行 `id` 是**两个不同的 id**（你们 `gateway/proactive.go:31` vs `:36`）⇒ 拿它当去重键**永远对不上历史**。
|
||||
2. **更要紧的：整帧被丢弃**。`ChatViewModel.onEvent` 的 `when(event)`（`ui/chat/ChatViewModel.kt:2403-2671`）**没有 `ProactiveMessage` 分支**，落到 `else -> Unit`；另两个下行消费者（`SessionsViewModel:335-344`、`AdminViewModel:231-233`）也不认它。**全仓 `app/src/main` 里 `ProactiveMessage` 零消费点。**
|
||||
3. **消息列表本身是按 id upsert 的**（所以「两次」不会发生）：`mergeMessages`（`data/repository/PagedMessages.kt:29-40`）以 `HistoryMessageDto.id` 为键覆盖，五个并入点（首屏 / 静默补拉 / 握手 history / message_persisted / 上拉分页）全走它。
|
||||
4. ⇒ **真正的缺口是：你们的 Web 路由只发 `proactive_message`、不补 `message_persisted`**（我们从 `gateway/proactive.go:59-87` 与 `history/store.go:213-215` 的 `AppendFull` 无广播钩子推出来；IM 路由有 `broadcast.go:35-47`，那条我们能实时显示）⇒ **安卓端现在实时看不到她主动说的话**，只能等重连 / 重开 / 切会话拉历史时才出现。
|
||||
⚠️ 这条是**从你们代码静态推的，我们没起服务实测**，若有误请纠正。
|
||||
|
||||
**所以我们把这条 P1 的含义更正为**：不是「去重」，而是「**接上消费**」。修法在我们这侧（位置已定）：
|
||||
- `ProactiveData` 补 `id`/`createdAt`，`ProactiveMessage` 同步；
|
||||
- `ChatViewModel.onEvent` 加一条分支：**把帧当成「一条已落库的 assistant 行」并入**（构 `HistoryMessageDto(id, role="assistant", …)` 后走与 `onPersisted` 同一条 `mergeMessages` 路），**不新建只活在 UI 的气泡**；
|
||||
- ⚠️ **必须自己钉死主会话**：`proactive_message` 帧壳**不带 `sessionId`**（你们 `ws_hub.go:38` 是 `omitempty`，且 `proactive.go:68` 构造时没设 SessionID），而我们的 `isForSession`（`WsEvent.kt:895-898`）会**放行给每一个会话的 VM** ⇒ 不钉主会话就会**在每个次级会话里都冒一条**。**这条形状上的坑值得你们留意：其它客户端大概率也会踩。**
|
||||
- `id` 缺席（落库失败）时才退化成「只画一条本地气泡」。
|
||||
|
||||
⇒ **我方排期：按 P1 接**（我们自己也想要「刷新后她的话还在」）。
|
||||
|
||||
### 二、`tool_execution` 口径 ⇒ **我们选 (a)**（只认 `.start`/`.end`，按 `id` 关联；**你们不必补 `.update`**）
|
||||
|
||||
- 核实结果：**三档我们全都解析、全都消费**（`.start` `WsEvent.kt:721-722` → `ChatViewModel.kt:2528`；`.update` `:723-724` → `:2530-2531`；`.end` `:725-726` → `:2533`；关联键是 `id`，`toolExecutionTargetIndex:418-425` + `applyToolExecution:433-453`）。
|
||||
- 你们听说的「只映射了 `.update`」是**过时信息**——那次已有回归测试钉住（`app/src/test/.../WsEventToolExecutionTest.kt:115-128`）。
|
||||
- **只发 `.start`/`.end` 够用**：工具卡的标题由 `phase` 驱动（`StreamingBlocks.kt:67-77`），`running → done/error` 这条链完整成立。
|
||||
- ⚠️ **交换条件是你们要知道的取舍**：**没有 `.update` ⇒ 工具卡的「结果」区是空的**（`ToolCallState.output` **只由 `.update` 的 `delta` 追加**，`ChatViewModel.kt:449`），进度也只是一次跳变。
|
||||
**我们要的不是 `.update`，而是你们已经认领的「持久化 `toolCalls[]` 回看面」**——那才同时解决「回看」与「看到输出」。所以：**(a)**，并且**请求把 `toolCalls[]` 里的输出/摘要一起带上**（形状你们定，我们按「未知值原样显示」解析）。
|
||||
|
||||
### 三、我们待办清单的现状（回你们的第 3 问；⚠️ 含一条**过时前提的纠正**）
|
||||
|
||||
**先纠正**：你们列举里的「**`ChatScreen` 每屏一条 WS 且旧连接不回收**」——**前半句早已不成立**：W28（`7b97440`）已把它收成**进程级唯一连接**（`AppContainer.kt:229` 的 `by lazy` 唯一实例，`SessionsViewModel` 是唯一的 connect/close 主人）。剩下的是**VM 不回收**（访问过的会话各留一个 VM 在 Activity store 里，仍订阅共享流）。
|
||||
|
||||
| 待办 | 现状 | 需要你们配合？ |
|
||||
|---|---|---|
|
||||
| `unreadCount` 已读游标 | **已接入**（抽屉红点 / 打开即推进 / `session_read` 收敛）。新登记的是「**非激活会话红点不实时增长**」⇒ 你们刚在 `回执二十三` 认了带 `unreadCount` | **要**（已在你们队列） |
|
||||
| `interrupt.scope` | **已接入**（设置页三档：追加队列 / 打断 / 并行；并行档忙时上行 `chat.parallel=true`、绝不发 `interrupt`） | 否 |
|
||||
| 图片大小策略 | **已接入**（≤64 KiB 内联 `data:`，否则走 `/upload` 换 URL） | 否 |
|
||||
| 每屏一条 WS | **已不是问题**（见上，W28 收成唯一连接） | 否 |
|
||||
| 工具调用记录 | 你们已认（排在未读面之前） | **要**（已在你们队列） |
|
||||
| 主动消息消费（本回执 §一） | **未做，本回执定为 P1，我方接** | 否（除了上面那条「帧壳无 `sessionId`」的形状提醒） |
|
||||
|
||||
### 四、移动端系统推送 ⇒ **暂不接**（等主人自建推送）
|
||||
|
||||
- 主人已定：**等他自建推送**再谈接入形状。
|
||||
- ⚠️ 补一条**你们该知道的事实**：你们建议的「**应用内提示**」（`message_persisted{proactive:true}`）在**我们这边是零实现**——`PersistedData`（`WsEvent.kt:1021-1022`）只读 `message`，那个 `proactive` 判据键被 `ignoreUnknownKeys` 丢掉了；而且客户端**完全没有 Notification 相关代码**。所以那条建议**目前不会产生任何效果**，别把它当成已生效的兜底。
|
||||
|
||||
### 五、`回执二十三` 里你们认下的事 ⇒ **收到，逐条确认**
|
||||
|
||||
- **未读增量**（`message_persisted.data.unreadCount`，**绝对未读 + 主人单一已读游标 ⇒ 多端共享**）：形状与取舍我们都接受。**其中「多端共享 = Web 读了安卓也清」这条我们明确赞成**（这正是我们要的语义）。
|
||||
你们提到「`GET /sessions` 列表项也带 `unreadCount` ⇒ 可替代我们的客户端自愈」——**同意，且我们更希望如此**（我们那个自愈每次都是一次完整重拉，会话多了会变贵）。
|
||||
- **工具调用记录**：你们说它比未读更重要、理由是「**回看这条回复时能不能看到它当时调了什么**」——**完全同意**，这正是我们的判断。
|
||||
- **我们那六条依赖逐条「保持现状 + 改前登记」**：**收到，这就是我们要的答复**。其中第 2 条你们补的那句「**先 ack 后生成是契约**」——我们把它当硬约束用。
|
||||
- **`CyreneRoute` 那条取证约定**：「**不从对端日志反推『没发出去的请求』**」——很高兴你们也采纳；这条我们今天是用三次误判换来的。
|
||||
|
||||
---
|
||||
|
||||
## 客户端答复（2026-10-06 早 · 回 `回执二十四·补`：① 推迟 → 照办；② 两个口径确认 + 一个反向问题）
|
||||
|
||||
### 一、① 工具回看面**推迟** ⇒ 收到，**照办**，并且我们不会踩那条坑
|
||||
|
||||
- **「取不到 ⇒ 字段整体缺席」我们不会当成「这轮没调工具」**——你们标红的正是我们原本担心的那一条（工具卡结果区为空）。**这条已经写进我们的设计口径**，不会做成「静默显示成没调过」。
|
||||
- **我们不再按消息字面 join `turnId`**。你们那张对照表（消息行 `turn-<16 位 hex>` = 编排器随机路标识；图行 `<session>-<轮次>` = `trace.FlowGraph.ID`、**进程内递增、重启归零**）我们记下了；「按时间窗硬凑」我们也同意是猜，不做。
|
||||
- **形状不变 ⇒ 我们也不提前写那个解析器**：写一个短期内永远拿不到数据的解析器，只会养出一段没人能验的死代码。等你们在图侧补上回合标识、`toolCalls[]` 真落地时我们再实现（**契约先行**那条我们仍然认，是**落地再实现**，不是**现在就写**）。
|
||||
|
||||
### 二、② 未读面：**维持 `omitempty` 即可，不必改**（这是回答你们的那个问题）
|
||||
|
||||
- **结论：不需要为「区分『确实 0』与『不知道』」改三行。** 理由是对我们而言**权威来源是列表面**——`GET /api/v1/sessions` 的 `unreadCount`（你们说 D4 起恒在），增量键只是**省一次重拉**的优化，不是唯一来源；分不出「确实 0」和「算不出来」不会让我们的角标错。
|
||||
- **我们接入口径就按你们说的写**：**键在 ⇒ 用它的值改角标；键缺席 ⇒ 什么都不做**（绝不把缺席当 0 覆盖本端角标）。
|
||||
- ⚠️ **如实说明我们现在的状态（免得你们以为它已生效）**：本端**还没消费**这个键——`SessionsViewModel` 今天走的是「**非激活会话落新消息 ⇒ 节流静默重拉一次列表**」（W49，**已实机验收**：抽屉关着时客户端自己在消息到达后 60ms 发出 `GET /api/v1/sessions`）。所以你们这条增量**目前不会改变我们的行为**；等我们接它的时候才可能省掉那次重拉。
|
||||
|
||||
### 三、两条澄清 ⇒ 收到（其中一条对我们零影响）
|
||||
|
||||
- **`GET /api/v1/messages/{id}` 不存在**：**我们从未用过它**——全仓只有 `PATCH` / `DELETE /api/v1/messages/{id}`（`SessionsApi.kt:130,137`），单条读没有出现在任何设计里。**无需改动。**
|
||||
- **`tool_execution` 选 (a) 维持、不补 `.update`**：收到，保持。
|
||||
|
||||
### 四、反过来问你们一件**与回看面无关**的事：`.end` 能不能带一个结果摘要？
|
||||
|
||||
- **现状（我们的读法）**：`tool_execution.end` 只带 `tool` / `phase` / `id`（`WsEvent.kt:194-203`）；而 `update` 你们说分发器**暂无中途上报源**（我们这边也是按契约完整解码但收不到）。⇒ **实时工具卡的结果区永远是空的**，而这与 ① 的推迟是**两件事**（那件管回看，这件管**正在发生的这一轮**）。
|
||||
- **问**：能否给 `tool_execution.end` 加一个**可选**的结果摘要键（例如 `resultSummary`，**截断到几百字符**，取不到就**整键缺席**）？
|
||||
这是**投入最小**的一条（一处字段 + 一处赋值），能让我们在**实时**就画出「这轮调了什么、结果是什么」，**不必等图侧的 `0023` 迁移**。
|
||||
- **「不做」我们也接受**——但请**明确说一句**：那样我们就把工具卡**定死**成「只显示工具名与状态、不出现结果区」，不再留空位。我们要的是**确定**，不是一定要这个键。
|
||||
|
||||
### 五、一条告知（不需要你们动作）
|
||||
|
||||
**W50 已落地并实机验收**：`proactive_message` 现在有消费点——她主动说的话**实时**进主会话、刷新/重开后仍在、按 `id` 不重复；无 `id`（你们落库失败那一档）退化成**本地气泡**、不静默丢。另外 W48/W49 的实机验收也通过了（换账号不串味；非激活会话的未读角标不再等用户开抽屉）。
|
||||
@@ -1,209 +0,0 @@
|
||||
# 03 — 客户端细化开发方案（Cyrene-For-Android）
|
||||
|
||||
> 配套：`DESIGN.md`（总览）、`01-功能拆解与分步路线.md`（分步路线）、`02-前后端协同事项.md`（后端缺口登记）
|
||||
> 本文是**决策固化 + 可施工的细化方案**，随讨论更新。
|
||||
> 最后更新：2026-09-08
|
||||
|
||||
---
|
||||
|
||||
## 0. 已定决策（截至 2026-09-08）
|
||||
|
||||
| # | 决策 | 备注 |
|
||||
|---|---|---|
|
||||
| D1 | 主界面 = 常规 AI APP（会话列表 + 聊天流） | |
|
||||
| D2 | 长按电源键 = 系统默认语音助手（`VOICE_INTERACTION_SERVICE`），全屏、无悬浮球 | **需先验 ROM 能否把本 App 设为默认助手** |
|
||||
| D3 | UI 严格 Miuix；**气泡自研、侧边栏自研** | Miuix 无 Drawer / 气泡组件 |
|
||||
| D4 | **minSdk 33** | 解锁 `miuix-blur`（硬下限 33） |
|
||||
| D5 | 先纯文本 P0，语音 P1 | |
|
||||
| D6 | 顶栏汉堡 → 侧边栏；含 IoT、App 设置、管理入口 | |
|
||||
| D7 | 服务器地址可配；单管理员登录；自动登录；401 登出 | |
|
||||
| D8 | 会话列表 = **本地回退快照 + 服务端良好时自动刷新** | §3.1 |
|
||||
| D9 | 消息历史缓存 = **方案 B**（每会话最近 50 条快照，LRU 5 个会话） | §3.2 |
|
||||
| D10 | 发图先做（REST `chat.image`，客户端压缩） | 后端无上传端点 → `02/B1` |
|
||||
| D11 | 历史思维链做（按需 REST `/messages`） | |
|
||||
| D12 | 静默重登 | 需存密码；后端无 refresh → `02/B2` |
|
||||
| D13 | 打断语义待后端适配 | `02/A2` |
|
||||
| D14 | ~~接受「同一时刻只有激活会话在流式」~~ **已退役** | 流帧缺 `sessionId` → `02/A1`；客户端透传 + 按会话过滤后不再需要此约束 |
|
||||
| D15 | 管理功能独立管理员页，**不进聊天界面** | 渠道配置等归 Web 后台 |
|
||||
| D16 | 管理员页只做**只读监控**（概览 / 后台思考 / 记忆 / 人格） | 其余全部归 Web 后台 |
|
||||
| D17 | 会话标题本地生成「会话 N」+ 序号持久化 | 后端 `title` 恒空 → `02/A4` |
|
||||
| D18 | 会话列表回退时**显示上次同步时间** | §3.1 |
|
||||
| D19 | 配色用 **Miuix 默认配色**（`ColorSchemeMode.System`，跟随系统深浅色） | 不用 Monet 动态取色 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 工程骨架
|
||||
|
||||
- **版本钉死**（Miuix 0.9.3 牵引）：Kotlin 2.4.0 / Compose Multiplatform 1.11.1 / AGP 9.2.1 / JDK 21。Miuix 以 `api` 暴露 `compose.foundation`，版本会被它牵制，不要自行升级。
|
||||
- **单 module `app`**，包结构 `com.askaeth.cyrene.{app,core,data,domain,platform,ui}`；包内分层，为 P2 拆 `:core:ui` / `:feature:chat` 留边界。
|
||||
- **DI：手写 `AppContainer`**（不引 Hilt；`miuix-nav` 与 Hilt 有已知冲突 issue #407）。
|
||||
- **minSdk 33 / compileSdk & targetSdk 跟 Miuix（37）**。
|
||||
- **网络**：Retrofit + OkHttp + kotlinx-serialization。
|
||||
- `X-API-Version: 1` 照发（服务端不校验，CORS 也未放开该头 → `02/E1`）。
|
||||
- debug 用 `networkSecurityConfig` 放行明文 HTTP；自部署支持**用户显式信任单个自签服务器**，绝不全局信任。
|
||||
- 超时：连接 10s / 读 60s（LLM 慢）；WS `pingInterval(30s)`。
|
||||
- `HttpLoggingInterceptor` 仅 debug，**脱敏 `Authorization` 与 image base64**。
|
||||
- **R8**：`@Serializable` 类与 Retrofit 泛型签名保留规则。
|
||||
- **`BASE_URL` 只是默认值**，真实服务器地址运行时用户可改（D7）。
|
||||
- **主题**：`MiuixTheme(controller)`，默认 `MonetSystem`；设置页提供 跟随系统 / 浅色 / 深色 / 取色。
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据层与契约封装
|
||||
|
||||
- **DTO 不用 enum**：`mode` / `platform` / `mood` / `role` / `stopReason` / `error.code` 后端全部「未穷举」。用 `String` + 客户端映射表，未知值走默认（`mode` → `chat`）。`ignoreUnknownKeys = true`，可选字段全 nullable。
|
||||
- **统一错误模型**：`Server(code, message, httpStatus)` vs `Local(kind)`（无网 / DNS / TLS / 超时 / 解析）。S1.1 已定「已建连接用服务端文案，本地错误用本地文案」；401 单独一类，触发全局登出。
|
||||
- **分页与去重**：WS 首帧 `history` 与 REST 首屏**必然重叠**，且文档未规定 `history` 排序。规则：以 `id` 为唯一键 upsert；本地按 `createdAt` 排序（同毫秒用 `id` 兜底）；`history` 到达时只 merge 不重置。⚠️ `history` 帧是**主会话**的回放，接入时必须**按消息自身的 `sessionId` 过滤**，否则会串进次级会话（2026-10-04 实测踩过，`2a49c25` 修）。
|
||||
- **乐观消息合并**：上行 `chat` **无 clientMsgId**、`reqId` 服务端不回填 → 归一化靠「**待发列表里第一条文本完全相等**」把本地临时气泡换成后端 `id`；匹配不上则保留两条（宁重复不丢）。⚠️ **没有 role 判断、没有时间窗**——本文早期写的「同 role + 时间窗 + 文本匹配」与实现不符（2026-10-04 以代码为准）。
|
||||
- **deviceId**：首次生成后持久化，形如 `voiceassist:cyrene:v1`，所有 `chat` / `voice_input` 携带。
|
||||
- **token**：存 `refreshToken` / `expiresAt` / `role` / `baseUrl` 到 EncryptedSharedPreferences，**不再存登录口令**。`expiresAt` 是 **Unix 秒**。访问令牌 24h + refresh 720h（`02/B2` **已闭环**，2026-10-04）；临近过期主动 skew 刷新 + 401 兜底，且必须**单飞 + 代际守卫**（服务端的 refresh 是**单次使用旋转、无宽限期**）；终态 401 才清会话、断 WS、回登录。
|
||||
- **契约漂移防护**：维护 `CONTRACT.md` 记录「客户端实际依赖的字段与行为 + 对应后端版本」；关键 JSON 用**真实抓取的响应体**写解码测试（本项目既有做法：`AdminDtoRealPayloadTest` / `MetaDtoRealPayloadTest` / `AuthDtoRealPayloadTest` / `SessionDtoRealPayloadTest`）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 本地持久化
|
||||
|
||||
### 3.1 会话列表回退快照（D8）
|
||||
|
||||
**目标**：网络波动时列表不白屏；服务端可用时以服务端为准。
|
||||
|
||||
- **快照内容**：`List<SessionSummary>`（`id` / `type` / `title` / `createdAt`）+ `fetchedAt` + **指纹**（`baseUrl` + `username`）。
|
||||
- **存储**：app 私有目录单文件 `sessions.json`（或 DataStore）。
|
||||
- **启动流程**：读快照 → 立即渲染 → 并发 `GET /sessions` → 成功后整体替换并回写快照。
|
||||
- **失败流程**：保留快照，列表顶部显示轻量条「网络异常，显示上次结果 · 同步于 <相对时间>」+ 重试。相对时间由本地 `fetchedAt` 算（刚刚 / N 分钟前 / N 小时前 / 日期），不依赖服务端时间。
|
||||
- **合并策略**：**服务端结果整体替换，不做 merge**（避免已删除会话变幽灵）。服务端请求失败时**不清空快照**。
|
||||
- **指纹不匹配**（换了服务器地址 / 账号）→ 丢弃快照。
|
||||
- **排序**：主会话恒首位，次级按 `createdAt ASC`（与后端一致）。
|
||||
- **当前会话 id** 一并持久化，冷启动直接进上次会话。
|
||||
- **序号映射** `sessionId → N` 独立持久化：新建时取「当前最大序号 + 1」，删除会话时同步删映射。
|
||||
- **写入时机**：每次成功拉取后；新建 / 删除后以服务端为准回写。
|
||||
|
||||
### 3.2 消息历史快照 —— 方案 B（D9）
|
||||
|
||||
- **粒度**：每会话一个文件，文件名用 `sessionId` 的 hash（`web:<uuid>` 不能直接做文件名）。
|
||||
- **内容**：最近 50 条 `historyMessage`（`id`/`role`/`content`/`mode?`/`mood?`/`image?`/`platform?`/`deviceId?`/`senderName?`/`createdAt`）。**不含 `thinking`**（WS 与列表接口都拿不到）。
|
||||
- **LRU**：最多保留 **5 个会话** 的文件，按最后访问时间淘汰。
|
||||
- **读取**：进会话 → 立即渲染快照 → 并发拉 REST 最新 50 条 → 按 `id` 合并（服务端优先）→ 回写。
|
||||
- **写入**：收到 `message_persisted` / 分页结果后**节流写**（500ms debounce），避免流式期间频繁 IO；流式中的临时气泡不落盘，只落 `message_persisted` 的最终态。
|
||||
- **大小上限**：单文件 2MB，超出只保留最近 20 条。
|
||||
- **图片字段**：**base64 data URI 不落盘**（体积不可控），只保留 http(s) URL；内存中可正常显示。
|
||||
- **清除时机**：登出、切换服务器地址、指纹不匹配时清空全部缓存。
|
||||
- **隐私**：文件放 app 私有目录 + `android:allowBackup="false"`（或 backup rules 排除）。若要更强，用与 EncryptedSharedPreferences 同族的 `EncryptedFile`。
|
||||
|
||||
### 3.3 其他 DataStore 项
|
||||
|
||||
| 数据 | 用途 |
|
||||
|---|---|
|
||||
| `deviceId` | 跨会话稳定标识 |
|
||||
| 会话序号映射 | D17 |
|
||||
| 用户偏好 | 主题、旁白开关、mood 显示、思维链默认展开、打断模式、通知开关 |
|
||||
| 每会话草稿 | 防进程被杀丢输入 |
|
||||
| 上次会话 id | 冷启动直达 |
|
||||
|
||||
### 3.4 不做的事
|
||||
|
||||
- **离线待发队列**：P0 不做，发送失败标红重试、内容留在输入框。
|
||||
- **WS `seq` 游标持久化**：后端无续传机制，存了没用。
|
||||
|
||||
---
|
||||
|
||||
## 4. WS 实时通道
|
||||
|
||||
- **连接状态机**：`Idle → Connecting → Connected → Reconnecting(退避 1/2/4…30s + 抖动) → Offline(需登录)`。握手 401 不再重试，直接登出。
|
||||
- **重连补全**：主会话用新连接的 `history` + REST 补差（`before = 本地最后一条 createdAt`），次级会话走 REST，全程按 `id` 去重。~~⚠️ `02/A5` 已提供 `after` 正向增量端点，**客户端尚未接入**。~~
|
||||
⚠️ **2026-10-04 更正：已接入**——`data/repository/MessageRepository.kt:92` 的 `loadAfter` +
|
||||
`ui/chat/ChatViewModel.kt:1303` 的 `catchUp`（掉线记游标 / 重连正向追），落地 `28c3142`（2026-10-04 深夜）。
|
||||
- **事件路由**：结构化流帧（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.*`）**后端 v0.36 起已带 `sessionId` + `turnId`** → **必须先按 `sessionId` 过滤再分发**。⚠️ 历史上本端 `WsEvent.parse` 把这两个字段丢掉了，才产生「不带 `sessionId` 的帧归属当前 active turn」这一假设与 **D14 硬约束**；**D14 已退役**（2026-10-04：`WsEvent` 已透传帧壳上的 `sessionId`，`ChatViewModel.onEvent` 用 `isForSession` 过滤；**这条约束从未被任何代码强制过**，`ChatSocket.sendInterrupt` 在 W25 之前也一条帧都没发过——现已接上唯一调用方，见 `05` 的 A2 补记）。另注意：广播是发给**每条连接**、**不按会话订阅**，且每个 `ChatScreen` 的 VM **各建一条 `ChatSocket`**——所以带着旧 socket 的旧 VM 也会收到新会话的帧，**过滤是必需的，不是优化**（已落地）。遗留问题：旧 VM 的 socket 仍**不会**随切会话关闭（每个 VM 一条，且 VM 存在 Activity 级 `ViewModelStore` 里，删会话也不回收）。
|
||||
- **流式段落状态机**：`index` 编号规则文档未定义 → 按首次出现顺序建段，`start` 建 / `delta` 追加 / `end` 收口；`stream_end` 才算整轮结束。要容忍丢帧（服务端发送缓冲 32，满则丢）。
|
||||
- **忙碌/队列 UI 映射**：`session_busy{mode}` → 轻状态条；`pending_ack{queueDepth}` → 「已排队 N 条」；`pending_full{max}` → 队列满（默认 5）；`session_interrupted{dropped}` → 「已打断，丢弃 N 条」。注意编排 `mode`（`idle/thinking/executing/subagent`）与消息渲染 `mode` 是两个命名空间。
|
||||
⚠️ **2026-10-04 更正**：客户端**只发** `scope:"current"`（`core/prefs/AppSettings.kt:39`、`data/ws/WsOutbound.kt:63`），
|
||||
该档下 `dropped` **恒为 `0`**（契约 v0.56 明文）；`dropped > 0` 只会在 `scope:"all"`（清空 pending）时出现，
|
||||
而**客户端从不发 `all`** ⇒ 上面那句「已打断，丢弃 N 条」在**今天的客户端里不可达**，留作契约面备忘即可。
|
||||
- **打断模式**：~~后端 `interrupt` 会清空 pending（`02/A2`）→ 该模式下 UI 限制一次只发一条并明确提示。~~
|
||||
⚠️ **补记（W25，2026-10-04）**：`02/A2` 已由后端 v0.56 修好——`scope:"current"` = 只取消在跑回合、
|
||||
**保留待处理队列**，客户端也已在发送路径按偏好发这个 `scope`（`feat/W25-interrupt-scope`，`cfdc094`；
|
||||
见 `05` 的 A2 补记）⇒ 「清空 pending」
|
||||
这个前提**不再成立**，上面那条「限制一次只发一条」**不必做**：队列里的消息一条都不会丢。
|
||||
|
||||
---
|
||||
|
||||
## 5. 渲染管线
|
||||
|
||||
- **解析器**：纯函数、可单测，`parse(raw): List<ContentPart>`。权威规则在 `configs/personas/cyrene.yaml`。
|
||||
- `<p>…</p>` 每段一个气泡；无 `<p>` 时按空行 `\n\n` 回退切分，单个 `\n` 不切。
|
||||
- `<action>` / `<narration>` → 灰斜体旁白，依附气泡：首部连续块在上、尾部连续块在下、中间块上提到 head。
|
||||
- 兼容漂移：全角 `＊…＊`（短于 40 字符且无换行 → action）；半角 `*…*` **仅当以 动作/旁白/内心/神态/轻声 开头**才算旁白，否则保持普通文本。
|
||||
- **流式增量解析**：delta 会把标签切半（`<act` + `ion>`）→ 带缓冲的增量解析器，保留尾部未完成片段，只在能确定边界时产出；未闭合 `<p>` 不显示直到闭合。行为对齐 Web 端 `parseContent.ts` + `chat.tsx`。
|
||||
- **mode 回落**：~~后端不落库（`02/A3`）→ P0 全部按 `chat` 渲染。~~
|
||||
⚠️ **2026-10-04 更正：已落库**（后端 `b686d5f`，见 `02` 的 `A3` 行与「回执五」补记第 5 条）——客户端按 `mode` 分支：
|
||||
`ui/chat/MessageBubble.kt:110` 的 `val isChat = message.mode.isNullOrBlank() || message.mode == "chat"`
|
||||
（只有 `chat` 才按 markup 解析 `<p>` 切气泡；其余 mode 走单块纯文本兜底，`null` / 空白同样回落 `chat`）。
|
||||
- **thinking / tool_call**：仅 WS 实时有；历史思维链按需请求 REST `/messages`（D11）。工具卡把 `tool_call.delta`（参数 JSON）与 `tool_execution.update` 的 `delta`（局部输出）分两块渲染；执行状态由 `tool_execution.start/update/end` 的 **`phase`**（`running`/`done`/`error`）驱动，三帧按 **`id`** 关联到对应的 `tool_call.*`（契约 v0.50；这三帧不带 `index`）。
|
||||
- **图片**：Coil 加载；base64 先读尺寸再决定是否解码，避免 OOM。
|
||||
- **Markdown**：P0 不渲染，代码只给等宽字体 + 横向滚动。
|
||||
|
||||
---
|
||||
|
||||
## 6. UI / Miuix 落地
|
||||
|
||||
| 需求 | 方案 |
|
||||
|---|---|
|
||||
| 顶栏 + 汉堡 | `SmallTopAppBar(navigationIcon = { IconButton { Icon(MiuixIcons.Sidebar) } })` |
|
||||
| 侧边栏 | **自研 `MiuixDrawer`**：`AnchoredDraggableState` + scrim + `Modifier.offset` lambda 版；汉堡开、抽屉内拖拽关；**不做左边缘滑出**（与系统返回手势冲突）；`BackHandler` 关抽屉 |
|
||||
| 气泡 | **自研**：`Surface` / `Card` + `RoundedCornerShape`，最大宽度 `min(0.78 × 屏宽, 600dp)` |
|
||||
| 列表 | `LazyColumn`（Foundation）+ `overScrollVertical()` + `VerticalScrollBar`，`key = id` |
|
||||
| 输入 / 按钮 / 设置 / 弹窗 / 提示 / 加载 | `TextField` / `IconButton`+`FAB` / 全套 `*Preference` / `OverlayDialog`（须在 `Scaffold` 内）/ `Snackbar`+Host / `ProgressIndicator` |
|
||||
| IME | Miuix `Scaffold` 默认只处理 `systemBars ∪ displayCutout`，需自行 `imePadding()` |
|
||||
| 毛玻璃 | 只用在顶栏 / 底栏，不大面积铺；<33 已在 D4 排除 |
|
||||
|
||||
**侧边栏信息架构**
|
||||
|
||||
```
|
||||
├─ 会话（主 / 次级）
|
||||
├─ IoT（预留）
|
||||
├─ App 设置
|
||||
├─ 管理（owner 可见）→ 独立导航图 + 独立 Scaffold，只读监控
|
||||
│ ├─ 概览（metrics / trace）
|
||||
│ ├─ 后台思考
|
||||
│ ├─ 记忆
|
||||
│ └─ 人格
|
||||
└─ 关于 / 登出
|
||||
```
|
||||
|
||||
- **管理员页范围**（D15/D16）：只做**只读监控**；渠道配置、LLM、RAG、插件、用户、自动化、系统危险操作全部归 **Web 后台**。危险操作即使将来做也必须 `OverlayDialog` 二次确认。
|
||||
- P0 管理员页只放入口占位（显示「规划中」），P2 再实现。
|
||||
|
||||
---
|
||||
|
||||
## 7. P1 语音（依赖后端）
|
||||
|
||||
- **第一件事是 spike，不是写 UI**：`VOICE_INTERACTION_SERVICE` 只保证系统「助手入口」能指向本 App；**MIUI 是否允许把第三方设为默认助手、长按电源键能否唤起**必须真机验证（不写代码，10 分钟）。验不过就换触发：系统助手手势 / 桌面快捷方式 / 通知磁贴 / 蓝牙耳机键 / App 内按钮。
|
||||
- **链路（已按后端现状修正）**：`AudioRecord` 录音 → WAV → `POST /audio/transcribe`（REST，绕 4KB）→ 文本 → **WS `chat`**（落库 + 流式 + 编排）→ 回复 → `POST /audio/speech`（**返回裸音频字节，非 `{data}` 信封**）→ `AudioTrack`/ExoPlayer 播放，支持打断。
|
||||
- **不用 `voice_input` 提交对话**：该路径不落库、不过编排器、无 `message_persisted`（`02/C1`）。
|
||||
- 权限：`RECORD_AUDIO` 运行时申请；录音期间可选前台服务。
|
||||
|
||||
---
|
||||
|
||||
## 8. 里程碑与验收
|
||||
|
||||
| 里程碑 | 内容 | 验收 |
|
||||
|---|---|---|
|
||||
| **M0 骨架** | Gradle + 依赖 + Miuix 主题 + 空壳首页 | `./gradlew :app:assembleDebug` 通过，App 起得来 |
|
||||
| **M1 登录** | 服务器地址可配 + 错误分类 + EncryptedPrefs + 自动登录 + 401 登出 | 错地址有本地文案、对地址能进；杀进程重开免登；token 失效自动回登录 |
|
||||
| **M2 只读主会话** | WS 连接 + `history` + REST 分页 + 倒序渲染 + 来源角标 + 会话列表回退 | 断网重开列表不白屏；进主会话看到历史；上拉翻页无重复；每条标来源 |
|
||||
| **M3 发送 + 流式** | `chat` 上行 + 乐观消息 + 流式气泡 + 忙碌/队列状态 + 失败重试 | 发消息立即上屏；流式逐字出；Web 端同步可见；忙时提示排队 |
|
||||
| **M4 富渲染** | `<p>` 拆气泡 + 旁白 + thinking/工具卡 + 图片 | 多气泡与旁白位置正确；流式半截标签不崩；图片正常显示 |
|
||||
| **M5 多会话 + 侧边栏** | 自研 Drawer + 新建/切换/删除 + 序号持久化 | 汉堡开合顺滑；次级可建可删；主会话禁删；重启记得上次会话 |
|
||||
| **M6 打磨** | 设置页、空态/错误态、无障碍、性能 | 字体放大不炸；冷启动 < 1.5s；无内存泄漏 |
|
||||
|
||||
**P1**：语音 spike → 全屏助手 UI → 语音闭环。
|
||||
**P2**：管理员页只读监控、IoT、主动推送（依赖 `02/D1`）、多角色。
|
||||
|
||||
---
|
||||
|
||||
## 9. 待定项
|
||||
|
||||
1. 消息历史快照是否改用 `EncryptedFile`（当前建议：私有目录 + 关备份，P0 够用）。
|
||||
2. 管理员页 P0 是否只占位（当前建议：是）。
|
||||
3. `CONTRACT.md` 是否现在就建（建议 M2 之前建）。
|
||||
4. 语音 spike 的具体验证清单与机器。
|
||||
@@ -1,138 +0,0 @@
|
||||
# 04 — 构建环境与开发流程
|
||||
|
||||
> 现在**开发全程在 PC（Meowhome）上**：写码、编译、单测都在那边；**后端（Cyrene v2 主项目）也已迁到同一台 PC**。
|
||||
> 本文记录 PC 的环境、镜像配置、日常流程和踩过的坑，换机器/重装时照抄即可。
|
||||
> （旧开发机是一台性能较弱的 aarch64 Linux 容器，已停用；相关记录见 §5 备查。）
|
||||
> 最后更新：2026-10-03
|
||||
|
||||
---
|
||||
|
||||
## 1. 机器分工
|
||||
|
||||
| 角色 | 机器 | 系统 / 架构 | 接入方式 | 干什么 |
|
||||
|---|---|---|---|---|
|
||||
| **开发 + 编译** | `Meowhome`（主机名 `AEiva`） | Windows / **AMD64** | `ssh Meowhome`（`cd.yeij.top:40022`，密钥 `~/.ssh/id_ed25519_meowhome`） | 写码、`gradlew.bat` 编译、跑单测 |
|
||||
| **后端** | 同一台 PC | — | 同上 | Cyrene v2 主项目 |
|
||||
|
||||
> 后端现在跑在这台 PC 上；App 的「服务器地址」填 PC 上的后端地址（模拟器 `10.0.2.2`，真机走局域网 IP；**具体端口以主人给的为准**）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 版本组合（钉死，别随意升）
|
||||
|
||||
| 项 | 版本 | 备注 |
|
||||
|---|---|---|
|
||||
| AGP | **9.2.1** | 9.x 起**内置 Kotlin**，不能再应用 `org.jetbrains.kotlin.android` |
|
||||
| Kotlin | **2.4.0** | 由 Miuix 0.9.3 的元数据牵引 |
|
||||
| Compose BOM | **2026.05.01** | 它 pin 的 `androidx.compose:ui:1.11.2` 正好等于 Miuix 0.9.3 在 Android 上的映射 |
|
||||
| Miuix | **0.9.3** | 只有 0.9.x；AAR 要求 `minCompileSdk=37` |
|
||||
| Gradle | **9.7.1** | wrapper 已配腾讯镜像 |
|
||||
| JDK | 本机 17 / PC **21** | AGP 9 需要 17+ |
|
||||
| minSdk / compileSdk / targetSdk | 33 / 37 / 37 | 33 起是为了解锁 `miuix-blur` |
|
||||
| buildToolsVersion | **37.0.0** | 必须显式指定，否则 AGP 默认找 36.0.0 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 本机（aarch64 容器）
|
||||
|
||||
SDK：`~/Android/Sdk`
|
||||
|
||||
| 组件 | 来源 |
|
||||
|---|---|
|
||||
| `platforms/android-37.0` | 腾讯镜像 `platform-37.0_r02.zip` 手工解压 + **手写 `package.xml`** |
|
||||
| `build-tools/37.0.0` | **ARM64 原生版**，来自 [Commit451/android-arm-build-tools](https://github.com/Commit451/android-arm-build-tools)（release 资源需经 `https://ghproxy.net/` 代理下载），逐个校验 SHA256 |
|
||||
| `licenses/` | `android-sdk-license` / `android-sdk-preview-license`（标准哈希） |
|
||||
|
||||
本机专用配置放在 **`~/.gradle/gradle.properties`**（不进仓库）：
|
||||
|
||||
```properties
|
||||
android.aapt2FromMavenOverride=/home/Aska/Android/Sdk/build-tools/37.0.0/aapt2
|
||||
android.builder.sdkDownload=false
|
||||
```
|
||||
|
||||
- 第一条：Google Maven 的 aapt2 只有 x86_64，aarch64 必须指向本地 ARM 版。
|
||||
- 第二条：本机访问不了 `dl.google.com`，禁止 AGP 联网拉 SDK 清单（否则会卡住）。
|
||||
|
||||
镜像：Maven → 阿里云（`settings.gradle.kts`）；Gradle 发行包 → 腾讯（`gradle-wrapper.properties`）。
|
||||
|
||||
---
|
||||
|
||||
## 4. Meowhome（Windows）
|
||||
|
||||
SDK：`C:\Users\Aska\AppData\Local\Android\Sdk`（**不在环境变量里**，是 Android Studio 默认位置）
|
||||
|
||||
- `build-tools/37.0.0` 已有（Windows 原生 `aapt2.exe` / `aidl.exe` / `zipalign.exe` / `d8.bat`）
|
||||
- `platforms/android-37.0` **本机没有**，已用腾讯镜像 `platform-37.0_r02.zip` 补装，并补了 `package.xml`
|
||||
- `JAVA_HOME` = `C:\Program Files\Microsoft\jdk-21.0.11.10-hotspot\`
|
||||
|
||||
项目目录：`D:\Project\Code\Uni\Cyrene-For-Android`
|
||||
|
||||
```bat
|
||||
git clone ssh://git@git.yeij.top:2222/AskaEth/Cyrene-For-Android.git -b android .
|
||||
echo sdk.dir=C:/Users/Aska/AppData/Local/Android/Sdk> local.properties
|
||||
gradlew.bat assembleDebug
|
||||
```
|
||||
|
||||
> `local.properties` 在 `.gitignore` 里，每台机器自己建。
|
||||
|
||||
PC 网络：`dl.google.com` 与腾讯镜像均可达（HTTP 200），但**按约定仍走国内镜像**。
|
||||
|
||||
### 4.1 工作副本同步记录（2026-10-03）
|
||||
|
||||
Windows 侧工作副本改为**从本机整树同步**（不再 `git clone`），已含 gitignored 的 `devdocs/`：
|
||||
|
||||
- HEAD = `9bc45dc`（= `origin/android`），工作树干净；83 个源码/资源文件与本机逐字节一致（`local.properties` 例外，各机自建）。
|
||||
- 验收：`gradlew.bat testDebugUnitTest --no-daemon` → **BUILD SUCCESSFUL**（JDK 21，49s）。
|
||||
- 坑：仓库 `core.filemode` 在 Windows 侧要设 `false`（值为 Linux 的 `true` 时，`gradlew` 会因丢失可执行位一直显示 `M`，内容其实没变）。
|
||||
- 同步方法：源码走 `tar | ssh` 解包，**中文文件名的 `devdocs/` 必须用 `scp`**（Windows 自带 bsdtar 解不出 UTF-8 文件名，会写出乱码副本）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 历史：上一阶段的真机流程（已停用）
|
||||
|
||||
> 这一节是上一阶段「把手机当运行目标」的做法，**现在不需要了**，留档备查。
|
||||
|
||||
- 手机（OnePlus PLK110 / Android 16）已 root（KernelSU），`su -c` 可用。
|
||||
- 装 APK（手机上的 Termux sshd，端口 2022）：
|
||||
```bash
|
||||
ssh -p 2022 aska@127.0.0.1 'cat > ~/cyrene.apk' < app-debug.apk
|
||||
ssh -p 2022 aska@127.0.0.1 'su -c "cp /data/data/com.termux/files/home/cyrene.apk /data/local/tmp/ \
|
||||
&& chmod 644 /data/local/tmp/cyrene.apk && pm install -r /data/local/tmp/cyrene.apk"'
|
||||
```
|
||||
- 截图 / UI 自动化：
|
||||
```bash
|
||||
su -c "screencap -p /data/data/com.termux/files/home/shot.png; chmod 644 /data/data/com.termux/files/home/shot.png"
|
||||
# 取回：ssh ... 'cat .../shot.png' > local.png（scp 会被 Termux 启动 banner 污染，不能用）
|
||||
```
|
||||
**坑**：中文输入法会把 `//` 打成 `、`、`.` 打成 `。`，用 `input text` 填 URL 会失败。
|
||||
|
||||
---
|
||||
|
||||
## 6. 日常流程
|
||||
|
||||
1. **本机**改代码（+ `devdocs/` 写文档，不进仓库）
|
||||
2. `git commit` → `git push origin android`
|
||||
3. **PC**：`cd /d D:\Project\Code\Uni\Cyrene-For-Android && git pull && gradlew.bat assembleDebug`
|
||||
4. **取回**：`scp Meowhome:D:/Project/Code/Uni/Cyrene-For-Android/app/build/outputs/apk/debug/app-debug.apk .`
|
||||
5. **装真机**（见 §5），看效果
|
||||
|
||||
---
|
||||
|
||||
## 7. 踩坑记录
|
||||
|
||||
| 现象 | 原因 / 解法 |
|
||||
|---|---|
|
||||
| Maven 依赖拉不下来 | `dl.google.com` / `maven.google.com` 不通 → 仓库加阿里云镜像 |
|
||||
| `aapt2: 可执行文件格式错误` | aarch64 机器上跑的是 Google 的 x86_64 二进制 → 换 ARM64 版 + `aapt2FromMavenOverride` |
|
||||
| `Failed to find Platform SDK with path: platforms;android-37.0` | 手工解压的 SDK 包缺 `package.xml` → 补上（从 `android-35` 的模板改） |
|
||||
| `Failed to find Build Tools revision 36.0.0` | AGP 默认 build-tools 版本 → `buildToolsVersion = "37.0.0"` |
|
||||
| `The 'org.jetbrains.kotlin.android' plugin is no longer required` | AGP 9 内置 Kotlin → 移除该插件 |
|
||||
| `Unresolved reference 'KotlinSerializationConverterFactory'` | Retrofit 3 用 `@file:JvmName` 暴露，Kotlin 侧要用扩展函数 `json.asConverterFactory(...)` |
|
||||
| `MiuixIcons.Sidebar` 解析不到 | 实际是 `MiuixIcons.Basic.Sidebar`（文档与 API 有出入，以 AAR 为准） |
|
||||
| `/tmp` 放东西撑内存 | 本机 `/tmp` 是 tmpfs（内存盘）→ 临时文件放 `~/.cache/` |
|
||||
| 填 `http://…` 登录报「网络不可用」 | Android 9+ 默认禁止明文 HTTP，OkHttp 抛 `UnknownServiceException`（属 `IOException`）被映射成无网 → 加 `res/xml/network_security_config.xml` 放行 cleartext + 信任用户 CA |
|
||||
| 模拟器后台启动设了超时 → 到点被收割 | **别给要常驻的进程设超时**。踩过一次：1800s 上限到点把模拟器杀了，`adb reverse` 隧道一起没了 → 模拟器一律不加超时 |
|
||||
| `adb shell … /sdcard/…` 报 `ls: C:/Program: No such file or directory` | Git Bash 把设备路径当 Windows 路径改写 → 命令前加 `MSYS_NO_PATHCONV=1` |
|
||||
| 往 8080 打 `/api/v1/*` 拿到一张 HTML 404 | **这台机器的 8080 是个 PHP 应用**（`X-Powered-By: PHP/8.4.1`），Cyrene 在 **10942**。别把「看起来像后端的 HTML 404」当成「后端起不来」。详见 `05` 的后端一节 |
|
||||
| 模拟器里填 `10.0.2.2` 不通 | 这个 AVD **没有网络接口** → 用 `adb reverse` + `127.0.0.1`。详见 `05` 的模拟器一节 |
|
||||
| 提交时满屏 `LF will be replaced by CRLF` | 纯提示、无害（`core.autocrlf` 归一化）；既有文件也一样，非某次改动引入 |
|
||||
@@ -1,418 +0,0 @@
|
||||
> **归档**：本文件由 `05-开发进度与交接.md` 拆出，存放 **W4–W7 起的各历史批次详细记录**与已过时的验收现场记录（原样搬运、按原文顺序，只读追溯）。
|
||||
> 当前状态、待办、家务、纪律与「★ 恢复锚点」各节都在 `05-开发进度与交接.md`；锚点里说的「上面各批次」即指本文件。
|
||||
|
||||
### 本轮追加（2026-10-04 深夜 · 三个 worktree 并行 + 合并验收）
|
||||
|
||||
**合并后 353 测试全绿**，正好 `272+11+33+37`——加法和实际一致，就是「文件集互不相交」成立的证据。合并**零冲突**（merge commit：`51ea890`/`b44e8d9`/`664fd8d`）。
|
||||
|
||||
- **D4 未读**（`f413f8d`）：抽屉角标（Miuix `Badge`，放**标题行内**、带 `content-desc="未读 N"`、溢出 `99+`）
|
||||
+ 已读游标。**已实机端到端验证（服务端证据）**：API `unread=6` 且角标「未读 6」→ 点该行 →
|
||||
logcat `POST /sessions/web/read (2-byte body)` → `200` → API `unread=0`、角标消失。
|
||||
读标记策略：**只在两处**推进——`select()`（进入会话）与「`message_persisted` 命中当前会话」；
|
||||
**不在 `refresh()` 里做**（会把设置/管理页打开期间到达的消息静默吞掉）。
|
||||
- **A2 `interrupt scope`**（`b780695`）：`WsOutbound.Interrupt` 增可选 `scope`；设置项「她忙时发消息」=
|
||||
**追加队列**（默认档，**根本不发 `interrupt`**）/ **打断**（`scope:"current"`：只取消在跑回合、**保留队列**）。
|
||||
默认档**逐字节等于旧帧**，有测试钉住。**设置项渲染已实机验证**。
|
||||
⚠️ 契约里 `all` 是「**清空 pending**」，所以「追加队列」**不能**映射到 `all`（那样自相矛盾）。
|
||||
> ⚠️ **补记（W25，`feat/W25-interrupt-scope`）**：`b780695` 只做了「**设置项 + 帧形状**」——
|
||||
> **没有任何发送路径读这个偏好**，所以那之后「打断」与「追加队列」行为完全一样（开关空转），
|
||||
> `ChatSocket.sendInterrupt` 也一条帧都没发过。现已接上：判据 `interruptScopeForSend(mode, busy)`，
|
||||
> **默认档恒不发帧**（线上逐字节不变）、选「打断」且**会话正忙**才发 `scope:"current"`、
|
||||
> **命中空闲会话不发**（服务端 no-op，白发只多一次往返）；「正忙」只认服务端 `session_busy` 的
|
||||
> `busyMode != null`，**不用** `queueDepth`（队列非零 ≠ 有回合在跑）。接线点在
|
||||
> `ChatViewModel.deliver()` 的通道分支之前，每次投递**最多一条**打断帧。
|
||||
- **B1 `/upload`**（`cc2f266`）：图片分流——**重编码后 >64 KiB 走上传（历史只留 URL），否则内联 base64**。
|
||||
阈值理由是「内联的成本是**发多少次**而非发一次」：服务端把 `image` 原样落库 ⇒ 每页历史/每次 WS 回放
|
||||
都重传。✅ **已实机端到端验证**（2026-10-04 深夜）：209 KB 图经 Photo Picker 发出 → logcat
|
||||
`POST /api/v1/upload (96764B)` → `201 Created` → `POST /api/v1/chat (243B body)`（243 字节 ⇒ 带的是
|
||||
**URL 不是 base64**）→ 落库 `image` = `…/api/v1/files/<32hex>.png` → **冷启动 force-stop 重开后仍渲染**
|
||||
（Coil 网络 fetcher 正常）→ 且**模型真的读懂了图**（那张图是模拟器截图，她逐条点评了图里的设置项）。
|
||||
⚠️ 未变：`url` 绑死请求时的 `r.Host`（换服务器地址后旧图取不回，`02/F6①`）；上传产物**无删除端点**（`02/F7`）。
|
||||
|
||||
**下一步（顺序已定）**：① ✅ **已完成**（W3 上传路径实机验收，见上）→ ② **分享入口**（`ACTION_SEND` /
|
||||
`ACTION_SEND_MULTIPLE` + `singleTop`/`onNewIntent` + pending-share 持有者 + 登录后落地）→
|
||||
③ 搜索 / 编辑删除 / `mode` / `after` → ④ 概览「按路径」可读性 → ⑤ 超限走文件（按 v0.59）。
|
||||
|
||||
> ⚠️ **更正上文「当前状态」**：`664fd8d` 已过时。最新提交 **`a6b4bae`**（= `origin/android`，四个模块全部已推）。
|
||||
|
||||
**并行批次 W4–W7 —— ✅ 全部完成、已合并、已推送**（2026-10-04 深夜）。按开发纲要「多个并行子代理协同」
|
||||
切分：四个 worktree、**文件集互不相交**（`D:/Project/Code/Uni/Cyrene-Android-W{4,5,6,7}`，分支
|
||||
`feat/W4-overview` / `feat/W5-persona` / `feat/W6-documents` / `feat/W7-share`，全部从 `664fd8d` 切出）：
|
||||
|
||||
| 模块 | 内容 | 测试增量 | 合并点 |
|
||||
|---|---|---|---|
|
||||
| W4 | 概览页「按路径」26 条的可读性重做（分组/折叠，Miuix） | 353 → 370（+17） | `f91a855` → `a6b4bae` |
|
||||
| W5 | 新建会话时**选角色**（`POST /sessions {personaId}`，v0.42） | 376 → 408（+32） | `217cfe3` → `557cdb2` |
|
||||
| W6 | 文档/文件进对话（`documents`）**数据层 + 纯逻辑**，不碰 UI/VM | 408 → 468（+60） | `095d6e7` → `a80dac7` |
|
||||
| W7 | **分享到 App**（`ACTION_SEND(_MULTIPLE)` + `singleTop`/`onNewIntent` + 进程级暂存） | 353 → 376（+23） | `ae4e4e5` → `4834905` |
|
||||
|
||||
**四轮合并在主树跑的都是 `assembleDebug` + `testDebugUnitTest --rerun-tasks`**（不是 FROM-CACHE），
|
||||
**最终 485 测试 / 0 失败 / 0 错误**（= 353 + 17 + 32 + 60 + 23，加法逐轮吻合——这正是「文件集互不相交」
|
||||
成立的证据）。每轮我都自己读了 `app/build/test-results/testDebugUnitTest/*.xml` 求和，**不采信子代理自述**。
|
||||
|
||||
- **A1 / D14 完成**（`d12a920`，2026-10-04）：`WsEvent` 的所有结构化流式事件类**透传帧壳上的 `sessionId`**
|
||||
（此前解析器把该字段丢掉），`ChatViewModel.onEvent` 用 `WsEvent.isForSession` **按会话过滤**——
|
||||
`sessionId` 为空仍放行（行为与修复前一致）。回归测试 `data/ws/WsEventSessionScopeTest.kt`（+16）。
|
||||
**D14「同一时刻只有一个会话在流式」退役**；核实结论：它**从来只是文档约定**，代码里从未强制
|
||||
（`ChatSocket.sendInterrupt` 至今零调用方）
|
||||
- **M0–M5 全部完成**，M4 完整（多气泡 / 旁白 / 思维链 / 工具卡 / 图片）
|
||||
- 交互打磨 B 完成（回车发送、文本选择模式、自动跟随底部、IME 修复）
|
||||
- 设置页 C-1 完成（主题 / 旁白 / 思维链默认展开 / 关于）
|
||||
- **C-2 管理员只读监控完成并已实跑验证**：概览（metrics + trace）/ 人格 / 记忆 / 后台思考
|
||||
四页只读，按 RBAC 分档自动降级（viewer 只能进概览 + 人格），管理区为可加页的壳 + 独立 `Scaffold`
|
||||
- **B4 完成**（`09a3222`）：接入 `GET /api/v1/meta/enums` 权威枚举表，删掉客户端硬编码的
|
||||
`platform` / `mood` / `mode` 映射表——顺带修掉一处既有漂移（客户端把 `web` 显示成「Web」，
|
||||
权威表是「网页」）
|
||||
- **B2 完成**（`f557654`）：接入 `/auth/refresh`，**登录口令不再落盘**（迁移对用户无感）；登出补调
|
||||
`/auth/logout`；可恢复的 401 不再登出；并发 401 由单飞刷新 + 代际守卫兜住
|
||||
- **A4 / D5 / B3 完成**（`c09a211`）：会话列表改用**服务端标题**（本地「会话 N」序号机器整块退役）、
|
||||
置顶（主会话与次级都可）、最后消息预览；并补上**抽屉打开时静默刷新**——此前只在初始化 /
|
||||
新建 / 删除时拉取，所以这些内容要重启 App 才可见；顺带修掉「快照指纹闸门没实装」与
|
||||
「预览剥标签导致旁白与正文粘连」两处既有缺陷
|
||||
- **`history` 串台已修**（`2a49c25`）：WS 首帧 `history` 是**主会话**的回放，此前被无过滤地并进
|
||||
每一个 `ChatViewModel` → 进次级会话会看到主会话的消息。现按**消息自身的 `sessionId`** 过滤
|
||||
（`historyForSession`，空值放行）
|
||||
- **工具执行三帧已接**（2026-10-04）：后端契约 v0.50 把 `tool_execution` 拆成
|
||||
`start` / `update` / `end`（载荷 `{tool, phase, id?, delta?}`，**无 `index`**，不属于模型流）。
|
||||
此前本端只映射 `.update` 且读的是 `tool_call.*` 的 DTO（`start` / `end` 落到未知类型分支被
|
||||
**静默丢弃**，而 `.update` 后端**没有生产者**）→ 工具执行状态根本到不了 UI。现三帧各有事件类
|
||||
与解码 DTO，`ChatViewModel` 按 **`id`** 把它们关联到工具卡（`toolExecutionTargetIndex`；`id`
|
||||
缺席时只在**无歧义**时才落位，绝不默认落第一张），工具卡标题/配色由 `phase` 驱动
|
||||
`running → 执行中` / `done → 完成` / `error → 失败`。回归测试
|
||||
`data/ws/WsEventToolExecutionTest.kt` + `ui/chat/ToolExecutionCorrelationTest.kt`
|
||||
|
||||
**待做**
|
||||
1. **遗留（本端，均为既有问题）**：
|
||||
- **① 连接所有权**：每个 `ChatScreen` 的 VM 各建一条 `ChatSocket`，而 VM 存在 **Activity 级
|
||||
`ViewModelStore`** 里，所以**访问过的每个会话都永久留一条连接**（含各自的 `OkHttpClient`
|
||||
与连接池），**删会话也不回收**；后端还会把每帧广播给每条连接。**已不再串台**（`d12a920`
|
||||
加了会话闸），现在纯粹是资源 / 生命周期成本。自然解法：**共享一条 socket + 按会话路由**。
|
||||
- **② `ChatSocket.sendInterrupt` 零调用方**——「切会话时打断」这个出口从未接线，是死 API。
|
||||
（原 ② 的工具执行帧解析缺口已修，见「当前状态」最后一条。）
|
||||
2. **概览页「按路径」的可读性**：26 条路径挤在一行右对齐文本里，手机上很密——是否改成分组/折叠，
|
||||
待主人定
|
||||
3. 子会话流程（主人已确认搁置）
|
||||
4. 图片 / 工具卡实机验证（后端暂未配置工具）
|
||||
2. **概览页「按路径」的可读性**：26 条路径挤在一行右对齐文本里，手机上很密——是否改成分组/折叠，
|
||||
待主人定
|
||||
3. 子会话流程（主人已确认搁置）
|
||||
4. 图片 / 工具卡实机验证（后端暂未配置工具）
|
||||
|
||||
**接下来可做的大块**（后端都已就绪，几乎全是纯客户端欠账）：
|
||||
|
||||
1. **REST `POST /api/v1/chat`（`stream:true`）** —— 当前性价比最高的一步：
|
||||
- 解决「**长文发不出去**」：WS 帧硬上限 4096 字节，且**超限是直接断连**（不是报个错），
|
||||
而客户端**只有 WS**
|
||||
- 解决「**图片完全发不了**」：大图走 REST + base64（**先缩放 / 重编码**，见 `02/G3`）
|
||||
- 是「分享到 App」的前置（`02/F1–F4`）
|
||||
- **已侦察确认**：REST 发起的回合**会**在已连接的 WS 上流式回来（`stream:true` 与
|
||||
`stream:false` 都会，同一个 orchestrator + 广播路径），所以能做到「**REST 发、WS 收**」，
|
||||
**不牺牲流式体验**
|
||||
- ⚠️ 两个坑必须一起处理：`stream:true` 走**有损总线**且**先回 200**，可能静默什么都没发生
|
||||
（`02/G2`）→ 以 `message_persisted` 为准 + **绝不自动重试**；全链路**无幂等**（`02/G4`）
|
||||
2. ~~**顺带解除 A1 / D14**：后端 v0.36 起流帧**已带 `sessionId` + `turnId`**，是本端 `WsEvent`
|
||||
把字段丢了（`02/G1`）→ 透传并按会话过滤，即可退役「同一时刻只有一个会话在流式」这条长期约束~~
|
||||
→ ✅ **已完成**（2026-10-04）：`WsEvent` 全部流式事件类透传 `sessionId`，`ChatViewModel.onEvent`
|
||||
按 `isForSession` 过滤（`null` 仍放行）；回归测试 `data/ws/WsEventSessionScopeTest.kt`。
|
||||
D14 **确认只是文档约定**，代码里从未强制。**未做**：连接所有权（每 VM 一条 socket、旧 socket 不关）
|
||||
仍是遗留问题
|
||||
3. 其余纯客户端欠账：A3 `mode` / D2 会话内搜索 / D3 消息编辑删除 / A5 正向增量 /
|
||||
D4 未读（后端 v0.37 已实现）
|
||||
4. **M6 打磨**（空态错误态、字体放大、冷启动 <1.5s、内存泄漏）与 **P1 语音**
|
||||
（先真机 spike，验不过就换触发方案）
|
||||
|
||||
## ② 分享到 App —— 三条路径全部实机通过（2026-10-04 深夜）
|
||||
|
||||
APK = 主树 `a6b4bae` 的产物（`app/build/outputs/apk/debug/app-debug.apk`，46 MB），模拟器 `Pixel_10_Pro_XL`，
|
||||
后端 `adb reverse` 到 `127.0.0.1:10942`。
|
||||
|
||||
| 路径 | 证据 |
|
||||
|---|---|
|
||||
| **装的 APK 真的在分享候选里** | `pm query-activities -a android.intent.action.SEND -t text/plain` 回 `top.yeij.cyrene.app.MainActivity` 且 `launchMode=LAUNCH_SINGLE_TOP`；`-t image/png` 同样在 |
|
||||
| 分享菜单出现 Cyrene | `am start -a android.intent.action.SEND …` → 系统 sharesheet 列出 **Cyrene**（第一条），点中即投递 |
|
||||
| **热启动 · 文本** | 落进会话的是**原样**的 user 气泡（正文一个标记都没加），她读懂了内容；走的 **WS**（logcat 里没有 `POST /chat`，符合「短文本走 WS」） |
|
||||
| **热启动 · 图片** | `POST /api/v1/upload (96764B)` → `201` → `POST /api/v1/chat (243B)` → `200`（243 字节 = **URL 形态**）；落库 `image` = `http://127.0.0.1:10942/api/v1/files/6b442b20….png`；气泡**渲染出了图**，且她**读懂了图里的内容** |
|
||||
| **未登录态先暂存** | 登出 → 把分享 intent 投给 App → 界面**仍是登录页**、logcat **零 POST/GET**（只暂存、不发） |
|
||||
| **登录后自动落地** | 登录（`POST /auth/login` → `200`）后**无需任何手动操作**，那条分享文本自动落进会话（DB 实查），她还回了话 |
|
||||
|
||||
**测试痕迹已清理**：临时会话已删；误落进主会话 `web` 的两条测试消息用 `DELETE /api/v1/messages/{id}` 删除
|
||||
（各回 200），主会话已复原。**服务端另有 5 个孤儿上传文件**（`/api/v1/files/{name}`，无删除端点，见 `02/F7`）。
|
||||
|
||||
### 本轮的坑（下个会话直接用）
|
||||
|
||||
- **`am start` 的 extra 值里不能带空格**：`--es k "a b"` 会被**远端 shell 再拆一次**，`am` 把第二个词当成
|
||||
`pkg`，报 `unable to resolve Intent … pkg=…`。写成无空格字符串，或整体加引号。
|
||||
- **`uiautomator dump` 会静默失败并留下旧文件**：转场/动画期间它可能 dump 不出来，这时 `cat /sdcard/ui.xml`
|
||||
拿到的是**上一次的快照**（本轮据此误判过「还停在分享菜单上」）。对策：**每次用唯一文件名**
|
||||
（`/sdcard/ui$(date +%s%N).xml`）并检查输出是否为 `UI hierchary dumped to: …`。
|
||||
- **sharesheet 里的「Direct Share」卡片（`Share with Cyrene` 那种圆角推荐行）对 `input tap` 无反应**：
|
||||
本轮三次点击都没用，而同一菜单里的**普通应用行**（`Cyrene`）一点就中。⇒ 验收时优先点普通应用行；
|
||||
或直接 `am start -n top.yeij.cyrene/.app.MainActivity -a …`，输出里的
|
||||
`intent has been delivered to currently running top-most instance` 就说明走的是 `onNewIntent`（热启动）。
|
||||
- 抽 `uiautomator` 属性时别用 `s/.*(text|content-desc)="([^"]*)"…/`：`.*` 贪婪，会匹配到后面那个
|
||||
`content-desc` 并把值抽成空。**只匹配 ` text="…"`**（带前导空格）才稳。
|
||||
|
||||
### 本轮之后的新欠账（客户端侧，按优先级）
|
||||
|
||||
1. **可观测性下行帧没接**：契约 v0.55 有 `observability_metrics` / `observability_trace` / `observability_log`
|
||||
（owner/admin，订阅 = 读一次对应 REST），客户端**完全没有 handler**，概览页仍是「进入 / 手动刷新各拉一次
|
||||
REST」。接上才能实时刷新（要动 `WsEvent`）。
|
||||
2. **文档附件的 VM/UI 接线**（W6 只做到数据层）：清单在 `02` 的「接线时要改哪几处」一节
|
||||
（`AppContainer` → `ChatViewModel` 的待发附件与回滚 → `sendViaRest` 带 `documents` → `MessageBubble` 渲染 chips）。
|
||||
**两个产品决定要主人拍板**：正文转文件前要不要先问用户；转成文件后正文还发不发。
|
||||
3. **分享的已知边界**：进程被杀会丢待落地内容（持有者在内存里）；未登录期间界面**不提示**「有一条分享在等登录」；
|
||||
分享一律落在**当前会话**（不能选会话/角色）；多图 = 多回合（4 张 = 4 条消息）。
|
||||
4. **搜索 / 编辑删除 / `after`** 仍是欠账（`mode` 已随轮次落库，客户端 `A3` 已完成）。
|
||||
|
||||
### 交付物
|
||||
|
||||
- 可安装 debug APK：`app/build/outputs/apk/debug/app-debug.apk`（主树 `a6b4bae` 构建，**已实机跑过上面全部路径**）
|
||||
- 仓库：`android` @ `a6b4bae` = `origin/android`，工作区干净，**485 测试 / 0 失败**
|
||||
|
||||
## W8–W10 批次 + 芯片修复（2026-10-04 深夜）
|
||||
|
||||
**四个模块全部合并、已推 `origin/android`，主树每一轮都跑 `assembleDebug` + `testDebugUnitTest --rerun-tasks`**（不是 FROM-CACHE），逐轮测试数我自己读 JUnit XML 求和：
|
||||
|
||||
| 模块 | 内容 | 测试 | 提交 |
|
||||
|---|---|---|---|
|
||||
| W8 | 设置页「版本」行可点 → **关于页**（应用名 / 版本取自 `BuildConfig` / 简介 / 作者 `AskaEth`） | 485 → 487 | `3ed2377` → `f24877d` |
|
||||
| W10 | 接上**可观测性三帧**（`observability_metrics/trace/log`），概览页实时刷新 + 「最近日志」区块 | 487 → 516 | `b5e6f78` → `93941cd` |
|
||||
| W9 | **文档附件全链路接线**：选文件入口（SAF）/ 待发芯片 / 上传 → `chat.documents` / 气泡芯片 / 分享进来的**文件**走文档通道 | 516 → 567 | `30180ab` → `ab76798` |
|
||||
| — | 契约 v0.59 已发布 → 更正 W6 那批「未发布」注释（纯注释） | 567 | `2973391` |
|
||||
| — | `devdocs/` **纳入版本库**（`.gitignore` 移除该条） | — | `2369dd2` |
|
||||
| — | **附件芯片改换行排布**（修主人发现的「多附件被裁到屏幕外」） | 567 | `ca5596a` |
|
||||
|
||||
**已实机验证**：关于页（点版本进 → 返回一次到设置、再一次到聊天，层级正确）；附件芯片换行（主会话那条**三附件**消息现在渲染成三行、三枚芯片与各自的状态行全部可见）。
|
||||
|
||||
### 踩到的坑（重要，别再重复）
|
||||
|
||||
- **模拟器「未响应」弹窗的根因是 AVD 内存配小了**：`hw.ramSize=2048` / `vm.heapSize=256`，而镜像是 **API 37 / 16k page / 1344×2992@480dpi**。冷启 2 分钟后 guest `load average` 冲到 **52.96**，`system_server` / `SystemUI` 被反复挤压 → 不停弹 `isn't responding`。**修法（不动 AVD 配置）**：启动时加 `-memory 6144`；另把闲置的 Gradle daemon 停掉（`gradlew --stop`，两个 daemon 白占 4 GB）→ 宿主空闲内存 5 GB → 13.9 GB，6 GB 后 guest 负载降到 ~20、**ANR 归零**。若要固化，改 `config.ini` 的 `hw.ramSize`（那文件在项目外，需主人点头）。
|
||||
- **在跑构建时 `adb reboot` 会把模拟器卡死在开机中途**：`sys.boot_completed` 永远空、`dev.bootcomplete` 空、logcat 里 init 反复报 `Could not find 'aidl/activity' for ctl.interface_start`（= `system_server` 没起来），此时 `adb install` 会**永远挂住**。**修法：`adb emu kill` 后冷启**，别指望它自己好。
|
||||
- **`uiautomator dump` 会静默失败并留下旧文件** → 每次用唯一文件名；**`am start` 的 extra 值不能带空格**（远端 shell 会再拆一次）；sharesheet 的 **Direct Share 卡片点不动 `input tap`**，点普通应用行或用 `-n` 直投。
|
||||
- **双击坐标复用会点错**：本轮「记住了」的坐标在两次会话里分别落到了「添加文件附件」（意外开了 DocumentsUI，反而算半个正面证据）和「与昔涟」顶栏标题上。**每次都从新 dump 取 bounds**，并按 x/y 区间消歧（抽屉行 vs 顶栏标题同名）。
|
||||
- **提交信息里别用反引号**：`git commit -m "…`文件名`…"` 在双引号里会被 bash 当命令替换执行，信息被吃掉一段（本轮真踩了，已用 `-F 消息文件` amend 修回）。**含反引号的提交信息一律走 `-F`。**
|
||||
|
||||
### 契约侧（已登记 `02`）
|
||||
|
||||
- **`api-client.md` 已发布 v0.59**（§1.2 文档存储与摄取契约 + 端点表 16/17）。我们实现的形状**逐条一致**（`file` 部件名、201/200+`deduped`、20 MiB、≤5、只收 `name`、相对 `url`、嗅探基类型、`documents` 数组含 `chars`/`truncated`/`status`、0 个附件时该键省略、4 个错误码）；白名单在契约里也已更正为 **22 项**。
|
||||
- 新登记的 `02` 项：`F7`（上传产物无删除端点 ⇒ 客户端无法清理孤儿）、可观测性订阅**会被「没有在线 WS 连接」剪掉**（客户端必须持连接）、日志**没有历史引导**（本端还没接 `GET /admin/observability/logs`，所以「最近日志」只显示进页面之后产生的）。
|
||||
- **`G5` 已由后端落地**（`pending_full` 带 `clientMsgId`）⇒ 队列满时客户端从此能**精确定位是哪条气泡被丢**；本端还没接（现状仍会让那条气泡永远挂「发送中…」）——**这是下一批的候选**。
|
||||
|
||||
### 主人给了一个调试用 `X-API-Key`（**owner 级**，值不写进任何文件）
|
||||
|
||||
`GET /api/v1/sessions`、`/api/v1/admin/observability/{metrics,logs}` 全部 200 —— 联调可以**不再用口令登录**（更省事也更干净）。用法：`curl -H "X-API-Key: <值>"`。
|
||||
|
||||
### 新欠账（按优先级）
|
||||
|
||||
1. **附件预览 / 打开**（主人 2026-10-04 问的）：`DocumentRepository.download(name)` 在 W6 就写好了、**零调用方**；消息 DTO 只带引用与统计（契约刻意），所以预览要**按需拉**。要做三件：① `FileProvider`（**manifest 现在没有任何 provider**，`file://` 交给别的 App 会抛 `FileUriExposedException`）② 下载到 `cacheDir/documents/<name>`（名字是内容寻址 + 服务端 `immutable` ⇒ 缓存永不失效）③ 预览要**截断并如实说明**（20 MiB 文本不能一把塞进 `Text`）。**两个决定待主人拍**：点芯片的默认动作（App 内预览 / 交给别的 App / 两者都给）与截断阈值。⚠️ `/documents/{name}` **要 Bearer**，所以**不能**照图片那样让 Coil 直接啃（Coil 用的不是挂了 `AuthInterceptor` 的那个 client）。
|
||||
2. **`pending_full` 的 `clientMsgId` 接线**（后端已就绪，见上）。
|
||||
3. **`GET /admin/observability/logs` 接线**（给「最近日志」补历史引导）。
|
||||
4. 搜索 / 编辑删除 / `after` 仍未动；可观测性 `observability_audit` 后端仍未做（审计仍是 REST）。
|
||||
|
||||
## W11–W12 批次 + 一个实机抓到的真 bug（2026-10-04 深夜）
|
||||
|
||||
| 模块 | 内容 | 测试 | 提交 |
|
||||
|---|---|---|---|
|
||||
| W12 | 「最近日志」接上 `GET /admin/observability/logs` 引导读取（历史 + 帧增量；**viewer 有历史、无增量**） | 567 → 591 | `642bdb1` → `a7dbee8` |
|
||||
| W11 | **附件预览**：点芯片开弹层（云端按需拉、256 KB / 5000 行先到者为准、分块渲染）＋「用其它应用打开」「保存到下载目录」（FileProvider） | 567 → 610 | `27b6910` → `60b0eac` |
|
||||
| — | **修**：保存附件被 SAF 补成双扩展名（`.md` → `.md.txt`） | 634 | `ffa7ed2` |
|
||||
|
||||
**合并后 634 测试 / 0 失败**（= 567 + 24 + 43，加法逐轮吻合）。
|
||||
|
||||
### 这两块的实机验证（这次抓得很细）
|
||||
|
||||
- **W12**：概览页三路并发 `GET /admin/observability/{logs?limit=200, metrics, trace?limit=100}` **全 200** —— logs 的 REST 引导**确实发出去了**，这就是 W10 那个「只显示进页面之后」缺口的闭环证据。
|
||||
- **W11 附件预览**（用的就是 `E2E-DOC` 会话里那条真实附件）：
|
||||
- 点芯片 → 弹层里**显示的正是从服务端取回的内容**（我那张纸条的正文）；logcat 硬证据：
|
||||
`GET /api/v1/documents/809320….md` → **200（95 字节）**；
|
||||
- **零 `FileUriExposedException`**；
|
||||
- 「用其它应用打开」在这台**裸模拟器没有能读 `text/plain` 的应用**时，如实回了一句「没有应用能打开……可以『保存到下载目录』后再处理」，**没有静默失败**；
|
||||
- 「保存到下载目录」→ SAF 的建议名 = **内容寻址存储名**（界面里同时如实写明「原始文件名不会返回给客户端」）→ 落盘 95 字节、内容与弹层一致。
|
||||
- **抓到的真 bug（已修）**：保存那条一开始落盘成 `…e.md.txt` —— `CreateDocument` 传的是**嗅探基类型**（`.md` 也报 `text/plain`），SAF 就按它补了 `.txt`。**修法：保存这条路传 `*/*`**（没有可补的扩展名），而**打开那条路继续用 mime**（那里要的正是「能读懂这段内容的类型」）。重测落盘为 `…e.md`。
|
||||
|
||||
### 新坑
|
||||
|
||||
- **GMS 自己会 ANR**：模拟器上 `Google Play services isn't responding` 会挡在界面前面（**与我们的 App 无关**，6 GB 内存也照样偶发）。对策：`adb shell am force-stop com.google.android.gms`，立刻清掉接着干活。
|
||||
- **`uiautomator dump` 的静默失败要包重试**：本轮把它包成「重试 3 次 + 检查文件非空」才稳定下来。
|
||||
- **「预览 / 打开 / 保存」三条出口的类型选择是不一样的**（见上），别互相套用。
|
||||
|
||||
### 仍欠（按顺序）
|
||||
|
||||
1. **`F7` / 原始文件名**：契约不给 `originalName` ⇒ 保存只能用内容寻址的存储名；已把这件事**写在界面上**（不编假名）。若后端补 `originalName`，客户端只需改一处。
|
||||
2. **`pending_full` 的 `clientMsgId` 接线**（后端已就绪 —— `05` 旧条目里的 G5）。
|
||||
3. 搜索 / 消息编辑删除 / `after`。
|
||||
4. `observability_audit` 帧（后端未做，审计仍是 REST）。
|
||||
|
||||
> 另：`E2E-DOC` 测试会话**暂时保留**当后端异常的现场证据（纯附件回合没有助手消息 + 两次 `knowledge` 工具失败，见 `02` 的最新登记）；对面回执说可删就删。
|
||||
|
||||
## W13–W14 批次（2026-10-04 深夜）
|
||||
|
||||
| 模块 | 内容 | 测试 | 提交 |
|
||||
|---|---|---|---|
|
||||
| W13 | 队列满时**定位并处置那条待发气泡**（`pending_full` / 定向 `chat_busy` 的 `clientMsgId`）——修「气泡永远挂发送中…」 | 634 → 664 | `3b4a790` → `9854cc4` |
|
||||
| W14 | 点气泡里的图片进**全屏查看**（双击/捏合缩放 + 拖动 + 边界钳制，返回键只关弹层）＋「用其它应用打开 / 保存到下载目录」 | 664 → 706 | `557ef3f` → `f109846` |
|
||||
|
||||
**合并后 706 测试 / 0 失败**（= 634 + 30 + 42，加法吻合）。`android` = `origin/android`。
|
||||
|
||||
### W13 的判定顺序（**证据强度优先，改之前先读**）
|
||||
|
||||
1. `clientMsgId` 命中某条待发气泡：`messageId` **非空 ⇒ 收编**（那条其实早就落库/被认领了，不能当失败）；**缺席 ⇒ 回滚**（正文/图片/附件一起还给输入栏 + 一句人话）。
|
||||
2. `clientMsgId` **有值但不命中 ⇒ Ignore**：带键的帧只属于某一次具体发送，键对不上就不是本端这条。**同一帧到两次也落这一档** —— 这是「广播 + 定向双到达」的幂等来源（不靠去重表，靠状态本身：气泡已经不在待发列表里了）。
|
||||
3. `clientMsgId` **缺席 ⇒ 不猜**（老服务端 / 那条消息本就没带键）：待发为空 → Ignore；**恰好一条 → 回滚它**；**两条及以上 → 只提示、一个气泡都不动**。沿用 `toolExecutionTargetIndex` 那条先例。
|
||||
|
||||
### ⚠️ W13 顺手查出的两条「文档与实现不符」
|
||||
|
||||
- `PendingMessage` 的 KDoc 写着「手动重试可以复用同一个 id」，但 `emitAndDeliver` **每次发送都新铸 `localId`** ⇒ 若某次失败其实是「服务端已收下、客户端判成失败」，用户手动重试**会变成第二条消息**（重复）。**要不要做「回滚后按内容指纹复用原键」是产品决定，本模块没擅自改**（改了才对得上 KDoc，但那是行为变更）。
|
||||
- REST `409 chat_busy` 的旧文案已与 WS 侧**统一成同一句**（同一个 code 不该有两种说法）。
|
||||
- 另：`WsEvent` 里**没有新增独立事件类**，而是扩了既有 `Error` 并保留 `code` 原文——因为定向 `error{code:"chat_busy"}` 与既有 `error` 是**同一个 `type`**，一个 type 无法用两个事件类表达。
|
||||
|
||||
### W14 实机验收（都在这台模拟器上点过）
|
||||
|
||||
- 弹层渲染正常（图片本体 + 两条出口 + 「原始文件名不会返回给客户端」那句诚实说明）；**返回键只关弹层**，回到聊天、没退到抽屉/桌面。
|
||||
- 保存落盘 `748a6a73….png`（**96,585 字节，没有被补成 `.png.png`**）—— W11 那条「保存一律传 `*/*`」的结论在图片上同样成立。
|
||||
- ⚠️ **取字节那条路 logcat 看不到**：W14 对能力 URL（`/api/v1/files/{name}`，免鉴权）用的是**裸 OkHttp 客户端**（不发 Bearer、**也不挂 logging**）⇒ 证据改为**设备上的缓存文件**：`cache/documents/748a6a73….png`（96,585 字节，与保存出来的一致）。
|
||||
- **未验**：手势手感（捏合焦点 / 双击判定 / touch slop）只有单测保证；Coil 的 `File` 分支没在真机确认；**待发图**有 20 MiB 上限（发送时 `ChatImagePreparer` 会缩到 ≤5 MiB，所以**落库后**的同一张图正常 —— 只有待发气泡那一段是死胡同）。
|
||||
|
||||
### 后端回执七要点（已入库 `9e03986`）
|
||||
|
||||
- **大附件那道坎修好了**（`51c1672`）：输入护栏上限不再硬编码 262144，改为按推导预算（1M 窗口 ⇒ **699,050 字符**）＋新 env `GUARDRAIL_MAX_INPUT_CHARS` ⇒ **可以恢复大文件路径**；「多份各自撞注入预算」还差一刀（G2b 在跑）。**这也解释了主会话那条 726 KB 的 `.txt` 回合为什么回 `input_length_exceeded`**。
|
||||
- **`X-API-Key` 是纯内存表**：进程重启即全部失效 —— **实测已经 `401`**（后端在这期间重启过）。要长期用 key 需等 K1 落 SQLite，或请主人再签发一个。
|
||||
- IM 侧：bridge 摄取已通，但适配器只上报 URL/ID 不带字节 ⇒ 真机目前只会得到「无法读取：渠道只给了远程引用」。
|
||||
- 面板将新增只读 `GET /api/v1/admin/system/storage`，契约升 **v0.60**（纯新增，客户端忽略未知字段即可）。
|
||||
|
||||
## W15–W16 批次（2026-10-04 深夜）
|
||||
|
||||
| 模块 | 内容 | 测试 | 提交 |
|
||||
|---|---|---|---|
|
||||
| W15 | 手动重试同一条内容时**复用原幂等键**（改过的内容照旧铸新键） | 706 → 729 | `af11a94` → `8b90703` |
|
||||
| W16 | **会话内搜索 D2**（顶栏入口 + 搜索面板 + 点结果定位） | 729 → 737 | `23b46f9` → 见 merge commit |
|
||||
|
||||
**合并后 737 测试 / 0 失败**（= 706 + 23 + 31，加法吻合）。`android` = `origin/android`。
|
||||
|
||||
### W15：三条必须记住的取舍（**改之前先读**）
|
||||
|
||||
1. **指纹是「值比较」不是哈希**：摘要一旦碰撞，两条**不同**的消息会共用一个键、后一条被服务端判重**静默丢掉**。比较只发生在进程内，值比较碰撞面为零、也没有收益可图。
|
||||
2. **正文一个字都不归一**：只多敲一个空格也算「改过」。反过来（归一后再比）会让**用户真打算发的两条消息并成一条**，而「改了却复用旧键 ⇒ 服务端判重 ⇒ 编辑被静默丢掉」才是真正要防的那一半。
|
||||
3. **晚到的 `message_persisted` 刻意不清键**：那条帧恰恰是「服务端其实收下了、客户端当时判成失败」的**证据**；键留着，用户的重试才会被判重而不是落成第二条。**谁按「成功即清」的字面去那里加一句 `forget`，就把这个 case 打回原样。**
|
||||
4. 附件只看**本地 URI（有序）**、不看 `displayName`/`sizeBytes`：那两项是元数据，同一份文件两次查询完全可能一次报得出、一次报不出，不影响「是不是同一份文件」。
|
||||
|
||||
**待主人确认的产品取舍**：记忆是**单槽**（只记最近一次失败那条）。正常流程下更早失败那条的内容早已不在输入栏，所以单槽够用；要改成多槽说一声。
|
||||
|
||||
### W16：搜索的落地形状
|
||||
|
||||
- 入口在**聊天页顶栏**；面板**叠在整页之上**（自带顶栏 + 输入框自动聚焦 + IME 搜索键 + 旁边的放大镜按钮）；结果 = 角色 / 时间 / 命中片段（命中子串加底色）；**四态分明**（未搜 / 搜索中 / **空结果** / **失败**，失败**绝不**画成「没找到」）。
|
||||
- 片段先过 `domain/parse` 的 `parse()` 再拼回**纯文本**（正文/旁白/动作全保留），**绝不把 `<p>`/`<action>` 当富文本**；只在纯文本上加底色。
|
||||
- **分页**：滚到末尾自动 `before + limit`；翻页失败**不清空已有结果**、尾部红字 + 重试、**不自动重试**。
|
||||
- **点结果**：在已加载窗口内 → 关面板 + 滚动定位 + 横幅；**不在窗口内 → 如实说**（按时间分三种措辞）。**没有插临时气泡**——列表是 `reverseLayout`，凭空插一条几千条前的消息会出现在「刚发出的位置」、与自己的时间戳自相矛盾，还会带偏 `followBottom`。要真正并进消息窗得改 `ChatViewModel`（本模块不许碰）⇒ **列为下一批**。
|
||||
- **状态归属**：`SessionSearchViewModel`，按会话各一份（`viewModel(key = "session-search:<id>")`），随 Activity 存活（关面板不丢结果）。
|
||||
- **返回键**：`ChatScreen` 内新增的 `BackHandler(enabled = searchOpen)` 注册在 `ChatHomeScreen` 那几条之后 ⇒ 优先级更高，**先关搜索**；搜索没开时 disabled，既有抽屉/管理页/设置页层级**一个字节没动**。
|
||||
- **未验**：UI 全部没实机跑过（自动聚焦 + IME、高亮对比度、滚动落点、图标长相都只有编译 + 推演）；`q` 只验到 Retrofit 层（对本地假服务端断言原始 URI），**服务端是否真按契约实现 `q` 没验**。
|
||||
|
||||
### 新登记（见 `02`）
|
||||
|
||||
W16 报上来六条**契约没写透**的口径，其中两条值得扫一眼：**`before` 是含还是不含游标**（契约只对 `after` 明说）、**`q` 匹配的是含标记的原始 `content`**（搜 `action` 会命中、但我们**不画高亮**，不假装命中）。
|
||||
|
||||
## 装机验收轮（2026-10-04 深夜 · 设备证据存档）
|
||||
|
||||
主人要求「每项都要**设备证据**，不能只看编译过了」。设备：模拟器 `Pixel_10_Pro_XL`（`-memory 6144`），App 的服务器地址 `http://127.0.0.1:10942`，`adb reverse tcp:10942 tcp:10942`。
|
||||
|
||||
### ② W18 `.pdf` 非文本拒收 —— ✅ 通过
|
||||
|
||||
用 API 造了一份**带文本层的真 PDF**（自拼对象 + 正确 xref，563 字节，文本 `Cyrene PDF e2e: meow-314`）→ `POST /documents` → `POST /chat` 挂进会话 `E2E-PDF`。落库形状：
|
||||
`documents: [{"name":"0efe0a2a….pdf","mime":"application/pdf","size":563,"chars":24,"status":"extracted"}]`
|
||||
（**`chars:24` 正好等于那份 PDF 里那句文本的长度** ⇒ 文本层真被抽取；也顺带证明我拼的 PDF 是合法的。）
|
||||
|
||||
设备上点那枚芯片，弹层显示：
|
||||
|
||||
```
|
||||
附件预览
|
||||
0efe0a2a13c2583568904105946f91a6.pdf
|
||||
PDF · 563 B · 24 字 · 已读入
|
||||
这是 PDF，App 内不预览这类内容，请用「用其它应用打开」或「保存到下载目录」
|
||||
用其它应用打开 / 保存到下载目录 / 关闭
|
||||
服务端只保留了内容寻址的存储名…原始文件名不会返回给客户端
|
||||
```
|
||||
|
||||
⇒ **正文区是那句人话，不是一屏二进制** —— 洞堵住了。截图 `app/build/e2e-shots/w18-pdf-preview.png`。
|
||||
（同时印证了登记进 `02` 的那条「措辞别扭」：芯片说**已读入**、弹层说**不预览**，两句都真。）
|
||||
|
||||
### ③ W15 重试复用幂等键 —— ✅ **可验部分**通过（另半边由单测背书）
|
||||
|
||||
会话 `E2E-RETRY`：
|
||||
|
||||
| 步骤 | 结果 |
|
||||
|---|---|
|
||||
| **硬断开**（`adb kill-server` 掐断 reverse 上的在途连接）→ 点发送 | **失败回滚**：正文 `W15-retry-2` **被还回输入框**，没有变成卡死的「发送中…」气泡 |
|
||||
| 恢复隧道 → 等 WS 重连 → **原样重发** | 服务端**只有 1 条**该内容的消息（**不重复**） |
|
||||
| 落库 | `clientMsgId: local-7c99433b-…` —— 幂等键确实在链路上 |
|
||||
|
||||
⚠️ **如实标明边界**：「复用**同一个** id」那半边在本机**证不出来** —— 那次失败根本没到服务端，所以 id 从未被服务端见过，重试是「铸新键 + 正常收下」，结果同样是**一条**。那半边的证据只有单测（W15 的 13+10、W17 的 16、W21 的 +7，其中一条专门钉住「失败记键 → 重发复用 → duplicate → 屏幕上只剩一条」）。**不许把它说成「设备上验过了」。**
|
||||
|
||||
### ④ W19 消息编辑删除 —— ✅ 通过
|
||||
|
||||
| 环节 | 证据 |
|
||||
|---|---|
|
||||
| 角色门 | 同一条 `⋯`（`content-desc="消息操作"`）：**user** 消息 → 「编辑 + 删除」；**assistant** 消息 → **只有「删除」** |
|
||||
| 编辑弹层 | 标题「编辑这条消息」、内容框里是**原始 content**、右下角**码点计数 `11 / 4000`** |
|
||||
| 编辑执行 | logcat **`PATCH /api/v1/messages/696cdf76…`（32 字节）→ `200`**，恰好一次；服务端同一条 id 内容变成 `W15-retry-2-EDITED`（**原位改、无第二条气泡**） |
|
||||
| 二次确认 | 「删除这条消息？」/「它会从所有端移除，且不可恢复。」 |
|
||||
| 删除执行 | logcat **`DELETE /api/v1/messages/f9c53d22…` → `200`**（56 字节）；服务端那条 assistant **已消失**、界面气泡消失 |
|
||||
|
||||
### ① W16 会话内搜索 —— ✅ **通过**（⚠️ 并附一条我自己制造的假警报与教训）
|
||||
|
||||
**结论先改**：这一项**本来就是好的**。下文保留那条「不可用」的原委，以免重犯。
|
||||
|
||||
真正的设备证据（都取到了）：
|
||||
|
||||
| 环节 | 证据 |
|
||||
|---|---|
|
||||
| 入口 | 顶栏右上角放大镜 `content-desc="搜索会话里的消息"`；它的**可点父节点**是 `[1164,162][1308,306]`（144px = 48dp 标准触控区） |
|
||||
| 打开面板 | **像素确认**：不透明盖满整页、顶栏「搜索会话」+ ✕、输入框**自动聚焦**（蓝色边框）且 IME 弹起、中间「输入关键词，搜索这个会话里的消息」 |
|
||||
| 搜索 | 输入 `W15` 提交 → logcat **`GET …/messages?limit=30&q=W15` → `200`（583 字节）**；顶栏「**2 条命中**」+ 两行结果（`我 / W15-retry-2-EDITED / 10-04 13:32`、`我 / W15-key-test / 10-04 13:30`） |
|
||||
| 点结果定位 | 面板关闭 + 顶部横幅「**已定位到这条消息**」 |
|
||||
| 返回键层级 | 再开面板（dump 数到「搜索会话」= 1）→ 按返回 → **像素确认回到聊天页**（面板关、IME 收起、消息与输入栏都在），`topResumedActivity` 仍 `MainActivity`（没退到抽屉/桌面） |
|
||||
|
||||
**⚠️ 那条假警报的原委（值得记，别再犯）**：我先前连点两次入口后 dump，都「看到聊天页、且多出一个 `EditText [36,339][1176,509]`」，于是判「面板没渲染、尺寸塌了」。**真相是 `uiautomator dump` 在「面板弹出 + IME 动画」期间会静默失败，而我读到了上一次的旧文件**——把「一个正常的输入框」读成了「面板塌掉的残骸」。改用**像素**（`screencap`）一看，面板好端端盖着整页。
|
||||
|
||||
**代价与教训**：我为此派了两个代理去修「非 bug」（W20 零输出挂死 14 分钟、W22 被停掉），**都零改动、没污染仓库**。两条纪律：
|
||||
1. **动代码之前先用像素确认症状**（`uiautomator dump` 只用来取坐标，不用来判定「界面有没有变化」）；
|
||||
2. 当**症状与读出来的结构矛盾**时（根容器 `fillMaxSize()` + 不透明底色 ⇒ 结构上不可能「看不见」），**先怀疑自己的测量**，再怀疑代码。
|
||||
|
||||
**另记一处「不是错但不该这么写」**：`SessionSearchPanel.kt:105` 在 `Column` 里给子项用了 `Modifier.fillMaxSize()`（正确写法是 `weight(1f)`）。实测**当前不影响观感**（面板内容居中正常），所以**我没有改**——没有证据的改动只会引入风险，留在这里备案。
|
||||
|
||||
### 本轮新增的坑（客户端侧方法论，值得单独记）
|
||||
|
||||
1. **`adb reverse --remove tcp:10942` 断不开已经建立的连接**（reverse 规则只影响**新建**连接）⇒ 拿它造「发送失败」是**无效**的（那次发送照样成功落库）。要真断得用 `adb kill-server` / `start-server`。
|
||||
2. **两个子代理同时跑 Gradle 会抢 `~/.gradle/caches` 的文件锁**，表现就是**零输出挂死**（本次 W20 静默 14 分钟就是它）。⇒ 给子代理加「**某条命令 3 分钟无输出就报告**」的约束；也别让它们跑多轮 `--rerun-tasks`。
|
||||
3. **「文件还在」≠「消息还在」**（后端已确认：他们现在有 GC，未引用且超 7 天的文档会被删；`GET /api/v1/files/<name>` 只证明字节在）。⇒ 别拿它当存活证据。
|
||||
4. **`mysql`/`uiautomator dump` 在转场期会静默失败并留下旧文件** ⇒ 唯一文件名 + 重试 3 次 + 检查非空（这条早就记过，本轮又踩到一次）。
|
||||
|
||||
### 验收用的会话（**都留着，未清理**）
|
||||
|
||||
`E2E-DOC`（纯附件回合没助手消息的现场）、`E2E-PDF`（带 PDF 附件、回合正常）、`E2E-RETRY`（含一条**被编辑过**的消息 `W15-retry-2-EDITED`）。主人说清再清。
|
||||
|
||||
## W27（2026-10-04 深夜 · 死代码清理 + `03` 四处过时表述更正）
|
||||
|
||||
**两处清理（都不改行为）**
|
||||
|
||||
- **删 `AdminAccess.availablePages()`**（`domain/admin/AdminAccess.kt`）：全仓（含 `app/src/test`）**调用点 0 处**——
|
||||
`app/src/main` 里只有它自己的声明，测试里 2 处（`AdminAccessTest` 的那 1 条用例，一并删掉）。
|
||||
它已被 UI 那套做法取代：`ui/admin/AdminHomeScreen.kt:101,116` 遍历 `AdminPage.entries` + 每行 `canAccess` 决定是否禁用。
|
||||
- **`ChatImageBudget.SERVER_MAX_CHARS` 不再自己重写膨胀公式**：原来它把 `base64Chars` 的
|
||||
`((n + 2) / 3) * 4` 又内联写了一遍（同一公式两份真相）⇒ 改为
|
||||
`val SERVER_MAX_CHARS = base64Chars(SERVER_MAX_DECODED_BYTES) + PREFIX_ALLOWANCE_CHARS`。
|
||||
⚠️ 代价：该常量由 `const val` 变 `val`（`const` 不允许调用函数）。**取值逐位不变 = `6990572`**
|
||||
（5 MiB ⇒ base64 膨胀 6990508 字符 + 前缀余量 64），由 `ChatSendPolicyTest` 的「独立重算 → 相等」断言继续钉住。
|
||||
|
||||
**`devdocs/03` 四处就地更正**（一律 ~~删除线~~ 保留原文 + 「⚠️ 更正」括注，不动别人的回执段落）
|
||||
|
||||
1. §4「重连补全」——`02/A5` 的 `after` 正向增量**早已接入**（`loadAfter` + `ChatViewModel.catchUp`，`28c3142`）。
|
||||
2. §4「忙碌/队列 UI 映射」——`session_interrupted{dropped}` 那句：客户端**只发** `scope:"current"`，
|
||||
该档 `dropped` **恒为 0**、`all` **从不发** ⇒「丢弃 N 条」在今天的客户端里**不可达**。
|
||||
3. §5「mode 回落」——`mode` **已落库**（后端 `b686d5f`），`MessageBubble.kt:110` 按 `mode` 分支。
|
||||
4. §4「打断模式」——「限制一次只发一条」**已由 W25 修掉**（补记本就写在案，本轮补上依据 `cfdc094` / `feat/W25-interrupt-scope`）。
|
||||
|
||||
> ⚠️ **顺手查到但本轮没动**：`data/ws/WsEvent.kt:272` 的 `SessionInterrupted` KDoc 也写着
|
||||
> 「当前任务取消、pending 清空，`dropped` 为丢弃条数」——与上面第 2 条同一个过时前提。
|
||||
> 它不在本轮允许改动的文件清单里，留给下一个动那个文件的会话顺手更正。
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,96 +0,0 @@
|
||||
# 06 — 开发工作迁至 Meowhome（交接说明）
|
||||
|
||||
> **开发全程在 Meowhome（Windows PC）上进行**：写码、编译、跑单测都在那边。
|
||||
> 后端（Cyrene v2 主项目）**也已迁到同一台 PC**。
|
||||
> 本目录（`devdocs/`）已随本次交接复制到 PC 的项目目录下。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么迁
|
||||
|
||||
旧开发机是一台性能较弱的 **aarch64 Linux 容器**，编译会把桌面卡死。之前的流程是「旧机写码 → 推仓库 → PC 编译」两段式；现在整段开发都放 PC，省掉来回同步和 SSH 搬运。
|
||||
|
||||
---
|
||||
|
||||
## 2. 开发机：Meowhome
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 接入 | `ssh Meowhome`（`cd.yeij.top:40022`，用户 `Aska`，密钥 `~/.ssh/id_ed25519_meowhome`） |
|
||||
| 系统 | Windows（主机名 `AEiva`，AMD64） |
|
||||
| 项目目录 | `D:\Project\Code\Uni\Cyrene-For-Android` |
|
||||
| Android SDK | `C:\Users\Aska\AppData\Local\Android\Sdk`（已装 `platforms/android-37.0` + `build-tools/37.0.0`） |
|
||||
| `JAVA_HOME` | `C:\Program Files\Microsoft\jdk-21.0.11.10-hotspot\` |
|
||||
| 构建 | `cd /d D:\Project\Code\Uni\Cyrene-For-Android & gradlew.bat assembleDebug` |
|
||||
| 单测 | `gradlew.bat testDebugUnitTest` |
|
||||
| 镜像 | Maven→阿里云、Gradle 发行包→腾讯（都已在仓库配置里，开箱即用） |
|
||||
|
||||
`local.properties`（不进仓库）已建好，指向上面的 SDK。
|
||||
|
||||
> `D:\...\Cyrene-For-Android` 里还有一份**未被 git 跟踪**的 `devdocs\`（本次交接复制过来的），`git status` 不会显示它。
|
||||
|
||||
---
|
||||
|
||||
## 3. 后端
|
||||
|
||||
**Cyrene v2 主项目也已迁到这台 PC**，不再跑在别处。
|
||||
|
||||
App 里的「服务器地址」指向本机后端即可：
|
||||
|
||||
- 模拟器：走 `10.0.2.2`
|
||||
- 真机 / 局域网设备：走 PC 的局域网 IP
|
||||
|
||||
**具体地址与端口以主人给的为准，不要自己假设。**
|
||||
|
||||
---
|
||||
|
||||
## 4. 仓库
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 分支 | **`android`**（不用 `main`，`dev` 是 4 个月前的弃用项目） |
|
||||
| 当前提交 | `9bc45dc`，工作区干净，已与 origin 同步 |
|
||||
| 远端 | `ssh://git@git.yeij.top:2222/AskaEth/Cyrene-For-Android.git` |
|
||||
| git 身份 | **`AskaEth <i@yeij.top>`**（PC 端如未配置，执行 `git config user.name AskaEth` / `git config user.email i@yeij.top`） |
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档清单（都在 `devdocs/`，不进仓库）
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `DESIGN.md` | 总览与已定决策 |
|
||||
| `01-功能拆解与分步路线.md` | 分步路线 |
|
||||
| `02-前后端协同事项.md` | **后端缺口登记**——开发中一旦遇到后端不支持或「文档写了但没实现」，**当场写进这里并反馈主人** |
|
||||
| `03-客户端细化开发方案.md` | 细化方案 + 里程碑 |
|
||||
| `04-构建环境.md` | 环境、镜像、踩坑记录 |
|
||||
| `05-开发进度与交接.md` | 进度 + 易忘的实现约定 |
|
||||
| `06-移到-PC-开发说明.md` | 本文 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 已完成 / 待办
|
||||
|
||||
**已完成**
|
||||
- M0 工程骨架｜M1 登录（含明文 HTTP 放行、自动登录、静默重登、401 登出）
|
||||
- M2 只读主会话（历史 / 倒序 / 上拉分页 / 来源角标）
|
||||
- M3 发送 + 流式（乐观消息、增量解析、光标、自动置底）
|
||||
- M4 完整：`<p>` 多气泡、`<action>/<narration>` 旁白、思维链卡片（自动折叠 + 保留 10 分钟）、工具卡、图片（Coil 3）
|
||||
- M5 侧边栏 + 会话列表（DataStore 快照、序号映射、切换/新建/删除）
|
||||
- 交互打磨：回车发送、文本选择模式（全选只作用于当前气泡）、IME 修复、返回键逐层回退
|
||||
- App 设置页：主题（跟随系统/浅色/深色）、显示旁白、思维链默认展开、版本、登出
|
||||
- 列表项统一为 Miuix `BasicComponent` + `PreferenceCard`（MD3 圆角卡片）
|
||||
|
||||
**待办**
|
||||
- **C-2 管理员只读监控**（概览 / 后台思考 / 记忆 / 人格）——独立导航图 + 独立 `Scaffold`，只读
|
||||
- 子会话流程（主人已确认先搁置，暂不完善）
|
||||
- 图片 / 工具卡实机验证（后端暂未配置工具）
|
||||
|
||||
---
|
||||
|
||||
## 7. 旧开发机
|
||||
|
||||
已停用，仅作历史参考：
|
||||
|
||||
- 编译配置（`~/.gradle/gradle.properties` 里的 `aapt2FromMavenOverride`、`daemon=false`）与 SDK 补装记录见 `04-构建环境.md`
|
||||
- 那台机器的 `/tmp` 是内存盘（tmpfs），别往里放东西
|
||||
@@ -1,87 +0,0 @@
|
||||
# W50「她主动说的话实时到安卓」——验收证据与避坑
|
||||
|
||||
> 状态：**W50 已合并并验证**（`android` 分支 `afee5f6`，已推）。本文件是该批次的**证据与操作细节**；
|
||||
> 状态与待办仍以 `05-开发进度与交接.md` 的锚点补记二十七为准（那里只放结论与指针）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 验收判据与证据（真机 = 模拟器 `emulator-5554`，假后端）
|
||||
|
||||
场景是怎么造出来的：`python devtools/fake-backend/proactive_inject.py --port 18090 --text "主动消息验收一"`
|
||||
（它按真后端的顺序**先落一行 assistant 历史行、再广播带同一 `id`/`createdAt` 的 `proactive_message` 帧**）。
|
||||
|
||||
| 判据 | 操作 | 证据 | 结果 |
|
||||
|---|---|---|---|
|
||||
| ① 主会话**实时**出现 | 注入后 5s 取 dump | 广播回执 `delivered=1`；dump 里有 `[78,406][400,472] \| 主动消息验收一`，其下 `发送至 网页` | ✅ |
|
||||
| ② 次级会话**不**出现 | 抽屉 → 「新会话」 | 该页 dump 里 `grep -c 主动消息验收一` ⇒ **0**（页面显示「还没有消息」） | ✅ |
|
||||
| ③ 刷新/重启后**仍在且只一条** | ①切回主会话 ②同 `id` 重投一帧 ③`force-stop` 后重启 | ①计数 **1** ②重投后仍 **1**（按 `id` upsert 生效）③重启后 **1** | ✅ |
|
||||
| ④ 无 `id`（后端落库失败）**不静默丢**、也不假装落库 | `--without-id` 注入 → 再重启 | 注入后计数 **1**（本地气泡）；重启后 **0**（历史里没有它），而落库那条仍 **1** | ✅ |
|
||||
|
||||
截图（主会话单条助手气泡 + 左下对齐）与 dump 一致，渲染无重叠。判据以 **dump 计数**为准（比截图更硬，也更省上下文）。
|
||||
|
||||
## 2. 环境坑（这次花掉的时间都在这，别再重复）
|
||||
|
||||
1. **`input text` / `input keyevent` 打出的标点会变全角**（`:`→`：`、`.`→`。`、`/`→`／`）。
|
||||
原因：模拟器**系统 locale 是 zh-CN**，Gboard 走中文标点；字母数字不受影响。
|
||||
**绕法（不必改 locale）**：`normalizeBaseUrl`（`app/.../data/api/ApiClientFactory.kt:109`）在缺 scheme 时
|
||||
会补 `http://` ⇒ 服务器地址栏只填**纯字母** `localhost`，再用 `adb reverse tcp:80 tcp:<后端端口>`
|
||||
把设备的 80 端口接到后端。**附带好处：切假后端/真后端只要改 reverse，一个字都不用重打。**
|
||||
2. **`adb reverse tcp:80` 需要 root**：`adb root` 在本 AVD（userdebug）可用，
|
||||
但它**会重启 adbd ⇒ 所有 `adb reverse` 丢失**，之后必须重新加（包括 `tcp:10942`）。
|
||||
3. **点太快会 ANR 被系统强杀**：实测 `ANR in top.yeij.cyrene … Waited 5065ms for MotionEvent(… (367.0, 780.0))`
|
||||
紧跟 `Force finishing activity`。App 冷启动要跑类校验（日志里每条 100~170ms），
|
||||
**等 25~35 秒再动**；并把三个动画开关置 0（`window_animation_scale` / `transition_animation_scale` / `animator_duration_scale`）。
|
||||
4. **屏幕会自己黑**（`svc power stayon true` + `screen_off_timeout` 都不一定挡得住）：
|
||||
交互前 `input keyevent 224`，并用 `dumpsys window | grep mCurrentFocus` **确认前台是本 App**——
|
||||
黑屏时点击会落到桌面（这次白跑过两轮），回到桌面后必须重新 `am start`。
|
||||
5. **`adb shell … /sdcard/…` 的路径会被 MSYS 改写**（变成 `C:/Program Files/Git/sdcard/…`）⇒ 命令前
|
||||
`export MSYS_NO_PATHCONV=1`。
|
||||
6. **Python 输出 GBK 会炸**（`UnicodeEncodeError: 'gbk' codec can't encode character`）⇒
|
||||
`export PYTHONIOENCODING=utf-8`（`ws_probe.py` 里那段 `reconfigure` 就是同一件事）。
|
||||
7. **`uiautomator dump` 时好时坏**（`ERROR: null root node returned by UiTestAutomationBridge`）：失败就重试；
|
||||
文字/坐标判据一律优先用 dump（`bounds | text`），截图只在需要看观感时用。
|
||||
8. **滑动手势会被系统返回手势吃掉**：从屏幕底部附近起滑会直接回桌面。真要滚动就避开底部区域
|
||||
（例如 `input swipe 540 1500 540 800 300`），别用 `1900 → 700`。
|
||||
9. **登录页的「服务器地址」留空时，App 会回落到上一次记住的地址**（不是报错、也不是用界面上那句示例 `http://192.168.1.10:8080`）。
|
||||
我为此白追了一个小时「请求怎么打到真后端去了」：那一次地址栏恰好是空的（我清过），而当时的 reverse 指向真后端。
|
||||
**教训**：凡是要换后端，先 `uiautomator dump` 确认地址栏里**真有值**（`http://localhost/`），别信「刚才填过」。
|
||||
10. **「登出」是设置页最底部的一个图标按钮**（`ui/settings/SettingsScreen.kt:160`，图标用的是 `MiuixIcons.Back`、
|
||||
只有 `contentDescription = "登出"`，红字）：截图上它看起来像「返回」，非常难找。找法：dump 里搜 `content-desc="登出"`
|
||||
（位置在「关于 → 版本」下面 32dp，约 `y≈2109` 处），或先把设置页滑到底。
|
||||
⚠️ 这条同时是个**观感问题**（主人可能根本不知道它在哪），要不要换成带文字的危险行条目属于产品决定。
|
||||
11. 验收结束时的状态：`adb root` 仍是开的；reverse 为 `tcp:80 → tcp:10942` 与 `tcp:10942 → tcp:10942`
|
||||
（都是真后端）；App 拿的是假后端签发的 token ⇒ 会在真后端的 401 上登出，登录页地址栏留着 `localhost`、用户名留着上一次填的。
|
||||
|
||||
## 3. 复现整套验收的最短路径
|
||||
|
||||
```bash
|
||||
export PATH="$PATH:/c/Users/Aska/AppData/Local/Android/Sdk/platform-tools"
|
||||
export MSYS_NO_PATHCONV=1 PYTHONIOENCODING=utf-8
|
||||
|
||||
# 1) 假后端 + 反向端口（80 ⇒ 假后端，地址栏填 localhost 即可）
|
||||
python devtools/fake-backend/fake_backend.py --port 18090 &
|
||||
adb root && adb reverse tcp:80 tcp:18090
|
||||
|
||||
# 2) App 侧：清数据 → 登录页填 localhost / 任意用户名密码 → 登录（假后端不校验）
|
||||
adb shell pm clear top.yeij.cyrene
|
||||
adb shell am start -n top.yeij.cyrene/.app.MainActivity # 等 25~35s 再动
|
||||
|
||||
# 3) 注入 + 看判据（四条判据见第 1 节）
|
||||
python devtools/fake-backend/proactive_inject.py --port 18090 --text "主动消息验收一"
|
||||
python devtools/fake-backend/proactive_inject.py --port 18090 --text "落库失败验收" --without-id
|
||||
```
|
||||
|
||||
## 4. 这个批次顺带发现的客户端缺陷（已随 W50 修掉）
|
||||
|
||||
`proactive_message` 载荷里的 `timestamp` 在服务端是 Go `time.Time` ⇒ 线上是 **RFC3339 字符串**，
|
||||
而客户端旧声明是 `Long?` ⇒ kotlinx 解码抛异常、被 `WsEvent.parse` 的 `runCatching`
|
||||
（`app/.../data/ws/WsEvent.kt:654`）**吞成 null** ⇒ 整帧在成形之前就没了。
|
||||
也就是说：**只加一条 `onEvent` 分支根本碰不到帧**。现在按字面量收（字符串/数字都吃）；
|
||||
该字段全仓零消费点，排序去重一律用 `createdAt`。
|
||||
|
||||
## 5. W50 留下的已知窄尾巴（**只在「落库失败」那一档可达**）
|
||||
|
||||
降级气泡是一条 `role=assistant` 的 `messages` 行，而删除入口的判据 `canDeleteMessage` 只看 role ⇒
|
||||
长按能删它，删除会用本地 id（`proactive-local:` 前缀）打服务端并失败报错。
|
||||
**没修的理由**：要收口得给每条消息加「是否服务端行」的标志位，会动 `ChatDisplayItem` 与气泡渲染，
|
||||
超出该批次范围。**最省的收口方式**：在 UI 层按 `proactive-local:` 前缀屏蔽动作入口。
|
||||
@@ -1,120 +0,0 @@
|
||||
# 给后端会话的交接（2026-10-04）
|
||||
|
||||
> 来自 **Android 客户端会话**。我们共享 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 作为交换登记处。
|
||||
> 你在 **v0.56** 里逐条落地了 A2 / G1 / G2 / G3 / G4 / F3，并在 changelog 里点名引用编号——**这套流程运转得很好**。
|
||||
> 本文件是接续：把我**复核到的现状**、**仍未闭环的项**、**我接下来要做的客户端改动**一次交代清。
|
||||
|
||||
---
|
||||
|
||||
## 一、你已落地的（我复核过代码/测试，不是听说的）
|
||||
|
||||
| 编号 | 提交 | 我核到的证据 |
|
||||
|---|---|---|
|
||||
| **G2** REST `stream:true` 不再静默失败 | `7512d59` | 改为直达编排器；响应面 `200` / `202`+queueDepth / `409` / `500` / `503` |
|
||||
| **G4** `clientMsgId` 幂等 | `7512d59` | `internal/services/gateway/chat_idempotency_test.go` 有去重断言 |
|
||||
| **G3** `chat.image` 上限 | v0.56 | `rest.go` 的 `chatImageTooLargeCode`（文案指路 `/upload`） |
|
||||
| **F3** 视觉链路 URL 取回 | v0.56 | `internal/runtime/multimodal/vision/resolver.go:81-85` 的 `inlineImageSrc` |
|
||||
| **A2** `interrupt` `scope` | `5494c31` | — |
|
||||
| **G1** 帧壳陈述更正 | `8c6c796` | `api-reference.md` §6.2 / §6.6 |
|
||||
|
||||
另注意到你多做了 **`3d8822c`（回合内 steer + `steer_ack` 帧）**——客户端**尚未**接，先记下。
|
||||
|
||||
---
|
||||
|
||||
## 二、最要紧的一件：`multimodal: false` 是设计还是漏配？
|
||||
|
||||
**实测的生效配置**：`provider: anthropic` / `model: deepseek-flash` / **`multimodal: false`**。
|
||||
|
||||
**问题**：你自己那份 `DevDocs/reference/deepseek/guides-vision.md`（2026-10-03 抓取）**首句**就写着
|
||||
「`deepseek-flash` 模型支持在文本之外输入图片」。若该标志并非有意：
|
||||
|
||||
1. **图像被降级走视觉工具**，而 `resolveImages` **每回合**都跑（`loop/run.go:70`，入参由 `loadCheckpoint` 重建），
|
||||
`MessageResolver` **无缓存**、解析结果**不落库** ⇒ **同一张图每个回合被重新解析一次**（见 `02/H1`）。
|
||||
2. **模型只拿到一段文字描述，不是图本身** —— 这不只是「贵」，是**有损**。
|
||||
|
||||
**若置为 `multimodal: true`**：走 `KindMain`（`resolver.go:75-85`），**不调任何工具** ⇒ H1 结构上消失，且模型真看到图。
|
||||
**这是「改一个配置项」与「写缓存代码」的差别。**
|
||||
|
||||
### 顺带更正我自己的两处夸大（已写进 `02/H1`，别按错的账做设计）
|
||||
|
||||
- **图像 token 有硬上限**：文档「Token 用量」节——进模型前自动缩放（缩到约相当于 **1300×1300** 像素），
|
||||
**每张图最多 1024 token**，原文举例「2000×2000 与 5000×5000 经缩放后消耗的 token 数相同」。
|
||||
所以**不是**「大图吃一大块预算」。
|
||||
- 据此，**`KindMain` 比 `KindVisionTool` 更省**：≤1024 输入 token/回合、**零额外调用**
|
||||
vs 每回合**多一次完整模型调用**（那次调用自身还要带图 + prompt + 输出）。
|
||||
|
||||
**请回答**：该标志是设计选择还是漏配？若是后者，欢迎直接改，我这边无需改动。
|
||||
|
||||
---
|
||||
|
||||
## 三、仍未闭环的（按优先级）
|
||||
|
||||
1. **`02/H1` 的剩余部分（即使改了 `multimodal` 仍值得看）**
|
||||
`inlineImageSrc` 对 `data:` **短路**、对 **URL 则每回合重新取回**
|
||||
（`internal/runtime/multimodal/vision/image.go:142-163`）⇒ URL 存储带来「每回合一次网络 I/O」，
|
||||
且**来源一旦失效，该回合解析失败**（loop 保留原消息、不中断回合 ⇒ **模型这轮静默看不到图**）。
|
||||
建议：把「取回 + 内联」的结果**按内容哈希 memo**。
|
||||
|
||||
2. **`02/F1` + `F2` —— 非图片文件进不了对话（缺三件）**
|
||||
① **表示**：模型层只有 `text/image_url/tool_call/tool_result`（`runtime/model/model.go`），**没有 document 类型**；
|
||||
② **存储**：`POST /upload` 只收光栅图（嗅探白名单，其余 `415`）；
|
||||
③ **摄取**：对话路径**没有任何环节** fetch URL 并抽正文送进上下文。
|
||||
旁证：IM 适配器层**已有** `adapter.ContentFile` / `MediaFile` 且各渠道都在填，
|
||||
但 **channelbridge 从不读 `msg.Media`**（`inbound.go` 只取 `msg.Content`，还丢弃无文本消息），所以**IM 侧也无先例可抄**。
|
||||
⇒ 主人提的「**分享到 App，超限走文件**」现在就卡在这里。
|
||||
|
||||
3. **`02/F4`（约定问题，动手前必须先定）**
|
||||
把 `[用户分享]` 这类标记**拼进 `content`** 违反项目红线（`design/11 §10.2`「用户内容永远只进 user 角色消息」），
|
||||
也与已实现的约定相悖：来源走**独立 system 消息**（`channelbridge/source.go:25-35`），身份走结构化 `SenderName`，
|
||||
源码注释原话「**文本标签既含糊，又构成提示词注入面**」。
|
||||
建议：来源走**来源 system 消息**或已有的 `deviceId` / `platform` 元数据；人类可见标记放**客户端渲染层**。
|
||||
|
||||
4. **`02/F5`（小）** `PATCH /sessions/{id}` 在 `title` **存在但空白**时回 `title is required`，读起来像「缺字段」。
|
||||
建议区分「字段缺失」与「值非法」两种情况。
|
||||
|
||||
5. **`02/E4` / `E5`（文档漂移，低优）**
|
||||
`/auth/logout` 的响应形状**文档 vs 文档 vs 代码三处互相打架**；`api-reference.md` §3.2 的会话字段已过时，
|
||||
且 `PATCH` / `read` **没有 §3.x 详情章节**。（§6.6 那处你已在 G1 修掉。）
|
||||
|
||||
6. **`02/D4`（未读）** `unreadCount` 已实现，但**已读游标** `POST /sessions/{id}/read` 客户端尚未接，
|
||||
所以「红点只增不减」。客户端侧待排，暂不需要你做什么。
|
||||
|
||||
---
|
||||
|
||||
## 四、来自你那套 DeepSeek 视觉文档的三条提醒（与新链路有交互，值得自查）
|
||||
|
||||
1. **图片只能出现在 `user` 消息**里；`system` / `assistant` 带图回 **400**。
|
||||
⇒ 历史重装配时若把图像部件落到非 user 角色，**整个回合会挂**。
|
||||
2. **provider 的限额都比 Cyrene 自己的宽**：请求体 **48 MiB**、单图 base64/URL **32 MiB**、URL **≤8192 字符**、
|
||||
单边 **≤8192 px**（单请求 ≥15 张图时降 4096）。
|
||||
⇒ **Cyrene 自己的 5 MiB（G3）才是真正的瓶颈**；要支持更大图，放宽这边比适配 provider 更直接。
|
||||
3. **`detail: low`**（缩到 512×512、更省 token）是**现成旋钮**，但由**服务端构造内容块时**决定，客户端设不了。
|
||||
|
||||
---
|
||||
|
||||
## 五、我接下来要做的客户端改动（便于你预判冲突）
|
||||
|
||||
1. **`tool_execution` 三事件**（进行中）
|
||||
客户端此前**只映射了 `.update`**——恰好是你**没有生产者**的那一帧；真正发出的 `.start` / `.end`
|
||||
落进未知类型被**静默丢弃** ⇒ **工具执行状态从未到过界面**。
|
||||
（`ws_bridge.go:191-194` 已写明 `id` 可关联 `tool_call.*`，我会**按 `id` 关联**，不按 `index`。）
|
||||
2. **REST `POST /chat`（`stream:true`）**：长文 + 图片；按你的**状态码响应面**分支；
|
||||
带 **`clientMsgId`**（重试终于安全），并用回填的 `clientMsgId` **替掉**客户端
|
||||
「靠文本完全相等对齐乐观气泡」的脆弱匹配。
|
||||
3. **接入 `interrupt` 的 `scope`**（A2 的客户端半边）。
|
||||
4. **图片策略**：小图 base64、大图走 **`/upload` + URL**（F3 修好后这条路才真正可用）。
|
||||
5. 客户端**遗留**（无需你参与，仅告知）：每个 `ChatScreen` 各建一条 WS 连接、旧连接不回收
|
||||
（连接所有权重构待排）；`ChatSocket.sendInterrupt` 至今零调用方。
|
||||
|
||||
---
|
||||
|
||||
## 六、协作方式上的两个请求
|
||||
|
||||
1. **改帧 / 字段形状时，请同步 `api-client.md` 并升契约版本号**——我 diff 的就是那个版本号。
|
||||
两次漂移（E4 / E5）都是「代码对了、文档没跟」，我照文档做就会做错。
|
||||
2. **`devdocs/` 不进 git**（已 gitignore），是磁盘上的共享文件。**你的回复直接写进 `02` 对应条目即可**，我读得到；
|
||||
若某项你要**拒绝**或**改口径**，也写进同一条目，**别静默不实现**。
|
||||
|
||||
---
|
||||
|
||||
*本文件由 Android 客户端会话生成；对面可直接在 `02-前后端协同事项.md` 里逐条回。*
|
||||
@@ -1,95 +0,0 @@
|
||||
# Cyrene-For-Android — Cyrene 安卓客户端设计文档（超详细讨论稿 v1）
|
||||
|
||||
> 配套 Cyrene v2（git.yeij.top/AskaEth/Cyrene_v2）的 Android 客户端。
|
||||
> **主人已确认的关键决策**（2026-09-08）：
|
||||
> - 主界面 = **常规 AI APP 风格**（会话列表 + 聊天流）。
|
||||
> - **长按电源键唤醒 = 全屏语音助手**（系统级语音助手交互），**不要悬浮球**。
|
||||
> - UI **严格遵守 MIUIx / Miuix 设计风格**：官网 https://compose-miuix-ui.github.io/miuix/zh_CN/ ，组件库 https://compose-miuix-ui.github.io/miuix/zh_CN/components/ 。
|
||||
> - **先做纯文本版本**（P0）；语音（P1）后续。
|
||||
> - 顶栏左上角**汉堡菜单**展开**侧边栏**，**预留 IoT 入口 + App 设置页入口**。
|
||||
> - 后端契约详见 `Cyrene v2` 的 `Docs/api-reference.md` + `DevDocs/design/21-安卓app语音助手.md`（本文件为端侧细化）。
|
||||
> 命名：仓库作者 `AskaEth`，日常名 `YeiJi / 叶酱`；App 名 `Cyrene`，角色 `昔涟`。
|
||||
|
||||
---
|
||||
|
||||
## 0. 目录与工程形态
|
||||
- **单 Module**：`app`（Kotlin + Jetpack Compose），Gradle 版本目录。
|
||||
- 依赖：`compose-miuix-ui`（Miuix 组件）、`androidx.lifecycle.viewmodel-compose`、`Retrofit + OkHttp + kotlinx-serialization`、`okhttp`（WebSocket）、`EncryptedSharedPreferences`（JWT）、`hilt`（DI，可选）。
|
||||
- `BuildConfig`：`BASE_URL`（默认可 `http://<host>:8080`，release 换 HTTPS）。
|
||||
- 包结构：`com.askaeth.cyrene.{app,core,data,domain,platform,ui}`（`app`=Activity/导航；`core`=Miuix 主题/Auth；`data`=Retrofit/WS/仓库；`domain`=会话/消息模型；`platform`=语音/权限/电源键；`ui`=各 Screen/组件）。
|
||||
|
||||
## 1. 总体信息架构（功能分类）
|
||||
```
|
||||
Cyrene-For-Android
|
||||
├─ A. 聊天（主界面，AI APP 风格）
|
||||
│ ├─ 会话列表：主会话「与昔涟」(web) + 次级会话(web:<uuid>)，可新建/删除/恢复
|
||||
│ └─ 聊天页：气泡流(<p>多气泡、<action>/<narration> 旁白灰斜体仅chat、思维链/工具卡折叠、图片)、输入框+发送、语音按钮(P0占位)
|
||||
├─ B. 侧边栏（汉堡抽屉）
|
||||
│ ├─ 会话/聊天
|
||||
│ ├─ [预留] IoT(设备/场景)入口
|
||||
│ ├─ [预留] App 设置入口
|
||||
│ ├─ [可选] 记忆 / 子代理 / 自主思考(只读)
|
||||
│ └─ 关于 / 登出
|
||||
├─ C. 语音助手（长按电源键唤醒，P1）— 全屏，无悬浮球
|
||||
│ ├─ 展开: 聆听动画 → 已识别文本 → 昔涟回复 → 再听/TTS
|
||||
│ └─ 系统级: AccessibilityService/系统语音助手回调 → 启动助手 Activity(全屏)
|
||||
├─ D. [预留] IoT：设备/场景列表（占位）
|
||||
└─ E. [预留] App 设置：主题(Miuix 深/浅)、通知、语音偏好(ASR/TTS 端侧 vs 后端)、关于
|
||||
```
|
||||
|
||||
## 2. 页面路由（单 Activity + 导航）
|
||||
- `LoginScreen`（首启无 token）→ `HomeScreen`（会话列表，含顶栏汉堡）→ `ChatScreen({sessionId})`（聊天）
|
||||
- `AssistantActivity`（P1 全屏语音助手，长按电源键拉起；无悬浮球，就一个全屏页）
|
||||
- `IotScreen` / `SettingsScreen`（占位页，P0 展示"规划中"）
|
||||
|
||||
## 3. 数据层（对照现有契约，P0 纯文本即用）
|
||||
- **认证**：`POST /api/v1/auth/login {username,password}` → `{token,expiresAt,role}`（`role=owner`，单账号）。JWT `Authorization: Bearer`+`X-API-Version: 1`；`EncryptedSharedPreferences` 存 token；**REST 401 → `auth_expired` 清 token → 回登录**；WS 握手失败同理。
|
||||
- **会话**：`GET /api/v1/sessions`（主会话 `id="web"` 恒在）；`POST /api/v1/sessions` 建次级；`GET /sessions/{id}/messages?limit=50&before=<ms>&platform=`（**倒序热分页**，`platform=` 过滤）；`DELETE /sessions/{id}`（主会话删=403）。
|
||||
- **发消息**：`POST /api/v1/chat {sessionId,text,deviceId,stream?}`（`stream:true`→转 WS；忙时 `202 {queued,queueDepth}`、队满 `409 chat_busy`）。
|
||||
- **WS** `/ws/chat?token=`：上行 `chat`/`interrupt`；下行 `message.start|delta|end`、`thinking.*`、`tool_call.*`、`message_persisted`、`history`（握手后首帧主会话最近 50 条）、`mood`、`session_busy`/`pending_*`/`session_idle`、`voice_output`（P1）。`message_persisted`/`history` 载荷为 `historyMessage`。
|
||||
- **消息 DTO**：`{id,sessionId,role,content,mode?,mood?,image?,thinking?,platform?,deviceId?,senderName?,adapterId?,createdAt}`；`thinking` 仅 owner 可见；主流 `mode` 有 `chat`（含 `<p>`/`<action>/<narration>` 需端侧解析）。
|
||||
- **deviceId**：`voiceassist:myapp:v1`（design/16 §4.5 允许自定可读前缀），`POST /chat`/ws `chat` 携带 → 落库标注来源；主会话 `web` 与 Web 共享上下文（multiplatform 同步）。
|
||||
|
||||
## 4. 消息渲染（聊天页核心）
|
||||
- 按 `mode` 决定形态：`chat` 用气泡；其它 `mode`（backthink/工具/审计等 refs）卡片化或折叠。
|
||||
- **`chat` 文本解析**：把 content 按 **`<p>`** 拆成多条气泡（每段一条）；`<action>…</action>`/`<narration>…</narration>` 解析为**灰斜体小字旁白**（依附气泡，不独立成气泡）；`＊…＊`/`*…*` 兼容。**非 chat 消息不解析**这些标签。
|
||||
- `thinking`（仅 owner）：可折叠「思维链」面板；`tool_call` →「工具卡」（折叠，可看参数/结果）。
|
||||
- 流式：`message.delta` 追加到当前气泡末尾 + 光标；`message.end` 收口。
|
||||
- 图片：`image`（base64 data: URI 或 URL）→ Coil 加载。
|
||||
|
||||
## 5. 语音助手（P1，长按电源键 全屏，无悬浮球）— 端侧与后端协同
|
||||
- **触发**：① 系统级语音助手回调（`VOICE_INTERACTION` / `AssistantService`）或 ② `AccessibilityService` 监听 `KEYCODE_POWER` **长按**（Android 对电源键长按有限制，需在系统「电源键双击/长按」设置里把本 App 设为语音助手，或通过系统辅助「voice assistant」入口）。落地：**声明 `VOICE_INTERACTION_SERVICE`**，长按电源键由系统拉起本 App 的 `AssistantActivity`（全屏）。
|
||||
- **链路**：`AssistantActivity` 聆听（`MediaRecorder`/`AudioRecord`）→ 录音交给 **ASR**（**端侧 or 后端**，见开放问题；后端当前 ASR/TTS 是占位，需先补 design/21 后端补强或端侧 whisper）→ 出文本 → `POST /api/v1/chat {text,deviceId}`（或 WS 流式）→ 昔涟回复 → **TTS** 合成朗读（端侧 e.g. `TextToSpeech` 或后端）。全程单页无悬浮球。
|
||||
- **保活/后台**：可选前台服务（语音持续/推送），权限最小化；无需悬浮球全局浮层。
|
||||
|
||||
## 6. MIUIx / Miuix 映射（紧跟 compose-miuix-ui）
|
||||
- 用 `compose-miuix-ui` 的 `MiuixTheme` + 组件：`TopAppBar`（汉堡/标题）、`Scaffold`/`Drawer`（侧边栏）、气泡用 `BubbleView`/卡片、`TextField`（输入）、`Button`（发送）、`Switch`/`List`（设置）、`Snackbar`/`Dialog`。**禁用原生 Material 组件**，全 Miuix 风格（圆角、毛玻璃、液态玻璃、强调色）。
|
||||
- 顶栏左上汉堡 → 侧边栏（`Drawer`）；侧边栏含「IoT」「App 设置」占位入口（P0 点开显示"规划中"）。
|
||||
|
||||
## 7. P0（纯文本）MVP 任务清单
|
||||
1. 工程搭建：Gradle + Compose + Miuix 依赖 + `BuildConfig.BASE_URL` + Hilt（可选）。
|
||||
2. `core`：Miuix 主题、AuthManager（EncryptedPrefs 存 JWT、401→auth_expired→登出）。
|
||||
3. `data`：Retrofit（login/sessions/messages/chat）、WS `ChatSocket`（`/ws/chat?token=`，事件分发到 StateFlow）、`ApiClient`（`Authorization: Bearer`+`X-API-Version`）。
|
||||
4. `domain`：`Conference`/`ChatMessage` 模型、`HistoryMessage` 映射、`<p>`/`<action>/<narration>` 解析器。
|
||||
5. `ui`：`LoginScreen` → `HomeScreen`（会话列表）→ `ChatScreen`（气泡流 + 流式 + 思维链/工具卡 + 输入框）。顶栏汉堡侧边栏（IoT/设置/登出）。
|
||||
6. 设备标识：`deviceId=voiceassist:myapp:v1`。
|
||||
7. 验证：登录 → 拉主会话历史 → 发消息 → WS 流式收到回复 → 跨端（web/微信）同步显示。
|
||||
|
||||
## 8. 长线 roadmap
|
||||
- **P0（纯文本）**：⑦ 完成 → 可日常聊天，多端同步。
|
||||
- **P1（语音助手）**：后端补 ASR/TTS（design/21）→ 电源键长按唤起全屏助手 → 聆听/ASR/chat/TTS 朗读闭环 → 无悬浮球。
|
||||
- **P2（智能）**：IoT 入口真实现（设备/场景）、App 设置功能化（主题/通知/语音偏好）、主动推送 + 系统通知、多角色（persona）切换、记忆/子代理/自主思考只读面板、多会话管理增强。
|
||||
|
||||
## 9. 开放问题（待与主人讨论 / 后续敲定）
|
||||
1. **[已定案] 长按电源键**：设置 App 为**系统默认语音助手**（`VOICE_INTERACTION_SERVICE` / `AssistantService`），由系统在长按电源键（或系统语音助手入口）时拉起本 App 的 `AssistantActivity`（全屏），无悬浮球。厂商（MIUI）自家更顺，需在系统「语音助手 / 电源键」设置里把本 App 设为默认。
|
||||
2. **[已定案] ASR/TTS 后端化**：**不在端侧**——因第三方适配器（微信 / KOOK 等 IM 渠道语音）**无法在端侧实现**，且为大后期**语音 / 视频通话**打基础。语音闭环统一走后端真实 ASR / TTS。**依赖**：后端 `voice` 链路当前是降级占位（cloud endpoint 空 → 降级、silent 空音频），需先接通真实 ASR / TTS（本会话 TTS/ASR 进程在做）。Android 语音 P1 依赖这项完成后接入。
|
||||
3. **Miuix 组件精确映射**：到 `components` 页逐组件对照，列出"我们用哪个"。
|
||||
4. **多角色**：现在登录恒 owner，暂无双角色切换；`GET /personas` 可只读展示人格列表。
|
||||
5. **会话管理 UI**：次级会话的新建/切换/删除入口。
|
||||
6. **Hilt vs 手写 DI**：视复杂度定。
|
||||
|
||||
## 10. 红线（必须遵守）
|
||||
- JWT 存储加密（EncryptedPrefs），不落明文/不打日志；401 即登出。
|
||||
- 身份靠 actor 元数据 + owner.yaml 白名单（登录即 owner），不靠提示词。
|
||||
- 语音/音频：权限最小化、显式授权；**不做悬浮球全局浮层**。
|
||||
- 严格 Miuix，禁原生 Material；`Docs/api-reference.md` 契约随实现更新。
|
||||
Reference in new issue
Block a user