Lampio 知识库

主题

词库 pipeline + 跨端 reseed 全景 ​

定位：vocabulary_builder_v3 构建引擎的架构知识 + 不变量 + 跨端数据流。 「怎么发布一个新词库」的动作流程见 skill preinstalled-db-update；本文是理解层（改引擎、加 stage、排查、跨端协同时读）。

1. 三组件关系（单向 producer→consumer 链） ​

build_all（构建引擎，产 pos_definitions 内容）
   │  output/reading_vocab.db
   ▼ 消费
preinstalled-db-update（RVH 发布者 skill：部署 assets + 验证 + 设备测 + 产 handoff）
   │  assets DB + docs/cross-end/NN handoff（sha + 版本 + 字段说明）
   ▼ 消费
vocab-reseed（RB 纯消费者 skill：资产 cp + 运行期 UPSERT + bump）
  • 无代码依赖耦合，唯一耦合点 = handoff 契约（byte-equal DB 文件 + sha + 版本 + 字段说明），artifact 级松耦合。
  • 非并列：有先后（RVH 先产 + 发布，RB 后消费）。
  • RVH = 生产者 + 自消费者（自己 app 也 reseed）→ 发布 skill 较"胖"；RB = 纯消费者 → reseed skill 较"瘦"。RVH 永无"纯消费别人 vocab"角色，故无对称纯消费 skill。
  • build_all 不单独做 skill：发布面知识已被 preinstalled-db-update 包住（Claude 可感知触发）；引擎内部知识在本文 + dartdoc（离代码近、不易漂；skill 会 stale）。

2. build_all pipeline（tools/vocabulary_builder_v3/bin/build_all.dart） ​

步stage产物调 LLM确定性何时跑
1wordlist_buildermaster_wordlist.csv否是建词库
2kaikki_parserkaikki_extracted.jsonl否是建词库
3data_mergercleaned_vocabulary.jsonl否是建词库
4enrich_translationstranslated_vocabulary.jsonl是（~$1/2h）否极少
5/5b/5cevaluate_cefr（opt-in --with-cefr-eval/--with-audit）回写 translated是否极少
5.5govern_qualitytranslated（纯治理 corpus）否是每次构建
5.55generate_examples（opt-in --generate-examples）data/generated_examples.json（缓存）是（~$1.2 全量）否按需（新增词/改 gloss）
5.6apply_example_cacheapplied_vocabulary.jsonl（corpus+llm+source）否是每次构建
6generate_dboutput/reading_vocab.db否是每次构建

关键分层：内容生成（步 1–5，贵、极少跑）/ 减法治理（5.5，每次）/ 例句生成（5.55，按需、调 LLM）/ 铺缓存+导出（5.6/6，每次、确定性）。

3. 文件数据流（三层库） ​

构建期：master_wordlist/kaikki ─步1-4→ translated_vocabulary.jsonl（纯 corpus，gitignored）
        + data/generated_examples.json（LLM 例句缓存，★提交进仓库★ 确定性锚点）
        ─步5.6→ applied_vocabulary.jsonl（corpus+llm+example_source，gitignored）
        ─步6→ output/reading_vocab.db ─cp→ assets/databases/reading_vocab.db（★提交★ byte-equal 源）
运行期：app 启动 → app_database UPSERT(word) → 用户 app_flutter/reading_vocab.db（活库，被外键引用）
跨端：  RB 收 handoff → cp 进 src-tauri/assets → 运行期 helpers.rs ON CONFLICT UPSERT

4. 不变量（改引擎时绝不可破坏） ​

  1. 🔒 确定性：LLM 例句只固化一次进提交进仓库的缓存；generate_examples 默认不在 build 跑（须 --generate-examples），仅补未缓存 sense（key = word|pos|fnv1a(normGloss)）。否则内容每 build 漂 → byte-equal 库变 → RB 无限 reseed。
  2. translated 永远是纯 corpus：apply 写独立 applied_vocabulary.jsonl，绝不回写 translated。否则下次 govern 会把 llm 例句当 corpus 重治理 / 误标 source。generate_db 读优先级 applied > translated > cleaned。
  3. 缓存提交、output gitignored：data/generated_examples.json（确定性锚点）必提交；output/ 是临时产物。
  4. 新字段须模型穿透：pos_definitions 经类型化 SenseDefinition.toJson() 重序列化，未知字段会被丢——加字段须同时改 lib/models/vocabulary_entry.dart + bin/generate_db.dart::_entryFromJson（如 v52 value_tier、v15 example_source）。
  5. byte-equal 三端共用：DB 文件 sha 每 build 变（created_at 时间戳），但 pos_definitions 内容 sha 稳定；RB reseed 比内容，handoff 给文件 sha 仅供完整性校验。

5. 使用场景 → 命令 ​

场景命令（cd tools/vocabulary_builder_v3）调 LLM
改治理规则dart bin/build_all.dart --from 6否
新增词 / 改 glossdart bin/build_all.dart --from 6 --generate-examples是（增量）
换 LLM 模型 / 翻译语言dart bin/build_all.dart（全量）是（全量）
验证确定性连跑两次 --from 6 比对 pos_definitions sha否

发布（部署 assets + bump 版本 + 设备测 + handoff + commit）走 skill preinstalled-db-update。

6. 例句治理 + 生成设计（v14/v15） ​

  • 治理（减法，GDEX 式）：例句丢 <15/>150、多句、含换行/" / " 诗行、古拼写（long-s/thou/hath/-eth/精选古语-est）、书目引文、OCR 残留；每 sense 取优 ≤3。义项每 POS 封顶 5、丢 archaic + 双重空保护（POS 空保护 + 词级 zh 锚点保护保词数不掉）、近义去重、裁剪 gloss。
  • 生成（加法，LLM）：deepseek-v4-flash，按词喂全义项让其对比区分近义；为每个 sense 生成 1–2 条短·现代·贴义例句（生成 + 评审区分度两遍），不可区分义留空（宁缺毋滥）。
  • 混排：apply 时 corpus 在前、llm 在后，cap≤3，预留 ≥1 llm 槽；写 example_source 平行数组（["corpus","llm"]）。
  • 效果：词数 12291 不变、例句 >150=0、95% 义项有例句。

7. 如何扩展 ​

  • 加治理规则：改 lib/quality_governor.dart（纯函数）→ --from 6 验证。
  • 加 example 字段/标签：改 SenseDefinition + generate_db._entryFromJson（不变量 4）。
  • 加翻译语言：config.yaml target_languages + 重跑 step 4（贵）。
  • 加 pipeline stage：在 build_all 按 5.5/5.6 范式 _runDartScript；必跑步骤放 Step 6 前，opt-in 加 flag。

8. 关联 ​

  • 发布动作 skill：.claude/skills/preinstalled-db-update/SKILL.md
  • RB 消费 skill：~/reading-browser vocab-reseed
  • pipeline dartdoc：tools/vocabulary_builder_v3/bin/build_all.dart 头部
  • 历次交接：docs/cross-end/04-*（v14）、05-*（v15）
  • plan：docs/plans/pos-definitions-quality-governance.md（v14）、pos-definitions-governance-v15-examples.md（v15）
  • 红线 #5e（lemmatizer/词库 byte-equal）：CLAUDE.md