From 350c6fd3ad725eccea06e735157f1200806ea746 Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Mon, 27 Jul 2026 13:46:42 +0800 Subject: [PATCH] feat(companion): add dedicated voice and game surfaces --- CHANGELOG.md | 2 + docs/decisions/pending-decisions.md | 16 +- docs/implementation-plan.md | 23 ++- docs/implementation-queue.md | 45 +++++ docs/progress.md | 26 +++ ...ui-and-screen-awareness-plan-2026-07-27.md | 184 ++++++++++++++++++ ...ness-understanding-framework-2026-07-27.md | 184 ++++++++++++++++++ docs/错题本.md | 61 ++++++ src/App.test.tsx | 35 +++- src/App.tsx | 25 ++- src/pages/CompanionPages.tsx | 118 +++++++++++ src/styles.css | 142 ++++++++++++++ 12 files changed, 850 insertions(+), 11 deletions(-) create mode 100644 docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md create mode 100644 docs/reports/screen-awareness-understanding-framework-2026-07-27.md create mode 100644 docs/错题本.md create mode 100644 src/pages/CompanionPages.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index e7edb65..9a72fb3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and ### Added +- Separate companion navigation for text chat, voice chat, and game companion. The game surface remains explicitly unavailable until Windows.Graphics.Capture has validated real DirectX/Vulkan frames. +- Screen-awareness implementation framework for scoped display consent, WGC capture, local privacy/quality gates, multimodal AstrBot validation, and low-interruption response control. - Debug-level tracing of AstrBot SSE frame shapes: frame type, which identity fields are present, and the key names inside `data`. No payload text is recorded. Enable with `RUST_LOG`. - Q10-Q15 chat experience increment: lightweight Markdown rendering, message actions, generation controls, session actions, connection controls, and responsive chat layout. - AstrBot OpenAPI adapter foundation: SSE mapper, dual-slot runtime skeleton, credential enrollment IPC, transport-aware profiles (ADR-0005). diff --git a/docs/decisions/pending-decisions.md b/docs/decisions/pending-decisions.md index f18707f..4c2f904 100644 --- a/docs/decisions/pending-decisions.md +++ b/docs/decisions/pending-decisions.md @@ -101,11 +101,23 @@ - Safe interim rule: keep provisional Desktop protocol as the internal normalized model and Mock Gateway contract; implement a Rust `AstrBotAdapter` for real servers. Do not claim compatibility and do not rewrite the whole client. - Open items requiring live container probe: actual SSE type sequence, JWT expiry handling in practice, server-instance identity substitute, dual-profile isolation against one or two containers, and whether operations tooling remains Desktop-local for MVP. - Stop boundary: if live probe proves only browser-cookie auth works, or requires AstrBot core changes for basic text chat, pause and escalate before coding the adapter. -- Interaction with existing open items: updates assumptions in PD-0009 and PD-0011; credential storage remains governed by PD-0010. +- Interaction with existing open items: updates assumptions in PD-0009 and PD-0011; credential storage remains governed by PD-0010. ### PD-0013 live probe update (2026-07-20) - Live target `http://192.168.31.210:26285` accepted API Key auth and streamed chat SSE from `POST /api/v1/chat`. - Dual usernames/session ids remained isolated on one server instance. - Provisional `/desktop/v1` remains non-native; adapter approach confirmed. -- Chat MVP connectivity is unblocked. Server identity substitute, JWT login path, file/WS paths, and operations proposal source remain open. +- Chat MVP connectivity is unblocked. Server identity substitute, JWT login path, file/WS paths, and operations proposal source remain open. + +## PD-0014: Scheduled screen awareness scope and consent + +- Date noted: 2026-07-27 +- Status: direction selected; implementation remains blocked on the required full-desktop Spike and acceptance gates. Planning artifact: docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md. +- Decision update (2026-07-27): the product owner selected option B, the scoped full-desktop direction. This approves discovery and design only; it does not authorize capture code before the required Spike passes. +- Conflict: the requested product direction asks for randomly timed screen captures after a settings toggle, while ADR-0008 only permits a single user-authorized foreground window and requires a visible indicator, a stop control, Companion-only delivery, no on-disk raw frames, and Rust-owned policy enforcement. +- Proposed safe interpretation: “random” means random trigger time, not an unbounded random capture target. V1 may schedule captures only for a live, explicitly authorized foreground-window session. The interval is a hard minimum between successful captures and the configured probability is evaluated only after that interval has elapsed. +- Chosen scope direction: add a full-desktop capability after Spike approval. The eventual consent UI must require the user to select either one monitor or an explicit all-monitors scope; the scheduler is bound to that stable scope and may never choose a different monitor by itself. +- Mandatory gates before implementation: separate scope-specific consent, revised threat model, Windows.Graphics.Capture Spike results, lock-screen/full-screen/protected-content/sensitive-app handling, visible indicator and stop-path validation, Companion-only delivery, and real AstrBot visual acceptance. +- Non-negotiable exclusions: no hidden capture, browser-history collection, input logging, process injection, or automatic delivery to Operations. +- Safe interim rule: preserve the current capture policy unchanged until the full-desktop Spike has passed and the product owner accepts its evidence. C1–C3 page work may be planned independently; no scheduler, persistence migration, or capture-scope expansion is implemented in this planning phase. diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 579722e..6447959 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -149,4 +149,25 @@ The quick window and bubble are presentation surfaces over the same runtime; the 1. 启动时读取并校验自动连接 Profile。 2. 按固定槽位独立激活 Rust-owned Runtime。 3. 为失败槽位保留可诊断状态,不影响另一槽位。 -4. 补充检查结果并进入聊天运行时事件订阅。 +4. 补充检查结果并进入聊天运行时事件订阅。 + +## 2026-07-27 规划增量:陪伴体验拆分与屏幕感知(未开始) + +1. 先以 docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md 作为 C1–C8 的设计基线;本轮不编写产品代码。 +2. 将“聊天、语音聊天、游戏陪玩”定义为共享同一运行时的三个展示入口,不允许为页面复制连接、会话或权限。 +3. 将定时屏幕感知放入“诊断与设置”,并将开关、授权、调度、限频、随机判定和停止路径视为同一 Rust-owned 安全能力。 +4. 在 PD-0014 获得范围决定前,不扩展当前的单窗口授权捕获;在 WGC Spike 通过前,不实现硬件加速游戏陪玩。 +5. 后续每阶段均需更新 docs/progress.md、错题本、相关 ADR/协议文档及验收证据后才可标记完成。 + +## 2026-07-27 C1 完成记录:陪伴入口页面壳 + +- 已完成:语音聊天与游戏陪玩从文字聊天中拆出独立导航和懒加载页面,保留一个共享聊天运行时。 +- 已完成:游戏页将 WGC 设为明确的不可用状态,不触发屏幕读取、全桌面捕获、调度或新的 Tauri command。 +- 已完成:导航图标设为 aria-hidden,避免图标字符污染可访问名称;App 回归测试覆盖两个新入口与禁用状态。 +- 已验证:typecheck、lint、Vitest 60/60、Vite 生产构建和本轮文件的 Prettier 检查。 + +## 2026-07-27:屏幕感知理解框架(评估完成,未开发) + +- 详细框架:`docs/reports/screen-awareness-understanding-framework-2026-07-27.md`。 +- 方案 B 的实施顺序固定为 S0 WGC Spike -> S1 范围授权与设置 -> S2 Rust 调度/策略 -> S3 多模态契约与视觉验收 -> S4 游戏陪玩接入 -> S5 隐私与人工验收。 +- 当前只具备短时、单前台窗口的手动读取;不得将其宣传为全桌面随机观察或游戏识屏。 diff --git a/docs/implementation-queue.md b/docs/implementation-queue.md index 1e433c0..6b0e2da 100644 --- a/docs/implementation-queue.md +++ b/docs/implementation-queue.md @@ -221,3 +221,48 @@ The roadmap items are implemented locally as follows: 13. Final acceptance: local gate is ready; external release acceptance is pending the prerequisites below. The following are deliberately not marked complete: HTTPS certificate pinning, signed updater delivery, and real dual-server soak. They require external infrastructure or release secrets and must not be faked in local development. + +## 2026-07-27:陪伴体验页面拆分与定时屏幕感知(C1 已完成) + +权威规划见 docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md,安全冲突与决策门见 PD-0014。 + +### C0:屏幕感知理解框架复核(2026-07-27,完成;未开发) + +- 评估结论写入 `docs/reports/screen-awareness-understanding-framework-2026-07-27.md`:全桌面“看一看”必须拆为 WGC 授权、质量门、最小上下文信封、视觉模型验收、低打扰决策和可撤销审计,不能等同于定时截图。 +- 在 C2-C4 前新增阻塞子阶段 S0:WGC 对显示器、游戏、锁屏、受保护内容、敏感应用、拔插和资源预算的 Spike;未通过时绝不扩展当前单窗口 GDI 能力。 +- 参考插件只借鉴总开关、间隔、概率、时段、互动风格、冷却、触发原因与手动状态页;不引入历史/输入轨迹、长期观察档案、远程桥接或录屏。 + +验收:框架明确“随机仅指触发时间”、Companion-only、无原始内容持久化、真实视觉验收及 S0-S5 的逐阶段停止条件;本轮无 `src/`、`src-tauri/` 或数据库改动。 + +### C1:聊天、语音聊天、游戏陪玩三页面壳 + +- 在现有“聊天”之后增加“语音聊天”“游戏陪玩”两个独立导航入口。 +- 三页面共享已有连接、会话、消息和权限状态;不得各自创建 REST/SSE 客户端或复制 SQLite 数据。 +- 聊天页只承载文字/附件会话;语音页承载录音、播放和转写状态;游戏页承载陪玩会话状态。 + +验收:导航可键盘访问;切换页面不丢流式消息;两个新增页面无新本机权限。 + +### C2:屏幕感知设置页与安全状态模型 + +- 在“诊断与设置”增加屏幕感知分组:总开关、授权状态、最短触发间隔、概率、活跃时段、停止和脱敏回执。 +- 默认关闭;随机只表示触发时机,绝不随机选择未授权的窗口、显示器或应用。 +- 方案 B 已选:C2–C6 仍受 PD-0014 约束,必须先通过 WGC、显示器范围专属授权、锁屏/受保护内容和敏感应用 Spike,才可扩展当前单窗口范围。 + +验收:未授权、关闭、锁屏、授权过期、目标变化和断连均不能上传画面;活跃会话始终存在可见指示器与停止按钮。 + +### C3:Rust 定时调度、附件发送与主动回应 + +- 在 Rust 侧实现概率判定、硬最短间隔、活跃时段、回复冷却和脱敏审计;React 不拥有调度或权限决定。 +- 只发送给 Companion;沿用 message 内附件段的已验证 AstrBot 出站契约。 +- 原始画面和窗口文本不写入数据库、日志、快照或测试夹具。 + +验收:概率 0 永不触发、概率 100 仅在到期后触发一次、停止后不再触发;真实 AstrBot 侧确认模型收到图片。 + +### C4:全桌面与游戏陪玩 Windows.Graphics.Capture Spike(方案 B) + +- 先验证 WGC 对单显示器、全部显示器和 DirectX/Vulkan 游戏窗口的非黑帧捕获;记录 CPU、GPU、内存、显示器拔插、最小化、窗口切换、锁屏和受保护内容行为。 +- 设计独立的范围专属授权:用户必须明确选定单显示器或全部显示器;随机调度只能复用该范围,不能自行扩张或改选目标。 +- Spike 通过前,游戏陪玩和全桌面感知只显示真实阻塞说明,不能发送 GDI 黑图或声称“正在观察”。 +- 禁止输入模拟、进程注入和游戏内存读取;自动画面只送 Companion,始终显示指示器和停止入口。 + +验收:单显示器和全部显示器均通过 WGC 真实画面、资源预算、敏感/受保护内容降级与可撤销授权测试后,才进入正式全桌面调度或游戏陪玩会话开发。 diff --git a/docs/progress.md b/docs/progress.md index 44298de..97549c7 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -724,3 +724,29 @@ Playwright 5 通过,`npm run build` 通过。25 处刻意回归全部被对应 `cargo test --workspace`(含集成测试)与 `npm run tauri:build` **未执行**——`astrbot-desktop.exe` 被运行中的 dev 进程占用。遵守工作流「不得声称未执行的检查已通过」,这两项记为待补。 + +## 2026-07-27 · 陪伴体验页面与屏幕感知规划(未开发) + +- 已完成:根据当前 UI 截图定义“聊天、语音聊天、游戏陪玩”三个独立导航入口;屏幕感知配置归入“诊断与设置”。 +- 已完成:审阅 menglimi/astrbot_plugin_screen_companion 的行为与配置维度,并写入本项目适配规划:docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md。 +- 已完成:将“随机定时全屏捕获”与 ADR-0008 的单窗口显式授权边界冲突记录为 PD-0014。 +- 已决定:产品所有者于 2026-07-27 选择方案 B(全桌面方向);它要求用户选定单显示器或全部显示器,并先完成 WGC、范围授权、锁屏/受保护内容、敏感应用与真实 AstrBot 图像验收。 +- 规划建立时:C1–C8 的任何代码、数据库迁移、协议变更、调度器或 WGC Spike 均未开始;C1 的后续完成记录见本节下方。 +- 阻塞:方案 B 的必要 Spike 尚未开始;游戏陪玩还受 F-80(WGC)阻塞。 +- 测试状态:本次仅文档规划,未新增或重跑测试。 + +## 2026-07-27 · C1 陪伴入口页面壳 + +- 已完成:在主导航中将“聊天、语音聊天、游戏陪玩”拆为三个独立入口;导航图标标记为装饰性,按钮可访问名称不再包含图标字符。 +- 已完成:新增语音聊天准备页,明确默认 Companion、录音/上传/转写/播放边界与 C2 接入状态;未复制 REST、SSE、会话或消息存储。 +- 已完成:新增游戏陪玩准备页,明确 Companion-only、范围授权和 WGC 阻塞;不会显示伪造的“正在观察”或发送 GDI 黑图。 +- 代码范围:src/App.tsx、src/pages/CompanionPages.tsx、src/styles.css、src/App.test.tsx。 +- 验证:App 定向测试 7/7;完整前端测试 60/60;typecheck、lint、生产构建通过;本轮四个改动文件已通过 Prettier。 +- 未开始:C2 语音页接入、C3 游戏页接入当前授权窗口状态、以及方案 B 的任何 WGC/全桌面/调度实现。 + +## 2026-07-27:屏幕感知理解框架复核(无代码变更) + +- **完成**:审计了当前单窗口 `PrintWindow` 链路、Companion-only 策略和已修复的图片附件段;将方案 B 的完整理解链路、数据最小化、WGC Spike、真实 AstrBot 视觉验证和 S0-S5 队列写入 `docs/reports/screen-awareness-understanding-framework-2026-07-27.md`。 +- **当前阻塞**:S0 WGC Spike 尚未执行;因此全桌面捕获、硬件加速游戏观察、定时自动观察和“Bot 已理解画面”都未实现。 +- **下一步**:先执行 S0,并以非黑帧、保护内容/锁屏降级、资源预算、可撤销授权和可见停止入口的实测证据决定是否进入 S1。 +- **验证**:本轮为文档评估,无功能代码、数据库、构建产物或协议改动,未运行构建门槛。 diff --git a/docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md b/docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md new file mode 100644 index 0000000..42779c9 --- /dev/null +++ b/docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md @@ -0,0 +1,184 @@ +# 陪伴体验页面拆分与定时屏幕感知规划(2026-07-27) + +> 状态:C1 页面壳已完成;C2–C8 尚未开始。 +> +> 本文定义“语音聊天”“游戏陪玩”的独立入口,以及随机触发的屏幕感知架构、验收和开发队列。初始规划阶段未改代码;后续 C1 已按本文实现导航和页面壳,但未修改数据库、协议或本机捕获能力。 + +## 1. 输入、参考与边界 + +### 1.1 本次目标 + +1. 左侧导航增加两个独立页面:**语音聊天**与**游戏陪玩**;文字聊天继续保持独立。 +2. 将“窥屏”作为内部俗称,面向用户统一显示为 **屏幕感知**,放在“诊断与设置”中。 +3. 用户可以开启定时随机触发,并设置最短触发间隔与触发概率;触发时将当前授权范围的画面发送给 AstrBot,让 Companion 知道用户正在做什么。 +4. 效果参考 menglimi/astrbot_plugin_screen_companion,但不复制其实现。 + +### 1.2 已有能力与不可突破的边界 + +- 当前页面只有“聊天、连接、桌面行为、桌宠、诊断与设置”五项导航;本规划在“聊天”之后插入两个新入口,而不是把所有能力继续堆进聊天页。 +- 现有实现已能录制语音、按附件通路发送给 AstrBot、播放语音回复;STT provider 仍由用户在 AstrBot 侧自行配置。 +- 现有屏幕能力仅支持:用户在短时授权窗口内切到一个前台窗口,读取该窗口的文本或图片,送给 **Companion** 槽位;会话可停止、有限频、具有常驻橙色指示器,原始画面不落盘。 +- GDI PrintWindow 无法可靠抓取硬件加速游戏画面;游戏陪玩要支持 DirectX/Vulkan 游戏,必须先完成 Windows.Graphics.Capture(WGC)Spike。禁止把黑图静默发送给模型。 +- 不增加输入监听、浏览器历史读取、鼠标键盘控制、进程注入、游戏内存读取、隐藏采集或自动向 Operations 槽位发送画面。 + +### 1.3 参考仓库的可借鉴点与许可处理 + +已审阅 menglimi/astrbot_plugin_screen_companion 的 main 分支提交 325ec215342c0a0fa7cf639afe6e4a19d4fbb6fd(2026-07-27 浅克隆至项目 .tmp/refs)。可借鉴的产品行为是:总开关、检查间隔、触发概率、活跃时间段、互动风格、主动消息冷却、触发原因可解释、手动识屏与状态页。 + +该参考还包含浏览历史、远程接收、录屏、日记、音量与使用轨迹等更广泛能力;本项目 MVP 不纳入。参考仓库采用 AGPL-3.0,本项目只借鉴公开可观察的产品思路和配置维度;不得复制其 Python、WebUI、提示词、资源或实现结构。任何未来代码复用必须先单独完成许可证审查。 + +## 2. 前端信息架构:三个独立陪伴入口 + +截图中左侧“聊天”下方的两个预留位置,按下表落位: + +| 导航项 | 说明 | 主要对象 | 与其他页面的关系 | +| ---------- | -------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- | +| 聊天 | 文字、图片、文件与普通会话 | Companion / Operations | 保留现有完整会话与附件能力,不再承载语音和陪玩控制台 | +| 语音聊天 | 按住说话、语音回复播放、转写状态 | 默认 Companion;Operations 必须显式切换 | 复用同一聊天运行时、同一会话和消息库,不新建连接 | +| 游戏陪玩 | 游戏会话、目标窗口、画面状态、陪玩事件 | 仅 Companion | 复用屏幕感知授权与发送通路;WGC 前只展示不可用原因与手动窗口读取入口 | +| 连接 | Profile 与两个活动槽位 | Companion / Operations | 不变 | +| 桌面行为 | 快速聊天与状态气泡 | 本地窗口 | 不变 | +| 桌宠 | 形象与活动范围 | 本地桌宠 | 不变 | +| 诊断与设置 | 增加“屏幕感知”分组 | 本地策略 | 只有这里能开启、配置或关闭定时感知 | + +### 2.1 聊天页(收敛后的职责) + +- 显示文字会话、图片/文件/视频、普通输入框和附件发送。 +- 保留现有 Companion / Operations 顶部槽位切换,不隐藏运维会话。 +- C2 将把语音按钮从聊天输入区移出,替换为“在语音聊天中继续”的轻量入口;C1 只创建独立页面壳,尚不改变现有录音通路。 +- 聊天页只显示屏幕感知的简短状态胶囊,例如“屏幕感知:已暂停”;不放开关、概率或捕获范围设置。 + +### 2.2 语音聊天页 + +首屏布局:上方为目标槽位和连接/STT/TTS 状态;中间为当前会话的转写与语音消息时间线;底部为大号“按住说话”控件、录音计时、取消和发送状态。 + +- 默认绑定 Companion;切换到 Operations 必须在页面内二次确认,且不会改变其他页面的当前槽位。 +- 录音状态明确分为:请求麦克风权限、录音中、上传中、等待服务端转写、失败;每种失败给出可操作说明。 +- 音频回复在原消息时间线内播放;页面不得维护第二份消息或第二条网络连接。 +- 设置区只链接到 AstrBot 的 STT/TTS 前置条件说明;客户端不保存或代选 STT provider。 + +### 2.3 游戏陪玩页 + +首屏布局:顶部是“游戏陪玩未启动 / 观察中 / 暂停 / 不支持”的状态卡;中部展示当前授权目标、最后一次观察的元数据和 Companion 的回应;底部提供“授权前台游戏窗口”“立即发送一次画面”“停止陪玩”。 + +- WGC Spike 未通过前,“开始游戏陪玩”按钮不可用,并固定说明“当前捕获方式无法读取硬件加速游戏画面”;不得假装已观察到游戏。 +- 页面仅管理游戏陪玩会话,不承载全局屏幕感知的概率、间隔与隐私设置。 +- 未来 WGC 可用时,游戏会话仍必须沿用屏幕感知的显式授权、可见指示、停止和 Companion-only 规则。 + +### 2.4 屏幕感知设置页 + +在“诊断与设置”内新增“屏幕感知”分组,按从安全到效果的顺序排列: + +1. 总开关(默认关闭)与常驻风险说明; +2. 捕获范围与授权状态; +3. 最短触发间隔、触发概率、活跃时间段; +4. 当前运行状态、上次触发原因、下次最早可触发时间; +5. “立即停止并清空会话”危险操作; +6. 历史与数据说明:只保留审计元数据,不保存截图或窗口正文。 + +**“随机”定义**:随机的是触发时机。系统不得随机挑选未授权窗口、屏幕或应用;每一次实际捕获都必须落在当前已授权范围内。 + +## 3. 屏幕感知目标效果与实现框架 + +### 3.1 用户可感知的效果 + +用户打开总开关、完成授权并设置“最短 20 分钟、概率 25%”后,客户端在活跃时间内于每个到期检查点进行一次概率判定。命中时: + +1. 外壳显示橙色“正在读取屏幕感知”指示和停止按钮; +2. Rust 本地策略再次检查授权、角色、范围、锁屏状态、最短间隔和连接状态; +3. 抓取一张当前授权范围画面,内存中校验大小与格式; +4. 以 AstrBot OpenAPI 已验证的图片附件段形状发送到 Companion 当前会话; +5. Companion 根据图像作低打扰回应;界面显示“触发原因:间隔已到 + 概率命中”; +6. 原始画面立即释放,不写 SQLite、不写日志、不生成本地相册。 + +失败时不伪造“已观察”状态:无授权、锁屏、目标变化、限频、连接失败、黑图或模型失败均记录为脱敏状态码,并在设置页说明下一步。 + +### 3.2 Rust-owned 状态机 + +Disabled -> SettingsConfigured -> AwaitingExplicitAuthorization -> ActiveAuthorizedScope -> EligibleToEvaluate -> ProbabilityMiss / ProbabilityHit -> LocalPolicyCheck -> CaptureInMemory -> UploadAttachmentAndSendToCompanion -> AwaitingReply or Completed -> Cooldown -> ActiveAuthorizedScope。 + +任何状态在 Stop、revoke、lock、scope changed 或 disconnect 时,回到 Disabled 或 AwaitingExplicitAuthorization。React 仅渲染状态和发起经过参数校验的 Tauri command;调度、随机数、限频、授权有效期、目标校验、发送目标限制和审计都属于 Rust。本地策略必须在上传前重新执行,不能只信任前端开关。 + +### 3.3 建议配置模型(尚未建表) + +| 字段 | 默认 / 范围 | 规则 | +| ---------------------------- | ------------------------------- | ----------------------------------------------------------------------------------- | +| enabled | false | 默认关闭;关闭立即撤销所有会话 | +| scope | selected_display / all_displays | 方案 B 已选;先完成 WGC、范围专属授权与隐私 Spike。调度器只能使用用户固定选定的范围 | +| min_trigger_interval_minutes | 默认 20;5–240 | 成功发送后重新计时;这是硬下限 | +| trigger_probability_percent | 默认 15;0–100 | 只在到达硬下限后抽样;0 表示永不自动触发 | +| active_time_range | 默认全天 | 可选 HH:MM-HH:MM;范围外只允许手动一次性发送 | +| interaction_style | 默认“低打扰” | 影响提示词和回应节流,不影响权限范围 | +| reply_cooldown_minutes | 默认 30;5–240 | 防止模型对相同场景连续打扰 | +| pause_when_locked | 固定 true | 锁屏、无可检查前台窗口、授权过期时不捕获 | + +概率抽样必须使用独立于 UI 的随机源,并在审计中保存“已评估 / 概率未命中 / 策略拒绝 / 已发送”这类原因,不保存图像、OCR 文本、窗口标题原文或模型完整回复。 + +### 3.4 数据、协议与审计边界 + +- **发送路径**:沿用当前已修正的附件上传与 message 段引用;不得回退为服务端会忽略的顶层 attachments 字段。 +- **本地持久化**:仅持久化非敏感设置、授权状态摘要和脱敏观察回执(时间、结果码、范围类型、节流原因);不得持久化截图、窗口文本、Authorization、Token 或模型输入原文。 +- **槽位隔离**:自动与手动屏幕感知均固定 Companion;Operations 不能成为调度目标或接收者。 +- **可见性**:任何活跃会话都显示常驻橙色指示器和“停止”;应用重启、崩溃恢复、锁屏和设置关停都默认关闭会话。 +- **错误处理**:截图大小超限、格式异常、全黑/空帧、目标窗口变化、上传失败、AstrBot 不支持视觉或模型拒绝均应显示状态,不应被吞掉。 + +### 3.5 与参考插件的对齐与刻意不对齐 + +| 参考能力 | 本项目规划 | 原因 | +| ----------------------------------- | -------------------- | ------------------------------------------------------ | +| 总开关、间隔、概率、活跃时段 | 纳入 | 直接满足可控的随机触发体验 | +| 陪伴/低打扰互动风格 | 纳入为提示与节流策略 | 保持主动消息有边界 | +| 手动识屏、状态可解释 | 纳入 | 用户可验证实际发生了什么 | +| 触发冷却与同场景限频 | 纳入 | 防止骚扰与无意义重复 | +| 浏览器历史、输入/使用轨迹 | 不纳入 MVP | 敏感度远高于屏幕授权,超出现有架构范围 | +| 远程接收器、共享目录、Docker bridge | 不纳入 | 桌面客户端直接使用本机 Rust 能力,不扩展网络攻击面 | +| 日记、长期观察档案 | 不纳入 MVP | 与“原始画面不落盘”和最小数据原则冲突,需要单独隐私设计 | +| 录屏识别 | 后续候选 | 先完成 WGC、资源预算、完整告知与授权审查 | + +## 4. 需要先完成的 Spike 与真实验收 + +### 4.1 阻塞性 Spike + +1. **WGC 游戏捕获 Spike**:验证 WGC 能否在 DirectX/Vulkan 硬件加速窗口获取非黑帧,并测量 1 fps 下 CPU、GPU、内存、窗口切换、最小化和受保护内容行为。 +2. **全屏范围 Spike(方案 B 已选)**:以 Windows.Graphics.Capture 验证单显示器与“全部显示器”范围;定义范围专属授权文案、显示器切换、敏感应用/受保护内容处理、锁屏策略和 Windows 权限表现;不通过则不实现全屏。 +3. **真实 AstrBot 多模态验收**:确认服务端实际接收图片附件段、目标模型看见画面、失败时返回何种 SSE/错误。 +4. **主动消息预算 Spike**:验证概率、冷却、手动聊天后静默期与通知权限,避免把“陪伴”实现成打扰。 + +### 4.2 验收清单 + +1. 三个入口在左侧导航独立可达,聊天、语音聊天、游戏陪玩不复制连接或消息运行时。 +2. 屏幕感知默认关闭;未授权时所有自动触发都被 Rust 拒绝。 +3. 最短间隔设为 5 分钟、概率设为 0%,连续等待多个检查点,证明从不上传。 +4. 概率设为 100%,到期后只发送一次,间隔未到前再次检查仍被拒绝并给出剩余时间。 +5. 开启会话后始终可见橙色指示器;点击停止立即撤销所有会话,后续检查不再上传。 +6. 授权窗口变更、锁屏、最小化、捕获黑帧或连接断开时,记录脱敏原因且不向模型发送伪造画面。 +7. 在 AstrBot 服务端确认模型实际看到了图片;本地日志、数据库和测试快照均不含截图、窗口正文或凭据。 +8. WGC 通过前,游戏陪玩明确显示“不支持硬件加速游戏捕获”,不会显示“观察中”。 + +## 5. 建议开发队列(等待批准后执行) + +| 阶段 | 产出 | 前置条件 | 完成标准 | +| ---- | ------------------------------------------------ | ------------------------------- | -------------------------------------------------------------------- | +| C1 | 导航与三个页面的前端壳:聊天、语音聊天、游戏陪玩 | 已完成(2026-07-27) | 路由、空态、无障碍与共享 runtime 边界测试完成;无新本机权限 | +| C2 | 语音聊天页接入现有录音/播放状态 | C1 | 不复制发送/存储逻辑;STT/TTS 前置条件与错误状态可见 | +| C3 | 游戏陪玩页接入当前授权窗口状态 | C1 | 只展示现有能力;WGC 未完成时禁止开始游戏观察 | +| C4 | 屏幕感知设置页与 schema/迁移设计 | 方案 B 的 WGC / 隐私 Spike 通过 | 默认关闭、显示器范围专属授权、参数校验、停止路径和设置恢复测试完成 | +| C5 | Rust 调度器与脱敏观察回执 | C4 | 概率、硬下限、活跃时段、断连/锁屏/授权撤销测试完成 | +| C6 | 画面上传与 Companion 主动回应 | C5 + 真实 AstrBot 探针 | 服务端视觉确认、冷却策略、无原始画面落盘 | +| C7 | WGC 全桌面与游戏捕获、性能/隐私 Spike | C3 | 单显示器/全显示器范围、非黑帧、资源预算、全屏/最小化安全降级验收通过 | +| C8 | 游戏陪玩正式会话 | C6 + C7 | 仅授权范围、可停止、无输入控制、真实游戏验收通过 | + +**当前状态**:C1 已完成:左侧导航、语音聊天页和游戏陪玩页的前端壳已落地,仍共享既有连接/会话运行时,未增加本机权限。C2–C8 尚未开始;不得把本文件视为已交付的自动屏幕感知功能。 + +## 6. 产品决定与仍需决定的事项 + +- **已决定(2026-07-27)**:采用 PD-0014 的方案 B,全桌面方向。全桌面不是隐式默认权限:启用时必须由用户明确选定单显示器或全部显示器;随机只影响触发时间,绝不改变已选范围。 +- **仍需决定**:“低打扰”默认值是否采用本文建议的 20 分钟 / 15% / 30 分钟回复冷却? +- **仍需决定**:游戏陪玩在 WGC 完成前只显示准备页,还是完全隐藏入口?本文建议显示准备页与真实阻塞原因。 +- **实施门槛**:方案 B 在 WGC、范围授权、锁屏/受保护内容、敏感应用、可见指示/停止和真实 AstrBot 图像验收均通过前,不得进入捕获、调度或上传实现。 + +## 7. 本次来源 + +- 用户提供的当前应用截图:导航中聊天下方的两个预留位置。 +- 本项目:src/App.tsx、docs/01_Architecture_Design.md、docs/implementation-queue.md、docs/decisions/ADR-0008-screen-awareness-and-voice-boundary.md、docs/reports/voice-and-awareness-2026-07-27.md。 +- 参考仓库:https://github.com/menglimi/astrbot_plugin_screen_companion,审阅提交 325ec215342c0a0fa7cf639afe6e4a19d4fbb6fd;本地临时阅读副本:.tmp/refs/astrbot_plugin_screen_companion/。 diff --git a/docs/reports/screen-awareness-understanding-framework-2026-07-27.md b/docs/reports/screen-awareness-understanding-framework-2026-07-27.md new file mode 100644 index 0000000..b42c6e3 --- /dev/null +++ b/docs/reports/screen-awareness-understanding-framework-2026-07-27.md @@ -0,0 +1,184 @@ +# 屏幕感知理解框架(方案 B) + +- 日期:2026-07-27 +- 状态:评估完成;仅定义实施框架,**未开发捕获、调度、数据库或网络代码**。 +- 范围:用户可在“诊断与设置”中授权单显示器或全部显示器;在随机时机将授权范围的有限上下文发送给 **Companion**,让已配置视觉能力的 AstrBot 理解用户当前在做什么。 +- 关联决策:`PD-0014`(方案 B)、`ADR-0008`。 +- 参考:已审阅 `menglimi/astrbot_plugin_screen_companion` 的提交 `325ec215342c0a0fa7cf639afe6e4a19d4fbb6fd`。仅借鉴交互与调度模式;该项目为 AGPL-3.0,禁止复制代码、资源、提示词或 WebUI。 + +## 1. 目标与非目标 + +### 目标 + +“Bot 知道用户在做什么”应是一次受限观察形成的**活动上下文**,而非把原始桌面持续上传: + +1. 用户明确授权固定捕获范围; +2. 客户端只在合格的随机时机采集一帧; +3. 本地过滤锁屏、受保护内容、敏感应用、黑帧和重复场景; +4. 将视觉帧与最小、脱敏的上下文信封作为同一条多模态消息送到 Companion; +5. AstrBot 必须使用已经实证可看图的模型; +6. 仅在新场景且未处于冷却期时,Bot 才作低打扰回应; +7. 用户始终能看到状态、原因、最后结果并一键停止。 + +### 非目标 + +- 不做隐藏采集、浏览器历史读取、输入记录、鼠标键盘控制、进程注入、游戏内存读取或录屏。 +- 不随机选择未授权目标;“随机”只表示触发时间。 +- 不向 Operations 自动发送画面、窗口文本或活动摘要。 +- 不持久化截图、OCR/UIA 原文、窗口标题原文、模型完整回复或凭据。 +- 不在 WGC Spike 通过前把 GDI `PrintWindow` 当作全桌面或游戏方案,也不发送可能为黑图的游戏画面。 + +## 2. 当前能力与目标差距 + +| 层级 | 当前已存在 | 方案 B 目标 | 实施前置条件 | +| -------- | ------------------------ | -------------------------------------- | ---------------------------------------- | +| 授权范围 | 短时、单前台窗口会话 | 单显示器或全部显示器的独立、可撤销授权 | WGC + 范围专属同意流程 Spike | +| 捕获 | GDI `PrintWindow` 截窗口 | WGC 采集显示器/游戏真实帧 | 非黑帧、受保护内容、锁屏和显示器变化验证 | +| 内容 | 手动发送窗口文字或图片 | 受控自动观察 + 手动“立即看一眼” | 本地策略、质量检查与调度器 | +| 上下文 | 自由文本提示或单张图 | 图片 + 脱敏活动上下文信封 + 触发原因 | 统一多模态消息构造器 | +| 模型 | 图片附件通路已修复 | 仅向视觉模型配置主动发送 | AstrBot 真实端到端视觉验收 | +| 主动回应 | 无场景去重策略 | 冷却、重复场景抑制、用户聊天静默期 | 本地结果状态与可解释回执 | +| 审计 | 当前会话状态/停止入口 | 只存脱敏结果码和配置 | 数据最小化模型与清理测试 | + +## 3. 端到端理解链路 + +```mermaid +flowchart LR + A[用户:开启总开关并选择显示器范围] --> B[WGC 范围授权] + B --> C[Rust 调度器:时段、间隔、随机判定] + C --> D[本地策略复检:锁屏/断连/敏感/角色] + D --> E[WGC 内存帧] + E --> F[质量与重复场景门] + F --> G[最小上下文信封] + G --> H[AstrBot 图片附件段 + Companion] + H --> I[视觉模型真实理解] + I --> J[本地回应决策:冷却/静默/去重] + J --> K[用户可见回执、状态和一键停止] +``` + +### 3.1 采集层:只得到授权范围的一帧 + +- 提供两种互斥范围:`selected_display`(用户选定的一台显示器)和 `all_displays`(用户明确确认全部显示器)。不提供“自动选择显示器”。 +- 总开关默认关闭;每种范围各自需要单独同意。修改范围、显示器拔插、锁屏、系统会话切换或授权撤销立即暂停。 +- WGC 输出只进入内存;达到尺寸、像素、编码、上传大小预算前不构造网络请求。 +- 游戏陪玩仅在 WGC 对 DirectX/Vulkan 实测为非黑帧后复用该能力;否则固定显示“不支持自动观察”,保留手动窗口读取作为另一条能力。 + +### 3.2 本地过滤与质量门:先决定“不发” + +每次触发均在 Rust 再次检查,任一失败即中止且产生脱敏结果码: + +1. 总开关、范围授权、Companion 连接和活动时段有效; +2. 当前 Windows 会话未锁屏,捕获目标仍存在且范围未变化; +3. 命中敏感应用规则、受保护内容或系统安全桌面时拒绝;规则初版采用保守拒绝,命中后只提示用户而不上传; +4. 图像尺寸/编码/文件大小在预算内,且通过黑帧、透明帧、空白帧检测; +5. 场景指纹与上一次成功观察不高度相似,或用户选择“即使相同也允许”。初版只保存不可逆的短期感知指纹,不保存图片; +6. 回复冷却、用户主动聊天静默期和最近发送间隔均已到期。 + +敏感规则的设计必须可解释:设置页显示“因敏感应用规则未发送”,但默认不展示被拒绝窗口的标题或 OCR 文本。用户可在本地查看规则类别、编辑允许/拒绝策略并随时停用自动观察。 + +### 3.3 上下文信封:图片之外给模型必要而非过量的信息 + +每次合格观察构造一条短生命周期消息: + +- 图片附件:唯一必需的视觉证据;沿用已验证的 `message` 内图片附件段,不再使用顶层 `attachments`。 +- 固定意图:这是经用户授权的一次桌面观察。请判断可见的高层活动;不要猜测不可见内容、凭据或私人信息;若没有帮助价值可不主动回应。 +- 脱敏元数据:观察原因(手动/间隔到期且概率命中)、范围类型、是否游戏会话、用户选择的互动风格。 +- 可选窗口线索:仅在用户开启“增强文字上下文”后,从前台窗口获取经过本地脱敏和长度上限处理的应用类别/UIA 摘要;禁用时绝不读取或上传此类文本。 + +禁止把完整窗口标题、窗口树、OCR 全文、剪贴板、浏览器 URL/历史等作为默认上下文。图片和可选摘要都属于同一次瞬时请求,发送完成后立即释放内存缓存。 + +### 3.4 AstrBot 多模态契约:验证模型真的看到了 + +“HTTP 200”或附件上传成功不能证明模型看到了图片。上线前必须运行真实服务端验收: + +1. 选用明确具有视觉能力的 AstrBot 模型配置;普通文本模型时自动观察不可启用,并说明原因; +2. 使用一组无敏感信息、内容可判定的测试画面; +3. 验证请求的图片附件段在 AstrBot 入站可见; +4. 验证模型能回答画面中可验证的高层事实,而非只复述固定提示; +5. 记录测试时间、模型配置标识(脱敏)和通过/失败结果,不记录测试图片或完整响应; +6. 对失败区分:上传失败、附件形状错误、模型非视觉、模型拒绝、SSE/回复失败。不得把失败标成“已观察”。 + +### 3.5 主动互动决策:少而准,不把监视变成打扰 + +参考插件的总开关、时段、概率、互动风格、主动消息冷却与状态解释模式,客户端采用下列本地决策顺序: + +1. **活跃时段**:不在时段内不采集、不调用模型; +2. **硬最短间隔**:距离上次完成观察(包括概率未命中后的本轮结束)未到最短间隔,不评估; +3. **随机时间**:到期后添加有上限的抖动,再执行一次概率抽样;不会高频轮询或重试; +4. **概率判定**:`0%` 永不自动触发,`100%` 只在每个合格时间窗最多触发一次;概率未命中进入下一个时间窗; +5. **本地策略与质量门**:任一门拒绝即不上传; +6. **场景去重**:相似场景默认不请求模型; +7. **回应冷却**:可发送观察但抑制主动文案,或直接跳过上传,最终策略必须由产品验收确定; +8. **用户聊天静默期**:用户刚在聊天/语音中主动交流时,不用自动观察插话; +9. **互动风格**:仅影响允许后的回应语气,不得改变采集范围或安全策略。 + +建议初始安全默认:最短间隔不低于 20 分钟、概率 25%、无活跃时段即不运行、互动风格为“低打扰”、用户最近主动聊天后 15 分钟静默。具体下限、冷却规则应在 C2 产品文案评审确认后固化。 + +### 3.6 可见性、停止与审计 + +- 捕获范围生效时,外壳常驻橙色指示器显示“正在读取:单显示器/全部显示器”,并提供直接停止入口。 +- 设置页显示最后一次**结果**而非原始内容:时间、手动/自动、结果码、范围类型、触发原因、下次最早评估时间。 +- 停止需同步取消等待中的定时器、当前捕获、上传和后续主动回应;取消竞态必须有测试。 +- 本地只持久化用户设置、授权状态摘要、最近观察时间、脱敏结果码和短期不可逆去重指纹;原始帧、原文摘要及完整模型输出不得进入 SQLite、日志、崩溃报告、测试快照或剪贴板。 + +## 4. 需要的状态模型 + +`Disabled -> Configured -> AwaitingScopeConsent -> AuthorizedScope -> WaitingForWindow -> EligibilityCheck -> ProbabilityMiss | PolicyRejected | Capturing -> QualityRejected | Sending -> AwaitingModel -> ResponseSuppressed | Completed -> Cooldown -> AuthorizedScope` + +以下事件从任何活动态立即中断到 `Disabled` 或 `AwaitingScopeConsent`:停止、撤销、锁屏、范围变化、显示器拔插、敏感内容命中、连接失效、应用退出。界面不得把中断显示为成功观察。 + +## 5. 分阶段开发队列与验收门 + +### S0:WGC 与安全边界 Spike(阻塞后续) + +- 验证单显示器、全部显示器、全屏 DirectX/Vulkan 游戏、最小化/切换、显示器拔插、锁屏、受保护内容和敏感应用下的 WGC 行为。 +- 测量每种范围的 CPU、GPU、峰值内存、编码耗时、帧尺寸和失败类型;定义明确预算。 +- 验收:真实游戏非黑帧;拒绝/降级路径可解释;指示器和停止在每个失败/成功路径均有效;结果写入 Spike 报告。任一关键项失败则不进入 S1。 + +### S1:范围授权、持久化最小设置与状态页 + +- 实现单显示器/全部显示器专属授权、总开关、活跃时段、最短间隔、概率、互动风格与增强文字上下文开关。 +- 验收:没有范围授权不可开启;修改范围必须重新授权;所有配置按 Profile 隔离;默认值安全且无原始内容落盘。 + +### S2:Rust 调度与本地策略门 + +- 将时间、概率、冷却、锁屏、断连、敏感规则、范围校验、质量/去重全部放在 Rust;React 只展示状态和请求手动操作。 +- 验收:概率 0/100、间隔、跨天活跃时段、停止竞态、锁屏、显示器变更、断连、敏感命中、黑帧、重复场景均有单元/集成回归测试。 + +### S3:上下文信封与 AstrBot 视觉验收 + +- 统一构造图片附件段、固定意图和可选脱敏文本;建立模型视觉能力前置检查和失败分类。 +- 验收:在真实 AstrBot 上证明图片抵达且视觉模型可回答测试画面的可验证事实;非视觉模型明确禁用自动观察;附件、文本和错误状态均不跨到 Operations。 + +### S4:主动陪伴与游戏页接入 + +- 把已通过的观察状态接入“游戏陪玩”及设置页;实现低打扰回应、用户聊天静默期和结果时间线。 +- 验收:游戏页只在 WGC 成功后显示“观察中”;冷却和静默期不打扰用户;停止立即终止所有自动链路。 + +### S5:隐私、安全与用户验收 + +- 进行威胁建模、隐私文案审查、可访问性检查、长时运行资源测试、真实游戏和多显示器人工验收。 +- 验收:所有九步端到端清单通过,包含 AstrBot 视觉证据;没有未解释的上传、没有黑图成功记录、没有原始屏幕持久化。 + +## 6. 当前不能开发或不能声称完成的部分 + +- 在 S0 之前,不能宣称全桌面、游戏陪玩自动观察或“Bot 正在看屏幕”。 +- 在 S3 之前,不能宣称 Bot 理解了图片;附件可上传不等于视觉模型已接收和理解。 +- 在 WGC 的受保护内容策略明确前,不能以“尽量捕获”为目标绕过系统限制。 +- 在用户明确选择范围前,不能因概率或“陪伴模式”自动扩展到其他显示器、窗口或应用。 + +## 7. 需要产品确认但不阻塞 S0 的细节 + +| 项目 | 建议默认 | 原因 | +| ------------------ | -------- | ------------------------------------- | +| 最短间隔下限 | 20 分钟 | 降低误触发、资源和打扰 | +| 默认概率 | 25% | 先验证低频体验,避免“被盯着”的感受 | +| 默认活跃时段 | 关闭 | 需要用户主动选择时间段 | +| 增强文字上下文 | 关闭 | 窗口/UIA 文字的隐私风险高于图片元数据 | +| 敏感应用策略 | 保守拒绝 | 先保证不发,再逐条可解释地放开 | +| 相似场景处理 | 默认抑制 | 降低重复上传和重复搭话 | +| 用户主动聊天静默期 | 15 分钟 | 防止 Bot 在对话后立即额外插话 | + +## 8. 实施完成定义 + +只有在 S0-S5 全部通过、真实 AstrBot 视觉验收有证据、停止和隐私边界经人工验证、文档/CHANGELOG/错题本同步且工作区干净后,才可将“看一看”标记为可用功能。 diff --git a/docs/错题本.md b/docs/错题本.md new file mode 100644 index 0000000..ccc478d --- /dev/null +++ b/docs/错题本.md @@ -0,0 +1,61 @@ +# 错题本 + +## 2026-07-27 — 屏幕感知规划阶段复盘 + +- 阶段:陪伴体验页面拆分与屏幕感知规划 +- 类型:API契约 / 功能行为 +- 现象:用户需求中的“随机捕捉屏幕”若直接理解为任意全屏抓取,会绕过当前只允许单窗口显式授权的架构边界,并可能把随机目标、随机时机和游戏捕获混为同一能力。 +- 根因:产品词汇未区分“随机何时触发”与“允许捕获什么范围”;现有 GDI 捕获也不能代表硬件加速游戏画面。 +- 修复或规避:建立 PD-0014;规划中将随机限定为时间判定,V1 仅使用已授权前台窗口;全屏范围与 WGC 游戏捕获分别设置为独立 Spike/决策门。 +- 预防规则:涉及屏幕、音频、输入或跨设备数据时,先写清捕获范围、授权生命周期、可见指示、存储边界、发送目标和失败降级,再排入实现队列。 +- 验证证据:docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md、docs/decisions/pending-decisions.md 的 PD-0014;本次未写产品代码。 + +## 2026-07-27 — 全桌面方向的实施闸门 + +- 阶段:屏幕感知产品决策 +- 类型:功能行为 / 安全边界 +- 现象:产品所有者选择了全桌面方向(PD-0014 方案 B),若把选择误当作立即扩大捕获权限,会绕开对多显示器、锁屏、受保护内容、敏感应用和硬件加速画面的验证。 +- 根因:产品范围决策与技术可行性/安全验收是两个独立闸门;全桌面与游戏窗口都不能由现有 GDI PrintWindow 可靠覆盖。 +- 修复或规避:将方案 B 记录为设计方向,而非实现放行;队列要求 WGC、范围专属授权、可见指示/停止、Companion-only 和真实 AstrBot 图片验收全部通过后才开发捕获或调度。 +- 预防规则:用户选择扩大范围时,记录为“方向已定 + 闸门未过”,并把每个闸门写入队列和验收证据,不能用产品批准替代安全/可行性验证。 +- 验证证据:PD-0014、docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md、docs/implementation-queue.md;本次未写产品代码。 + +## 2026-07-27 — 临时参考源码不应进入项目 lint 范围 + +- 阶段:C1 陪伴入口页面壳验证 +- 类型:测试 / 环境 +- 现象:全仓 lint 扫描到项目 .tmp/refs 下为调研而浅克隆的第三方插件 JavaScript,产生 322 个与本项目无关的 no-undef 等错误。 +- 根因:.tmp 目录未被 ESLint 忽略;调研副本保留在工作区时会被全仓规则当作产品源码处理。 +- 修复或规避:在参考提取完成后,验证路径位于项目 .tmp/refs 内并删除该临时克隆;随后 lint 通过。 +- 预防规则:外部临时参考应放在 lint 排除目录或在运行全仓检查前清理;不得为了第三方源码而放宽项目 ESLint 规则。 +- 验证证据:删除 D:\CODEX\projects\AstrBot-Desktop\.tmp\refs\astrbot_plugin_screen_companion 后,npm.cmd run lint 通过。 + +## 2026-07-27 — 导航图标必须是装饰性内容 + +- 阶段:C1 陪伴入口页面壳 +- 类型:功能行为 / 可访问性 +- 现象:主导航图标与文字共同组成按钮可访问名称,测试和读屏依赖图标字符;更换图标会同时破坏语义和测试选择器。 +- 根因:图标 span 未声明 aria-hidden,导致装饰性字符进入无障碍名称计算。 +- 修复或规避:将导航图标设为 aria-hidden,并把测试定位改为文字标签;新增语音聊天和游戏陪玩导航回归测试。 +- 预防规则:纯装饰图标一律 aria-hidden;交互元素用可读文字或显式 aria-label 提供稳定名称,测试不得依赖视觉符号。 +- 验证证据:src/App.test.tsx 通过;npm.cmd run test 为 60/60 通过。 + +## 2026-07-27 — 把“定时截图”误当作“活动理解” + +- 阶段:屏幕感知方案 B 规划复核 +- 类型:功能行为 / API契约 +- 现象:仅有截图上传、HTTP 成功或附件上传成功时,容易误称 Bot 已经理解用户当前活动;GDI `PrintWindow` 对硬件加速游戏还可能产出黑帧。 +- 根因:没有将范围授权、帧质量、最小上下文、视觉模型能力、场景去重和主动回应拆成独立可验证的门。 +- 修复或规避:新增 `docs/reports/screen-awareness-understanding-framework-2026-07-27.md`,把 WGC Spike 和真实 AstrBot 视觉验收设为全桌面/游戏功能的前置停止条件。 +- 预防规则:后续不得以请求成功、上传成功或单张图片测试替代“模型看图并理解”的真实验收;任何自动观察先通过本地策略与质量门。 +- 验证证据:框架定义 S0-S5 阶段、附件段契约、Companion-only 约束、黑帧拒绝和真实服务端视觉验收。 + +## 2026-07-27 — 懒加载页面的启动集成测试不能依赖默认五秒 + +- 阶段:C1 陪伴入口页面壳提交前验证 +- 类型:测试 / 功能行为 +- 现象:新增独立懒加载页面后,既有的“Rust 启动状态”集成测试在受限 Windows 环境中稳定略过 Vitest 默认五秒;它点击诊断页后也没有等待目标页面就绪。 +- 根因:测试把页面切换、懒加载和异步 bootstrap IPC 都压在默认预算内,并以未等待的导航操作开始后续断言。 +- 修复或规避:诊断页 helper 改为等待目标标题,调用方显式等待;仅该启动集成测试预算设为十秒,不调整全局测试配置或产品代码。 +- 预防规则:涉及懒加载页面切换的集成测试必须等待可见的页面就绪信号;单条跨异步边界测试应声明与其真实链路匹配的局部预算。 +- 验证证据:修复后运行完整 Vitest、ESLint、TypeScript 和生产 Web 构建;产品逻辑无改动。 diff --git a/src/App.test.tsx b/src/App.test.tsx index 25e3b61..0a9d2fe 100644 --- a/src/App.test.tsx +++ b/src/App.test.tsx @@ -47,12 +47,13 @@ const emptyPolicy: ConnectionPolicyStatus = { }; async function openConnectionsPage() { - fireEvent.click(screen.getByRole("button", { name: /◎连接/ })); + fireEvent.click(screen.getByRole("button", { name: /连接/ })); await screen.findByRole("heading", { level: 2 }, { timeout: 5000 }); } -function openDiagnosticsPage() { - fireEvent.click(screen.getByRole("button", { name: /⚙诊断与设置/ })); +async function openDiagnosticsPage() { + fireEvent.click(screen.getByRole("button", { name: /诊断与设置/ })); + await screen.findByRole("heading", { name: "诊断与设置" }); } function mockBaseCommands(options?: { @@ -138,12 +139,12 @@ describe("App", () => { it("renders the verified Rust bootstrap status", async () => { render(); - openDiagnosticsPage(); + await openDiagnosticsPage(); expect(await screen.findByText("ready")).toBeInTheDocument(); expect(screen.getByText("desktop-v1alpha1")).toBeInTheDocument(); await openConnectionsPage(); expect(screen.getByText("连接 Profile")).toBeInTheDocument(); - }); + }, 10_000); it("rejects an invalid Rust IPC payload", async () => { vi.mocked(invoke).mockImplementation(async (command) => { @@ -497,4 +498,28 @@ describe("App", () => { screen.getByText(/运维任务进行中,已锁定运维槽位切换(\s*1 个活动任务)/), ).toBeInTheDocument(); }); + + it("separates voice chat and game companion into distinct accessible pages", async () => { + render(); + + fireEvent.click(screen.getByRole("button", { name: /语音聊天/ })); + expect( + await screen.findByRole("heading", { name: "把说话和文字会话分开" }), + ).toBeInTheDocument(); + expect(screen.getByText("默认陪伴槽位")).toBeInTheDocument(); + expect( + screen.getByRole("button", { name: "语音会话准备中" }), + ).toBeDisabled(); + + fireEvent.click(screen.getByRole("button", { name: /游戏陪玩/ })); + expect( + await screen.findByRole("heading", { name: "游戏陪玩需要可信的画面" }), + ).toBeInTheDocument(); + expect( + screen.getByText("等待 Windows.Graphics.Capture 验证"), + ).toBeInTheDocument(); + expect( + screen.getByRole("button", { name: "等待捕获能力验证" }), + ).toBeDisabled(); + }); }); diff --git a/src/App.tsx b/src/App.tsx index f94f10b..60bf70f 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -44,12 +44,23 @@ const DiagnosticsPage = lazy(() => default: DiagnosticsPage, })), ); +const VoiceChatPage = lazy(() => + import("./pages/CompanionPages").then(({ VoiceChatPage }) => ({ + default: VoiceChatPage, + })), +); +const GameCompanionPage = lazy(() => + import("./pages/CompanionPages").then(({ GameCompanionPage }) => ({ + default: GameCompanionPage, + })), +); import { bootstrapStatusSchema, type BootstrapStatus } from "./types/bootstrap"; /// Shared with `ChatPanel`, which portals its slot tabs into this element. export const WINDOW_CHROME_MOUNT_ID = "window-chrome-mount"; -type PageKey = "chat" | "connections" | "desktop" | "pet" | "diagnostics"; +type PageKey = + "chat" | "voice" | "game" | "connections" | "desktop" | "pet" | "diagnostics"; type ChatSlot = "companion" | "operations"; type PetDisplayMode = "app-ui" | "desktop-floating"; type ThemeMode = "dark" | "light"; @@ -64,7 +75,9 @@ const initialStatus: BootstrapStatus = { const navigation: Array<{ key: PageKey; label: string; description: string }> = [ - { key: "chat", label: "聊天", description: "陪伴与运维对话" }, + { key: "chat", label: "聊天", description: "文字与附件会话" }, + { key: "voice", label: "语音聊天", description: "录音、转写与语音回复" }, + { key: "game", label: "游戏陪玩", description: "授权画面与陪伴状态" }, { key: "connections", label: "连接", description: "实例与槽位管理" }, { key: "desktop", label: "桌面行为", description: "快速聊天与状态气泡" }, { key: "pet", label: "桌宠", description: "形象与活动范围" }, @@ -190,7 +203,9 @@ export function App() { className={page === item.key ? "nav-item active" : "nav-item"} onClick={() => setPage(item.key)} > - {navIcon(item.key)} + {item.label} {item.description} @@ -218,6 +233,8 @@ export function App() { ) : null} }> {page === "chat" ? : null} + {page === "voice" ? : null} + {page === "game" ? : null} {page === "connections" ? : null} {page === "desktop" ? ( +
+
+ Companion voice +

把说话和文字会话分开

+

+ 语音录制、服务端转写和语音回复会集中在这里;它们仍然使用陪伴槽位的同一会话、连接和消息记录。 +

+
+
+ +
+ 准备接入语音会话 + 下一阶段连接现有录音与播放状态 +
+
+
+ +
+
+ Target + 默认陪伴槽位 +

+ 运维槽位只能在语音页面中显式选择,不会被文字聊天的当前选择悄悄改变。 +

+
+
+ Flow + 录音 → 上传 → 转写 +

+ 客户端不会保存 STT 凭据;服务端语音 provider 由你在 AstrBot 中配置。 +

+
+
+ Playback + 回复留在原会话 +

语音消息与文字时间线共用同一消息库,不创建第二份聊天历史。

+
+
+ +
+
+ C2 +

下一步:接入现有录音状态

+

+ 录音权限、上传进度、服务端转写和可播放回复会在完成接入后显示在此处。 +

+
+ +
+ + ); +} + +export function GameCompanionPage() { + return ( +
+
+
+ Companion play +

游戏陪玩需要可信的画面

+

+ 这里会展示授权范围、观察状态和陪伴回应。当前不会把 GDI + 的黑图当作游戏画面发送给 AstrBot。 +

+
+
+ +
+ 等待 Windows.Graphics.Capture 验证 + 硬件加速游戏窗口尚未具备可用捕获路径 +
+
+
+ +
+
+ Scope + 仅陪伴槽位 +

画面感知不会自动发送给运维槽位,也不会为游戏开启任何输入控制。

+
+
+ Consent + 范围必须由你选择 +

方案 B 会要求明确选择单显示器或全部显示器;随机只影响触发时机。

+
+
+ Guardrail + 看不到就明确说明 +

最小化、锁屏、受保护内容或黑帧都会安全降级,不伪造“正在观察”。

+
+
+ +
+
+ C4 · WGC Spike +

先验证,再开启陪玩

+

+ 需验证全桌面、游戏窗口、锁屏和受保护内容的捕获行为,以及资源预算和可撤销授权。 +

+
+ +
+
+ ); +} diff --git a/src/styles.css b/src/styles.css index 35cd8bf..6a88508 100644 --- a/src/styles.css +++ b/src/styles.css @@ -3600,3 +3600,145 @@ button:disabled { opacity: 0.35; } } + +/* Dedicated companion surfaces share the shell vocabulary while keeping voice + and game states separate from the text-chat composer. */ +.companion-page { + display: grid; + width: min(100%, 72rem); + gap: 1rem; + margin: 0 auto; +} + +.companion-hero, +.companion-overview-card, +.companion-next-step { + border: 1px solid var(--ui-line, rgb(137 175 232 / 28%)); + border-radius: 1rem; + background: var(--ui-surface, rgb(13 29 52 / 78%)); + box-shadow: 0 1rem 3rem rgb(0 0 0 / 14%); +} + +.companion-hero { + display: grid; + grid-template-columns: minmax(0, 1fr) minmax(16rem, 0.75fr); + gap: 1.5rem; + align-items: center; + padding: clamp(1.2rem, 3vw, 2rem); +} + +.companion-hero h2, +.companion-next-step h3, +.companion-overview-card strong { + color: var(--ui-ink, #f6f9ff); +} + +.companion-hero h2, +.companion-next-step h3 { + margin: 0.35rem 0 0.55rem; +} + +.companion-hero p, +.companion-overview-card p, +.companion-next-step p { + margin: 0; + color: var(--ui-muted, #aebfda); + line-height: 1.55; +} + +.companion-state { + display: flex; + gap: 0.7rem; + align-items: center; + padding: 0.9rem 1rem; + border: 1px solid rgb(96 211 153 / 36%); + border-radius: 0.8rem; + background: rgb(35 102 79 / 18%); +} + +.companion-state-warning { + border-color: rgb(255 189 103 / 48%); + background: rgb(112 73 25 / 18%); +} + +.companion-state-dot { + width: 0.62rem; + height: 0.62rem; + flex: 0 0 auto; + border-radius: 50%; + background: #60d399; + box-shadow: 0 0 0.7rem rgb(96 211 153 / 72%); +} + +.companion-state-warning .companion-state-dot { + background: #ffbd67; + box-shadow: 0 0 0.7rem rgb(255 189 103 / 72%); +} + +.companion-state strong, +.companion-state small { + display: block; +} + +.companion-state strong { + color: var(--ui-ink, #f6f9ff); + font-size: 0.9rem; +} + +.companion-state small { + margin-top: 0.18rem; + color: var(--ui-muted, #aebfda); + font-size: 0.78rem; + line-height: 1.4; +} + +.companion-overview { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 1rem; +} + +.companion-overview-card { + display: grid; + gap: 0.55rem; + min-height: 11.5rem; + padding: 1.1rem; +} + +.companion-overview-card strong { + font-size: 1rem; +} + +.companion-next-step { + display: flex; + justify-content: space-between; + gap: 1.25rem; + align-items: center; + padding: 1.15rem 1.25rem; +} + +.companion-next-step button { + flex: 0 0 auto; +} + +@media (max-width: 860px) { + .companion-hero, + .companion-overview { + grid-template-columns: 1fr; + } + + .companion-overview-card { + min-height: auto; + } +} + +@media (max-width: 580px) { + .companion-next-step { + align-items: stretch; + flex-direction: column; + } + + .companion-next-step button { + width: 100%; + } +}