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