explainer-narrative-flow

# 深度讲解 · 递进动线 把一个主题讲成**读者能一口气读懂**的内容。不是复述资料，而是按读者的认知顺序组织：**先建立直觉，再给真实应用，最后才讲限制与风险。** 主题不限：技术概念、框架、API、产品、算法、设计模式、工作流程都适用。输出格式不限：HTML 长页、Markdown 文章、幻灯文稿等。 ## 内核：三幕递进（这是不可变的部分） ``` 第一幕 · 懂 先让读者明白「这是什么、为什么存在」 第二幕 · 用 再让读者看到「能拿它做什么、怎么用」 第三幕 · 慎 最后才讲「有什么限制、坑、代价」 ``` **为什么顺序不能乱**：读者先「懂」才有兴趣，再看「能干嘛」才有动力，最后才接受「有什么坑」。把限制/成本提前，会在价值感建立之前劝退读者。 可以增减、改名、合并具体小节，但**三幕的先后不可颠倒**。 ## 按主题类型选节（这是通用的关键） 三幕之下放哪些小节，取决于主题类型。先判断类型，再挑菜单： | 主题类型 | 第一幕·懂 | 第二幕·用 | 第三幕·慎 | |---------|----------|----------|----------| | **纯概念/原理**（如一致性模型、加密原理） | 是什么 + 生活类比 + 关键机制 | 在真实系统里怎么体现 + 常见误区 | 局限/边界条件 + 总结 | | **工具/API/框架** | 是什么 + 生活类比 | 真实例子 + 快速上手 + 配置定制 | 机制限制 + 注意事项 + 总结 | | **产品/功能** | 是什么 + 生活类比 | 典型用法场景 + 上手步骤 | 适用边界 + 费用/限制 + 总结 | | **流程/方法论** | 是什么 + 为什么需要 | 分步走 + 真实案例 | 常见坑 + 适用/不适用 + 总结 | | **多概念对比** | 各是什么 + 生活类比（统一映射） | 各自适用场景 + 决策树 | 误用风险 + 总结 | **默认全菜单**（适合工具/产品类）：是什么 → 生活类比 → 真实例子 → 快速上手 → 配置定制 → 机制限制 → 注意事项 → 总结。各节写法见 [references/narrative-structure.md](references/narrative-structure.md)。 没有「快速上手命令」「配置开关」「费用」的主题（如纯概念），**删掉对应小节**，不要硬凑。 ## 核心原则 1. **一个概念只讲一次**。若某节已讲清概念区别，后面**不要**再开「详细对比/深入辨析」的重复章节——这是最常见的臃肿来源。 2. **生活类比优先**（条件性必需）：只要主题有≥2 个易混概念或抽象到缺乏先验经验，第一幕就**必须**有生活类比；若主题极简单或纯操作步骤，可省略。方法见 [references/life-analogy-patterns.md](references/life-analogy-patterns.md)。 3. **大白话**：术语首次出现用括号给一句解释；避免「二选一」式误导（很多概念是分层/递进，不是互斥）。 4. **能可视化就可视化**：输出格式支持图表时，每节尽量配一图（尤其生活类比节）；纯文本格式则用结构化表格/列表替代。 ## 执行流程 1. **判断主题类型 + 输出格式 + 受众**（新手到什么程度）。未指明则默认「工具类 / HTML 长页 / 完全新手」。 2. **收集素材**：有 URL 用 `WebFetch` 抓取（含文档索引页补充）；只提取动线各节需要的事实并标注来源。 3. **按上表选节、逐节列要点**，确认无重复、符合「懂→用→慎」。 4. **设计生活类比**（若需要）：挑一个能映射主题每个核心概念的场景，方法见 life-analogy-patterns.md。 5. **生成输出**： - Markdown：直接按选定小节成文。 - HTML 长页：单文件，左侧固定目录 + 右侧滚动章节，自包含样式与图表；规范见 [references/diagram-checklist.md](references/diagram-checklist.md)。 - 命名 `explainer_[主题].{html,md}`。 6. **验证**（HTML 时）：用本地 HTTP 预览，确认图表渲染、目录与节号一致、过渡自然。 > 本技能只负责**内容结构与讲解顺序**，不绑定任何特定技能或仓库。若环境中已有网页排版/HTML 生成类技能，可复用其骨架。 ## 结构变更检查单 删节、合并、调序后必做： - [ ] 更新目录（TOC）文案与锚点 - [ ] 重排节号与图号，连续无跳号 - [ ] 删除指向已删章节的过渡句 - [ ] 确认没有重复讲解同一概念 - [ ] 确认三幕顺序未被打乱 ## 参考文件 - [references/narrative-structure.md](references/narrative-structure.md) — 各小节职责、写法与反模式 - [references/life-analogy-patterns.md](references/life-analogy-patterns.md) — 生活类比设计方法（含多领域示例） - [references/diagram-checklist.md](references/diagram-checklist.md) — 图表类型与 HTML/Mermaid 通用规范