| name | swcc-plan |
| description | Use when the user wants to start preparing or reviewing a technical topic, or to update / expand an existing topic. 触发例:「复习 X」「准备面试 X」「给我搭个 X 知识树」「plan X」「更新 X 的知识树」「把这个专题补全点」。 |
| argument-hint | [topic] [level] [--update|--regenerate] |
| user-invocable | true |
swcc · plan — 生成 / 更新专题 roadmap 与教学教案
为一个技术专题搭建（或增量更新）roadmap 级知识树与递进式教学教案。质量标杆是「阶段 → 子主题（带核心问题 + 本章考察点）→ 可考核的叶子节点」的骨架，加上每个叶子节点「背景 → 本质问题 → 核心机制 → 进阶」的教案密度。
动手前先读三份契约:
${CLAUDE_PLUGIN_ROOT}/skills/_shared/data-contract.md —— 目录布局、节点路径 key、各文件格式、参考资料读取策略、合并/更新语义、旧格式兼容与迁移规则。${CLAUDE_PLUGIN_ROOT}/skills/_shared/review-rubric.md —— 强制评审的 4 个维度、各 level 深度校准、缺口格式。
所有数据写到 $HOME/.study-with-cc/。
参数:$ARGUMENTS —— 第一个词是 topic（必填），可选 level（p6/p7/p8/p9，默认 p7），可选 --update / --regenerate。
核心原则（贯穿全程，在门控处会复述）
- 先自己想透，再看书。 永远先用自身领域知识构建完整大纲，再用参考资料锚定/补充。绝不因为挂了书就把范围缩到书的目录——书是锚点，不是天花板。
- 深度优先于条目数。 每个叶子节点都要能回答「是什么 + 为什么这样设计 + 取舍/边界」，不是列名词。宁可少而透，不要多而空。
- 质量由流程保证，不靠用户判断。 生成后必须派评审子智能体查漏补缺并据反馈补全——这是强制环节，不问用户「够不够」。
- 结构可演进，进度不可丢。 更新已存在专题时，默认增量合并，用户已学的进度一律保留。
- 不编来源。 没挂资料就老实靠自身理解，不要假称「依据某书」。
- 大文件分块写,永不一次性整文件输出。 knowledge-system.md 等大产物按 data-contract 第十二节分块追加 + TodoWrite 跟踪,否则会超时。
- roadmap 与教案分离。
knowledge-tree.md 是 roadmap（骨架 + 每章核心问题/考察点），knowledge-system.md 是递进式教案（背景/本质问题/核心机制/进阶）。
subagent 纪律（起草子智能体与评审子智能体共用）
plan 执行过程中会派两类子智能体：阶段 7 的起草子智能体（逐子主题生成教案文本）和阶段 8 的4 维评审子智能体。二者必须遵守以下纪律，主对话 also 默认不在 plan 执行中调用 WebSearch/WebFetch。
- 工具权限 —— 禁止联网。 subagent 严禁调用 WebSearch、WebFetch 以及任何其他联网工具；只能使用 Read 读取输入上下文中已提供的文件、Bash 进行纯本地处理、Agent 返回结果。主对话在
plan 执行期间也默认不调用 WebSearch/WebFetch。
- 输入来源 —— 只读既定材料。 subagent 只能基于以下素材工作：现有 teaching plans / knowledge tree / knowledge-system.md、本轮对话历史、模型内部领域知识、用户在阶段 3 提供的参考资料路径。禁止主动检索外部网页、文档、博客、论文或在线课程。
- 输出契约。
- 起草子智能体：只返回其被分配子主题下的 markdown 教案文本（背景/本质问题/核心机制/进阶四段），不返回 frontmatter、不写文件、不输出额外说明。
- 评审子智能体：严格按
review-rubric.md 第四节 gaps[] JSON 结构返回缺口；除 JSON 外不要解释性文字。
- 失败回退。
- 起草子智能体失败/超时 → 由阶段 7 现有规则处理（不阻塞其他子主题，登记进 TodoWrite 后由主体补写）。
- 评审子智能体失败/超时 → 由阶段 8 现有规则处理（等待其余维度；若全部失败，本轮按空 gaps 处理并继续，摘要提示「评审暂不可用」）。
执行流程
| 阶段 | 名称 | 目的 |
|---|
| 1 | 解析参数 | 取 topic / level / 模式标记 |
| 2 | 存在性检查 & 路由 | 新建 or 更新（增量合并 / 重建） |
| 3 | 询问参考资料 | 收集 PDF/文档/目录的绝对路径 |
| 4 | 独立构建专家大纲 | 先不看书，凭领域知识列全大纲 |
| 5 | 挂载资料并锚定补充 | 用书映射/补充/纠错，标注来源 |
| 6 | 生成 roadmap（knowledge-tree.md） | 含 ## 子主题下的核心问题 + 本章考察点 + 嵌套 checkbox |
| 7 | 生成教学教案（knowledge-system.md） | 每个叶子节点按 背景/本质问题/核心机制/进阶 四段组织 |
| 8 | 强制 subagent 4 维评审 + 补全 | 并行评审 → 合并缺口 → 补全 → 循环 |
| 9 | 写 5 文件 + 自检 | 落盘并 ls 验证缺一不可 |
| 10 | 输出摘要 | 含评审补了哪些缺口 |
阶段 1：解析参数
- 从
$ARGUMENTS 取 topic（没给则问用户「要复习/准备哪个专题？」）、level（默认 p7）、模式标记。
- 由 topic 生成小写 kebab-case
slug（转小写、空格转连字符；如「Foo Bar」→ foo-bar）。
阶段 2：存在性检查 & 路由
看 $HOME/.study-with-cc/topics/<slug>/ 是否存在:
| 情况 | 路由 |
|---|
| 不存在 | 新建模式:走阶段 3→10 全流程。 |
已存在，且无 --regenerate | 增量合并模式（默认）:仍走阶段 4–8 重新深想+评审，但落盘时按 data-contract 第十一节只增不毁——新增缺失节点、加深已有节点内容、补全 roadmap 核心问题/考察点、迁移旧 system 格式，progress 进度全保留，frontmatter version 递增。先读出现有 tree/system/progress 作为基线。 |
已存在，且有 --regenerate | 重建模式:全量重写 tree/system，但按节点路径 key 迁移旧 progress，匹配不上的旧节点在摘要里列出。仅在用户明确要求时用。 |
提醒（原则 4）:合并/重建都以「用户已学的进度不丢」为底线。
阶段 3：询问参考资料
问用户:是否有 PDF 书籍、文档、或资料目录作为本专题依据？（举例:/Users/you/books/<教材文件>.pdf）
- 有 → 收集每份的绝对路径、类型、标题，准备写入
references.json。
- 无 →
references 写 {"references": []}，纯靠自身理解（阶段 5 跳过书锚定）。
- 更新模式下:沿用已有
references.json，并问是否新增。
阶段 4：独立构建专家大纲（先不看书）
这是深度的源头，先做这步、且不要被书牵着走。
凭你自身领域知识，把专题分解为:阶段（## 分组）→ 子主题 → 知识点（叶子节点）。
- 按
level（见 review-rubric 第三节深度校准）确定粒度与深度:p7 要覆盖高频面试考点 + 实战调优，密度满足 review-rubric「深度标准」。
- 叶子节点是「可单独考核的知识点」，不是大而空的名词（见 data-contract 第三节节点粒度）。
- 为每个
## 子主题准备：核心问题（一句驱动性问题）和 本章考察点（业务研发视角下的实践/场景/选型点，3-7 条）。
- 此刻先在心里/草稿列出完整骨架，不要因为「书里没有」就删点。
提醒（原则 1）:即使挂了书，这一步也先于读书。书用来补，不用来框。
阶段 5：挂载资料并锚定补充
仅当阶段 3 挂了资料:按 data-contract 第八节读取（PDF 用 Read 分页读目录/前 10 页提取章节结构；目录列结构挑相关文件；docx 走 best-effort 转换）。然后:
- 把书的章节映射到阶段 4 的大纲上，给相关节点标 inline 来源（如「据《XX》第 N 章」）。
- 用书补充细节、纠正错误、补上你漏掉的点。
- 大纲里书没覆盖、但该 level 该掌握的点，标「网络补充」。
门控:离开本阶段前确认——大纲是否仍超出书的目录范围（应当超出）？若发现自己被书缩窄了，回阶段 4 补回来。
阶段 6：生成 roadmap（knowledge-tree.md）
按 data-contract 第三节格式生成：
- frontmatter：
topic/slug/version/level/kind/createdAt（更新时 version 递增）。
- 每个
## 子主题下先写 核心问题 和 本章考察点，再写该子主题的叶子节点 checkbox。
- checkbox 状态：新建全
- [ ]；更新模式按合并语义只增不毁，保留已有勾选/🔴。
阶段 7：生成教学教案（knowledge-system.md，分块写，禁止一次性整文件输出）
⚠️ 一次性输出几十个 roadmap 级节点会超时失败。严格按 data-contract 第十二节「大文件分块写入策略」:
- 先用 Write 建文件:表头
# <topic> 教学教案 + 末尾哨兵 <!-- @end -->。
- 用 TodoWrite 为
knowledge-tree.md 中每个 ## 子主题建一个 todo（「生成+落盘 <子主题>」），作为本阶段进度看板。
- 按 knowledge-tree.md 中
## 子主题的出现顺序，每次取最多 7 个未完成子主题组成一批，用 Agent 工具并行派起草子智能体（每个只起草一个子主题、只返回该子主题的 markdown 文本、不写文件）。
- 等待整批全部返回或超时后，主体按 tree 顺序（不是按返回先后）用 Edit 替换哨兵把本批每个子主题逐块追加到
knowledge-system.md；每个子主题的内容严格按 data-contract 第四节格式（背景 / 本质问题 / 核心机制 / 进阶；核心机制每条带结论与原理/取舍/边界、不许只写名词）。一个子主题一次 Edit。
- 本批全部追加后，用 TodoUpdate 勾掉成功落盘的子主题；失败/超时的子主题保持未勾选，并在 todo 里加注失败原因（如「超时」「返回为空」「格式不符」），不阻塞其余批次。
- 重复步骤 3–5 直到所有子主题处理完毕；最后由主体自行补写或重新派发仍失败的子主题，确认
knowledge-system.md 完整后，再进入阶段 8。
门控:每块落盘后再写下一块；每批返回后再发下一批。中途超时也能凭 TodoWrite + 已落盘内容续写，不必从头再来。
阶段 8：强制 subagent 4 维评审 + 补全（不问用户）
这是质量闸门，必做。 用 Agent 工具并行派发评审子智能体（一条消息里多个 Agent 调用并发），按 review-rubric 第二节，每维度一个:
- 覆盖度（始终）、深度（始终）、递进性（始终）、书本忠实度（挂了书才派）。
把当前的知识树大纲 + knowledge-system 内容 + topic + level（+ 挂载资料清单）作为上下文交给每个子智能体，要求其只读、严禁 WebSearch/WebFetch 等任何联网工具、按 review-rubric 第四节的 gaps[] JSON 结构返回缺口。
拿到结果后（原则 3）:
- 合并四维
gaps[]，按 node+suggestion 去重。
- 任一维度返回非空 gaps 均触发 system 教案重写（新增/加深节点内容、补背景/本质问题等；补 system 同样用分块 Edit 追加，见 data-contract 第十二节）。优先
high、再 medium。
- 循环复审(loop-until-dry,定义如下，不许凭感觉收尾):
- 一轮 = 覆盖度 / 深度 / 递进性（挂书再加书本忠实度）四维评审子智能体并行各跑一次。
- dry（终止） = 本轮 coverage、depth、progression 三维均返回空 gaps（book-fidelity 的
low 缺口不计入终止判定，可在篇幅允许时顺带补）。
- 每轮补完缺口后再派下一轮;硬上限 3 轮（含可能采用的更严格视角复审轮），到顶即停。
- 到达上限仍有未补的 high/medium → 不强撑，在摘要里列出这些缺口，提示用户「可稍后
/swcc-plan <topic> --update 补全」。
- 若某评审子智能体调用失败/超时，或其返回内容中出现
http(s):// URL、引用了输入上下文未提供的网页/文档/博客，或出现「according to web/article/online / 据网络/文章/在线资料」等外部检索措辞，则主对话应丢弃该结果并按失败处理：先等待其余维度返回；若全部失败则本轮按空 gaps 处理并继续（不阻塞用户），在摘要中提示「评审暂不可用，本次未做质量补全」。
- 记下「评审补了哪些缺口」用于摘要。
若四个维度的子智能体都返回空缺口,先对照 review-rubric「深度标准」逐节点核对是否真的已达标;若仍不确定,可在 3 轮硬上限内换一个更严格的视角（例如「一个挑剔的资深面试官会追问什么」）再评审一轮,该轮计入硬上限。
阶段 9：写文件 —— 必须生成 5 样，缺一不可
⚠️ 必须生成下列全部 5 个文件，缺一不可。config.json 位于全局根目录（不在 topic 目录内）、references.json 即使没有资料也要建为空——这两处位置/条件特殊，最先创建。一律 mkdir -p 确保目录存在；建 topic 目录时一并 mkdir -p 出 review-sessions/ mock-sessions/ reports/ deep-notes/ 四个空子目录，供后续 go/stop/mock/compound/deep 直接写入（避免首次 stop/mock 因目录缺失出错）。更新模式下按 data-contract 第十一节合并语义写入，不得覆盖已有进度。
| # | 文件 | 位置 | 要点 |
|---|
| 1 | config.json | $HOME/.study-with-cc/（全局根） | 已存在:读出 → 追加/确认本 topic 在 topics[] → activeTopic 设为本 slug → 写回（别覆盖别的 topic）。不存在:按 data-contract 第九节新建。 |
| 2 | references.json | topic 目录 | 阶段 3 的资料清单;无资料写 {"references": []}。即使为空也必须创建。 |
| 3 | knowledge-tree.md | topic 目录 | frontmatter（topic/slug/version/level/kind/createdAt；kind 按 data-contract 第三节判定）+ 每 ## 子主题的核心问题/考察点 + 嵌套 checkbox。新建全 - [ ];更新模式按合并语义只增不毁、version 递增。 |
| 4 | knowledge-system.md | topic 目录 | 每个叶子节点四段：背景/本质问题/核心机制/进阶。 |
| 5 | progress.json | topic 目录 | 新建:每个叶子节点一条 not_started/mastery:0，currentNode=第一个叶子，weakPoints 空，stats 全 0。更新:按合并语义只补新节点、保留旧进度。节点 key 必须与 tree 层级完全一致。 |
阶段 9.5：完成前自检（必做）
ls -1 "$HOME/.study-with-cc/config.json" \
"$HOME/.study-with-cc/topics/<slug>/references.json" \
"$HOME/.study-with-cc/topics/<slug>/knowledge-tree.md" \
"$HOME/.study-with-cc/topics/<slug>/knowledge-system.md" \
"$HOME/.study-with-cc/topics/<slug>/progress.json"
再确认 config.json 的 activeTopic 指向本 slug、topics[] 含本条目。任一缺失/不符立即补写。
阶段 10：输出摘要
✅ 知识树已<生成 / 更新>：<topic>（level: <level>）
📊 节点数：<叶子总数>（其中本次新增 <k>） 子主题：<N>
🔍 评审补全：<高优 a 个 / 中优 b 个缺口>（无则「评审通过，无缺口」）
📚 已挂载参考资料：<M> 份
📄 详细教案：knowledge-system.md
📁 位置：~/.study-with-cc/topics/<slug>/
下一步：用 /swcc-go 开始系统学习或复习。
质量基准（达到才算完成）
- 每个
## 子主题在 knowledge-tree.md 里都有「核心问题 + 本章考察点」。
- 每个叶子节点在 knowledge-system.md 里都有「背景 + 本质问题 + 核心机制 + 进阶」，满足 review-rubric「深度标准」那五条。
- 知识树的范围不止于挂载资料的目录（除非该专题确实就这么大）。
- 评审子智能体确实跑过 4 维，且 high/medium 缺口已补或已说明为何不补。
- 5 个文件齐全，更新模式下旧进度零丢失。
