Sansheng Distill

sansheng-distill -- 书籍/视频蒸馏引擎(v3 浏览型)

输入一本书的电子全文(或一组视频),跑完 Step0-Step7 管线(Step2 分两遍),产出一个可 file:// 直开的单文件交互 HTML 蒸馏页。

v3 页型 = 浏览型「凝练地图 + 详实正文 + 批判证据 + 页内二级视图」,按读者逻辑链组织:

交互:脑图可点跳章节、章节手风琴多开、两张页内全屏子视图(hash 路由开合)、多主题换肤。

这是入口编排文件。 先读本文对齐管线,再在每一步按下表读对应 reference / 跑对应 script;references 是各步的执行细则,不要凭记忆做。

先分流：蒸馏对象 → 路径

判断口诀：分析单位是「作品」→ 主管线；分析单位是「一个创作者自己的思想输出」→ StepC；分析单位是「一个人的历史生平及其证据」→ biography_corpus。StepA/StepB 是主管线的可选聚合步，与后两条人物路径不冲突。

人物路径边界：creator_corpus 归并一个创作者跨媒介表达出的观点族，回答「他的思想体系是什么、如何变化」；biography_corpus 汇合多来源的史实观察、分歧与外部核验，回答「发生过什么、证据在哪里、哪些仍有争议」。把传记做成「一页」产品、网站页面、SEO 或正式部署属于下游产品与工程，不在本 Skill 内实现。

🪶 用轻量模型 / 弱 agent 跑本 skill(如 Gemini Flash 级、Antigravity 客户端)→ 先读 references\flash-mode.md。 那份卡不降低任何质量标准,只把「靠自觉」的环节换成「可自检的判据」,并钉死六个最容易滑落的点。 Opus / Sonnet 级模型照本文主管线走即可,不必读。

路径与变量约定(全文只定义一次)

命令里的占位符替成实值再执行。单书目录首次运行 Step0 时自动建。

数据目录约定(单书产物布局)

$DATA\
  knowledge-index.json          # 跨书概念索引(全库共享,Step4 维护,自动 .bak)
  {书目录}\
    book.txt                    # 全文(书=Step0-B;视频=Step0-V 组装的转写语料)  -- gitignore
    diagnose.json               # 入书诊断(书=Step0-B;视频=Step0-V 的 video_series 变体)
    raw\                        # 仅视频:各集原始转写 srt/txt(Step0-V)             -- gitignore
    series-input.json           # 仅视频:手写 manifest(Step0-V 输入)
    series.json                 # 仅视频:规范化 manifest(Step0-V 产物,下游只读它)
    comments.json               # 仅视频:观众评论(Step0-V,供 Step3 enrich.reviews)
    distill.json                # 蒸馏主对象 v2(Step2 两遍产:Pass1 骨架 + Pass2 narrative/excerpts)
    _pass2_g*.json              # Pass2 分块中间态(长书按章 fan-out 各组产物,合并回 distill) -- gitignore
    enrich.json                 # 联网增补 v2.1(五个基础键;心理学书加 evidence_page 科学证据层)
    claim-coverage.json         # 仅心理学:Pass1 待审计项到最终 claim 的裁决表
    source-audit.json           # 仅心理学:原文分段、逐项来源记录与四输入 hash
    index-merge.json            # 5-tag 合并清单(Step4 中间产物)
    {slug}.html                 # 单文件交互蒸馏页(Step6 产物,最终交付,≤3MB;真封面 base64 内联,无独立 cover 文件)
    _verify.png                 # Step7 验证全页截图                                  -- gitignore

gitignore(建议在数据目录加 .gitignore):book.txt / raw/ / _verify.png / _pass2_*.json / *.bak 不入库(版权原文 / 临时产物);其余(distill / enrich / HTML / index-merge / series / comments / diagnose;心理学另含 claim-coverage / source-audit)可入库。

管线表(Step0-Step7,Step2 分两遍)

每一步:做什么 / 读哪个 reference / 跑哪条命令 / 产物 / 失败降级。逐步照做,上一步产物是下一步输入。

⚠ 视频路径 v2 尚未跑 E2E 验证:骨架 / method.md §V / html-spec.md §V / enrich.md §V / verify_page.py 的视频分支已随 v2 更新到位,但尚未用视频样本完整重蒸验收(书样本《金钱心理学》已 E2E 通过)。蒸视频系列时按 §V 照做,遇到骨架/门禁与视频不吻合的坑先记录再修。 跑判成败的脚本别用 \| tail / \| head 取摘要(管道退出码取最后一段,tail 永远成功会吞失败);看完整结尾行或补 ; echo "退出码=$?"。

⚠ Step6 只能在正式 page-skeleton.html 的基础上逐槽填入数据。严禁另起极简 HTML 壳，或删掉 theme-picker、initMindmap()、initHashRouter() 来“简化渲染”；这会丢失主题、脑图 viewer 和章节路由，Step7 会直接拒收。

StepA · 作者演变聚合(可选,同一作者 ≥2 部已蒸时)

某作者在 $DATA 下已蒸 ≥2 部作品时,可选做「思想演变专题」聚合页;单书蒸馏不涉及,<2 部不生成。

• 做什么:只读各书 distill.json(绝不重蒸)聚合成 author.json → 渲染作者演变页 author.html(4 视图:时间线 / 母题 ribbon / 思想转向 / 概念演化图)。每书蒸馏页顶部「演变入口卡」(SLOT:AUTHOR-ENTRY)链到它。
• 读哪个 reference:author-craft.md(§0 事实 vs 叙事铁律 / §2 author.json schema / §4 四视图数据契约 / §5 板块骨架 / §6 转向证伪层 / §7 入口卡)。
• 跑哪条命令:python $SKILL\scripts\build_author.py --author "<作者名>" --data-root "$DATA" --manual "$DATA\authors\{author_slug}\author.manual.json" --enrich "$DATA\authors\{author_slug}\author.enrich.json" --out "$DATA\authors\{author_slug}\author.json"(已有 author.json 且 manual 缺失时防覆盖栏拒跑,确需重建加 --force;<2 部 exit 3 不生成);再复制 templates\author-page-skeleton.html、把 #author-data 槽替换为该 author.json 生成 author.html。
• 产物:$DATA\authors\{author_slug}\author.json + author.html。
• 显式成员与站内书页:需纳入合著作品或固定策展边界时,在 manual 写 member_slugs:[slug];清单中任一成员缺失、损坏或内部 slug 不一致即 exit 2,不得静默缩小集合。可在 book_meta.{slug}.web_url 写站内根相对书页路径(如 /library/work-a.html);只接受安全的单 / 起始路径,非法值不进入产物。
• 触发门槛 / 降级:该作者 <2 部已蒸 → build_author.py exit 3 不生成、连网搜(enrich)不启、每书页入口卡整卡删。
• 出厂验证:python $SKILL\scripts\verify_page.py "$DATA\authors\{author_slug}\author.html"; echo "退出码=$?"(自动识别作者页走独立门禁:4 视图齐 / 零外链 / Zero-Hex / lang=zh / 破折号 / slug 与 web_url 安全 / 转向 verdict 一致;exit 0 才算完成)。

StepB · 主题聚合(可选,同主题 ≥3 本已蒸时)

同一主题下已蒸 ≥3 本作品时,可选做「主题聚合专题」页 -- 把各书按流派归类、把分歧摆上台面、把可执行数字并排对照。单书/双书不涉及,<3 本不生成。StepA 聚合「同一作者的思想演变」(时间轴);StepB 聚合「同一主题下各书的立场光谱与分歧」(空间轴),对称迁移非照搬四视图。

• 做什么:只读各书 distill.json + knowledge-index.json(绝不重蒸)聚合成 topic.json → 渲染主题聚合页 topic.html(4 视图:分类地图 / 分歧矩阵 / 维度对照表 / 书目导航)。每成员书蒸馏页顶部「主题入口卡」(SLOT:TOPIC-ENTRY)链到它。
• 读哪个 reference:topic-craft.md(§0 事实 vs 归纳分层铁律 + 成员圈定 / §2 topic.json schema / §4 四视图数据契约 / §5 板块骨架 / §6 外部争议 enrich / §7 入口卡)。
• 跑哪条命令:先手写 $DATA\topics\{topic_slug}\topic.manual.json(圈定 members:[slug] + schools 流派归类 + disputes 分歧分组 + dimensions 维度对照 + verdict 怎么选);再 python $SKILL\scripts\build_topic.py --topic "<主题名>" --data-root "$DATA" --manual "$DATA\topics\{topic_slug}\topic.manual.json" --out "$DATA\topics\{topic_slug}\topic.json"(已有 topic.json 且 manual 缺失时防覆盖栏拒跑,确需重建加 --force;<3 本 exit 3 不生成);再复制 templates\topic-page-skeleton.html、把 #topic-data 槽替换为该 topic.json 生成 topic.html。
• 产物:$DATA\topics\{topic_slug}\topic.json + topic.html。
• 成员圈定 = manual 显式列 slugs:主题边界是编辑判断,不改 distill schema、不自动按 tag 归堆(见 topic-craft §0);清单中任一成员缺失、损坏或内部 slug 不一致即 exit 2,不得静默缩小集合。book_meta.{slug}.web_url 与 StepA 同样只允许安全的站内根相对路径。
• 分歧与平行对照分流:分歧矩阵只渲 CONTRADICTS(knowledge-index 已登记真对立,红旗)和 curated(编者归纳、金标,note 须给依据)。相关但不互斥、回答不同层次问题的材料写入独立 parallel_comparisons[],至少两列且每列均有可回指成员与非空 stance,渲染为 .cmp-card,不计入分歧数;旧 manual 的 disputes[].parallel:true 会迁移到该独立数组。未显式声明、仅被算法判为 parallel 的松散并列仍剔除不渲。编者归纳出 index 未登记的真分歧轴时,应回补进 knowledge-index。
• 触发门槛 / 降级:有效成员 <3 → build_topic.py exit 3 不生成、每书页入口卡整卡删;external_debate 整块搜空 → 该板块隐藏,分类/分歧/维度作书内事实照发。
• 出厂验证:python $SKILL\scripts\verify_page.py "$DATA\topics\{topic_slug}\topic.html"; echo "退出码=$?"(自动识别主题页走独立门禁:4 视图齐 / 零外链 / Zero-Hex / lang=zh / 破折号 / slug 与 web_url 安全 / index_relation + certainty 枚举 / 分歧与平行对照可回指 / .dsp-card、.cmp-card 数量精确;exit 0 才算完成)。

StepC · 人物/博主蒸馏(creator_corpus 路径)

蒸馏对象是「一个人的跨媒介全部作品」(视频博主的全部视频 + 专栏/Newsletter + 书 + 播客)时走本路径,不走 Step0-Step7 主管线 -- 主管线的分析单位是「一部作品」,本路径的分析单位是「人」,基本单元是跨媒介归并后的「观点族」。

• 做什么:全量采集 → 来源卡建库 → 去重聚类(观点族/主题/关系/时间线) → 总体蒸馏(系统/模型/张力/谱系) → 外部交叉核验 + 通俗化两道闸(必做) → 产出与网站 creator-distill 契约一致的 10 份数据 JSON + 作者简介。
• 读哪个 reference:creator-craft.md(§0 路由 / §1 总原则「输入全量采集、分析完整建库、展示去重重构」/ §3 P0-P9 阶段管线与批次门 / §5 密度下限 / §6 外部交叉核验 / §7 通俗化两道闸 / §8 展示层信息架构 / §9 数据流规则)。
• 产物:{人物项目目录} 五层数据(L0-L4) + 下游网站数据包；页面渲染、契约测试与部署由消费该数据包的产品工程负责。
• 先例与模板:references\creator-craft.md 记录了经多人物实测收敛的来源卡、证据索引与导出契约；公开测试使用合成 fixture，不依赖任何私有项目目录。
• 与 StepA 的区别:StepA 聚合「同一作者已蒸的 ≥2 本书」(只读 distill.json,绝不重蒸);StepC 从零蒸「一个人的全部语料」。人物出了书且书已单蒸,两者可共存。

Biography · 证据型人物传记(biography_corpus 候选路径)

当目标是复原人物生平，而不是总结其自有作品中的思想时，使用 biography_corpus。这条路径不生成书籍蒸馏 HTML，也不复用 StepC 的观点族 schema。

• 做什么：为每个人物初始化独立 store → 建 Source Unit 与逐条 Observation → 由正式 reviewer 签署 admission / resolution → 形成六类 Canonical → 编写 Editorial → 补外部核验 → 以同一语义审计器执行 audit / strict-data / publish-ready → 把只读投影交给下游产品。
• 读哪个 reference：biography-craft.md。当前实验契约为 0.9.0-candidate，机器形状以 biography-contract-v0.9.0.schema.json 为准，跨文件闭包以 scripts\biography_contract.py 为唯一实现。仓库 SemVer 与数据契约版本是两个独立版本域；候选契约在稳定前可能调整。
• 模型边界：GLM-5.3 或其他外部模型可以并行做查漏、冲突扫描和修订建议，但只能写 recommendation_only；正式事实裁决只允许 manifest 中登记的 human 或 main_agent reviewer 签署。
• 跨人物隔离：每个人物都有独立 slug、稳定 subject ID、ID namespace、路由、资源目录和 CSS scope；共享资源必须显式登记为只读并绑定摘要，禁止从另一个人物项目继承隐式默认值。
• 与「一页」产品的边界：本路径交付公共数据契约、初始化骨架与门禁，不规定某个站点的信息架构、视觉、SEO 或发布流程。下游只读 Canonical / Editorial 投影，不能把页面状态反写事实层。

硬门禁(三处,不过不许往下走)

1. Step0 exit 3 → 停下问用户:诊断判「需OCR」(扫描版纯图)或「需人工确认」(gb18030 疑似假字/乱码率>2%)时,不启动蒸馏、不硬读、不编内容,把 diagnose 结论报给用户定夺(补 OCR / 换文件 / 人工核编码)。视频系列同理:build_series.py exit 3(全部视频都缺转写,一个都没抓到)→ 停下问用户(补转写 / 换视频 / 核 manifest),不拿空语料硬蒸。

   toc_detected: false / chapters_detected: 1 也要停(v0.5 补):目录结构没识别出来 = 蒸馏时手里没有原书章节划分,章数只能靠模型自由发挥(2026-07-26 实测:6 本全切自同一个「套装共5册」合订 epub,toc_detected 全 false,产出的章数一律被压成 6 章)。 套装/合集 epub 走 --volume 切,别整本硬蒸、也别手工切:convert_book.py --list-volumes 列出顶层分册与各自章数 → 逐本 --volume "<分册名>"。切分按 TOC 顶层定分册、按 spine 区间取正文(未列入目录的正文续页也收进来,只取 TOC 篇目会静默丢正文),diagnose.title 自动取分册名。chapters_source 字段标明章数来自 epub_toc 还是 body_regex。 v0.9.0 补:--list-volumes 输出新增 index 字段,供 --volume-index 按下标寻址(分册重名时唯一可用的路径,且切出的 title 取自目录节点原名,遇到「目录」这类名字要人工改写)。容器 >1MB 却只切出 <5000 字会降级为「需人工确认」并 exit 3 —— 那是切到封面页了,别当成书薄。古籍电子书的生僻字造字图现在转成 〔图字:…〕 可见标记,diagnose.inline_glyph_images 给计数;正文因此比旧版略长(造字图多的分册约 +0.2%~1.4%),是补回来的信息,不是重复内容。

2. Step2 两遍质量门禁自查(G1-G23):Pass1 骨架 + Pass2 详实转述产出后,按 method.md §7 逐条自查。通用/书型/详实门 G1-G21 不变;stakes=high 条件激活 G22;domain_profile.domain=psychology 条件激活 G23,要求每条 core_idea/decision_rule 有唯一 claim_id + 合法 claim_type。命中即打回重蒸/回补,不带病进 Step3/Step6。

3. Step7 verify v2 exit 0 才算完成:verify_page.py(v2,传 --distill 追加契约门禁)退出码非 0 就不是成品。已知心理学项目必须同时传 --require-domain psychology --distill ... --source ...,否则严格验证直接失败;默认不传严格域则保持旧书兼容。心理学严格域另要求同书目录 source-audit.json,其中 claim map 必须绑定该目录固定文件名 claim-coverage.json,并核四输入 hash、原文章界、逐项原文命中、全部 audit flags 账本覆盖、evidence 对最终 claims 的精确覆盖及 HTML 三栏映射(见 source-audit.md)。按输出修数据/样式后重跑,直到 exit 0。绝不放宽验证阈值或删检查项来假过关。

   T0 三道补盲门(v0.5,2026-07-27 加):[占位] 模板槽 / dummy 残留、[schema] 顶层必需键缺失、[lint] 封面是占位 SVG -- 三者恒校验、任何 render_profile 不可关。立法起因见 flash-mode.md §0(旧门禁 174 项全是「校验已有字段的取值」,默认「一定会填槽、一定产全 schema」;模型把模板原样交付或少产半个 schema 时,循环空转 = 零违规放行)。[schema] 项对 2026-07-27 前蒸的旧书会报 render_profile/cover_intro 等缺失,属预期,旧书不必重蒸。⚠ 默认/普通书 verify 仍主要查「结构 / 契约 / 版权长度 / 防注水」,不保证事实正确；心理学严格域会额外机检 source-audit 中声明的原文片段与行号、覆盖和输入 hash,但仍不能替代对「是否遗漏关键反例 / 是否误解语境」的人工语义复审。exit 0 ≠ 内容绝对属实(高后果书另做人工抽检,见铁律「不编造」)。

4. 批量交付闸 exit 0 才许上站(v0.5,蒸多本时):单本 verify 只回答「这一本合不合格」,回答不了「这一批该有的都在吗」。上站前把预期名单显式交给批量闸核对:

   python $SKILL\scripts\verify_batch.py --data-root "$DATA" --slugs slug1,slug2,slug3; echo "退出码=$?"
   # 已知心理学批次必须把严格域传播到每一本
   python $SKILL\scripts\verify_batch.py --data-root "$DATA" --slugs slug1,slug2,slug3 --require-domain psychology; echo "退出码=$?"
   

   它逐本核 ①产物齐备(缺 distill/html = 这本根本没蒸完)②verify_page.py 退出码 ③交付卫生(enrich 缺失 / _pass2_g*.json 中间态残留)。心理学严格批次还强制 book.txt 与 source-audit.json 存在，自动传播 --source 并逐书复算审计 hash；默认批次行为不变。退出码 0 才允许上站;非 0 时二选一 -- 补完管线,或把这本从上站名单里摘掉。⚠ 名单留着而产物不存在 = 线上 404(2026-07-26 实测:6 本里 2 本只跑到 Step0,仍被挂上作品集页)。

铁律(每步都守)

• 锚点:蒸馏内容必须锚定原文,method.md §5.1 六类字段(core_ideas / decision_rules / quotes / mental_models.evidence / chapters.excerpts / self_check)每条带 anchor,上站进 data-source;无锚点论断 = 门禁打回。
• 论点式标题(v2):chapters[].title / M04 <h3> 一律可反驳的判断句,禁「第N章 / 视频N」式纯章号、禁通用容器词(章节脉络/全书脉络/金句墙/总结/概述…),有效长度 ≥8 字(G8;verify 机拦黑名单+长度,判断句语义靠蒸馏自查)。脑图二级节点(v4 批 A 双层化)例外:topic 改概念关键词 ≤10 字做扫读层、取消 ≥8 字下限(仍守黑名单+禁容器词);可反驳判断句下沉到 tags[0](≥8 字,verify 机拦缺失/过短),tags[1] 放「第N章」章码 chip(见 method §4.6 / html-spec §5)。
• 详实度下限(v2):每章 narrative 书 ≥800 字 / 视频段 ≥400 字(G9);宁可少论点讲透,不注水;标志性案例 / 故事必须整段完整讲(时间·人物·动作·转折·结果),禁压成一句标签。
• 真封面(书,v2):书籍 M01 封面必须真封面 base64(data:image),禁外链、禁纯色占位;联网拿不到才退占位 SVG。视频用系列封面(首集缩略图 data: URI)。
• URL:外部信息(作者/书评/同类书/观点对比/跨书外部/心理学科学证据)必须带可点击 http(s) 来源 URL;拿不到就按各块契约降级,不臆造。心理学可检验 claim 不得整块隐藏,证据不足要显式低置信或未复制。
• 不编造:金句 <blockquote> / excerpts 原文照录不改写(直接照录单段 ≤150 字,blockquote 明示引用,连续 30 字与原文雷同即版权红线须改写);拿不到的数据(评分/年份)据实留空,不制造假精度。evidence_level 只表示原书转述忠实度,不得当作科学有效性。高后果书事实抽检(stakes=high):育儿 / 医疗 / 理财 / 法律等读者会照着做、数字错会误导的书(判定见 method.md §1.5),蒸完须人工回原书抽检 ≥5 条可执行数字 / 月龄 / 剂量 / 时长 + 金句,确认所标 anchor 指向处确有其文、数值未被记串。抽出错即回改或降 evidence_level;这类可执行数字还须逐条标 certainty(见 §4.5.16/G22)。心理学书另逐 claim 做外部科学证据核查(见 enrich §1.1/G24)。
• 破折号一律 --:所有给读者看的文字里用两个英文连字符,禁全角 ——。
• 底部「回原书」声明:页面底部固定 AI 拆书当地图、别当目的地的收口声明(骨架已带,别删)。
• 上站 = 有静态入口 + 有 SEO 头,少一样等于没上站(2026-08-14 实证,代价:一批蒸馏页零收录):
  • 静态入口:新蒸的书必须能从某个目录/书单页用静态 <a href> 点到。判据是 HTML 里那条边 —— 搜索引擎只认它,JS 运行时才渲染出来的导航对爬虫完全不存在。只把 HTML 丢进静态目录、 只登记进索引 JSON、只提交 sitemap,都不算:实测这样的页面会被判「已发现 - 尚未编入索引」, 一篇都不收。而它毫无症状 —— 页面能开、构建不报错、索引也登记了。
  • SEO 头:蒸馏产出的独立 HTML 往往只有 <title>。上站前补 description / canonical / og:*,用幂等脚本批量注入(读书目 JSON 取书名作者简介封面),别手改一百个文件。
  • URL 一致:目录页链 /x/ 而 sitemap 提交 /x/index.html,同一篇会以两个 URL 进索引。
  • 数量一多就该建从数据真源自动生成的目录页:内容增删自动跟随,不需要谁回头维护清单。

批量模式(蒸多本)

成本大头在编排层,不在 Pass2 分块数:逐章命名 ≠ 逐章派 agent,各 subagent 仍守「≤5 章/组」,砍分块数省不到 token 且掉详实度。真正吃 token/时长的四项:①并发撞 529 风暴 ②会话碎片化 re-grounding ③同作者重复联网 ④失败假重跑。以下按此立规,优化编排、不砍生成深度。

• 先抽样 1 本人工验收再铺量:多本任务先完整跑通 1 本(Step0-7 + 浏览器过一遍),你/审校者确认质量与 signature 成立,通过才铺其余;通过后错峰铺,不齐发。
• 上站前必过批量交付闸(见硬门禁④):verify_batch.py --slugs <预期名单> exit 0 才许上站；心理学批次追加 --require-domain psychology。预期名单必须显式声明,靠人肉数「应该都蒸完了吧」正是 2026-07-26 漏掉 2 本仍上站的病因。
• 跨会话并发闸:全局在飞的 Pass2 subagent ≤ 6-8 个,不论开了几个会话 / 几个作者批次并行。多作者批次禁同时段并跑 Pass2 —— 多作者通宵并发会直接引爆服务端 529 风暴(大量 agent 撞 529、大量 retry、墙钟拖到 8-9 小时)。批次之间错峰发起,别十分钟内齐发。
• 1 本书 = 1 会话(或每会话 ≤2-3 本):避免单会话塞多本反复 compact(实测单会话曾 compact 8 次)。会话续接只重读小的 distill.json checkpoint,禁重读 book.txt 全文(实测 book.txt 曾被重复引用 60-198 次/会话)。
• 批前估 token 预算:铺量前粗估「N 本 × 每本约 X = 总量」,对照账户周/日用量上限;超则分日/分批跑,预留撞用量上限的余量(实测批量铺量曾把账户用量跑爆、被迫中途暂停)。全程用高能力模型、不做 token 节流仍成立,但要预判总量别中途断粮。
• 失败先核盘再重派(防假重跑):agent 报「失败」多为已写盘、只是返回元数据时被限流。重派任何失败 agent 前,*先查 $DATA\{书目录}\ 下 `_pass2_g.json/ 产物是否已落盘**:已落盘只对缺章做**定点 gap-fill,禁整组重跑**。fan-out 合并后断言「N 章 narrative 全齐且达标」,只补真缺口(见method.md §3.5.5` 合并完整性门禁)。
• Pass2 产物统一命名 _pass2_gN.json + 合并后清理:并发多会话易各自即兴命名(曾并存 _ch_N/_pass2_N/_pass2_gN/_pass2_batchX 四套),漂移致合并对不齐、掉章。统一只用 _pass2_gN.json;合并完整性门禁通过后,主控删本书 _pass2_g*.json 中间态(已 gitignore、已回填 distill,别留到入库/聚合污染目录 -- 2026-07-15 复盘 13 本睡眠书 7 本残留)。见 method.md §3.5.5 清理步。
• 同作者 enrich 只搜一次:批量拆同一作者多本时,作者研究(author_page)一位作者只联网搜一次,写 $DATA\authors\{author_slug}\author.enrich.json,各书 enrich 的 author_page 引用它、不重搜(否则同一作者多本各自重搜作者背景 = 大量冗余联网轮次);与 StepA 作者演变聚合页共用同一份作者研究(见 enrich.md §3 + StepA)。
• 索引串行登记:Step4 的 update_index.py register 会写同一个 knowledge-index.json,批量时串行登记(逐本 dry-run→真跑),避免并发写盘互相覆盖;每次写前自动 .bak。

环境依赖

• Python >= 3.10:pip install ebooklib beautifulsoup4 pymupdf pillow pytest playwright + playwright install chromium(Step7 需 chromium;pillow 用于真封面 / 缩略图的压缩与 base64 内联)。biography_corpus 候选路径另需 jsonschema>=4。
• azw3 / mobi 输入需 calibre 的 ebook-convert(winget install calibre.calibre);epub/pdf/txt 不需要。
• 视频系列(取材 cascade 见 method.md §V.0):yt-dlp(YouTube 抓字幕 + 抓评论;B站评论走公开 API 免依赖)。B站/抖音的转写需一个字幕/ASR 上游工具(如 video-to-subtitle-summary,读其 AI_DOUYIN_API_KEY);fetch_comments 的 B站评论无需 key。无字幕 / 需画面语义走一个 Gemini 视频分析工具,如独立公开 skill sansheng-gemini-video(读 env GOOGLE_API_KEY),装上即可;不装不影响书籍蒸馏与有字幕视频。