study-master

Category: Docs & Knowledge | Uploader: Learner-Geek-Perfectionist | Downloads: 0 | Version: v1.0（Latest）
深入学习开源项目源码、协议规范和语言框架内部机制，生成教科书风格的学习文档
Changelog: Source: GitHub https://github.com/Learner-Geek-Perfectionist/claude-code-study-skills
Directory Structure

Current level: study-master-skill/
📁 hooks/
- 📄 check-study_master.sh 588 B
- 📄 validate_study_master.py 12.0 KB
📄 install.sh 3.5 KB
📄 SKILL.md 9.0 KB
SKILL.md

---
name: study-master
description: 深入学习开源项目源码、协议规范和语言框架内部机制，生成教科书风格的学习文档
---

# Study-Master Skill

## 概述

帮助程序员深入学习开源项目源码、协议栈实现（如 TCP/IP、HTTP）、特定编程语言或框架的内部机制。生成深度解析型学习文档，采用教科书风格，文档规模根据主题复杂度动态调整。支持自动检测并使用 LSP 增强代码分析。

## 强制目录结构

- `source/` — 源码目录
- `specs/` — 协议规范文档
- `study/<topic>/` — 学习文档输出目录（自动创建）

**规则**：至少 `source/` 或 `specs/` 之一必须存在。两者都不存在时拒绝执行并提示用户调整目录结构。

## 教科书风格原则

1. **先整体后局部**：先展示模块在系统中的位置，再深入细节
2. **先接口后实现**：先讲清楚"做什么"，再讲"怎么做"
3. **先主流程后边界**：先追踪正常执行路径，再分析错误处理
4. **先概念后代码**：先用自然语言解释设计思想，再展示代码

## 工作流程

### Phase 1：源码加载与分析

#### 1.1 源码定位与环境准备

1. 检查 `source/` 或 `specs/` 目录是否存在
2. 按优先级查找：`source/<topic>/` → `source/*<topic>*/` → `specs/<topic>/` → `specs/*<topic>*/` → `./<topic>/`（不区分大小写，支持部分匹配）
3. 找到多个候选时列出让用户选择
4. 解析 `<topic>` 参数，判断类型（项目/协议/语言内部机制）
5. 创建输出目录 `study/<topic>/`

#### 1.2 LSP 检测（C/C++ 项目必须执行，其他语言跳过）

**必须主动执行以下两步，不允许跳过或假设结果：**

1. **搜索 `compile_commands.json`**：用 Glob 在源码根目录、上级目录、build/ 子目录中查找
2. **测试 LSP**：对源码中的一个 `.c` 文件执行 `LSP documentSymbol`，确认返回符号列表

**必须向用户报告检测结果**：`✓ LSP 可用（找到 compile_commands.json，documentSymbol 返回 N 个符号）` 或 `✗ LSP 不可用（原因）`。如果 LSP 可用，后续分析必须优先使用 LSP 工具而非 Grep。

#### 1.3 全源码深度分析

利用 1M 上下文窗口，执行全源码深度分析：

1. **源码加载**：Read 项目所有核心源文件到上下文中
2. **结构分析**：根据 LSP 可用性选择分析方法，识别核心模块、热点函数和模块依赖关系

   | 分析任务 | LSP 可用 | LSP 不可用 |
   |---------|---------|-----------|
   | 符号列表 | `LSP documentSymbol` | Grep 搜索函数定义 |
   | 核心 API | `LSP findReferences` 统计引用次数 | 基于文件位置和命名推断 |
   | 模块依赖 | 基于符号的文件位置分组 | Glob/Grep 扫描 include/import |
   | 调用关系 | `LSP findReferences` | Grep 搜索函数名 |
   | 调用树 | `prepareCallHierarchy` + `incomingCalls` + `outgoingCalls` | 手动推断 |

3. **深度解读**：在拥有全部源码的上下文中分析每个模块的设计意图、职责边界、关键算法、模块间耦合关系和设计决策
4. **热点函数深度分析**：对每个核心函数，阅读完整实现，理解内部逻辑、错误处理策略和与其他模块的交互方式

#### 1.4 确定章节大纲

基于深度分析，确定章节划分和学习路径，明确列出所有需要生成的章节。

**必须完成以下准备（结论保留在上下文中，不写文件）：**

1. **计算 `source_path_prefix`**：统计 `study/<topic>/` 相对于项目根的目录层数，每层一个 `../`。例如 `study/redis/` 为 2 层 → `../../`。
2. **确定章节大纲和各章节的主要标题结构**：明确各章节会包含哪些核心结构体/函数的定义标题，以便串行生成时自然地内嵌前向和后向交叉引用。

### Phase 2：串行生成文档

**策略：主对话利用 1M 上下文串行生成所有章节。**

每一章都在拥有以下完整上下文的环境中生成：
- Phase 1 加载的全部源码
- Phase 1.3 的深度分析结论
- 所有已生成的前序章节内容（上下文累积）

生成顺序：`00-overview.md` → `01-xxx.md` → ... → `NN-xxx.md` → `appendix-references.md`

#### 2.1 逐章生成

按章节大纲顺序，使用 Write 工具依次生成每个章节。每章生成后立即 Read 验证无乱码（U+FFFD），发现问题用 Edit 修正。

**Overview 章节（00-overview.md）结构：**

1. **项目/协议简介**：背景、目标、核心特性
2. **核心概念速览**：关键术语、设计理念
3. **典型场景剖析**：选择 1-2 个典型场景，追踪完整执行路径
4. **架构全景图**：Mermaid 图展示系统整体结构
5. **学习路线图**：建议学习顺序，导航后续章节

**模块章节（01~NN-module-xxx.md）结构（7 节必须齐全）：**

1. **模块概述**：模块职责、在系统中的位置
2. **API 签名速查**：该模块所有函数的完整 C 签名（代码块），每个函数一行注释说明用途。包括公开 API 和文档中分析到的内部函数，不可省略。
3. **多层次代码展示**：调用关系图（Mermaid）→ 伪代码 → 真实代码片段 → 实现细节
4. **数据结构深度解析**：结构定义、字段含义、生命周期
5. **关键算法剖析**：算法思想、时间复杂度、边界处理
6. **设计决策分析**：为什么这样设计、权衡考虑、替代方案
7. **学习检查点**：📝 本章小结（3-5 个要点）+ 🤔 思考题（2-3 个引导性问题）

**生成规范：**
- 遵循教科书风格四原则
- **所有标识符必须可点击**：函数名、结构体名、文件名在任何位置（正文、表格、列表）出现时都必须有超链接，指向源码行号或其他章节的定义标题。绝不允许纯文本标识符。
- **交叉引用**：提到其他章节已分析或将要分析的结构体/函数/概念时，必须链接到该章节对应标题。每章至少应有 2-3 个指向其他章节的交叉引用，建立章节间的知识网络。
- **Mermaid 图表**：每个模块章节至少 2 个 Mermaid 图（如调用关系图 + 时序图/状态图），帮助读者从不同角度理解模块。

## 格式规范

### 链接格式

- 必须使用相对路径（前缀为 `source_path_prefix`），禁止 `file:///` 绝对路径
- 链接文本不加反引号（反引号破坏超链接样式）
- **源码位置格式**：`> 📍 源码：[文件名:起始行-结束行](相对路径#L起始行)`（表格内只写文件名）
- **文档间交叉链接**：`[术语名](./目标文件.md#锚点)`，锚点遵循 GFM 规则（全小写，空格→`-`）
- **标题语言规则**：普通章节标题必须用中文（如 `## 1. 背景与目标`、`### 关键算法剖析`）。仅以下两类标题用英文：结构体定义标题（`### struct ddsi_xxx`）和 API 签名节标题（`## 2. API Signatures`）。跨文件引用这两类标题时锚点自然是纯 ASCII，无需额外处理。跨文件引用中文标题时，引用方应链接到该文件中已有的英文标题（struct 或 API）而非中文小节标题。禁止使用 `{#id}` 自定义锚点语法。
- 有超链接 → 不加反引号；无超链接的标识符 → 必须加反引号

### 图表格式

- **所有图表必须使用 Mermaid**，禁止 ASCII art / box-drawing 字符（`┌─┐│└┘├┤` 等）
- **内存布局例外**：嵌套包含关系 Mermaid 渲染效果差，改为生成独立 `.svg` 文件到 `study/<topic>/`，用 `![描述](文件名.svg)` 引用。禁止内嵌 SVG（渲染器会过滤）
- 节点文本 ≤ 25 字符，图表节点总数 ≤ 20

### 代码块

- 所有代码块必须指定语言标识（C: ` ```c `，Shell: ` ```bash `，Mermaid: ` ```mermaid `）
- **伪代码用最接近的语言标识**（C 风格伪代码用 ` ```c `），禁止用 ` ```text ` 包裹有编程语言语法特征的代码

### 数学表达式

- 所有数学符号必须用 LaTeX（`$2^{31}$`、`$\times$`、`$\geq$`），禁止 Unicode 数学符号（²³、×、≥、≤ 等）

### 文本编码

- UTF-8，禁止 box-drawing Unicode 字符（`│`, `├`, `└`, `─` 等）

#### 2.2 生成参考索引

所有章节完成后，生成 `appendix-references.md`（参考资料索引）。

### Phase 3：收尾

1. 创建 `.study-meta.json`：

   ```json
   {
     "topic": "主题名",
     "source_path": "源码路径",
     "generated_at": "时间戳",
     "lsp_enabled": true/false,
     "chapters": ["00-overview.md", "01-xxx.md", ...]
   }
   ```

2. 输出最终报告：

   ```
   ✅ 学习文档生成完成！
   📍 位置：study/<topic>/
   📚 章节数：Y 个
   🔧 LSP 增强：已使用/未使用
   ```

## 文档结构概要

| 文件 | 内容 |
|------|------|
| `00-overview.md` | 快速导览：项目简介、核心概念、典型场景、架构图、学习路线 |
| `01-module-xxx.md` | 模块深度解析：概述、代码展示、数据结构、算法、设计决策、检查点 |
| `appendix-references.md` | 参考资料索引 |
| `.study-meta.json` | 元数据 |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
study-master

Directory Structure

SKILL.md

Report

Notice
