运行方式（先看这个，别自己造轮子）

本 skill 自带生成器脚本，不要临时手写 TTS/注入逻辑，直接调：

# 1) 脑图   —— 自动建并归档到 ./书名_图图解读/
python3 scripts/make_mindmap.py <脑图数据.json> --title "《书名》"

# 2) 动画（含真人配音） —— 落进同一个文件夹
python3 scripts/make_animation.py <书籍spec.json>

# 2b) 规模自适应：带上章节数/字数，parts 数与详略由书决定
python3 scripts/make_animation.py <书籍spec.json> --chapters 22 --words 240000
# 2c) 默认单集连续（时长随内容变，不拆分）；要拆多集用 --split（抖音等竖屏短视频）
python3 scripts/make_animation.py <书籍spec.json> --split --max-duration 75

# 3) 章节图 —— 用 ImageGen 生成后存进该文件夹，命名 书名_章节图.png

# 4) 自检
node scripts/check.js "./书名_图图解读/*.html"

插画模式（推荐画风 / 默认成片风格）

手绘图形适合讲概念；要更耐看、更有质感的成片，用插画模式（现已是推荐默认）——每个场景一整幅 AI 插画做底图并缓慢推镜（Ken Burns），
文字/字幕仍由播放器叠加。不传 --illustrated 则回退手绘风。

# ① 生成风格锁定的提示词 → illustrations/prompts.json + prompts.txt（默认单集，9 个场景 key）
python3 scripts/make_illustrations.py <书籍spec.json> --chapters 42 --words 400000
#    若要拆多集，加 --split（会多生成 continue/recap 承接场景 key）

# ② 按 prompts.json 逐条出图，图片存进 illustrations/，文件名必须等于场景 key
#    场景 key：cover / overview / p1…pN / ending（单集）；加 --split 时另有 recap / continue
#    提示词已统一加风格前缀并禁止出现文字，所以整本书画风一致、图上不会有糊字。

# ③ 合成（默认单集连续；缺图的场景会自动回退手绘，不会开天窗）
python3 scripts/make_animation.py <书籍spec.json> --illustrated \
    --tts-provider edge --voice zh-CN-XiaoxiaoNeural

• 想给某一部分指定画面：在 spec 的 parts[i] 里加 "img_prompt": "…"；封面/结尾同理用
  cover_img_prompt / ending_img_prompt。
• 图片超过 420KB 会自动压到 1280 宽并转 JPEG（需 Pillow），避免最终 HTML 过大。
• 插画里的文字一律不要：所有标题、要点、字幕都由播放器叠加，AI 画字必糊。

> 不指定 -o 时两件脚本都会自动建 书名_图图解读/ 并归档进去（铁律一）。
> 需要改文件夹名用 --folder，需要完全自定义路径用 -o。

• 数据格式：照抄 examples/mindmap_data.example.json 与 examples/book_spec.example.json；
  不确定就跑 python3 scripts/make_animation.py --print-schema。
• 安装与依赖、换嗓音、平台迁移见 README.md。
• 脚本用 Path(__file__) 相对定位，整个目录拷到任何平台都不用改路径。
• 依赖：配音支持多音源——siliconflow（硅基流动 fish-speech，国内可达，需 key：环境变量 SILICONFLOW_API_KEY 或 --tts-key）、edge（微软 Edge TTS，免费无 key：pip install edge-tts）、local（自定义 OpenAI 兼容 /audio/speech，--tts-endpoint 指定）、none（--no-tts 不配音）。auto 默认按可用性自动选；自检需 npm i jsdom（缺则自动跳过）。
• 八段场景顺序由 make_animation.py 自动拼装，调用方无法漏掉封面/总览（铁律二的结构性保证）。

图图吧 · 图书解读动画工作流

把任意一本书转化为「结构化脑图 → 动画解说」的端到端流水线。本质不是单一技能，而是四段流水线 + 五类技能，权重严重不均。

铁律（不可协商，每次运行都必须满足）

铁律一 · 每本书单独归档，且必须产出 3 件

每本书的所有产出放进独立文件夹 书名_图图解读/（两个生成脚本不指定 -o 时会自动建并归档，
脑图脚本给了 --title "《书名》" 也会落进同一个文件夹）。不允许把多本书混在一个目录里，
也不允许把散件丢在工作区根目录。

目录示例：

富爸爸穷爸爸_图图解读/
├── 富爸爸穷爸爸_脑图.html
├── 富爸爸穷爸爸_章节图.png
├── 富爸爸穷爸爸_动画.html
└── 富爸爸穷爸爸_解说脚本分镜表.md

• 缺 3 件主产出中任意一件即为未完成，不得以「用户没提」为由省略。
• 顺序固定：先脑图（定骨架）→ 再章节图（定视觉）→ 最后动画（定表达）。
• 脑图没定稿，不许往下做动画——骨架错了，动画做得再好也是放大错误。
• 想改文件夹名用 --folder；想完全指定路径用 -o。

铁律二 · 动画解说的场景顺序固定

动画 scenes 数组必须按下面四段结构排，不许直接从第一章开始讲：

• 总览的 nar 要完整覆盖全书内容 + 逐部分预告（先说核心主张，再「第一部分讲…第二部分讲…」），听众看完总览就知道整本书长什么样。
• 封面与总览不是可选的装饰，是硬性前置段；跳过 = 不合格。

铁律三 · 视觉与排版

• 手绘引擎必须走 rough.js（已内嵌在 assets/animation.html，离线可用）。禁止退回 feTurbulence+feDisplacementMap 滤镜方案——滤镜只是给形状糊一层噪点，显糙且伤文字。
• 动画 HTML 必须一屏放得下：body 纵向 flex + 100dvh，画板 flex:1; min-height:0，SVG 必须带 preserveAspectRatio="xMidYMid meet" 且 width/height:100%。禁止给画板写固定像素高度。
• 配音只认预生成 mp3：有 audio 的场景，播放失败时禁止回退浏览器 TTS（机械音），只能提示点击后用原 mp3 重试。
• 每份产出交付前必须自检无错别字（人名、术语、数字逐项核对）。

铁律四 · 规模自适应（内容量决定时长，默认单集连续）

内容量直接决定输出多少、动画总时长随内容量延长；默认产出一条不拆分的连续动画，多集拆分改为显式 --split 开启。

• 规模自适应（时长由书决定）：spec 提供 chapters（章节数）/words（字数）后，脚本自动建议 parts 数量与每段详略；不提供也能跑，但建议带上以启用自适应。档位映射（单集连续总时长 ≈ 封面5s + 总览12s + Σ段 + 结尾6s）：
  | 档位 | 触发 | parts 数 | 每段解说字数 | 单集连续总时长 |
  |---|---|---|---|---|
  | thin | ≤8 章 或 ≤8 万字 | ~5 | ~150 | ~75s |
  | medium | 9–18 章 或 8–18 万 | ~8 | ~190 | ~150s |
  | thick | ≥19 章 或 ≥18 万 | ~12 | ~230 | ~280s+ |
  内容越多 → parts 越多、每段越详 → 单集连续动画总时长越长。这是「输出篇幅由书决定」的结构性保证，不靠手动凑；加 --illustrated 后每段还会叠一幅 AI 插画 + 推镜。
• 默认单集连续（v1.5.0 起）：不传 --split 即为一条完整动画 书名_动画.html，封面 → 全书总览 → 逐部分 → 结尾 一气呵成，总时长 = 全书内容时长（见上表）。适合「一镜到底」、B站/视频号/小红书长视频，或作为剪辑软件时间轴底稿。
• 多集拆分（按需 --split）：传 --split 后，单集预计时长超过 --max-duration（默认 90s）时，脚本把 parts 按次序贪心切分为多集，每集独立 HTML，文件名 书名_动画_上.html / _中.html / _下.html（更多则 _续N.html）。
• 封面带集数徽标（右上角「第 X/共 Y 集 · 上」）；
• 首集含全书总览，承接集改含本集要点（承接上集）；
• 末集用结尾金句，非末集用「下集待续」收尾并预告下集；
• 单段自身超长也会独占一集，确保不丢内容。
• 适合抖音等 ≤60s 竖屏短视频、系列化发布；--split --max-duration 60 可压到每集 60s。

核心判断（先给结论）

• 这是一条四段流水线：原书输入 → 内容提炼 → 脑图构建 → 动画解说；「工具运用」与「流程整合」贯穿全链路。
• 五类技能权重不均：①内容提炼=天花板（决定上限）、②脑图构建=转换器、⑤流程整合=黏合剂（唯一不可被工具替代）、③动画解说=放大器（救不了烂骨架）、④工具运用=杠杆（省 60% 机械活）。
• 优先级：P0 = ①内容提炼 + ②脑图构建；P1 = ⑤流程整合 + ④工具运用；P2 = ③动画解说（可 TTS/模板降本）。
• 统一视觉语言：脑图、动画、章节总结图全部手绘风（灵动抖动线条、字随线动、纸感背景、插画点缀），保证三份产出视觉一致。
• 最高频失效：把目录当骨架（目录搬运）、笔记化（摘录集）、AI 一键生成即交付（只到目录级）。

统一视觉语言（手绘风三件套）

三份产出共用同一套视觉，读者一眼认出是「同一本书的图图吧解读」：

1. 纸感点阵底：浅米色 #FBF7EF + 点阵纹理。
2. 灵动手绘线：rough.js（Excalidraw 同款引擎，已内嵌 assets/rough.js，离线可用）生成真正的多笔速写路径——同一条边画两遍、带轻微弯曲与出头，这才是手绘感。
   - 旧方案 feTurbulence+feDisplacementMap 已废弃：它只是给形状糊一层噪点，线条发毛、文字发虚，观感「糙」。
   - 用法：一次形状 = 一次填充（fillStyle:'solid'、淡入）+ 一次描边（fill:'none'、描边生长），两者共用同一 seed 保证贴合。
   - 底层工具见 assets/animation.html：rRect / rCircle / rLine / rCurve / rArrow / rPoly / rPath / txt / char / coin。
3. 楷体手写体 + 柔和粉彩配色：色类 t1—t6 + 中央 central，见 assets/mindmap.html 与 assets/animation.html 顶部变量。
   - 注意：SVG 表现属性里不要用 var(--x)，一律用 JS 调色板 C.t1 等真实色值。

> 脑图套 assets/mindmap.html；动画套 assets/animation.html；章节总结图套 references/chapter_image_prompt.md（漫画风，与手绘风同源）。

工作流（拿到书名即启动）

阶段 0 · 原书输入（书名直生成）

• 阶段 0 直接以书名启动：常见书直接给书名 + 作者；罕见书/小众书再补 PDF 或原文切片，由模型提炼骨架。
• 本工作流产出全部用自有生成完成：模型按下方方法提炼骨架并产出脑图/脚本/动画，不依赖任何第三方脑图云 AI，无需登录或调用外部服务。

阶段 1 · 内容提炼（技能①，P0，最重要）

动作：
1. 判断书籍类型：论点型 / 知识体系型 / 叙事型 / 汇编型（类型决定骨架取法）。
2. 主张提取（Claim Mining）：抽作者「可被反驳的论断」，不是信息。
3. 论据—证据三层分离：观点 → 论据 → 证据（数据/实验/案例/引文）。
4. 章节脉络还原：识别论证推进关系（问题→原因→解法 / 现象→机制→应用），主分支跟着推进关系走，不跟目录走。
5. 跨章节归并：合并作者分散重复讲的同一论点。
6. 密度控制：进脑图信息量约原文的 3%—8%。
- 产出：知识骨架（带层级、论证关系、取舍说明）。
- 验收：删任一主分支读者明显觉得缺东西；任意分支能答「作者为什么这么说」。

阶段 2 · 脑图构建（技能②，P0）

动作：
- 层级设计：中心节点放核心主张（非书名）；主分支 5—7 条。
- 节点文字：短语化、同级同语法结构。
- 同层同逻辑（MECE）。
- 配色编码（演示友好）：用颜色区分信息类（观点/论据/案例/建议）。
- 详略双版本：完整版存档 + 演示版（砍到 30%—50%）做动画。
- 默认出手绘风脑图：直接套用 assets/mindmap.html，替换 data 对象即可，配色类 t1—t6 + central；节点与连线由 rough.js 生成多笔速写路径（内置缩放条：适应宽度 / ±15%）。点 ± 可展开收起分支。
- 圆角矩形走 rrPath() + rc().path()——rough 的 rectangle() 不支持圆角。
- 产出：可交互脑图 HTML（演示版）。

阶段 2.5 · 章节总结图（可选）

• 若需要社交媒体/短视频封面，可用图片生成工具产出漫画式章节总结图，风格参考「小德 MOMO」：卡通人物 + 数字分步 + 气泡对话框 + 核心规则板 + 底部核心理解栏 + 结论区（与手绘风同源，观感统一）。

• 模板见 references/chapter_image_prompt.md；可用参考图做 image-to-image 风格迁移，约消耗 5—10 积分/张。

• 边界：单图建议 ≤200 节点，演示才跟得住。

阶段 3 · 动画解说（技能③，P2）

动作：
- 场景顺序严格按铁律二：封面 → 全书总览 → 逐部分章节动画 → 结尾。总览分了几部分，后面就出几段，一一对应。
- 规模自适应（铁律四）：写 spec 时带 chapters/words，parts 数量与每段详略由书的内容量决定（thin/medium/thick 见铁律四映射），不要对厚书也只写 4—5 段。脚本会打印规模建议并校验偏差。默认产出单集连续动画（时长随内容量拉长）；需多集短视频时加 --split，单集超 --max-duration（默认 90s）即自动拆成上/中/下，每集独立 HTML 按次序完整覆盖全书——你只需保证 parts 不遗漏，切分交给脚本。
- 解说脚本口语化：1 分钟 ≈ 200—240 字；开场 15 秒给「与我有关」的钩子。每段写成 2—4 句完整口语（有钩子、有解释、有过渡），不要只写一句话，否则朗读起来突兀。
- 分镜表五列：时间轴 / 画面动作 / 解说词 / 字幕 / 音效（套 assets/storyboard.md）。
- 风格手绘风动画解说（与脑图同一视觉语言）：纸感底 + 楷体 + rough.js 多笔速写线，做「灵动手绘板书」式动态图示。套 assets/animation.html，替换 scenes 数组即可。
- 画面预设（assets/animation.html 内置，按需选用或照此扩写）：
drawCover（封面）/ drawOverview（全书总览·自动 1—3 列布局）/ drawCompare（两相对照）/ drawMoneyFlow（双向流向）/ drawWheel（循环陷阱）/ drawQuadrants（四象限）/ drawCards（并列要点）/ drawEnding（结尾金句）。
- 两类入场动画：.draw = 描边生长（靠 pathLength="1" + stroke-dasharray:1，无需算路径长度）；.pop = 淡入上浮（文字/填充块）。给元素加 delay 可做出「一笔一笔写出来」的节奏。
- 真人配音（关键）：用神经网络 TTS 把每段 nar 解说词生成 mp3，base64 嵌进 scenes[].audio；引擎优先播放预生成音频、按音频自然时长切场，规避浏览器自带嗓音的「AI 味」。无 audio 时回退浏览器 TTS。字幕（移动端单行 ≤15 字）由 sub 提供。
- 音源（默认 auto 自动选）：--tts-provider siliconflow（硅基流动 fish-speech，国内可达、嗓音自然，需 key）、edge（微软 Edge TTS，免费无 key）、local（自部署/私有 OpenAI 兼容 /audio/speech，--tts-endpoint 指定）、none/--no-tts（不配音）。无 key 时自动回退 edge，再不行可 --no-tts 离线生成。每段配带超时（默认 30s）+ 指数退避重试（默认 3 次），网络抖动不卡死。
- 配音保真 + 自动播放（踩过坑，别再犯）：首屏直接尝试播放预生成的真人配音 mp3。若被浏览器自动播放策略拦截，只提示「点一下页面继续」，等手势后用同一段 mp3 重试——
严禁回退浏览器 TTS：一旦回退，声音立刻变回机械的「AI 味」，用户会直接听出来「又换回去了」。
只有没有 audio 字段的场景（如模板示例）才允许浏览器 TTS 兜底。
判断标准：有 audio → 只能用它；播放失败 → 提示 + 重试，不换声源。
- 反向校验：做出来放一遍，某段讲太久往往暴露①的重心判断错了 → 回阶段1。
- 边界说明：手绘风原型是「可交互预览 + 分镜基准」，默认预生成神经网络 TTS 真人配音（自然、不机械）+ 屏幕字幕，可一键静音；无音频时回退浏览器 TTS。正式成片在剪辑软件（剪映/Premiere）按分镜表换更高质 TTS、加 BGM（-25dB）与人声精修，手绘感由 rough.js 与字体延续。

阶段 3.5 · 排版与自适应（硬性）

• body 用纵向 flex + height:100dvh + overflow:hidden；header / footer 固定，#board 用 flex:1; min-height:0 吃掉剩余空间。
• SVG 必须 preserveAspectRatio="xMidYMid meet" + width:100%; height:100%，画板永远等比缩放居中，任何窗口比例都一屏放得下。
• 禁止给 #board / #stage 写固定像素高度——这正是旧版「屏幕放不下」的根因（宽度一拉高，SVG 等比变高，把字幕和控制条顶出视口）。
• 窄屏/矮屏用媒体查询收缩：矮屏（<620px 高）隐藏跳段标签、压缩字幕区；窄屏（<560px 宽）隐藏副标题。

贯穿 · 工具运用（④）+ 流程整合（⑤）

• ④：流程各阶段可杠杆的现成工具（脑图/动画/配音/图片生成）调用约定见各阶段说明，统一走自有生成，不绑定任何单一第三方产品。
• ⑤：固化 SOP + 六份中间产物版本留档（原文切片→骨架→脑图源文件→演示版→分镜表→成片）+ 三个强制关卡（骨架评审 / 结构评审 / 成片试看）。

五类技能速查

工具与依赖

脑图 / 动画 / 章节图 / 配音均可由本工作流自有脚本与 ImageGen 生成，不绑定任何单一第三方脑图产品。

交付物（对应铁律一，全部放进 书名_图图解读/）

1. 书名_脑图.html — 手绘风可交互脑图（scripts/make_mindmap.py 生成）。
2. 书名_章节图.png — 漫画式章节总结图，适合公众号/小红书/短视频封面（提示词见 references/chapter_image_prompt.md，ImageGen 约 5—10 积分/张；生成后存进该文件夹）。
3. 书名_动画.html — 手绘风动画解说（scripts/make_animation.py 生成；rough.js 手绘引擎，一屏自适应，含神经网络 TTS 真人配音 + 屏幕字幕；场景顺序按铁律二）。
4. 书名_解说脚本分镜表.md — 套 assets/storyboard.md（辅助产物，同样放进文件夹）。

三件主产出全部生成后，必须跑 node scripts/check.js "书名_图图解读/*.html" 自检，通过才算完成。

边界说明（全部自有生成，非调用第三方）

• 本工作流产出全部用自有生成完成，不调用任何第三方脑图云 AI，无需登录或调用外部服务。
• 快速验证可用自有原型；精品走手绘风分镜 + 剪辑软件合成。
• AI 一键生成只到「章节目录级」，不等于知识体系，须人工重构为「主张—论据—证据」（这正是阶段1的本职）。
• 演示场景单图建议 ≤200 节点。

自检清单

结构（铁律一 / 铁律二）
- [ ] 三件产出都齐了：脑图 + 章节图 + 动画解说？
- [ ] 动画第一段是封面（书名+作者+钩子）？
- [ ] 动画第二段是全书总览（讲清全书内容 + 分几部分）？
- [ ] 总览分了 N 部分，后面就刚好 N 段章节动画，一一对应？

视觉与排版（铁律三）
- [ ] 全部走 rough.js，没有残留 feTurbulence 滤镜？
- [ ] 脑图 / 动画 / 章节图视觉是否一致（手绘风）？
- [ ] 动画窗口拉宽、压扁都还能一屏放得下，字幕和控制条没被顶出去？
- [ ] SVG 是否带 preserveAspectRatio="xMidYMid meet"，画板无固定像素高度？

内容
- [ ] 不看脑图能用 3 句话说清这本书？
- [ ] 删任意主分支是否明显影响完整性？
- [ ] 节点是否短语化、同级同结构？
- [ ] 三份产出有无错别字（人名、术语、数字务必核对）？
- [ ] 换一本书流程能否原样再跑？