Files
cbb-refresh-verify-795/docs/superpowers/specs/2026-09-20-adaptive-dialog-supervision-design.md
T
阿白叔 11a2b2e46e Import CBB refresh verify r4 stability baseline
Preserve tested Verify source, authoritative READY checks, bounded bridge retries, diagnostics and failure-only reporting. Include 336-test suite and packaging assets; exclude live Mentor samples, field logs, backups and distributions.
2026-09-29 15:05:20 +08:00

11 KiB
Raw Blame History

CBB 自适应弹窗监督设计

日期: 2026-09-20
状态: 已确认方向,待实施计划

目标

为 CBB 批量 Verify 建立一套可跨 Mentor EE 7.9/7.9.5、不同 Windows 主题、语言和现场机器使用的弹窗监督机制。该机制必须在后台私有桌面运行,不移动用户鼠标、不发送真实键盘输入、不切换前台桌面;已知安全弹窗自动处理,进度弹窗持续观察,致命弹窗立即记录并跳过当前 CBB,完全未知的弹窗保留完整证据后跳过当前 CBB。

本设计扩展 2026-09-20-bridge-execution-and-unc-design.md,不替换其中已经确认的中心库状态桥、PCB COM 执行桥、UNC 路径租约和结果判定规则。

当前问题

现有实现有以下结构性限制:

  • dialog_supervisor.py 只接受窗口类名为 #32770 的标准对话框,无法完整发现 GXWND、TaskDialog 和 Mentor 自绘窗口。
  • 动作主要依赖按钮文案和 BM_CLICK,对于自绘列表、延迟初始化控件以及需要 UI Automation Selection/Invoke 的窗口无效。
  • dialog_supervisor.py 与 mentor_adapter.handle_known_dialogs() 各自维护一套分类和点击逻辑,可能对同一弹窗作出不同决定。
  • 规则缺少明确的执行阶段约束。同名的 OK、Yes 或 Continue 在启动、恢复、保存和错误阶段具有不同含义。
  • 未识别的非标准窗口可能完全不进入证据日志,最终只表现为超时。

设计原则

  1. Mentor/PCB 官方接口优先于界面自动化。
  2. UI Automation 模式优先于 Win32 控件消息。
  3. 不以坐标、颜色、窗口句柄或固定 PID 作为稳定身份。
  4. 不对未知弹窗执行猜测性确认。
  5. 弹窗消失只表示动作已响应,不表示 Verify 成功。
  6. 每个动作必须受执行阶段、窗口指纹和后置条件共同约束。
  7. 新现场弹窗通过数据化规则适配,不在主程序中继续堆叠分支。

总体架构

1. 单一监督入口

保留 DialogSupervisor 作为父进程唯一入口,删除生产流程对 mentor_adapter.handle_known_dialogs() 和 choose_dialog_action() 的调用。兼容函数可以短期保留给旧测试,但不得再参与真实 Verify。

监督入口接收:

  • 当前 Job Object 的进程树;
  • 当前私有桌面句柄;
  • PCB 执行状态机阶段;
  • 当前目标 CBB、PCB 和 PRJ 身份;
  • 默认规则包与可选的现场规则包。

它输出统一的 DialogEvent,不直接决定最终 Verify 结果。

2. 私有桌面观察代理

新增一个随校验 worker 启动、位于同一私有桌面的观察代理。父进程继续负责超时和结果裁决,观察代理负责窗口发现和控件操作,二者通过带 request_id 和单调序号的 JSONL 通道通信。

将观察代理放在私有桌面内部,避免 UI Automation 从输入桌面跨桌面访问时出现元素不可见、COM apartment 不一致或句柄可枚举但 Pattern 不可调用的问题。

观察代理按两层采集窗口:

  • Win32 层:所有可见顶层窗口,不限制 #32770,记录 HWND、PID、进程程序名、窗口类、标题、owner、父子窗口及控件 ID。
  • UI Automation 层:记录 AutomationId、ControlType、Name、IsEnabled,以及 Invoke、SelectionItem、Toggle、Value、Window 等可用 Pattern。

私有桌面本身是隔离边界。代理仍记录进程树归属,但不会因为许可证或设计服务器使用辅助 PID 而漏掉窗口。用户输入桌面的窗口永远不在观察范围内。

3. 规范化窗口模型与动态指纹

所有观察结果先转换为 WindowSnapshot:

  • stage
  • process_name、process_role
  • window_class、title
  • 标准化后的可见文本集合
  • 控件树结构摘要
  • 控件 ID、AutomationId、ControlType 和可用 Pattern
  • enabled、selected、checked、visible 状态

窗口指纹由稳定字段组合得到:

stage + process_role + window_class + normalized semantics + control-shape

动态 HWND、PID、坐标、主题色、控件创建顺序和文本中的路径/耗时数字只写入证据,不进入稳定指纹。中英文同义词经过语义标签归一化,例如 恢复数据库/Restore Database 都映射为 RESTORE_DATABASE。

4. 数据化规则引擎

默认规则以版本化 JSON 文件发布,用户现场规则放在数据目录,两者都只允许声明式匹配和预定义动作,禁止执行任意脚本。规则包括:

  • rule_id、schema_version、适用 Mentor 版本;
  • 允许的执行阶段;
  • 进程角色、窗口类和控件结构条件;
  • 必须存在和必须不存在的语义证据;
  • 动作类型、目标控件条件和后置条件;
  • 重试次数、退避时间和失败分类。

同一窗口可以匹配多个证据,但只有唯一最高优先级规则满足全部条件时才执行。规则冲突返回 DIALOG_RULE_CONFLICT,不得任选一条。

规则分类:

  • OBSERVE_PROGRESS:只观察状态变化,不点击 Cancel,并刷新活动超时。
  • SAFE_RECOVERY:数据库恢复、许可证选择、打开锁确认等可恢复动作。
  • SAFE_CONFIRM:保存 Reusable Block 等与当前阶段一致的确认动作。
  • FATAL_ACK:保存失败、设计服务器失败、Project Integration 错误;允许关闭提示以便清理,但当前项结果锁定为 FAIL。
  • UNKNOWN:不执行动作,保存现场后结束当前项。

5. 分层动作适配器

每条规则声明允许使用的动作通道,按以下顺序尝试:

  1. 已确认的 Mentor/PCB COM 或桥接接口;
  2. UI Automation InvokePattern;
  3. UI Automation SelectionItemPattern、TogglePattern 或 ValuePattern;
  4. 标准 Win32 WM_COMMAND 或 BM_CLICK;
  5. 默认禁用的窗口内相对点击。

窗口消息降级仅能在后续明确验证某个自绘控件没有任何接口、UIA Pattern 或标准控件消息可用时,为单独规则显式开启;当前仅允许 EE7.9.5 许可证选择器规则使用 WM_LBUTTONDOWN/WM_LBUTTONUP 目标句柄消息。它仍不得移动真实鼠标或注入真实键盘。屏幕绝对坐标永远禁用。

动作发出后必须满足规则定义的后置条件,例如:

  • 目标控件变为 selected;
  • OK 从 disabled 变为 enabled;
  • 当前窗口消失;
  • 下一阶段窗口出现;
  • PCB COM/执行桥返回对应状态变化。

未满足后置条件时不记录为已处理,而是在有限次数内重试;达到上限返回 DIALOG_ACTION_STUCK。

6. 阶段状态机

父进程维护以下阶段:

  1. PCB_STARTING
  2. LICENSE_ACQUISITION
  3. DATABASE_RECOVERY
  4. DOCUMENT_ATTACH
  5. IDENTITY_CHECK
  6. PROJECT_INTEGRATION
  7. VALIDATE
  8. SAVE
  9. CLOSE
  10. POST_VERIFY_STATUS

阶段由 PCB 执行桥事件推进,不能仅靠窗口标题推进。规则只在声明的阶段生效。例如恢复选择只能出现在启动或文档附加前,保存确认只能出现在 SAVE/CLOSE,Project Integration 进度窗口只能在 PROJECT_INTEGRATION 被当作正常活动。

阶段不匹配的已知弹窗按 DIALOG_OUT_OF_PHASE 留证并失败,防止残留窗口被误确认。

7. 未知弹窗证据包

发现未知、冲突、阶段错误或无法操作的窗口时,当前项立即生成结构化证据:

  • window_snapshot.json
  • uia_tree.json
  • dialogs.jsonl
  • events.jsonl
  • process_tree.json
  • 当前阶段、目标 CBB/PCB/PRJ 和已匹配规则候选
  • 仅截取私有桌面中该窗口的诊断截图(如果系统允许)

截图只为未知窗口诊断生成,不参与自动判定,也不批量截取正常流程。证据写入采用追加和原子落盘;证据失败不能遮蔽原始错误码。

现场确认该窗口的安全动作后,可新增一条现场 JSON 规则。规则先在 observe_only 模式验证指纹命中和目标唯一性,再允许执行动作。程序不根据一次人工选择自动学习,避免错误行为被永久固化。

8. 超时与恢复

沿用父进程唯一的动态 inactivity deadline:

  • 新窗口、控件状态变化、桥阶段变化和动作后置条件满足都属于活动;
  • 重复的相同窗口快照和重复投递动作不刷新超时;
  • 未知弹窗无需等待 30 秒,证据保存完成后立即结束当前项;
  • 正常 Project Integration 状态持续变化时不会误触发超时;
  • 总时长上限仍然存在,避免异常窗口不断变化导致永不结束。

当前项结束时通过 Job Object 回收观察代理、PCB、执行桥和辅助进程。清理失败写入 cleanup_error,但不阻塞队列中的下一项。

已知弹窗首批规则

第一版至少覆盖:

  • EE7.9/7.9.5 产品许可证选择;
  • Database Restoration 与 Last User Saved Database;
  • 设计正在被其他用户打开时的读写确认;
  • Reusable Block 保存确认;
  • Project Integration 正常进度窗口;
  • Project Integration 错误汇总;
  • Error saving the Reusable Block;
  • Could not run server / Could not bring it alive;
  • Database load is being terminated;
  • Tip of the Day。

许可证规则优先尝试 Automation Licensing COM。只有 COM 取 token 不可用且 UIA 能确认唯一许可证项、选中状态和 OK 可用状态时,才走 UIA 界面通道。

最终结果判定

弹窗监督器只能产生过程事件或失败锁,不能单独产生 PASS。Verify PASS 仍必须满足既有五项条件:

  1. PCB/PRJ 身份一致;
  2. 四项 Project Integration 均为 InSynch;
  3. Validate、Save、IsSaved 和 Close 成功;
  4. 本次没有 fatal、unknown、规则冲突或阶段错误;
  5. PCB 退出后状态桥返回该 CBB 为 READY。

测试策略

单元与契约测试

  • 标准 #32770、TaskDialog、GXWND 和无子控件窗口均能进入 WindowSnapshot。
  • 中英文、动态路径和耗时数字归一化后得到稳定指纹。
  • 规则优先级、冲突、阶段限制和必须不存在条件正确。
  • UIA Pattern、Win32 消息和接口通道按顺序降级。
  • 动作已发送但窗口未变化时不会判定成功。
  • 未知窗口立即输出完整证据,不执行任何按钮。
  • 两套旧弹窗处理入口不再被生产代码调用。

故障注入测试

  • 窗口延迟初始化、控件延迟 enabled、句柄复用、窗口瞬间消失。
  • 辅助进程创建弹窗、进程 PID 变化、UIA 调用超时。
  • 恢复窗口文案变化、中文/英文版本切换、按钮顺序变化。
  • 正常 Project Integration 长时间运行但状态持续变化。
  • 证据目录不可写、规则 JSON 损坏、现场规则与默认规则冲突。

本机真实验收

  1. 先对一个可恢复副本上的单个 CBB 运行,不进行批量。
  2. 分别验证许可证、文件恢复、Project Integration、保存和关闭路径。
  3. 人为保留一个未知测试弹窗,确认它不会被点击且证据完整。
  4. 确认全程不切换前台、不移动鼠标、不注入键盘。
  5. 确认最终状态桥由 PENDING 变为 READY。
  6. 再用三个条目测试“成功、业务错误、缺文件”各自隔离。
  7. 最后才使用冻结包执行小批量回归。

明确不做

  • 不自动点击完全未知弹窗的默认按钮。
  • 不使用真实键盘、鼠标、前台焦点或 SwitchDesktop。
  • 不依赖屏幕绝对坐标、颜色或截图 OCR 判断成功。
  • 不把弹窗消失、日志出现成功字样或 Cert 时间戳单独当作 PASS。
  • 不让观察器修改中心库状态;中心库最终状态仍由权威状态桥读取。
  • 不在同一个中心库上并发执行多个写入 Verify。