PDF 设计稿版本差异对比（pdf-design-diff）

用途

对同一份设计稿/图纸的两个 PDF 版本做多层交叉验证，定位并标注差异。一条命令按序完成：

1. 文件级 sha256 检查（相同即短路）；--all 逐页粗筛跳过完全相同页
2. 像素 diff 定位差异块（主扫 + 灵敏度补扫）
3. 文本层行级集合差 + 矢量路径 bbox 签名多重集差 → 增/删元素数
4. OCR 读出内容（6x）；关键行（许可证/电话/日期/公司/地址）先用已在算的整页 3x 读数免费交叉验证，不足才升 10x，且只重扫关键行邻域窗口
5. 条码/QR/UDI 解码对比：按 payload 集合差对比，不对比图像
6. 差异块内小簇聚类 + 位移模式 + 高清裁图 + 结论草稿 + 合并报告
7. 属性级自动核验（默认开）：矢量逐点差 + 8 字段属性差 + 框外核验一次进程跑完，并标出未被任何像素簇覆盖的属性变化（漏检守卫）

何时使用

• 用户给出同一图纸的两个版本 PDF（文件名常带 V03/V04、Rev A/B、日期后缀）要求对比差异
• 图纸为全矢量（包装设计稿、版面工艺图），文字已转曲线，肉眼或文本提取无法对比
• 需忽略标题栏/修改记录只看中间设计稿，或需标注差异位置并输出证据
• 版面含条码/二维码/UDI（GS1 DataMatrix、批号、效期）要按解码数据核对
• 多页说明书/版面逐页对比

不适用：纯文本 PDF 的合同/文档对比（文本 diff 更快）；位图扫描件大幅面比对（先做图像配准）。

使用方法

运行打包脚本（不要逐段重写分析代码）：

python scripts/compare_design_drafts.py OLD.pdf NEW.pdf --out diff_output \
    --auto-align --forensics --barcode --details auto:6 --draft-report --pack

一条命令产出全部交付物。随后只剩一步 LLM 工作：把 report_md.draft.md 改写为 report_md.md（补语义结论与风险），需要时重跑 --pack。

最常用参数（完整参数、子脚本 CLI、产物清单见 references/parameters.md）：

环境依赖：pymupdf、numpy、pillow、rapidocr-onnxruntime（或 easyocr）。缺 rapidocr 时先试 easyocr；中文模型 zip 损坏（BadZipFile）是 easyocr 常见坑，直接换 rapidocr。

★ 硬性规则 1：报告的 md 一律用结论式摘要，禁止直接指向 diff_summary.md（后者是机器证据：逐行 OCR 清单、像素坐标、路径增删计数，进正文会淹没细节，实测被退回）。报告只有三节：① 结论——共 N 处差异的语义结论与风险；条码与关键行复核在此以单行条目出现；② 差异汇总表（编号 / 位置 / 旧版 → 新版 / 性质，一行一条、语义级）；③ 说明——只写范围不写内容（忽略区坐标/名称、弱差异性质、原始明细留档位置）。「位置」列必须保留「p0 块 #N / p0 簇 N.M」前缀，否则合并报告脚注会映射错块或丢行。结构只以 report_md.draft.md 或 references/report_md.template.md 为准，禁止拿历史报告/上一份报告当模板。合成前 check_report_md.py 机械校验：忽略区内容入正文即 block（退出码 4）。

★ 硬性规则 2：已删除的「对比方法」与「重点复核项」两节不得 re-add。 前者是过程信息（旧/新版标注、链路段、坐标基准、忽略区行），后者是机器证据表格（条码 payload、关键行复核状态）——其风险内容已在「结论」段以单行条目保留，信息不丢但不占章节位。旧报告里若还有这两节，那是历史产物，不要照抄。

执行提速（默认路径）

分工原则：能代码做的都在脚本里。 外框测量、归一化裁剪、位移量化、证据裁图、报告配置与合成全部由脚本一次完成——不要临时写 Python/JSON 片段补这几步（实测那样一轮要 20+ 次工具往返）。

• 一条命令出全部产物，把输出一次看全，不要一步一探。
• 解释器固定：用已装全依赖的 Python，勿逐环境探测；脚本启动即打印 [OK] interpreter: 与 [OK] pymupdf ...，读这两行即可。
• 读图预算：默认 0 张，最多 2 张（硬闸门）。内容结论以 diff_summary.md 的「差异块内部小簇」段为准（与放大图红框同源）；只有判视觉形态（Logo 重绘风格、图标形状、底纹）时才读图，且每读一张必须先登记（read_budget.py）。超预算未授权、或自报张数与台账不符，--pack 直接失败（退出码 5）。
• LLM 只做两件事：定范围（是否/如何排除页眉与修改记录）与写结论（性质归类、风险标注）。位置、量值、条码 payload、复核状态一律取脚本输出，不靠目测。
• 补充取证 / 差异定性 / 矢量·属性·框外核验各有专责脚本，都走一个进程：probe_regions.py（批量探针，spec 驱动）、diag_reexport.py（栅格差 / 缩放 / 位移 / 内容增删）、forensics_kit.py（逐点差 / 属性差 / 框外核验）。不要一个疑点起一个 python -c。
• 批量合并跑：多对文件一次跑完再统一写报告；不需要内容结论时加 --no-ocr。
• 性能：--timing 打函数级 incl/self 表并写 timing.json。OCR 是唯一主要算力成本，要提速只能从「次数 × 倍率」入手；耗时结构与已证伪的提速手段见 references/methodology.md「性能」节。

解读与汇报规则

1. 三层证据齐全才下结论：像素块位置 + 路径增删数 + OCR 内容互相印证；只有像素证据时只报位置与大小，不猜内容。
2. 关键数据复核状态必须为 OK；RECHECK 时换更高倍率或换引擎再验，并在「结论」段以单行风险条目如实标注（不单列复核章节）。
3. 汇报按差异块逐条：位置 → 旧内容 → 新内容 → 性质（删除 / 新增 / 改写 / 位移 / 格式修正）。
4. 忽略区内容（标题栏版本号、修订日期、修改记录新增行）不得出现在报告任何位置（含汇总表与说明段）；说明段只引用脚本的「忽略区命中 N 处」计数与坐标并声明已按要求忽略。反例（禁止）：「版本号 V03→V04、修订日期 …」——转述内容 ≠ 写范围。
5. OCR 是矢量小字的最后手段：7–8pt 转曲线字 6x 渲染是下限，关键行 10x。

详细方法学、排错与实测案例见 references/methodology.md。

注意事项

• 控制台与脚本输出只用 ASCII 符号（[OK]/[WARN]/[NG]），禁用 emoji（GBK 控制台会崩）。坐标一律用 PDF pt 思考与传参；渲染像素 = pt × scale，换算错误是定位偏差首要来源。
• 条码能力边界：zxing-cpp 解 QR/DataMatrix/EAN/UPC/Code128，cv2 解 QR + EAN/UPC。UDI 场景先确认 zxing-cpp 可用；全缺时必须注明「DataMatrix 未解码」，不得只看 QR 就下「条码无变化」结论。
• 两版页尺寸不一致：优先加 --auto-align（外框尺寸一致即归一，不一致则 [WARN] 并保持不归一化）。降级分支与三分支判定见 methodology「页尺寸不一致」。
• 多面板版面（纸盒展开图）先看守门告警：--auto-align 的外框只是其中一个面板，其余面板会被静默排除（实测覆盖率低至 16%）。覆盖率 <60% 时脚本 [WARN] 并打印可直接粘贴的 --frame-rect，仍须对照 annotated_*_p<N>.png 确认覆盖；或去掉 --auto-align 按面板分别比对。
• 重新导出型 PDF（同内容不同导出批次：白边零差异 + 正文散布 2–5% 像素差 + ±3px 平移最优偏移 0）属字形栅格差，不是内容变化；三步诊断见 methodology「重新导出型」。
• 页级聚合成单一大块时以「差异块内部小簇」为准（簇矩形 + 带内单侧差异行 + 位移模式）：通常无需读图即可定结论；窄条簇（宽/高 <3pt）为边界/线条位移，量值看 --forensics。
• 细条小差异块（高 <30pt 且宽 <200pt）的放大图与 OCR 自动外扩到整行；整页标注红框仍标原始小块。
• PDF 报告生成坑（pymupdf）：insert_text(fontname="china-s") 对长中英混排静默截断（rc 仍返 1）→ 带 CJK 报告一律 TextWriter + Font("china-s")，保存后逐块回读校验（build_merged_report.py 已内置，退出码 2）。
• 黄底条标的是内容层面新增/删除/改写的字词，不是「这行动过」：行内只改几个字就只圈那几个字，只改字号/换行而文字未变不标黄，纯插入行只在插入侧标黄。判定细则（双路 OCR 交叉验证、密度守门）见 methodology「黄底条」节。

版本历史

完整逐版明细见 CHANGELOG.md。