AgentSkillsCN

latex-compile-qa

编译 LaTeX 项目并运行基础 QA（检查缺失引用、BibTeX 错误、失效引用），生成 `latex/main.pdf` 文件与构建报告。 **触发条件**：LaTeX 编译、PDF 构建、LaTeX 错误、缺失引用、编译 PDF、引用错误。 **适用场景**：当你已拥有 `latex/main.tex` 文件（通常源自 `latex-scaffold`），并希望确认其可编译性，同时输出失败原因报告时。 **跳过条件**：若尚未搭建 LaTeX 脚手架（请先运行 `latex-scaffold`）。 **网络要求**：无需联网。 **防护措施**：即使编译失败，也需将结果记录至 `output/LATEX_BUILD_REPORT.md` 文件；不做“内容改写”，仅进行编译与 QA。

SKILL.md
--- frontmatter
name: latex-compile-qa
description: |
  Compile a LaTeX project and run basic QA (missing refs, bib errors, broken citations), producing `latex/main.pdf` and a build report.
  **Trigger**: latex compile, build PDF, LaTeX errors, missing refs, 编译PDF, 引用错误.
  **Use when**: 已有 `latex/main.tex`（通常来自 `latex-scaffold`），需要确认可编译并输出失败原因报告。
  **Skip if**: 还没有 LaTeX scaffold（先跑 `latex-scaffold`）。
  **Network**: none.
  **Guardrail**: 编译失败也要落盘 `output/LATEX_BUILD_REPORT.md`；不做“内容改写”，只做编译/QA。

LaTeX Compile + QA

Compile the LaTeX project and produce a PDF (when the toolchain is available), plus a short build report.

This step is deterministic; if compilation fails, record actionable diagnostics rather than guessing.

Inputs

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

Outputs

  • •latex/main.pdf (if compilation succeeds)
  • •output/LATEX_BUILD_REPORT.md (recommended)

Workflow

  1. •Run a LaTeX build (e.g., latexmk) if available.
  2. •Fix missing packages, missing bib entries, and unresolved references.
  3. •Record remaining issues in a build report.

Quality checklist

  • • Either latex/main.pdf exists, or output/LATEX_BUILD_REPORT.md explains why compilation failed.
  • • For arxiv-survey-latex deliverables: latex/main.pdf is >= 8 pages and has no undefined citations/references (strict gate).

Script

Quick Start

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

All Options

  • •See --help (inputs/outputs are taken from the unit runner when used via pipeline)

Examples

  • •Compile + produce report:
    • •python .codex/skills/latex-compile-qa/scripts/run.py --workspace <ws>

Notes

  • •Uses latexmk -xelatex -bibtex when available.
  • •Always writes output/LATEX_BUILD_REPORT.md (success or failure).
  • •Report includes page count + warning summary when available.

Troubleshooting

Common Issues

Issue: latexmk not found

Symptom:

  • •Build report says “latexmk not found in PATH”.

Causes:

  • •LaTeX toolchain is not installed.

Solutions:

  • •Install a TeX distribution that includes latexmk.
  • •If you can’t install tools, still use latex-scaffold to generate latex/main.tex and compile elsewhere.

Issue: Build fails with bib/ref errors

Symptom:

  • •Report shows missing citations/refs or BibTeX errors.

Causes:

  • •citations/ref.bib missing/miswired, or draft contains invalid cite keys.

Solutions:

  • •Ensure latex/main.tex points to ../citations/ref.bib (or the correct relative path).
  • •Ensure all citation keys exist in citations/ref.bib.

Recovery Checklist

  • • Read output/LATEX_BUILD_REPORT.md tail for the first actionable error.
  • • Confirm latex/main.tex exists and bibliography path is correct.