AstrBot-Desktop/docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md
YokiiroBW 350c6fd3ad
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(companion): add dedicated voice and game surfaces
2026-07-27 13:46:42 +08:00

18 KiB

陪伴体验页面拆分与定时屏幕感知规划(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/。