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.
11 KiB
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 在启动、恢复、保存和错误阶段具有不同含义。
- 未识别的非标准窗口可能完全不进入证据日志,最终只表现为超时。
设计原则
- Mentor/PCB 官方接口优先于界面自动化。
- UI Automation 模式优先于 Win32 控件消息。
- 不以坐标、颜色、窗口句柄或固定 PID 作为稳定身份。
- 不对未知弹窗执行猜测性确认。
- 弹窗消失只表示动作已响应,不表示 Verify 成功。
- 每个动作必须受执行阶段、窗口指纹和后置条件共同约束。
- 新现场弹窗通过数据化规则适配,不在主程序中继续堆叠分支。
总体架构
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:
stageprocess_name、process_rolewindow_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. 分层动作适配器
每条规则声明允许使用的动作通道,按以下顺序尝试:
- 已确认的 Mentor/PCB COM 或桥接接口;
- UI Automation
InvokePattern; - UI Automation
SelectionItemPattern、TogglePattern或ValuePattern; - 标准 Win32
WM_COMMAND或BM_CLICK; - 默认禁用的窗口内相对点击。
窗口消息降级仅能在后续明确验证某个自绘控件没有任何接口、UIA Pattern 或标准控件消息可用时,为单独规则显式开启;当前仅允许 EE7.9.5 许可证选择器规则使用 WM_LBUTTONDOWN/WM_LBUTTONUP 目标句柄消息。它仍不得移动真实鼠标或注入真实键盘。屏幕绝对坐标永远禁用。
动作发出后必须满足规则定义的后置条件,例如:
- 目标控件变为 selected;
- OK 从 disabled 变为 enabled;
- 当前窗口消失;
- 下一阶段窗口出现;
- PCB COM/执行桥返回对应状态变化。
未满足后置条件时不记录为已处理,而是在有限次数内重试;达到上限返回 DIALOG_ACTION_STUCK。
6. 阶段状态机
父进程维护以下阶段:
PCB_STARTINGLICENSE_ACQUISITIONDATABASE_RECOVERYDOCUMENT_ATTACHIDENTITY_CHECKPROJECT_INTEGRATIONVALIDATESAVECLOSEPOST_VERIFY_STATUS
阶段由 PCB 执行桥事件推进,不能仅靠窗口标题推进。规则只在声明的阶段生效。例如恢复选择只能出现在启动或文档附加前,保存确认只能出现在 SAVE/CLOSE,Project Integration 进度窗口只能在 PROJECT_INTEGRATION 被当作正常活动。
阶段不匹配的已知弹窗按 DIALOG_OUT_OF_PHASE 留证并失败,防止残留窗口被误确认。
7. 未知弹窗证据包
发现未知、冲突、阶段错误或无法操作的窗口时,当前项立即生成结构化证据:
window_snapshot.jsonuia_tree.jsondialogs.jsonlevents.jsonlprocess_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 仍必须满足既有五项条件:
- PCB/PRJ 身份一致;
- 四项 Project Integration 均为
InSynch; - Validate、Save、IsSaved 和 Close 成功;
- 本次没有 fatal、unknown、规则冲突或阶段错误;
- PCB 退出后状态桥返回该 CBB 为
READY。
测试策略
单元与契约测试
- 标准
#32770、TaskDialog、GXWND 和无子控件窗口均能进入WindowSnapshot。 - 中英文、动态路径和耗时数字归一化后得到稳定指纹。
- 规则优先级、冲突、阶段限制和必须不存在条件正确。
- UIA Pattern、Win32 消息和接口通道按顺序降级。
- 动作已发送但窗口未变化时不会判定成功。
- 未知窗口立即输出完整证据,不执行任何按钮。
- 两套旧弹窗处理入口不再被生产代码调用。
故障注入测试
- 窗口延迟初始化、控件延迟 enabled、句柄复用、窗口瞬间消失。
- 辅助进程创建弹窗、进程 PID 变化、UIA 调用超时。
- 恢复窗口文案变化、中文/英文版本切换、按钮顺序变化。
- 正常 Project Integration 长时间运行但状态持续变化。
- 证据目录不可写、规则 JSON 损坏、现场规则与默认规则冲突。
本机真实验收
- 先对一个可恢复副本上的单个 CBB 运行,不进行批量。
- 分别验证许可证、文件恢复、Project Integration、保存和关闭路径。
- 人为保留一个未知测试弹窗,确认它不会被点击且证据完整。
- 确认全程不切换前台、不移动鼠标、不注入键盘。
- 确认最终状态桥由
PENDING变为READY。 - 再用三个条目测试“成功、业务错误、缺文件”各自隔离。
- 最后才使用冻结包执行小批量回归。
明确不做
- 不自动点击完全未知弹窗的默认按钮。
- 不使用真实键盘、鼠标、前台焦点或
SwitchDesktop。 - 不依赖屏幕绝对坐标、颜色或截图 OCR 判断成功。
- 不把弹窗消失、日志出现成功字样或 Cert 时间戳单独当作 PASS。
- 不让观察器修改中心库状态;中心库最终状态仍由权威状态桥读取。
- 不在同一个中心库上并发执行多个写入 Verify。