AstrBot-Desktop/docs/reports/screen-awareness-understanding-framework-2026-07-27.md

191 行
15 KiB
Markdown

# 屏幕感知理解框架(方案 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_window`(指定窗口):用户通过原生窗口选择器选择一个可见顶层窗口,或选择“授权当前前台窗口”。授权令牌绑定窗口句柄、进程身份和有效期;窗口关闭、最小化、进程变化或句柄复用即停止,不自动跟随新的前台窗口。
- `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/错题本同步且工作区干净后,才可将“看一看”标记为可用功能。