Lampio 知识库

主题

12 · 词源 / 助记 etymology reseed 交接（RVH → RB） ​

RVH 段一交付：接 RB 消费契约 ~/reading-browser/docs/cross-end/12-etymology-handoff.md， 在预装库 pipeline 离线生成 word 级 vocabulary.etymology（原 0 填充），烤进 reading_vocab.db。 日期：2026-06-15 · RVH Schema v54 不变 / 预装 v19→v20 · 优先级 P3（纯展示增强，不阻塞匹配/同步）

TL;DR（RB 要做的 2 件事） ​

  1. 复制预装库：reading_vocab.db 整包覆盖（新 SHA c81d137492…），VOCABULARY_SEED_VERSION 升 v20。 走 RB /vocab-reseed（merge 路径即可，无 PK 变化、无 prune）。 ⚠️ 唯一比 ⑤ 多的一步：etymology 是独立列（区别于 ⑤ 走 pos_definitions JSON 内部）—— RB merge SQL 的 DO UPDATE SET 必须新增 etymology = excluded.etymology，否则远端词源拉不下来。
  2. 接段二渲染（另起 RB 会话）：dictionary.rs/srs.rs SELECT 加 etymology 列 → 解析 JSON → DictEntry/DueCard 加 word 级字段；新组件 EtymologyAction.tsx（贴词头，复用 ⑤/④ 收起 chip 原语）。 可顺手做「词族 chips」（word_family 4408 词已填、未露出），与来历同区展示。详见 RB docs/plans/archive/etymology-mnemonic-plan.md。

纯 additive：新增一个早已 reserve 的 word 级列内容。 无 schema 变更、无资产变更、无 PK 变更、无 prune、不进 Supabase 同步矩阵（红线 #10）。

§1 数据落点 & 形状（契约本体回执） ​

word 级 etymology 列存 JSON 字符串（一词一条；NULL = 无确证可用词源，宁缺毋滥）：

jsonc
{
  "summary_en": "From Latin 'benevolens', from 'bene' (well) + 'volens' (wishing) — 'well-wishing'.",
  "summary_zh": "源自拉丁语 benevolens，由 bene（好）和 volens（意愿）组成，意为“好意的”。",
  "roots": [                              // 可选；仅「可拆出真实词根」的词给，习语/不可拆词省略
    {"root": "bene",   "gloss_zh": "好"},
    {"root": "volens", "gloss_zh": "意愿"}
  ]
}
  • 键序固定（byte-equal 保序）：summary_en → summary_zh → roots；root 内 root → gloss_zh。
  • summary_en / summary_zh 必填（非空才落库；任一缺失则整列 NULL）。
  • roots 可选数组：仅真实可考词根（Latin/Greek/OE…）；习语 / 不可分析词省略该键（只给 summary）。
  • 整列可空：词源不清晰 / 不可考 / trivial 的词 etymology = NULL。RB 据「列非空」决定是否渲染入口。
  • 习语用 origin story（summary 写在 canonical_surface 形态语境下），省 roots。

习语示例（origin story + hedge）：

jsonc
// kick the bucket（canonical_surface 形态）
{"summary_en":"Origin uncertain; one theory is that it refers to a person standing on a bucket to hang themselves, then kicking it away.",
 "summary_zh":"确切来源存疑，一说指上吊时踢开垫脚的水桶。"}

§2 反 folk etymology 纪律回执（契约 §3.3 铁律 — 已落地验证） ​

机制落地
规则层黑名单 + acronym-claim 检测posh/golf/tip/SOS/"Port Out…"… 未 hedge 即丢（35 词被规则拦截）
Pass2 对抗式事实核查（v4-pro temp 0）「此词源是否确证？有无 folk/acronym myth？」显式 reject → NULL（498+88 词拒）
不确定 → 显式 hedge 或留 NULL来源存疑词 summary 标「确切来源存疑/一说…」，或整列 NULL

全库扫描实证：12743 条非空 etymology，0 bad JSON / 0 folk 泄漏（acronym marker 未 hedge = 0）。 陷阱词 posh / golf / tip 全数 NULL ✓。

§3 预装库变更 ​

旧（v19）新（v20）
reading_vocab.db SHA256e180784393f4ffe72f770488cb62a46a0c817041d9deb4b1af815bda5f541d38c81d137492bd4a20bc14fbb697ad441d6d5868b4531c7e92c12c50be76c0f4ba
_preinstalledVocabVersion1920
总词数1889918899（不变）
Schema 版本v54v54（不变，etymology 列早在 baseline）
etymology 非空012743（单词 7470 / 习语 5273）
含 roots010267 词 / 18275 个词根

DB 文件 sha 每 build 变（created_at 时间戳）属正常；RB reseed 比内容，文件 sha 仅供完整性校验。

§4 生成方法（确定性 / 红线 #10） ​

  • 候选范围：习语全量 + CEFR B2/C1/C2 + B1 长词（len≥7）；功能词 / 低 CEFR 短词 / 不可考词留 NULL， 不硬凑覆盖率。（已知取舍：CEFR×词长代理会漏掉个别有词根的低 CEFR 常用词如 telephone/transport。）
  • 模型：deepseek-v4-pro、temperature 0、response_format: json_object；Pass1 生成 + Pass2 对抗核查。
  • 确定性：LLM 输出固化进提交进仓库的缓存 tools/vocabulary_builder_v3/data/etymology.json， 禁止每 build 调 LLM；generate_db 按 emoji 同款 word 级模式回填 etymology 列（非 jsonl-apply）。 连跑两次 generate_db → etymology 内容 byte-equal（已验证）。
  • 成本：首跑 $3.50 + 召回重跑 $0.62（一次性）。

§5 给 RB 的实现提醒（段二） ​

  1. merge SQL（关键）：DO UPDATE SET … , etymology = excluded.etymology（系统列、幂等覆盖； ⑤ 走 pos_definitions 内部不需要此行，⑦ 是独立列必须加）。
  2. dictionary.rs::lookup_word SELECT 加 etymology；解析 JSON → DictResult 加 word 级 etymology 结构字段。srs.rs::get_due_cards DueCard 同加（复习背面用）。
  3. types/index.ts：Etymology { summary_en; summary_zh; roots?: {root; gloss_zh}[] } + DictEntry/DueCard 加字段。
  4. 渲染 = word 级一次（贴词头 headword/IPA 区，不进 PosGroupBlock）；en 斜体 / zh 正体 / roots 一行。 入口 v1：Library 详情词头 + 复习卡背面；查词弹窗留 v2。不 opt-in（静态数据）。
  5. 解析须容错：未知键忽略、roots 缺失正常、整列 NULL → 不渲染入口。

§6 关联 ​

  • RB 消费契约：~/reading-browser/docs/cross-end/12-etymology-handoff.md
  • RVH 代码：tools/vocabulary_builder_v3/{lib/etymology_cache.dart, lib/etymology_generator.dart, bin/generate_etymology.dart} + bin/generate_db.dart::_applyEtymologyMapping（emoji 同款回填）
  • 缓存（提交进仓库）：tools/vocabulary_builder_v3/data/etymology.json
  • 前序交接：⑤ 10-synonym-differentiation-reseed-handoff.md
  • RB 消费侧 skill：~/reading-browser /vocab-reseed