latex-document-skill

LaTeX 文档技能

创建任意 LaTeX 文档、编译为 PDF，并生成 PNG 预览。将任意类型的 PDF 转换为 LaTeX。

工作流：创建文档

1. 确定文档类型（简历、报告、信函、发票、文章、论文、学术 CV、演示文稿、海报、考试材料、书籍、速查表）
2. 如果目标是 IEEE 期刊／Transactions／IEEE 双栏论文： 选择模板前，先阅读 references/ieee-journal-twocolumn-guide.md。从 examples/ieee-twocolumn-sample.tex 开始，使用可运行的 IEEEtran 基础模板，并将 examples/ieee-twocolumn.png／examples/ieee-twocolumn-p1.png／examples/ieee-twocolumn-p2.png 作为视觉参考。
3. 如果是海报： 运行海报子工作流（见下方的 海报子工作流），然后跳至第 5 步。
4. 如果是速查表／参考卡片： 运行速查表子工作流（见下方的 速查表／参考卡片子工作流），然后跳至第 5 步。
5. 询问用户希望添加哪些丰富元素（使用 AskUserQuestion 工具并启用 multiSelect）。根据文档类型提供相关选项：
   • AI 生成图像——定制插图、图表、照片（使用 generate-image 技能）
   • 图表／曲线图——柱状图、折线图、饼图、散点图、热力图（pgfplots 或 matplotlib）
   • 流程图／示意图——流程、架构、决策树（TikZ 或 Mermaid）
   • 引文／参考文献——学术参考文献、脚注、引用作品（BibTeX/biblatex）
   • 数据表格——对比矩阵、财务数据、统计数据（booktabs）
   • 水印——DRAFT、CONFIDENTIAL 或公司徽标背景
   • 简单文档（求职信、发票）或用户已明确说明具体需求时，跳过此步骤。
6. 从 assets/templates/ 复制合适的模板，或从头编写
7. 根据用户需求定制内容
8. 根据用户选择的元素生成外部资源：
   • AI 图像：python3 <skill_path>/../generate-image/scripts/generate_image.py "prompt" --output ./outputs/figure.png
   • matplotlib 图表：python3 <skill_path>/scripts/generate_chart.py <type> --data '<json>' --output chart.png
   • Mermaid 示意图：bash <skill_path>/scripts/mermaid_to_image.sh diagram.mmd output.png
9. 对于 5 页及以上的文档： 编译前阅读长篇文档反模式部分，并运行内容生成检查清单。关键规则：优先使用叙述而非项目符号，统一压缩列表，在文本模式下转义 </>，调整各节格式，限制 \newpage 的使用，将图片尺寸设为文本宽度的 0.75–0.85 倍。
10. 使用 scripts/compile_latex.sh 编译（自动检测适用于 CJK／RTL、术语表和参考文献的 XeLaTeX）
11. 向用户展示 PNG 预览，并交付 PDF

海报子工作流

用户要求制作海报时，阅读 references/poster-design-guide.md，了解完整工作流，包括会议尺寸预设（NeurIPS/ICML/CVPR/ICLR 尺寸）、布局类型（传统型／BetterPoster／视觉优先型）、配色方案和排版标准。使用 poster.tex（纵向）或 poster-landscape.tex（横向）。使用 AskUserQuestion 询问用户的会议／方向、布局风格和配色方案，然后继续第 5 步。

速查表／参考卡片子工作流

用户要求制作速查表、参考卡片或公式表时：

1. 阅读 references/cheatsheet-guide.md，了解完整工作流，包括模板选择、内容篇幅限制、排版规则以及 PDF 转速查表流程。
2. 选择模板：cheatsheet.tex（通用，横向 3 栏）、cheatsheet-exam.tex（考试公式，纵向 2 栏）或 cheatsheet-code.tex（编程，横向 4 栏）。
3. 按照指南中的工作流步骤操作，然后返回主工作流第 5 步。

工作流：邮件合并（批量生成个性化文档）

使用 LaTeX 模板和 CSV/JSON 数据源，通过 scripts/mail_merge.py 生成 N 份个性化文档。模板语法：使用 {{variable}} 进行简单替换，使用 Jinja2（<< >>、<% %>）处理条件和循环。示例请参阅 assets/templates/mail-merge-letter.tex。完整指南：references/interactive-features.md。

工作流：版本差异比较（latexdiff）

使用 scripts/latex_diff.sh 生成突出显示修订内容的 PDF。支持文件间差异比较、Git 修订版本差异比较、多文件合并以及自定义标记样式。完整指南：references/interactive-features.md。

工作流：转换文档格式

使用 scripts/convert_document.sh 在 Markdown、DOCX、HTML 和 LaTeX 之间进行转换。完整指南：references/format-conversion.md。

工作流：将 PDF 转换为 LaTeX

将现有 PDF（手写笔记、印刷报告、法律文件）转换为 LaTeX。完整流程：references/pdf-conversion.md。

快速步骤：将 PDF 拆分为页面图像（scripts/pdf_to_images.sh），选择转换配置文件，创建共享导言区，应用缩放策略，使用 scripts/validate_latex.py 验证，合并并编译。

缩放策略：1-10 页 = 单个 Agent；11-20 页 = 对半拆分（2 个 Agent）；21 页及以上 = batch-7 流水线（ceil(N/7) 个 Agent，设置 run_in_background: true）。

转换配置文件（位于 references/profiles/）：math-notes.md（方程、定理——包含精美模式）、business-document.md（报告、备忘录）、legal-document.md（合同、法规）、general-notes.md（手写内容、混合内容）。

工作流：填写 PDF 表单

填写现有 PDF 表单——包括可填写表单（带有表单字段）和不可填写表单（基于图像）。完整指南：references/pdf-operations.md。

第 1 步：检查表单类型：

python3 <skill_path>/scripts/pdf_check_form.py form.pdf

如果可填写（带有表单字段）：

# Extract field metadata
python3 <skill_path>/scripts/pdf_extract_fields.py form.pdf field_info.json
# Create field_values.json with values for each field, then fill
python3 <skill_path>/scripts/pdf_fill_form.py form.pdf field_values.json output.pdf

如果不可填写（不带表单字段）：

# Convert to images for visual analysis
bash <skill_path>/scripts/pdf_to_images.sh form.pdf ./tmp/pages
# Visually identify fields, create fields.json with bounding boxes
# Validate bounding boxes (+ optional validation image)
python3 <skill_path>/scripts/pdf_validate_boxes.py fields.json --image page_1.png --output validation.png --page 1
# Fill with text annotations
python3 <skill_path>/scripts/pdf_fill_annotations.py form.pdf fields.json output.pdf

工作流：高级 PDF 操作

有关文本/表格提取（pdfplumber）、OCR（pytesseract）、以编程方式创建 PDF（reportlab）、添加水印、旋转/裁剪页面、提取元数据、JavaScript 库（pdf-lib、pdfjs-dist）和批处理，请参阅 references/pdf-operations.md。

编译脚本

# Basic compile (auto-detects engine)
bash <skill_path>/scripts/compile_latex.sh document.tex

# Compile + generate PNG previews
bash <skill_path>/scripts/compile_latex.sh document.tex --preview

# Compile + PNG in specific directory
bash <skill_path>/scripts/compile_latex.sh document.tex --preview --preview-dir ./outputs

# Force a specific engine
bash <skill_path>/scripts/compile_latex.sh document.tex --engine xelatex
bash <skill_path>/scripts/compile_latex.sh document.tex --engine lualatex

# Use latexmk for automatic multi-pass (recommended for complex documents)
bash <skill_path>/scripts/compile_latex.sh document.tex --use-latexmk --preview

# PDF/A output for thesis submissions and archival compliance
bash <skill_path>/scripts/compile_latex.sh document.tex --pdfa

# Verbose output for debugging compilation issues
bash <skill_path>/scripts/compile_latex.sh document.tex --verbose

# Quiet mode for batch/CI jobs (only errors shown)
bash <skill_path>/scripts/compile_latex.sh document.tex --quiet

# Clean auxiliary files only (no compilation)
bash <skill_path>/scripts/compile_latex.sh document.tex --clean

编译标志

标志	说明
--preview	编译后生成每页的 PNG 预览
--preview-dir DIR	PNG 输出目录（默认：与 .tex 文件相同的目录）
--engine ENGINE	指定引擎：pdflatex、xelatex 或 lualatex
--use-latexmk	使用 latexmk 作为编译后端（自动多轮编译、处理参考文献和索引）
--verbose	显示完整编译输出（所有引擎日志）
--quiet	禁止显示所有非错误输出
--clean	删除辅助文件（.aux、.log、.bbl、.fdb_latexmk 等）并退出
--pdfa	生成符合 PDF/A-2b 标准的输出（自动注入 pdfx 包）
--auto-fix	自动修复常见编译错误（浮动体位置、编码）

编译后端

**手动多轮编译（默认）：**根据需要多次运行引擎，并处理参考文献、索引和术语表。此传统方式无需安装 latexmk 即可使用。

**latexmk（--use-latexmk）：**使用 latexmk 根据依赖关系自动编译。对于包含参考文献、索引、术语表或交叉引用的复杂文档，推荐使用此方式——latexmk 会自动确定正确的编译轮数。需要安装 latexmk（TeX Live 附带）。

日志过滤（texfot）

安装 texfot（包含在 TeX Live 中）后，编译输出会自动过滤，仅显示相关警告和错误，并抑制嘈杂的软件包加载消息。这适用于默认详细程度模式。使用 --verbose 查看未经筛选的输出，或使用 --quiet 隐藏所有非错误输出。

引擎自动检测：如果 .tex 文件使用 fontspec、xeCJK 或 polyglossia，脚本会自动使用 xelatex。如果使用 luacode 或 luatextra，则使用 lualatex。否则默认使用 pdflatex。使用 --engine 可覆盖此设置。

如果缺少依赖项，脚本会自动安装 texlive（包括 texlive-science、texlive-xetex、texlive-luatex、biber）和 poppler-utils。脚本会自动检测 \bibliography{}（运行 bibtex）、\addbibresource{}（运行 biber）、\makeindex（运行 makeindex）、\makeglossaries（运行 makeglossaries），运行正确次数的编译，使用 pdftoppm 生成 PNG 预览，并清理辅助文件。

脚本与工具参考

有关 PDF 工具（加密、合并、优化、提取页面、PDF 转图像）、LaTeX 质量工具（lint、字数统计、分析、软件包检查、引用）、编译自动修复、文献获取和图表脚本（Mermaid、Graphviz、PlantUML），请参阅 references/script-tools.md。

模板

从 assets/templates/ 复制并自定义。

简历模板（5 种兼容 ATS 的选项）

根据经验水平、行业和 ATS 要求进行选择。完整的 ATS 指南请参阅 references/resume-ats-guide.md。

模板	最适合	主要特点	ATS 评分
resume-classic-ats.tex	金融、法律、政府部门，以及任何 ATS 门户	无图形元素，仅纯文本，最大程度确保解析安全	10/10
resume-modern-professional.tex	科技、企业、通用专业岗位	柔和的色彩点缀、简洁设计，兼顾 ATS 兼容性与人工阅读体验	9/10
resume-executive.tex	VP、总监、高管层（5-15 年以上经验）	两页版、执行摘要、董事会职位、侧重损益	9/10
resume-technical.tex	软件、数据、工程岗位	技能优先的混合布局、项目部分、突出技术栈	9/10
resume-entry-level.tex	应届毕业生、职业生涯起步者	教育经历优先、单页版、课程作业、活动经历	9/10

这 5 个模板均遵循 ATS 规则：单栏布局、不使用图形或图像、不用表格排版、使用标准的部分标题，联系信息置于正文中（而非页眉或页脚）。

STEM 学生模板

• homework.tex -- 作业/习题提交模板（article 类，11pt），支持切换是否显示解答（\showsolutionstrue/\showsolutionsfalse），包含自定义题目/解答环境、诚信守则部分、fancyhdr 页眉、用于数学的 amsmath+amssymb+amsthm、代码高亮 listings（Python、Java、C++、Matlab 样式）、用于 (a)、(b)、(c) 子题的 enumitem、hyperref。可通过 \coursename、\assignmentnumber、\studentname、\studentid、\duedate 自定义。示例题目：微积分、数学归纳法证明、Python 编程、矩阵代数、运动学、Java 面向对象编程。
• lab-report.tex -- STEM 实验报告模板（article 类，11pt），使用 siunitx 表示不确定度和 SI 单位，使用 pgfplots 可视化数据，使用 booktabs 制作专业表格，使用 amsmath 编写方程，使用 fancyhdr 设置页眉，使用 caption+subcaption 排版图表。结构化部分包括：摘要、理论、实验步骤、数据/结果（含不确定度表格）、分析（pgfplots 图表）、讨论（误差分析）、结论、参考文献、附录。示例：通过误差传播测量摆的周期。

其他模板

• lecture-notes.tex — 精美讲义（scrartcl KOMA-Script 类），采用 Palatino 字体、microtype 排版、彩色 tcolorbox 定理环境（蓝色定理、绿色定义、橙色示例、紫色备注）、TikZ 图论图形样式和宏（\CompleteGraph、\CycleGraph、\PathGraph）、使用 titlesec 设置的样式化章节标题、fancyhdr 页眉，以及 hyperref + cleveref 导航。适合将手写数学／科学笔记转换为精美 PDF。包含图论自定义命令（\V、\E、\deg、\chr）。数学笔记转换配置文件的精美模式会使用此模板。
• thesis.tex — 学位论文／毕业论文（book 类），包含标题页、声明、摘要、致谢、目录、插图目录／表格目录、章节、附录和参考文献。前置部分使用罗马数字编号，正文部分使用阿拉伯数字编号。包含定理环境。
• academic-cv.tex — 多页学术简历，包含出版物（期刊／会议／预印本部分）、资助项目与经费、教学、指导（在读／已毕业学生）、奖项、专业服务和受邀演讲。包含 ORCID 和 Google Scholar 链接。
• book.tex — 完整图书（book 类），包含半标题页、标题页、版权页、献词、序言、致谢、目录、插图目录／表格目录、篇、章节、附录、参考文献和索引。包含自定义章节标题、题词、fancyhdr 和 microtype。
• poster.tex — 会议海报（tikzposter 类，A0 纵向），采用双栏布局，包含二维码、5 种配色方案、tikzfigure 图表、表格和高亮彩色框。包含以注释形式提供的 #BetterPoster 布局变体（中央展示区 + 侧栏）。纵向版式适用于大多数会议。会议尺寸预设请参见海报设计指南。
• poster-landscape.tex — 横向会议海报（tikzposter 类，A0 横向），采用三栏（30/40/30）布局，包含二维码和科技紫配色方案。适用于计算机科学／机器学习会议（NeurIPS、ICML、CVPR、ICLR）。包含以注释形式提供的 \geometry{} 预设，适用于 CVPR／NeurIPS 自定义尺寸。
• cheatsheet.tex — 通用速查卡（extarticle 类，A4 横向，基础字号 7pt），采用 multicols 三栏布局、tcolorbox 彩色分节框和紧凑间距。适用于命令参考、概念摘要和快速参考指南。支持正反面打印。
• cheatsheet-exam.tex — 考试公式表（extarticle 类，A4 纵向，基础字号 6pt），采用双栏布局，内容密度最高，并适合黑白打印机打印。适用于大学考试中允许携带的公式表，包含公式、定理和定义。针对单面打印进行了优化。
• cheatsheet-code.tex — 编程速查卡（extarticle 类，A4 横向，基础字号 7pt），采用四栏布局、minted 语法高亮和等宽字体强调。适用于语言语法、API 参考、CLI 命令和键盘快捷键。
• letter.tex — 正式商务信函，包含彩色信头栏、TikZ 标志占位符、公司信息、收件人信息栏、日期、主题行和签名。呈现专业的企业风格。
• exam.tex — 考试／测验（exam 类），包含评分表、多种题型（单选题、判断题、填空题、配对题、简答题、论述题）、分值，以及通过 \printanswers 切换答案显示。
• report.tex — 商务报告，包含目录、页眉／页脚、数据表格、柱状图（pgfplots）、流程图（TikZ）和建议
• cover-letter.tex — 专业求职信，包含寄件人／收件人信息栏
• invoice.tex — 发票，包含公司抬头、明细表、小计／税额／总计
• academic-paper.tex — 研究论文，包含摘要、章节、参考文献和插图。包含用于 BibTeX 引用的示例 .bib 文件（references.bib）。
• examples/ieee-twocolumn-sample.tex — IEEE Transactions／期刊示例，使用 \documentclass[journal,10pt]{IEEEtran}，包含摘要、关键词、单栏插图、单栏表格、通栏表格和数字编号的参考文献。请与 references/ieee-journal-twocolumn-guide.md 配合使用。PNG 预览：examples/ieee-twocolumn.png、examples/ieee-twocolumn-p1.png、examples/ieee-twocolumn-p2.png。
• presentation.tex — Beamer 演示文稿，包含标题页、内容页和分栏
• fillable-form.tex — 可填写 PDF 表单（article 类），通过 hyperref 表单字段提供文本输入框、复选框、单选按钮、下拉菜单和按钮。使用 tabularx 实现双栏布局。包含自定义辅助命令 \FormField、\FormCheck、\FormDropdown。完整表单功能需要 Adobe Reader 支持（浏览器中的 PDF 查看器对表单功能的支持有限）。
• conditional-document.tex — 可配置文档（article 类），使用 etoolbox 开关系统控制目录、附录、水印、草稿模式、保密标记和摘要的显示／隐藏。通过 \providecommand 设置模板变量（标题、作者、机构、版本）。提供三种视觉配置（企业、学术、极简）。支持通过命令行传递变量，以用于 CI/CD。
• mail-merge-letter.tex — 邮件合并信函模板，包含供 scripts/mail_merge.py 使用的 {{variable}} 占位符。包含公司品牌信头、收件人地址栏，以及基于数据个性化的正文。可配合 CSV/JSON 数据源使用。
• resume.tex — 旧版简历模板（包含照片区域和表格，不针对 ATS 优化） 用法：

cp <skill_path>/assets/templates/resume-classic-ats.tex ./outputs/my_resume.tex
# Edit content, then compile
bash <skill_path>/scripts/compile_latex.sh ./outputs/my_resume.tex --preview --preview-dir ./outputs

文档类型选择

用户请求	模板	文档类
简历、CV（兼容 ATS）	resume-classic-ats.tex	article
简历（现代风格）	resume-modern-professional.tex	article
简历（资深人士／高管）	resume-executive.tex	article
简历（技术／工程）	resume-technical.tex	article
简历（应届毕业生）	resume-entry-level.tex	article
作业、课题、习题集	homework.tex	article
实验报告、实验记录	lab-report.tex	article
讲义、数学笔记（精美版）	lecture-notes.tex	scrartcl
论文、学位论文	thesis.tex	book
学术 CV（出版物、资助项目）	academic-cv.tex	article
报告、分析	report.tex	article
求职信	cover-letter.tex	article
发票	invoice.tex	article
学术论文	academic-paper.tex + references.bib	article
IEEE 期刊、IEEE Transactions、IEEE 双栏论文	examples/ieee-twocolumn-sample.tex + ieee-journal-twocolumn-guide.md	IEEEtran
书籍	book.tex	book
科学海报（纵向）	poster.tex	tikzposter
科学海报（横向）	poster-landscape.tex	tikzposter
速查表、参考卡	cheatsheet.tex	extarticle
考试公式表、备忘单	cheatsheet-exam.tex	extarticle
编程参考卡	cheatsheet-code.tex	extarticle
正式商务信函	letter.tex	article
考试、测验、测试	exam.tex	exam
幻灯片、演示文稿	presentation.tex	beamer
可填写 PDF 表单	fillable-form.tex	article
条件式／可配置文档	conditional-document.tex	article
邮件合并、批量信函	mail-merge-letter.tex + scripts/mail_merge.py	article
版本差异（latexdiff）	使用 scripts/latex_diff.sh + 参阅 interactive-features.md	各不相同
将 PDF 转换为 LaTeX	选择配置文件 + 参阅 pdf-conversion.md	各不相同
转换格式	使用 scripts/convert_document.sh + 参阅 format-conversion.md	各不相同
从 CSV/JSON 进行邮件合并	使用 scripts/mail_merge.py + 参阅 interactive-features.md	各不相同

LaTeX 关键模式

特殊字符转义

始终转义：% → \%、$ → \$、& → \&、# → \#、_ → \_

文本模式中的尖括号： 在 T1 编码下，< 和 > 在 LaTeX 文本模式中无效。它们会显示为倒置问号（¡ 或 ¿）。务必使用数学模式或文本命令：

• <5% → $<$5\% 或 \textless 5\%
• >50 → $>$50 或 \textgreater 50
• <$300 → $<$\$300
• >= → $\geq$、<= → $\leq$

这是生成的 LaTeX 中最常见的静默错误之一——文档可以无错误地编译，但 PDF 中会显示乱码。

日期范围使用 en dash：2019--2025（两个连字符）。

标准导言区

\documentclass[11pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{geometry}
\usepackage{hyperref}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{tabularx}
\usepackage{colortbl}
\usepackage{enumitem}
\usepackage{titlesec}

代码模式（按需加载）

如需可直接使用的 LaTeX 代码片段（表格、图表、流程图、参考文献、浮水印、横向页面、多语言、图片、Mermaid 图表、matplotlib 图表、CSV 表格、AI 图片、可填写表单、条件式内容、邮件合并、版本差异），请阅读 references/code-patterns.md。

报告中的视觉元素

创建报告时，请使用用户在第 4 步中选择的增强元素。视觉元素工具（图表、流程图、AI 图片、表格、时间线）和尺寸指南的速查表，请参阅 references/advanced-features.md。使用 \begin{figure}[H]（来自 float 宏包）防止图形浮动。TikZ 示意图的尺寸设为 width=0.8\textwidth 或更小。

参考指南（按需加载）

如果不确定 LaTeX 模式、编译问题或文档质量，请查阅此表并加载相关文件。

主题	文件	阅读时机
长文档最佳实践	long-form-best-practices.md	5 页及以上的文档必须阅读：9 种反模式、报告前言、内容生成检查清单
代码模式（LaTeX 代码片段）	code-patterns.md	可直接使用的 LaTeX 代码：表格、图表、流程图、参考文献、浮水印、横向页面、多语言、图片、表单、邮件合并、差异对比
脚本和工具参考	script-tools.md	PDF 实用工具（加密、合并、优化、提取）、LaTeX 质量工具（lint、字数统计、分析）、编译自动修复、参考文献、图表
参考文献/引用	bibliography-guide.md	BibTeX/biblatex、引用样式、.bib 格式
高级功能和视觉元素	advanced-features.md	浮水印、横向页面、多语言、代码、算法、tcolorbox、siunitx、高级图表、AI 图片、视觉元素参考表
Mermaid 图表	mermaid-diagrams.md	流程图、时序图、类图、ER 图、甘特图、饼图、思维导图
Python 图表（matplotlib）	python-charts.md	柱状图、折线图、散点图、饼图、热力图、箱线图、直方图、面积图、雷达图
格式转换（Pandoc）	format-conversion.md	Markdown/DOCX/HTML 与 LaTeX 之间的转换
表格和图片	tables-and-images.md	彩色行、多行/多列、booktabs、长表格、图片、TikZ
图表和曲线图（pgfplots）	charts-and-graphs.md	pgfplots 中的折线图、柱状图、散点图、饼图
IEEE 期刊双栏排版	ieee-journal-twocolumn-guide.md	IEEEtran 期刊版式、浮动体规则、XeLaTeX 与 pdfLaTeX、参考文献、Markdown 到 IEEE 的工作流、examples/ieee-twocolumn*.png 中的示例 PNG
LaTeX 宏包	packages.md	常用宏包参考
海报设计指南	poster-design-guide.md	会议尺寸预设、排版、配色方案、布局原型、内容指南
简历 ATS 指南	resume-ats-guide.md	ATS 规则、LaTeX 易错点、关键词
PDF 到 LaTeX 流程	pdf-conversion.md	完整转换流程、缩放策略、工作 Agent、验证
交互功能	interactive-features.md	可填写 PDF 表单、条件内容、从 CSV/JSON 邮件合并、latexdiff 版本跟踪
速查表设计	cheatsheet-guide.md	模板选择、排版、密度优化、PDF 到速查表流程
PDF 到速查表的提示词	pdf-extraction-prompts.md	用于提取阶段的大模型提示词：结构分析、特定主题提取、压缩、格式整理
视觉宏包（TikZ）	visual-packages.md	24 个已安装的 TikZ/可视化宏包及可运行示例
Graphviz 和 PlantUML	graphviz-plantuml.md	.dot 转 PDF/PNG、.puml 转 PDF/PNG、LaTeX 集成
调试和错误	debugging-guide.md	阅读 LaTeX 错误、20 种常见错误、.log 分析、静默失败
无障碍和 PDF/A	accessibility-guide.md	论文用 PDF/A、屏幕阅读器用 PDF/UA、带标签的 PDF、替代文本
Beamer 演示文稿	beamer-guide.md	主题、叠加/动画、代码幻灯片、讲义、演讲者备注
字体选择	font-guide.md	字体系列、fontspec、数学字体、fontawesome5、microtype、CJK
协作和 CI/CD	collaboration-guide.md	LaTeX 的 Git、GitHub Actions、Docker、多作者工作流
PDF 操作	pdf-operations.md	表单填写（可填写和不可填写）、文本/表格提取（pdfplumber）、OCR（pytesseract）、程序化创建 PDF（reportlab）、添加浮水印、旋转/裁剪、元数据、JavaScript（pdf-lib、pdfjs-dist）、批量处理、性能提示

关键提示和常见错误

编译与输出

• 从包含 .tex 文件的目录运行编译脚本，或使用绝对路径
• 将输出 .tex 文件放在 ./outputs/ 中，方便用户查看
• 编译后，阅读 PNG 预览文件，向用户展示文档效果
• PNG 预览需要 poppler-utils（脚本会自动安装）

软件包依赖错误（必须阅读）

这些错误会导致 Undefined control sequence——务必包含所需的软件包：

如果使用……	必须包含	未包含时的错误
\rowcolor{}	\usepackage{colortbl}	未定义的控制序列 \rowcolor
在 .bib 中与 natbib 一起使用 \url{}	\usepackage{url}	未定义的控制序列 \url
\checkmark	\usepackage{amssymb}	未定义的控制序列 \checkmark
\begin{figure}[H]	\usepackage{float}	未知的浮动体选项 H
\rowcolors{}{}{}	\usepackage[table]{xcolor} 或 \usepackage{colortbl}	未定义的控制序列

hyperref 软件包

• 对于普通文档，使用 hyperref 没问题（大多数模板都会使用它）。
• 仅在带有定理环境的 PDF 转 LaTeX 文档中避免使用，因为它会导致 \set@color 错误。

编译环境

• 如果尚未安装 texlive，编译脚本会自动安装。安装 texlive 前，不要并行运行多个编译命令——它们都会尝试同时安装，从而导致 dpkg 锁竞争。请先安装一次，或按顺序运行编译。
• 编译脚本使用 -interaction=nonstopmode（而非 -halt-on-error），确保即使存在警告也能生成 PDF。这是有意为之——许多文档首次编译时会产生警告，在后续编译中会消除。
• latexmk 和 texfot 已包含在 TeX Live 中。设置脚本（setup.sh）会验证它们是否可用。传入 --use-latexmk 时会使用 latexmk；texfot 则会在可用时自动使用（默认详细程度模式）。
• 技能根目录中包含 .chktexrc 配置文件，用于抑制检查生成的 LaTeX 文档时常见的误报。latex_lint.sh 脚本会自动使用该文件。

长篇文档反模式

对于 5 页及以上的文档（报告、论文、书籍），请阅读 references/long-form-best-practices.md，了解 9 个关键反模式、报告导言区的最佳实践，以及内容生成检查清单。生成任何长篇文档前，必须阅读这些材料。