05-测试-已知可用基线差异对比与变量收敛排查法

一、适用场景

「明明看着都对，却仍然失败」这一类问题：打包被拒、装上起不来、性能不达标、配置不生效、迁移后数据对不上。
共同特征是存在一个已知可用基线 A（能装上的旧包、改动前的版本、达标的那次测量、正常的源端库）
和一个失败对象 B，需要回答"差异在哪、哪个差异是因"。

与"从零猜根因"相对：本方法不猜，只做可枚举的事实比对 + 单变量验证。

二、操作步骤

1. 锁定基线 A 并确认它真可用：A 必须有成功实证（装过 / 跑过 / 测过），并尽量与 B 同源同链路。
   A 本身带病会得出反向结论。
2. 先校准比对落点：确认你比的是不是"对方真正收到的那一份"。
   锚点：.workbuddy/memory/2026-10-16.md L96-106（本地逐字节无罪的包，DSM 收到的却是中转后的文件）；
   SPK 包反例"只在包内找原因、不核落地文件"。落点错了，后面全白做。
3. 把 A/B 拆成可枚举的事实清单：按「结构 / 元数据 / 内容 / 环境」四类各列一遍，写到能数出项数。
   锚点（结构类）：tar 头逐字段比对 mode/uid/gid/typeflag/magic/version/uname/gname/prefix；
   锚点（内容类）：全部生命周期脚本 sh -n 语法校验 + LF/无 BOM/无 NUL/shebang；
   锚点（元数据类）：INFO 逐字节比对。
4. 逐项比对，产出三个数：一致数 / 差异项 / 单边缺失项。
   锚点：2026-10-16 逐项对比两版 SPK，12 个条目中 10 项完全一致，差异仅 version 与 start-stop-status 两处。
5. 按差异数 N 走分支（本方法核心）：
   - N = 0 → 清单/结构无罪，变量必在清单之外：落点是否同一份文件、传输链路、宿主环境、运行载荷。
   - N = 1 → 可直接定位，改这一项并复现一次即可证实或证伪。
   - N ≥ 2 → 禁止逐个猜，做单变量 A/B：用 A 的其余项 + 只替换 B 的某一个差异项，组对照组。
   装上（通过）⇒ 问题在被替换的那一项；装不上 ⇒ 与本次改动无关，转向环境。
   锚点：基线对照包 程序源代码/deploy/synology/spk_ctl/ → 产物 群晖安装包/hfms-ds418play-基线对照-20261016.spk。
6. 结论必须能被复现一次证伪或证实：改完重跑，确认不再失败。
   锚点：程序源代码/app.py L3821-3830 注释里记录的 A/B 验证（p99 ~888ms → ~96ms）。

三、注意边界

• 清单漏列 = 前功尽弃：按四类各列一遍，宁多勿少；漏一项就可能漏掉真因。
• 差异对比只回答"哪里不同"，不回答"哪个是因" —— 因果必须靠单变量 A/B，不能靠"看起来最可疑"。
• 性能类比对必须同档位：并发数、预热窗口、有无并行负载都要一致，否则比出来的是噪声。
  锚点：05-测试-QA测量环境隔离与失真排除法（DB 快照副本 + DB_PATH 隔离 + 零并行负载）。
• 相关性当因果是常见误判：tar 头的 mtime / size 随内容变化属正常差异，不是因。
• N≥2 时逐个改是最大的时间黑洞：两个变量来回纠缠，永远收敛不了。
• 本方法产出的是定位，不是修复；定位到之后仍要按对应域的修法处理。

四、反例避雷

• ✗ "看着像"就下结论：不做清单、不数差异，直接说"应该就是格式问题"→ 同一个地方反复打转。
• ✗ 比错落点（2026-10-16 实战）：本地逐字节比对做到"12 条目 10 项一致"仍然白做，
  因为 DSM 收到的是经中转后的文件。解法：先核落地文件大小 + SHA256，再谈结构。
• ✗ N≥2 时逐个改：改一个不行再改一个，两个变量纠缠。解法：基线对照包，一次只换一个变量。
• ✗ 把相关性当因果：看到 mtime 不同就改时间戳，真因在别处。
• ✗ 轻载与重载混比：p99 96ms（近空闲）和 470ms（8 并发）不是同一个测量对象，不能放一张表里当对照。
• ✗ 拿带病的 A 当基线：A 若本身有问题，会推出"差异项都无罪"的反向错误结论。

五、代码锚点 / 实战战绩

锚点：
- 程序源代码/app.py L3821-3830（HFMServer 常驻线程池，注释内记录 A/B 验证方式与指标口径）
- 程序源代码/deploy/synology/config.syno.env L11-14（官方 Spec vs 面板实测，双源比对范本）
- 程序源代码/tools/inst_extract.py（登记 vs 原件比对，输出待新增 / 路径失效 / 无主登记三向）
- 程序源代码/deploy/synology/spk_ctl/（基线对照包暂存目录，控制变量用）

战绩：
- 2026-10-14：新旧线程模型 8 并发 ×40s 同档位对照 → 稳定期真实开连接 2052→0、中位 86.6→32.7ms、
p99 720→470ms、>1000ms 秒级卡顿 4→0。
- 2026-10-15：version 差异对比定位到四段版本号违规 → 改三段后装上。
- 2026-10-16：12 条目 10 同 2 异 → 结构无罪，转向链路；再组基线对照包做二分。
- 2026-10-15：制度登记 vs 原件比对 → 10 域 / 75 编号 / documents 76 行，待新增 0、路径失效 0、无主登记 0。

六、关联笔记

• 与 06-成品-群晖SPK打包与格式排查法 第 8、9 步（包内排查穷尽三层证据法 / 基线对照包控制变量法）
  的关系：那是本方法在 SPK 域的实例化，本包提供跨域的通用层与 N 分支判据。
• 与 05-测试-QA测量环境隔离与失真排除法 配合：先隔离环境再做比对，否则差异项里混着噪声。
• 与 06-成品-部署目标机硬件规格核实与参数联动法 的"双源核实"是同一思路在规格方向的用法。
• 与 00-总纲-前序结论证伪与产物连锁订正法 相接：本方法产出的结论一旦被推翻，走那条做连锁订正。

七、版本记录

• v1.0（2026-10-19）：首版。六步操作（锁基线 → 校准落点 → 拆清单 → 逐项比对 → N 分支 → 复现验证）
• 六条反例；附 scripts/diff_locate_check.py 只读体检器（逐项比对 + N 分支判定 + 清单校验），
  已实测：内置 12 项 10 同 2 异实战样例 PASS（正确判定需 A/B）；
  只给"包看着都对，重打一次试试"的结论文本 FAIL（无清单，比对不成立）。