docs: CBB Verify 全量扫描与阻塞分析(关联 #4) #5

Merged
abaishu0730 merged 1 commits from docs/scan-20261104-blockers into main 2026-11-06 10:20:24 +08:00
@@ -0,0 +1,366 @@
# CBB 中心库上传后校验工具(cbb-refresh-verify-795)全面扫描与阻塞分析
- **扫描对象**:`https://git.simgreek.com/Skyworth_Digital_Hardware/cbb-refresh-verify-795`
- **默认分支**:`main` @ `39985f7`(`chore: release v0.2.3-beta.1`,2026-10-29)
- **活跃分支**:`codex/temp-issue-2-icdb-recovery` @ `29959e2`(2026-11-04 14:16,领先 `main` **49 个提交 / +13,173 行**,未合并、未发布)
- **标签**:`r4-stability-20260929`、`v0.2.2-beta.1`、`v0.2.3-beta.1`
- **扫描时间**:2026-11-04
- **扫描方式**:全量克隆 + 逐模块源码阅读(38 个源文件 / 8,180 行)+ 两个分支完整 pytest + 32 位桥 PE 导入表解析与实机启动 + 关键判定函数行为探针 + 与 `docs/` 现场记录交叉核对
---
> 关联工单:<https://git.simgreek.com/Skyworth_Digital_Hardware/cbb-refresh-verify-795/issues/4>
>
> 扫描基准:`main@39985f7`(v0.2.3-beta.1)、`codex/temp-issue-2-icdb-recovery@29959e2`。
> 本文是扫描时的静态与实测记录;修复进展以工单和后续 PR 为准。
## 0. 一页结论
1. **单机、Win11、有 32 位状态桥、CBB 无异常** 的条件下,`v0.2.3-beta.1` 的"ReusableCircuit PCB → Project Integration → Save/Close → `IsVerifiedReuseBlock` READY"链路是成立的(发布说明有隔离实机 PASS 记录),工具没有伪造绿色状态,失败即阻塞的设计方向正确。
2. **批量场景是这个工具真正的短板**:状态判定依赖外部 32 位桥,但**桥的 x86 VC++/MFC 运行时不随包提供**(本机实测 `0xC0000135` 无法启动);没有桥时工具仍会对每个 CBB 做完整刷新再判 FAIL;叠加"未知弹窗即停批""残留 `sAddress.adr` 即阻断""本机任何 PCB 打开即拒跑",批量任务在现场高概率中途停止。
3. **Win10 是明确的未验收边界**:LM 原生菜单在私有桌面上不派发 MFC 命令(`docs/API-FINDINGS.md`),直接 PCB 路线在 Win10 上是否会提交 Verify 状态没有现场证据。
4. **共享中心库并发没有真正的互斥**:`main` 只有进程内 `Local\` 命名互斥 + 本机进程探测;另一台机器/另一个工程师同时操作同名 CBB 时无任何防护。活跃分支新增了 sidecar 库锁,但它是"合作式"文件锁,Mentor 本身不参与。
5. **ICDB 失联修复尚未闭环**:分支已经做到"原生 Repair → 重开 → 历史版本选择 → 校验 → READY",但文档明确"服务器会话失联经实际按钮触发的完整链路仍需通过",并且出现过"Repair 后 BackAnnotate 被原生拒绝"的失败结论。
6. 代码质量整体高于同类现场工具(分层清晰、证据链完整、失败关闭),但存在若干**可复现的功能缺陷**(内容检查文本误判、`.prj` 编码假设、超时后孤儿 worker、save helper 无超时等),详见第 3 节。
**一句话**:这个工具现在能"证明一个 CBB 是否真的绿",但还不能稳定地"把一批 CBB 刷成绿";阻塞点不在算法,而在**判定链的部署完整性、现场弹窗/占用环境、以及批量的工程化**。
---
## 1. 系统定位与运行链路
### 1.1 定位
| 项 | 内容 |
| --- | --- |
| 处理对象 | 已上传到 Mentor 中心库(`.lmc` + `ReusableBlocksLP`)的 CBB 条目 |
| 核心动作 | 打开该 CBB 的 ReusableCircuit PCB → Project Integration 四项同步 → 保存 Reusable Block cell → 关闭 → 只读读取权威 Verify 状态 |
| 不做什么 | 不做 Part Number 替换、不做上传、不直接改写中心库数据来伪造绿色 |
| 成功判据 | `worker` 完成 + 32 位桥 `IsVerifiedReuseBlock` 返回 `READY / raw=1`,二者缺一即 FAIL |
### 1.2 主链路(`main`)
```
GUI (ui/main_window.py)
└─ run_batch (verify_runner.py) # 串行,max_workers=1
└─ run_verify # 会话级互斥 Local\CbbRefreshVerify795
├─ preflight # Work 下唯一 PRJ / PCBDesignPath / 链接越界
├─ unreleased_addresses # sAddress.adr 残留即 BLOCKED
├─ ReuseBlockImporter -chkContents # 可选:LibSpec + DMS 登录配置
├─ icdb_ports_bindable # 10000-10100 端口预检
├─ DesktopWorker (私有桌面) # 32 位桥/弹窗代理同桌面
│ └─ execute_job (mentor_adapter.py)
│ ├─ 备份(仅本地盘) / CentralLibrary 路径修正
│ ├─ ExpeditionPCB.exe <pcb> -ReusableCircuit
│ ├─ wait_for_target_document (COM 身份核对)
│ ├─ refresh_integration (四项 InSynch)
│ └─ cscript save_verified_block.vbs (Validate/Save/IsSaved/Close/Quit)
├─ cleanup_verify_processes # 只观察退出,不强杀
└─ IsVerifiedReuseBlock (status_bridge.py) → READY / PENDING / UNAVAILABLE
```
对话框监督是一条独立链路:`DesktopWorker` 在私有桌面启动 `--dialog-agent` 伴生进程,agent 用 Win32 + UIA 抓窗口快照,`dialog_supervisor` 按 `assets/dialog_rules.v1.json` 的**阶段化白名单规则**决策,通过 JSONL loopback IPC 回传。
### 1.3 每次校验的产物
`evidence/verify-*/`:`result.json`、`events.jsonl`、`dialogs.jsonl`、`save.log`、`performance.json`、`bridge-status.json`、`diagnostics/`(preflight、native-logs、icdb-recovery)、失败时的 `recovery-required.json`。
### 1.4 现场自述的验证状态(文档)
- `v0.2.3-beta.1`:`pytest` 471 passed;EE7.9.5 隔离实测"破坏 ICDB 文件头 → 备份恢复 → 重新打开 → PASS/GREEN/READY"。
- 明确未验收:Win10、真实网络库大批量、现场 ICDB 失联的自动 Repair 全链路。
- 旧批次 68 项中 51 PASS / 17 FAIL,失败类型已在 `docs/2026-09-29-stability-r4.md` 分类。
---
## 2. 规模与结构
| 指标 | main | temp-issue-2 分支 |
| --- | --- | --- |
| 提交数(相对 main) | — | +49 |
| 源文件 / 行数 | 38 / 8,180 | 47 / 约 13,000+ |
| 测试文件 / 行数 | 35 / 5,752 | 约 50 / 9,000+ |
| 测试用例 | 471 | 1,196 |
| 本机 pytest 结果 | **463 passed / 8 failed** | **1,178 passed / 18 failed** |
| Python / 依赖 | 3.12 + PySide6 6.11 + pywin32 + pywinauto + Pillow | 同 main |
| 打包 | PyInstaller onedir(`CbbRefreshVerify-Background`) | 同 main |
> 本机失败均与环境有关(未完成 `pip install -e .`、无 Mentor 安装、缺 x86 VC 运行时、长路径/编码),不是断言暴露的产品逻辑失败。具体归类见第 7 节。
---
## 3. 功能性问题清单
严重度:**P0** 阻塞交付 / 数据安全风险;**P1** 现场高概率失败或明显功能缺陷;**P2** 可用性、可维护性、规模化问题。
### 3.1 判定链与证据
| 编号 | 严重度 | 问题 | 代码证据 | 影响 |
| --- | --- | --- | --- | --- |
| **F-01** | P0 | **状态桥不可用时仍执行完整刷新,最后才判 FAIL**。批量入口不检查桥是否可用;桥只在 worker 成功后才查询 | `verify_runner.py:981-1000`;UI 读库 `ui/main_window.py:63-68`;`batch_status.authoritative_status_map` 失败只返回 `UNAVAILABLE` | 每个 CBB 白做 2-10 分钟原生刷新 + 一次 Save/Close,然后 `BRIDGE_UNAVAILABLE`;3000 项批量等于 3000 次无效写库 |
| **F-02** | P0 | **32 位状态桥依赖 x86 `mfc140/MSVCP140/VCRUNTIME140`,打包清单只带 exe、未声明或检测该运行时**。本机 SysWOW64 无 x86 运行时,桥启动即 `0xC0000135`(发布 ZIP 不在仓库中,需在发布包上复核是否另行分发) | `packaging/CbbRefreshVerify.spec:4-14` 仅 `binaries=[CbbStatusBridge32.exe]`;PE 导入表实测:`KERNEL32, mfc140, MSVCP140, VCRUNTIME140, api-ms-win-crt-*` | 未额外安装 VC++ 2015-2022 x86 运行时的机器,桥永远不可用 → 所有项最终 FAIL |
| **F-03** | P1 | 内容检查结果用正则 `failed\|error\|cannot connect\|bad data` 判失败,**"0 errors"、路径含 `error` 也会判 FAIL** | `verify_runner.py:30-31, 128-141`;本机实测 `classify_output(0, "...successfully! 0 errors...") == 'FAIL'` | 内容检查偶发误报阻断,且现场难以看出是文本匹配导致 |
| **F-04** | P1 | `preflight` 用 `read_text(encoding='utf-8', errors='replace')` 解析 `.prj`;UTF-16/ANSI 工程会读不到 `PCBDesignPath` → 误判"工程没有 PCBDesignPath" | `verify_runner.py:157-161`;对照 `backup_recovery._project_text`(`backup_recovery.py:129-136`)已正确区分 UTF-16/UTF-8/mbcs | 老工程/修复后工程被预检直接判 BLOCKED,且看起来像"工程数据坏了" |
| **F-05** | P1 | 内容检查报告写入**中心库目录** `LogFiles/`;写失败只拼进局部 `stderr`,PASS 路径下该信息被丢弃 | `verify_runner.py:688-693` | 只读共享/权限不足时无任何提示;中心库额外产生日志文件 |
| **F-06** | P2 | 备份只在 PASS 且 `safe_to_continue` 时清理;失败项 `backup/`(可能数 GB)永久保留,无保留策略 | `verify_runner.py:641-651`;`mentor_adapter.cleanup_evidence_backup` | 长时间批量后磁盘被失败证据占满 |
### 3.2 现场自动化(弹窗 / 桌面 / 进程)
| 编号 | 严重度 | 问题 | 代码证据 | 影响 |
| --- | --- | --- | --- | --- |
| **F-07** | P0 | **任何不在白名单里的弹窗 = `UNKNOWN_DIALOG` = 当前项 FAIL + 整批停止**。规则要求精确英文文本、`GXWND`+`Button` 类名 | `dialog_rules.py:216-236`、`188-236`;`dialog_supervisor.py:458-471` | Mentor 版本/语言/主题差异、任何新提示("Reusable block already exists""license checkout failed"…)都会中断整批;现场 6 项 IME 语言栏误判即此类 |
| **F-08** | P1 | 弹窗代理客户端**每请求 2 秒超时**,而 agent 端 `capture()` 最坏为"N 个窗口 × 0.75s UIA + 子控件枚举";UIA 探测超时后线程泄漏继续跑 | `dialog_agent.py:383-388`(默认 2.0s)、`dialog_probe.py:37-44, 242` | 机器繁忙/窗口多时 `DIALOG_PROTOCOL_TIMEOUT` 被当成致命错误;泄漏的 STA 线程与主探测并发调用 UIA,进一步拖慢 |
| **F-09** | P1 | **Win10 私有桌面上 UIA `InvokePattern` 只关闭原生菜单、不派发 MFC 命令**;`native_lm_verify` 默认关闭,只有显式勾选才走菜单路线 | `docs/API-FINDINGS.md` §7、README「Win10/Win11 兼容性边界」;`verify_runner.py:466-470` | Win10 现场两条路线都不保证成功;目前只能以"Win11 已验证"交付 |
| **F-10** | P1 | **本机只要有任何 `ExpeditionPCB.exe` 在跑就拒绝校验**(即使与本 CBB 无关) | `mentor_adapter.py:619-621` | 工程师日常开着 PCB 时无法点击校验;现场"先关掉所有 PCB"成为隐性前置条件 |
| **F-11** | P1 | `sAddress.adr` 任一残留即 `ICDB_SESSION_UNCONFIRMED` 阻断;正常/异常退出后残留都要人工处理 | `icdb_ownership.py:13-16`;`mentor_adapter.py:644-650`;`verify_runner.py:661-670` | 一次现场崩溃会让后续每次校验都失败,且错误信息指向"未释放",与真实原因(陈旧文件)难区分 |
| **F-12** | P1 | save helper 轮询循环**无超时、无取消检查**;helper 卡在 `doc.Save()` 时 worker 只能等监督器 600s 空闲超时 | `mentor_adapter.py:794-816` | 网络库/许可异常时单次长时间挂起;超时后 helper 仍可能继续写 |
| **F-13** | P0 | **超时/取消只"请求停止"(touch 取消文件),不终止 worker**;worker 只在启动前、PCB 启动循环、保存前 3 处检查取消 | `desktop_worker.py:149-157`;`mentor_adapter.py:684-689, 744-746, 787-789`;`verify_runner.py:892-903` | 监督器已返回 TIMEOUT/FAIL 并释放互斥;worker 仍可能在随后的几秒内完成 Save/Close。若清理时恰好观察到 PCB 已退出,会判定 `safe_to_continue=True` 并启动下一项,而上一项仍可能有迟到的原生写入 |
| **F-14** | P1 | supervisor 崩溃看门狗在 `cancel_path` 存在时(**生产总是存在**)只写取消文件然后返回,**不退出 worker**;只有 `cancel_path=None` 才 `os._exit(75)` | `desktop_worker.py:34-52`;`verify_runner.py:724` 恒写入 `cancel_signal` | 与 F-13 叠加:父进程崩溃后可能留下无监督的自动化进程继续写库 |
### 3.3 数据、权限与边界
| 编号 | 严重度 | 问题 | 代码证据 | 影响 |
| --- | --- | --- | --- | --- |
| **F-15** | P1 | 工具会**改写中心库内 `PCB/pcb.prj` 的 `CentralLibrary`**;修改前只在本次证据目录留单文件副本,网络库不做整工程备份 | `mentor_adapter.py:93-162, 707-712`;README 第 22 行亦承认 | 现场(网络中心库)没有可回退的工程副本;与 README「不允许直接改写中心库 .prj」的表述冲突 |
| **F-16** | P2 | `Work` 下 `.prj` 不唯一即预检跳过;修复/导入后残留的备份 PRJ 会被当作"无法唯一确定" | `verify_runner.py:152-155`;`preflight_skip_reason` | 条目被静默跳过(黄行),用户以为已校验 |
| **F-17** | P2 | Cert 完全不参与判定(设计取舍),但也没有"保存成功但未提交"的独立证据维度 | `verify_runner.py:313-330`;`collect_cert_evidence` 仅记路径 | 只能靠桥区分 PASS/PENDING;桥抖动时无法自证 |
| **F-18** | P2 | 备份策略:网络盘直接跳过递归备份(`backup_skipped`),本地盘 3-30s 预算 | `mentor_adapter.py:632-640, 399-453` | 现场中心库基本都在网络盘 → 实际上没有前置备份 |
### 3.4 性能与规模化
| 编号 | 严重度 | 问题 | 代码证据 | 影响 |
| --- | --- | --- | --- | --- |
| **F-19** | P1 | 每次"读取 CBB"都会:整文件 SHA-256 `.lmc` + 顶层目录指纹 + 逐 CBB 桥查询 + **逐 CBB `preflight_skip_reason`(网络 stat/glob/读 PRJ)** | `batch_status.py:95-122, 194-197`;`ui/main_window.py:257-263` | 3000 项网络库首屏可能数分钟到数十分钟;期间只有一个"正在读取中心库…"标签,无进度、不可取消 |
| **F-20** | P1 | 批量无进度条(仅全库 ICDB 模式有)、**不能取消当前项**(只能"当前项完成后停止")、崩溃后队列不持久化、不续跑 | `ui/main_window.py:417-454, 547-548`;`run_batch` 只在项间检查 stop | 长批次一旦中断只能从头再来;现场无法预估剩余时间 |
| **F-21** | P2 | 每次桥查询(单条路径)都新起一个 32 位进程;批量依赖常驻 `--server`,桥崩溃后整段剩余项直接标 UNAVAILABLE | `status_bridge.py:141-203, 206-332`;`batch_status.py:258-270` | 单条校验慢;桥异常时"剩余全部不可用",无法只重试当前项 |
| **F-22** | P2 | 多处 0.2s 轮询叠加 WMI 查询(`Win32_Process` 每次约 50-200ms)、integration 每次 `native_error()` 读 3 个原生日志 | `mentor_adapter.py:744-761, 800-809`;`integration.py:33-39`;`post_verify_diagnostics.py:32-39` | CPU/网络 I/O 放大;网络日志读取可能反过来拖慢原生操作 |
### 3.5 工程性 / 可维护性
| 编号 | 严重度 | 问题 | 证据 |
| --- | --- | --- | --- |
| **F-23** | P2 | 38 个源文件里 **102 处** `except Exception`/裸 `except`,大量 `except: pass`;故障常被降级成 `UNKNOWN/FAIL`,根因只留在日志 | 静态统计 |
| **F-24** | P2 | GUI/CLI 顶层异常只 `return 1`,不打对话框、不打印到控制台;批处理用户只看到退出码 | `application.py:134` |
| **F-25** | P2 | 无 CI 配置、无 lint/类型检查、无 LICENSE/CHANGELOG;300KB 二进制入库;`.gitattributes` 全量 `-text` | 仓库根目录 |
| **F-26** | P2 | 测试依赖"本机已 `pip install -e .` + 已装 Mentor + 有 x86 运行时",新克隆机器直接 pytest 会有 8 项环境失败 | 第 7 节 |
| **F-27** | P2 | 分支 49 个提交、+13k 行,`pyproject.toml` 版本仍是 `0.2.3b1`,候选包与正式包同版本号 | `pyproject.toml:6`(两分支相同) |
---
## 4. 阻塞点划分(任务视角)
把"阻塞"分成三类,避免把平台限制、工程缺陷、规模问题混在一起:
- **K1 平台/产品硬约束**:Mentor/Windows 决定,改代码无法消除,只能绕行、限定验收范围或推动替代方案。
- **K2 交付阻塞**:团队可修,但当前版本不满足"可交付/可批量"的最低条件。
- **K3 规模化阻塞**:单机少量可用,上批量/上团队前必须解决。
### 4.1 阻塞点总表
| 编号 | 阻塞点 | 类型 | 证据 | 受影响任务 | 解除条件 | 优先级 |
| --- | --- | --- | --- | --- | --- | --- |
| **K1-1** | Library Manager 没有公开的 CBB `Verify()` COM 方法,只有内部 32 位导出 | K1 | `docs/API-FINDINGS.md` §3;`LibraryManager.tlb` 审计 | 所有"编程触发 Verify"的路线 | 接受"只读判定 + ReusableCircuit 刷新"路线,或继续 ABI 研究 | — |
| **K1-2** | 状态判定只能靠 32 位 MFC ABI 桥,64 位 Python 不能直连 | K1 | `docs/API-FINDINGS.md` §3、§9 | 状态读取 | 保持独立 x86 桥(现状) | — |
| **K1-3** | 私有桌面上 LM 原生菜单不派发(Win10 UIA),`SwitchDesktop` 在本机不可用 | K1 | `docs/API-FINDINGS.md` §7 | Win10 现场 | 现场 Windows 10 真机验收;或限定仅 Win11 | — |
| **K1-4** | iCDB 服务器端口必须落在 10000–10100,可能被 Hyper-V/WSL 保留 | K1 | `mentor_adapter.py:978-1082`;文档 §8 | 所有 PCB 启动 | 管理员 `net stop winnat && net start winnat`(工具已给提示) | — |
| **K1-5** | Mentor 对"已验证工程"禁止 BackAnnotate;共享符号库没有 PRJ 入口 | K1 | 工单 #2 文档、`integration.py:93-100` | 已绿工程复检、共享库修复 | 按原生限制记录为"已同步/不支持",或人工处理 | — |
| **K2-1** | **桥不可用(缺 x86 运行时 / 未打包 / 路径找不到)仍可启动批量** | K2 | F-01、F-02 | 全部批量 | 打包 `VC_redist.x86` 或 `/MT` 静态链接;启动自检;无桥禁止批量 | **P0** |
| **K2-2** | **未知弹窗即停批**,白名单覆盖不了现场提示 | K2 | F-07 | 批量、Win10 | 规则分级(致命/可确认/仅记录)、未知弹窗可配置停机或继续并留证 | **P0** |
| **K2-3** | **超时/取消不终止 worker,孤儿进程可能继续写库** | K2 | F-13、F-14 | 数据安全、连续批量 | 明确"取消=停自动化客户端、保留原生会话"的边界;对 worker 进程做可验证的终止/对账;看门狗在崩溃时真正退出 | **P0** |
| **K2-4** | 共享中心库无跨机互斥;`main` 只有进程内互斥 + 本机 PCB 探测 | K2 | `verify_runner.py:504-547, 742-746`;分支 `library_lock.py` | 多人/多机使用 | 合并分支库锁并让上传工具/Mentor 侧协同;或规定"单人独占窗口" | **P1** |
| **K2-5** | 残留 `sAddress.adr` 永久阻断;本机任意 PCB 打开即拒跑 | K2 | F-10、F-11 | 日常使用 | 区分"陈旧地址文件"与"活会话"(探测可达性已具备,但策略过严);PCB 占用按 CBB/工程匹配而非全局 | **P1** |
| **K2-6** | ICDB 失联的自动 Repair 全链路未验收;Repair 后 BackAnnotate 被拒 | K2(分支) | `docs/releases/2026-11-03-field-feedback.md`、`2026-11-04-icdb-review-fixes.md` | 库损坏恢复、全库维护 | 现场真实失联库端到端验收;修复后重开/保存/READY 全绿 | **P0(分支)** |
| **K2-7** | Win10 未验证,且没有可用的菜单触发兜底 | K2 | F-09 | Win10 现场 | Win10 真机单 CBB 验收,或书面限定 Win11 | **P1** |
| **K2-8** | 内容检查文本误判 + `.prj` 编码假设 | K2 | F-03、F-04 | 启用内容检查的批次 | 修正解析/判定,补回归 | **P1** |
| **K3-1** | 首屏扫描 O(全库) + 逐 CBB 预检,无进度/不可取消 | K3 | F-19 | 3000 项批量 | 增量扫描、缓存指纹、预检并行/惰性、进度条 | **P1** |
| **K3-2** | 队列不持久化、不能取消当前项、无断点续跑 | K3 | F-20 | 长批次 | 队列清单落盘 + 逐项检查点 + 取消当前项 | **P1** |
| **K3-3** | 失败证据/备份无上限 | K3 | F-06 | 长期运行 | 证据保留策略(按天/按大小) | **P2** |
| **K3-4** | 质量门禁缺失(无 CI、版本号不变、环境耦合) | K3 | F-25、F-26、F-27 | 发布/回归 | CI(无 Mentor 的 mock 层 + 一台 Mentor 自托管 runner)、版本号规范 | **P2** |
### 4.2 任务可达性矩阵
| 任务场景 | 结论 | 关键阻塞 |
| --- | --- | --- |
| 单 CBB,Win11,本地/网络库,桥可用,无人占用 | ✅ **可用**(有隔离实机 PASS 记录) | 无 |
| 单 CBB,桥不可用/未装 x86 运行时 | ⛔ **必然 FAIL** | K2-1 |
| 小批量(10–50),工作时段 | ⚠️ **可用但易中断** | K2-2、K2-5、F-12 |
| 大批量(数百–3000) | ⛔ **时间与稳定性不可接受** | K3-1、K3-2、K2-2 |
| Win10 现场 | ⛔ **未验收** | K2-7、K1-3 |
| 共享中心库多人同时操作 | ⛔ `main` 无锁;分支为合作式锁 | K2-4 |
| 库损坏/ICDB 失联恢复 | ⚠️ 诊断与手动路径可用;自动 Repair 未闭环 | K2-6 |
| 无 Mentor 的开发机 | ✅ 仅单元测试(需先装包) | F-26 |
### 4.3 建议的解除顺序
1. **先让"批量的失败是可信且廉价的"**:桥预检 + 打包运行时(K2-1)→ 不做无用刷新。
2. **再让"批量的中断可控"**:弹窗分级(K2-2)、取消/超时语义(K2-3)、占用与残留地址策略(K2-5)。
3. **然后才谈规模化**:增量扫描、进度、续跑(K3-1、K3-2)。
4. **平台边界单独验收**:Win10(K2-7)、共享库并发(K2-4)、ICDB 修复闭环(K2-6)。
---
## 5. 现场失败模式 → 代码根因映射
| 现场现象(文档) | 代码根因 | 对应问题 |
| --- | --- | --- |
| 6 项 `UNKNOWN_DIALOG: TF_FloatingLangBar_WndTitle` | IME 语言栏过滤条件过窄(类名+标题+无控件同时满足) | F-07 |
| `TUNER_R836` Save/Close 后桥返回 PENDING | 桥判定 + Verify 未提交;或原生 BackAnnotate 被拒 | F-17、K1-5 |
| `TUNER_R836_A` 数据库打开失败被记 UNKNOWN_DIALOG | 早期靠文本分类;现走规则白名单 | F-07 |
| `1GPHY_8211` 打开时失联 → 后续 Repair `REPAIR_DATABASE_IN_USE` | 失败打开的 PCB 未被关闭(分支已修:启动失败关闭路径) | K2-6 |
| 5 项 Project Integration 符号错误 | 工程/符号数据问题,工具只负责分类与留证 | — |
| 3 项 JobPrefs / 本地 Cell Library 失败 | 环境/工程状态;工具仅诊断不修复 | — |
| 端口 10000-10100 被保留 | `WinError 10013`,Hyper-V/WSL 动态预留 | K1-4 |
| 桥 UNAVAILABLE 但报告"四绿"风险 | 已被 fail-closed 设计排除(不会伪造 READY) | — |
---
## 6. 活跃分支现状(`codex/temp-issue-2-icdb-recovery`)
### 6.1 新增能力(相对 main)
- 库锁与占用探测:`library_lock.py`、`owner_probe.py`、`native_occupancy.py`(与上传工具兼容的 `.cbb-upload.lock` / `.blocked.json` 协议)。
- CBB 管理:`management.py`、`native_management.py`、`management_transaction.py`、`native_engineering_identity.py`、`native_export_guard.py`(新增/同名替换/移除、身份与导出副本保护)。
- 恢复:`reimport_recovery.py`、`scoped_manifest.py`、`post_repair_consent.py`、`pcb_restore_prompt.py`、`maintenance_entry.py`(库外完整工程副本恢复、历史 PCB 版本选择)。
- 策略调整:取消应用自动备份,改为**弹窗提醒手动备份**(`docs/releases/2026-11-03-manual-backup.md`)。
- 启动失败关闭:`failed_session.py` 扩展为"预检失败/数据库打开失败也协作关闭 PCB"。
### 6.2 本机验证结果
- 1,178 passed / 18 failed;其中 8 项与 main 同因(环境),新增失败集中在:
- **长路径**(`native_add_failures` 两个用例,150 字符目录名 → Windows `MAX_PATH`);
- **owner probe 依赖安装**(`native_export_guard` 6 个用例:子进程 `-m cbb_refresh_verify` 不可用);
- **编码**(`native_repair` 一个用例按 cp1252 解码失败);
- **无 Mentor 安装**(`native_repair` 取消用例)。
### 6.3 分支仍未满足的门槛(文档自述)
- 服务器会话失联 → 实际按钮触发 → 自动 Repair → 重开 → 保存关闭 → READY 的**完整链路未验收**。
- `1GPHY_8212` 原生 Repair 后 **BackAnnotate 仍被拒**,结论未变。
- Windows 10 未验证(当前实机 Win11 / EE7.9.5)。
- 历史 PCB 版本恢复记为 `RESTORED_REVIEW_REQUIRED`,**不等于无损修复**。
- 目标缺 `PartsDB` 分区时无法完成完整校验。
- 共享符号库不支持自动修复。
- 版本号未递增、分支未合并。
> 结论:分支在"管理 + 恢复"上补齐了很多能力,但**没有解除 K2-6(ICDB 自动修复闭环)和 K2-7(Win10)**;同时引入了新的环境敏感性(长路径、owner probe 子进程、编码)。
---
## 7. 测试与质量评估
### 7.1 本机结果
```
main: 463 passed, 8 failed, 1 warning, 37.09s
branch: 1,178 passed, 18 failed, 1 warning, 92.29s
```
main 的 8 项失败归因:
| 失败 | 原因 |
| --- | --- |
| `test_application`(2 项)、`test_abnormal_shutdown`、`test_extended_safety`、`test_failure_lifecycle`(共 5 项) | 子进程 `python -m cbb_refresh_verify` 依赖 `pip install -e .`,本机安装未完成 |
| `test_native_repair::test_repair_cancellation...`、`test_verify_runner::test_pcb_launch...` | 本机无 `D:\Mentor\7.9.5EE` 安装 |
| `test_packaging_status_bridge::test_compiled_bridge...` | 缺 x86 VC/MFC 运行时,`0xC0000135` |
### 7.2 覆盖情况
**做得好的**:状态判定(PASS 只能来自桥 READY)、对话框规则/后置条件、ICDB 日志新鲜度、备份/恢复、进程释放、UI 交互都有大量单测,且测试直接编码了"不得伪造绿色"的安全契约。
**缺口**:
- 没有真实 Mentor 的集成测试(全部依赖 fake COM/进程边界);
- 没有 Win10 测试矩阵;
- 没有网络库并发/多人场景;
- 没有长时间稳定性与性能回归(600s 空闲超时、3000 项批量);
- 测试与"本机安装 + 本机 Mentor 路径"耦合,换机即红;
- 无 CI,测试结果靠人工粘贴进 release note。
### 7.3 代码静态指标
- 38 个源文件 / 8,180 行;**102 处**宽泛异常捕获;15 处 `time.sleep`;15 处 subprocess 调用。
- 硬编码 `D:\Mentor\7.9.5EE\SDD_HOME` 兜底 5 处(可作为默认,但需在 UI/日志里明确"发现失败")。新机器上会静默落到不存在的路径,报错信息偏底层。
---
## 8. 修复路线图(建议)
### P0(1–3 天,先让批量"失败得正确")
1. **桥部署闭环**
- 打包 `VC_redist.x86.exe`(或桥改 `/MT` 静态链接),安装脚本检测/安装;
- 启动时执行一次桥自检(`--codec-test` 或空查询),失败则禁用"批量校验"并给出可操作提示;
- `read_library_fast` 返回 `UNAVAILABLE` 时,UI 明确"无法判定绿色,批量将全部失败",不静默入队。
- 验收:干净 Win11 + 无 VC 运行时 → 工具提示安装而不是跑 3000 次无效刷新。
2. **未知弹窗分级**
- 规则增加 `on_unknown: stop | record_continue | block_item`;
- 默认对"无按钮/纯文本/IME/浏览器宿主"仅记录,对"数据库恢复/许可/保存失败"阻断;
- 每次未知弹窗都落 `dialogs.jsonl` + 截图证据,批量结束汇总"待人工确认弹窗"。
- 验收:新增一个未登记弹窗的模拟场景,批量不中断且证据可查。
3. **取消/超时语义**
- 明确"取消 = 停止自动化客户端,保留原生会话";对 worker 增加强制终止开关(仅在未进入 Save 阶段可用);
- 看门狗在 supervisor 退出时按"是否处于 Save/Close"决定终止或保留,并落 `watchdog-decision.json`;
- `run_verify` 在 worker 未确认退出时不得释放互斥、不得继续下一项(当前已部分满足,需把"进程仍活"纳入 `safe_to_continue`)。
- 验收:模拟 Save 卡死 → 工具超时后 worker 确实退出或明确标记"仍活",下一项不启动。
### P1(1–2 周,现场可用性)
4. 弹窗代理超时预算与 `capture()` 并发控制(F-08);UIA 探测改为按进程白名单 + 单窗口超时,禁止泄漏线程。
5. 占用/残留策略(F-10、F-11):PCB 占用按 CBB 路径匹配;`sAddress.adr` 增加"不可达 + 非本机进程 + 超时"三条件判定为陈旧并可清理(需用户确认)。
6. 内容检查判定(F-03)与 `.prj` 编码(F-04)。
7. 中心库写入保护(F-15):改写 `pcb.prj` 前做整文件副本 + 变更清单,网络库至少保留原文件并可一键回滚。
8. 合并分支库锁(K2-4),并与上传工具约定锁协议。
### P2(2–4 周,规模化)
9. 增量扫描/指纹缓存、预检惰性化、进度条、取消当前项、队列持久化与续跑(F-19、F-20)。
10. 证据保留策略与磁盘配额(F-06)。
11. CI:mock 层全量测试 + 一台 Mentor 自托管 runner 做冒烟;版本号规范(`0.2.3b1+candidate.49`)。
12. 清理宽泛异常,至少在关键路径保留 `error_code` 与原始异常链(F-23)。
---
## 9. 附:关键证据索引
| 主题 | 文件:行 |
| --- | --- |
| 成功判据(桥 READY) | `src/cbb_refresh_verify/verify_runner.py:313-330, 981-1000` |
| 内容检查判定 | `src/cbb_refresh_verify/verify_runner.py:30-31, 128-141` |
| 预检(PRJ/PCB/链接) | `src/cbb_refresh_verify/verify_runner.py:144-174` |
| 端口预检 | `src/cbb_refresh_verify/mentor_adapter.py:1061-1082` |
| 数据库地址阻断 | `src/cbb_refresh_verify/icdb_ownership.py:13-16` |
| PCB 全局占用检查 | `src/cbb_refresh_verify/mentor_adapter.py:619-621` |
| CentralLibrary 改写 | `src/cbb_refresh_verify/mentor_adapter.py:93-162, 707-712` |
| save helper 循环 | `src/cbb_refresh_verify/mentor_adapter.py:790-816` |
| 取消信号 | `src/cbb_refresh_verify/desktop_worker.py:149-157`;`mentor_adapter.py:684-689, 744-746, 787-789` |
| 看门狗 | `src/cbb_refresh_verify/desktop_worker.py:25-56` |
| 弹窗规则 | `src/cbb_refresh_verify/dialog_rules.py:188-236`;`assets/dialog_rules.v1.json` |
| 弹窗代理超时 | `src/cbb_refresh_verify/dialog_agent.py:383-388`;`dialog_probe.py:37-44, 242` |
| 状态桥 | `src/cbb_refresh_verify/status_bridge.py:115-203, 206-332` |
| 批量状态扫描 | `src/cbb_refresh_verify/batch_status.py:95-122, 184-277` |
| UI 读库/队列 | `src/cbb_refresh_verify/ui/main_window.py:225-335, 417-548` |
| 打包清单 | `packaging/CbbRefreshVerify.spec:4-25` |
| 分支库锁 | `src/cbb_refresh_verify/library_lock.py:80-200`(分支) |
### 复现命令
```powershell
git clone https://git.simgreek.com/Skyworth_Digital_Hardware/cbb-refresh-verify-795.git
cd cbb-refresh-verify-795
python -m pip install -e .
python -m pip install pytest pytest-qt
python -m pytest -q # main: 463 passed / 8 failed(本机环境)
git worktree add ..\cbb-branch origin/codex/temp-issue-2-icdb-recovery
cd ..\cbb-branch; python -m pytest -q # branch: 1178 passed / 18 failed(本机环境)
```
桥依赖验证:
```powershell
# 1) 导入表:KERNEL32 / mfc140 / MSVCP140 / VCRUNTIME140 / api-ms-win-crt-*
dumpbin /dependents .\tools\status_bridge\bin\CbbStatusBridge32.exe
# 2) 实机启动:缺 x86 运行时时的退出码 -1073741515 (0xC0000135)
.\tools\status_bridge\bin\CbbStatusBridge32.exe --codec-test
```