源代码深度理解分析器 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：

• WHY 需要这段代码？（解决什么问题，不写会怎样）

• WHY 选择这种技术方案？（替代方案 + 权衡）

• WHY 这个时机/场景需要它？（应用场景 + 前后置条件）

输出格式：

背景与动机分析

问题本质

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

方案选择

WHY 选择这个方案： 优势 / 劣势 / 权衡 替代方案对比：

• 方案 A：[简述] - WHY 不选：[原因]
• 方案 B：[简述] - WHY 不选：[原因]

应用场景

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

第 3 步：概念网络构建

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

必须包含：

• 每个核心概念回答 3 个 WHY（是什么 / WHY 需要 / WHY 这样实现 / WHY 不用其他）

• 概念关系映射：依赖/对比/组合，每条关系说明 WHY

• 连接到已有知识：设计模式、算法理论、领域原则

输出格式：

概念网络图

核心概念清单

概念 N：[名称]

• 是什么： [简述]
• WHY 需要： [原因]
• WHY 这样实现： [原因]
• WHY 不用其他方式： [原因]

概念关系矩阵

第 4 步：算法与理论分析

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

• 时间/空间复杂度

• WHY 选择这个算法（且复杂度可接受）

• 什么时候会退化

• 权威参考资料链接

输出格式：

算法与理论分析

算法：[名称]

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

第 5 步：设计模式识别

每个设计模式必须包含：

• 模式名称 + 应用位置

• WHY 使用这个模式

• 不用这个模式会怎样

• 标准参考链接

输出格式：

设计模式分析

模式 N：[模式名]

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

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

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

阶段 6A：核心片段识别

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

识别标准（按优先级）：

优先级 片段类型 识别特征

★★★ 核心算法实现 复杂逻辑、循环嵌套、位运算

★★★ 关键接口/抽象 系统边界处、被大量调用

★★☆ 精妙设计 不常见实现方式、有趣权衡

★★☆ 易错点集中区 边界处理、并发控制、内存管理

★☆☆ 胶水代码 连接多模块的协调逻辑

输出格式：

核心片段清单

跳过说明：

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

识别完成后，对每个片段单独执行阶段 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]

- [注意点 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 — 模块级扫描（串行）： 将项目按目录/功能分为 3-8 个模块，为每个模块生成独立的模块摘要（子 Agent 并行）

- 阶段 2 — 章节级分析（并行）： 每个章节子 Agent 获取完整项目地图 + 负责模块摘要 + 需要深入阅读的关键文件列表

- 阶段 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

人性化写作要点

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

核心要求：

- 口语化引导，而非直接甩定义 — 用"这个函数是整个系统的门卫——每次登录都要经过它"而非"该函数负责执行身份验证流程"

- 先说结论，再展开原因 — 用"用 bcrypt 而不用 MD5，根本原因是 MD5 太快了"而非"由于 bcrypt 具有自适应性哈希函数特性……"

- 善用类比 — 讲锁机制比作图书馆阅览规则，讲缓存比作把常用的东西放桌上

- 代码注释说人话 — 说明意图和原因，而非重复代码字面意思

- 复杂概念分层解释 — 先一句话直觉理解，再补充技术细节

- 顺手标注易错点 — 用 ⚠️ 标注常见误区

禁止的写法：

- 大段罗列术语不加解释

- "该函数实现了 X 功能"（读者已知）

- WHY 解释只有一句话

- 照抄官方文档措辞

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