# Deep Dive

> 深度拆解任意开源项目或 Claude Skill，生成分层递进的结构化教程文档。当用户说'拆解这个项目'、'帮我理解这个是怎么工作的'、'讲透 xxx'、'分析一下这个 skill'时触发。支持增量更新：当用户发现已解析技能有新版本时，执行版本对比和增量解析。

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

---


# deep-dive

深度拆解任意开源项目或 Claude Skill，生成分层递进的结构化教程文档。

当用户说"拆解这个项目"、"帮我理解这个是怎么工作的"、"讲透 xxx"、"分析一下这个 skill"时触发。

---

## 核心设计原则

1. **按运行顺序组织，而非文件结构**
   - 低效："先看 main.py，再看 utils.py..."
   - 高效："输入 → 预处理 → 核心转换 → 输出"

2. **分层递进，由浅入深**
   - 第 1 层（5 分钟）：全景概览，解决"这是什么"
   - 第 2 层（15 分钟）：核心机制，解决"怎么运作"
   - 第 3 层（25 分钟）：实现细节，解决"代码怎么写"
   - 第 4 层（20 分钟）：扩展实战，解决"怎么用/改"
   - 第 5 层（15 分钟）：链接与共鸣，解决"与我何干"

3. **复杂度自适应**
   - < 500 行：2 层（概览 + 详解）
   - 500-5000 行：3 层（+ 实现细节）
   - > 5000 行：4 层（+ 扩展实战）+ 模块索引
   - 任意规模：+ 第 5 层（链接与共鸣，当用户 skills 库存在相关概念时）

---

## 触发条件

用户表达以下意图时触发：

- "拆解这个项目 [链接]"
- "帮我理解 [链接] 是怎么工作的"
- "讲透 [项目名称]"
- "深度分析 [链接]"
- "这个 skill 的逻辑是什么"
- "放到 [目录] 下"（用户指定输出位置）
- "xx 技能有更新"、"发现新版本"（技能迭代更新）

---

## 工作流程

### 分支 A：首次解析（默认）

#### 第 1 步：确认输出目录

**必须询问**：教程文档放到哪个目录？

```
用户：拆解这个项目 https://github.com/xxx，放到 ./教程/xxx/
```

如果用户未指定，询问：
> "你想把教程文档放在哪个目录？（例如：./教程/项目名称/）"

---

#### 第 2 步：获取并分析项目

##### 2.1 识别项目类型

| 输入类型 | 识别特征 | 获取方式 |
|---------|---------|---------|
| GitHub 仓库 | github.com 链接 | web-access skill 抓取文件树、README、核心源码 |
| Claude Skill | 本地路径或 skills.sh 链接 | 读取 SKILL.md、scripts/ 目录 |
| Web 工具/服务 | 任意 URL | 抓取主页 + 文档页，寻找 GitHub 链接 |
| 本地项目 | 本地文件路径 | 直接读取文件结构 |

##### 2.2 评估项目复杂度

扫描代码量，确定分层数：

```python
total_lines = count_code_lines(project_files)

if total_lines < 500:
    layers = 2  # 概览、详解
elif total_lines < 5000:
    layers = 3  # + 实现细节
else:
    layers = 4  # + 扩展实战
```

##### 2.3 提取关键信息

回答以下问题（用于后续章节）：

| 问题 | 用途 |
|-----|------|
| 这个项目解决什么具体问题？ | 确定价值定位（第 1 层）|
| 用户的输入是什么？输出是什么？ | 确定数据流起点终点（第 2 层）|
| 核心转换/处理是什么？ | 找到关键算法/逻辑（第 3 层）|
| 有哪些外部依赖？ | 理解边界和约束（第 2 层）|
| 配置在哪里？如何扩展？ | 确定二次开发入口（第 4 层）|

---

#### 第 3 步：生成分层教程

按顺序生成以下文档（根据复杂度自适应）：

```
[输出目录]/
├── README.md              ← 目录索引 + 学习路径建议
├── 01-概览与定位.md        ← 项目是什么、解决什么问题、适用场景
├── 02-架构与数据流.md      ← 整体架构图、数据流转、核心模块关系
├── 03-核心机制详解.md      ← 关键代码走读、算法原理、设计决策
├── 04-扩展与实战.md        ← 如何调试、如何修改、如何添加功能
└── 05-链接与共鸣.md        ← 与用户现有技能的链接、概念共振、启发迁移
```

##### 每层文档的固定结构

```markdown
# [章节标题]

> 定位：解决什么问题，学完后能做什么

## 一、核心问题
一句话描述本章要理解的难点。

## 二、原理图解
Mermaid 流程图或文字描述数据流。

## 三、关键实现
代码片段 + 逐行解释。

## 四、实际效果
输入什么 → 经过什么处理 → 输出什么。

## 五、调试/验证
读者可以自己试的命令或方法。

## 六、小结
3-5 个要点。
```

---

#### 第 4 步：特殊处理（Skill 项目）

如果分析的是 Claude Skill，额外关注：

| 普通项目 | Skill 项目 |
|---------|-----------|
| 看 README | **优先看 SKILL.md** |
| 找入口函数 | **找触发条件** |
| 看配置系统 | **看 Instructions 怎么写** |
| 理解数据流 | **理解用户意图识别** |

**专用章节**：
- "触发词是怎么设计的？"
- "Instructions 如何组织工作流？"
- "如何与 Claude 的 capabilities 配合？"

---

#### 第 5 步：共鸣发现（链接层）

**触发条件**：
- 用户已安装 skills 库存在相关概念
- 本 Skill 的核心概念与用户现有 Skill 形成共振

**执行流程**：

##### 5.1 概念提取
从本 Skill 解析中提取核心概念：
- 关键术语（如 `plain_text`、`async`、`oauth`、`recall`）
- 设计原则（如 "信任用户"、"异步处理"、"零依赖"）
- 机制模式（如 "轮询"、"直传"、"分层递进"）

##### 5.2 用户 Skills 库扫描
扫描 `~/.claude/skills/` 或用户指定的 skills 目录：
- 读取各 Skill 的 SKILL.md frontmatter 和关键描述
- 提取概念关键词
- 匹配潜在共鸣点

##### 5.3 共鸣识别
识别以下类型的链接：

| 共鸣类型 | 示例 | 说明 |
|---------|------|------|
| **概念共振** | Get笔记.plain_text ↔ ljg-plain.白 | 相同概念，不同语境 |
| **设计同源** | 轮询机制 ↔  OAuth 轮询脚本 | 相同模式，不同应用 |
| **哲学呼应** | "信任用户" ↔ "信任读者" | 共享原则，不同领域 |
| **机制互补** | async 任务 ↔ sync 保存 | 对立统一，完整图景 |

##### 5.4 生成 05-链接与共鸣.md

**文档结构**：

```markdown
# 05 - 链接与共鸣

> 定位：这个 Skill 与你的已有 Skill 如何对话？

## 一、概念共振

### [概念 A]
- **在本 Skill 中**：...
- **在你的 [Skill X] 中**：...
- **共鸣点**：...

## 二、设计哲学对照

| 本 Skill | 你的 Skill | 共享原则 |
|---------|-----------|---------|
| ... | ... | ... |

## 三、启发与迁移

- **机制迁移**：本 Skill 的 [X] 机制可以如何优化你的 [Y]？
- **原则反刍**：你的 [Z] 原则可以如何丰富本 Skill 的理解？

## 四、小结

核心洞见：...
```

---

### 分支 B：技能迭代更新

当用户输入包含"技能有更新"、"发现新版本"、"迭代了"等信号时，执行增量更新流程：

#### 第 1 步：版本检测

读取本地解析文档的 frontmatter，确认：
- `version`: 当前记录的版本
- `analyzed_at`: 上次解析日期

#### 第 2 步：评估变更范围

获取新版本 SKILL.md，对比变更类型：

| 变更类型 | 判断标准 | 处理策略 |
|---------|---------|---------|
| **小版本迭代** | 新增 1-2 个参数、优化描述、修复 typo | 增量更新：创建 `04-版本更新解析-vx.x.x.md` |
| **中版本迭代** | 新增模具/模式、核心逻辑调整、参数重命名 | 补充章节：更新对应模具文档 + 变更对照表 |
| **大版本重构** | 架构重写、多个文件结构变更、破坏性更新 | 重新 deep-dive：保留旧文档作为历史版本 |

#### 第 3 步：执行更新

**小/中版本迭代**：

不做的事：
- ❌ 不重新生成 01/02/03（核心机制没变）
- ❌ 不修改原有文档

做的事：
- ✅ 创建 `04-版本更新解析-vx.x.x.md`
  - 版本概览对照表
  - 参数变更映射
  - 新增/变更模具详解
  - Footer/变量变更说明
  - 选择指南

**大版本重构**：

- ✅ 重新执行完整 deep-dive 流程
- ✅ 旧版文档移至 `[输出目录]/_历史版本/vx.x.x/`
- ✅ 生成全新的 01/02/03/04

#### 第 4 步：更新索引

更新 `README.md`：
- 添加「版本历史」章节
- 列出各版本解析文档

---

## 输出规范

### 文档元数据

每篇文档开头包含 YAML frontmatter：

```yaml
---
project: [项目名称]
source: [原始链接]
analyzed_at: [分析日期]
complexity: [small|medium|large]
layers: [2|3|4|5]
layer: [1|2|3|4|5]
version: [版本号，如 "1.7.0"]
previous_version: [上一版本号，增量更新时填写]
---
```

### 代码引用格式

标注代码位置，方便读者查找：

```markdown
本文档讲解的代码位于：
- `src/core.py:45-78` ← 配置加载逻辑
- `src/engine.py:120-156` ← 核心转换算法
```

### 双向导航

每篇文档末尾包含：

```markdown
> 上一篇：[xxx.md](./xxx.md)
>
> 下一篇：[xxx.md](./xxx.md)
```

第一篇和 README 显示：
> 这是系列教程的第 1 篇，共 N 篇。

---

## 质量控制检查清单

生成每篇文档后自检：

- [ ] 是否回答了该层应该解决的核心问题？
- [ ] 是否有具体的代码/数据示例，而非纯概念？
- [ ] 是否有可视化辅助（流程图/架构图/表格）？
- [ ] 读者读完能否向他人讲清楚这一层的内容？
- [ ] 与源码的链接是否准确？

---

## 示例用法

### 示例 1：GitHub 项目

```
用户：拆解这个项目 https://github.com/xiaohuailabs/xiaohu-wechat-format，放到 ./教程/微信发布助手/

AI：好的，我来深度拆解这个项目。首先让我获取项目内容...
[分析中...]

已生成 4 层教程（项目复杂度：中型，约 3000 行）：
- ./教程/微信发布助手/README.md
- ./教程/微信发布助手/01-概览与定位.md
- ./教程/微信发布助手/02-架构与数据流.md
- ./教程/微信发布助手/03-核心机制详解.md
- ./教程/微信发布助手/04-扩展与实战.md
```

### 示例 2：Claude Skill（含共鸣层）

```
用户：帮我理解 skill-creator 是怎么工作的，放到 ./学习笔记/

AI：我来分析 skill-creator 的工作原理...
[分析中...]

已生成 4 层教程（项目复杂度：中型）：
- ./学习笔记/skill-creator/README.md
- ./学习笔记/skill-creator/01-概览与定位.md
- ./学习笔记/skill-creator/02-架构与数据流.md
- ./学习笔记/skill-creator/03-核心机制详解.md
- ./学习笔记/skill-creator/04-扩展与实战.md

[扫描用户 skills 库...]
发现共鸣：skill-creator 的"渐进式披露"原则 ↔ 你的 ljg-plain "结构自由"

已生成第 5 层：
- ./学习笔记/skill-creator/05-链接与共鸣.md
```

### 示例 3：Get笔记 Skill 的 plain 共鸣（第 5 层示例）

```
用户：拆解 getnote-openclaw，放到 ./教程/

AI：好的，我来深度拆解 Get笔记 Skill...
[分析中...]

已生成 4 层教程（项目复杂度：中型）：
- ./教程/getnote-openclaw/README.md
- ./教程/getnote-openclaw/01-概览与定位.md
- ./教程/getnote-openclaw/02-架构与数据流.md
- ./教程/getnote-openclaw/03-核心机制详解.md
- ./教程/getnote-openclaw/04-扩展与实战.md

[扫描用户 skills 库...]
发现概念共振：getnote.plain_text ↔ ljg-plain.白

已生成第 5 层：
- ./教程/getnote-openclaw/05-链接与共鸣.md

核心洞见：两者共享"削去中介，直达本质"的设计哲学——
- getnote：plain_text 是唯一不需要 AI 加工的笔记类型
- ljg-plain：结构自由，形式跟随内容，去除 AI 生成痕迹
```

### 示例 4：技能迭代更新

```
用户：ljg-card 技能有更新

AI：检测版本变更中...
- 本地版本：1.6.0
- 远程版本：1.7.0
- 变更类型：中版本迭代（新增 3 种模具，参数重命名）

执行增量更新：
- ./教程/ljg-card/04-版本更新解析-v1.7.0.md ← 新增
- ./教程/ljg-card/README.md ← 更新版本索引
```

---

## 注意事项

1. **不要一次性 dump 所有信息** —— 严格按分层递进
2. **不要用"首先...其次...最后..."罗列文件** —— 要按数据流组织
3. **不要省略"为什么这样设计"** —— 每个关键决策都要解释原因
4. **不要生成无法验证的内容** —— 所有代码引用必须真实存在
5. **不要忘记询问输出目录** —— 这是必须的用户输入

---

## 依赖

- `web-access` skill —— 用于抓取远程项目
- `web-content-extraction` skill —— 用于提取文档内容
- 文件系统工具 —— 用于读取本地项目和写入文档