Latex Compilation Troubleshooting

` (em-dash)

• ≤ → $\leq$
• ≥ → $\geq$
• 或者在preamble添加：\usepackage[utf8]{inputenc}（但某些字体仍不支持）

Environment algorithmic undefined

• 根因：algorithmic包与elsarticle不兼容或加载失败
• 解决：直接删除algorithmic环境（论文通常不需要），或改用algorithm2e包
• 检查：\usepackage{algorithmic}在preamble中的位置是否正确

B. Natbib/Undefined Citations (警告)

Package natbib Warning: Citation `xxx' undefined

• 根因：bibtex未执行或引用缺失
• 修复流程：pdflatex → bibtex paper → pdflatex → pdflatex
• 检查：paper.bbl是否生成（0字节=失败）
• 检查：paper.blg是否有"0 warnings"
• 如果仍有未定义：检查.bib文件中bibkey是否在.tex中被\cite{}引用

C. Reference Errors

Missing \begin{document} after graphicspath fix

• 根因：正则替换{{figures/}},{pics/}}时括号不匹配，导致LaTeX解析器在preamble中找到未闭合括号
• 修复：\graphicspath{{05-figures/}} 确保外层{}匹配

3. 修复验证

# 编译测试
rm -f paper.*
pdflatex -interaction=nonstopmode paper.tex 2>&1 | grep '! LaTeX Error'
grep -c 'undefined' paper.log

# 如果0错误且0未定义引用 → 成功
# 如果有错误 → 继续修复并重复

4. 安全守则（铁律）

操作前必须备份：\nbash\ncp paper.tex paper.tex.bak.{timestamp}\n# 或在修改前创建 .bak 文件\n\n\n**🔴 绝对禁止 rm -f paper.* 通配符删除**：\n- paper.* 通配符会匹配 paper.tex（因为 .tex 以 .t 开头，匹配 *）→ 已发生 2026-06-15 事故：一次性删除了完整论文源文件\n- 只能删除已确认生成的辅助文件：rm -f paper.aux paper.log paper.out paper.blg paper.bbl paper.pdf\n- 删除前用 ls paper.* 确认列表中不含 paper.tex

• 任何批量操作（replace/patch）前必须创建 .bak 备份

批量修改后验证：

• 每次 replace 或 patch 后，立即检查关键部分是否被正确修改
• 编译测试是最快的验证方式

陷阱

Highlignts环境: \\begin{highlights} 是 elsarticle 的扩展环境，需要 elsarticle-harvard.sty。默认安装的 elsarticle 不支持。如果报错 Missing \\item 且发现 highlights，改为 \\begin{itemize}。

D10a 验证 — .bbl 权威来源：\n- 对于使用外部 .bib + \\bibliography{} 的论文，D10a 必须从 .bbl 文件验证，而非从 .bib 扫描\n- .bbl 包含 bibtex 实际解析出的 bibitem keys，是最权威来源\n- 验证方法：re.findall(r'\\bibitem\{([^}]*)\}', bbl_content) → 得到确定的 bibitem 集合\n- 然后用 grep -oP '\\\\cite{[^}]+}' paper.tex | sort -u 对比 cite keys\n- 常见陷阱：\\cite{daugman2001statistical, bowyer2008image} 在注释行（%% 开头）中，bibtex 忽略注释 → D10a 不增加 → 必须将引用移至正文

• equation in enumerate: LaTeX 不允许浮动环境（equation, figure, table）嵌套在 enumerate/itemize 的 item 中。修复方法：将 equation 移到 enumerate 外面，或使用 minipage 包裹。

enumerate[nosep] error: \\begin{enumerate}[nosep] 中的 nosep 选项来自 enumitem 宏包。elsarticle 等标准文档类不自动加载 enumitem。修复：去掉 [nosep] 使用默认间距，或在导言区添加 \\usepackage{enumitem}。

Table 最后一行缺 \\ 导致 \bottomrule 级联错误 🔴 NEW 2026-06-29 — HCS-3WT

• 根因：tabular 中最后一行数据（在 \bottomrule 之前）缺少行尾 \\。LaTeX 将 \bottomrule 视为新的行内容但当前行未正确结束 → ! Misplaced \noalign + ! Missing } inserted + 级联 ! Missing \cr inserted（100+ 错误）。
• 症状：错误集中在 l.203 } 附近，大量 ! Misplaced \cr 和 ! Missing \cr inserted。
• Detection：grep 表中最后一行数据（在 \bottomrule 前一行）是否以 \\ 结尾：grep -B1 '\\\\bottomrule' paper.tex。最后一行应以 \\ 结尾。
• Fix：在最后一行数据末尾添加 \\。例如：FN reduction vs. best single & $-38.7\\%$ & -- \\\\。
• 铁律：每次 patch 修改表格后，必须检查 \bottomrule 前一行的 \\ 存在性。

verbatim inside \fbox{}: LaTeX 的 verbatim 环境不能放在 \fbox{...} 的参数内部。\fbox 在读取参数时已经改变了 catcode，导致 \begin{verbatim} 无法正确激活逐字模式。修复：移除 \fbox{} 包裹，仅保留 minipage 环境。例如将 \fbox{\begin{minipage}...\begin{verbatim}...\end{verbatim}\end{minipage}} 改为 \begin{minipage}...\begin{verbatim}...\end{verbatim}\end{minipage}。

• Unicode in LaTeX: 即使添加了 inputenc，某些 Unicode 字符（如 ≈ →）仍需手动替换为 LaTeX 命令。
• graphicspath bracket matching: \graphicspath 需要双花括号 {{path/}}。替换时如果原始路径包含多个目录（如 {{figures/},{pics/}}），正则替换必须确保括号配对正确。
• Algorithmic package compatibility: algorithmic 包在某些环境下（如 elarticle + MiKTeX特定版本）可能与 preamble 中的其他宏包冲突。如果报错 algorithmic undefined，直接删除算法环境是最安全的修复方式。
• Backup-before-destructive: 任何涉及 rm、cp、或批量 replace 的操作前，必须备份原始文件。paper.* 通配符会匹配 paper.tex。
• State-score staleness: paper-repair cron 生成的 state.json 可能包含过期的 quality_score。修复流程：先检查 quality-report.md 提取 Layer B 分数，用该分数更新 state.json。如果 quality_score >= 80，gate_status 改为 PASS，stage 改为 quality_check_complete。

External .bib with \bibliography{} — required workflow 🔴 2026-07-01 — HCS-3WT

• 根因：删除内嵌 thebibliography 后改用外部 .bib，缺少 \bibliographystyle{plain} 导致 bibtex 执行失败（"I found no \bibstyle command"）。
• Fix：在 \bibliography{references} 之前必须加 \bibliographystyle{plain}。完整流程：pdflatex → bibtex paper → pdflatex → pdflatex。
• 路径陷阱：.bib 文件必须与 .tex 在同一目录（BibTeX 使用相对路径）。如果 bib 在 06-references/ 而 tex 在 01-manuscript/，bibtex 会找不到文件。将 .bib 复制到当前目录。
• 验证：编译后检查 paper.bbl 中的 \bibitem 计数是否等于论文中 \cite{} 的唯一 key 数。

+BibTeX "didn't find database entry" for specific entries — don't blame the entries, blame the file 🔴 2026-07-01

• 根因：当 BibTeX 报告特定条目"找不到"（"I didn't find a database entry for X"），但条目在 .bib 文件中存在且语法正确时，问题通常不在这些条目本身，而是文件中某个更早位置的格式错误（花括号不匹配、未闭合、特殊字符等）导致 BibTeX 解析提前失败，跳过了后续条目。
• Debug 流程：
  1. 用 hexdump -C 检查条目字节，确认无不可见字符
  2. 用 grep -cP '{' / grep -cP '}' 检查花括号平衡
  3. 将嫌疑条目提取到独立文件，用最小化 tex 编译测试：如果独立文件成功 → 原文件中有其他条目导致解析失败；如果独立文件也失败 → 条目本身有问题
  4. 如果独立测试成功但原文件失败 → 逐个注释掉原文件中其他条目，逐步缩小问题范围
• 铁律：BibTeX 对错误条目报 "didn't find" 而非 "illegal character"，容易误导。当多个条目同时"找不到"时，优先怀疑文件结构而非条目内容。

+Crossref 作者格式差异 🔴 2026-07-01 — BPPV

• 根因：Crossref API 返回作者有两种格式：格式1 given/family（个人作者），格式2 name（机构作者）。解析时必须同时处理两种格式，否则机构作者的姓名会丢失。
• 示例：机构作者返回 {"name": "Education Directorate Of Thi-Qar, Ministry Of Education, Iraq"}，given/family 均为空。
• Fix：解析时优先取 given+family，若无则取 name，再无则跳过。

参考文件

• ref/latex-error-checklist.md — 完整错误分类速查表
• ref/paper-compile-checklist.md — 每次编译前检查清单
• references/symlink-path-trap-01-manuscript.md — 01-manuscript/ 符号链接路径陷阱（2026-06-18 实战）
• scripts/latex-auto-fix.py — 自动检测和修复常见LaTeX错误的脚本

契约层 · BOUNDARY

边界：技能功能边界。

契约层 · IO_CONTRACT

输入：请求描述、上下文信息。 输出：执行结果、状态反馈。

验证清单 · VERIFICATION

• 任何批量 replace/patch 或 rm 操作前已创建带时间戳的 .bak 备份，未使用 paper.* 通配符删除
• Citation undefined 已执行完整编译链 pdflatex → bibtex → pdflatex → pdflatex，且 paper.bbl 非空、paper.blg 显示 0 warnings
• 外部 .bib 场景：\bibliography{} 前已添加 \bibliographystyle{plain}，且 .bib 与 .tex 在同一目录
• 表格 \bottomrule 前一行以 \\ 结尾，未出现 Misplaced \noalign 或级联 Missing \cr 错误
• 修复验证：pdflatex -interaction=nonstopmode 编译后 ! LaTeX Error 计数为 0，grep -c 'undefined' paper.log 为 0
• 不兼容环境已处理：algorithmic undefined → 删除环境或改用 algorithm2e；enumerate[nosep] → 添加 \usepackage{enumitem} 或去掉选项
• D10a 引用完整性以 .bbl 中 \bibitem keys 为权威来源验证，而非扫描 .bib

核心原则 · PRINCIPLES

1. 准确为先: 所有输出必须经过事实核查，不编造数据
2. 证据驱动: 每个结论必须可追溯到具体证据或数据源
3. 可复现性: 每一步操作必须可重复，结果可验证

Golden 集合 · GOLDEN SET

• Golden Input: 一篇使用外部 references.bib（与 paper.tex 同目录）的 elsarticle 论文，preamble 已含 \bibliographystyle{plain}，触发条件：首次 pdflatex 后 paper.log 出现 Package natbib Warning: Citation 'xxx' undefined
• Golden Output: 执行 pdflatex → bibtex paper → pdflatex → pdflatex 完整链后，paper.bbl 非空且 paper.blg 显示 0 warnings；pdflatex -interaction=nonstopmode 重编译后 ! LaTeX Error 计数为 0、grep -c 'undefined' paper.log 为 0
• Golden Error: paper.bbl 为 0 字节或 bibtex 报 I found no \bibstyle command → 判定缺失 \bibliographystyle{plain}（而非 bib 条目问题）；BibTeX 报 "didn't find a database entry for X" 但条目存在 → 判定 .bib 文件早期花括号不匹配，用独立文件最小化编译定位，不修改"嫌疑"条目本身

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反任何原则的输出视为失败。原则优先级：准确 > 证据 > 可复现。 每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Latex Compilation Troubleshooting---

(P032 去重: 以下为合并前第二份中的 1 行独有内容, 保留以防丢失)

Latex Compilation Troubleshooting

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [LATE-001] 遇到 Citation undefined 警告 → 执行 pdflatex → bibtex → pdflatex → pdflatex 完整编译链并检查 .bbl 文件非空
• [LATE-002] 执行任何批量修改或 rm 操作前 → 必须创建带时间戳的 .bak 备份，且严禁使用 paper.* 通配符删除以防误删源文件
• [LATE-003] 出现 Misplaced \noalign 或大量 Missing \cr 级联错误 → 检查表格 \bottomrule 前一行是否缺失行尾 \\ 并补全
• [LATE-004] BibTeX 报告特定条目 "didn't find database entry" 但条目存在 → 优先排查 .bib 文件早期位置的花括号不匹配或格式错误，而非怀疑条目本身
• [LATE-005] 使用外部 .bib 文件时 bibtex 执行失败 → 确保 .bib 与 .tex 同目录，且在 \bibliography{} 前添加 \bibliographystyle{plain}
• [LATE-006] 遇到 algorithmic undefined 或 enumitem 选项报错 → 直接删除不兼容环境/选项，或改用 algorithm2e 包/添加 \usepackage{enumitem}
• [LATE-007] 验证引用完整性时 → 以 .bbl 文件中解析出的 \bibitem keys 为权威来源，而非直接扫描 .bib 文件