# Devtree

> 依据 docs/DEVTREE.md 中作者维护的 Epic 结构，重新生成可视化图表和节点索引

- Skill: `pkulijing/devtree` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pkulijing/devtree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pkulijing/devtree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pkulijing (https://skillmd.com/u/pkulijing)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pkulijing/devtree

---


用户调用此 skill 表示要刷新「可视化」和「节点索引」两个区块（含同步本轮开发项的 Epic 归属）。

---

## 核心原则：每次都从 Epic 结构完全重建

**「Epic 结构」区块是单一事实来源。「可视化」和「节点索引」每次调用本 skill 时都必须被完全重建，不允许增量修补、不允许从旧图里复制结构。**

执行流程：

1. 读取并解析「Epic 结构」区块
2. **丢弃**现有「可视化」与「节点索引」区块的全部内容（它们是从上次 Epic 结构渲染的过时产物）
3. **只从**当前「Epic 结构」 + 各开发项 SUMMARY.md 重新构造两个区块
4. 整块替换写回

如果旧「节点索引」表里有某开发项的「一句话描述」且该开发项在新 Epic 结构中仍存在，可以复用这一行描述（避免重新读 SUMMARY.md），但层级/归属一律以新 Epic 结构为准。

**例外：冷启动**。当 `docs/DEVTREE.md` 不存在，或文件中没有「Epic 结构」区块，或 Epic 结构区块没有任何叶 Epic 时，本 skill 改为落初始骨架（见下文「第零步」），不报错。只要 Epic 结构非空，仍严格遵循「从 Epic 结构完全重建」原则。

---

## docs/DEVTREE.md 文件结构

**区块顺序（从上到下）：可视化 → 节点索引 → Epic 结构。** 读者最先看到的是图，其次是索引表，最底下才是作者手写的依赖关系定义 —— 从「结论」到「原料」。

| 顺序 | 区块          | 维护者            | 说明                                       |
| ---- | ------------- | ----------------- | ------------------------------------------ |
| 1    | **可视化**    | AI 维护           | Mermaid 图                                 |
| 2    | **节点索引**  | AI 维护           | 所有开发项的分类与 Epic 归属表             |
| 3    | **Epic 结构** | 作者主导，AI 协助 | Markdown 树形列表，定义目标层次 + 轮次归属 |

（「可视化」「节点索引」每次从 Epic 结构完全重建，见上「核心原则」。另有「分类图例」小区块在「可视化」之前，作阅读字典。）

**Epic 结构是作者主导维护的区块**。AI 按下述策略协助：

- **作者已手改入新开发项** → 以作者版本为准、不覆盖，直接渲染。
- **本轮有新开发项但 Epic 结构里没有** → AI 提议追加（往哪个叶 Epic 加 + 理由，或建议新建），等作者确认后写回再渲染。
- **本轮 Epic 结构与现状一致** → 跳过提议，直接渲染。

---

## Epic 结构规范

作者在「Epic 结构」区块中用 Markdown 标题层级定义目标树：

- 非叶 Epic（中间节点）：只有子目标，没有「状态」和「轮次」
- 叶 Epic（最底层目标）：有「状态」和「轮次」字段
  - 状态取值：`已完成` / `进行中` / `已放弃`
  - 轮次：逗号分隔的开发项编号列表
- 同一叶 Epic 内的开发项是**并列关系**，没有层次，没有先后

---

## 开发项分类体系

为每个开发项分配以下 6 类之一，依据 SUMMARY.md（或 PROMPT.md）内容判断：

| 类型 | classDef 名 | 图标 | 判断标准                   |
| ---- | ----------- | ---- | -------------------------- |
| 初建 | genesis     | 🌱   | 某功能域首次从零建立       |
| 功能 | feature     | ✨   | 扩展用户可感知的能力       |
| 修复 | bugfix      | 🐛   | 纠正缺陷或回归             |
| 重构 | refactor    | 🏗️   | 内部结构改善，用户行为不变 |
| 工程 | infra       | 📦   | 打包/CI/分发/工具链        |
| 探索 | research    | 🔬   | 调研，可能被搁置或回退     |

---

## 执行步骤

### 第零步：冷启动判定与骨架落盘

按顺序检查：

1. `docs/DEVTREE.md` 是否存在
2. 文件中是否存在「Epic 结构」区块（`## Epic 结构` 标题）
3. 该区块是否包含至少一个叶 Epic（即至少有一个标题节点带「状态」「轮次」字段）

任一不满足 → **判定为冷启动**：

- `mkdir -p docs`（如果 `docs/` 也没有）
- 写入完整骨架（按下文「输出格式模板」结构），其中：
  - 「分类图例」区块：原样写入模板内容
  - 「可视化」区块：仅写一行占位 `> Epic 结构尚未填写，待作者添加叶 Epic 后再次调用 /devtree 渲染。`
  - 「节点索引」区块：同上占位
  - 「Epic 结构」区块：写入说明性占位，引导作者维护，例如：
    ```
    （此区块由作者维护。在此用 Markdown 标题层级定义目标树。叶 Epic 包含「状态」（已完成 / 进行中 / 已放弃）与「轮次」（逗号分隔的开发项编号列表）字段；非叶 Epic 仅作为分组节点。完整规范见 ~/.claude/skills/devtree/SKILL.md。）
    ```
- 写完即返回，**不**继续执行后续步骤

三个条件全部满足 → 冷启动判定不触发，继续执行第一步。

### 第一步：解析 Epic 结构（唯一事实来源）

读取 `docs/DEVTREE.md` 的「Epic 结构」区块，提取：

- Epic 的层次关系（哪些是中间节点，哪些是叶）
- 每个叶 Epic 的名称、状态、所含开发项编号列表

这一步的数据模型是后续生成的**唯一依据**（不回看旧「可视化」/「节点索引」推断结构）。

### 第二步：为每个开发项确定分类

遍历「Epic 结构」中列出的所有开发项编号：

- 若该编号已在旧「节点索引」表中，直接复用其类型和一句话描述
- 否则读取 `docs/{编号}-*/SUMMARY.md`（若无则读 `PROMPT.md`）分配类型、写一句话描述

### 第三步：从零生成「可视化」区块

Mermaid 格式规范：

- 整体是一棵有根树，用有向边（`-->`）表达 Epic 层级关系
- 根节点：`ROOT["{项目目录名}"]:::epic`（由 AI 根据项目上下文推断）
- **非叶 Epic**：普通节点 `{id}["{名称}"]:::epic`，通过 `-->` 边与父节点连接
  - id 用英文缩写，如 `pd`、`ea`、`cross`
- **叶 Epic**：`subgraph {id}["{状态图标} {名称}"]` 容器，内部声明 `direction TB`，通过 `-->` 边从父节点指向 subgraph id
  - 状态图标：✅ 已完成 / 🔄 进行中 / ❌ 已放弃
- 开发项节点放在所属叶 Epic 的 subgraph 内，节点之间用 `~~~`（不可见链接）强制纵向堆叠，不画有向边
- 开发项格式：`N{编号}["{类型图标} {编号} · {文件夹中文名}"]:::{classDef名}`
- 新增 `classDef epic fill:#f8f9fa,stroke:#adb5bd,color:#495057` 用于 Epic 节点配色

#### Mermaid 防御性渲染规则（必须遵守）

历史上踩过坑的几条硬规则，不要图省事：

1. **`~~~` 必须两两成对，不许链式**：`N1 ~~~ N2 ~~~ N3` 链式写法在某些 Mermaid 版本会把中间节点当过渡吞掉、整个不渲染。拆成独立行（即便只两个节点）：
   ```
   N1 ~~~ N2
   N2 ~~~ N3
   ```
2. **先集中声明边，再声明 subgraph**：所有 `-->` 边放最前面，subgraph 块全部放在边声明之后。解析更稳、diff 更清爽。
3. **flowchart init 用 `rankSpacing: 30, nodeSpacing: 20`**：节点密集的子图需更多呼吸空间，否则标签重叠或被裁。
4. **节点标签里中英文之间留空格**：`Qwen3-ASR 替换 SenseVoice` 优于 `Qwen3-ASR替换SenseVoice`，避免个别渲染器对 CJK + 连字符的怪异处理。节点索引名称列同步保持一致。

### 第四步：从零生成「节点索引」区块

按编号升序排列，每行包含：编号、名称、类型、所属叶 Epic、一句话描述。「所属 Epic」列**必须**与第一步解析出的 Epic 结构一致，不得沿用旧索引中的归属。表格用**紧凑单空格**、不对齐补空格（见「输出格式模板」的表格规则）。

---

## 输出格式模板

区块顺序固定：**分类图例 → 可视化 → 节点索引 → Epic 结构**。

**表格一律用紧凑单空格**：生成「分类图例」「节点索引」等表格时，每个单元格只用**一个空格**包裹、竖线不对齐（`| a | b |`、分隔行 `| - | - |`），**绝不**把各列补空格对齐到等宽。原因：DEVTREE.md 已被 `.prettierignore` 豁免，对齐补空格会让「内容一变整列重排」→ 每次 `/devtree` 刷新 diff 爆炸；紧凑单空格下改一行只动那一行（渲染结果两种写法相同）。**注意**：下方示例表在本 SKILL.md 里显示为对齐，是因 SKILL.md 自身不在豁免名单、被 prettier 补齐——示例仅供看列结构，写进 DEVTREE.md 时务必用紧凑单空格。

````markdown
# 开发树

## 分类图例

| 图标 | 类型 | 说明                       |
| ---- | ---- | -------------------------- |
| 🌱   | 初建 | 某功能域首次从零建立       |
| ✨   | 功能 | 扩展用户可感知的能力       |
| 🐛   | 修复 | 纠正缺陷或回归             |
| 🏗️   | 重构 | 内部结构改善，用户行为不变 |
| 📦   | 工程 | 打包/CI/分发/工具链        |
| 🔬   | 探索 | 调研，可能被搁置           |

## 可视化

```mermaid
%%{init: {'flowchart': {'rankSpacing': 30, 'nodeSpacing': 20}}}%%
graph TD
  classDef genesis  fill:#d4edda,stroke:#28a745,color:#155724,font-weight:bold
  classDef feature  fill:#cce5ff,stroke:#0d6efd,color:#003d8f,font-weight:bold
  classDef bugfix   fill:#f8d7da,stroke:#dc3545,color:#721c24,font-weight:bold
  classDef refactor fill:#fff3cd,stroke:#ffc107,color:#664d03,font-weight:bold
  classDef infra    fill:#e2d9f3,stroke:#6f42c1,color:#3d1a78,font-weight:bold
  classDef research fill:#e2e3e5,stroke:#6c757d,color:#383d41,font-weight:bold
  classDef epic     fill:#f8f9fa,stroke:#adb5bd,color:#495057,font-weight:bold,font-size:15px

  ROOT["项目名"]:::epic
  ROOT --> ea["顶层 Epic A"]:::epic
  ea --> ea1
  ea --> ea2

  subgraph ea1["✅ 叶 Epic A1"]
    direction TB
    N0["🌱 0 · 示例开发项"]:::genesis
  end

  subgraph ea2["🔄 叶 Epic A2"]
    direction TB
    N1["✨ 1 · 示例开发项"]:::feature
    N2["🐛 2 · 示例开发项"]:::bugfix
    N1 ~~~ N2
  end
```

## 节点索引

> 最后更新：{今日日期} | 共 {N} 轮

| #   | 名称       | 类型    | 所属 Epic  | 一句话描述     |
| --- | ---------- | ------- | ---------- | -------------- |
| 0   | 示例开发项 | 🌱 初建 | 叶 Epic A1 | （一句话描述） |
| 1   | 示例开发项 | ✨ 功能 | 叶 Epic A2 | （一句话描述） |
| 2   | 示例开发项 | 🐛 修复 | 叶 Epic A2 | （一句话描述） |

## Epic 结构

（此区块由作者主导维护；AI 仅在有新开发项且作者尚未自行加入时，提议追加并等确认后写入。）
````

---

## 当已存在的 DEVTREE.md 是旧顺序（Epic 结构在前）

如果进入本 skill 时看到的 `docs/DEVTREE.md` 还是老顺序（Epic 结构在第一位），**本次调用要顺手把全文颠倒成新顺序**：分类图例 → 可视化 → 节点索引 → Epic 结构。一次性完成，之后就按新顺序维护。