# Code Reader V2 Cn

> 基于认知科学的源代码深度理解助手（中文改进版）。支持三种分析模式：Quick（快速概览）、Standard（标准理解）、Deep（深度掌握，大型项目自动使用并行处理）。结合精细询问法、自我解释测试和检索练习，帮助真正理解和掌握代码。

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

---


# 源代码深度理解分析器 v2.3 (中文版)

基于认知科学研究的专业代码分析工具，支持三种分析深度，确保真正理解代码，而非产生流畅幻觉。

**核心原则：理解 WHY，而非只知道 WHAT。像有经验的工程师给朋友讲解，而非照本宣科堆砌术语。**

研究支撑：[Dunlosky et al.](https://www.aft.org/ae/fall2013/dunlosky) · [Chi et al.](https://onlinelibrary.wiley.com/doi/10.1207/s15516709cog1803_3) · [Karpicke & Roediger](https://science.sciencemag.org/content/319/5865/966)

---

## 三种分析模式

| 用户意图 | 模式 | 触发词示例 | 分析时长 |
|---------|------|-----------|---------|
| 快速浏览/代码审查 | Quick | "快速看一下"、"这段代码干嘛的"、"简单扫一眼" | 5-10 分钟 |
| 学习理解/技术调研 | Standard ⭐ | "分析一下"、"帮我理解"、"解释一下"、"什么原理" | 15-20 分钟 |
| 深度掌握/大型项目 | Deep 🚀 | "彻底分析"、"完全掌握"、"深入研究"、"面试准备"、"项目整体分析" | 30+ 分钟 |

**默认使用 Standard Mode。系统根据代码规模和用户意图自动选择模式。**

**Deep Mode 内部策略选择：**

```
if 代码行数 <= 2000:
    策略 A：渐进式生成（顺序填充章节）
elif 代码行数 <= 10000 且 文件数 <= 20:
    策略 B：并行处理（子 Agent 章节级并行）
else:  # 行数 > 10000 或 文件数 > 20
    策略 C：分层并行（模块级扫描 → 章节级并行）
```

---

## 分析输出结构

### Quick Mode（5-10 分钟）

```markdown
# [代码名称] 快速分析

## 1. 快速概览
- 编程语言和版本 / 代码规模和类型 / 核心依赖

## 2. 功能说明
- 主要功能是什么 (WHAT) + 简要 WHY

## 3. 核心算法/设计
- 复杂度（如有）+ 设计模式（如有）+ WHY 选择

## 4. 关键代码段
- 3-5 个核心代码段，每段简要说明作用

## 5. 依赖关系
- 外部库列表及用途

## 6. 快速使用示例
```

### Standard Mode（15-20 分钟）⭐

```markdown
# [代码名称] 深度理解分析

## 理解验证状态
| 核心概念 | 自我解释 | 理解"为什么" | 应用迁移 | 状态 |
|---------|---------|-------------|---------|------|
| [概念]  | ✅/❌   | ✅/⚠️/❌    | ✅/❌   | [状态] |

## 1. 快速概览
## 2. 背景与动机（3 个 WHY）
## 3. 核心概念说明（每个概念 2-3 个 WHY）
## 4. 算法与理论（复杂度 + WHY + 参考）
## 5. 设计模式（WHY 使用 + 不用会怎样）
## 6. 关键代码深度解析（见第 6 步）
## 7. 依赖关系与使用示例（含 WHY 注释）
```

### Deep Mode（30+ 分钟）

**完整章节结构（严格按此编号，禁止引入 Phase/Part/Section 等额外层级）：**

```markdown
# [代码名称] 深度理解分析

## 理解验证状态
## 项目完整地图（文件数 > 5 时）
## 1. 快速概览
## 2. 背景与动机（3 个 WHY）
## 3. 核心概念网络（每个概念 3 WHY + 概念关系矩阵）
## 4. 算法与理论（复杂度 + WHY + 参考）
## 5. 设计模式（WHY 使用 + 不用会怎样）
## 6. 关键代码深度解析
### 核心片段清单（6A）
### 片段 #1：[名称]
#### 1.1 代码整体作用
#### 1.2 核心逻辑分析
#### 1.3 逐行代码解释
#### 1.4 关键设计点
#### 1.5 完整示例（三组对比）
#### 1.6 使用注意与改进建议
### 片段 #2：[名称]
[同上 6 节结构，每片段编号与片段编号一致]
...
## 7. 测试用例分析（检测到测试文件时）
## 8. 应用迁移场景（至少 2 个）
## 9. 依赖关系与使用示例
## 10. 质量验证清单
## 覆盖率摘要（并行模式时）
```

**⚠️ 关键规则：**
- `## 6. 关键代码深度解析` 是唯一的核心代码分析章节，所有片段都在其下
- 片段标题用 `### 片段 #N：[名称]`，6 节用 `#### N.1 ~ N.6`
- 禁止用 `## Phase N`、`## 模块N`、`## 阶段N` 等自创章节层级打断编号连续性

---

## 9 步分析流程

### 第 1 步：快速概览

**目标：** 建立整体心智模型

识别：编程语言和版本、文件/项目规模、核心依赖、代码类型（算法/业务逻辑/框架等）

**大型项目（文件数 > 5）必须额外生成项目地图：**

```markdown
## 项目完整地图

### 完整目录树
[使用工具枚举所有文件，生成树状结构]

### 文件清单（分类）
| 类别 | 文件路径 | 行数 | 职责摘要 |
|------|---------|------|---------|
| 核心逻辑 | [路径] | [行数] | [职责] |
| 工具模块 | [路径] | [行数] | [职责] |
| 测试 | [路径] | [行数] | [职责] |
| 配置 | [路径] | [行数] | [职责] |

### 入口文件 + 核心调用链
```

**此步骤必须在分析任何具体代码之前完成，是防止遗漏信息的基础。**

---

### 第 2 步：背景与动机（精细询问）

**必须回答的 3 个 WHY：**
1. WHY 需要这段代码？（解决什么问题，不写会怎样）
2. WHY 选择这种技术方案？（替代方案 + 权衡）
3. WHY 这个时机/场景需要它？（应用场景 + 前后置条件）

**输出格式：**

```markdown
## 背景与动机分析

### 问题本质
**要解决的问题：** [一句话描述]
**WHY 需要解决：** [不解决的后果]

### 方案选择
**WHY 选择这个方案：** 优势 / 劣势 / 权衡
**替代方案对比：**
- 方案 A：[简述] - WHY 不选：[原因]
- 方案 B：[简述] - WHY 不选：[原因]

### 应用场景
**适用场景：** [描述] — **WHY 适用：** [原因]
**不适用场景：** [边界条件] — **WHY 不适用：** [原因]
```

---

### 第 3 步：概念网络构建

**目标：** 建立概念间的连接，而非孤立记忆

**必须包含：**
- 每个核心概念回答 3 个 WHY（是什么 / WHY 需要 / WHY 这样实现 / WHY 不用其他）
- 概念关系映射：依赖/对比/组合，每条关系说明 WHY
- 连接到已有知识：设计模式、算法理论、领域原则

**输出格式：**

```markdown
## 概念网络图

### 核心概念清单
**概念 N：[名称]**
- **是什么：** [简述]
- **WHY 需要：** [原因]
- **WHY 这样实现：** [原因]
- **WHY 不用其他方式：** [原因]

### 概念关系矩阵
| 关系类型 | 概念 A | 概念 B | WHY 这样关联 |
|---------|--------|--------|-------------|
| 依赖/顺序/对比 | [A] | [B] | [原因] |
```

---

### 第 4 步：算法与理论分析

**每个算法/理论必须包含：**
1. 时间/空间复杂度
2. WHY 选择这个算法（且复杂度可接受）
3. 什么时候会退化
4. 权威参考资料链接

**输出格式：**

```markdown
## 算法与理论分析

### 算法：[名称]
- **时间复杂度：** [O(...)]  **空间复杂度：** [O(...)]
- **WHY 选择：** [2-3 条理由]
- **WHY 复杂度可接受：** [说明]
- **WHY 不选其他：** [对比其他算法的理由]
- **退化场景：** [何时退化 + 如何规避]
- **参考：** [权威链接]
```

---

### 第 5 步：设计模式识别

**每个设计模式必须包含：**
1. 模式名称 + 应用位置
2. WHY 使用这个模式
3. 不用这个模式会怎样
4. 标准参考链接

**输出格式：**

```markdown
## 设计模式分析

### 模式 N：[模式名]
**应用位置：** [类/函数名]
**WHY 使用：** [2-3 条理由]
**WHY 不用会怎样：** [后果]
**潜在问题：** ⚠️ [已知局限]
**参考：** [Refactoring Guru 等链接]
```

---

### 第 6 步：关键代码深度解析（两阶段工作流）

本步骤是整个分析的核心，分两个阶段。

---

#### 阶段 6A：核心片段识别

**适用条件：** 文件数 > 5 或代码 > 500 行。小型/单文件代码跳过 6A，直接对全部代码执行 6B（1-3 个片段）。

**识别标准（按优先级）：**

| 优先级 | 片段类型 | 识别特征 |
|--------|----------|----------|
| ★★★ | 核心算法实现 | 复杂逻辑、循环嵌套、位运算 |
| ★★★ | 关键接口/抽象 | 系统边界处、被大量调用 |
| ★★☆ | 精妙设计 | 不常见实现方式、有趣权衡 |
| ★★☆ | 易错点集中区 | 边界处理、并发控制、内存管理 |
| ★☆☆ | 胶水代码 | 连接多模块的协调逻辑 |

**输出格式：**

```markdown
## 核心片段清单

| 编号 | 片段名称 | 所在文件:行号 | 优先级 | 识别理由 |
|------|----------|--------------|--------|----------|
| #1 | [函数名] | [文件:起止行] | ★★★ | [理由] |
| #2 | [函数名] | [文件:起止行] | ★★☆ | [理由] |

**跳过说明：**
- [文件]：[跳过原因，如：仅数据结构定义，无复杂逻辑]
```

**识别完成后，对每个片段单独执行阶段 6B。**

---

#### 阶段 6B：逐片段深度解读（6 节模板）

**对每个核心片段，严格按以下 6 节结构输出：**

**⚠️ 硬性红线（主流程同样适用）：**
- 任何一节不得出现"略"、"同上"、"详见上文"、"此处省略"
- N.3 必须贴出真实代码片段（30行以上），不能只描述逻辑
- 每个 WHY 至少 2 句话，禁止单句结论
- 每片段 6 节合计不得少于 1000 字

```markdown
### 片段 #N：[片段名称]

> 📍 **位置：** `文件路径:起止行号`
> 🎯 **优先级：** ★★★
> 💡 **一句话核心：** [用一句话概括这段代码的本质]

#### N.1 代码整体作用（≥150字）

[3~5 句话说明核心目标]

**它解决了什么问题？** 不用它会有什么后果？
**系统层次定位：** [业务逻辑 / 调度器 / 编译器前端 / IR 变换 / 等]
**角色与依赖：** 上游依赖什么？被下游如何使用？

#### N.2 核心逻辑分析（≥200字）

**执行流程：**
```
输入 → [步骤1] → [步骤2] → ... → 输出
                    ↓
              [条件分支A / 条件分支B]
```

**关键算法/数据结构：** [名称] — 选择理由（至少2句解释WHY）？

**核心状态变量：**
| 变量名 | 初始值 | 变化时机 | 终态 |
|--------|--------|----------|------|
| [变量] | [初值] | [时机] | [终态] |

**多执行路径（至少2条）：**
- **路径 A（正常）：** 触发条件 → 关键状态变化 → 结果
- **路径 B（异常/边界）：** 触发条件 → 关键状态变化 → 结果

#### N.3 逐行代码解释（≥300字，必须贴真实代码）

> **贯穿示例输入：** `[具体值]`

```[语言]
[贴出真实代码，不少于30行核心逻辑]

// 步骤 1: [操作描述]
[代码行]
// WHY: [理由，至少2句]
// 此时：[变量] = [值]

// 场景 1: [条件描述]
if [条件]:
    [代码]
    // WHY: [理由，至少2句]
```

注释风格规范：
- `# 场景 N: [描述]` / `// 场景 N: [描述]` — 标注条件分支（if/else/switch）
- `# 步骤 N: [描述]` / `// 步骤 N: [描述]` — 标注串行执行流程
- `# 此时: [变量] = [值]` — 追踪变量状态

#### N.4 关键设计点（≥200字）

| 设计维度 | 分析内容（每项不少于2句） |
|----------|----------|
| **实现选择** | 为什么采用这种方式？有哪些备选方案？WHY不选备选？ |
| **性能优化** | 内存、计算、并发方面的优化？量化说明（如有） |
| **编译器相关** | IR 变换/Pass 设计/调度策略？（不涉及则写"不涉及"） |
| **安全与健壮性** | 边界检查、错误处理、异常路径？ |
| **可扩展性** | 扩展点在哪里？如何扩展？ |
| **潜在问题** | 已知局限、隐患或可改进之处？ |

#### N.5 完整示例（三组对比，≥150字）

> 三个示例使用同一代码逻辑，仅改变输入，形成对比。

**示例 1 — 基础场景**
- **输入：** `[具体值]` → **执行过程：** [关键变量变化] → **输出：** `[结果]`

**示例 2 — 复杂/典型场景**
- **输入：** `[更复杂值]` → **关键差异：** [与示例 1 的差异] → **结果：** [输出]

**示例 3 — 边界或异常情况**
- **输入：** `[极值/空值/非法输入]` → **处理方式：** [是否有保护？崩溃还是降级？] → **结果及原因**

#### N.6 使用注意与改进建议（≥100字）

**使用此片段时需注意（≥2条，每条2句以上）：**
1. [注意点 1 + 不注意会怎样]
2. [注意点 2 + 不注意会怎样]

**可考虑的改进（≥1条）：**
- [改进方向：具体描述 + WHY 更好（不少于2句）]
```

---

### 第 6.5 步：测试用例反向理解（检测到测试文件时执行）

**目标：** 通过测试用例反向验证和深化对代码功能的理解。测试是最准确的"使用说明书"，覆盖边界条件和异常场景。

**检测测试文件的模式：**

| 语言 | 测试文件模式 | 常见目录 |
|------|-------------|---------|
| Python | `test_*.py`, `*_test.py` | `tests/`, `test/` |
| JavaScript/TypeScript | `*.test.ts`, `*.spec.ts` | `__tests__/` |
| Go | `*_test.go` | 与源码同目录 |
| Java | `*Test.java` | `src/test/java/` |
| C++ | `*_test.cpp` (gtest) | `test/`, `tests/` |
| MLIR/LLVM | `*.mlir` (测试文件) | `test/Dialect/*/` |

**输出格式：**

```markdown
## 测试用例分析

### 测试文件清单
| 测试文件/目录 | 测试的模块 | 测试用例数量 |
|--------------|-----------|-------------|
| [路径] | [模块] | [数量] |

### 功能覆盖矩阵
| 核心功能 | 主代码位置 | 测试覆盖 | 覆盖率评估 |
|---------|-----------|---------|-----------|
| [功能] | [位置] | ✅/⚠️/❌ | [评估] |

### 从测试中发现的边界条件
[选择 3-5 个最有价值的测试用例，说明它们揭示了哪些仅看代码容易遗漏的细节]

### 测试质量评估
- 正常流程：✅/⚠️/❌
- 边界输入：✅/⚠️/❌
- 异常输入：✅/⚠️/❌
- 并发场景：✅/⚠️/❌

### 测试质量建议
[如测试不足，提出具体改进建议]
```

---

### 第 7 步：应用迁移测试

**目标：** 检验概念能否迁移到不同场景，验证真实理解

**必须包含：** 至少 2 个不同领域的应用场景，每个场景说明：
- 不变的原理（核心思想）
- 需要修改的部分（具体代码/逻辑）
- WHY 这样迁移（连接到通用模式）

**输出格式：**

```markdown
## 应用迁移场景

### 场景 1：[原始场景] → [新场景]

**不变的原理：** [列出保持不变的核心思想]

**需要修改的部分：**
[代码对比，含 WHY 注释]

**学到的通用模式：** [提取可复用的抽象模式]

### 场景 2：[原始场景] → [新场景]
[同上结构]
```

---

### 第 8 步：依赖关系与使用示例

**每个依赖必须说明：** WHY 选择 + WHY 不用替代方案

**输出格式：**

```markdown
## 依赖关系分析

### 外部库
**[库名] (v[版本])**
- **用途：** [简述]
- **WHY 选择：** [2-3 条理由]
- **WHY 不用 [替代方案]：** [原因]

### 内部模块依赖
**[模块A] → [模块B]**
- **依赖原因：** [原因]
- **WHY 这样设计：** [设计原则]

## 完整使用示例
[完整可运行示例，含详细 WHY 注释]
```

---

### 第 9 步：质量验证清单

```markdown
## 质量验证清单

### 理解深度
- [ ] 每个核心概念都回答了 3 个 WHY（需要/实现/不用其他）
- [ ] 自我解释测试：不看代码能解释每个核心概念
- [ ] 概念连接：标注了依赖/对比/组合关系及 WHY

### 技术准确性
- [ ] 算法：复杂度 + WHY 选择 + WHY 可接受 + 参考资料
- [ ] 设计模式：模式名 + WHY 使用 + 不用会怎样
- [ ] 代码解析：逐行 WHY + 具体数据执行示例 + 易错点

### 实用性
- [ ] 应用迁移：至少 2 个场景，不变原理 + 修改部分
- [ ] 使用示例：代码完整 + WHY 注释 + 执行结果
- [ ] 改进建议：指出问题 + WHY 是问题 + 改进方案

### 最终"四能"测试
根据这份分析文档（不看原代码）：
1. ✅ 能否理解代码的设计思路？
2. ✅ 能否独立实现类似功能？
3. ✅ 能否应用到不同场景？
4. ✅ 能否向他人清晰解释？

**任何一项答"否"，说明分析不够深入，需要补充。**
```

---

## Deep Mode 并行处理详细流程（策略 B/C）

### 执行阶段

| 阶段 | 执行者 | 操作 | 输出 |
|-----|--------|------|-----|
| **1. 项目地图** | 主 Agent | 枚举所有文件，建立完整目录树和模块清单 | `项目地图.md` |
| **2. 框架准备** | 主 Agent | 基于项目地图，生成大纲、核心概念列表、章节到文件映射 | `00-框架.json` |
| **3. 任务分发** | 主 Agent | 为每个章节创建独立任务，附上具体文件路径列表 | 任务列表 |
| **4. 并行执行** | 子 Agents | 每个子 Agent 专注一个章节，读取指定文件深度生成 | `章节-N.md` |
| **5. 覆盖率校验** | 主 Agent | 对比项目地图，检查哪些文件/模块未被覆盖 | 覆盖率报告 |
| **6. 结果汇总** | 主 Agent | 合并所有章节，统一格式，写入最终文档 | `完整分析.md` |
| **7. 质量验证** | 主 Agent | 检查深度标准，补充薄弱部分 | 最终文档 |

### 子 Agent 任务模板

```markdown
# 子 Agent 任务：[章节名称]

## 上下文信息
- **代码名称：** [项目/代码名]
- **编程语言：** [语言]
- **核心概念：** [从主 Agent 传递的概念列表]
- **你负责的文件：** [明确列出具体文件路径]
- **其他模块摘要：** [简要说明其他模块职责，避免重复分析]

## 强制执行步骤
1. 用 Read 工具依次读取"你负责的文件"中的每一个文件
2. 确认文件内容后再开始分析（不能凭记忆或假设）
3. 分析内容必须引用实际代码行

## 特殊指令：如果你负责「关键代码解析」章节

必须执行两阶段工作流：

**阶段 1 — 核心片段识别（6A）：**
读取所有指定文件后，筛选 3-7 个最值得深度解读的片段，按优先级：
1. ★★★ 核心算法实现（复杂逻辑/循环嵌套/位运算）
2. ★★★ 关键接口（系统边界处/被大量调用）
3. ★★☆ 精妙设计（不常见实现/有趣权衡）
4. ★★☆ 易错点集中区（边界处理/并发控制/内存管理）
5. ★☆☆ 胶水代码（连接多模块的协调逻辑）

先输出「核心片段清单」：
| 编号 | 片段名称 | 所在文件:行号 | 优先级 | 识别理由 |

**阶段 2 — 逐片段深度解读（6B）：**
每个片段严格按 6 节输出，每节内容要求如下：

- **N.1 代码整体作用**（≥150字）：核心目标 + 不用它的后果 + 系统层次定位 + 角色依赖关系
- **N.2 核心逻辑分析**（≥200字）：文字执行流程图 + 算法/数据结构选型理由 + 核心状态变量表（变量名/初值/变化时机/终态）+ 至少2条执行路径说明
- **N.3 逐行代码解释**（≥300字，必须贴出实际代码）：先定义贯穿示例（具体输入值），每行或每块用「场景/步骤 + WHY + 此时变量值」注释；禁止只贴代码不注释，也禁止省略核心逻辑行
- **N.4 关键设计点**（≥200字）：用表格或条目覆盖：实现选择、性能优化、编译器相关（不涉及写"不涉及"）、安全健壮性、可扩展性、潜在问题
- **N.5 完整示例（三组对比）**（≥150字）：三组示例用同一代码逻辑，仅改变输入——基础/复杂/边界异常，每组写出输入→关键变量变化→输出
- **N.6 使用注意与改进建议**（≥100字）：≥2 个使用注意点 + ≥1 个可考虑的改进方向（含WHY更好）

**⚠️ 硬性红线：**
- 任何一节不得出现"略"、"同上"、"详见上文"、"此处省略"
- N.3 必须贴出真实代码片段（30行以上），不能只描述逻辑
- 每个 WHY 至少 2 句话，禁止单句结论

## 输出要求
- 本章节至少 [X] 字，每个 WHY 至少 2-3 句话
- 代码注释使用场景/步骤 + WHY 风格
- 提供权威参考链接
- 负责文件中每个公共函数/类都必须提及

## 深度自检
- [ ] 所有指定文件都已读取
- [ ] 所有子项都已覆盖（不能有"略"或"同上"）
- [ ] 每个 WHY 至少 2-3 句话
- [ ] 代码示例有完整注释
- [ ] 执行流程有具体数据追踪
- [ ] 「关键代码解析」已输出核心片段清单 + 每个片段的 6 节深度解读

直接输出 Markdown 格式，以 `## [章节名称]` 开头。
```

### 覆盖率校验格式

```markdown
## 覆盖率校验报告

### 文件覆盖情况
| 文件路径 | 是否被分析 | 分析章节 | 备注 |
|---------|-----------|---------|------|
| [路径] | ✅/❌ | [章节] | [说明] |

### 模块覆盖率
- 核心模块：X/Y 已覆盖（目标：100%）
- 工具模块：X/Y 已覆盖
- 测试文件：X/Y 已覆盖（目标：≥ 80%）

### 未覆盖内容处理
- 重要文件（核心业务）：立即补充分析
- 次要文件（配置/工具）：在依赖关系章节简要提及
- 测试文件：确认已在测试用例分析章节覆盖
```

### 策略 C：超大项目分层并行（文件数 > 20 或行数 > 10000）

1. **阶段 1 — 模块级扫描（串行）：** 将项目按目录/功能分为 3-8 个模块，为每个模块生成独立的模块摘要（子 Agent 并行）
2. **阶段 2 — 章节级分析（并行）：** 每个章节子 Agent 获取完整项目地图 + 负责模块摘要 + 需要深入阅读的关键文件列表
3. **阶段 3 — 汇总：** 同策略 B

---

## 深度自检清单（每章完成后检查）

```markdown
## 章节深度自检

### 内容完整性
- [ ] 所有子项已覆盖（不能有"略"、"详见上文"、"同上"）
- [ ] 每个 WHY 有具体解释（至少 2-3 句话）
- [ ] 代码示例有完整注释（场景/步骤 + WHY）
- [ ] 引用有来源链接

### 分析深度（按章节类型）
- **概念类：** 每个概念 3 个 WHY（需要/实现/不用其他）
- **算法类：** 复杂度 + WHY 选择 + WHY 可接受 + 退化场景
- **设计模式类：** 模式名 + WHY 使用 + 不用会怎样
- **代码解析类：** 核心片段清单（≥3 个，含文件:行号 + 优先级 + 理由）+ 每片段 6 节解读 + 贯穿示例 + 三组对比

### 各章最低字数与必含元素
| 章节 | 最低字数 | 必含元素 |
|-----|---------|---------|
| 1. 快速概览 | 200 | 语言、规模、依赖、类型 |
| 2. 背景与动机 | 400 | 问题本质、方案选择、应用场景 |
| 3. 核心概念 | 600 | 每概念 3 WHY、关系矩阵 |
| 4. 算法与理论 | 500 | 复杂度、WHY、参考资料 |
| 5. 设计模式 | 400 | 模式名、WHY、标准参考 |
| 6. 关键代码解析 | 每片段≥1000字（3片段起步即≥3000字）| 片段清单、每片段 6 节（含真实代码≥30行、三组对比示例）|
| 7. 测试用例分析 | 400 | 测试覆盖、边界条件、测试发现 |
| 8. 应用迁移 | 500 | ≥2 场景、不变原理、修改部分 |
| 9. 依赖关系 | 300 | 每依赖的 WHY、使用示例 |
| 10. 质量验证 | 200 | 验证清单、四能测试 |

**Deep Mode 文档应 ≥ 8000 字（含代码注释）**

**⚠️ 关键提醒：章节编号必须连续，禁止用 Phase/模块/阶段等词打断编号**
```

---

## Token 优化输出策略

| 模式 | 生成方式 | 文件数量 |
|-----|---------|---------|
| Quick | 单次 Write | 1 |
| Standard | 单次 Write | 1 |
| Deep ≤ 2000 行（策略 A） | 渐进式 Write（先框架，逐节填充） | 1-2 |
| Deep > 2000 行（策略 B/C） | 并行子 Agent → 汇总 Write | 多个临时章节 → 1 个最终文档 |

**核心原则：完整分析直接写入文件，对话中仅输出摘要。**

```markdown
## 分析完成

**模式：** [Quick/Standard/Deep]

**核心发现：**
- 代码实现了 [核心功能]
- 使用 [算法/模式] 解决 [问题]
- 关键优化点：[优化点]
- 潜在问题：[问题]

**完整文档：** `[代码名称]-深度分析.md`
```

**文件命名：**
- 单文件：`[代码名称]-深度分析.md`
- 多文件项目：`[项目名]-概述.md` + `[模块名]-分析.md`
- 大型项目：`work/项目地图.md` + `work/chapters/章节-N.md` + `[项目名]-完全掌握分析.md`

---

## 人性化写作要点

分析文档必须读起来像有经验的工程师在讲解，而非照本宣科堆砌术语。

**核心要求：**
1. **口语化引导，而非直接甩定义** — 用"这个函数是整个系统的门卫——每次登录都要经过它"而非"该函数负责执行身份验证流程"
2. **先说结论，再展开原因** — 用"用 bcrypt 而不用 MD5，根本原因是 MD5 太快了"而非"由于 bcrypt 具有自适应性哈希函数特性……"
3. **善用类比** — 讲锁机制比作图书馆阅览规则，讲缓存比作把常用的东西放桌上
4. **代码注释说人话** — 说明意图和原因，而非重复代码字面意思
5. **复杂概念分层解释** — 先一句话直觉理解，再补充技术细节
6. **顺手标注易错点** — 用 ⚠️ 标注常见误区

**禁止的写法：**
- 大段罗列术语不加解释
- "该函数实现了 X 功能"（读者已知）
- WHY 解释只有一句话
- 照抄官方文档措辞

**自检问题：** 一个刚入行的工程师能看懂吗？有没有让读者有"原来如此！"的感觉？