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 知道用户在做什么”应是一次受限观察形成的活动上下文,而非把原始桌面持续上传:
- 用户明确授权固定捕获范围;
- 客户端只在合格的随机时机采集一帧;
- 本地过滤锁屏、受保护内容、敏感应用、黑帧和重复场景;
- 将视觉帧与最小、脱敏的上下文信封作为同一条多模态消息送到 Companion;
- AstrBot 必须使用已经实证可看图的模型;
- 仅在新场景且未处于冷却期时,Bot 才作低打扰回应;
- 用户始终能看到状态、原因、最后结果并一键停止。
非目标
- 不做隐藏采集、浏览器历史读取、输入记录、鼠标键盘控制、进程注入、游戏内存读取或录屏。
- 不随机选择未授权目标;“随机”只表示触发时间。
- 不向 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 再次检查,任一失败即中止且产生脱敏结果码:
- 总开关、范围授权、Companion 连接和活动时段有效;
- 当前 Windows 会话未锁屏,捕获目标仍存在且范围未变化;
- 命中敏感应用规则、受保护内容或系统安全桌面时拒绝;规则初版采用保守拒绝,命中后只提示用户而不上传;
- 图像尺寸/编码/文件大小在预算内,且通过黑帧、透明帧、空白帧检测;
- 场景指纹与上一次成功观察不高度相似,或用户选择“即使相同也允许”。初版只保存不可逆的短期感知指纹,不保存图片;
- 回复冷却、用户主动聊天静默期和最近发送间隔均已到期。
敏感规则的设计必须可解释:设置页显示“因敏感应用规则未发送”,但默认不展示被拒绝窗口的标题或 OCR 文本。用户可在本地查看规则类别、编辑允许/拒绝策略并随时停用自动观察。
3.3 上下文信封:图片之外给模型必要而非过量的信息
每次合格观察构造一条短生命周期消息:
- 图片附件:唯一必需的视觉证据;沿用已验证的
message内图片附件段,不再使用顶层attachments。 - 固定意图:这是经用户授权的一次桌面观察。请判断可见的高层活动;不要猜测不可见内容、凭据或私人信息;若没有帮助价值可不主动回应。
- 脱敏元数据:观察原因(手动/间隔到期且概率命中)、范围类型、是否游戏会话、用户选择的互动风格。
- 可选窗口线索:仅在用户开启“增强文字上下文”后,从前台窗口获取经过本地脱敏和长度上限处理的应用类别/UIA 摘要;禁用时绝不读取或上传此类文本。
禁止把完整窗口标题、窗口树、OCR 全文、剪贴板、浏览器 URL/历史等作为默认上下文。图片和可选摘要都属于同一次瞬时请求,发送完成后立即释放内存缓存。
3.4 AstrBot 多模态契约:验证模型真的看到了
“HTTP 200”或附件上传成功不能证明模型看到了图片。上线前必须运行真实服务端验收:
- 选用明确具有视觉能力的 AstrBot 模型配置;普通文本模型时自动观察不可启用,并说明原因;
- 使用一组无敏感信息、内容可判定的测试画面;
- 验证请求的图片附件段在 AstrBot 入站可见;
- 验证模型能回答画面中可验证的高层事实,而非只复述固定提示;
- 记录测试时间、模型配置标识(脱敏)和通过/失败结果,不记录测试图片或完整响应;
- 对失败区分:上传失败、附件形状错误、模型非视觉、模型拒绝、SSE/回复失败。不得把失败标成“已观察”。
3.5 主动互动决策:少而准,不把监视变成打扰
参考插件的总开关、时段、概率、互动风格、主动消息冷却与状态解释模式,客户端采用下列本地决策顺序:
- 活跃时段:不在时段内不采集、不调用模型;
- 硬最短间隔:距离上次完成观察(包括概率未命中后的本轮结束)未到最短间隔,不评估;
- 随机时间:到期后添加有上限的抖动,再执行一次概率抽样;不会高频轮询或重试;
- 概率判定:
0%永不自动触发,100%只在每个合格时间窗最多触发一次;概率未命中进入下一个时间窗; - 本地策略与质量门:任一门拒绝即不上传;
- 场景去重:相似场景默认不请求模型;
- 回应冷却:可发送观察但抑制主动文案,或直接跳过上传,最终策略必须由产品验收确定;
- 用户聊天静默期:用户刚在聊天/语音中主动交流时,不用自动观察插话;
- 互动风格:仅影响允许后的回应语气,不得改变采集范围或安全策略。
建议初始安全默认:最短间隔不低于 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/错题本同步且工作区干净后,才可将“看一看”标记为可用功能。