教材单词 写·练·测 三件套生成器
适用场景
- 给孩子做英语单词抄写本（四线三格，练英文书写）
- 做默写本 / 听写本（看中写英、看英写中）
- 做练习本（多种题型 + 答案对照，自学用）
- 做测本 / 测试卷（干净版 + 单独答案页，供家长老师批改）
支持小学到初中任意出版社版本（人教/外研/牛津沪教/译林/冀教/北师大…）。
三件套说明
| 产物 | 文件 | 内容 | 用途 |
|---|---|---|---|
| 抄写本 | copybook.docx |
每词=示范行 + 横排4个四线三格(英文各抄1遍,共4遍) + 2行中文实线横线(抄2遍)；整词 cantSplit 不跨页 |
抄写练字 |
| 练习本 | practice.docx |
一、看英文写中文 二、看中文写英文 三、首字母提示写词 + 末尾「答案对照」 | 自学自测 |
| 测本 | test.docx |
姓名/得分抬头 + 第一部分英译中 + 第二部分中译英 + 末尾「参考答案」页 | 打印批改 |
四线三格是 PIL 绘制的真实红线网格图 嵌入 docx，打印即真格线，无需勾选背景色。纸张固定 A4，每个单元自动新页。
标准工作流
Step 1 — 锁定教材坐标并调研词库
先与用户确认或推断出版社 / 年级册次 / 课标年份 / 是否含 Starter。调研方法见 references/research_guide.md（多源检索 + 交叉校验 + 整理成 JSON）。
> 若用户对词库没有特殊要求，可直接用内置示例 examples/waiyan_7a_2024.json（外研版2024七上，316词）演示。
Step 2 — 落盘词汇 JSON
按此 schema 写文件（如 vocab.json），字段含义见 research_guide：
{
"meta": {"title": "英语单词抄写本", "subtitle": "外研版(2024新版) · 七年级上册", "subject": "英语"},
"units": [
{"name": "Unit 1 A new start",
"words": [["without","prep.","缺乏;没有"], ["sentence","n.","句子"]]}
]
}
Step 3 — 运行生成器
生成器依赖 python-docx + Pillow。用本机可用的 Python 3（建议 3.9+）建隔离 venv 即可，不依赖任何写死的本机路径：
PY=python3 # 用本机可用的 Python 3
VENV=./.venv
"$PY" -m venv "$VENV"
"$VENV/bin/pip" install -q python-docx Pillow
# 全三件套
"$VENV/bin/python" <技能目录>/scripts/build_vocab_docs.py vocab.json --mode all --out ./out
# 或单出某一本: --mode copybook | practice | test
技能目录即本 SKILL.md 同级。示例一键跑通：
"$VENV/bin/python" <技能目录>/scripts/build_vocab_docs.py \
<技能目录>/examples/waiyan_7a_2024.json --mode all --out ./out
Step 4 — 校验与交付
- 校验：A4 尺寸（页宽 210mm）、总词数、三文件存在。
- 交付：用
present_files同时给出copybook.docx/practice.docx/test.docx。 - 打印提示：Word/WPS 打开 →
Ctrl/Cmd+P→ A4 → 直接打印（红线是真图，无需勾背景）。
参数与定制
--mode all|copybook|practice|test：只生成需要的本子。--out <dir>：输出目录（四线三格图grid1.png/grid4.png也会生成在此）。- 词库变更：改 JSON 重跑即可，无需动脚本。
- 想加词/换单元/补 Starter：直接编辑 JSON 的
units。
已知坑位（必避）
| 坑 | 解法 |
|---|---|
| 版本搞混（旧课标 vs 2024新版） | 检索词带年份，按单元标题核对；见 research_guide |
| 四线三格打印不出来 | 必须用 PIL 绘制的红线图嵌入（已采用），不要靠 CSS 背景 |
| 单词跨页被拦腰截断 | 每词包进 cantSplit 表格单元（已采用） |
| 多行格线糊在一起看错行 | 双栏每格加独立边框 + 拉大行距（已采用） |
| venv 缺依赖 | 用上面命令先建 venv 装 python-docx/Pillow |
边界与降级
- 只做三件套生成：本技能只负责「检索词库 → 整理 JSON → 生成 docx 三件套」。不翻译课文、不改写教材、不做试卷排版以外的设计。
- 不联网抓取付费词库：检索只用公开可访问的网页搜索结果交叉比对，不破解/付费下载受版权保护的词库文件；若某版本词库全网无可靠公开来源，停止并如实告知用户，不拿猜测词表顶替。
- 依赖缺失即停：运行前确认
python-docx+Pillow已装入 venv；若pip install失败（无网络/权限），停止并说明缺失项与恢复方式，不强行降级产出残缺文档。 - 不覆盖用户文件：输出固定写入
--out指定目录的copybook/practice/test.docx与grid1/grid4.png；若目标文件已存在，先提示用户确认，不静默覆盖。 - 词库准确性由来源负责：版本/单元若有歧义，先与用户确认再生成；生成后如用户指出某词有误，只需改 JSON 对应条目重跑，无需动脚本。
文件结构
textbook-vocab-workbook/
├── SKILL.md
├── scripts/build_vocab_docs.py # 通用生成器(吃JSON, 出三件套)
├── references/research_guide.md # 词库调研方法
└── examples/waiyan_7a_2024.json # 外研2024七上示例词库
