course-generator

course-generator：单章节课程正文生成

把一份章节大纲和一堆参考材料，写成一篇学员读完就能上手、读起来像康健本人在讲的课程正文。一次只写一章，写深写透，不批量铺框架。

适用边界（先确认是不是该用我）

• ✅ 用我：已有章节标题 + 小节大纲 + 参考材料，要写这一章的完整正文。
• ❌ 不用我：还没想好写什么章节 → ai-programming-topic-planner；手上是一段实战操作记录要整理成案例 → coding-session-to-tutorial；想一次生成整门课所有章节 → 拆成多次调用我，一章一章来。

输入（缺什么就先问，别瞎补）

按这四项收集，前两项必需，后两项强烈建议：

1. 课程名称（必需）— 如「Claude Code 从入门到精通」。决定输出目录。
2. 章节编号 + 标题（必需）— 如「第08讲：Claude Code 的 Agent 模式详解」。
3. 小节大纲（建议）— 列表形式。没有就根据参考材料和章节标题，先产出一版小节结构给用户确认，再动笔。
4. 参考材料（可选）— 用户主动提供的材料优先使用，两种形态：
   • 本地文件：直接 Read 读取（.md / .txt / 代码文件等）。
   • 网页链接：用 WebFetch 抓取正文。抓不到就告诉用户，不要编造内容。

输入不全时的动作：只缺大纲 → 先生成小节结构请用户确认；缺参考材料 → 不要直接开写，先执行「第 0 步：主动搜料」，用搜到的材料支撑内容质量。

工作流程

第 0 步：主动搜料（必须执行，不能跳）

无论用户是否提供了参考材料，都要执行此步——用户给的材料是起点，不是终点。搜料的目标：让这章的内容有充分的事实依据、可复现的示例、准确的技术细节。

详细搜索策略见 references/material-hunt.md，执行摘要如下：

1. 搜本地仓库（优先，速度快）

从章节标题提取 2–4 个核心关键词（英文 + 中文），在以下路径搜索：

# 在当前课程仓库搜
grep -r "<关键词>" . --include="*.md" -l

# 在 kj-skills 仓库搜（技能文档、已有教程）
grep -r "<关键词>" /Users/chengkangjian/work/kj-skills --include="*.md" -l

# 在 kj-llm-wiki 搜（知识沉淀）
grep -r "<关键词>" "/Users/chengkangjian/Library/Mobile Documents/iCloud~md~obsidian/Documents/kj-llm-wiki" --include="*.md" -l 2>/dev/null

命中的文件用 Read 读取相关段落，提取可用知识点。

2. 搜网络（补充官方一手资料和最新内容）

用 WebSearch 执行 2–4 轮搜索，查询策略见 material-hunt.md。搜到高质量 URL 后用 WebFetch 抓取正文。

3. 汇总材料清单

搜完后，在脑中（或草稿）列出：

• 已读材料 N 篇、覆盖哪些知识点
• 哪些知识点仍然空白（技术细节不足 / 无可复现示例）

如果空白太多（超过章节主干的 30%），告知用户并请求补充，而不是硬写靠猜。

第 1 步：吃透材料，定结构

1. 读全部参考材料（本地 Read + 网页 WebFetch），提取这一章真正要讲清楚的知识点清单。
2. 判断章节类型（决定用哪套结构骨架，详见 references/chapter-blueprint.md）：
   • 概念讲解型（讲清一个原理 / 模式，如「Agent 模式详解」）
   • 工具操作型（教会一个配置 / 功能，如「MCP 配置」）
   • 实战项目型（带做一个完整产物，如「实战一：核心功能实现」）
   • 方法论型（讲思维 / 工作流，如「写出高质量 Prompt」）
3. 把知识点对应到小节大纲。大纲缺失或不合理时，按 blueprint 的最佳实践重排，改动要告诉用户原因。

第 2 步：写正文

打开 references/chapter-blueprint.md 对应章节类型的骨架，逐节落笔。同时严格遵守 references/style-and-gate.md 的写作风格。