| name | draft-chapter |
| description | 生成本周正文：规划（含 Bloom/回顾桥/超级线/角色）→ 场景驱动写正文 → 深度润色 → 四维 QA → 修订回路 → 落盘 QA_REPORT。 |
| argument-hint | <week_id e.g. week_01> |
| allowed-tools | Read, Write, Edit, Grep, Glob |
| disable-model-invocation | true |
/draft-chapter
用法
/draft-chapter week_XX
目标
CHAPTER.md：叙事流畅、有贯穿案例 + BI 系统超级线、循环角色出场、回顾桥达标、读起来像真人教材（不是模板填空）QA_REPORT.md：写入 StudentQA 的四维评分 + 阻塞项/建议项
核心原则
写作质量是第一优先级。 通过验证是必要条件，但不是充分条件。一篇通过了所有检查但读起来像模板的文章，仍然是失败的交付。
步骤（按顺序）
第 0 步：日期校准（立即执行）
生成 shared/current_date.txt，供后续所有 agent 读取当前日期：
date '+%Y-%m-%d' > shared/current_date.txt
这确保时代脉搏、AI 小专栏、参考链接中的日期使用当前年份，不会因模型训练数据截止日期而过时。
第 1 步：规划结构 + 贯穿案例 + 认知负荷 + 超级线 + 角色
调用 subagent syllabus-planner：
- 产出章节结构（小节标题 + 每节学习目标 + Bloom 层次）
- 必须设计本章的贯穿案例：一个渐进式小项目，每节推进一步，章末可运行
- 必须规划 2 个 AI 小专栏的位置和主题（第 1 个在前段，第 2 个在中段；含建议搜索词）
- 必须做认知负荷检查：新概念数在预算内，回顾桥设计达标
- 必须规划 BI 系统超级线推进
- 必须规划循环角色出场位置
- 必须规划章首导入：选择一句与本章主题相关的引言格言，并草拟时代脉搏段落的方向
- 写入
chapters/week_XX/CHAPTER.md
- 所有规划元数据必须用
<!-- ... --> HTML 注释包裹（Bloom 标注、概念预算表、AI 专栏规划、角色出场规划、章节结构骨架等）
第 1.5 步：Context7 技术查证
在写正文之前，使用 Context7 MCP 查证本章涉及的统计/数据分析相关库的最佳实践（pandas、scipy、statsmodels、scikit-learn 等）：
- 从第 1 步的规划中提取本章涉及的库与关键 API
- 调用
resolve-library-id 定位相关库（如 pandas、scikit-learn 等）
- 调用
query-docs 查询具体的最佳实践和 API 用法
- 将查证结果传递给第 2 步的 chapter-writer，确保代码示例符合当前最佳实践（尤其是避免数据泄漏、保证可复现）
搜索工具分工：
- Context7：查证官方文档 API 用法（标准答案）
- Exa Code Context：搜索真实项目代码示例（社区实践）
- 两者互补，确保代码既正确又实用
第 2 步：场景驱动写正文
调用 subagent chapter-writer：
- 必须先读
shared/writing_exemplars.md + shared/characters.yml
- 必须写章首导入：在章标题之后、学习目标之前写入引言格言 + 时代脉搏段落（200-300 字，场景化引入 AI/技术趋势与本章关联）。详见
shared/style_guide.md 的"章首导入"章节
- 必须基于第 1.5 步的 Context7 查证结果确保代码示例使用当前最佳实践
- 以贯穿案例为主线，用"场景 → 困惑 → 解法 → 深化"的叙事弧线写每一节
- 使用循环角色（小北/阿码/老潘）增强代入感，每章至少 2 次出场
- 写回顾桥：在新场景中自然引用前几周概念
- 写 BI 系统进度小节
- 严禁所有节使用相同的子标题模式
- 严禁用 bullet list 堆砌做小结
- 所有写作元数据（每节的 Bloom/叙事入口/建议示例等）必须用
<!-- ... --> 注释包裹
第 2.5 步：联网研究收集（Lead agent 亲自执行）
由你（Lead agent）直接执行，不委派给 subagent。为第 3 步的 prose-polisher 准备搜索数据。
-
从 CHAPTER.md 的 HTML 注释中提取 2 个 AI 小专栏的主题和建议搜索词
-
读取 shared/current_date.txt 获取当前日期
-
使用搜索工具收集数据（每个侧栏 2-3 次搜索）：
优先级 1: WebSearch（内置搜索，最可靠）
WebSearch("GitHub Copilot adoption statistics 2026")
优先级 2: Exa MCP（AI 增强搜索，适合深度研究）
mcp__exa__web_search_exa({
"query": "GitHub Copilot adoption statistics 2026",
"numResults": 5,
"type": "auto"
})
mcp__exa__company_research_exa({
"companyName": "OpenAI",
"numResults": 3
})
优先级 3: perplexity MCP（如可用）
mcp__perplexity__perplexity_search({
"query": "vibe coding trend AI programming 2026",
"recency": "year",
"response_format": "json"
})
- 搜索关键词中必须包含当前年份
- 同时搜索时代脉搏段落需要的素材
-
将所有搜索结果写入 chapters/week_XX/.research_cache.md（含事实、URL、访问日期）
第 3 步：深度润色 + AI 小专栏
调用 subagent prose-polisher：
- 必须先读
shared/writing_exemplars.md + shared/characters.yml
- 执行诊断清单 + 趣味性诊断清单，判断需要哪个级别的改写
- 检查角色一致性（对照
shared/characters.yml）
- 可做结构性重组（不仅仅是换词）
- 必须插入 2 个 AI 时代小专栏：
- 按
syllabus-planner 规划的位置和主题插入
- 优先读取
chapters/week_XX/.research_cache.md 中的预搜索数据和真实 URL
- 如果缓存数据不足，可以补充搜索（WebSearch/Exa MCP），并将新结果追加写入缓存文件
- 绝对禁止编造参考链接：所有 URL 必须来自搜索工具或研究缓存。搜索失败时写
<!-- TODO --> 占位，不得伪造
- 位置硬约束：一个在前段、一个在中段，禁止全堆章末
第 4 步：学生视角四维审读
调用 subagent student-qa：
- 只读审读，输出四维评分 + 问题清单
- 四维评分：叙事流畅度 / 趣味性 / 知识覆盖 / 认知负荷（各 1-5 分）
- 总分 >= 18/20 才能通过
第 5 步：修订回路（简化版：2 档处理，有硬性迭代上限）
修订回路规则：
| 总分范围 | 处理方式 | 回传给谁 |
|---|
| >= 18 | 根据 QA 反馈进行轻量修订后通过 | prose-polisher（轻量修复，处理建议项） |
| < 18 | 结构性重写（需大幅改进） | chapter-writer |
迭代计数规则（防止无限循环）：
- 维护一个变量
revision_round，初始值为 0。
- 每次进入修订回路（回传给 polisher/writer/planner），
revision_round += 1。
revision_round 达到 3 时，强制停止修订回路：
- 不再回传修订，直接进入第 6 步落盘。
- 在 QA_REPORT.md 中标注：
<!-- 修订回路已达上限（3 轮），以下问题需人工介入 -->
- 未解决的阻塞项保留为
- [ ] 但添加注释说明已尝试 3 轮修订。
- 如果第 1 轮修订后总分 >= 18 且无阻塞项，跳过后续轮次，直接进入第 6 步。
第 6 步：落盘 QA_REPORT
把最终的 StudentQA 输出落盘到 chapters/week_XX/QA_REPORT.md：
- 四维评分写在顶部（标注是第几轮评分）
- 阻塞项放到"## 阻塞项"下（checkbox）
- 建议项放到"## 建议项"下（checkbox）
- 如果经过修订回路，记录每轮评分变化（例如
第 1 轮：14/20 → 第 2 轮：17/20）
