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 识别项目类型

2.2 评估项目复杂度

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

total_lines = count_code_lines(project_files)

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

2.3 提取关键信息

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

第 3 步：生成分层教程

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

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

每层文档的固定结构

# [章节标题]

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

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

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

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

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

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

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

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

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

专用章节：

• "触发词是怎么设计的？"
• "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 共鸣识别

识别以下类型的链接：

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

文档结构：

# 05 - 链接与共鸣

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

## 一、概念共振

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

## 二、设计哲学对照

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

## 三、启发与迁移

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

## 四、小结

核心洞见：...

分支 B：技能迭代更新

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

第 1 步：版本检测

读取本地解析文档的 frontmatter，确认：

• version: 当前记录的版本
• analyzed_at: 上次解析日期

第 2 步：评估变更范围

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

第 3 步：执行更新

小/中版本迭代：

不做的事：

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

做的事：

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

大版本重构：

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

第 4 步：更新索引

更新 README.md：

• 添加「版本历史」章节
• 列出各版本解析文档

输出规范

文档元数据

每篇文档开头包含 YAML frontmatter：

---
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: [上一版本号，增量更新时填写]
---

代码引用格式

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

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

双向导航

每篇文档末尾包含：

> 上一篇：[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 —— 用于提取文档内容
• 文件系统工具 —— 用于读取本地项目和写入文档