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

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

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

研究支撑：Dunlosky et al. · Chi et al. · Karpicke & Roediger

三种分析模式

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

Deep Mode 内部策略选择：

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

分析输出结构

Quick Mode（5-10 分钟）

# [代码名称] 快速分析

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

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

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

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

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

## 6. 快速使用示例

Standard Mode（15-20 分钟）⭐

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

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

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

Deep Mode（30+ 分钟）

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

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

## 理解验证状态
## 项目完整地图（文件数 > 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）必须额外生成项目地图：

## 项目完整地图

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

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

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

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

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

必须回答的 3 个 WHY：

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

输出格式：

## 背景与动机分析

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

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

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

第 3 步：概念网络构建

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

必须包含：

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

输出格式：

## 概念网络图

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

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

第 4 步：算法与理论分析

每个算法/理论必须包含：

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

输出格式：

## 算法与理论分析

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

第 5 步：设计模式识别

每个设计模式必须包含：

1. 模式名称 + 应用位置
2. WHY 使用这个模式
3. 不用这个模式会怎样
4. 标准参考链接

输出格式：

## 设计模式分析

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

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

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

阶段 6A：核心片段识别

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

识别标准（按优先级）：

输出格式：

## 核心片段清单

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

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

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

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

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

⚠️ 硬性红线（主流程同样适用）：

• 任何一节不得出现"略"、"同上"、"详见上文"、"此处省略"
• N.3 必须贴出真实代码片段（30行以上），不能只描述逻辑
• 每个 WHY 至少 2 句话，禁止单句结论
• 每片段 6 节合计不得少于 1000 字

### 片段 #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字）

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 这样迁移（连接到通用模式）

输出格式：

## 应用迁移场景

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

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

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

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

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

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

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

输出格式：

## 依赖关系分析

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

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

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

第 9 步：质量验证清单

## 质量验证清单

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

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

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

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

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

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

执行阶段

子 Agent 任务模板

# 子 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 格式，以 `## [章节名称]` 开头。

覆盖率校验格式

## 覆盖率校验报告

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

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

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

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

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

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

## 章节深度自检

### 内容完整性
- [ ] 所有子项已覆盖（不能有"略"、"详见上文"、"同上"）
- [ ] 每个 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/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 解释只有一句话
• 照抄官方文档措辞

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