explainer-narrative-flow

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

深度讲解 · 递进动线

把一个主题讲成读者能一口气读懂的内容。不是复述资料，而是按读者的认知顺序组织：先建立直觉，再给真实应用，最后才讲限制与风险。

主题不限：技术概念、框架、API、产品、算法、设计模式、工作流程都适用。输出格式不限：HTML 长页、Markdown 文章、幻灯文稿等。

内核：三幕递进（这是不可变的部分）

第一幕 · 懂   先让读者明白「这是什么、为什么存在」
第二幕 · 用   再让读者看到「能拿它做什么、怎么用」
第三幕 · 慎   最后才讲「有什么限制、坑、代价」

为什么顺序不能乱：读者先「懂」才有兴趣，再看「能干嘛」才有动力，最后才接受「有什么坑」。把限制/成本提前，会在价值感建立之前劝退读者。

可以增减、改名、合并具体小节，但三幕的先后不可颠倒。

按主题类型选节（这是通用的关键）

三幕之下放哪些小节，取决于主题类型。先判断类型，再挑菜单：

主题类型	第一幕·懂	第二幕·用	第三幕·慎
纯概念/原理（如一致性模型、加密原理）	是什么 + 生活类比 + 关键机制	在真实系统里怎么体现 + 常见误区	局限/边界条件 + 总结
工具/API/框架	是什么 + 生活类比	真实例子 + 快速上手 + 配置定制	机制限制 + 注意事项 + 总结
产品/功能	是什么 + 生活类比	典型用法场景 + 上手步骤	适用边界 + 费用/限制 + 总结
流程/方法论	是什么 + 为什么需要	分步走 + 真实案例	常见坑 + 适用/不适用 + 总结
多概念对比	各是什么 + 生活类比（统一映射）	各自适用场景 + 决策树	误用风险 + 总结

默认全菜单（适合工具/产品类）：是什么 → 生活类比 → 真实例子 → 快速上手 → 配置定制 → 机制限制 → 注意事项 → 总结。各节写法见 references/narrative-structure.md。

没有「快速上手命令」「配置开关」「费用」的主题（如纯概念），删掉对应小节，不要硬凑。

核心原则

1. 一个概念只讲一次。若某节已讲清概念区别，后面不要再开「详细对比/深入辨析」的重复章节——这是最常见的臃肿来源。
2. 生活类比优先（条件性必需）：只要主题有≥2 个易混概念或抽象到缺乏先验经验，第一幕就必须有生活类比；若主题极简单或纯操作步骤，可省略。方法见 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。
   • 命名 explainer_[主题].{html,md}。
6. 验证（HTML 时）：用本地 HTTP 预览，确认图表渲染、目录与节号一致、过渡自然。

本技能只负责内容结构与讲解顺序，不绑定任何特定技能或仓库。若环境中已有网页排版/HTML 生成类技能，可复用其骨架。

结构变更检查单

删节、合并、调序后必做：

• 更新目录（TOC）文案与锚点
• 重排节号与图号，连续无跳号
• 删除指向已删章节的过渡句
• 确认没有重复讲解同一概念
• 确认三幕顺序未被打乱

参考文件

• references/narrative-structure.md — 各小节职责、写法与反模式
• references/life-analogy-patterns.md — 生活类比设计方法（含多领域示例）
• references/diagram-checklist.md — 图表类型与 HTML/Mermaid 通用规范