liuchun19860817-glitch 数学专题卷生成器
概述
把“出一张带配图、带答案详解的初中数学专题卷 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指向含上述字体的目录（优先级最高）
- Windows：
迁移到其他电脑
- 把
math-paper-generator整个文件夹拷到目标电脑的~/.codex/skills/（Windows 为C:\Users\<用户名>\.codex\skills\）。 - 目标电脑安装 Python 3.12+ 与全部依赖（见上）。
- 确保中文字体可用：Windows 自带；macOS/Linux 安装 CJK 字体，或设置
MATH_PAPER_FONT_DIR。 - 调用方式与在本机一致（对话中直接说需求，或
Use $math-paper-generator …）。 - 可选：把技能文件夹放进 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 步确认的范围）。
- 多解题必须写全“所有满足条件的点/值”。
- 每题必须配答案详解，且主线程或审核员用符号计算复核数值。