初中英语词汇学习表生成器（A4 打印版 HTML）

Overview

将任意来源的英语单词表，产出为一份专业、克制、黑白灰的 A4 纸质讲义风格单文件 HTML：三栏表格、每页自动重复标题与表头、单词行不会被跨页切断、打印与「另存为 PDF」效果一致。

核心交付物是 Vocabulary_Learning_Sheet.html（离线可用、UTF-8、无外部资源）。配套的 words.txt＋build.py 保证后续改词、改句、改标题都能一键重生成。

When to Use

• 用户提供一份单词表（文字/图片/PDF/Word/Excel），要求做成可打印的词汇表或讲义
• 需要为每个单词配语境例句 + 中文翻译
• 需要 A4 纵向、固定列宽、多页自动重复表头
• 需要在已有词汇表上增改词条、换标题、调整释义或例句

Role

以「有初中英语教学经验的教师 ＋ 专业 HTML/CSS 排版设计师」的身份工作：释义按中考价值精选，例句按六、七年级认知水平撰写，排版按纸质讲义标准控制。

Workflow

Step 1 — 确认课标词汇白名单

Skill 内置 assets/curriculum_words.txt（义务教育英语课程标准词汇表，1600 词）。默认以此为唯一词源。

• 用户另行提供了课标词汇表 → 覆盖写入该文件，或另存后用 --whitelist 指定。
• 用户明确说「不加限制」→ 跳过本步，不传 --whitelist。

四条硬规则（用户定制，优先级高于其他所有规则）：

1. 不在课标词汇表中的单词，一律删除，不出现在单词表里，不做解释、不留空行。
2. 只要单词，不要短语。多词词组（give up、take a seat、ice skating、put oneself in sb.'s shoes）一律剔除，即使它整体在课标表内。连字符复合词（X-ray、ice-skate、old-fashioned）算单词，不在此列。
   判定方式：词条含空格 → 短语 → 删除。脚本默认执行，想保留需显式加 --phrases。
3. 例句长度 7—10 个英文单词，上限 10，越短越好懂（照顾中等生）。
4. 例句用词难度 ≤ 五四制七年级水平，可以低不可以高。

关于规则 4 的实现（重要）：词条过滤和例句用词用两张不同的表。

• 传了 --whitelist 但没传 --sentence-whitelist 时，脚本自动加载七年级表，不用担心漏传。
• 想让例句也用完整 1600 表 → --sentence-whitelist none。
• 目标词本身永远放行：manage 词条里的 managed、hide 词条里的 hid 不算超纲（脚本会做词形还原后再比对）。
• curriculum_words_grade7.txt 是按「人教版七上 / 七下 词汇」为参照，从 1600 表里剔除高年级词得到的，剔除清单保留在 assets/level_grade8plus.txt。若用户手上有正式的五四制七年级词表，直接替换该文件即可，不必改脚本。

Step 2 — 提取原始词表

从用户提供的来源中读出全部词条，保持原顺序。

多词短语照常写进 words.txt 即可，脚本生成时会统一剔除（规则 3），不必手工预先删除——保留在数据源里，将来若切换成"保留短语"模式（--phrases）可以直接复用。

> 若来源是图片/PDF/Word/Excel，先用对应工具抽取文本，再进入 Step 3。

Step 3 — 编写中间数据源 words.txt

复制 assets/words_template.txt 作为起点，一条一行，四段用 ||| 分隔：

单词|||词性及释义|||英文例句|||中文翻译

以 ##Unit N 开头标记单元标题（## 后的内容原样显示为单元标题行）。

第二栏写法

• 词性缩写：n. v. adj. adv. prep. conj. pron.
• 最多 3 个义项，通常 1—2 个；义项间用中文分号「；」隔开
• 只保留初中阶段最值得掌握的义项；不为凑数添加低频义
• 示例：v. 改进；提高 / n. 经历；经验 / v. 改变；n. 变化

第三栏写法 — 逐条对照 references/sentence_guidelines.md：

• 严格 7—10 个英文单词（默认 --min 7 --max 10；上限 10 是硬要求）
• 每一个英文单词都必须在七年级白名单内，目标词本身除外
• 只用一般现在/过去/将来、现在进行、常见情态动词、there be、because/when/if/but/so
• 必须有真实情境，让学生能靠上下文猜出词义
• 一词一句，优先用最常见义项，可合理变形（managed、hid、shook 都算目标词的合法变形）

> 写句技巧：先在七年级表里挑 5—7 个高频实词，再用表内功能词串起来，比"先写句子再查词"高效得多。
> 七年级表只有 850 词，很多看似简单的词其实不在里面（如 plant、coin、catch、carry、break、bright、loud、hurt）。
> 写之前先跑一次校验，对着 [OOV] 报告逐个替换，比凭感觉猜快。
> 数词、星期、月份、常见人名/地名未单列在词汇表里，已放在 assets/allow_extra_default.txt，脚本会自动放行。

第四栏写法

• 准确、自然、通顺，符合初中生中文表达，不逐词硬译
• 不加「翻译：」「中文意思：」等标签

Step 4 — 生成 HTML

<SKILL_DIR> 指本 Skill 的安装目录（如 ~/.workbuddy/skills/vocab-print-sheet），
words.txt 与输出 HTML 放在用户的工作目录。两者路径不同，命令里不要用相对路径互相引用。

# 启用课标词汇白名单（推荐）
python <SKILL_DIR>/scripts/build_sheet.py words.txt \
    -o Vocabulary_Learning_Sheet.html \
    -t "八年级上册单词" \
    --whitelist <SKILL_DIR>/assets/curriculum_words.txt

# 不限词源
python <SKILL_DIR>/scripts/build_sheet.py words.txt -o Sheet.html -t "八年级上册单词"

# 需要保留短语时（默认是剔除的）
python <SKILL_DIR>/scripts/build_sheet.py words.txt -o Sheet.html --phrases

脚本先跑校验，全部通过才写出文件；不通过则列出 行号 + 单词 + 例句 并退出（加 --no-abort 可强制输出）。

> 启用白名单时，被删除的条目会以 [NOT-IN-LIST] / [PHRASE] 形式计入 errors，因此必须配合 --no-abort 使用，否则脚本会因"错误"而中止——这些删除是预期结果，不是缺陷。

Step 5 — 交付与预览

• 输出 HTML 到工作目录，用 present_files 打开预览。
• 提示用户：Ctrl+P 打印或「另存为 PDF」，勾选「背景图形」以保留表头浅灰底。
• 后续任何修改：只改 words.txt／命令行参数，再跑脚本，不要手改 HTML。

Layout & Print Rules（易踩坑，务必遵守）

A4 与双通道样式

@page { size: A4 portrait; margin: 12mm; }
.paper { width:210mm; min-height:297mm; margin:0 auto; background:#fff; padding:12mm;
         box-shadow:0 2px 12px rgba(0,0,0,.16); }

@media print{
  html,body{background:#fff;padding:0;margin:0;}
  .toolbar{display:none;}
  .paper{width:auto;min-height:0;margin:0;padding:0;box-shadow:none;}
}

屏幕与打印是两条独立路径：打印时必须把 .paper 的 width / padding / box-shadow 全部归零，否则叠加 @page 的 12mm 会出现 24mm 双倍边距。

表格线：禁止 border-collapse: collapse

合并边框模式下，表格最外圈边框只按半宽绘制，叠加打印缩放的抗锯齿后，最右侧竖线和最底部横线会明显比其他线细、发虚——屏幕预览正常，导出 PDF 后才暴露。

必须改用「独立边框 + 零间距」，让每条线只由唯一一个单元格边绘制：

table{ width:100%; border-collapse:separate; border-spacing:0; table-layout:fixed; }
thead th{ border-top:1px solid var(--line); border-right:1px solid var(--line);
          border-bottom:1px solid var(--line); }
thead th:first-child{ border-left:1px solid var(--line); }
tbody td{ border-right:1px solid var(--line); border-bottom:1px solid var(--line); }
tbody td:first-child{ border-left:1px solid var(--line); }

（separate 不影响 thead{display:table-header-group} 的每页重复表头。）

线条颜色

--line 不得浅于 #adadad。#c8c8c8 / #ddd 在打印和 PDF 中会发虚甚至消失。

列宽与字体

• 列宽固定 20% / 25% / 55%（table-layout: fixed ＋ colgroup）
• 标题 17pt 加粗，中文字体显式指定微软雅黑/苹方/宋体；<title> 与大标题一致
• 单词 11.5pt 加粗深色；释义 10.5pt 常规；英文例句 10.8pt 行高 1.45；中文 9.5pt 灰色行高 1.45，与英文间距 3px

分页

thead { display: table-header-group; }
tr    { break-inside: avoid; page-break-inside: avoid; }
tr.unit-row { break-after: avoid; page-break-after: avoid; }

标题放进 <thead> 内跨 3 列的单元格，才能每页重复。

Quality Gate（生成前必须全过）

脚本内置、自动执行，不允许靠肉眼逐条数：

1. 每行切分出 4 段，否则报错退出
2. 例句英文单词数 ∈ [7, 10]，打印不合规的 [词数] 单词 :: 例句
3. 中文翻译非空
4. 单词无重复，条目数与原表一致
5. 课标白名单：词条不在表内 → [NOT-IN-LIST] 并直接删除
6. 七年级白名单：例句出现表外词 → [OOV] 并列出具体超纲词
   （已做词形还原：villages/tried/children 不算超纲；目标词的变形 managed/hid/shook 也放行）
7. 只留单词：多词短语 → [PHRASE] 并直接删除（默认；--phrases 可关闭）
8. HTML 标签闭合检查

自动校验通过后，再做人工抽检：释义是否够常用、例句是否有情境且不模板化、译文是否自然、导出 PDF 后四条边框粗细是否一致。

Resources

scripts/

• build_sheet.py — 解析器 + 校验器 + HTML 渲染器。用法见文件头 docstring 与 Step 3。

references/

• sentence_guidelines.md — 例句编写规范：长度、词汇难度、语法范围、真实语境要求、合格/不合格对照、机械化造句禁用清单、输出前自查表。撰写或审核例句时加载。

assets/

• curriculum_words.txt — 义务教育英语课程标准词汇表（1600 词），词条过滤用。支持 a/an、actor/actress、be (am, is, are)、child (pl. children)、centre (AmE center)、ad (=advertisement) 等写法。用户给出新版课标表时覆盖此文件。
• curriculum_words_grade7.txt — 五四制七年级（及以下）水平词汇（850 词），例句用词用。由 1600 表剔除高年级词生成，剔除清单见 level_grade8plus.txt。若用户有正式的五四制七年级词表，直接替换本文件。
• level_grade8plus.txt — 被判为「八年级及以上、例句不可用」的词，仅用于说明 curriculum_words_grade7.txt 的生成来源，运行时不读取。
• allow_extra_default.txt — 词汇表未单列但例句需要的最低限度补充词（数词、星期、月份、常见人名地名）。启用 --whitelist 且未指定 --allow-extra 时自动加载；清空该文件即回到「严格只用表内词」。
• words_template.txt — words.txt 数据源空白模板，含格式说明与示例条目。新建词表时复制此文件。