# Math Paper Generator

> 生成初中数学专题卷并输出为 PDF（含题目配图、参考答案与详细解析）。适用于用户要求“出一套带图、带详解的数学试卷/专题卷/练习卷”的场景，例如“一次函数图像与初一平面几何结合的中难度专题卷”“低难度第2套”等；也适用于用户要求把出卷流程沉淀为可复用能力。技能内置三道 subagent 审核流水线（出题教师→审核员→排版审核员）、配图策略（题目区图不得揭露答案）、PDF 生成脚本与可复用提示词模板。适合用户要求出数学专题卷/试卷/练习卷并输出 PDF，或要求复用已有出卷流程时使用。

- Skill: `liuchun19860817-glitch/math-paper-generator` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add liuchun19860817-glitch/math-paper-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liuchun19860817-glitch/math-paper-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: liuchun19860817-glitch (https://skillmd.com/u/liuchun19860817-glitch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liuchun19860817-glitch/math-paper-generator

---


# 数学专题卷生成器

## 概述

把“出一张带配图、带答案详解的初中数学专题卷 PDF”固化为标准流水线：规划 → 出题教师出题 → 审核员逐题审核 → 修订复审 → 程序化配图 → 生成 PDF → 排版审核员检查 → 校验交付。脚本与提示词模板均可复用，避免每次重复描述要求。

## 适用输入（用户需提供，可缺省用默认）

- 专题与年级（如“一次函数图像 × 初一平面几何”）
- 难度与套号（低/中/高；第1/2/3套）
- 每套题量与题型结构（默认：选择题5+填空题5+解答题6+计算题4=20题）
- 知识范围限定（默认参考 references/knowledge-scope-example.md，须按用户教材版本调整）
- 输出目录（默认在用户工作区建 `专题/难度/第N套/`）
- 特殊要求（如：题目区配图不得揭露答案、答案需详解、多解题写全解等）

## 环境要求

- Python 3.12+（任意可用 `python` 解释器），依赖：matplotlib、reportlab、sympy、pymupdf、pypdf、PIL、fontTools、pyyaml
- 安装依赖：`python -m pip install matplotlib reportlab sympy pymupdf pypdf pillow fonttools pyyaml`
  （国内网络慢可加 `--index-url https://pypi.tuna.tsinghua.edu.cn/simple`）
- 中文字体：脚本会自动探测以下字体，找不到会给出明确报错：
  - Windows：`C:\Windows\Fonts\simsun.ttc`（宋体）、`simhei.ttf`（黑体）、`simkai.ttf`（楷体）、`msyh.ttc`（微软雅黑）
  - macOS：`/System/Library/Fonts/PingFang.ttc`、`Supplemental/Songti.ttc`
  - Linux：Noto Sans CJK（`/usr/share/fonts/opentype/noto/`）、文泉驿（`/usr/share/fonts/truetype/wqy/`）、AR PL UMing/UKai
  - 也可设置环境变量 `MATH_PAPER_FONT_DIR` 指向含上述字体的目录（优先级最高）

## 迁移到其他电脑

1. 把 `math-paper-generator` 整个文件夹拷到目标电脑的 `~/.codex/skills/`（Windows 为 `C:\Users\<用户名>\.codex\skills\`）。
2. 目标电脑安装 Python 3.12+ 与全部依赖（见上）。
3. 确保中文字体可用：Windows 自带；macOS/Linux 安装 CJK 字体，或设置 `MATH_PAPER_FONT_DIR`。
4. 调用方式与在本机一致（对话中直接说需求，或 `Use $math-paper-generator …`）。
5. 可选：把技能文件夹放进 Git 仓库（如 GitHub），目标电脑用系统 `skill-installer` 直接安装，无需手动拷贝。

## 工作流

### 第 1 步：确认需求与知识范围
- 确认/推定：专题、难度、套号、题量题型、年级与教材版本。
- 以 references/knowledge-scope-example.md 为默认基准，按用户教材增删“允许/禁止”清单（勾股定理、两点间距离公式、全等、相似、三角函数、二次函数等默认禁止）。

### 第 2 步：规划试卷结构
- 题型分布与难度梯度（卷内从易到难渐进）。
- 每题须“专题 × 本年级工具”结合，数据设计成整数、能整出答案。

### 第 3 步：出题教师 subagent 出题
- 按 references/subagent-prompts.md 的“出题教师”模板（填入专题、难度、题型结构、知识范围文件路径、输出 JSON 路径）spawn 一个 subagent。
- 产出 `draft_problems.json`：每题含 stem/options/answer/solution/stars/knowledge/figure/answer_figure（schema 见 references/json-schema.md）。

### 第 4 步：审核员 subagent 逐题审核（循环至全 PASS）
- 按 references/subagent-prompts.md 的“审核员”模板 spawn 审核员。
- 检查：知识范围合规、难度定位、答案正确性（必要时用 Python/sympy 重算）、figure 是否揭露答案、answer_figure 是否完整、题干“如图”与 figure 是否一致。
- NEEDS-FIX 的题退回出题教师修订，再复审，直到全卷 PASS。

### 第 5 步：程序化配图
- 依据 references/figure-policy.md，按 scripts/make_figures_example.py 的写法为每题写两个 matplotlib 函数：
  - `q{N}_p()` → `figures/q{N}_p.png`（题目区图：只画题干已给信息、无网格无刻度、不揭露答案）
  - `q{N}_a()` → `figures/q{N}_a.png`（答案区图：完整标注坐标/角度/阴影/辅助线）
- 复用 scripts/fig_helpers.py 的辅助函数（new_axes/plot_line/point/angle_arc/right_angle_mark/shade_polygon/parallel_marks/annotate/save）。图内文字白底已内置；标注避开坐标轴与直线。

### 第 6 步：生成 PDF
- 运行 `scripts/build_pdf.py <draft_problems.json> <figures目录> <输出.pdf>`
- 脚本自动处理：题目区图、答案区“解析配图”、分节标题与首题同页、图片宽高比保持、宋体/黑体/楷体。

### 第 7 步：排版审核员 subagent 检查（推荐）
- 按 references/subagent-prompts.md 的“排版审核员”模板 spawn 审核员，检查 PDF：孤悬标题、越界、文字与图重叠、图片拉伸、空白页、图内文字压线。
- 落实其修改建议（改 make_figures.py / build_pdf.py）后重建 PDF。

### 第 8 步：校验与交付
- 用 PyMuPDF 校验：页数、四个分节、答案部分、每页图片数、文本提取正常。
- 渲染 2-3 页预览 PNG，把 PDF 绝对路径交给用户，请其检查后反馈；合格后再批量产出其余套数。

## 关键规范

- JSON 结构：references/json-schema.md
- 配图策略：references/figure-policy.md
- subagent 提示词模板：references/subagent-prompts.md
- 默认知识范围示例：references/knowledge-scope-example.md

## 脚本

- `scripts/fig_helpers.py`：通用 matplotlib 配图辅助（坐标轴、直线、点、角度弧、直角、平行记号、阴影、白底文字）。
- `scripts/build_pdf.py`：通用 PDF 生成器（读取 schema JSON，嵌入题目图与答案图，输出 A4 PDF）。
- `scripts/make_figures_example.py`：画图脚本写法示例（题目区图 + 答案区图）。
- `scripts/verify_answers_example.py`：用 sympy 验算坐标/交点/面积的示例。

## 质量红线

- 题目区配图绝不揭露答案；会揭露答案的图一律放答案区。
- 解题方法不得超出用户年级范围（按第 1 步确认的范围）。
- 多解题必须写全“所有满足条件的点/值”。
- 每题必须配答案详解，且主线程或审核员用符号计算复核数值。