latex-scaffold

LaTeX 项目骨架

触发条件与路由

• 触发词：latex scaffold、md→tex、LaTeX 项目骨架、生成 main.tex。
• 适用场景：需要交付 LaTeX/PDF（例如 arxiv-survey-latex pipeline），且草稿已生成/已进入写作阶段。

将已批准的 Markdown 草稿转换为最精简且可构建的 LaTeX 项目。

这是一个确定性的转换步骤；正文质量应已在 output/DRAFT.md 中处理完毕。

输入

• output/DRAFT.md 或 output/TUTORIAL.md
• 可选：citations/ref.bib

输出

• latex/main.tex（以及任何必需的 LaTeX 支持文件）

布局策略

机器可读的布局约定位于 assets/layout_profiles.json。 默认配置使用 1in 的 A4 页边距，包含目录，并且可以拆分较大的表格。受限的 course_paper 配置使用文档说明的 0.9in A4 页边距，不包含目录，并在可能时保留紧凑表格的完整性，且仅将参考文献设为 \small。正文保持 11pt。 此配置旨在满足明确的页数范围，而非通过缩小论文来制造实质上的完整性。

工作流

1. 如果 latex/ 目录不存在，则创建该目录。
2. 创建 latex/main.tex，其章节应与大纲一致。
3. 如果 citations/ref.bib 文件存在，则将参考文献与其关联。

质量检查清单

• latex/main.tex 存在。
• 如果 citations/ref.bib 存在，latex/main.tex 会引用它。

脚本

快速开始

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

所有选项

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

示例

• 从 output/DRAFT.md 或 output/TUTORIAL.md 构建 latex/main.tex：
  • uv run python .codex/skills/latex-scaffold/scripts/run.py --workspace <workspace>

说明

• 为便于阅读，生成的 latex/main.tex 包含目录（tocdepth=2）。
• 根据 assets/layout_profiles.json，course_paper 配置不包含目录；其他配置默认包含目录。
• 默认语言：项目骨架使用 article（外观偏英语的前置部分）。如果草稿包含 CJK 字符，则会切换为 ctexart，以确保 PDF 正确渲染。
• 转换规则（概述）：
  • 标题 ##/###/#### → \section/\subsection/\subsubsection（去掉 1.2 等开头的数字前缀）。
  • 以 Appendix / 附录 开头的标题会触发一次 \appendix，之后按附录章节渲染。
  • 紧邻 Markdown 表格之前的粗体标题行（如 **Table 1. ...** / **Appendix Table A1. ...**）会转换为带有 \caption{...} 和稳定 \label{tab:...} 的 LaTeX table 浮动体。
  • ## Abstract → abstract 环境。
  • [@Key] 或 [@Key1; @Key2] → \citep{Key} / \citep{Key1,Key2}。
  • 行内 Markdown **bold** / *italic* / `code` → \textbf{} / \emph{} / \texttt{}。

故障排查

问题：生成的 latex/main.tex 仍包含 Markdown 标记

解决方法：

• 重新运行 latex-scaffold，并确保输入的 output/DRAFT.md 格式干净（不含 ##、** 或未处理的 [@...] 语法）。

问题：LaTeX 中缺少引用

解决方法：

• 确保 citations/ref.bib 存在，且项目骨架将参考文献指向该文件；然后使用 latex-compile-qa 进行编译。