金字塔式教程生成
把一个主题变成一篇零基础读者能从直觉读到上手的完整教程。本 SKILL 按自身规则写成，可作为结构示范。
0 三条立意
这三条贯穿全篇，其余规则都由它们推出。规则之间冲突时，回到这里裁决。
- 不让读者掉队。读者不懂，常常不是他不肯学，而是写的人忘了自己是从哪一步走过来的。懂的人看不见不懂的人卡在哪里，这份教程就是替写的人把这一步补上。
- 一次只上一级台阶。每层只比上一层多一级台阶。读者在任意一层停下，都能带走完整的一块理解。
- 规则也说人话。本 SKILL 给自己定的词，先过一遍零基础读者的眼睛。规则用了拗口的词，写出来的正文会跟着拗口。
1 方法论核心
方法论核心是四层金字塔。
- L1 纯生活比喻，建立直觉。
- L2 比喻与术语对照，知晓名词。
- L3 精简技术语言，准确理解。
- L4 实操配置，便于上手。
从 L1 起逐层向上，绝对不允许跳跃。
生成任何一篇教程，起点恒为 L1。读者的熟悉程度只决定各层写多写少，不决定从哪层开始。
2 适用范围
2.1 触发条件
- 显式：用户说「生成教程 / 写教程 / 金字塔教程 / 金字塔式教程 / 分层讲 X / 给小白讲透 X / 零基础讲 X」。
- 隐式：已有内容被反馈「太深了 / 术语太多 / 看不懂」，需按层级重写为分层教程。
- 场景：新人培训文档、概念科普手册、上手指南、入职教材，且要求结构完整、可独立阅读。
不用于碎片式问答、无教学目的的创作、有清晰对话上下文的增量改写。
2.2 独立运行声明
本 SKILL 不依赖任何没有写明、没有交代过、只有对话里才知道的前置文件或上下文，也不依赖任何没有随本 SKILL 分发的本地资源。
3 读者共识
教程与读者达成共识：本教程面向的读者只掌握高中阶段通用基础知识，不默认任何领域背景。
正文不得依赖没有写明、没有交代过的前置内容。用到的前置概念，在首次使用处给一句话定义或回指，不能默认读者已经知道。
4 交付边界
教程正文就是最终交付物。
修订版本说明、修改前后对比、生成过程说明、自检报告等过程产物，只出现在正文之外的对话中，不写入正文。
5 输入与默认值
最小输入是一个主题名。其余项按下表取默认值，不追问。
| 输入项 | 默认值 |
|---|---|
| 受众 | 只具备高中阶段通用基础知识的读者，无专业领域背景 |
| 比喻系统 | 从读者日常生活中选取最普适的一个喻体 |
| 深度 | 四层全开，用户限定时按需截断并声明 |
| 核心概念数 | 3 至 6 个，按依赖关系排序 |
| 版本号 | v1 起，每次修订递增 |
| 撰写者 | 用户指定，未提供时标注 AUTHOR |
| 输出媒介 | 单个 Markdown 文件 |
| 禁用词 | 无 |
三条铁律。
- 不追问。输入缺失按默认值执行，破坏性动作除外。
- 标注假设。文首「本篇约定」写明默认值与涵盖范围，读者可据此要求重生成。
- 不编造。事实无法确认时明示「原文未提供 / 待核实」，严禁编造数据、版本号、路径、结论。
6 生成流程
6.1 读者起点判断
「不追问」只约束正文写作，不禁止动笔前的摸底。正式动笔前，先弄清读者对这三类内容熟到什么程度。
- 名词：主题里的关键术语，他听过没有。
- 原理：这些术语之间怎么运转，他有没有概念。
- 操作：实际做这件事的步骤，他动过手没有。
交互环境里，把这三问做成执行前弹出的选项，让用户逐个选择。非交互环境里，则在下一轮对话中列出题目（单选题或不定项选择题皆可），请用户作答。
判断结果只调整各层详略，不改变起点，也不删层。对应关系如下。
| 读者情况 | 处理方式 |
|---|---|
| 三类都陌生 | 四层按默认篇幅写，L1 不少于 4 句 |
| 只熟名词 | L1 压缩为一句过渡，L2 仍完整给表 |
| 熟名词与原理 | L1、L2 各压一句过渡，重心移到 L3 |
| 三类都熟 | L1 至 L3 各压一句过渡，重心移到 L4 |
压缩后的过渡句仍要交代「它像什么」与「它叫什么」，一个都不能省。读者以为熟、其实没对上的情况并不少见。
6.2 输入解析
读取用户输入，对照默认值表补齐缺失项，起草文首元信息与「本篇约定」。
6.3 金字塔规划
- 选定比喻系统。从日常生活选一个比喻，须与主题核心机制一一对应并覆盖至少 3 个子概念。选定后全篇锁定，禁止第二个比喻系统。
- 列概念清单。拆出 3 至 6 个核心概念，按依赖排序，先被依赖的先讲，同步生成术语黑名单供 L1 自检。
- 查前置概念。逐个核对每个概念的讲解会用到哪些术语，这些术语所属的概念是否都已排在它前面并已讲完。有不满足的，调整概念顺序，不靠补定义。
- 填四层内容单。每个概念在四层各讲什么，各用一句话写死。逐层规则见 references/pyramid-rules.md。
- 定章节骨架。每个概念一章，章内按 L1 到 L4 分节，文末加术语速查表与常见困惑。
6.4 先讲前置概念
阐述任一概念时，只能引用它成立时依赖的前置概念。该前置概念必须是顺序在前、且已完整讲完的术语。禁止引用当前概念向后引申出的后置高级术语，也不许用「先给一句话定义、后文再细讲」的方式提前使用后面的术语。核查到前置概念不足时，先讲清楚前置概念，不靠补定义。
这条只在概念与概念之间生效。概念内部 L2 给名字、L3 讲机制，本身就是金字塔的安排，不受此限。
口诀：先讲该有的，再讲要讲的。
这条是写作前提，不是交付检查项。顺序错了，自检也补不回来，只能重排，因此在 6.3 的规划阶段就核对完毕。
6.5 阅读负担
信息密度不是越密越好，也不是越松越好，要看读者处在哪一层。各层的上限如下。
| 指标 | L1 | L2 | L3 | L4 |
|---|---|---|---|---|
| 单句字数上限 | 40 | 45 | 60 | 60 |
| 单句分句数上限（逗号、顿号） | 2 | 2 | 3 | 3 |
| 单句并列项数上限 | 3 | 3 | 3 | 3 |
| 段落新增术语数上限 | 0 | 3 | 5 | 5 |
连续排比、连续等长句，各层都不用。「分句」与「并列项」指一句话里用逗号、顿号分开的小段。
L1 的新增术语数必须是 0。读者在这一层还不认识任何术语，一个都不该见到。
这四项由 scripts/selfcheck.sh 检查，属交付检查项。数值是当前基线，跑过的实际产出若显示某层临界值不合适，回头改这张表。
6.6 逐层撰写
按概念顺序、概念内按 L1 到 L4 顺序撰写，绝不跳层。
- L1 只建立直觉，回答「像什么、解决什么麻烦」。只允许日常生活词，英文术语一律写成「中文词（英文——一句解释）」，一个比喻系统贯穿，一个概念 3 至 6 句。
- L2 用三栏表给正式名字，三列分别为生活说法、正式说法、一句话定义，每行一个术语并与比喻一一对应。
- L3 去比喻留结构，一段一概念，因果链完整。每个概念覆盖至少 5 个要素，要素如下。
- 是什么、为什么需要、解决什么、怎么运作、何时不用。
- L4 逐字直给命令与配置，复制即用，步骤编号无歧义。本地命令前给前置准备块，每步写「看到什么算对」。
写作纪律三条硬规则，全文适用。
- 自然引导。术语不凭空出现，生活场景先出现，正式名字后给出，新概念进入前先给一句「为什么需要它」。
- 语言简洁。每句话只表达一个陈述或事实，多重从句与三点以上并列一律拆成短句。
- 富文本辅助。按学习者需要引入代码块、截图、流程图。辅助内容与正文互相配合，服务于理解，可省则省。
每章收尾写章末自检。用 3 至 5 个反问或设问，每问附一句提示或回指章节，不直接给全答案。
6.7 结构与排版
每个概念单元由四段构成，顺序固定。
- 原文段，有阅读门槛的原文才设。公式、代码、正式定义、规范引文属这一类，没有就不设。原文与它的解释不得被其他内容隔开。
- 精读段，用词专业精简的技术解释，措辞准确。
- 浅读段，生活化通俗化的解释，跟在精读段之后，把技术内容落回读者语言。
- 收尾段，段末一句小结或承接；章末写总结、价值说明、实操配置、章末自检与承接。
段名不写进正文，靠排版样式与衔接句区分。四段说的是材料的先后顺序，章节的 L1 到 L4 阶梯不变。原文段落位与术语编号细则见 references/pyramid-rules.md。
原文段不受引用顺序限制。原文里出现读者还不认识的词是常事，不必在这里卡住。设原文段时，紧随其后加一句引导，如：「先别急着读懂这段原文。里面几个陌生的词，是后文要逐个讲清楚的；等它们到齐，再回来看，这段自然就通了。」按语感调整措辞，不写成大白话，也不写成书面腔。
- 标题用数字标明层级，最多三级。标题只做结构路标，不罗列主题与对象，不传达重复信息。
- 符号从简。冒号提示的内容达到一句以上时，后续内容另起一行。
- 自然段落行文，不写写作过程的话，不写 AI 腔。
- 文首元信息依次呈现教程名称、版本号、撰写者、总字数、预计阅读时间、主题简述。阅读时间按总字数除以每分钟 400 字向上取整，总字数定稿后统计回填。
- 术语速查表四列汇总，编号、术语、通俗解释、技术解释。信息缺失处明示「原文未提供」。
6.8 自检与交付
执行两步校验，全过才交付。第一步运行 scripts/selfcheck.sh 产出文件.md，机械计数项全部 PASS；第二步按 references/selfcheck.md 的人工项逐条核对，覆盖小白复读、不引入新词解释旧词、比喻一致、要素完整、因果链、自然引导、先讲前置概念与用词通俗。把脚本计数与人工核对结果作为达标证据汇报。任一项不过就改到通过为止，未通过前不交付。
7 润色规范
定稿前对全文做一遍去 AI 感润色，覆盖字词与标点。
7.1 字词选择
- 删空泛套话：总的来说、不难发现、值得注意的是、综上所述、某种意义上。
- 不用模板句式：不仅仅是……更是……、让我们一起、在这个……的时代。
- 机械枚举词「首先 / 其次 / 最后」只在其确有顺序语义时保留。
- 保留通顺的双音节词。简洁不是把双音节词压成拗口的单音节词，「可作为」不写成「可作」，「建立直觉」不写成「建直觉」。
- 用具体名词与动词，少抽象名词串联，事实与数字优先于形容词。
- 长短句交错，像有经验的人在分享做法。连续排比或连续等长句即打散。
7.2 术语通俗化
写给自己看的规则与写给读者看的正文，用的是同一把尺子。本 SKILL 里的词须先过这一关，正文里的词同理。
- 不自造压缩词。两个词能说清的事，不压成一个词。不用「粒度」「作用域」这类词，直接说「选取范围」「只在概念之间」。
- 不借专业词。用物理学、数学、行业里的现成词来解释别的东西，本身就是一层门槛，等于让读者先学新词再学旧词。
- 不生造比喻式命名。名词锚、心智模型这类叫法，读者要多想一步才知道在说什么，能用「术语编号」「读者心里的理解」替代就替代。
- 检验法：把词单独拎出来给一个高中生看，他要多想一步才明白，就换掉。
7.3 标点符号
- 破折号仅用于「中文词（英文——解释）」格式。
- 不用冒号做强调。冒号提示长内容时另起一行。
- 不用省略号与波浪号营造语气，感叹号不使用。
- 分号仅用于紧密并列句，默认用句号切短句。
8 规则速查表
| 规则 | 架构落点 | 自检方式 |
|---|---|---|
| 内容自包含 | 第 3 节与 6.3 节 | 前置概念均可回指 |
| 纯交付物 | 第 4 节 | 修订说明类词句为 0 |
| 起点恒为 L1 | 第 1 节与 6.1 节 | 判断只调详略，层序不变 |
| 先讲前置概念 | 6.3 与 6.4 节 | 规划阶段核对，无后置术语引用 |
| 阅读负担 | 6.5 节 | 脚本查分句、并列项、字数与术语数 |
| 自然引导 | 6.6 节硬规则 | 术语首现前有场景铺垫 |
| 章末检验 | 6.6 节章末自检 | 自检数等于概念章数 |
| 语言简洁 | 6.6 节硬规则 | 复杂句式抽查 |
| 富文本结构 | 6.6 节硬规则 | 辅助内容均服务理解 |
| 四段顺序 | 6.7 节 | 精读段先于浅读段，原文与解释相邻 |
| 术语编号 | 6.7 节 | 术语首现带编号，速查表编号齐全 |
| 原文段引导 | 6.7 节 | 原文段后有一句解释性引导 |
| 用词通俗 | 7.2 节 | 无生造的压缩词，也不借用其他领域的专业词 |
| 符号规范 | 6.7 节 | 冒号换行合规 |
| 标题规范 | 6.7 节 | 编号连续且不超过三级 |
| 开头格式 | 6.7 节元信息 | 六要素按序齐全 |
| 去 AI 感润色 | 第 7 节 | 套话与违规标点为 0，单音节化抽查通过 |
9 输出格式
单一 Markdown，结构固定。层标题措辞可微调，四层顺序与编号规则不得改变。
# 教程名称
（元信息：版本号 / 撰写者 / 总字数 / 预计阅读时间 / 主题简述）
（本篇约定：受众 / 比喻系统 / 涵盖范围 / 默认假设）
## 1 概念名
（原文：有门槛的原文，如有。引用块或代码块，术语首现处标编号）
### 1.1 生活场景
### 1.2 正式名字
### 1.3 准确地说
### 1.4 动手试试
**章末自检**
**本章名词**：1 术语、2 术语
## 2 概念二
## N 术语速查表
（四列：编号 / 术语 / 通俗解释 / 技术解释）
## N+1 常见困惑
10 参考文件
以下文件随本 SKILL 一同分发，属其组成部分，不构成外部依赖。
- references/pyramid-rules.md，四层填充规则、铁律、正反例与章末自检写法。
- references/blocks.md，各区块模板。
- references/selfcheck.md，自检清单与人工项判读标准。
- examples/rag-tutorial.md，单概念完整教程示例。
- scripts/selfcheck.sh，机械计数项自检脚本。
