Library Distillation

术-内容 · 术层 skill 全文

本页是 <code>rules/skills/workflow_library_distillation.md</code> 的逐字投影（仅隐私清洗，零改写）。

Workflow: Library Distillation

2026-05-31 重大更新：作者忠实度优先 + 写时 verify-gate（新方法，已实证）

基于实测：旧 8-phase 产物只有约 20% 作者扎根、80% 编辑物，R / A1 / B 在多个 skill 间逐字节相同模板；Phase 4 的 3110 个合成 test-prompts 从未被任何 runner 执行（画靶射箭，should_trigger 是 A2 语言信号逐字复制），事后两两正交审计不落地。三本代表书（Out of the Tar Pit / Gödel Escher Bach / A Pattern Language）用新方法 + Codex 全量重蒸 + 盲审验证：作者忠实度 8.0/10，客观逐字核验 97-100%（旧方法 0% 可核验）。证据与评价见 adhoc_jobs/distillation_newmethod_trial_20260531/EVALUATION_AND_WORKFLOW_UPDATE.md，方法全文 tmp/distill_newmethod/METHOD_v3.md，更新历史 WORKFLOW_UPDATE_HISTORY.md。

新方法的核心改动（取代下方 Phase 2 / 4 / 5 的对应做法）：

1. 写时逐字纪律 + 硬 gate：R / A1 必须从源文逐字复制 + 给行号；写完由 library_distillation_verify_citations（独立确定性脚本，非 LLM 自评）核验，PARAPHRASE / MISCITED 必须修或老实标 PARAPHRASE（去引号去行号）。这是缺失的「误差信号」，替代不可靠的自我回望（实测 Codex 自报零问题但实际 86% 转述冒充逐字）。
2. 道术矩阵：用作者「问题 → 解法」结构组织（行 = 作者问题 / 道，列 = 术 + 作者招牌诊断信号）。正交性从矩阵位置读出（同格 MERGE / 相邻格 COMPOSES 且引作者亲手写的链接 / 异行天然正交），不做 Phase 4 的事后两两 should_trigger 交叉审计。
3. 取消合成 test-prompts：改为每条 skill 的机械锚 mechanical_anchors.md（≥2 条确定性可核验 positive + ≥1 条 decoy）；触发正确性与有效性差异交 Harness 层 differential oracle（loop3/4/5 协议：paired skill-blind vs skill-loaded、fresh-agent routing probe），不在写 skill 阶段造虚拟场景。研究依据 TESTCASE_RESEARCH_BRIEF.md。
4. 大书分块：单次蒸馏 source ≤ ~40K tokens（实测一次喂 272K → 86% 转述冒充逐字；按 ~43K / chunk → 99.4% 逐字）。
5. skill 内容再平衡：E 段（含 输入 / 输出 / 每步判停）为主体；R 真引文（不截断）+ A1 作者真实例；与相邻 skill 的区别压成一行指针指回矩阵（不在 skill 体内重复三遍）；现代 / 编辑性 caveat 显式标 editorial（非作者原文）。

下方 Phase 4 的「合成 test-prompts」和「事后两两正交审计」标记为 deprecated（保留历史，不再作为默认路径）。Phase 0 多路 critique、Phase 1.5 source contract 判断层、Phase 3 关系图保留有效。

把以上并入下方逐 phase 正文 + 同步 tools/library_distillation/prompts/phase*.md 的全面重构走 version-manager + reference_validator，待用户确认后执行（本次先做顶层更新 + 工具落地 + 实证，不静默改写全部 phase 文本）。

运行入口（新方法 phase-split 管线，2026-05-31 落地，按名见 tools/INDEX.md）：tools/library_distillation/v3_run.sh 编排 v3_p0_split（切 ≤40K chunk）→ v3_p1_distill（Codex primary + Kimi fallback，不用 GLM/zai，每 chunk checkpoint 断点续传）→ v3_p2_verify（verify_citations gate + repair ≤2 轮）→ v3_p3_assemble（汇编到 draft track v3/）。误报限额 bug 已修（router.py 成功路径不再扫 rate-limit 短路 + quota_state.py 先解析 ISO 绝对日期）。

When to Use

当一本书从"读过但调不出来"需要转化为 agent 或人可直接调用的认知单元时走本 workflow。

• 输入：原书 PDF / EPUB / .txt / .md 可以先放在 tmp/ 或 temp/。若源文件仍在临时目录，必须先走 library_distillation_distill_from_tmp plan/run；若已经在 contexts/library/<书 slug>/source_original/，进入切章前必须先由 library_distillation_prepare_source 生成或确认 canonical UTF-8 source text
• 输出：rules/skills/drafts/<书 slug>/ 下的 axioms/、skills/、meta_skills/、INDEX.md
• 适用：方法论书、技术规范书、决策框架书、控制论 / 系统论书、软件设计书、投资 / 管理思想书
• 不适用：散文集、回忆录、纯叙事文学、Wikipedia 条目综合版、二手书摘 —— 缺少可形式化骨架命题、缺少可回溯 anchor

Prerequisites

按名引用工具，路径查 tools/INDEX.md。

• 主 agent：深度推理模型，负责设计、写作、质量验证 —— 三项不外包
• Sub-agent CLI：Anthropic-compatible wrapper（claude-zai 或 claude-kimi，quota 充裕者用之，本 workflow 任务上功能等价）
• Codex provider：可用 CI_DISTILL_CLI=codex:medium / codex:high 跑 Phase 0-1.5；Codex 产物通过 artifact block materialization 落盘，不直接依赖交互式 Write 工具
• library_distillation_distill_from_tmp：自然语言 session 入口。发现 tmp/ / temp/ 中的 PDF / EPUB / TXT / Markdown，生成 intake plan，执行 move/copy、source preparation、split、Phase 0-1.5、Phase 2-5、generated status update，并通过 doctor 输出恢复命令
• library_distillation_prepare_source：PDF / EPUB / TXT / Markdown source preparation。PDF 先用 pdftotext -layout，文本层不足时 fallback 到 pdfimages + macOS Vision OCR helper；EPUB 用 stdlib OPF/spine 解析
• library_distillation_check_status / update_global_status：完成后统一做 filesystem scan、generated JSON/Markdown status 和 drift check
• token_estimator：分组前估 token
• reference_validator：文件移动 / 重命名时保持引用同步
• todo：记录遗留任务、补做、opt-in 扩展
• 并发纪律：主流 wrapper 并发上限约 5，超过易触发 provider 限流；按"并发上限 = 每波 sub-agent 数"规划
• 单 sub-agent 输出纪律：输出越长越易卡死；任务设计让单次输出规模明显小于已观测 stuck 过的规模，不设绝对字节上限

Tmp Intake Gate

当用户的自然语言请求包含“书在 tmp/ / temp/ 里”“帮我蒸馏这些书”“新 session 开始后处理书籍”等场景，第一步不是跑 run_book.py，而是先做 tmp intake。

第一动作：

python3 tools/library_distillation/distill_from_tmp.py plan --recent-hours 48

若 plan 中 slug、目标路径、replace 行为清楚，才执行：

python3 tools/library_distillation/distill_from_tmp.py run \
  --source <tmp/source.pdf-or-epub> --slug <book_slug> --name <canonical_name> \
  --provider codex:medium --track codex_v6 --max-parallel 2 --yes

若只需要验证 intake / TXT conversion，不进入长蒸馏，使用 --prepare-only --yes。

低负担 agent loop：新 session 不要把整套 Phase 细节一次性放进工作记忆。先执行：

python3 tools/library_distillation/distill_from_tmp.py plan --recent-hours 48 \
  --write-plan tmp/library_distillation_intake_plan.json --json

只检查 plan 的 blocked、slug、canonical_name、destination_path_relative、replace_requested。若是新 slug，主 agent 先统一更新 contexts/library/INDEX.md；每本书的 worker / sub-agent 不改这个共享书单。若 blocked 为空且来源文件符合用户要求，直接执行：

python3 tools/library_distillation/distill_from_tmp.py run \
  --plan-file tmp/library_distillation_intake_plan.json --yes

完成或中断后再运行 doctor。不要在 doctor 报缺口之前手工跳进 Phase 0-5 的内部状态。

硬条件：

• run 前必须能说明每个源文件对应的 book_slug、source_original/ 目标路径，以及是否会替换已有文件。
• 新 slug 必须登记到 contexts/library/INDEX.md，状态可先标为“从 tmp 入库 / 蒸馏中”；完成后再改为已蒸馏。doctor 会把缺失登记报告为 warning。
• 存在同名目标文件、多个可能 slug、或新旧版本替换风险时，不自动覆盖；先让 plan 暴露阻塞，再由用户或主 agent 明确 --replace。
• Phase 0 不得早于 source_ingest.json、SOURCE_INGEST.md、source_preparation.json、SOURCE_PREPARATION.md 和 source_original/manifest.json。
• 每个通过 tmp intake 启动的书籍必须有 contexts/library/<slug>/process/DISTILLATION_RUN.json；中断后先运行 distill_from_tmp.py doctor --slug <slug>，再按 repair commands 补齐。
• 同一本书不得同时启动两个 tmp-intake runner 或两个 Phase 0-1.5 runner；同一书同一 track 不得同时启动两个 Phase 2-5 runner。distill_from_tmp.py / run_book.py / run_phase2_5.py 有 lock file 防线，但调度上仍应先查进程和 doctor，避免重复恢复。

Source Preparation Gate

Distillation 的第一层确定性检查是 source preparation，不再要求 agent 手工判断 PDF / EPUB 该怎么转 TXT。

成功条件：source_original/ 至少存在一个可用 .txt / .md；若只有 PDF / EPUB，library_distillation_prepare_source 必须生成 .txt、source_preparation.json 和 SOURCE_PREPARATION.md，记录 method、输入路径、输出路径、文本统计、OCR fallback 和 warning。split_book.py 只消费已准备好的 text。

PDF 策略：优先 pdftotext -layout，因为它保留页内布局且成本低。若 text layer 为空、极短或字母数字密度异常低，转入 OCR fallback。OCR 产物足够用于搜索、切章和蒸馏；exact quotes、公式、页码、表格仍需回查原 PDF。

EPUB 策略：按 OPF spine 顺序提取正文，避免按 ZIP 文件名乱序。若 EPUB spine 缺失，才退回 HTML 文件名排序，并在 source_preparation.json 中留下 method details。

验收边界：source preparation 只证明 text 可用，不证明章节切分完美。OCR 噪声、跨页断行、图表公式损坏要进入 Phase 0 summary / source contract caveat，而不是在 source preparation 阶段伪装成 clean source。

Provider Runtime Handling

Provider failure 是运行时状态，不应污染书籍完成事实。

• Provider、模型 alias、quota scope 和 fallback chain 以 llm_runtime 为准，不在 workflow 文档中硬编码模型 ID。
• Rate-limit / quota 文本使任务回到 pending，retry budget 保留，并写入 quota state；后续由恢复运行或 watchdog 接手。
• provider_watchdog 只覆盖 Phase 0-1.5 的 run_book.py / run_all.sh。Phase 2-5 必须看目标 track STATE.json、gate artifacts 和 generated status。
• Codex provider 必须通过 durable last-message 和 artifact block materialization 交付文件。若 timeout 前已经在 JSON event log 中输出合法 artifact block，adapter 可用同一套路径安全规则救援落盘；rc=0 但无 final message / artifact 属于 empty delivery，可重试，不能计为业务完成。
• 如果目标输出文件已经非空但 subprocess 最后 rc != 0，任务可计为 done，但 STATE.json 必须保留 rc=<n> but output present; accepted。最终状态应标为 warning / recovered，而不是 clean run。
• 每次完成或恢复后运行 library_distillation_update_global_status --write，交付前运行 --check。旧人工表不作为当前事实源。

Reading Strategy for Large Books

原书 100K+ tokens 时主 agent 不直读全书原文，否则 context 被原文吃掉，设计 / 写作 / 验证无余地。

主 agent 读什么：BOOK_OVERVIEW.md、各章 summary、候选清单的结构化字段（tier / anchor 等，不含大段原文）、合并产物。原文 raw text 不读。

原文读取 delegate 给分章 sub-agent：先用 token_estimator 估总 token 和每章 token；按保序装箱分组（preserve-order chunking，非 token 降序）保章节连贯；每组大小让 sub-agent 一次读完且有余量产结构化输出；sub-agent 只回传结构化产出（摘要 / candidate / local concept 列表），不回传原文。

Context 预算分配（参考比例）：设计 + 编排约 15%；写作（RIA++ / INDEX / meta-skill）> 50%；验证 + 收尾约 20%；剩余 buffer 给分派 prompt 和中间产物阅读。

降级策略：主 agent context 超过 70% 时停止写新 RIA++，将剩余候选持久化到 process/remaining_candidates.md。单 session 不够时中间产物全部落盘（process/ 目录），分 session 续跑，下一 session 从磁盘读，不依赖对话历史。超大书（200K+ tokens）默认分 2–3 个 session：Phase 0–1B / Phase 1.5–2 / 验证 + 晋升。

Orchestration Cheatsheet

Phase 0:   N 章节摘要 + 多路 critique (并行)
Phase 1A:  主 agent 写 anchor_list; N distributed-scan + 主 agent merge
Phase 1B:  M extractor (M = 章节组数, ≤并发上限)
Phase 1.5: 三重验证 + source contracts + coverage ledger + mini/final merge
Phase 2:   主 agent 分阶段亲写 RIA++
Phase 3:   主 agent 亲写 Zettelkasten INDEX
Phase 4:   test-prompts + 正交 / 尺寸 / cold-read + Phase 4e utility gate
Phase 5:   meta-skill 合成 + 晋升评估

N / M / K 由书的章节数 + token 量决定。下游 phase 读上游落盘产物，不允许跳 phase 反推。

核心 Phase

Phase 0 — Adler 整书理解 + 多路 Critique

• 目标：把全书压缩为骨架命题 + 作者局限 critique + 不予提取清单
• 输入：source_original/ 原书文本
• 输出：process/BOOK_OVERVIEW.md（Adler 四步 + 骨架命题 + 关键术语词典 + critique 综合 + 不予提取清单 + 🔴 / 🟡 / 🟢 预估分级）；process/chapter_*_summary.md 每章一份可回溯原文章节路径
• Adler 四步（综合由主 agent 亲写）：(1) 结构分析：书类型 + 主旨一句话 + 一级论点及关系；(2) 解释分析：关键术语词典（≥5 条作者本人用法）+ 核心命题（5–15 条）；(3) 批判分析（硬质量门）：≥3 条作者局限每条独立机制论述，不足 3 条不得进入 Phase 1A；(4) 应用潜力：标注 🔴 axiom / 🟡 skill / 🟢 素材
• 验收：骨架命题每条可由陌生读者仅凭章节摘要重述，不依赖书外背景；不予提取清单的每一项在 Phase 1B candidates 里不得出现；critique 来自多路并行独立产出（有独立 lane 文件），非单 sub-agent 多段合成；每章摘要可定位原文章节路径
• Sub-agent 分派：章节摘要按章节数派 N 个并行；critique 多路独立并行（逻辑漏洞 / 时代局限 / 跨域映射边界 / 现代反例等视角，建议 ≥3 路）
• 失败处理：某章 sub-agent 超时 → 单独重派不整体回滚；某路 critique 产出稀薄 → 换视角重跑那一路，不靠补写

Phase 1A — Anchor List + Cross-Chapter Concept Index

• 目标：给骨架命题和高风险论点绑 anchor；建立跨章节 concept key 索引，让下游按 concept 对齐
• 输入：BOOK_OVERVIEW.md、章节摘要
• 输出：process/anchor_list.md（A_NN + chapter + line_range + high_risk 标记）；process/cross_chapter_concepts.md（CK_NN + 涉及章节 + meta-skill 候选 pipeline 种子）
• 验收：每条 anchor 含 chapter + line_range（不是泛指"Ch 5 附近"）；每个 CK 至少跨 2 章出现，单章概念不升级为 CK；高风险 anchor 比例在经验带内（参考 10–20%），超出时回读 BOOK_OVERVIEW 复核不硬打回
• Sub-agent 分派：主 agent 自写 anchor_list；CK 扫描拆 N 组并行 distributed scan 后主 agent 合并

Phase 1B — 五类 Extractor 并行提取 + 红绿灯分级

• 目标：在骨架 + anchor + CK 约束下切章节组，并行跑五类 extractor 产 candidate，当场标 tier
• 输入：章节文本、anchor_list.md、cross_chapter_concepts.md、不予提取清单
• 输出：process/candidates/candidates_group_*.md，每条含：id / kind（framework / principle / case / counter-example / glossary）/ tier（🔴 / 🟡 / 🟢）/ statement / source_section / anchor_ref / concept_key（或 local-only）/ evidence（原文 ≤150 字）
• 五类 Extractor 职责（同一 sub-agent prompt 内并列，避免遗漏）：
• framework — 可迁移思考结构（作者命名过、跨章节反复引用的思考流程）
• principle — 规范性断言（"必须..."、"永远..."、编号清单、判断标准）
• case — 作者亲自使用过的实例，非二手引用
• counter-example — 失败模式 / 陷阱 / 作者警告；必含 failure_mode / mechanism / warning_signs / bound_to 四个硬字段
• glossary — 作者特定用法的术语，非字典定义、非领域通识
• 红绿灯分级（当场标）：
• 🔴 跨域普适 / 反直觉 / 作者独特视角 → 候选 axiom（Phase 1.5 门槛最严）
• 🟡 书内可执行单元 / 方法论步骤 → 候选 skill
• 🟢 案例 / 故事 / 自传性内容 → 仅作 A1 素材，不独立成单元
• 验收：
• 每条 anchor_ref 可在 anchor_list.md 找到
• 每条 concept_key 要么在 cross_chapter_concepts.md，要么显式标 local-only
• 不予提取清单中的论点不出现在任何 group
• 各组产出条数大致接近；某组远少 → prompt 漏激活，重跑该组
• counter-example 四个硬字段齐全
• Sub-agent 分派：按保序装箱切 M 组（M 受并发上限约束），每组派一个 sub-agent 并列跑五类。章节组保序不用大小降序 —— 破坏章节连贯会降低跨章节 candidate 质量
• 失败处理：某组 stuck → 再拆小子组重派，不干等 timeout；某类别产出为零 → 重跑并在 prompt 单独加粗该类别信号

Phase 1.5 — 三重验证筛选 + 合并（按 tier 分流）

• 目标：用 V1/V2/V3 筛候选，按 tier 分流写作池；按 concept_key 对齐并 anchor 去重
• 输入：candidates_group_*.md
• 输出：
• process/candidates_merged.md：按 concept_key 对齐 + anchor 去重 + tier 标注的合并产物
• process/insights.md:通过的 axiom / skill 候选清单
• process/rejected/<id>.md：每条淘汰原因
• process/source_contracts/<unit_id>.source_contract.md：每个进入 Phase 2 的 skill / axiom / meta-skill 候选各一份
• process/coverage_ledger.md：记录每条书内内容最终承担的角色，必要时可按章节或 concept_key 拆分
• 三重验证：
• V1 跨域 — 书中 ≥2 个独立语境（不同章节 + 不同对象 + 不同结论）。🔴 要求 ≥3。作弊检测：去掉具体名词后两条证据结构是否相同，相同即同一例换说法
• V2 预测力 — 能推导书中未明说的新问题且结论非平庸。🔴 要求新场景在 ≥3 个不同领域成立。作弊检测：新问题给没读过此书的人看能否直接从书中找到答案，能即旧题冒充
• V3 独特性 — 抹掉作者名字，聪明但没读过本书的人能否自发说出这段内容？若能，这条等于通识，无论它多重要都不独特。若不能，必须写出本书到底多出了什么——说不出"多出了什么"（只能说"很重要"或"作者写得漂亮"）也算通识。🔴 tier 的一个常见信号是翻译成大白话后仍反直觉，但这是参考信号，不是硬条件。作弊检测：翻译后只剩修辞漂亮而无新内容即不算独特
• 分流：🔴 全通过 → axiom 写作池；🔴 单项不通过 → 降 🟡 重评；🟡 全通过 → skill 写作池；🟡 单项不通过 → 降 🟢；多项不通过 → rejected/
• 综合从众提示：合并多个 sub-agent 的 V1/V2/V3 判定时，优先用上面各项「作弊检测」这类可机械复核的信号（可验证综合最稳），不要按 sub-agent 措辞或「多数通过」投票；不可验证的 tier 印象先多采样取众数压 churn。机制见 workflow_parallel_subagents §等待与整合「独立综合者配方」。
• Source Contract：Phase 1.5 到 Phase 2 的交接物。每份 contract 至少列出 source_scope、allowed_source_claims、operationalizations、forbidden_extrapolations、caveats_must_survive、orthogonality、utility_hypothesis。它先判定哪些 source claim 可写、哪些操作是 source-supported / bounded-inference / editorial-addition / contradicted-by-source，再允许 Phase 2 写成品 prose。它不是 Phase 2 之后的 audit checklist。
• Fragile claim active retrieval：entity names、exact counts、quotes、named mechanisms / categories、source-sensitive examples、author caveats / limitations，以及 Round 1 / Round 2 已暴露过的 defect class，必须在 contract 中标 active_retrieval_required，并在 Phase 2 对原书 span 再检索。检索不到时只能 omit、defer 或显式标 editorial，不能写成 book-grounded final claim。exact quotes 和 source claims 需要 citation-location fidelity，不只需要词句相似。
• Coverage Ledger：每个高风险 anchor、candidate、case、glossary 或 rejected item 都要有 ledger row，角色为 skill / axiom / meta_skill_component / case_example / glossary_reference / rejected / not_extracted。完整反映书籍内容通过 ledger 完成，不通过把所有内容膨胀成 executable skill 完成。
• 验收：
• candidates_merged.md 是真实合并产物，不是从 anchor_list / cross_chapter_concepts 反推的 inventory（随机抽条回追到原始某组能找到 evidence 链）
• 无 anchor 级重复；跨组同 CK 的 candidate 合并为一条；tier 字段齐全
• 每条 rejected/<id>.md 含具体证据和淘汰原因
• 每个进入 Phase 2 的候选都有 source_contract，且每个 fragile claim 的 retrieval 状态可检查
• 每个 executable unit 至少指向一个 coverage ledger row，rejected / deferred fragile row 有 reason
• Sub-agent 分派：候选组多时拆若干 mini-merge 并行（每个负责相邻 2 组或单独 1 组），再派一个 final-merge sub-agent 按 concept_key 对齐跨 mini-merge 结果。不要一次性合并全部组 —— 已观测单次合并全部组导致 sub-agent 长时间无输出
• 失败处理：mini-merge 某个超时 → 再拆一半重派；final-merge 超时 → 检查某些组是否可直接透传不需重合并

Phase 2 — RIA++ 构造（写作由主 agent 亲写）

本阶段是"精确提取"收束为"可被陌生 agent 调用"的 skill / axiom 的关键写作点。RIA++ 六段是通用 skill 规范（When to Use / Prerequisites / 步骤 / 验收 / 边界）在 library distillation 子类的具象化：metadata 头承担 Prerequisites 的可回溯部分；A2 承担 When to Use 的触发判定；E 承担步骤与判停；B 承担边界。陌生 agent 读单条 SKILL.md 即可判"是否触发 / 如何执行 / 何时停 / 何时不该调用"。

• 目标：把 🟡 单元写为 skill，🔴 单元写为 axiom，同时保持 source-supported、bounded-inference、editorial material 的边界
• 输入：candidates_merged.md + insights.md + process/source_contracts/<unit_id>.source_contract.md + process/coverage_ledger.md
• 输出：
• rules/skills/drafts/<书 slug>/skills/<slug>/SKILL.md
• rules/skills/drafts/<书 slug>/axioms/AX_NN_<slug>.md
• 每条含 metadata 头（= Prerequisites 的 source-traceable 形式）：tier / source_section / anchor_ref / concept_key / high_risk / caveat_origin
• 分阶段写作：
• Pass 0 Contract Readiness：只读 source contract 和原书 span，不写 RIA++ prose。每个 fragile claim 必须可检索，每个 allowed operation 必须有 supporting claim，每个 forbidden extrapolation 必须显式。未 ready 时停止并回 Phase 1.5 修 contract。
• Pass 1 Operational Skeleton：只写方法骨架、可执行步骤和判停点。只能使用 source-supported operation 与 contract 明确允许的 bounded inference，不写 A1 / A2 / B，不新增 entity / count / quote。
• Pass 2 A2 Routing：只写具体触发场景、语言信号、相邻 skill 区分和 near-boundary decoy。缺 neighbor distinction 时记录 gap，不现场发明。
• Pass 3 Examples And Caveats：只写 A1 examples 和 B caveats。entity names、exact counts、quotes、source-sensitive examples、named mechanisms、author caveats 必须回原书 active retrieval。Phase 0 critique 或现代工程评论只能作为 caveat/editorial，不作为 book claim。
• Pass 4 Assembly：只从已通过的 Pass 1-3 parts 组装最终 RIA++。Assembly 阶段不得引入新的 source claim、entity、count、quote、example、operational step 或 neighbor distinction。
• SKILL.md RIA++ 六段：
• R 原文引用 ≤150 字
• I 方法论骨架（自述语言，不照搬译本）
• A1 书中案例 1–3 个
• A2 ★ 最关键字段 —— A2 是"可独立调用"性质的落地点，三件事缺一不可：(1) 具体场景描述（"用户陷入纠结列 pro / con 仍无法推进"，不是"决策场景"这种泛词）；(2) 语言信号（使用者会说的话的关键词或句式）；(3) 与相邻 skill 的区别（为什么调用本 skill 而非另一个看似类似的）。没有 A2 三件事，skill 在陌生 agent 处等同不存在
• E 1-2-3 可执行步骤 + 每步判停点
• B 反场景 + 失败模式 + 作者盲点（来自 Phase 0 critique，非当场发明的免责声明）+ 与相邻方法论的易混淆点 —— 承担 skill 规范里的"边界"段
• Axiom 六节：核心公理 / 深度推演 / 应用判定 / 陷阱与洞察 / 相关公理 / 实践建议
• 验收：
• 每条单独读即可理解，不需回原书章节
• metadata 头完整，anchor_ref 和 source_section 可回溯
• 高风险 axiom 的陷阱 / B 段含来自 Phase 0 critique 的 caveat
• 每条 skill 的 A2 含场景 + 语言信号 + 相邻区分三件事
• A1 / B 段不含本次 distillation 的 meta 叙述（"本次 judge..." 等元写作只存在 process notes，不进成品）
• final prose 中所有 fragile claim 都能回到 source contract 和 active retrieval 记录；bounded-inference 与 editorial material 没有伪装成 source claim
• Sub-agent 分派：写作不外包，主 agent 亲写；超 context 时分批（先 axioms 再 skills，或按主题分批），不一口气撑爆

Phase 3 — Zettelkasten 链接

• 目标：识别单元间的真实 usage 关系，生成网络索引
• 输入：所有 SKILL.md / axiom.md
• 输出：每个文件的 related_skills frontmatter + rules/skills/drafts/<书 slug>/INDEX.md
• 三类关系（只记真实 usage，不记"主题相关"或"同一章节"）：
• depends-on — A 的使用前提是先理解 B
• contrasts-with — A 和 B 是互斥或竞争的两种方案
• composes-with — A 和 B 经常配合使用
• 验收：
• 每条边指向真实 ID，无悬空引用；depends-on 图无环
• 说不出一句话理由的关系不写
• INDEX 含节点清单、关系图（可用 mermaid）、从 depends-on 拓扑推导出的学习顺序
• Sub-agent 分派：主 agent 亲写（跨单元关系判断需整体视野）

Phase 4 — 压力测试 + 质量把关

• 目标：验证每个 skill 能否被正确触发，检查 skill 之间是否正交、单 skill 是否过载
• 输入：所有 SKILL.md
• 输出：
• 每个 skill 目录下 test-prompts.json（darwin 兼容格式）
• process/insights.md 追加 Orthogonality Audit 段 + Size Audit 段
• test-prompts 硬约束：
• should_trigger ≥3 条
• should_not_trigger ≥2 条诱饵（"看似相关但不该触发"的场景，不是完全无关）
• edge_case ≥1 条
• 没有诱饵的 skill 一律打回重做
• Orthogonality 检查：两两交叉 —— 把 skill A 的 should_trigger 场景逐一问"此场景下会调用 skill B 吗"；重叠大多数 → 实质重叠需合并；部分重叠但各有独特触发 → 双方 A2 加强"与 X 的区别"
• Size 检查：单 skill 整体明显超常（如 R 段原文远超 150 字、总字数中步骤占一半）→ 覆盖面太宽，拆成多个独立 skill
• Cold-read 观察（非 gate）：派 sub-agent 扮演第一次接触此 axiom 的读者，分批读 RIA++ 并回答能否独立理解 / caveat 是否清晰 / 能否拒掉同主题 decoy；失败项主 agent micro-edit A1 摘要而非重写整条
• 验收：
• 每个 skill 都有 test-prompts，诱饵数达标
• 两两正交性问题有结论（pass / 合并 / 加强区分），不留悬空
• 尺寸异常的 skill 已处理
• cold-read 失败项均有对应 micro-edit 或标注"未验证"
• Sub-agent 分派：test-prompts 可派 sub-agent 起草主 agent 验收；正交性交叉可多 sub-agent 并行；cold-read 拆多 batch 并行
• 失败处理：test-prompts 通过率明显偏低 → 回 Phase 2 改 A2；正交性重叠不可合并也不可加强区分 → 回 Phase 1.5 重审是否本应降级

Phase 4e — Differential Utility Gate（晋升 gate，不修 source fidelity）

Phase 4e 在 source fidelity、test-prompts、orthogonality、size、cold-read 之后运行。它只回答一个问题：一个已经 source-faithful 且可触发的单元，加载后是否改变实际工程判断或行动。

• 输入：已通过 Phase 4 的 draft unit、source contract 的 utility_hypothesis、覆盖 ledger row、成对 A/B 测试任务
• 输出：process/insights.md 追加 Differential Utility Gate 段，逐条标 D / I / W：
• D differential：skill-loaded 答案改变 action、tradeoff、边界判断或拒绝条件
• I indifferent / nomenclature-only：只换词、改名、重述通识，行动不变
• W worse：引入错误、过度约束、source drift 或更差工程建议
• 验收：
• A/B 前先写 utility hypothesis，不能事后解释通过
• vocabulary-only 或 citation-only improvement 记为 I
• source-unfaithful unit 先回 Phase 1.5 / Phase 2，不能用 utility gate 抵消
• W 必须回退或重写；I 默认不晋升为 executable skill，可保留为 glossary / case / axiom 支撑；D 或有充分理由的 mixed result 才进入 Phase 5 晋升评估
• 边界：Phase 4e 是 promotion gate，不是 source-fidelity repair。source fidelity 的修复点在 Phase 1.5 source contract 和 Phase 2 active retrieval。

Phase 5 — Meta-skill 合成 + 晋升评估

• 目标：识别跨多 axiom 的 pipeline 写成 meta-skill；判定哪些 skill / axiom 晋升到正式 rules/skills/ 或 rules/axioms/
• 输入：INDEX.md 的 composes 群组、cross_chapter_concepts.md 的 meta-skill 候选 pipeline
• 输出：
• rules/skills/drafts/<书 slug>/meta_skills/MS_NN_<slug>.md
• process/insights.md 的 Promotion Candidates 段
• Meta-skill 要求：
• N 步可操作 procedure（不是对子 axiom 的同义重述），每步含 input / output / decision criterion
• composed-of 字段列出组合的 axiom / skill ID
• V-meta 三问回答（写 meta-skill 前就明确，不允许事后反推通过）：
• Pipeline Reality — sub-axiom 间依赖真实存在，不是为凑 meta-skill 捏造
• Independent Scaffold Value — 合成后比子 axiom sum 多出独立工具价值
• Non-Tautology — 不是子单元的简单 concat，是方法论层面的 prescription
• 晋升硬条件（三项全中才晋升）：
• 通过 Phase 4 全部质量门（test-prompts 到位 + 正交性通过 + 尺寸达标）
• 通过 Phase 4e Differential Utility Gate，且结论不是 vocabulary-only / nomenclature-only
• coverage ledger 中对应高风险内容已 covered，source contract 与 final prose 可互相追溯
• ≥3 个独立适用领域，insights.md 显式列出证据
• 用户明确确认
• 验收：每条 meta-skill 含三问答案，非泛泛"有用"；Promotion Candidates 段逐条列出领域 + 证据 + 与现有 skill / axiom 的冲突检查；用户未点头不落到 rules/skills/ / rules/axioms/
• Sub-agent 分派：主 agent 亲写 meta-skill；V-meta 三问可主 agent 自跑或派 sub-agent judge 交叉验证

失败与恢复

以下基于真实执行观测，不编造。

• 单次合并全部组导致 sub-agent 长时间无输出：表现 CPU 空转、log 零字节、远超同量级任务的正常耗时。恢复：kill 当前 sub-agent，拆为若干 mini-merge 并行（每个合并相邻 2 组或单独 1 组），再由 final-merge 对 mini-merge 结果做 concept_key 对齐
• 主 agent 在 sub-agent stuck 后退回写作舒适区：sub-agent 失败后主 agent 不排查、不拆分、不换 provider，转而以"简化推算"名义从上游 anchor / CK 反推 inventory，之后未跑验证直接把 RIA 一路写到收尾。恢复：sub-agent 单次失败视为"这个任务要拆"，非"整条 pipeline 不可靠"；写作前必须有真实合并产物，禁止从 anchor 反推；验证没跑完不写 FINAL_REPORT；简化 fallback 必须显式说明简化了什么、代价是什么
• 资源不全时过早放弃：初次获取失败被误判为"资源不可得"，之后在数据不全下硬跑或写过深 RIA 挤占 context。恢复：资源缺口第一时间问用户是否有合法电子版；不要只试一次；确认不可得时在 BOOK_OVERVIEW.md 明确标 scope，下游不跨 scope 推断
• 过早 wrap-up 消耗主 agent context：phase 未跑完就开始写长篇 SESSION_LOG / FINAL_REPORT / HANDOFF 等互相 overlap 的收尾文档，挤掉应跑验证的 context。恢复：pipeline 未跑完不写 FINAL_REPORT；SESSION_LOG 只写行进度 + 未完成 phase 清单；HANDOFF 留给 session 真正结束时写
• cold-read 失败时整体重写：某条 RIA cold-read 失败就重写整条；通常失败只在 A1 摘要层（缺 closure、公式前置、术语未自包含）。恢复：主 agent micro-edit A1 而非重写整条；多条都失败 → 回查是否 Phase 2 写作模板本身的问题再统一改

Bad Behavior 防护

• F1 (Scope Anchoring)：Phase 0 先产骨架命题 + 不予提取清单；Phase 1B extractor prompt 强制引用二者做硬约束，不让 extractor 被章节结构牵走
• F4 (Creative Overproduction)：Phase 2 写 RIA 前先查 INDEX 是否已有同 concept_key 节点，并先通过 source contract readiness；写完后不追加"迁移指南" / "版本对比" / "已知限制" / "Design Rationale" 等用户未要求的章节；单条 RIA 字数适度，不 upfront 深度化挤占验证 context
• F4-Premature (Premature Concretization)：被问方法论或方向时先把 phase 目标 + 验收写清楚再给模板作为附带资产；单次运行的数字（sub-agent 数量、通过率、wall clock）不作为通用基准复用到其他书
• F6 (Formal Metric Substitution)：cold-read / 元审计 / judge 是观察工具，不作 source-fidelity 替代；Phase 4e 是 promotion gate，只判 differential utility，不修复 source drift；合格仍以"陌生读者能独立调用且 source-faithful"为准，不以"cold-read 通过率达 X%"或"ablation 全 PASS"替代
• F7 (Score-based False Precision)：judge / 重叠率等数字只作相对参考，不作绝对质量签名；不把具体百分比写成交付 SLA
• F9 (Void-filling Drift)：Phase 2 写作前 INDEX 初始关系图、source contract、coverage ledger row 必须存在（哪怕只有骨架 depends 链和待验证 ledger row），否则主 agent 会在"该归入哪个集群"或"书里到底支持什么"上凭空造标准；Phase 5 V-meta 三问必须在写 meta-skill 前就明确，不允许事后反推通过；section 写不出来就留空或标"未验证"，不为完整性硬填

产物质量标准

以陌生 agent 能否独立调用为准，非形式指标。

Axiom：六节齐全；单独读可重述核心公理不依赖书外背景；高风险 axiom 的陷阱段含来自 critique 的作者局限（非当场发明的免责声明）；与 rules/axioms/INDEX.md 既有公理有显式关系或明确新增。

Skill：RIA++ 六段齐全；有 source contract 和 coverage ledger row；fragile claim 已 active retrieval；A2 三件事缺一不可（具体场景 + 语言信号 + 相邻区分）—— 这是"可独立调用"性质在 skill 层面的实体化；E 段步骤可执行每步有判停点；B 段含反场景 + 失败模式 + 作者盲点；有 test-prompts（≥3 should_trigger / ≥2 诱饵 / ≥1 edge_case）；两两正交性问题有结论；Phase 4e 不为 vocabulary-only。

Meta-skill：N 步 procedure 每步含 input / output / decision criterion；composed-of 列出组合的 axiom / skill ID；V-meta 三问（Pipeline Reality / Independent Scaffold Value / Non-Tautology）有显式回答；不是子单元同义重述或简单 concat。

INDEX：每条边指向真实 ID，无悬空引用；depends 图无环；Zettelkasten 关系只记真实 usage（说不出一句话理由的关系不写）。

工具引用

按名引用，路径查 tools/INDEX.md。

• claude-zai / claude-kimi — sub-agent CLI（功能等价，quota 充裕者用之）
• library_distillation_prepare_source — PDF / EPUB / TXT / Markdown source preparation
• library_distillation_check_status — filesystem-authoritative completion scan
• library_distillation_update_global_status — generated JSON/Markdown status refresh and drift check
• library_distillation_provider_watchdog — Phase 0-1.5 provider quota / stuck-on-429 watchdog
• token_estimator — chunking 前估 token
• reference_validator — 文件移动 / 重命名时保持引用同步
• todo — 记录 opt-in 扩展、补做、遗留任务