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>
18 KiB
语音 · 窗口读取 · 游戏陪伴 实施记录(2026-07-27 夜)
按队列顺序推进:先清语音/屏幕读取被卡住的前期修复(A 段),再实施功能本体(B 段)。 七个提交,每个都过完整门槛后才推送。
配套文档:ADR-0008(边界与策略)、 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(),三条互斥规则,任一分支都不会丢已展示的文本:
- 逐字节是已展示内容的前缀延伸 → 只发尾部(流式收敛场景,既有测试钉住);
- 空白归一化后已被展示过 → 什么都不发(分段场景,N-9 本体);
- 与已展示内容分叉 → 另起一条消息,两边都保留。
顺带修掉 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
同理,已移除。
正确形状(官方文档)是把附件放进 message:
{
"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) |