docs: add desktop dialog guard design

2026-05-09 20:49:52 +08:00
parent 2c719168b6
commit 0757d07521
1 changed files with 245 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-09-desktop-dialog-guard-design.md
+++ b/docs/superpowers/specs/2026-05-09-desktop-dialog-guard-design.md
@@ -0,0 +1,245 @@
+# Desktop Dialog Guard 跨平台弹窗治理设计
+
+## 背景
+
+Boss 当前已经具备 `desktop_control` 任务链路，本地设备端通过 `local-agent/computer-use-task-runner.mjs` 调用 `scripts/computer-use-smoke.mjs` 完成桌面控制 smoke 执行。现状的问题是：桌面自动化在遇到系统级弹窗、应用首次启动弹窗、权限申请、账号/隐私确认时，没有统一处理层，容易中断任务，或者需要临时针对 Chrome、QQ、系统设置等单个应用补丁化处理。
+
+本设计目标是新增一个通用 `Desktop Dialog Guard`，作为所有桌面控制任务的前置和运行中治理层，分别支持 macOS 与 Windows，不把能力写死到某一个应用。
+
+## 目标
+
+1. 让 Boss APP 控制电脑时，常见系统/应用弹窗可以被稳定识别、分级和处理。
+2. 支持 macOS 与 Windows 两套平台适配器，统一上层策略、审计和 APP 确认交互。
+3. 安全弹窗可以自动处理，未知或高风险弹窗必须暂停任务并请求用户确认。
+4. 所有处理过程可追踪，避免自动化黑箱乱点。
+5. 作为通用能力服务于主 Agent 托管、用户直接桌面控制、Codex GUI/CLI 辅助操作、浏览器自动化等链路。
+
+## 非目标
+
+1. 不绕过系统安全模型，不静默授予屏幕录制、辅助功能、输入监控、完整磁盘访问、钥匙串、管理员密码、Apple ID、Windows UAC 等敏感权限。
+2. 不默认用坐标点击作为主方案。坐标只能作为控件树和 OCR 都失败后的受控 fallback。
+3. 不把弹窗策略写死在主 Agent 提示词里。
+4. 不做全局永久放行。长期放行必须绑定设备、平台、应用、弹窗签名和动作范围。
+
+## 推荐方案
+
+采用“平台适配器 + 策略引擎 + APP 人工确认”的组合方案。
+
+备选方案一是继续在各应用控制脚本里写特例，成本低但不可维护，遇到新应用会重复踩坑。备选方案二是完全依赖大模型看图判断弹窗，通用性强但延迟高、成本高、审计难。推荐方案把可预测弹窗交给本地规则，把未知和高风险弹窗交给用户确认，必要时再让模型参与摘要，不让模型直接决定敏感点击。
+
+## 总体架构
+
+新增模块分为五层：
+
+1. `DialogGuardOrchestrator`：桌面任务统一入口，负责 preflight、执行中 watch、超时和任务恢复。
+2. `DialogPolicyEngine`：读取规则表，基于平台、应用、窗口标题、弹窗文本、按钮、风险级别匹配处理策略。
+3. `MacDialogAdapter`：基于 macOS Accessibility/AX 获取窗口、控件、按钮和文本，必要时结合截图 OCR。
+4. `WindowsDialogAdapter`：基于 Windows UI Automation 获取窗口、控件、按钮和文本，必要时结合截图 OCR。
+5. `DialogConsentGateway`：将未知或高风险弹窗推送到 Boss 服务端，再由 APP 展示确认卡片。
+
+数据流：
+
+1. Boss 服务端下发 `desktop_control` 任务。
+2. `local-agent/computer-use-task-runner.mjs` 构造 runtime payload。
+3. 桌面 runtime 启动 `DialogGuardOrchestrator`。
+4. 执行前先跑权限和弹窗 preflight。
+5. 执行过程中 watcher 周期性采集当前前台窗口和系统弹窗。
+6. 命中安全策略则自动点击或关闭，并写审计。
+7. 命中未知或敏感策略则暂停任务，返回 `needs_user_action`，Boss APP 显示确认卡片。
+8. 用户确认后，任务按同一 request/session 继续执行。
+
+## 策略模型
+
+新增 `dialog-policies` 配置，规则结构如下：
+
+```json
+{
+  "id": "common-dismiss-welcome",
+  "platforms": ["darwin", "win32"],
+  "appPatterns": ["*"],
+  "titlePatterns": ["欢迎", "Welcome", "提示", "Notice"],
+  "textPatterns": ["稍后", "跳过", "以后再说", "Not now", "Skip"],
+  "buttonPatterns": ["稍后", "跳过", "以后再说", "Not now", "Skip"],
+  "risk": "safe",
+  "action": "click_button",
+  "scope": "device_app_dialog",
+  "auditRequired": true
+}
+```
+
+动作类型：
+
+1. `click_button`：点击指定按钮。
+2. `dismiss`：关闭弹窗。
+3. `pause_for_user`：暂停任务，请求 APP 确认。
+4. `deny`：默认拒绝，例如通知权限或非必要追踪权限。
+5. `ignore`：不处理，只记录。
+
+风险级别：
+
+1. `safe`：普通欢迎、更新、稍后提醒、非必要通知。
+2. `medium`：账号登录、浏览器默认设置、下载打开、跨应用自动化授权。
+3. `sensitive`：隐私、付款、删除、发送外部消息、权限授权。
+4. `blocked`：系统明确禁止或必须人工授权的安全权限。
+
+## 弹窗签名
+
+每个弹窗生成稳定签名，避免误放行：
+
+```json
+{
+  "platform": "darwin",
+  "deviceId": "mac-studio",
+  "appBundleId": "com.google.Chrome",
+  "windowTitleHash": "sha256:title",
+  "textHash": "sha256:normalized-text",
+  "buttonHash": "sha256:buttons",
+  "risk": "medium"
+}
+```
+
+用户选择“本次允许”只作用于当前 task/session。用户选择“对此设备和此类弹窗允许”只作用于同一设备、同一应用、同一弹窗签名和同一动作，不提升到全局。
+
+## macOS 版本
+
+macOS 适配器优先使用 Accessibility/AX：
+
+1. 获取前台应用、窗口、sheet、alert、popover。
+2. 读取 `AXTitle`、`AXDescription`、`AXValue`、按钮列表和可点击控件。
+3. 通过 AX element reference 点击按钮，避免坐标漂移。
+4. 当 AX 不可读时，使用截图 OCR 识别文本，再进入人工确认或受控坐标 fallback。
+
+macOS 权限策略：
+
+1. Accessibility 缺失：不能自动操作，返回 `needs_permission`。
+2. Screen Recording 缺失：可以继续文本控件树任务，但不能做视觉判断，提示用户授权。
+3. Input Monitoring 缺失：影响全局键盘输入，提示用户授权。
+4. Automation consent 弹窗：如果 helper 已具备 Accessibility 且用户预先允许当前设备策略，可点击；否则请求用户确认。
+5. Keychain、管理员密码、Apple ID、系统隐私授权：永远不自动输入或绕过。
+
+## Windows 版本
+
+Windows 适配器优先使用 UI Automation：
+
+1. 通过 UIA 获取前台窗口、子窗口、Dialog、Button、Text、Edit 控件。
+2. 使用 AutomationId、Name、ControlType 和 BoundingRectangle 建立控件引用。
+3. 优先调用 InvokePattern 点击按钮，不直接鼠标坐标点击。
+4. UIA 不可读时，使用截图 OCR 识别并进入人工确认。
+
+Windows 权限策略：
+
+1. UAC 安全桌面不可被普通进程可靠控制，必须提示用户本机确认。
+2. Windows Defender、SmartScreen、安装器高危提示默认 `pause_for_user`。
+3. 浏览器欢迎页、默认浏览器、通知权限、更新提示可按策略自动处理。
+4. 管理员密码、系统账号、企业安全策略相关弹窗永远不自动输入或绕过。
+
+## Boss APP 交互
+
+当弹窗需要用户处理时，服务端向 APP 推送一张确认卡片：
+
+1. 标题：`电脑弹窗需要确认`
+2. 内容：应用名、设备名、弹窗摘要、推荐动作、风险级别。
+3. 按钮：`允许本次`、`对此设备和此弹窗类型允许`、`拒绝`。
+4. 敏感弹窗只显示 `我已在电脑上处理` 和 `取消任务`，不提供远程自动允许。
+
+APP 不显示内部字段、控件树、权限原文长日志，只展示和用户决策直接相关的信息。
+
+## 服务端与本地 agent 接口
+
+`desktop_control` runtime 输出新增状态：
+
+```json
+{
+  "status": "needs_user_action",
+  "requestId": "task-id",
+  "kind": "dialog_intervention_required",
+  "dialogId": "dialog-signature-id",
+  "risk": "medium",
+  "summary": "Chrome 请求成为默认浏览器",
+  "recommendedAction": "dismiss",
+  "availableActions": ["allow_once", "allow_for_device_dialog", "deny"]
+}
+```
+
+用户确认后，Boss 服务端向 local-agent 下发：
+
+```json
+{
+  "requestId": "task-id",
+  "dialogId": "dialog-signature-id",
+  "decision": "allow_once"
+}
+```
+
+local-agent 根据原始 request/session 恢复执行，避免重新发起任务导致重复操作。
+
+## 审计与安全
+
+每次处理记录：
+
+1. 设备、平台、应用、窗口摘要。
+2. 弹窗签名和风险级别。
+3. 命中的策略 ID。
+4. 实际执行动作。
+5. 用户确认人和确认范围。
+6. 时间戳和任务 ID。
+7. 可选截图路径或 OCR 摘要。
+
+审计日志需要进入现有 Boss 风险/权限日志体系，供企业管理员查看。
+
+## 测试策略
+
+单元测试：
+
+1. 策略匹配优先级。
+2. 弹窗签名稳定性。
+3. 风险分级和禁止自动越权规则。
+4. `needs_user_action` 输出结构。
+5. 用户确认 scope 不能越权到全局。
+
+平台 fixture 测试：
+
+1. macOS AX snapshot fixture。
+2. Windows UIA snapshot fixture。
+3. OCR fallback fixture。
+4. 未知弹窗 fixture。
+
+真机回归：
+
+1. macOS：Chrome 首启、QQ/浏览器普通弹窗、系统权限缺失检测、Automation consent。
+2. Windows：浏览器首启、通知权限、安装器提示、UAC 检测。
+3. Boss APP：确认卡片展示、允许本次、拒绝、设备级弹窗规则生效。
+4. 主 Agent 托管：遇到弹窗暂停，不丢任务；用户确认后继续。
+
+## 分阶段实现
+
+第一阶段：
+
+1. 新增通用策略模型和策略匹配测试。
+2. 新增 runtime 结果类型 `needs_user_action`。
+3. macOS 适配器接入现有 helper/AX 能力。
+4. APP 展示基础确认卡片。
+
+第二阶段：
+
+1. Windows UI Automation helper。
+2. Windows fixture 和本机回归。
+3. 设备级弹窗策略持久化。
+4. 审计日志进入后台风险视图。
+
+第三阶段：
+
+1. OCR fallback。
+2. 弹窗处理效果统计。
+3. 企业部署策略模板。
+4. MDM/PPPC 预配置指引，用于企业批量授权 macOS 权限。
+
+## 验收标准
+
+1. Chrome 只是普通测试样例，不是专用实现。
+2. macOS 和 Windows 都有独立 adapter，统一上层接口。
+3. 安全弹窗能自动处理，敏感弹窗不能自动越权。
+4. Boss APP 能收到弹窗确认卡片并恢复任务。
+5. 主 Agent 托管和用户直接控制都复用同一套弹窗治理。
+6. 所有自动处理都有审计记录。
+7. 权限不足时给出明确原因和用户下一步动作。