SOP — 共享库 precheck_module 新增 ProbeBatch（只读探测批量化上移）

变更日期：2026-10-08　｜　变更类型：C 类（共享库结构调整，向后兼容） 交付物：~/py_public_modules/precheck_module.py 新增 ProbeBatch 类；eda_tools_ins 三处工程删除同名副本并改走共享库。

1. 背景

2026-10-08 的「只读探测批量化」改造中，eda_tools_ins 下的三个在用子工程各自新增了一份 utils/probe_batch.py（5580 B × 3，cmp 实测内容完全一致），提供「记录 → 打包预取 → 命中缓存」三件套。

该模块进入第二次复用，按共享库判据（同名副本出现 ≥2 处且内容一致 → 上移）应集中一份；同时它与 base_module 已有的 query_on_host / probe_per_host 互补但不等价：

能力	面向对象	命令来源
base_module.probe_per_host / PreCheckBase.prefetch	继承 PreCheckBase 的检查器	static_probes() 静态表
ProbeBatch	任意执行通道（含不继承基类的工程，如本地 LocalExecutor）	既有探测函数实际调用时记录，无需重写探测逻辑

故上移目标定为 precheck_module（与 build_probe_shell / parse_probe_output 同源，避免跨模块依赖）。

2. 目标

1. 三份 utils/probe_batch.py 副本删除，改由 from precheck_module import ProbeBatch 取用；
2. 三个子工程的 precheck / drift 结论与命令数收益与改造后完全一致（报告逐行不变）；
3. 共享库变更向后兼容——其余挂载工程无需改动。

3. 前置条件

• ~/py_public_modules 已通过 .pth 挂入各工程 venv（python -c "import precheck_module" 可通）；
• 三个子工程 .venv/bin/python 可用；
• 改动前先备份（见 §7）。

4. 影响范围

对象	改动
~/py_public_modules/precheck_module.py	新增 ProbeBatch 类；typing 导入补 Callable / Iterable / Tuple。无既有符号改名或删除
eda_tools_ins/Synopsys/rocky9_eda_compat_20260928/deployer.py	import 归并入既有 from precheck_module import ... 行
eda_tools_ins/Synopsys/synopsys_pdk_saed32_20260929/deployer.py	同上
eda_tools_ins/Cadence/pdk_integration_20260927/deployer.py	同上
三处 utils/probe_batch.py	删除（副本另存入各工程 probe_batch_20261008/backup/<工程>/utils/ 作回归对照件）

无需停服；不影响任何远端主机。

5. 分步操作

步骤 1：备份

TS=$(date +%Y%m%d-%H%M%S)
D=~/Documents/py_public_modules_changes/probe_batch_upstream_20261008
mkdir -p "$D/backup"
cp -a ~/py_public_modules/precheck_module.py "$D/backup/precheck_module.py.bak.$TS"
chmod 600 "$D/backup/precheck_module.py.bak.$TS"

预期：备份文件权限 600。失败判断：目录不可写 → 检查 $D 属主。

步骤 2：共享库新增 ProbeBatch

在 precheck_module.py 末尾追加 ProbeBatch 类（collect → prefetch → run 三方法）。要点：

• run() 复用文件内既有的私有 _ProbeResult（属性集与 CommandResult 对齐），不另造结果类型；
• prefetch() 每台拼一段 shell（build_probe_shell），主机间 ThreadPoolExecutor 并发，主机内串行；
• 连接层失败（exit_code == -1）时全部键记 -1，与逐条探测语义一致；
• 超时按记录到的各命令超时之和推导，钳制在 [120, 1800] 秒。

坑：typing 导入若漏 Callable / Iterable / Tuple，collect 与 _cache 的类型注解会在导入期报 NameError。

步骤 3：三处 deployer 归并 import

# 每处：把 ProbeBatch 并入既有 precheck_module 导入行，并删除 utils.probe_batch 导入行
sed -i 's/^from precheck_module import has_block, render_report$/from precheck_module import ProbeBatch, has_block, render_report/' \
  <工程根>/deployer.py
sed -i '/^from utils\.probe_batch import ProbeBatch$/d' <工程根>/deployer.py

预期：grep -n probe_batch <工程根>/deployer.py 无输出。

步骤 4：副本先入对照备份，再删除工作区副本

坑：probe_batch_20261008/backup/ 原先不含该文件（它是改造时新增、从未备份），若直接删工作区副本，回归自测装配「旧版」时会因缺件 ImportError。故必须先复制到 backup 再删。

B=<工程根>/probe_batch_20261008/backup/<工程名>/utils
mkdir -p "$B"
cp -a <工程根>/utils/probe_batch.py "$B/probe_batch.py"
rm <工程根>/utils/probe_batch.py

步骤 5：回归

见 §6。

6. 验证

项	命令	实测结果
A/B 对照	python3 /home/rain/Documents/eda_tools_ins/probe_batch_20261008/selftest.py	4/4 通过：rocky9 precheck 18→3、drift 30→3；saed32 16→4；ic617 8→4；结果一致=True、命令数下降=True
import 冒烟	三工程 .venv/bin/python -c "import deployer, precheck_module; print(precheck_module.ProbeBatch.__module__)"	三处均输出 precheck_module，hasattr(deployer,'ProbeBatch')=True
副本清零	find /home/rain/Documents/eda_tools_ins -name probe_batch.py -not -path '*/backup/*' \| wc -l	0
共享库副作用	其余挂载工程 import precheck_module 冒烟	通过（新增类，无改名）

7. 回滚

# 1) 恢复共享库
cp -a ~/Documents/py_public_modules_changes/probe_batch_upstream_20261008/backup/precheck_module.py.bak.<TS> \
      ~/py_public_modules/precheck_module.py
# 2) 恢复三处 deployer（备份见同目录 backup/eda/<工程>/deployer.py.bak.<TS>）
# 3) 恢复三份副本（从各工程 probe_batch_20261008/backup/<工程>/utils/probe_batch.py 复制回 utils/）

回滚后验证：python3 .../probe_batch_20261008/selftest.py 仍应 4/4 通过（旧版与新版的装配都在 backup 中）。

备份台账见 backup/README.md。

8. 风险说明

风险	缓解
误删副本致回归自测缺件	已在 SOP 步骤 4 固化为「先备份再删」，并写入步骤顺序
未预取的命令静默漏合并	ProbeBatch.run 对未命中缓存回落逐条下发，语义与改造前一致 → 漏配只损失收益、不改结论
collect 两遍模式要求命令确定性	只适用于「命令由配置派生、不依赖前一条结果」的状态探测；变更类命令不走本模块
共享库被多工程共用	本次为纯新增（无改名/删除），向后兼容；已做多解释器 import 冒烟

---

来源：/home/rain/Documents/py_public_modules_changes/probe_batch_upstream_20261008/SOP.md ｜ 最后更新：2026-10-08 13:27（由 build/sync.py 同步，请勿在站点侧修改）