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

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

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

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

---

三种分析模式

用户意图	模式	触发词示例	分析时长
快速浏览/代码审查	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 分钟）

# [代码名称] 快速分析

## 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+ 分钟）

在 Standard 基础上额外包含：

• ## 3+. 概念网络图：核心概念清单（每个 3 WHY）+ 概念关系矩阵
• ## 6+. 关键代码深度解析：6A 核心片段清单 + 6B 每片段 6 节解读
• ## 8. 测试用例分析（如代码包含测试）
• ## 9. 应用迁移场景（至少 2 个）
• ## 10. 依赖关系与使用示例
• ## 11. 质量验证清单
• ## 覆盖率摘要（并行模式时）

---

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：[片段名称]

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

### N.1 代码整体作用

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

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

### N.2 核心逻辑分析

**执行流程：**

输入 → [步骤1] → [步骤2] → ... → 输出 ↓ [条件分支A / 条件分支B]

**关键算法/数据结构：** [名称] — 选择理由？

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

**多执行路径：**
- **路径 A（正常）：** 触发条件 → 结果
- **路径 B（异常/边界）：** 触发条件 → 结果

### N.3 逐行代码解释

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

```[语言]
[原始代码，附场景/步骤注释 + 变量值追踪]

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

// 场景 1: [条件描述]
if [条件]:
    [代码]
    // WHY: [理由]

注释风格规范：

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

N.4 关键设计点

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

N.5 完整示例（三组对比）

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

示例 1 — 基础场景

• 输入： [具体值] → 执行过程： [关键变量变化] → 输出： [结果]

示例 2 — 复杂/典型场景

• 输入： [更复杂值] → 关键差异： [与示例 1 的差异] → 结果： [输出]

示例 3 — 边界或异常情况

• 输入： [极值/空值/非法输入] → 处理方式： [是否有保护？崩溃还是降级？] → 结果及原因

N.6 使用注意与改进建议

使用此片段时需注意：

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）

执行阶段

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

子 Agent 任务模板

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

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

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

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

必须执行两阶段工作流：

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

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

**阶段 2 — 逐片段深度解读（6B）：**
每个片段严格按 6 节输出：
- N.1 代码整体作用（核心目标 + 解决问题 + 系统层次 + 角色依赖）
- N.2 核心逻辑分析（执行流程 + 算法/数据结构选型 + 状态变量表 + 多路径说明）
- N.3 逐行代码解释（先定义贯穿示例，逐行用「场景/步骤 + WHY + 此时变量值」注释）
- N.4 关键设计点（实现选择/性能优化/编译器相关/安全健壮性/可扩展性/潜在问题）
- N.5 完整示例（同一代码逻辑，3 组不同输入对比：基础/复杂/边界异常）
- N.6 使用注意与改进建议（2~3 个注意点 + 可选改进方向）

## 输出要求
- 本章节至少 [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. 关键代码解析 | 800 | 片段清单、6 节解读、示例追踪 |
| 7. 测试用例分析 | 400 | 测试覆盖、边界条件、测试发现 |
| 8. 应用迁移 | 500 | ≥2 场景、不变原理、修改部分 |
| 9. 依赖关系 | 300 | 每依赖的 WHY、使用示例 |
| 10. 质量验证 | 200 | 验证清单、四能测试 |

**Deep Mode 文档应 ≥ 4300 字**

---

Token 优化输出策略

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

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

## 分析完成

**模式：** [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 解释只有一句话
• 照抄官方文档措辞

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