docs: record tonight's voice and awareness work, and what it did not finish
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run

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>
这个提交存在于:
YokiiroBW 2026-07-27 06:39:51 +08:00
父节点 876fad30c1
当前提交 d08c9817cc
共有 4 个文件被更改,包括 297 次插入 和 20 次删除

查看文件

@ -47,6 +47,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
- Synchronized the 13-item roadmap status with the actual P02 implementation state.
- Documented external prerequisites for HTTPS certificate pinning, signed updates, and dual-server soak testing.
- Voice input records the microphone and sends the audio for AstrBot to transcribe. The previous
implementation called the browser speech API, which WebView2 does not provide, so it could never
have worked. Refused permission, a missing microphone, and a microphone held by another program are
now reported as three different things.
- Voice, file, and video attachments in a reply are now carried through and played or shown, instead
of being dropped without a marker, an event, or an error. A SILK-encoded voice message says that no
browser can play it rather than showing a player that does nothing.
- The companion can be shown one window the user authorizes: its text or its picture. Authorization is
per window, rate limited, revocable, and off until switched on; a banner shows while it is live.
### Fixed
- Message action buttons render as borderless icons again. Their labels were being laid out inside
@ -71,6 +81,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
and the pet settings page now reflects what the window is actually doing rather than a fixed set
of defaults. They are not yet remembered across restarts.
- The desktop pet's animation now follows the connection again after the first time it is shown.
- Attachments now reach AstrBot. They were sent under a top-level `attachments` key that the server's
chat request does not declare, and unknown keys are ignored rather than rejected, so every
attachment was discarded in silence while the send reported success. They travel inside `message` as
segments now.
- A reply that arrives in several blocks keeps every block. The blocks were appended into one message
and then replaced wholesale by the final frame, so only whichever block that frame restated was
ever shown. A block that merely restates text already streamed is no longer shown twice.
- Streaming replies no longer break into one message per fragment when the server sends no message id
on the opening frames.
- An attachment download is now bounded while it runs rather than measured after being read in full.
- The pet's context menu is anchored to a visible window again.
- One unreachable connection no longer freezes the whole application. The reachability probe now
runs outside the runtime lock, so a slot that is connecting cannot block status, sending,

查看文件

@ -308,6 +308,7 @@ Still not claimed complete: automatic startup activation, real Tauri multi-windo
- Added responsive runtime metadata and chat layout refinements; preserved the existing pet event bus for Q13 state synchronization.
- Updated frontend test mocks for runtime status schema changes.
- Validation: Vitest (6), TypeScript, ESLint, and targeted Prettier checks pass.
## 2026-07-21: frontend UI audit and chat-page visual increment
- Completed the Impeccable audit and recorded the P0-P3 findings in `docs/reports/ui-audit-2026-07-21.md`.
@ -346,7 +347,6 @@ Still not claimed complete: automatic startup activation, real Tauri multi-windo
- Validation: targeted Prettier, ESLint, TypeScript, Vitest 6/6, Vite production build, Playwright 5/5, Rust fmt, Clippy with warnings denied, Rust workspace tests (67), and Rust workspace check all passed.
- Known non-blocking warnings: Node is `24.14.0` while the package requires `>=24.17.0`; Vite reports the intentional lazy `DesktopPetView` chunk above 500 kB.
## 2026-07-21: roadmap completion audit
Roadmap audit and acceptance updates are included in commit f61f440.
@ -378,7 +378,6 @@ Current branch: feat/p02-dual-connections.
Run the full stage gate, refresh the local acceptance checklist, then create the P02 pull request. Do not claim certificate pinning, signed updates, or dual-server soak until the external prerequisites are supplied.
## 2026-07-21: full local stage gate
- Frontend lint, TypeScript, Vitest (9 tests), Vite production build: passed.
@ -573,7 +572,7 @@ Current stage: P02 dual connections, branch `feat/p02-dual-connections`. Six com
- **F-19** One profile can no longer occupy both runtime slots. Enforced inside `activate_slot`
(which also covers startup auto-connect), cross-checked against `connection_slots` in the
command, and the operations switch guard now covers probe and disconnect. Both rules are
negative — they ask only whether the profile is bound to the *other* slot — because auto-connect
negative — they ask only whether the profile is bound to the _other_ slot — because auto-connect
activates from `auto_connect_slot` and never writes `connection_slots`.
- **F-18** Sends are validated before anything is written to history, via a new read-only
`ensure_slot_can_send`. A failure that the server never received marks the row rather than
@ -698,3 +697,30 @@ Rust 112 passed / 2 ignored. Frontend 29 passed / 6 files. Playwright 5 passed.
Verified in a browser against the real stylesheet rather than by inspection: four visible fields
plus a collapsed advanced section, the insecure checkbox appearing only for `http://` and carrying
`required`, and the display name resolving to identity@host.
## 2026-07-27 夜 · 语音、窗口读取与游戏陪伴
完整记录见 [voice-and-awareness-2026-07-27.md](./reports/voice-and-awareness-2026-07-27.md),
边界与策略见 [ADR-0008](./decisions/ADR-0008-screen-awareness-and-voice-boundary.md)。
按队列顺序推进:A 段清掉卡住这三个功能的前期修复(分段回复丢内容、非图片媒体帧、出站附件契约、
下载体积守卫),B 段实施功能本体(策略模块、窗口读取命令、送往陪伴槽位、语音录制)。七个提交,
每个都在门槛全绿后才推送。
**已可用**:语音录制与发送(服务端 STT 待用户配置 provider)、语音/文件/视频回复的接收与播放、
单窗口授权读取与把文本或画面发给陪伴槽位、常驻的读屏指示器与终止开关。
**已修的沉默缺陷**:附件从未真正送达 AstrBot(放在服务端不读的键里);分段回复只显示其中一段;
CSP 缺 `media-src` 会让语音在发布版无法播放而 dev 无感。
**未完成**:游戏陪伴受阻于 `capture.rs` 用 GDI `PrintWindow`,捕获不到硬件加速的游戏画面(F-80,
需改 `Windows.Graphics.Capture`);WebView2 麦克风权限行为需真机确认(F-81);STT provider 属用户
决策(F-82);只能授权前台窗口,无窗口选择器(F-83)。
### 测试状态
Rust 139 通过(`astrbot-desktop` 113、`desktop-protocol` 26),前端 59 通过 / 11 文件,
Playwright 5 通过,`npm run build` 通过。25 处刻意回归全部被对应测试抓到。
`cargo test --workspace`(含集成测试)与 `npm run tauri:build` **未执行**——`astrbot-desktop.exe`
被运行中的 dev 进程占用。遵守工作流「不得声称未执行的检查已通过」,这两项记为待补。

查看文件

@ -1,7 +1,7 @@
# AstrBot Desktop 修复队列
基于 2026-07-26 全源码审计 · 共 78 项 · 8 个批次
(原 73 项 + 2026-07-27 桌宠窗口审计补编 F-75 – F-79)
基于 2026-07-26 全源码审计 · 共 82 项 · 8 个批次
(原 73 项 + 2026-07-27 桌宠窗口审计补编 F-75 – F-79 + 语音/屏幕读取补编 F-80 – F-83)
> 配套审计档案:[full-source-audit-2026-07-26.md](./full-source-audit-2026-07-26.md)。
> 本文中的 `P0-1` / `P1-7` 等编号均指向该档案中的对应发现。
@ -319,6 +319,18 @@ N-12、N-13 是 `4f73c08` **自身引入的回归**——把窗口从销毁改
**本批未修、已编号**:F-75 – F-79,见下。
### F-80 – F-83 语音与屏幕读取补编(2026-07-27 夜)
来自语音/窗口读取实施过程中确认的四项。前三项**不是缺陷队列意义上的缺陷**,而是实施后暴露的真实
阻塞,按队列惯例统一编号以便追踪。
| 新编号 | 位置与实质 | 性质 | 验收 |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **F-80** | `windows/capture.rs` 用 GDI 的 `PrintWindow`。它捕获不到硬件加速的游戏画面——DirectX/Vulkan 的后台缓冲不经过 GDI,结果是黑图或陈旧内容 | 真实技术墙。**故意未绕过**:给模型送黑图比报错更糟 | 改用 `Windows.Graphics.Capture` 后,全屏游戏窗口的截帧内容与屏幕一致 |
| **F-81** | WebView2 的麦克风访问触发 `PermissionRequested`,由宿主应用处理;wry 只在 `clipboard: true` 时注册处理器,Tauri 该项默认 false,本应用未开启。因此结果由 WebView2 默认行为决定,无法在不出真机构建的情况下确认 | 未知,需真机 | 装包后按「语音输入」,记录是弹窗/自动允许/自动拒绝;若为自动拒绝,需在 wry 层注册处理器 |
| **F-82** | 服务端 STT 需要用户配置 provider(API key 或自托管模型)。AstrBot 的 STT 在 `PreProcessStage`、TTS 在 `ResultDecorateStage`,均由默认为 `False` 的配置开关控制 | **用户决策**,不得代为选择——这是唯一会把用户语音送往外部的环节。TTS 可用 Edge TTS 零密钥开启 | 用户配好 provider 后,一段录音能回文本 |
| **F-83** | 只能授权**前台**窗口:`windows/` 下没有非前台窗口枚举,因此无法做「窗口选择器」。现以「给你几秒切到目标窗口」代替,并拒绝抓到本进程窗口 | 缺失能力 | 出现可选列表,且列表不泄漏未授权窗口的内容(只列标题与进程) |
## 功能空缺盘点(2026-07-27)
用户询问语音聊天、窗口感知、游戏陪伴是否已有。三项**均在既定产品范围内**
@ -373,21 +385,21 @@ N-12、N-13 是 `4f73c08` **自身引入的回归**——把窗口从销毁改
## R5 · 协议健壮与契约治理批
| ID | 来源 | 位置 | 动作 | 验证 |
| -------- | ----- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **F-26** | P1-5 | `gateway_client.rs:179-184,282-284` | `UnsupportedEventType` / `InvalidPayload` 降级为事件级跳过(记日志、推进 `last_event_id`),仅版本/身份不匹配保持终态 | 单测:mock 推未知事件类型 → 槽位保持 Connected,后续事件正常 |
| **F-27** | P2-15 | `envelope.rs:171` 及各 payload | 信封与只读 payload 移除 `deny_unknown_fields`(`ToolProposal`/`ToolResult` **保留**);或解析失败跳过并推进游标 | 单测:信封带附加字段仍能解析;不再出现重放死循环 |
| **F-28** | P1-8 | `docs/protocol/v1/schemas/`;`tests/protocol_contract.rs` | 重跑 `export_schemas --write`;新增测试比对 `generated_schemas()` 与磁盘文件 | `cargo test` 即可发现漂移;`connection-profile.schema.json` 含 `remoteDisplayName` |
| **F-29** | P2-16 | `astrbot.rs:17-43`;`src/features/chat/types.ts:13`;`ChatPanel.tsx:240`;README | `TransportKind` 加 `#[serde(rename = "astrbot-openapi")]` 统一两套拼写,前端 enum 与文档同步(**跨端原子改动,一次落地**;DB 值不变,无迁移) | 全库 grep 无 `astr-bot-open-api` 残留 |
| **F-30** | P2-5 | `astrbot_client.rs:128-133,431-438` | 删除恒 false 的身份自比较,或改为探测可观测特征后再比对;文档明示 AstrBot 身份为 URL 派生 | 代码无死分支;`docs/decisions/` 记录该限制 |
| **F-31** | P2-19 | `mock-gateway/src/routes.rs:196-206`、`state.rs:161-173`、`config.rs:29-31` | `Lagged` 改 `break`(迫使走重连重放);cursor 未命中先发 gap 事件;`server_instance_id` 掺端口 | soak 增加 sequence 单调无缺口断言 |
| **F-32** | P2-17 | `astrbot.rs:381-444` | complete 后记录 per-message 完成标记,同 id 的后续 plain/complete 需显式重新开窗或忽略 | 单测覆盖"重复 complete"与"complete 后迟到 plain" |
| **F-33** | P2-18 | `astrbot.rs:336-353` | 非图片媒体输出通用占位标记;`pending_media` 改 FIFO 队列 | 单测:`record` + `attachment_saved` 产出可见标记;双图交错不丢 |
| **F-34** | P2-13 | `commands.rs:341`;`ChatPanel.tsx:916-917` | mapper 为无 `message_id` 的流合成稳定流内 id(如 `synthetic-{stream}`),前后端同步取消 event_id 回退 | 单测:省略 message_id 的多帧流合并为一条消息 |
| **F-70** | P2-6 | `astrbot_client.rs:383-388` | `download_attachment` 先查 `Content-Length`,改流式累读并在超过 16MiB 时立即中断,不再整体读入内存后才校验 | 单测:mock 返回超限 body,客户端在读满前返回超限错误且内存占用有界 |
| **F-71** | P2-7 | `gateway_client.rs:121-126` | `health()` 与 SSE 一致附带 bearer | 单测:mock 对无 bearer 的 health 返回 401,激活仍成功即失败 |
| **F-72** | P2-8 | `gateway_client.rs:237-238` | 仅在「连接存活超阈值且收到过事件」时重置退避,避免服务端接受即优雅关流时进入约 10 次/秒热重连 | 单测:mock 接受连接后立即关闭,断言重连间隔单调增长 |
| **F-73** | P2-29 | `astrbot_client.rs:554-565` | JWT `exp` 判定改 `exp <= now + 30s`;不可解析的 token 打 debug 日志 | 单测:`exp` 落在 30 秒内的 token 被判为过期 |
| ID | 来源 | 位置 | 动作 | 验证 |
| --------------------------- | ----- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **F-26** | P1-5 | `gateway_client.rs:179-184,282-284` | `UnsupportedEventType` / `InvalidPayload` 降级为事件级跳过(记日志、推进 `last_event_id`),仅版本/身份不匹配保持终态 | 单测:mock 推未知事件类型 → 槽位保持 Connected,后续事件正常 |
| **F-27** | P2-15 | `envelope.rs:171` 及各 payload | 信封与只读 payload 移除 `deny_unknown_fields`(`ToolProposal`/`ToolResult` **保留**);或解析失败跳过并推进游标 | 单测:信封带附加字段仍能解析;不再出现重放死循环 |
| **F-28** | P1-8 | `docs/protocol/v1/schemas/`;`tests/protocol_contract.rs` | 重跑 `export_schemas --write`;新增测试比对 `generated_schemas()` 与磁盘文件 | `cargo test` 即可发现漂移;`connection-profile.schema.json` 含 `remoteDisplayName` |
| **F-29** | P2-16 | `astrbot.rs:17-43`;`src/features/chat/types.ts:13`;`ChatPanel.tsx:240`;README | `TransportKind` 加 `#[serde(rename = "astrbot-openapi")]` 统一两套拼写,前端 enum 与文档同步(**跨端原子改动,一次落地**;DB 值不变,无迁移) | 全库 grep 无 `astr-bot-open-api` 残留 |
| **F-30** | P2-5 | `astrbot_client.rs:128-133,431-438` | 删除恒 false 的身份自比较,或改为探测可观测特征后再比对;文档明示 AstrBot 身份为 URL 派生 | 代码无死分支;`docs/decisions/` 记录该限制 |
| **F-31** | P2-19 | `mock-gateway/src/routes.rs:196-206`、`state.rs:161-173`、`config.rs:29-31` | `Lagged` 改 `break`(迫使走重连重放);cursor 未命中先发 gap 事件;`server_instance_id` 掺端口 | soak 增加 sequence 单调无缺口断言 |
| **F-32** | P2-17 | `astrbot.rs:381-444` | complete 后记录 per-message 完成标记,同 id 的后续 plain/complete 需显式重新开窗或忽略 | 单测覆盖"重复 complete"与"complete 后迟到 plain" |
| **F-33**(已修 2026-07-27) | P2-18 | `astrbot.rs:336-353` | 非图片媒体输出通用占位标记;`pending_media` 改 FIFO 队列 | 单测:`record` + `attachment_saved` 产出可见标记;双图交错不丢 |
| **F-34** | P2-13 | `commands.rs:341`;`ChatPanel.tsx:916-917` | mapper 为无 `message_id` 的流合成稳定流内 id(如 `synthetic-{stream}`),前后端同步取消 event_id 回退 | 单测:省略 message_id 的多帧流合并为一条消息 |
| **F-70**(已修 2026-07-27) | P2-6 | `astrbot_client.rs:383-388` | `download_attachment` 先查 `Content-Length`,改流式累读并在超过 16MiB 时立即中断,不再整体读入内存后才校验 | 单测:mock 返回超限 body,客户端在读满前返回超限错误且内存占用有界 |
| **F-71** | P2-7 | `gateway_client.rs:121-126` | `health()` 与 SSE 一致附带 bearer | 单测:mock 对无 bearer 的 health 返回 401,激活仍成功即失败 |
| **F-72** | P2-8 | `gateway_client.rs:237-238` | 仅在「连接存活超阈值且收到过事件」时重置退避,避免服务端接受即优雅关流时进入约 10 次/秒热重连 | 单测:mock 接受连接后立即关闭,断言重连间隔单调增长 |
| **F-73** | P2-29 | `astrbot_client.rs:554-565` | JWT `exp` 判定改 `exp <= now + 30s`;不可解析的 token 打 debug 日志 | 单测:`exp` 落在 30 秒内的 token 被判为过期 |
上列四项系 2026-07-27 补编。它们与 F-26、F-30 同处 `gateway_client.rs` / `astrbot_client.rs`,按本队列
「同文件相邻改动合并进同一批」的编排原则归入 R5;放入 R4 会让两个可并行分支争夺同一文件。

查看文件

@ -0,0 +1,219 @@
# 语音 · 窗口读取 · 游戏陪伴 实施记录(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) |