# Explainer Narrative Flow

> 把任意主题（技术概念、框架、API、产品、算法、流程等）讲成新手能一口气读懂的「深度讲解」内容，输出可为 HTML 长页、Markdown 文章或其它格式。核心方法是「懂→用→慎」三幕递进动线：先用生活类比建立直觉，再给真实应用，最后才讲限制与风险，并按主题类型自适应选节。当用户要求新手向解读、通俗讲解、生活化比喻、把文档讲清楚、调整讲解顺序、消除重复章节、或做成可分享的 explainer 时触发。关键词：深度讲解、新手向、通俗解读、生活类比、讲解动线、explainer、递进结构、把概念讲清楚。

- Skill: `xiaoweidotnet/explainer-narrative-flow` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add xiaoweidotnet/explainer-narrative-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoweidotnet/explainer-narrative-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: xiaoweidotnet (https://skillmd.com/u/xiaoweidotnet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaoweidotnet/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 通用规范