Adds docs/reports/voice-and-awareness-2026-07-27.md alongside ADR-0008, assigns F-80 to F-83 for what is genuinely blocked, marks F-33 and F-70 implemented, and appends the session to progress.md and the changelog. Recorded rather than smoothed over: two pushes tonight carried a failing gate, because I read test results out of a grep instead of an exit code; the first attempt at the segmented-reply fix was wrong in a way my own diagnostic fixtures already documented; and the earlier reading of the architecture's screenshot exclusion as product-level was a mis-read that would have cancelled the feature. Also states plainly that game companionship does not work yet and why — PrintWindow over GDI cannot capture a hardware-accelerated surface — and that cargo test --workspace and tauri:build were not run at all, because the dev process holds the executable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
219 行
18 KiB
Markdown
219 行
18 KiB
Markdown
# 语音 · 窗口读取 · 游戏陪伴 实施记录(2026-07-27 夜)
|
||
|
||
按队列顺序推进:先清语音/屏幕读取被卡住的前期修复(A 段),再实施功能本体(B 段)。
|
||
七个提交,每个都过完整门槛后才推送。
|
||
|
||
> 配套文档:[ADR-0008](../decisions/ADR-0008-screen-awareness-and-voice-boundary.md)(边界与策略)、
|
||
> [fix-queue-2026-07-26.md](./fix-queue-2026-07-26.md)(缺陷队列与 F 编号)。
|
||
|
||
## 门槛结果
|
||
|
||
| 项 | 结果 |
|
||
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||
| `cargo fmt --all -- --check` | 通过 |
|
||
| `cargo clippy --workspace --all-targets -- -D warnings` | 通过 |
|
||
| `cargo test --workspace --lib` | **139 通过 / 0 失败**(`astrbot-desktop` 113、`desktop-protocol` 26) |
|
||
| `npm run typecheck` / `lint` | 通过(`--max-warnings 0`) |
|
||
| `npm run test -- --run` | **59 通过 / 11 文件**(本轮 35 → 59) |
|
||
| `npm run build` | 通过 |
|
||
| `npm run test:e2e` | 5 通过 |
|
||
| `cargo test --workspace`(含集成测试)与 `npm run tauri:build` | **未执行**:`target\debug\astrbot-desktop.exe` 被运行中的 dev 进程占用。停掉 dev 后需补跑 |
|
||
|
||
测试计数变化:Rust 101 → 139(协议 12 → 26、客户端 99 → 113),前端 35 → 59。
|
||
**每一条新断言都做过变异检验**,共 25 处刻意回归全部被对应测试抓到;其中两处第一次检验时
|
||
「无测试覆盖」,补测试后才通过(见下方 A2)。
|
||
|
||
---
|
||
|
||
## A 段 · 前期修复
|
||
|
||
### A2 · 分段回复不再丢内容(N-9)
|
||
|
||
`streaming: false` 的 `plain` 帧被当作 delta **追加**进 `accumulated`,随后 `map_complete`
|
||
用自己的文本**整体替换**它。三段的回复只显示一段,其余既不显示也不入库。
|
||
|
||
真正的形状比原判断复杂,而且**我第一版改错了**:这类块**有时是已流式发过内容的重述,有时是全新
|
||
内容**——`astrbot_client.rs` 的诊断夹具里写着 `// Repeats what the delta stream already carried` 和
|
||
`// Carries content the stream never delivers`,那些注释是我自己写的。按「每块一个气泡」实现会把
|
||
重述显示两遍,并且立刻 complete 每一块导致截流/取消时已无消息可终止,两条 R2 哨兵拿到 `stop`
|
||
而不是 `error`/`cancelled`。
|
||
|
||
修正后两处统一走一个 `reconcile()`,三条互斥规则,任一分支都不会丢已展示的文本:
|
||
|
||
1. 逐字节是已展示内容的前缀延伸 → 只发尾部(流式收敛场景,既有测试钉住);
|
||
2. 空白归一化后已被展示过 → 什么都不发(分段场景,N-9 本体);
|
||
3. 与已展示内容分叉 → 另起一条消息,两边都保留。
|
||
|
||
顺带修掉 `adopt_message_id` 的一个真实缺陷:同 id 分支会把 `m1#part-1` 覆盖回 `m1`,抹掉刚区分开
|
||
的分块。`map_media` 里还留着同一段逻辑的私有副本,带同一个缺陷,已合并。
|
||
|
||
**同时修的 N-4 映射器半边**:`event()` 在没有任何帧携带 `message_id` 前发出的 delta,元数据里
|
||
`message_id` 为 `None`,客户端回退到每事件唯一的 `event_id`,于是每个 delta 自成一条消息。现在流
|
||
id 兜底命名。**N-4 的「两个气泡」现象本身尚未确认是这条**,客户端的 `messageId || eventId` 回退
|
||
未动。
|
||
|
||
### A3 · 非图片媒体帧(F-33)
|
||
|
||
语音回复此前**什么都不产生**:无标记、无事件、无报错。四道独立闸门各自丢弃它,**只修任何一道都
|
||
看不出变化**:
|
||
|
||
| 闸门 | 症状 | 修法 |
|
||
| --------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
||
| 映射器 | `map_media` 唯一的产出分支写死 `frame_type == "image"`,`map_attachment_saved` 直接拒绝非图片 | 两处都按实际类型产出,帧类型写进标记的 alt 文本 |
|
||
| `pending_media` | 单槽位,一条回复里第二个媒体帧顶掉第一个 | 有界队列;无 id 的 `attachment_saved` 不再消耗待配对项 |
|
||
| 下载 | 候选路径只在字节嗅探为图片时才算成功(服务端对未知路径以 HTTP 200 返回自己的文本,故嗅探是必需的) | 增加音频/视频签名;`Content-Type` 声明为媒体类型时才可短路嗅探 |
|
||
| **CSP** | 无 `media-src`,回退到不含 `blob:` 的 `default-src 'self'`,`<audio src="blob:">` **只在发布版**被拒 | 补 `media-src`,并为 CSP 本身建立契约测试 |
|
||
|
||
CSP 那条与 F-04、`pet.html` 的内联脚本是同一类:dev 不注入 CSP,所以本地全绿、装包后失效。
|
||
现在 `src/lib/csp.test.ts` 逐条钉住应用依赖的每个指令,包括 `script-src` 仍拒绝 inline。
|
||
|
||
**SILK 单独处理**:AstrBot 中转 QQ/微信语音用的是 SILK 编码,浏览器无法解码。识别它,是为了让界面
|
||
直接说明,而不是渲染一个按下去没反应的播放器。
|
||
|
||
渲染层改为按**下载回来的真实 mime** 选元素(`<img>`/`<audio>`/`<video>`/说明文字),标记里的帧类型
|
||
只用于加载中的占位文案和失败提示。
|
||
|
||
### A4 · 出站附件契约(P1-9 出站半边)
|
||
|
||
**图片上传发送从来没送达过 AstrBot。** 客户端把附件放在顶层 `attachments` 键里,值还是 camelCase
|
||
对象;而服务端 `OpenApiChatRequest` 的字段只有
|
||
`message` / `session_id` / `conversation_id` / `username` / `config_id` / `config_name` /
|
||
`platform_id` / `enable_streaming` / `flags`——从其**自身** `/api/v1/openapi.json` 读到,该端点无需
|
||
认证即可访问。FastAPI 默认忽略多余字段而非报错,所以请求一直「成功」,附件一直被丢弃。`nickname`
|
||
同理,已移除。
|
||
|
||
正确形状([官方文档](https://docs.astrbot.app/en/dev/openapi.html))是把附件放进 `message`:
|
||
|
||
```json
|
||
{
|
||
"message": [
|
||
{ "type": "plain", "text": "..." },
|
||
{ "type": "image", "attachment_id": "..." },
|
||
{ "type": "record", "attachment_id": "..." }
|
||
]
|
||
}
|
||
```
|
||
|
||
段类型按上传的媒体类型决定,未识别的类型退化为 `file` 而非被丢弃。**这同时确定了语音输入怎么送**,
|
||
B4 不必再猜契约。队列此前把 P1-9 记为「需真实容器确认」的外部阻塞——**并不需要**,schema 是公开的。
|
||
|
||
新增一条白名单断言:序列化后的请求不得含九个字段之外的任何键。这类错误的失效方式是「被忽略」而
|
||
不是「报错」,所以必须由测试而不是由服务器来发现。
|
||
|
||
### A4 · 下载体积守卫(F-70)
|
||
|
||
`response.bytes()` 把整个 body 读进内存**之后**才查 16 MiB 上限。改为流式累读、越界即中止,并对声明
|
||
的 `Content-Length` 做早拒。音频比表情包大得多,这条从理论风险变成日常路径上的实际风险。
|
||
|
||
假服务端用 `Connection: close` 不声明长度(不用 chunked 分帧,免得夹具自身的分帧失败被误判为被测
|
||
守卫),并统计它成功写出了多少块——这才是「提前中止」与「读完再量」的区别所在,退回 `bytes()`
|
||
会让测试失败。
|
||
|
||
---
|
||
|
||
## B 段 · 功能本体
|
||
|
||
### B1 · ADR-0008:边界与策略
|
||
|
||
**先纠正一处会决定功能生死的误读。** `01_Architecture_Design.md:250-261` 的标题是
|
||
「**不应放在前端的能力**」,所以 259 行的「原始截图捕获」禁止的是**在 React 里截图**,不是产品级
|
||
禁令。此前的审计把它当成产品级排除,据此判定屏幕读取超出范围——那是误读。
|
||
|
||
项目规则实际**允许**:「用户授权的单次窗口截图」(`:739`)、阶段 7 的「按键说话;TTS;游戏窗口
|
||
绑定;时长事件;手动和低频截图」(`:1418-1424`)。
|
||
真正的硬排除是「实时全双工语音」「唤醒词」「高频视频分析」(`:1349-1351`)与 `AGENTS.md:32` 的
|
||
「无限制桌面控制」。
|
||
而 `implementation-queue.md:129` **已经写明**了闸门:「游戏模式接入截图/状态摘要前,先完成授权
|
||
提示、频率限制和隐私开关。」——策略不用发明,照做即可。
|
||
|
||
唯一所有文档都没规定的是:读屏时用户能否看见。ADR 第 5 条把它作为**提议**写入并实现了,理由是从
|
||
外部看,无可见标识的读屏与间谍软件无法区分;而需要用户去翻找的终止开关不算终止开关。
|
||
|
||
### B2 · 策略模块与命令出口
|
||
|
||
`uia.rs`(339 行) 与 `capture.rs`(363 行) 早已写完,却**没有任何 Tauri 命令**,全仓唯一调用方是一个
|
||
被 `#[ignore]` 的冒烟测试——即装包后产品里根本触达不到。
|
||
|
||
新增 `src-tauri/src/capture_policy.rs`,把 Q8:129 的三项要求做成代码,并作为触达窗口句柄的**唯一
|
||
通道**:读取接口收一个闭包,句柄不离开模块,因此不存在跳过开关/会话/过期/限频的访问器。
|
||
|
||
| 要求 | 实现 |
|
||
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 授权提示 | 会话制。一次会话只指向一个窗口,带 5 分钟上限(沿用 `WindowSelection` 自身的上限,不另发明);过期需用户重新授权,而重新授权本身就是一次同意事件 |
|
||
| 频率限制 | 画面默认 2 秒一次、下限 500ms **且调用方无法调低**;文本 750ms。离视频帧率三个数量级——因为「高频视频分析」超范围,而阶段 7 要的是「手动和低频截图」 |
|
||
| 隐私开关 | 默认**关**。关闭时同时清空所有进行中的会话,所以中途关掉会拦住下一次读取,而不只是阻止新授权 |
|
||
|
||
两条值得单独说明的判定:
|
||
|
||
- **会话不能绑定到运维槽位**,在创建时就拒绝而不是每次读取时判断——`:1077` 说运维槽位不自动接收
|
||
游戏截图、窗口状态或游戏事件,而一次会话正是这种自动投递。规则抽成自由函数,直接断言,不必造
|
||
一个活窗口。
|
||
- 限频的 `now` 是参数而非在内部读时钟,所以不用 `sleep` 就能测,也不会与调用方判断「该读了」时用
|
||
的时钟脱节。被拒绝的读取**不推后**下一次允许的时刻,否则轮询快于限频的调用方会被永久锁死。
|
||
|
||
六个命令:隐私开关读写、会话列表、开始/结束、窗口画面、窗口 UIA 文本。
|
||
**应用自身的命令不需要 capability 条目**——ACL 只管插件命令,现有命令仅靠 `core:default` 即可工作
|
||
已经证明这一点。
|
||
|
||
开始会话有个真实的交互障碍:读前台窗口是这些模块唯一的选择机制,而用户点按钮那一刻的前台窗口
|
||
**就是本应用**。所以按钮给出几秒(有上限)让用户切到目标窗口,并且**拒绝**抓到本进程的窗口——那
|
||
正是延时结束时用户还停在设置页的最可能结果。
|
||
|
||
### B3 · 送往陪伴槽位
|
||
|
||
面板可以把窗口的**文本**或**画面**发给陪伴槽位。界面顺序上文本在前是刻意的:它比截图暴露的信息
|
||
少得多,而且通常足以回答「我在看什么」。
|
||
|
||
外壳里的常驻指示器是 ADR 第 5 条。它**轮询**而不是等通知,因为授权会自行失效(会话过期、开关被
|
||
关);读不到状态时**什么都不显示**——既不声称正在读取,也不声称没有。
|
||
|
||
### B4 · 语音聊天
|
||
|
||
`ChatPanel.tsx` 原本调 `SpeechRecognition`,而 WebView2 不提供它,所以唯一走得到的分支就是那句
|
||
「当前 WebView 不支持语音输入」。改为架构规定的路线:`MediaRecorder` 录成 WebM/Opus → 走既有附件
|
||
上传 → **不带自己的文本**发送(音频**就是**消息,服务端 STT 负责把它变成文本)。`record` 段由 A4
|
||
的消息组装免费获得。
|
||
|
||
槽位在录音**开始时**固定,所以切了标签页后才结束的录音仍然发给他原本在对话的那一边(`:1065`
|
||
规定麦克风绑定当前聚焦实例)。
|
||
|
||
失败信息**分类映射**:权限被拒、没有麦克风、麦克风被占用需要用户做三件不同的事,旧代码对三者一律
|
||
回「请检查麦克风权限」。无音频编码器的 WebView2 在**打开麦克风之前**就被识别,而不是等
|
||
`MediaRecorder` 抛异常。
|
||
|
||
麦克风轨道在**每条**退出路径上关闭,包括编码失败与构造失败——不关它会让 Windows 的录音指示器在用
|
||
户说完之后继续亮着,这三条路径各有一条测试守着。
|
||
|
||
播放侧在 A3 已完成(`record` 帧 → 标记 → 下载 → `<audio>`),CSP 的 `media-src` 也在那里补上。
|
||
|
||
---
|
||
|
||
## 未完成与真实阻塞
|
||
|
||
| 新编号 | 事项 | 性质 | 下一步 |
|
||
| -------- | ------------------------------------------------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||
| **F-80** | `capture.rs` 用 GDI 的 `PrintWindow`,**捕获不到硬件加速的游戏画面** | 真实技术墙,非配置问题 | 游戏陪伴要真正可用,需改用 `Windows.Graphics.Capture`(WGC)。**故意没有绕过**:给模型送一张黑图比报错更糟 |
|
||
| **F-81** | WebView2 的麦克风 `PermissionRequested` 由宿主处理,而 Tauri 只在启用 `clipboard` 时注册处理器,本应用未启用 | 未知,需真机构建才能确定 | 装包后按下「语音输入」,记录是弹窗、自动允许还是自动拒绝。失败信息映射已就位,无论哪种都会给出可行动的提示 |
|
||
| **F-82** | 服务端 STT 需要用户配置 provider(API key 或自托管模型) | **用户决策,我不代选** | 这是唯一会把你的语音送往某处的环节。TTS 可用 Edge TTS 零密钥开启,STT 不行 |
|
||
| **F-83** | 只能授权**前台**窗口;没有非前台窗口枚举,所以没有「窗口选择器」 | 缺失能力 | 现以「给你几秒切过去」代替。要做选择器需新增枚举 |
|
||
| — | 「陪玩会话」(自动按间隔采样 + 语音)尚未组装 | 依赖 F-80 | B2/B3/B4 的部件已就位且各自可用,组装本身不难,但在 F-80 之前对游戏无效 |
|
||
|
||
另外,**已推的两个提交曾带着未通过的门槛**(`64dab45` 破坏两条 R2 哨兵、`9b2ec64` 让
|
||
typecheck/build 失败),分别由 `33ac5a3` 与同一提交修复。原因是我用 grep 判断测试结果而不是看退出
|
||
码。此后每次提交前都跑逐项检查退出码的门槛脚本。
|
||
|
||
## 真机验收清单
|
||
|
||
需要你在停掉 dev 进程后执行。前两项只需要装包,不需要容器。
|
||
|
||
| # | 步骤 | 证明 |
|
||
| --- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
|
||
| 1 | `cargo test --workspace` 与 `npm run tauri:build` | 今夜唯一未跑的两项门槛(exe 被占用) |
|
||
| 2 | 装新包,让 AstrBot 回一张图 | A3 的渲染 + CSP `media-src` 只能在发布版验证 |
|
||
| 3 | 让 AstrBot 回一条语音(需先配 TTS) | F-33 端到端;SILK 与可播放格式的分支 |
|
||
| 4 | 发一条带图消息,**在 AstrBot 侧确认模型真的看到了图** | A4 出站契约。此前从未送达,只能在服务端观察 |
|
||
| 5 | 按「语音输入」说一句话 | F-81:权限行为;配好 STT 后才有文本回复 |
|
||
| 6 | 设置 › 诊断页开启「允许读取窗口」→「授权一个窗口」→ 5 秒内切到记事本 → 发送窗口文本 | B2/B3 全链路;外壳应出现橙色指示器 |
|
||
| 7 | 指示器上点「停止」 | 关开关即清空所有会话 |
|
||
| 8 | 连续两次「发送窗口画面」 | 限频:第二次应被拒并给出重试毫秒数 |
|
||
| 9 | 把桌宠切到桌面浮动,确认不抢焦点、不置顶 | 上一轮的 N-15 / N-16(F-35) |
|