蒸馏skill（zyuan）— 把长内容蒸馏成可执行 skill
使命
把长内容里沉淀的方法论拆成原子化、可被 agent 在真实任务中调用的能力，按用户目的编译成 1 个或少量 skill，让读者真正用起来。
术语约定：「长内容」= 书、长视频转写、播客、课程、访谈、长文、资料集（含知识库文件夹、单文档工作流）。
边界：做方法论 / 决策框架 / 原则 / 清单 / 概念体系的蒸馏；不做书摘、读后感、作者人设扮演、纯知识问答，也不做已有 Skill 的重构 / 精简 / 优化（属他类工具地盘）。
常见说法 → 对应能力（命中即用本技能）
用户很少说「蒸馏」，而是说下面这些：
| 用户这样说 | 本技能做什么 |
|---|---|
| 拆书 / 把这本书做成技能 | 全书提取 → RIA-TV++ 卡 → 装配成 skill |
| 把这门课的方法论抽成 checklist | 课件/转写稿 → 判定标准 + 步骤 → 清单型卡 |
| 把视频或播客的干货沉淀成 prompt / 技能 | 转写 → 提取 → 可调用能力卡 |
| 把老板的汇报套路变成可复用模板 | 访谈/记录 → 提取 → 模板型卡 |
| 把一堆研究资料整理成操作手册 | 多文档摄入 → 去重合并 → 手册型 skill |
| 把文档里的最佳实践做成能跑的流程 | 文档 → 步骤 + 判停标准 → 流程卡 |
| 把行业报告变成决策框架 / 把调研变成竞品分析模板 | 提取框架与原则 → 决策型 / 模板型卡 |
| 把书里的思维模型做成提问清单 | 提取概念与模型 → 提问清单卡 |
同义说法按同一处理：把 XX 做成 skill / 沉淀成 skill / 提炼成方法 / 抽象成框架 / 整理成手册 / 做成模板 / 变成清单 / 把经验固化下来。
不要用本技能：要文风克隆或扮演作者 → 文风蒸馏工具；要把已有 skill 改小改简洁 → skill 重构工具；只要一段摘要或书评 → 直接回答。
完整对照表与边界判断三问见 references/21-trigger-map.md。
根本洞察
现有读书方法论都是为人类读者蒸馏的，不是为 agent 执行者蒸馏的。 差别在关键字段（故事/金句 → 触发条件/可执行步骤/判停标准）、失败模式（读完就忘 → 触发不准、永不调用或乱调用）、成功标准（读者"有收获" → 真实问题被解决）。理论来源映射见 references/00-overview.md。
不变量（任何迭代都不得违反）
INV-1. 原子性 — 一个能力只做一个方法论单元；single 的"一个"指一个发现入口，内部能力仍原子化
INV-2. 可追溯 — 每个能力必须有原文引用，指向源位置（书填章节/页码，视频填时间戳，播客填集数）
INV-3. 可验证 — 每个能力必须通过三重验证 + 压力测试，且能给出一条可被现实推翻的预测（可证伪 字段）；给不出否证的说法是格言，不是能力
INV-4. 可进化 — 每个晋级能力必须附带 darwin 兼容的评测用例
INV-5. 用户参与 — 三道闸门：阶段 0 确认骨架、阶段 2 确认入选名单、阶段 7 确认安装位置
INV-6. 可交付 — 流程终点是"用户能调用"：产物必须安装到 skills 目录，读者需求由 DIGEST.md 承接
INV-7. 单一事实源 — cards/ 是唯一事实源，single 与 pack 引用同一组能力卡，不做二次改写；不设 verified.yaml / capability_id 中间层——少一层中间层就少一个漂移面（中间层与卡片对不上的风险），这是用"装配只认卡片结构"换来的
INV-8. 能力不失联 — 未晋级能力保留为路由入口内的能力卡，每个 active 能力恰好一个去向
INV-9. 不擅自变更输出形态 — 除非有证据或用户显式要求，不改 single / pack 选型（split-on-evidence）
INV-10. 连贯性保真 — 每条引文必须带回邻接上下文并写入卡片「上下文保真」块；check_coherence.py 判引文在源中存在且上下文未篡改，否则视为断章取义打回
INV-11. 跨书可合并 — 同一能力被多来源蒸馏时，必须能去重合并且保留 provenance；合并以成熟度最高者为 canonical，不丢来源
INV-12. 源是唯一确认人 — 交付后任何修复/升级，方案必须经「源」（内容所有者/需求客户）确认；代理不得自行确认并执行破坏性变更；未确认前只允许自检取证
输入要求（开始前必须确认，缺一就问）
- 文本来源：PDF / EPUB / TXT / 字幕 / 转写稿路径，或可访问纯文本。没有文本不许凭记忆蒸馏 —— 但硬停不是句号，要给出可走的三条合规取文本路径：
- ① 有本地文件：直接给路径，最常见；
- ② 是视频 / 音频（mp4/mkv/mp3/m4a/wav…）：用scripts/transcribe.py转成带时间戳转写稿（元可「直接吃」媒体）。零配置优先：同目录同名.srt/.vtt零依赖跑通（连 ffmpeg 都不用），内嵌字幕轨只需 ffmpeg——都不装引擎、不下模型、不配密钥、不联网；无字幕才需 ASR（国内路径见references/10-media-ingest.md）；
- ③ 只有书名或链接：先合法取得文本（购买/借阅的正版电子文本、公开授权正文页），取得后再开工。不提供"凭记忆蒸馏"的替代，也不绕付费墙、登录限制与平台风控——宁可不做，不做编造。 - 元信息：书 → 书名 + 作者 + 出版年；视频/播客/课程 → 标题 + 讲者 + 发布时间
- 使用目的：学习查阅 → single；接入工作流、跨内容组合 → pack。不确定按 single-first（首次先蒸馏 1 份验流程，再批量）
档位与工作量预估（开工前先定档）
| 档位 | 适用 | 流程 | 闸门 | 工作量量级 |
|---|---|---|---|---|
| 轻量 | 首次试点、单篇快验证 | 阶段 0–4，single-first，只留够用的卡 | 2（阶段 0、7） | 一轮提取 + 成卡 |
| 标准 | 常规单来源（默认） | 完整 0–7，含三重验证与压力测试 | 3 | 数轮：提取→验证→测试 |
| 深度 | 多来源跨书淬炼 | 标准 + merge_books.py + 全量压力测试 |
3 + 每来源 0 阶段 | 成倍于标准，且随来源数线性增长 |
档位只改投入，不改质量红线：任选哪档，交付的卡片照过三重验证与上下文保真。不确定就从轻量起——先在 1 份内容上跑通，再升档。
执行流程（严格按序）
开工第一件事：python scripts/pipeline_state.py resume books/<slug>。
有状态就从断点继续（检出中断残留、产物缺失、未确认闸门并给出下一条命令），没有就 init。每阶段用 start/done/gate 记录，不要只手写 markdown：机器状态在 .zyuan_state.json，PIPELINE_STATE.md 是自动生成的人读镜像。详见 references/13-checkpoint-resume.md。
蒸馏前先过内容预检：python scripts/content_precheck.py "<源>" --baseline。🔴 停下问源、🟡 改写后继续、🟢 直接进流程（references/12-content-precheck.md）。
常见反模式 / 踩坑 / 首用问答集中在 references/19-faq-anti-patterns.md。想跑通最短路径看 references/quickstart.md；想看「一张真卡从素材到安装」的完整示范看 references/20-walkthrough.md；想查「用户这么说该怎么做」看 references/21-trigger-map.md。
| 阶段 | 动作 | 产出 | 用户确认 |
|---|---|---|---|
| 0 | Adler 整书理解 | BOOK_OVERVIEW.md |
★ 骨架 |
| 1 | 5 条提取线并行 | candidates/*.md |
— |
| 2 | 三重验证 | verified.md / rejected/ |
★ 入选名单 |
| 3 | 晋级门（产品化验证） | verified.md 去向标注 |
— |
| 4 | RIA++ 能力卡 | cards/*.md |
— |
| 5 | Zettelkasten 链接 | also_read + GLOSSARY.md |
— |
| 6 | 压力测试（darwin 兼容） | test-prompts.json + test-results.md |
— |
| 7 | 交付安装 | DIGEST.md + INDEX.md + skill 目录 |
★ 安装位置 |
阶段要点（细则分别见 references/01–08）
| 阶段 | 关键约束 |
|---|---|
| 0 整书理解 | 先素材体检：count_tokens.py 数字数（脚本算，不许目测），单源 <1 万字 / 多源 <3 源2万字标「语料不足」并写进 BOOK_OVERVIEW + DIGEST。产出 BOOK_OVERVIEW.md 并确认骨架。★ 闸门是硬停止点，"按最优解/直接做"不豁免等待；显式跳过须 pipeline_state.py skip <book> --stage 0 --by <授权人> --reason <原话>，手写 PIPELINE_STATE.md 会被覆盖 |
| 1 五行提取 | 每条候选必标 freq（≥3 次 high / 2 次 mid / 1 次 low，同段改写不算多次），low 不进 promoted。并行 spawn 5 个 sub-agent，各读 extractors/ 对应 prompt（框架/原则全量；案例/反例/术语检索式取块）。视频先跑 transcribe.py；大文本（>5 万字）先 build_chunks.py + build_index.py --neighbors 建图。检索式线必 --neighbors 1 + 记前后文，否则阶段 2 打回；不支持并行则串行，产出格式不变 |
| 2 三重验证 | V1 跨位置佐证（同源多锚点）/ V2 预测力 / V3 独特性；通过后向用户确认入选名单（理论 / 论断型素材额外判据见 references/18） |
| 3 晋级门 | 知识验证通过 ≠ 值得独立成 skill；五条判据定 promoted / router；认知层级门槛见 references/04。预算只数"晋级 skill"，单包模式全是 router 卡（promoted=0），不算破预算 |
| 4 能力卡 | R / I / A1 / A2 / E / B 六段写入 cards/<slug>.md；R 段必写「上下文保真」（引文前后各一句）；卡头补字段（含 认知层级/知识维度，见卡片模板） |
| 5 链接 | 建能力间 also_read + GLOSSARY.md；检索轨 build_topic_index.py（术语索引 + 跨书综合待办 + 检索盲区） |
| 6 压力测试 | Part A 触发评测 test-prompts.json 独立盲测，<80% 回炉；Part B run_output_evals.py 断言判分，必跑 without_skill 对照组——无卡片组也全过说明断言无区分力（断言只从 E 段完成标准抽） |
| 7 交付 | select_output_strategy.py --evidence 定 single/pack → DIGEST.md+INDEX.md → assemble.py 从 cards/ 装配 → publish.py 发布（适配器 user/project/dir/zip；--staged 探针；退避重试；slug 不改名；线上手改不静默覆盖；迭代元自己用 publish.py sync --src <开发目录>）。补完已有技能走「补完模式」（merge→快照→临时目录→impact_analysis.py --diff-other）；交付后建 REPAIR_LOG.md |
交付后自愈（反馈驱动修复）
交付不是终点。客户/源反馈问题时，走 references/11-feedback-repair.md 八步闭环：
收反馈(原话) → 归因(triage_feedback.py) → 定向自检(取证) → 最优方案(A/B/C) → ⛔源确认 → 执行升级(先快照) → 四关回归 → 记录闭环+沉淀
- 归因自检：
triage_feedback.py "<反馈>" --source "<源>" --skill "<目录>" --source-file "<源文件>" --run-checks --out REPAIR_TICKET.md（9 类归因 + 实跑四关取证）。 - ⛔ 源是唯一确认人：只有「源」（内容所有者/客户）能确认修复方案；未确认前只许自检取证，禁止改卡片 / 改 description / 重装配。
- 先快照后动手：
snapshot.py snap后只改归因命中范围；不过则snapshot.py rollback。 - 沉淀：暴露的是流程缺陷就回写 reference 或补不变量，做到越用越强。
输出结构
books/<slug>/
├── .zyuan_state.json # 断点状态（唯一事实源；PIPELINE_STATE.md 是镜像）
├── BOOK_OVERVIEW / verified # 阶段 0 / 2-3
├── GLOSSARY / DIGEST / INDEX / TOPIC_INDEX # 阶段 5 / 7
├── candidates/ rejected/ # 候选池、淘汰留痕
└── cards/ # 能力卡 —— 唯一事实源
最终交付物：single = 1 个入口 SKILL.md（路由表）+ cards/；pack = 1 个路由入口 + N 个独立 skill 目录，共享同一组 cards/。
质量红线（违反即阻止输出）
共 16 条。完整条文与判定见 references/17-quality-redlines.md；本节只留短标签，条号与权威版一一对应。
- 提取与成卡：1 三重验证（V1/V2/V3）全过 ｜ 2 R/I/A1/A2/E/B 六段齐全 ｜ 3 引文 ≤150 字（英 ≤100 词）/段 ｜ 4 每能力恰好一个去向 ｜ 5 description 写触发条件 + 互设近邻负例 ｜ 6 无诱饵测试一律打回
- 交付与验证：7 必须装到 skills 目录 ｜ 8 R 段「上下文保真」+
check_coherence.py通过 ｜ 9 同名异义不得强并（进 MERGE_REPORT）｜ 10 成熟度只由已有标记推断、脚本不臆造 ｜ 12verifiable: true必给可证伪声明 ｜ 13 单文件超 token 预算就下沉 references ｜ 14 预检 🔴 不交付 / 🟡 剥离操作参数 ｜ 15 slug 装配固定、发布不改名、目标被手改不覆盖 - 变更与自愈：11 修复须「源」确认 + 先
snapshot.py snap+ 四关回归 ｜ 16 改名做持久化标识双读（新名优先、旧名兜底），写只用新名
调用惯例
- 先试点 1 份，除非用户明说批量；阶段之间主动汇报，不静默跑完再 dump
- 压力测试优先独立 sub-agent 盲测；只能主流程自测时须在
test-results.md标明 fallback
配套文件（清单见 references/00-overview.md 附录）
references/00–13、17–21：总览 + 各阶段细则 + 跨书合并 / 媒体 / 自愈 / 预检 / 断点 + 17 质量红线权威条文 + 18 认识论卫生 + 19 反模式与首用 FAQ、20 端到端范例、21 触发对照表 + quickstart 快速开始extractors/×5：五条提取线 prompt ｜templates/：产物模板scripts/：24 个业务脚本 + 1 个_cli.py兜底模块 = 25 个.py（纯标准库、不调模型；FTS5 缺失自动降级）。增删脚本后请同步这三个数字与附录 A 清单（业务脚本数 = .py 总数 − 1）
最常用的五个：pipeline_state.py（断点续跑）、check_coherence.py（引文保真）、assemble.py（装配）、content_precheck.py（预检）、export_mindmap.py（cards/ → mermaid 框架图，交付辅助，只读不改元，--links 加关系边）。参数见各脚本 -h；改元自身代码后先跑 selftest.py（秒级自测）。
