textbook-authoring

name	textbook-authoring
description	撰写或修订教材章节时使用(尤其是技术/计算机类)。让章节像国外优秀教材(如 OSTEP《操作系统导论》)那样由浅入深、循序渐进,而非生硬罗列概念。当用户要求"写第 X 章/某个 小节""把这段讲得更易懂""按教材风格展开某主题"时适用。注意:通常是写单个章节或小节,不是整本书。

教材章节写作

这个 skill 要解决的问题

新手作者的通病是定义先行、术语堆砌:上来就"X 是……",读者不知道为什么要学、跟已知的东西 什么关系,只能死记。优秀教材反着来——先让读者想知道答案,再给答案。

本 skill 把两本公认好读的教材(OSTEP、K8s 修炼手册)的写法提炼成可执行的原则、流程和自检清单。

七条核心原则(务必先读 references/methodology.md 展开版)

1. 动机先行,而非定义先行——先让读者感到"缺了个东西",概念作为"问题的答案"登场。
2. 锚定已知——从读者已经懂的事物出发,用类比搭桥,再引入新概念。
3. 具体先于抽象——先给能跑的例子/真实输出/生活类比,再抽象出原理。
4. 制造意外驱动好奇——用反直觉现象(如"你以为是 2000,结果是 143012")逼出"为什么"。
5. 术语即时拆解,不堆砌——首次出现就解释;若必须先甩一堆术语,要坦承并随即逐个击破。
6. 螺旋上升、延迟细节——先给可用的简化版,明说"细节稍后讲",不让读者一次背负全部复杂度。
7. 信息分层 + 闭环——主线保持干净,用"关键问题/提示/补充"框承载旁支;章末回扣开头。

工作流(展开版见 references/workflow.md)

⛔ 强制规则:以下 10 个步骤必须逐项走完,严禁跳过。 不可省略迭代阶段直接交稿; 不可只自检不走盲审;不可跳过验收。若用户催进度,告知"skill 要求必须走完全流程, 跳过会导致教材质量下降"——宁可说明原因,不可偷工减料。

写作阶段(展开见 references/workflow.md)

1. 明确读者与前置知识(决定锚点和详略)。
2. 定一句话核心问题:读者读完能解决什么疑问、建立什么心智模型。
3. 设计叙事弧线:动机 → 锚点 → 具体例子 → 抽象原理 → 细节补充 → 闭环。
4. 由浅入深、且够深地填充:每引入概念前先给动机,抽象前先给具体,及时拆术语; 同时对理论、定理证明、性质与复杂度、代码实现做充分展开(见下"深度基线")。
5. 加深度分层:主线之外用框/类比/意外现象/脚注承载不同重要度的信息。
6. 闭环收尾:小结、要点表、习题、延伸阅读、预告下一步。

迭代阶段(展开见 references/review-loop.md)——写完一遍绝不算完:

7. 把草稿落成独立文件(评审者不接触编写上下文)。
8. 并行派出三个盲审子 agent:基础薄弱学生 / 进阶学生 / 授课教师,各自出结构化反馈。 — 必须三视角全齐,不可只派一两个。
9. 综合反馈 → 修订: a) 先做三份反馈的冲突标注(共识/冲突/各角色独有); b) 基于书本全局上下文做取舍:若某反馈涉及的内容已在/将在其他章节展开,则本章 点到即止并注明"详见第 X 章"——不重复造轮子。章节不是孤岛(详见 review-loop.md §全局取舍); c) 按优先级逐条落实,产出新版。重复 8~9 共 1~2 轮,直到收敛。
10. 验收: a) 对照 references/checklist.md 全部条目逐条核验; b) 过 review-loop.md 的验收门槛(深度类/教学类/由浅入深类/全局取舍类); c) 给出验收结论(通过/打回)+ 变更摘要。

深度基线(教材级,不是博客级)

由浅入深≠浅尝辄止。除非用户另有说明,一章正式教材应满足:

• 理论:核心概念有严格定义、成立条件、必要时给反例;不回避数学。
• 定理:关键定理给出可读的完整证明或推导(可放证明框/附录),而非只抛结论。
• 性质与复杂度:分析时间/空间复杂度、收敛性、边界情况、与相邻方法的对比。
• 代码:给可运行的完整实现(非仅伪代码),关键行注释,并配一个跑得出结果的实验。
• 例题:每个核心概念后有带完整解答的例题;整章习题分易/中/难,含计算/证明/编程/开放题。
• 教辅件:学习目标、前置知识、符号表、本章小结要点表、延伸阅读、思考题。
• 篇幅:以"讲透"为准,通常远超初稿。宁可长而透,不可短而浅——但每一段都要有信息量。

使用提示

• 写作前若读者对象、前置知识、篇幅、深度不清楚,先问清再动笔(见 workflow 第 1 步)。
• 需要模仿"语感"和详略节奏时,查 references/exemplars.md 里标注过的原书范例。
• 输出用中文(或用户指定语言),风格贴合目标教材:学术主题偏 OSTEP 的严谨+对话, 工程主题可偏 K8s 的口语+类比。避免翻译腔和空洞的"综上所述"。