上海小初高英语词汇（shanghai-k12-english-vocab）
覆盖上海市小学 / 初中 / 高中三个学段的英语词汇查询与学习辅助 Skill。
可输出全部词汇、单词音标与释义详情、上海课标语法大纲、功能意念（使用场景）总表，
并支持导出 Anki / CSV / Markdown 词表，以及随机抽测、默写自测。
> 离线可用：所有词表已解析为本地 data/*.json，不依赖网络。
一、何时使用
- 想浏览或搜索上海某学段的英语单词（按字母、按学段）。
- 查某个单词的音标、词性、释义，并知道它属于哪个学段。
- 需要上海课标语法大纲（语音 / 词法 / 句法 / 构词法，按学段分级）。
- 需要功能意念项目（使用场景）总表，按场景背词。
- 想导出词表导入 Anki 复习，或生成 CSV / Markdown 清单。
- 想做随机抽测 / 默写自测。
二、数据来源与准确性说明（重要）
| 学段 | 词条数 | 含英式音标 | 来源说明 |
|---|---|---|---|
| 高中 | 1733 | 1710 | 真·上海官方：上海招考院《英语词汇表》2019 版（shmeea.edu.cn/download/20190926/07.pdf，标题即「英语词汇表」，普通高中高考官方词表）。逐词解析 1731 词，含大小写/缩写变体共 1733 条。注：网传「上海高考约 4300 词、必含 inevitable/dilemma 等学术词」多来自教辅词汇手册（出版社）扩充，非招考院官方文档本身；官方文档即此规模、且不含上述部分学术词。 |
| 初中 | 1248 | 1248 | 推荐版 / 待校正：基于上海初中中考大纲核心词框架 + 沪教牛津上海版整理，非逐词官方/教材版；待用户提供上海教辅/学校词表后校正。 |
| 小学 | 479 | 479 | 推荐版 / 待校正：基于上海小学课标核心词框架 + 沪教牛津上海版整理，非逐词官方/教材版；待用户提供上海教辅/学校词表后校正。 |
诚实标注：
- 高中词表为真·上海官方来源（招考院发布），可追溯、可核验；其余学段为推荐版，明确标注待校正。
- 初中 / 小学为核心词框架近似版，并非教材逐词全量版；若需某校某册逐词版，需另行采集上海教材/教辅词表替换（投递入口见仓库内 .dev/shanghai-k12-english-vocab/data/sources/user_provided/）。
- 音标全部为英式（RP）发音，已统一生成：优先采用 ipa-dict 的 en_UK 金标准英式词典（约 6.5 万词，高置信）；该词典未收录的词由 espeak-ng（en-GB，离线 WASM）生成英式音标兜底（中置信）。原值保留在 phonetic_original，每条标注 phonetic_source 与 phonetic_confidence。详细方法见 data/PHONETIC_REPORT.md。
- 重音记法已统一为学习者词典惯例（OALD / 剑桥风格）：重音标记 ˈ 标在重读音节的音节起始（声母之前），如 about /əˈbaʊt/、computer /kəmˈpjuːtə/；单音节词不标重音，如 red /red/、blue /bluː/。次重音 ˌ 保留（如 international /ˌɪntəˈnæʃənəl/）。
- 沙箱环境外网出口对 Wiktionary / Free Dictionary 等实时 API 为硬封堵，故未采用在线核验；改用可稳定下载的 en_UK 词库 + 本地离线 espeak-ng 生成。
- 高中 23 个词条（多为专有名词 Australia/Britain/England 等，及 contact/detail/survey/recognize 等 en_UK 未收录词与少量解析碎片 bund/caf）暂无英式音标，查询时提示「见教材」，后续校正补齐。
- 跨学段重叠词（如 able）在 lookup 中会同时列出其所出现的多个学段条目，属正常行为。
三、功能一览
| 功能 | 子命令 | 说明 |
|---|---|---|
| 各学段统计 | stats |
词条数、含音标数、实际数据来源 |
| 列出数据源 | sources |
内置套件 + --data-dir 下用户套件（词数/来源/是否官方） |
| 浏览全部词汇 | browse |
按学段 / 首字母 / 年级筛选，可限条数 |
| 单词详情查询 | lookup <word> |
音标、词性、释义、所属学段、来源标记 |
| 导出词表 | export |
格式 anki(TSV) / csv(UTF-8 BOM) / md |
| 随机抽测/默写 | quiz |
zh 给释义猜词 / en 给词猜释义；加 --ipa 可在题面与答案附英式音标 |
| 导入用户词表 | import |
CSV/TXT/JSON 归一化 → 写入用户套件 |
| 语法大纲 | grammar |
按学段打印词法/句法/构词法（详见 references/grammar.md） |
| 使用场景 | scenarios |
功能意念项目 40 项总表（详见 references/scenarios.md） |
> stats / browse / lookup / export / quiz 均支持 --set <id> 与 --data-dir <目录> 选择数据源（见下方「数据源可插拔」）。
四、使用方法
所有功能通过 scripts/query.py 调用（Python 3，无第三方依赖）。
PY=python3 # 或本机 python3
cd <skill_dir>
# 1) 统计
$PY scripts/query.py stats
# 2) 浏览：高中 A 开头前 10 个
$PY scripts/query.py browse --level 高中 --letter a --limit 10
# 3) 查词：able（会列出其出现的各学段条目）
$PY scripts/query.py lookup able
# 4) 导出 Anki（TSV，可直接导入）
$PY scripts/query.py export --format anki --level 高中 --out senior_anki.tsv
# 5) 导出 CSV（Excel 友好，带 BOM）
$PY scripts/query.py export --format csv --level 初中 --out junior.csv
# 6) 导出 Markdown 清单
$PY scripts/query.py export --format md --level 小学 --out primary.md
# 7) 随机抽测：初中 10 题，给释义猜词
$PY scripts/query.py quiz --level 初中 --n 10 --mode zh
# 7b) 带音标的抽测：初中 10 题，给单词猜释义（题面含音标）
$PY scripts/query.py quiz --level 初中 --n 10 --mode en --ipa
# 8) 语法大纲（按学段）
$PY scripts/query.py grammar --level 高中
# 9) 使用场景（功能意念项目）
$PY scripts/query.py scenarios
数据源可插拔（选用 / 导入自己的词表）
默认使用内置套件 builtin。要使用自己的词表，把它放到技能目录之外的目录，再用 --set + --data-dir 指定（无默认目录，须显式指定）：
# a) 查看可用数据源（内置 + 指定目录下的用户套件）
$PY scripts/query.py sources --data-dir ~/my-shanghai-vocab
# b) 导入自己的词表（CSV/TXT/JSON）为用户套件 my-gk 的高中数据
$PY scripts/query.py import ~/my-shanghai-vocab/gaokao.csv \
--set my-gk --level 高中 --data-dir ~/my-shanghai-vocab
# c) 选定用户套件查询（该套件未覆盖的学段自动回退内置）
$PY scripts/query.py stats --set my-gk --data-dir ~/my-shanghai-vocab
$PY scripts/query.py browse --level 高中 --limit 20 --set my-gk --data-dir ~/my-shanghai-vocab
- 目录结构：
<data-dir>/<套件id>/{primary.json, junior.json, senior.json}。 - 解析优先级：用户套件 > 内置，且按学段逐级回退（用户套件只含高中时，小/初自动用内置）。
import支持的输入：.csv（表头word,pos,meaning或首三列）、.txt（每行一条，可word<Tab|,|，>pos<sep>meaning）、.json（标准 schema 或[{word,pos,meaning}]）。同词若内置词表已有音标会自动复用；可另加--ipa-dict <en_UK.txt>补充。
导入 Anki 说明
export --format anki 输出 TSV，表头为 word\tphonetic\tpos_meaning\tlevel。
在 Anki 中「文件 → 导入」，选择该 TSV，字段用 Tab 分隔，word 设为正面、phonetic+pos_meaning 设为背面即可。
五、目录结构
shanghai-k12-english-vocab/
├── SKILL.md
├── data/
│ ├── primary.json # 小学 479 词
│ ├── junior.json # 初中 1248 词
│ ├── senior.json # 高中 1733 词（真·上海官方）
│ └── PHONETIC_REPORT.md # 音标生成方法与置信度说明
├── scripts/
│ └── query.py # 查询引擎（唯一运行时脚本）
└── references/
├── grammar.md # 上海课标语法大纲（词法/句法/构词法，分级）
└── scenarios.md # 功能意念项目（使用场景）40 项总表
> 工程侧文件不随包发布：官方词表 PDF、原始解析产物、构建脚本、ipa-dict 词典、QA 报告等已迁至仓库内 .dev/shanghai-k12-english-vocab/（已加入 .gitignore）；本 Skill 的工作原理文档（运行原理.md + 三张配图）位于仓库级 <repo>/00docs/shanghai-k12-english-vocab/。二者均为工程资料，不进发布包。用户补充词表走「数据源可插拔」：投放到自己的目录并用 --data-dir 指定，或用 import 导入。
数据 schema（data/*.json）
{
"meta": { "level": "高中", "source": "...", "phonetic_source": "...", "count": 1733, "shanghai_official": true },
"words": [
{ "word": "about", "phonetic": "/əˈbaʊt/", "phonetic_original": "/ɐbˈaʊt/",
"phonetic_source": "ipa-dict:en_UK", "phonetic_confidence": "high",
"level": "高中", "grade": "高考", "source_tag": "shmeea官方上海高考词汇表(2019版)",
"senses": [ { "pos": "adv", "meaning": "大约；到处，四处" } ] }
]
}
> phonetic 为归一化后的标准英式音标（重音在音节起始、单音节不标重音）；phonetic_original 为来源词典原值，便于回溯。
六、注意事项与边界
- 本 Skill 为离线词表查询与学习辅助，不连接任何生产环境或外部 API。
- 初中 / 小学词表为权威核心框架版，非教材逐词全量；若用户要求「某校某册逐词版」，需另行采集教材词表（当前未覆盖）。
quiz为本地随机抽样的自测卡，不持久化成绩。- 数据源可插拔：默认用内置套件；使用者可把自己的词表放到技能目录之外的任意目录，用
--set <id> --data-dir <目录>选用（无默认目录，须显式指定）。解析优先级：用户套件 > 内置，按学段逐级回退。 - 用户数据必须放技能目录外：发布包受扩展名白名单与单文件 1MB 限制，且安装目录只读托管。
import只接受结构化格式（CSV/TXT/JSON）；PDF 教辅需先转文本。解析/构建脚本在仓库内.dev/shanghai-k12-english-vocab/scripts/（已 gitignore）。
