AstrBot-Desktop/docs/reports/screen-awareness-understanding-framework-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

14 KiB

屏幕感知理解框架(方案 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. 端到端理解链路

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/错题本同步且工作区干净后,才可将“看一看”标记为可用功能。