考研数学做题模板 - PDF生成器
生成专业排版的数学练习题PDF文档，支持完整的LaTeX数学公式渲染。
输出格式选择
- HTML方式（推荐）- 使用HTML+KaTeX，通过Playwright (Chromium headless) 生成PDF，无需LaTeX环境
- LaTeX方式 - 生成.tex文件后用xelatex编译，公式渲染最精致
工作流程
步骤1：收集题目信息
向用户确认以下信息：
- 标题（如"数学练习题"、"考研数学强化训练"等）
- 副标题（如知识点范围）
- 年份/系列信息
- 题目内容（按章节/分类组织）
步骤2：选择输出格式
如果 用户需要高质量PDF且本地有LaTeX环境 → 使用LaTeX模板
如果 用户需要快速预览或无LaTeX环境 → 使用HTML模板
步骤3：生成文档
HTML方式（推荐）：
1. 复制 assets/math_template.html 作为基础
2. 替换封面信息（标题、副标题、年份）
3. 按章节添加题目内容
4. 保存为 .html 文件
5. 运行 python scripts/html_to_pdf.py <文件名>.html 生成PDF
6. 若脚本提示"未放在数学定界符中的LaTeX命令"，先修复再导出
LaTeX方式：
1. 复制 assets/math_template.tex 作为基础
2. 替换封面信息（标题、副标题、年份）
3. 按章节添加题目内容
4. 保存为 .tex 文件
5. 使用 xelatex 编译生成PDF
文件结构
math-exercise-pdf/
├── SKILL.md # 技能说明文档
├── assets/
│ ├── math_template.html # HTML模板（推荐）
│ ├── math_template.tex # LaTeX模板
│ └── README.md # 模板使用说明
└── scripts/
├── html_to_pdf.py # HTML转PDF脚本
├── self_check.py # 自检脚本（验证环境+最小PDF）
└── README.md # 脚本使用说明
题目格式规范
数学公式语法
行内公式：$公式$
块级公式：$$公式$$ 或 \[公式\]
公式渲染防错规则（关键）
- 所有 LaTeX 命令（如
\frac、\sum、\lim、\epsilon、\underline）必须写在数学定界符中（$...$或$$...$$）。 - 填空线请写为
$\\underline{\\qquad\\qquad}$，不要在普通文本里裸写\underline{...}。 - 不要覆盖 KaTeX 内部分式布局相关样式（如
.katex .mfrac的display:flex），否则会导致分子分母错位或缺失。 - 数学公式中的不等号必须使用以下三种之一（按推荐顺序）：
-\\lt/\\gt（KaTeX 原生命令，最推荐）
-&lt;/&gt;（HTML 实体，脚本会自动转义为\\lt/\\gt）
- 不要写裸</>（KaTeX 不支持，浏览器会把它当 HTML 标签，破坏公式） - PDF 导出统一使用
scripts/html_to_pdf.py；脚本会先做语法检查，并自动修复数学区内的&lt;/&gt;后再导出。 - 如需跳过语法检查，可使用
--strict，但只建议在确认无误时使用。
章节结构模板
## 第X部分 章节名称
### 题 N
题目内容，支持数学公式 $x^2 + y^2 = r^2$
### 题 N+1
下一题内容...
常用LaTeX数学命令
| 符号 | 代码 | 符号 | 代码 |
|---|---|---|---|
| 分数 | \dfrac{a}{b} |
根号 | \sqrt{x} |
| 求和 | \sum_{i=1}^{n} |
积分 | \int_a^b |
| 极限 | \lim_{x \to 0} |
偏导 | \frac{\partial f}{\partial x} |
| 向量 | \vec{a} |
矩阵 | \begin{pmatrix}...\end{pmatrix} |
脚本命令行参数
python html_to_pdf.py <输入html> [输出pdf] [--strict] [--keep-temp]
参数:
--strict 严格模式: 检测到可疑LaTeX时中止导出 (默认仅警告不中断)
--keep-temp 保留临时安全副本 (调试用, 默认导出后自动删除)
故障排查
快速诊断
运行 python scripts/self_check.py 一次性检查：
- Python 依赖（playwright、pymupdf）
- Playwright Chromium 浏览器是否已下载
- KaTeX CDN（jsdelivr）是否可达
- sanitize_raw_angle_in_math 函数的正确性
- 最小 HTML 文件能否成功生成 PDF
如果自检失败，按错误提示逐项修复。
常见问题
Q1: PDF 中出现裸 LaTeX（如 $x^2$）
- 原因：KaTeX 库未加载（断网/CND被墙）或触发时机问题
- 排查：
1. self_check.py 第3项检查 KaTeX CDN 是否可达
2. 用浏览器打开 HTML，按 F12 看 Console 是否有 JS 错误
3. 用浏览器打开 HTML，看 DOM 中 .katex 元素数是否 > 0
Q2: PDF 中数学公式里的 < / > 显示为字面字符
- 原因：用户写了裸 < / > 而非 \\lt / \\gt 或 &lt; / &gt;
- 修复：把 HTML 里的 $ ... < ... $ 改成 $ ... \\lt ... $
- 注：脚本不能自动修复裸 < / >（避免误判跨HTML标签的OCR噪声）
Q3: PDF 中出现 $\frac{\partial}{\partial}$ 这种"梯形"伪影
- 原因：自定义 CSS 覆盖了 KaTeX 的 .katex .mfrac 样式
- 修复：删除任何对 .katex .mfrac 的 display / flex / align-items 覆盖
Q4: 三角符号（▲▼●）出现在 PDF 上
- 原因：.katex 上设置了过大的 font-size（如 1.1em）
- 修复：删除 .katex { font-size: ... !important; } 覆盖
Q5: 某些公式不渲染但 PDF 看起来"还行"
- 原因：KaTeX throwOnError: false 让失败公式保持原文
- 排查：浏览器打开 HTML，按 F12 Console 看 ParseError 警告
- 修复：根据警告修正 LaTeX 语法
渲染机制说明
本 skill 使用 Playwright (Chromium headless) 而非 Edge headless，原因是：
- Playwright 对 defer 脚本和 auto-render 的触发更可靠
- Playwright 的 page.evaluate 可主动调用 renderMathInElement，避免依赖 DOMContentLoaded 时机
KaTeX auto-render 的二次扫描机制（setTimeout(600ms)）确保所有动态添加的公式也被处理。
示例输出
HTML模板渲染效果
第一部分 高等数学
题 1
设函数 $f(x)$ 在 $[0,1]$ 上连续，证明：
$$\int_0^1 f(x)dx = f(\xi), \quad \xi \in [0,1]$$
题 2
求极限：$\displaystyle\lim_{x\to 0}\frac{\sin x}{x}$
依赖要求
pip install playwright pymupdf
playwright install chromium
- LaTeX转PDF（可选）：TeX Live 或 MiKTeX 发行版
