Plan

---
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`。

---

## 核心原则（贯穿全程，在门控处会复述）

1. **先自己想透，再看书。** 永远**先用自身领域知识构建完整大纲**，再用参考资料锚定/补充。**绝不**因为挂了书就把范围缩到书的目录——书是锚点，不是天花板。
2. **深度优先于条目数。** 每个叶子节点都要能回答「是什么 + 为什么这样设计 + 取舍/边界」，不是列名词。宁可少而透，不要多而空。
3. **质量由流程保证，不靠用户判断。** 生成后**必须**派评审子智能体查漏补缺并据反馈补全——这是强制环节，不问用户「够不够」。
4. **结构可演进，进度不可丢。** 更新已存在专题时，默认增量合并，用户已学的进度一律保留。
5. **不编来源。** 没挂资料就老实靠自身理解，不要假称「依据某书」。
6. **大文件分块写,永不一次性整文件输出。** knowledge-system.md 等大产物按 data-contract 第十二节分块追加 + TodoWrite 跟踪,否则会超时。
7. **roadmap 与教案分离。** `knowledge-tree.md` 是 roadmap（骨架 + 每章核心问题/考察点），`knowledge-system.md` 是递进式教案（背景/本质问题/核心机制/进阶）。

---

## subagent 纪律（起草子智能体与评审子智能体共用）

`plan` 执行过程中会派两类子智能体：阶段 7 的**起草子智能体**（逐子主题生成教案文本）和阶段 8 的**4 维评审子智能体**。二者必须遵守以下纪律，主对话 also 默认不在 `plan` 执行中调用 WebSearch/WebFetch。

1. **工具权限 —— 禁止联网。** subagent **严禁**调用 WebSearch、WebFetch 以及任何其他联网工具；只能使用 Read 读取输入上下文中已提供的文件、Bash 进行纯本地处理、Agent 返回结果。主对话在 `plan` 执行期间也默认不调用 WebSearch/WebFetch。
2. **输入来源 —— 只读既定材料。** subagent 只能基于以下素材工作：现有 teaching plans / knowledge tree / knowledge-system.md、本轮对话历史、模型内部领域知识、用户在阶段 3 提供的参考资料路径。禁止主动检索外部网页、文档、博客、论文或在线课程。
3. **输出契约。**
   - **起草子智能体**：只返回其被分配子主题下的 markdown 教案文本（背景/本质问题/核心机制/进阶四段），不返回 frontmatter、不写文件、不输出额外说明。
   - **评审子智能体**：严格按 `review-rubric.md` 第四节 `gaps[]` JSON 结构返回缺口；除 JSON 外不要解释性文字。
4. **失败回退。**
   - 起草子智能体失败/超时 → 由阶段 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 第三节格式生成：
1. frontmatter：`topic`/`slug`/`version`/`level`/`kind`/`createdAt`（更新时 `version` 递增）。
2. 每个 `##` 子主题下先写 **核心问题** 和 **本章考察点**，再写该子主题的叶子节点 checkbox。
3. checkbox 状态：新建全 `- [ ]`；更新模式按合并语义只增不毁，保留已有勾选/🔴。

### 阶段 7：生成教学教案（knowledge-system.md，**分块写，禁止一次性整文件输出**）

⚠️ 一次性输出几十个 roadmap 级节点会**超时失败**。严格按 data-contract 第十二节「大文件分块写入策略」:

1. 先用 Write 建文件:表头 `# <topic> 教学教案` + 末尾哨兵 `<!-- @end -->`。
2. 用 **TodoWrite** 为 `knowledge-tree.md` 中每个 `##` 子主题建一个 todo（「生成+落盘 <子主题>」），作为本阶段进度看板。
3. **按 knowledge-tree.md 中 `##` 子主题的出现顺序**，每次取**最多 7 个未完成子主题**组成一批，用 Agent 工具**并行派起草子智能体**（每个只起草一个子主题、只返回该子主题的 markdown 文本、不写文件）。
4. 等待整批全部返回或超时后，主体**按 tree 顺序**（不是按返回先后）用 **Edit 替换哨兵**把本批每个子主题逐块追加到 `knowledge-system.md`；每个子主题的内容严格按 data-contract 第四节格式（**背景 / 本质问题 / 核心机制 / 进阶**；核心机制每条带结论与原理/取舍/边界、不许只写名词）。**一个子主题一次 Edit**。
5. 本批全部追加后，用 **TodoUpdate** 勾掉成功落盘的子主题；失败/超时的子主题保持未勾选，并在 todo 里加注失败原因（如「超时」「返回为空」「格式不符」），不阻塞其余批次。
6. 重复步骤 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）:
1. 合并四维 `gaps[]`，按 `node+suggestion` 去重。
2. 任一维度返回非空 gaps 均触发 system 教案重写（新增/加深节点内容、补背景/本质问题等；**补 system 同样用分块 Edit 追加，见 data-contract 第十二节**）。优先 `high`、再 `medium`。
3. **循环复审**(loop-until-dry,定义如下，不许凭感觉收尾):
   - **一轮** = 覆盖度 / 深度 / 递进性（挂书再加书本忠实度）四维评审子智能体**并行各跑一次**。
   - **dry（终止）** = 本轮 **coverage、depth、progression 三维均返回空 gaps**（book-fidelity 的 `low` 缺口**不计入**终止判定，可在篇幅允许时顺带补）。
   - 每轮补完缺口后再派下一轮;**硬上限 3 轮**（含可能采用的更严格视角复审轮），到顶即停。
   - 到达上限仍有未补的 high/medium → 不强撑，在摘要里**列出这些缺口**，提示用户「可稍后 `/swcc-plan <topic> --update` 补全」。
4. 若某评审子智能体调用失败/超时，或其返回内容中出现 `http(s)://` URL、引用了输入上下文未提供的网页/文档/博客，或出现「according to web/article/online / 据网络/文章/在线资料」等外部检索措辞，则主对话应**丢弃该结果并按失败处理**：先等待其余维度返回；若全部失败则本轮按空 gaps 处理并继续（不阻塞用户），在摘要中提示「评审暂不可用，本次未做质量补全」。
5. 记下「评审补了哪些缺口」用于摘要。

> 若四个维度的子智能体都返回空缺口,先对照 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 个文件齐全，更新模式下旧进度零丢失。