# 词库数据来源与许可

`assets/words/wordbank.json` 由两份来源合成，两份的地位不同，处置方式也不同。

## 1. 等级与词表范围：CEFR-J Vocabulary Profile 1.5

- 决定**哪些词进词库、算哪一级**。
- 登记在 `tool/courses/lexicon/SOURCES.md`（版本、下载地址、SHA-256、许可原文），
  与 `tool/courses/pools/{a1,a2,b1}-word-pool.csv` 的生成用的是同一份数据。
- CEFR-J 本身**只有分级，没有释义、音标、例句、词频** —— 它是分级表，不是词典。

## 2. 音标：公开词书（有许可风险，未解决）

- 来源：<https://github.com/lilinji/English>，由 `tool/words/fetch.sh` 下载其中的
  入门级词书（KET、PET、小学/初中教材词表）。
- 许可：仓库标 CC BY-NC-SA 4.0，README 自称「整理自公开来源，仅供个人学习，严禁商用」。
  上游权利不明，**低于本项目 `SOURCES.md` 对课程数据的标准**。
- 结论：**自用、不分发，风险基本为零；一旦要分发或上架，这部分必须换掉。**
  换的时候只需要替换音标一列 —— 词表范围和等级由 CEFR-J 决定，释义和例句已经由 AI 重写，
  都不受影响。

## 3. 释义与例句：AI 重写（deepseek-flash）

- `tool/words/enrich_wordbank.py` 把词书释义当**参考**喂给模型，明确告诉它词书质量不稳定、
  可以推翻；模型返回主释义、次要义项、一个例句和例句中文。
- `tool/words/apply_enrichment.py` 校验后合并：释义为空、带括号、超过 10 个字的一律丢弃，
  保留词书原值。实际全部 2748 条都通过了校验。
- 结果缓存在 `ENRICH_CACHE` 指定的 jsonl 里，按 id 去重，中断可续跑，不会重复付费。
- 一次全量：输入约 10 万 token，输出约 63 万 token（模型会先推理，输出占大头）。

## 4. 词频：OpenSubtitles 计数（MIT）

- 来源：<https://github.com/hermitdave/FrequencyWords> 的 `content/2018/en/en_50k.txt`，
  仓库 MIT 许可，计数来自 OpenSubtitles 字幕语料。
- 决定**新词按什么顺序发给用户**。同等级内从最常用的开始，不按字母序。
- 为什么不用网页语料：先试了 `first20hours/google-10000-english`（公共领域），
  对词库只有 78% 覆盖，缺的全是 `ankle`、`ambulance`、`asleep`、`aspirin` 这类日常词 ——
  网页语料对口语词覆盖不好。字幕语料覆盖 97%，缺的只有 `bus stop` 这类多词短语。
- 多词短语取组成词里**最罕见**那个词的名次：短语不会比它最难的组成词更容易。
- `tool/words/add_frequency.py` 把名次写进 `rank` 字段；表里完全查不到的 11 个词
  排在本等级末尾。

排序效果：

| 等级 | 前 12 个词 |
| --- | --- |
| A1 | no not know just there here like get go right out about |
| A2 | it yeah even first name ever enough understand next dead actually bit |
| B1 | working rest able stupid sometimes sort serious scared hang bet beat calm |

## 合成规则

`tool/words/build_wordbank.py`：

1. 读 `tool/courses/pools/*-word-pool.csv`，只取 `status == pool` 且非虚词的词条；
2. 词书里的词只有落在词池里才进词库，**词书不能往词库里加词**；
3. 释义按词性拆分，优先匹配 CEFR-J 标注的词性，丢掉 `[美俚]` `<美>` 这类限定义项，
   去掉全部括号，每个义项取第一个逗号项；
4. 第一个义项进 `zh`（选择题答案），其余进 `more`（只在词条详情里显示）；
5. `add_frequency.py` 最后写入 `rank`，决定发放顺序。

## 现状

| 项 | 数值 |
| --- | --- |
| 词条总数 | 2748（A1 807 / A2 912 / B1 1029）|
| A1 词池覆盖 | 807 / 828 = 97% |
| A2 词池覆盖 | 912 / 1065 = 86% |
| B1 词池覆盖 | 1029 / 1557 = 66% |
| 有例句 | 2748（100%）|
| 有词频名次 | 2737（99.6%）|
| 有次要义项 | 2304 |
| 无音标 | 37 条 |

规格 5.4 要求覆盖率 ≥85%：A1、A2 达标，**B1 偏低**，因为只下了入门级词书，
补 B1 需要再下四六级一类的中高级词书。

## 释义缺陷的处置

词书原始数据有相当一部分词条只收了罕见义，规则清洗修不掉，全部由 AI 重写解决：

| 词 | 词书原值 | 现值 |
| --- | --- | --- |
| ticket | 加标签于；指派 | 票（次要义：罚单）|
| it | 信息技术information technology | 它 |
| check | 制止；检验 | 检查（次要义：核对；支票）|
| accept | 承认；同意；承兑 | 接受（次要义：同意）|

`apply_enrichment.py` 还会打印一份「需要人眼看一下」的例句清单：它用词干前缀判断例句里
是否真的用到了这个词，而 `teach → taught`、`bus stop` 这类变形和词组它判断不了，
所以只报告、不丢弃。最近一次是 9 条，全部核对无误。