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 的写作风格。

人物语感不在本技能重复定义——直接复用 kangjian-skill：开始写之前读它的 references/voice-dna.md，让正文「长得像康健写的」，而不是贴风格标签。

核心几条（详见 style-and-gate）：

• 不要定场白。不写「大家好，我是康健」。开篇直接用「痛点 / 反常识结论 / 一个具体场景」切入。署名只在全章结尾用一句话收束，开头不署名。
• 说人话。以第一次接触该主题的学员为基准：陌生术语首次出现时，先用一句普通话说清它在当前任务中是什么、用来做什么，再保留必要的英文名或缩写。抽象概念优先换成具体场景、动作和结果；确实能帮助理解时再用日常类比。
• 关键判断句加粗，但别滥用，一节 1–2 处。
• 不用「铁律」「赋能」「闭环」这类生硬或 AI 腔词；要强调就直接说「这条最重要」「记住一点」。
• 该上表格上表格（对比 / 选型），该上代码上代码（可运行、带必要注释），该上步骤上步骤。
• 图文并茂：在「看图比看文字更快懂」的位置插入视觉元素。代码块直接写进正文；截图 / 流程图 / 录屏 用标准占位标记注明，格式和放置逻辑详见 references/chapter-blueprint.md「视觉元素指南」。
• 真实性优先：第一人称经历、项目故事、报错、耗时、数据、对话、用户反馈和结果只能来自用户素材或可追溯证据。资料不支持时，改写为客观条件句、常见错误或明确标注的假设示例，不得为了“康健味”补造“我踩过”“我亲测”等经历。

第 3.5 步：生成可自动化的视觉元素（SVG）

打开 references/image-protocol.md，扫描本章正文中所有 <!-- [流程图] --> 和 <!-- [对比图] --> 占位，逐一处理：

1. 取出注释里的描述文本，填入 image-protocol.md 第 5 节的提示词模板中的 {描述} 位置。
2. 按模板生成 SVG 代码，用 Write 工具写入 assets/lessons-claudecode/<编号>-<slug>.svg（命名规则见 image-protocol.md 第 3 节）。
3. 用 Bash 工具执行 open <svg路径> 本地预览，确认渲染正常。
4. 按 A 方案在注释下方紧接插入图片引用（保留注释，不删）：

   <!-- [流程图] 描述：... -->
   ![alt 文字](../../../../assets/lessons-claudecode/xxx.svg)

5. [截图] 和 [录屏建议] 原样保留，不处理。

每章通常 1-2 张，不会显著影响写章节节奏。若描述不够清晰导致 SVG 难以准确表达，告知用户并跳过该张（保留占位）。

第 3 步：过质量门禁（强制，不能跳）

写完对照 references/style-and-gate.md 的检查清单逐条自查：去 AI 味、康健味在场、课程有效性（学员真能学会吗 / 有没有可操作的产出）。不通过就改，改到通过再交付。

第 4 步：写文件 + 报告

输出到下面的路径，然后用 1–2 句告诉用户：本章类型、覆盖了哪些知识点、哪些地方因材料不足做了保守处理或需要用户补充。

输出位置与命名

写到课程仓库的章节目录，目录名和文件名都带零填充编号，与 Cursor 课现有结构一致：

<root>/<课程名>/<编号><章节名>/<编号>-<章节名>.md

• <root>：默认 modules/（与现有 Cursor 课同仓）。若用户的课程已建在 lessons/，则跟随 lessons/。不确定就问用户用哪个。
• 编号：两位零填充，如 008。
• 示例：modules/Claude Code 从入门到精通/008Claude Code Agent 模式详解/008-Claude Code Agent 模式详解.md
• 章节配图放同级 assets/ 目录（如材料里有图片引用）。

一章的体量参考

不是越长越好，以「学员读完能学会这一个主题」为准。概念 / 方法论型通常 1500–3000 字；工具操作型按步骤展开，关键是每步可复现；实战项目型以「跟着做能跑通」为准，代码完整、步骤不跳。宁可一章讲透一件事，不要一章塞五件事。

交付前自检

• 核对输出文件路径符合 <root>/<课程名>/<编号><章节名>/<编号>-<章节名>.md，编号为两位零填充
• 对照 references/style-and-gate.md 检查清单逐条完成质量门禁（去 AI 味、康健味在场、课程有效性），不通过先改再交付
• 从新手视角再读一遍：术语首次出现时已解释；没有连续堆叠术语、内部步骤编号和抽象比喻；每个核心概念都能对应到具体场景、动作或结果
• 逐一检查正文中 <!-- [流程图] -->、<!-- [对比图] --> 占位下方已插入 SVG 引用，对应 SVG 文件已写入 assets/lessons-claudecode/ 并用 open 预览确认渲染正常
• 确认 [截图]、[录屏建议] 占位原样保留，未被删除或替换
• 核对章节体量落在类型对应区间（概念 / 方法论型 1500–3000 字），且开篇无「大家好，我是康健」式定场白、署名只在结尾出现
• 执行真实性扫描：第一人称亲历、数字、对话、报错、用户反馈和结果均有证据；无证据内容已改为客观说明或明确标注的假设示例
• 确认已向用户报告本章类型、覆盖的知识点，以及因材料不足做保守处理或需用户补充的部分