| name | textbook |
| description | Use when the user wants to write a complete multi-chapter textbook or systematic course material with exercises — e.g. "写教材"、"写一本教材"、"编写课程讲义"、"系统教材"、"textbook". Orchestrates a five-stage UbD-driven pipeline (教学定位 → UbD 预期结果 gate → 章节树 gate → 逐章写作 → 审核定稿) with resumable progress via .progress.json. Not for single tutorials (use tutorial-writer), single chapters (use textbook-chapter), or exercise-only requests (use textbook-exercises). |
textbook
写教材的主 skill（orchestrator）：驱动五阶段流程，管理 .progress.json 状态实现中断可续，在阶段间传递交接契约，最终交付一本有主线、有梯度、可评估的多章节 Markdown 教材。契约、落盘布局、状态机的权威定义见 references/handoff-contract.md（下称"契约文档"）。
何时不触发
- 单篇教程/图文教程（用 tutorial-writer）
- 只写一章或一篇深度文章（用 textbook-chapter）
- 只要例题/习题（用 textbook-exercises）
- 只做大纲不写正文（直接用 textbook-outline）
工作流总览
| 阶段 | 名称 | 执行者 | 产出 | Gate? |
|---|
| 1 | 教学定位确认 | textbook-outline | 学科/读者起点/深度/篇幅 → 00-教材设计.md | 否（一轮提问） |
| 2 | UbD 预期结果设计 | textbook-outline | UbD 五件套 | 是（核心 gate） |
| 3 | 评估与章节设计 | textbook-outline | 章节树+例题计划+梯度报告+表现性任务 | 是（次要 gate） |
| 4 | 章节正文编写 | textbook-chapter（逐章） | NN-章.md × N + 术语表增量 | 否 |
| 5 | 审核定稿 | 本 skill | 自检报告 + 交付摘要 | 否 |
gate 之外的阶段只打印一行进度（格式见契约文档第 5 节），不打断作者。
启动与重入（每次触发的第一件事）
-
确定教材项目目录：用户指定则用之；未指定则询问一次（默认 ./<教材名>/）。
-
找 .progress.json：
- 不存在 → 全新项目：确认教材名 → 建目录 → 初始化
.progress.json（schema 见契约文档第 4 节，current_stage=1，gates 全 false）→ 从阶段 1 开始；
- 存在 → 按契约文档第 4 节重入规则表定位续点，打印续写行：阶段 4 用
▶ 续写：<教材名>，从第 N 章继续，其余阶段用 ▶ 续写：<教材名>，从阶段 N 继续。特别地：current_stage=2/3 且对应 gate 未确认时，从 00-教材设计.md 读出已有产出（阶段 2 为五件套、阶段 3 为章节树/例题习题计划/梯度报告/表现性任务四项）重新呈现并等确认，不推倒重做；作者提出修改时委托 textbook-outline 执行修改与再确认循环。
-
状态纪律：.progress.json 只由本 skill 读写（子 skill 一律不碰）；每完成一个阶段、每完成一章立即更新写盘，绝不批量延迟。
阶段 1–3：委托 textbook-outline
打印 ▶ 阶段 1/5：教学定位确认（阶段 2、3 进入时同格式）。
使用 Skill 工具调用 textbook-outline（传入 {教材项目目录, 教材名}）；若 Skill 工具不可用或未注册，直接读取 ../textbook-outline/SKILL.md 并严格遵循其指令执行。
- 其内部两个 gate 就是本流程的 gate——gate 由该子 skill 面向作者执行，本 skill 绝不越过未确认的 gate 推进状态；
- 阶段 2 确认后：置
gates.stage2_ubd_confirmed=true、current_stage=3，写盘；
- 阶段 3 确认后：置
gates.stage3_outline_confirmed=true、current_stage=4、chapters.total=章节树章数、chapters.next=1，写盘。
阶段 4：逐章循环
打印 ▶ 阶段 4/5：章节正文编写。
对 章号 N 从 chapters.next 到 chapters.total 逐章执行（严格顺序，前章完成才写后章）：
- 提取该章大纲切片：从
00-教材设计.md 的「## 三、章节树与梯度规划（已确认）」取该章的章节树条目 + 例题习题计划；
- 读跨章载体：术语表.md 当前版 + 前一章文件的「## 本章小结」全节（N=1 时前章小结为空）；
- 组装输入契约调用 textbook-chapter：
{章号, 章标题, 该章大纲切片, UbD五件套, 术语表, 前章小结}（五件套从「## 二、UbD 五件套（已确认）」提取 {大概念[], 持久理解[], 核心问题[]}）。调用方式同上：Skill 工具优先，降级读 ../textbook-chapter/SKILL.md；
- 收输出契约
{章文件路径, 新增术语[], Bloom标注回写[]}：新增术语追加进术语表.md；Bloom 标注回写记入 00-教材设计.md 该章例题习题计划条目旁的"实际"标注（与"计划"并排，供阶段 5 对比）；
- 更新状态：
chapters.done 加入 N、chapters.next=N+1，写盘 .progress.json。
全部章完成后置 current_stage=5，写盘。任何一章中途中断，重入时从 chapters.next 无缝继续，已完成章不重写。
阶段 5：审核定稿（自检清单，非 gate，必须全跑）
打印 ▶ 阶段 5/5：审核定稿。逐项检查并输出报告，每项给出：通过/不通过 + 具体位置 + 修改建议。
- 章节对齐走查：逐章读「## 本章小结」的"与持久理解的呼应"，对照
00-教材设计.md 的承载计划——每章至少承载一条持久理解，每条持久理解至少被一章实际承载；
- Bloom 梯度复核（看实际不看计划）：用各章"实际"标注重算层级×章节矩阵，按 ../textbook-outline/references/bloom-levels.md 第 5 节三条规则复核，输出第 6 节格式的报告；
- 术语一致性：对照术语表.md 抽查各章（每章至少查引言与小结两处）用词与符号是否一致，发现不一致列出位置；
- 例题验证残留：全书搜索
⚠️ 需作者确认，汇总成清单呈现——带此标注是合规的（红线允许"明确标注不能验证"），但必须让作者全部看见；
- 循序渐进走查：逐章检查引言是否衔接前章小结、是否使用了后文才定义的概念（前置知识跳跃）。
报告完毕后：不通过项由作者决定修不修；作者要求修 → 定位到章，重新组装该章输入契约调用 textbook-chapter 修订（修订后相关项复查）。全部处理完写盘 stage5_passed：无遗留不通过项（全过或均已修复）置 true；作者决定不修的不通过项仍存在置 false，并在交付摘要中列明遗留项。
交付
输出交付摘要：章数 / 三类题总数 / 已验证题数 / ⚠️ 需作者确认 条数 / 梯度复核结论 / 未修复项清单（如有）。
交付物为教材项目完整目录（布局见契约文档第 3 节）：00-教材设计.md、NN-<章标题>.md × N、术语表.md、.progress.json。
边界说明（须向作者说明）：定稿指文字与结构层面完成；若正文含人工截图标注块，需作者按标注自行补图后才算可发布。
