词库 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 等）。

二、记录结构（每行一个词条）

{
  "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 使用须知

背单词优先序（推荐）：A2 全部 → B1 中 new_at_b1=true 的 1517 词 → topic_list 补充词。两级共约 3257 去重词条。
例句仍是稀缺资源：官方词表仅约 11% 词条带例句（A2 170 / B1 218 条），主要标注多义词的分用法。中文释义与音标已通过 P3.5 增补进 gloss 字段（见 §三·五），但例句本身未生成。
主题背诵：topics 字段支持按场景刷词（如先攻 Food and Drink）；同一词可属多个主题。
词性坑：be 的词性是 ["aux v","v"]（PDF 原文缩写 "av"，按剑桥缩写表解释为助动词）；不可数名词注记在 pos_notes（如 rubbish）。
topic_only 词（A2 13 / B1 117）：官方明确为"考生还应知道的补充词"（如 get dressed、climate change），无例句无主表词性，但 pos 可能来自主题表标注。
变体词头：trainers（topic）与 trainer（主表）已按复数回退匹配；但 A2 主表无 trainer，故 A2 里 trainers 仍是独立补充词。
word-sets.json：基数/序数/星期/月份/季节/大洲为确定性生成集；国家·语言·民族开放集合未枚举（官方用 etc.），需要时另行补表。
许可：全部 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）。

管线与复现

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 例均正确）。

五、复现

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）。

7.3 KiB 原始文件 Blame 文件历史 Unescape Escape