latex-compile-qa

LaTeX 编译与 QA

触发条件与路由

• 触发条件：latex 编译、构建 PDF、LaTeX 错误、缺失引用、编译PDF、引用错误。
• 适用场景：已有 latex/main.tex（通常来自 latex-scaffold），需要确认可以编译，并输出失败原因报告。

编译 LaTeX 项目并生成 PDF（如果工具链可用），同时提供简短的构建报告。

此步骤具有确定性；如果编译失败，请记录可执行的诊断信息，而不是猜测原因。

输入

• latex/main.tex
• citations/ref.bib

输出

• latex/main.pdf（如果编译成功）
• output/LATEX_BUILD_REPORT.md（推荐）

工作流

1. 运行 LaTeX 构建（例如，使用 latexmk），如果该工具可用。
2. 修复缺失的宏包、缺失的 bib 条目以及未解析的引用。
3. 在构建报告中记录剩余问题。

质量检查清单

• 仅当编译成功时，latex/main.pdf 才会存在；构建失败时必须删除过时的 PDF，并在 output/LATEX_BUILD_REPORT.md 中说明失败原因。
• 对于 arxiv-survey-latex 交付物：latex/main.pdf 页数不少于 8 页，且没有未定义的引用/参考文献（严格门槛）。

脚本

快速开始

• uv run python .codex/skills/latex-compile-qa/scripts/run.py --help
• uv run python .codex/skills/latex-compile-qa/scripts/run.py --workspace <workspace>

所有选项

• 请参阅 --help（通过管道使用时，输入/输出由单元运行器提供）

示例

• 编译并生成报告：
  • uv run python .codex/skills/latex-compile-qa/scripts/run.py --workspace <workspace>

备注

• 如果可用，将使用 latexmk -xelatex -bibtex。
• 无论成功还是失败，都会写入 output/LATEX_BUILD_REPORT.md。
• 报告会在可用时包含页数和警告摘要。

故障排除

常见问题

问题：找不到 latexmk

症状：

• 构建报告显示“latexmk not found in PATH”。

原因：

• 未安装 LaTeX 工具链。

解决方案：

• 安装包含 latexmk 的 TeX 发行版。
• 如果无法安装工具，仍可使用 latex-scaffold 生成 latex/main.tex，然后在其他环境中编译。

问题：构建因 bib/ref 错误失败

症状：

• 报告显示缺失的引用/参考文献或 BibTeX 错误。

原因：

• citations/ref.bib 缺失或配置错误，或者草稿包含无效的引用键。

解决方案：

• 确保 latex/main.tex 指向 ../citations/ref.bib（或正确的相对路径）。
• 确保所有引用键都存在于 citations/ref.bib 中。

恢复检查清单

• 阅读 output/LATEX_BUILD_REPORT.md 末尾部分，查找第一个可执行的错误。
• 确认 latex/main.tex 存在且参考文献路径正确。