PDF 翻译 · 对照校对

本技能的 review 是翻译校对，不是论文精读或学术审稿。默认不追加精读；仅精读/总结请求交给 paper-reading，学术审稿交给 paper-review。

将学术 PDF 论文翻译为不含原文的中文图文文档，完成原译对照与逐字校对，并按需产出离线自包含 HTML。

核心原则

1. 翻译忠实：公式必须与原文逐字一致，不得凭记忆补写。翻译使用领域惯用表述，但不得改变物理含义。
2. 公式严格：所有公式保留原文编号；文本公式用 $...$（行内）、$$...$$（块级），不用 \(...\) / \[...\]（部分 Markdown 预览器不识别，会显示为源码）。
3. 图片按图注配对：图片必须按论文 Fig. 图注定位提取，内容与编号双重核对；不得按 PDF 内嵌对象顺序取图。
4. 审查必做：交付前逐字核对公式、翻译与图片，反复检查，不允许"看起来对"。
5. 交付件不得露出源码：最终 HTML 里读者能看到的只能有译文、公式排版与图片。原始 LaTeX（\xi、\frac、\|）、未渲染的定界符（$、\(）、Markdown 记号（**粗体**、_斜体_、段首 >）与 KaTeX 解析失败回退块都算交付缺陷，不是"渲染问题"。这类缺陷在 Markdown 阶段查不出来，必须对最终 HTML 逐项查（见 5.5）。
6. 没有报错 ≠ 渲染正确：渲染器"没报错"只说明它接受了这段 TeX，不说明它渲染出的数学是对的。KaTeX 对 $\\|\bar{v}_L\\|$（把 $\|\bar{v}_L\|$ 的每个反斜杠都写成了两个）不报任何错误：它把 \\ 当成换行、把 | 当成单竖线、把 \\bar 拆成字面量 bar，于是"手速度平均范数"在页面上变成单竖线加三个字母。结论：公式核对必须目视比对渲染结果与原文（见 5.1 第 4 条），不能以"渲染器没报错"结案。同理，检查器的盲区不等于覆盖率——把 $…$ 整段遮掉再数源码、或把可见文本跨标签拼接后再匹配定界符的检查器，看不见这两类缺陷，它报"全部通过"时只能说明它没查这些（见 5.5）。

工作流总览

① 准备  → 定位 PDF，建工作目录
② 提取  → 文本 + 按图注裁剪的图片 + 页面渲染图 + 表格清单
③ 翻译  → 逐节忠实翻译，公式保编号，表格全量转译
④ 校对  → 原译对照 / 术语 / 数字 / 条件与论断强度
⑤ 审查  → 逐字核对公式、图片、表格、翻译；自动验证；反复检查
⑥ 交付  → 图文 Markdown；可选离线自包含 HTML

① 准备

1. 定位 PDF 文件。
2. 建立独立工作目录（提取物与译文分开放，例如 out/、out/assets/、out/meta/）。
3. 确认依赖可用：python -m pip install pymupdf pymupdf4llm；需要 HTML 产出时在仓库根目录执行 npm install。

② 提取

python scripts/extract_pdf.py paper.pdf --out out/

得到 out/paper.md（文本基准）、out/assets/raw/（逐页 150 DPI 渲染图 + PDF 内嵌图片对象）、out/meta/（pages/figures/source 元数据）。

关键认识：PDF 中公式常是矢量或图片对象，文本层会丢公式、丢括号、丢上下标，甚至把 I 与 1 混淆。因此：

• paper.md 只作为翻译的文字基准；
• 公式的精确结构必须用页面渲染图逐字确认（见 ⑤）。

2.1 图片提取：按图注定位

规则：一张图的内容由它的图注（Fig. N）定义，而与 PDF 内嵌对象顺序无关。内嵌对象顺序既包含公式截图，也不保证与图号同序。

步骤：

1. 列出全文 Fig. 图注（页码 / 栏位 / y 坐标 / 文本），确定图总数 M：

   python scripts/extract_figs_by_caption.py paper.pdf --list

2. 每张图 = 同栏内、该图注上方、上一条图注下方的整块区域；有图像块时按图像块合并裁剪，矢量图/组合图时按栏内区间裁剪：

   python scripts/extract_figs_by_caption.py paper.pdf -o out/assets --dpi 300 --col-x 300 --pad 20

3. 两栏排版按图注 x 坐标判定栏位，左右栏各自裁剪；跨栏大图单独处理。
4. 逐张目视核对（用 Read 打开图片）：内容与 Fig. N 图注语义一致、图文完整无裁切（顶部/底部图例被切掉就调整边界重裁）。
5. 以图注为基准统计图总数 M，译文中的图片数必须等于 M；附录、分栏底部、跨页处的图容易漏。

2.2 表格提取：原文所有表格都要转译

1. 定位全文表格标题（常见形态 TABLE I、TABLE 1，含页码/栏位）。
2. 渲染每张表（600 DPI 左右）看清表头、全部行、数值、单位、符号上下标。
3. 每个表都完整转译为 Markdown 表格：表标题、列头、全部数值与单位、符号用行内公式。
4. 跨栏表在单页内也要按栏裁剪完整；跨页表把两页部分合并成一张表。
5. 只在正文写"见表 X"而不转译表格内容视为未完成。

③ 翻译

• 不含原文：输出纯中文翻译 + 公式 + 图片，不并列英文原文。
• 公式：每个公式用 $$...$$ 块级显示，\tag{N} 保留原文编号；行内符号用 $...$。
• 符号说明：变量符号首次出现处给出含义。
• 章节：保留原文章节结构（摘要 / 引言 / 各节 / 结论 / 附录），中文标题可附原文编号。
• 图片：按原文位置嵌入 assets/figN.png，图下方写"图 N"标题；figN.png 的内容必须与 Fig. N 图注一一对应。
• 表格：每个表用 Markdown 表格完整转译，放在正文引用处附近。
• 原文笔误：忠实保留原文写法，并在下方加 > 注释 说明疑似笔误与理由，不擅自"修正"。

④ 原译对照校对

核对段落覆盖、术语词义、否定与条件、数字单位及论断强度。review 仅指译文校对；默认不做论文精读、价值评价或研究建议。明确要求精读时由 paper-reading 单独交付。

⑤ 审查（必做，逐字核对）

同步执行 reference/verification-guide.md，并至少做两轮。

5.1 公式核对

文本层提取的公式不可信。必须：

1. 用 scripts/zoom_formula.py 定位公式行坐标并渲染 800–1600 DPI 裁剪图，肉眼逐字符确认；
2. 逐式比对译文公式与原文，记录差异；
3. 重点核对以下抽象要点（每一项都放大渲染图确认）：
   • 上下标归属：确认每个字符是下标、上标还是同行正常字号；下标与上标位置不同会改变符号含义，并用文中参数表交叉验证符号命名；
   • 分数 vs 加号：确认是否存在分数线、分子分母结构，避免把"加号 + 列向量"误读成分数，也避免把分数误读成并列项；
   • 函数自变量：确认自变量本身是否带导数点（形如 D(q) 与 D(\dot{q}) 是不同函数）；
   • 括号范围：[(I-a)b - ac] 与 [(I-a)(b-c)] 两种 LaTeX 语法都合法但语义不同——必须逐项确认减号两侧各被谁相乘。发现括号范围可疑时，用该公式下游推导式反推验证：把两种结构分别代入后续推导，能推出原文下一式的才是正确结构；
   • 多行共享编号：多行矩阵 / 方程组共用一个编号时，确认共享关系与原文一致，不得拆成 12a/12b；反过来，若原文自身就用子编号（如 (28a)–(28d)、(42a)/(42b)、(57a)–(57g)），必须照抄，不要"合并"成 (28)。编号只在共享块的末行出现一次——每行都写 \tag{N} 会让读者看到同一个编号重复渲染（实战中出现过 4 组）；用 \text{(28a)} 表示子编号时，只靠 \\tag\{(\d+)\} 统计会漏计，必须同时扫 \text{(…)}；
   • 跨页公式组：多式共用编号的公式组可能跨页（编号标注在末式），判定"原文没有此式"必须把编号所在页与其前一页的两栏全部渲染核对后才能下结论；
   • 不补写：原文未给出的公式（如未显式写出的矩阵）不得补写；确有合理补充必须加 > 注释：原文此处未给出…，此为译者补充。。

4. 渲染结果必须目视比对，不能只看有没有报错。 至少要有一次"把公式渲染出来、再和原文渲染图比"的动作：用无头浏览器加载交付 HTML，把每条公式渲染后的可见文本打出来（跳过隐藏的 MathML 副本），与原文同一条公式逐字符比。只看"KaTeX 错误数为 0"是不够的——错的数学可以完全静默：

   • 双反斜杠陷阱（实战）$\\|\bar{v}_L\\|$：本意是 $\|\bar{v}_L\|$，每个反斜杠都多写了一个。KaTeX 不报错，但 \\ 变成换行、\\bar 变成字面量 bar、| 变成单竖线，读者看到的是一个换了行的"单竖线 + bar + v_L + 单竖线"，而原文印的是双竖线范数 ∥v̄_L∥。修复要点：这类字符串写进 HTML 时隔着 Shell / Python / JS 多层转义，任何一层多写一个 \ 都会静默出错；改完必须读回文件按字符打印（repr()）确认，再渲染确认。
   • 单竖线 vs 双竖线：|x| 与 \|x\|（\Vert）渲染出的字符不同（单竖线 U+2223 vs 双竖线 U+2225）。核对范数时要比对渲染出来的码位，不能只看"有个竖线"。
   • 判定方法：无头浏览器加载页面后，把 document.querySelectorAll('.katex') 的可见文本（先移除 .katex-mathml 隐藏副本）导出成列表，与原文公式逐条比。实战就是这么发现"6 条公式、0 个错误、但 5 条数学是错的"。
   • 附带的同类陷阱：\mathrm、\left、\frac、\bar 等命令被多写一个反斜杠后，命令名会退化成字面量字母（x_{\mathrm{sym,th}} → xmathrmsym,th）。这类"命令变字母"的信号同样只能在渲染结果里看到。

发现错误后同步修改对应位置：译文正文及 HTML 内嵌公式源（<annotation encoding="application/x-tex">）——同一公式常在多处出现，必须一致。

5.2 图片-图注一致性核对（必做）

1. 列出论文全部 Fig. 图注（编号应连续 1..M）；
2. 列出译文全部"图 N"标题与引用的 assets/figN.png；
3. 逐一比对：数量相等、编号连续、图 N 标题语义与 Fig. N 图注一致；
4. 用 Read 逐张目视确认图片内容（而非只看文件名）；
5. 检查图片在文档中的出现顺序与图注编号顺序一致；
6. 同一图片文件不得被两次引用表示两张不同图（组合图要按边界拆成两幅）；交付 HTML 时直接按图片字节哈希比对——实战中出现过"公式 10 / 公式 12"两张图与"图 4 / 图 5"字节完全相同的情况，即两条公式从未显示过。一旦发现，要用原文 PDF 重新裁出真正的公式插入，而不是删掉重复那张；
7. 自动化辅助：

   python scripts/check_img_order.py out.html --expected 1,2,3,4,5
   python scripts/check_img_dims.py out.html
   python scripts/check_source_leaks.py out.html      # 含图片字节重复检测

5.2b 内嵌图裁图保真核对（交付 HTML 时必跑）

为什么单列一步：5.2 的字节重复检查只能抓"两个槽位装了同一张图"，看不见这三类缺陷——一张裁图里装了两幅图、原文的英文图注或译文自己的中文正文被烤进像素、槽位声明"公式 12"而图里印的是 (11)。它们骗得过语义配对，只有把每张内嵌图与原文 PDF 的区域逐张对位才会现形。实战一轮全量复核（24 篇、403 张图）查出 27 张 critical、65 张 major：Han2026「图 21」是一整条页面竖条，Passive_MPC「图 4」「图 5」共用一张整页裁图且中间夹着译文正文，PartialBiGrasp「图 12」干脆是 PDF 第 17 页的局部截图。

python scripts/check_crop_fidelity.py --html out.html --pdf paper.pdf --name Proj --out fidelity/
python scripts/check_crop_fidelity.py --selftest        # 自检

工具回答两个互相独立的问题，报告里分开列：

• 保真 FIDELITY：这张图是否忠实复制了它匹配到的 PDF 区域（缺墨 / 多墨 / 墨迹 IoU / 实心块 / 笔画丢失）；
• 对位 PLACEMENT：匹配到的区域是否就是槽位（alt 与邻近的「图 N / 公式 N」）声明的那个编号。

判读与修法：

1. 定位用 TM_CCOEFF_NORMED，别拿 SQDIFF 当搜索准则：低对比度模板对浅色背景的归一化平方差恒在最小尺度取最小，永远选错尺度；SQDIFF 只在相关性对齐之后再算，当报告值用。
2. 分档：SQDIFF ≤ 0.0003 干净、≤ 0.0092 轻微、≤ 0.16 可疑、> 0.16 非匹配。墨迹阈值按类型：公式条与线稿 5%，照片与渲染图 35%（照片类不跑实心块 / 笔画丢失检测，二值化本身不稳定）。
3. review 桶（相关系数 < 0.55）= 定位器没定下来，不是缺陷：必须人眼看证据图，既不能当"通过"，也不能当"不合格"。
4. 每条告警落到两种修法之一：重裁（按原文 300 dpi 只裁该图注 / 公式号定义的区域，图注文字、英文碎片、译文正文都不得留在像素里）或归位（把图换到它真正对应的槽位）。不许用"删掉重复那张"了事——公式会整条消失。
5. 重裁的公式图收尾时与原文 600 dpi 渲染做一次模板匹配：cc ≈ 1.000000、缺失 / 多余墨迹为 0，才算修好。
6. alt 写读者看得见的标签（图 3、公式 12、算法 1；原文未编号的写 公式（未编号）），不写素材路径（assets/eq1.png）——alt 会随图显示，也是对位检查器的判据。
7. 三类已知假阳性，先排除再动手（2026-09-13 全库复核的统计口径）：① 定位器对密集多行公式与表格常配错（配到插图或空白条带），这类条目的指标无意义——按声明槽位人工定位后再看；② 等式裁图若来自约 135–150 dpi 的重采样，细笔画变灰会触发 INK_MISSING / GLYPH_VANISHED / SOLID_BLOB，而"实心块"常是 = 的两横或大括号笔画——交付尺寸下仍可读就不算缺陷；③ 检查器给插图定义的是条带，会把相邻图的照片一并圈进去，于是把"复现了相邻图"报成 critical（实战：Zhao2024 图 9 被报成复现 Fig. 10，核实为误报）。判死只认三种：缺笔画导致读数错误、内容与槽位编号不符、两幅图同图。

5.2c 内嵌图“重影”核对（交付 HTML 时必跑）

为什么单列一节：5.2 的字节去重与 5.2b 的裁图保真都看不见它——重影是同一段字被画了两遍、错开一两像素（截图时页面被重绘或缩放两次），内容、编号、对位数全对，只有把每张内嵌图与原文 PDF 的同一区域做墨迹记账才会现形。实战一轮全库检查（24 篇、441 张内嵌图）据此修掉 93 张。

python scripts/check_image_ghosts.py --html out.html --pdf paper.pdf --out ghosts/
# 退出码 1 = 发现重影，可直接当闸门用

判据（用改前/改后两组真实样本标定，见 scripts/check_image_ghosts.py 顶部说明）：

1. 不能只用 mad（同尺度重建后的平均像素差）：不是同一渲染器出的图（无头浏览器按缩放截的）mad 天然 2–17、ink_iou 却 0.9+，并排看并没有重影；反过来，尺度集合里漏掉 0.25（= 600 dpi）会把一批高清图整批跳过。尺度用 med（像素差中位数）来选：定位正确时它恒为 ~0，与渲染方式无关；定位错误时它很大。
2. 真重影三项特征：ink_ratio ≥ 1.03（多出一层描边，可以到 2.6）、unexplained_rel ≥ 0.02（多出来的墨落在原文的空白处）、vanished_rel ≈ 0（只多不少；若是“定位差一两像素”或“另一套渲染器”，vanished 会与 unexplained 同量级）。
3. 定位闸门：med ≤ 2 且 ink_iou ≥ 0.30 且定位区域内墨迹 ≥ 200 px，才算“判得下来”。三条不满足的记为 unverified——既不算通过、也不算缺陷，多为白底折线图或早期流水线的图（模板匹配会配到空白处）。实战 441 张里 147 张属这类，抽查 16 张目视全部干净，可直接看图（embedded | 干净渲染 | 差值）。
4. 修法只有一种：在原 PDF 里定位同一区域，按 2 倍像素重裁，并在 style 里写死 width:原像素宽——显示尺寸与版面一律不动。收尾复核：被换的图恰好 2 倍像素、是 PNG、<img> / <table> / data: 的个数一个不变，HTML 文字层（去掉 --- 后）与改前逐字相同、PDF 全文 span 只少掉那些 ---。
5. 重影与 --- 常同时出现在同一批文件里；两者都要顺手清（见 5.3）。

5.3 表格核对

提取原文全部表格标题，与译文中的 Markdown 表格一一比对：数量相等、表头一致、每行数值与单位一致、符号上下标一致；正文"见表 X"必须伴随实际表格。Markdown 表格的分隔行（|---|）不得进入交付件：它转成 HTML 后是读者可见的 <td>---</td>（实战一份 3 行 26 格），必须删掉分隔行并把"指标行"并入表头（rowspan / colspan），最后确认表头每一行的格数与数据行逐列对齐。

5.4 自动验证

# 结构兜底：编号齐全、$$/$ 配对、无 \( 残留、括号与环境配对、图片一一对应、关键式存在
python scripts/verify_translation.py translation.md \
  --max-eq 38 --assets-dir assets --expect-imgs 15 \
  --section "## 摘要" \
  --key 'J_i^{-T}u_i' --check-english

# 公式语法：逐条用 KaTeX 渲染，列出失败公式（真实语法错误，不是"看起来像"）
node scripts/verify_katex_md.js translation.md

5.5 HTML 交付件源码级复查（产出 ⑥-B 离线 HTML 时必跑）

为什么单列一步：3～5.4 各步查的是译文内容，5.6 查的是渲染是否重叠。但交付的 HTML 里 还可能出现"内容都对、读者却看到源代码"或"公式渲染了、但数学是错的"的情况，而且在 Markdown 阶段完全查不出来——Markdown 里 $...$ 就是数学，转成 HTML 后能不能渲染取决于 页面自己的定界符配置。实战中一次归档 27 份 HTML，有 12 份栽在这一类问题上，其中 7 份共 1110 处行内公式以源码形式显示；修完之后又漏掉两类：双反斜杠把公式渲染成错的数学 （KaTeX 不报错，见核心原则 6）与定界符被行内标签切开的公式碎片。

python scripts/check_source_leaks.py out.html
python scripts/check_source_leaks.py --dir out/            # 递归
python scripts/check_source_leaks.py --selftest            # 改过本脚本后必跑：坏样本必须报错、好样本必须通过

逐项判死（任一不为零即不合格）：

1. 未配对的定界符：该页 delimiters 里配置的 $、\(、\[ 在某个文本节点里没配成对。
2. 正文里的 LaTeX：非数学文本里残留 \xi、\frac、\| 这类命令。
3. 双反斜杠命令（\\bar、\\|、\\mathrm、\\frac）：单个反斜杠被写成两个。矩阵 / 数组 / cases / aligned 环境里 \\ 是换行符，属正常，检查器已按环境排除；其余位置 一律算错，因为它渲染成"换行 + 字面量"而不是命令。
4. 正文里的上下标：非数学文本里残留 _{…} / ^{…}（公式被切断后最常见的残骸）。
5. 定界符 / 公式被行内标签切断：把相邻两个文本节点带着边界标记拼起来再匹配一遍， 若匹配结果与逐节点匹配不同，说明这段公式只有在标签消失时才能渲染——读者实际看到的是 碎片。
6. 不可能成形的数学 span：花括号 / 圆括号 / 方括号不配对，或 \left 没有 \right。 这类 span 一定是从一条更长公式里截出来的。
7. 正文里成对的 _…_（Markdown 斜体记号残留）：_全局精修_、_ContactGraspNet + 配对_、 _DAGDiff_ 都是这一类的典型形态，读者看到的是下划线而不是斜体。判定要看配对： 论文自身的标识符只有一个、没有配对的下划线（right_real、teleop_default、 github.com/user/repo_name、公式记法 α_min/h_global/x_ref/lim_(t→∞)）， 属词内下划线，只进报告项，不算缺陷（细节与误报分析见脚本头部与陷阱清单第 24 条）。
8. 正文里成对的 ~~…~~（Markdown 删除线残留）：right ~~r~~ eal 这种把论文自身标识符 拆开的写法最典型。
9. 图片标签后多出的 >：<img …>>。构建工具留下的这个字符会被浏览器当作正文文本 节点渲染出来，读者在图后面看到一个多余的尖括号。别只看源码——无头浏览器里遍历 文本节点确认它真的在正文里（实战 8 份交付件、共 104 处）。
10. 图注编号不递增 / 重复：按文档顺序抽图注编号（图 N 出现在图片之后那一块的行首， 接标点或短文本才算图注），若出现 … 图 12 → 图 11 … 就是装订顺序错了；同一编号出现 两次也算。
11. 正文泄漏内部工作路径：_extracted…、assets/raw、G:\、/mnt/、_work\、 _fixwork、_bak_fix。这类字样出现在读者可见的正文（含 <code>）里，等于交付件里 夹了自己的中间产物路径。
12. Markdown 残留：**粗体**、_斜体_、段首的 > 引用记号。
13. KaTeX 解析失败回退：<span class="katex-error">，读者看到的是红色源码而不是公式。
14. 同一张图被两个不同标签引用：按图片字节哈希比对，能直接抓出"公式图其实是一张论文图" 这类图注错位。
15. 外链与非内嵌图片：自包含被破坏。

报告项（单独列出、不计入"不合格"，因为检出依赖启发式，需要人工确认）：

• 正文引用了、但没有对应图注的图号（会列出号码，如 图 6）。这一项必须人工复核： 图注写在图片旁边之外的形状（公式图、表格上方的图、长图注）会被漏认——实战里 图 19 双臂机器人运动构型。(a) … 这种长图注就会被漏掉，而它其实在文档里。
• 整篇没有 参考文献 / REFERENCES 章节（实战：一份交付件 39 条文献与全部正文引用 标记一起消失）。
• 参考文献 标题下只有译者占位说明（如"（参考文献保持原文，见下方原文清单）"）， 没有真正的文献条目。注意区分译者说明 + 真条目（那种不算缺陷）。

三条必须记住的边界：

• 判"渲染了没有"必须按该页自己的配置来：用 renderMathInElement 的 delimiters 决定哪些 定界符真的会被处理；页面上写了 \(...\) 不等于会渲染。没有客户端渲染的预渲染页面（只有 katex-html 或 annotation）则任何定界符都不会被处理。
• 检查器的盲区不是覆盖率。反面教材（旧版 check_source_leaks.py 就是这么写的）： ① 在配了 $ 的页面上把 $…$ 整段遮掉再数剩下的源码——那么"公式体里写错了什么" 永远查不到，上面的第 3、6 项必然漏报；② 把可见文本跨标签直接拼接再匹配定界符—— 拼接本身就把标签边界抹平了，第 5 项必然漏报。新版按页面自己的 auto-render 算法逐文本节点 匹配定界符（splitAtDelimiters / findEndOfMath 的等价实现，已用交付件内嵌的 bundle 逐节点 比对验证），并逐条读公式体做体检。换检查器/改检查器之后，必须拿"已确认有缺陷的旧版本" 回归一遍：如果新旧版本对同一份坏文件都报通过，说明新检查项根本没生效。
• 每个新检查项都要配一个"必须通过"的反例样本。加检查项本身不难，难的是不误报： 实战中"下划线配对"这条规则先写成"任何非词内下划线都算"，结果把公式记法 α_min、lim_(t→∞)、Σ_(n=1)^N 全报成了强调残留；把配对内容里带 ()[]{}=<>^ 的 排除掉才收敛。改完规则先跑一遍全语料库，看新报出来的东西是不是同一个成因； 不能解释的先别急着判死，它们多半是启发式的边界，不是缺陷。--selftest 里因此同时 保留了"缺陷样本"和"合法样本"两类 fixture。

5.6 翻译核对

逐段比对 PDF 文本层与译文：数字、单位、参数、实验条件、引文编号、专有名词。

5.7 反复检查

修正后重跑 5.4 与 5.2（产出 HTML 时连同 5.5）；若要求"反复检查"，至少三轮：初查 → 修正 → 复查 → 再修正 → 终查。每一轮都重跑自动验证，直到 0 问题。

⑥ 交付

产出 A：图文 Markdown（默认）

translation.md + assets/ 图片目录，相对路径引用。需要单文件分发时内嵌图片：

python scripts/md_self_contained.py translation.md --out translation_one_file.md

产出 B：离线自包含 HTML（需要公式排版 / 单文件分发时）

python scripts/build_html.py translation.md out.html     # KaTeX 预渲染 + 字体/图片 base64 + 编号防重叠
python scripts/check_all_html.py out.html                # 全量复查：重叠/图片/渲染残留
python scripts/check_source_leaks.py out.html            # 源码级复查：定界符/公式体/双反斜杠/正文 LaTeX 与上下标 + Markdown 残留 + 图片旁尖括号 + 图注顺序 + 内部路径 + 参考文献
python scripts/headless_check.py out.html                # 单文件快速体检

构建 HTML 时必须一并确认的四件事（第 5.5 步的工具会替你查）：

• 定界符一致性：build_html.py 走 KaTeX 预渲染时，页面文本里若还留着 \(...\)（例如译文素材混用了两种行内写法），必须全量转成 $...$ 再构建，否则预渲染器与浏览器都不会处理它们，读者直接看到源码。
• 不要把定界符与公式体拆到不同块级元素里：<p>$$</p><p>公式</p><p>$$</p> 这种写法，auto-render 在单个文本节点内匹配定界符，跨元素一定匹配不到；显示公式必须写成同一个 <p>$$…$$</p>。同理，行内公式不要跨 <em>/<strong>/<sup> 等行内标签断开。
• 写进 HTML 的 LaTeX 只允许单反斜杠：\|\bar{v}_L\| 是对的，$\\|\\bar{v}_L\\|$ 是错的——后者每个反斜杠都多了一个。KaTeX 对后者不报错，只是渲染成"换行 + 字面量 bar + 单竖线"。原因是这类字符串要穿过 Shell → Python → HTML/JS 多层转义，任何一层多写一个 \ 都会静默出错。所以写完后必须读回文件按字符确认（见 reference/verification-guide.md 陷阱清单第 21 条），并做一次渲染目视比对（5.1 第 4 条）。
• 结构类残渣同样要在交付件上查：Markdown 强调记号残留（成对的 _…_、~~…~~）、图片标签后多出的 >、图注编号顺序、正文里的内部工作路径、参考文献章节是否存在——这些都不是"渲染问题"，而是构建/翻译过程漏改的痕迹，只有对最终 HTML 才查得出来（见 5.5 与陷阱清单第 24–27 条）。

HTML 的修复与归档工具：

python scripts/fix_overlap.py out.html     # 编号压公式：追加覆盖 CSS（幂等）
python scripts/fix_wide.py out.html        # 超宽公式：注入自适应缩放脚本（幂等）
python scripts/sync_zotero.py out.html --target-dir <DIR>
python scripts/sync_zotero.py out.html --zotero-storage <ZOTERO_STORAGE> --key <ATTACHMENT_KEY>

附加资源

• 审查方法论与命令清单：reference/verification-guide.md
• 提取：scripts/extract_pdf.py（文本+页面图+图片对象）、scripts/extract_figs_by_caption.py（按图注裁剪）、scripts/ocr_formula.py（公式截图 OCR 辅助）
• 核对：scripts/zoom_formula.py（公式高清渲染）、scripts/verify_translation.py（文档结构验证）、scripts/verify_katex_md.js（公式语法验证）、scripts/check_source_leaks.py（交付 HTML 源码级复查，--selftest 可自检）
• HTML：scripts/md_self_contained.py（图片内嵌 Markdown）、scripts/render_body.js（Markdown→KaTeX 静态 HTML）、scripts/md_to_offline_html.js（Node 一键自包含 HTML）、scripts/build_html.py（Python 一键构建）、scripts/vendor_katex.py（导出 KaTeX 离线资源）
• 检查：scripts/check_source_leaks.py、scripts/fix_overlap.py、scripts/fix_wide.py、scripts/check_img_order.py、scripts/check_img_dims.py、scripts/headless_check.py、scripts/check_loaded_all.py、scripts/check_all_html.py
• 归档：scripts/sync_zotero.py