init: edu-content 内容库骨架（L1-L4 四层数据模型 + B类迁移 + lint/CI 工具）

structured/exams/pet/vocab/INDEX.md

@@ -0,0 +1,101 @@
+# 词库 INDEX — 数据总览与使用指南
+
+> 更新：2026-08-21 ｜ 解析器：`scripts/parse_vocab.py`（pymupdf，纯规则解析，零 LLM 成本）
+> 对应计划：题库路线 P3（官方词表 → 结构化词库）+ P3.5（词库增补：中文释义 + IPA 音标）
+> 增补管线：`scripts/enrich_gloss.py`（ECDICT 匹配）+ `scripts/make_llm.py`（LLM 增补）+ `scripts/finalize_vocab.py`（音标格式统一 + 补常用词音标）
+
+## 一、现有数据
+
+| 文件 | 级别 | 主表词条 | 仅主题表补充词 | 合计 | 其中 B1 新增 | 来源 | 许可 |
+|---|---|---|---|---|---|---|---|
+| `a2-key-vocab.jsonl` | A2 Key / for Schools | 1727 | 13 | **1740** | — | 剑桥官方词汇表（2025-08 版） | `official-free` |
+| `b1-preliminary-vocab.jsonl` | B1 Preliminary / for Schools | 3055 | 117 | **3172** | 1517（`new_at_b1=true`） | 剑桥官方词汇表（2020 版） | `official-free` |
+| `word-sets.json` | A2+B1 通用 | — | — | 6 个词集 | — | Appendix 1（规则生成） | `official-free` |
+
+主题（topic）覆盖：A2 25 个 / B1 23 个（Clothes、Education、Food and Drink、Travel and Transport、Work and Jobs 等）。
+
+## 二、记录结构（每行一个词条）
+
+```json
+{
+  "id": "a2k-vocab-0091",
+  "level": "A2",
+  "headword": "attractive",            // 原样保留, 含变体斜杠 "café/cafe"、缩写 "(kg)"
+  "pos": ["adj"],                      // 词性数组; 多词词性整体保留: "phr v"/"prep phr"/"aux v"
+  "pos_notes": null,                   // 用法/地区注记: ["+ ing"], ["(Br Eng) (Am Eng: bathing suit)"], ["unc (uncountable)"]
+  "examples": [{"text": "The walls are an attractive colour.", "pos": null}],
+  "phrases": null,                     // 子短语/搭配: "(be) bad for somebody", "bright pink"
+  "topics": ["Clothes and Accessories"],   // 来自 Appendix 2 主题表
+  "origin": "main_list",               // main_list=字母序主表 / topic_list=仅出现在主题表
+  "no_pos": true,                      // 仅少数: PDF 原文无词性标注 (如 "film star")
+  "new_at_b1": false,                  // 仅 B1 文件: 该词不在 A2 词表 = B1 新增
+  "source": {"file": "...", "url": "...", "publisher": "Cambridge English / UCLES", "licence": "official-free"},
+  "gloss": {                           // P3.5 增补: 中文释义 + IPA 音标
+    "zh": "n. 苹果",                    // 带词性前缀的中文释义
+    "phonetic": "/ˈæpl/",              // 英式 IPA, 统一包裹为 /.../
+    "source": "ecdict",                // ★ 来源标注: "ecdict"=ECDICT 开源词典 / "llm"=LLM 生成
+    "licence": "CC-BY-SA-4.0",         // ecdict 对应 CC-BY-SA-4.0; llm 对应 llm-generated
+    "phonetic_source": "llm"           // 可选: 仅当音标由 LLM 补、释义来自 ECDICT 时出现
+  }
+}
+```
+
+## 三、下游 agent 使用须知
+
+1. **背单词优先序**（推荐）：A2 全部 → B1 中 `new_at_b1=true` 的 1517 词 → topic_list 补充词。两级共约 3257 去重词条。
+2. **例句仍是稀缺资源**：官方词表仅约 11% 词条带例句（A2 170 / B1 218 条），主要标注多义词的分用法。**中文释义与音标已通过 P3.5 增补进 `gloss` 字段**（见 §三·五），但例句本身未生成。
+3. **主题背诵**：`topics` 字段支持按场景刷词（如先攻 Food and Drink）；同一词可属多个主题。
+4. **词性坑**：`be` 的词性是 `["aux v","v"]`（PDF 原文缩写 "av"，按剑桥缩写表解释为助动词）；不可数名词注记在 `pos_notes`（如 rubbish）。
+5. **topic_only 词**（A2 13 / B1 117）：官方明确为"考生还应知道的补充词"（如 get dressed、climate change），无例句无主表词性，但 `pos` 可能来自主题表标注。
+6. **变体词头**：`trainers`（topic）与 `trainer`（主表）已按复数回退匹配；但 A2 主表无 trainer，故 A2 里 trainers 仍是独立补充词。
+7. **word-sets.json**：基数/序数/星期/月份/季节/大洲为确定性生成集；国家·语言·民族开放集合未枚举（官方用 etc.），需要时另行补表。
+8. **许可**：全部 `official-free`，可进部署门户；但 PDF 内的 "Additions in green"（2025 新增词标记）在文本层无颜色信息，未能结构化。
+
+## 三·五、P3.5 增补说明（中文释义 + IPA 音标）
+
+官方 PDF 无中文释义、无音标，本步补齐 `gloss` 字段（每条记录已写入，无遗漏）。
+
+**来源标注（用户要求：区分「原词条」与「LLM 增补」）**
+- `gloss.source = "ecdict"`：中文释义来自 **ECDICT** 开源英汉词典（CC-BY-SA-4.0），词典级数据，覆盖约 98%。
+- `gloss.source = "llm"`：ECDICT 未命中的残余词头（多为短语/复合词/剑桥多义分项，如 `deal with`、`smart (clever)`、`social media`），由 **LLM 生成**中文释义 + 音标（`licence: llm-generated`）。共 98 条记录（83 个去重词头）。
+- `gloss.phonetic_source = "llm"`（可选）：仅 97 条「释义来自 ECDICT、但 ECDICT 原条目缺音标」的常用单词，音标由 LLM 补、释义 provenance 不变。
+
+**覆盖统计（4902 条）**
+| 指标 | 数值 |
+|---|---|
+| `gloss` 覆盖率 | 100%（4902/4902） |
+| `source=ecdict` | 4804 条 |
+| `source=llm` | 98 条 |
+| 有音标 | 4576 条（93.3%） |
+| 无音标 | 326 条（6.7%，**全部为短语/多词**，如 `a few`、`alarm clock`） |
+
+**为什么短语留空音标**：学习者已掌握组成单词的发音，短语整体音标优先级低；若后续需要可单独补（g2p 模型或 LLM）。
+
+**管线与复现**
+```bash
+cd english-site
+python scripts/enrich_gloss.py match   # ECDICT 匹配 -> _gloss_cache/ecdict.json
+python scripts/make_llm.py             # LLM 增补 83 词 -> _gloss_cache/llm.json
+python scripts/enrich_gloss.py merge   # 合并写回 *.jsonl
+python scripts/finalize_vocab.py       # 音标统一 /.../ + 补 71 常用单词音标
+```
+> ECDICT 原始数据：`assets/vocab/ecdict/`（StarDict 格式，67MB，从 github release 经 gh-proxy 镜像下载）。清洗规则见 `enrich_gloss.py: clean_entry`（剥离词频/考试标签、西里尔 ә→ə、ASCII 撇号→IPA 重音符等）。
+
+## 四、已知局限（诚实披露）
+
+- ~~官方 PDF 无中文释义、无音标~~ → 已在 P3.5 通过 ECDICT + LLM 增补进 `gloss` 字段（见 §三·五）；仅 326 条短语（6.7%）因 ECDICT 无音标而留空，释义仍在。
+- `film star`、`zebra` 等 2 个 B1 词条原文无词性（`no_pos=true`），非解析丢失。
+- `driving/driver's licence` 等极少数跨行词头的地区变体注记可能不完整（已抽查主流 5 例均正确）。
+- B1 词表基于 2018 © 版本（2020 起生效），A2 基于 2025-08 版，两版之间 A2 的新增词（若 B1 版本更旧）不影响 `new_at_b1` 的判断方向，但个别词的归属可能滞后。
+
+## 五、复现
+
+```bash
+cd english-site
+python scripts/parse_vocab.py    # 输出到 data/vocab/, 隔离区 0 条, id 唯一校验通过
+```
+
+## 六、素材勘误（相对调研报告）
+
+- `assets/vocab/b1-preliminary-vocabulary-booklet.pdf`（8MB）**不是词表**，是《B1 for Schools 词汇教学活动手册》（教师用），保留作教学设计参考。
+- B1 官方词表直链 `cambridgeenglish.org/Images/506887-*.pdf` 已 404，改用 **cambridgeenglish.cn 域名**下载成功（文件已存 `assets/vocab/b1-preliminary-2020-vocabulary-list.pdf`）。