Menu
基于认知科学的源代码深度理解助手（中文改进版）。支持三种分析模式：Quick（快速概览）、Standard（标准理解）、Deep（深度掌握，大型项目自动使用并行处理）。结合精细询问法、自我解释测试和检索练习，帮助真正理解和掌握代码。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | code-reader-v2-cn |
| description | 基于认知科学的源代码深度理解助手（中文改进版）。支持三种分析模式：Quick（快速概览）、Standard（标准理解）、Deep（深度掌握，大型项目自动使用并行处理）。结合精细询问法、自我解释测试和检索练习，帮助真正理解和掌握代码。 |
基于认知科学研究的专业代码分析工具，支持三种分析深度，确保真正理解代码，而非产生流畅幻觉。
核心原则：理解 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：分层并行（模块级扫描 → 章节级并行）
# [代码名称] 快速分析
## 1. 快速概览
- 编程语言和版本 / 代码规模和类型 / 核心依赖
## 2. 功能说明
- 主要功能是什么 (WHAT) + 简要 WHY
## 3. 核心算法/设计
- 复杂度（如有）+ 设计模式（如有）+ WHY 选择
## 4. 关键代码段
- 3-5 个核心代码段，每段简要说明作用
## 5. 依赖关系
- 外部库列表及用途
## 6. 快速使用示例
# [代码名称] 深度理解分析
## 理解验证状态
| 核心概念 | 自我解释 | 理解"为什么" | 应用迁移 | 状态 |
|---------|---------|-------------|---------|------|
| [概念] | ✅/❌ | ✅/⚠️/❌ | ✅/❌ | [状态] |
## 1. 快速概览
## 2. 背景与动机（3 个 WHY）
## 3. 核心概念说明（每个概念 2-3 个 WHY）
## 4. 算法与理论（复杂度 + WHY + 参考）
## 5. 设计模式（WHY 使用 + 不用会怎样）
## 6. 关键代码深度解析（见第 6 步）
## 7. 依赖关系与使用示例（含 WHY 注释）
完整章节结构（严格按此编号，禁止引入 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 等自创章节层级打断编号连续性目标： 建立整体心智模型
识别：编程语言和版本、文件/项目规模、核心依赖、代码类型（算法/业务逻辑/框架等）
大型项目（文件数 > 5）必须额外生成项目地图：
## 项目完整地图
### 完整目录树
[使用工具枚举所有文件，生成树状结构]
### 文件清单（分类）
| 类别 | 文件路径 | 行数 | 职责摘要 |
|------|---------|------|---------|
| 核心逻辑 | [路径] | [行数] | [职责] |
| 工具模块 | [路径] | [行数] | [职责] |
| 测试 | [路径] | [行数] | [职责] |
| 配置 | [路径] | [行数] | [职责] |
### 入口文件 + 核心调用链
此步骤必须在分析任何具体代码之前完成，是防止遗漏信息的基础。
必须回答的 3 个 WHY：
输出格式：
## 背景与动机分析
### 问题本质
**要解决的问题：** [一句话描述]
**WHY 需要解决：** [不解决的后果]
### 方案选择
**WHY 选择这个方案：** 优势 / 劣势 / 权衡
**替代方案对比：**
- 方案 A：[简述] - WHY 不选：[原因]
- 方案 B：[简述] - WHY 不选：[原因]
### 应用场景
**适用场景：** [描述] — **WHY 适用：** [原因]
**不适用场景：** [边界条件] — **WHY 不适用：** [原因]
目标： 建立概念间的连接，而非孤立记忆
必须包含：
输出格式：
## 概念网络图
### 核心概念清单
**概念 N：[名称]**
- **是什么：** [简述]
- **WHY 需要：** [原因]
- **WHY 这样实现：** [原因]
- **WHY 不用其他方式：** [原因]
### 概念关系矩阵
| 关系类型 | 概念 A | 概念 B | WHY 这样关联 |
|---------|--------|--------|-------------|
| 依赖/顺序/对比 | [A] | [B] | [原因] |
每个算法/理论必须包含：
输出格式：
## 算法与理论分析
### 算法：[名称]
- **时间复杂度：** [O(...)] **空间复杂度：** [O(...)]
- **WHY 选择：** [2-3 条理由]
- **WHY 复杂度可接受：** [说明]
- **WHY 不选其他：** [对比其他算法的理由]
- **退化场景：** [何时退化 + 如何规避]
- **参考：** [权威链接]
每个设计模式必须包含：
输出格式：
## 设计模式分析
### 模式 N：[模式名]
**应用位置：** [类/函数名]
**WHY 使用：** [2-3 条理由]
**WHY 不用会怎样：** [后果]
**潜在问题：** ⚠️ [已知局限]
**参考：** [Refactoring Guru 等链接]
本步骤是整个分析的核心，分两个阶段。
适用条件： 文件数 > 5 或代码 > 500 行。小型/单文件代码跳过 6A，直接对全部代码执行 6B（1-3 个片段）。
识别标准（按优先级）：
| 优先级 | 片段类型 | 识别特征 |
|---|---|---|
| ★★★ | 核心算法实现 | 复杂逻辑、循环嵌套、位运算 |
| ★★★ | 关键接口/抽象 | 系统边界处、被大量调用 |
| ★★☆ | 精妙设计 | 不常见实现方式、有趣权衡 |
| ★★☆ | 易错点集中区 | 边界处理、并发控制、内存管理 |
| ★☆☆ | 胶水代码 | 连接多模块的协调逻辑 |
输出格式：
## 核心片段清单
| 编号 | 片段名称 | 所在文件:行号 | 优先级 | 识别理由 |
|------|----------|--------------|--------|----------|
| #1 | [函数名] | [文件:起止行] | ★★★ | [理由] |
| #2 | [函数名] | [文件:起止行] | ★★☆ | [理由] |
**跳过说明：**
- [文件]：[跳过原因，如：仅数据结构定义，无复杂逻辑]
识别完成后，对每个片段单独执行阶段 6B。
对每个核心片段，严格按以下 6 节结构输出：
⚠️ 硬性红线（主流程同样适用）：
### 片段 #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: [描述] — 标注串行执行流程# 此时: [变量] = [值] — 追踪变量状态| 设计维度 | 分析内容（每项不少于2句） |
|---|---|
| 实现选择 | 为什么采用这种方式？有哪些备选方案？WHY不选备选？ |
| 性能优化 | 内存、计算、并发方面的优化？量化说明（如有） |
| 编译器相关 | IR 变换/Pass 设计/调度策略？（不涉及则写"不涉及"） |
| 安全与健壮性 | 边界检查、错误处理、异常路径？ |
| 可扩展性 | 扩展点在哪里？如何扩展？ |
| 潜在问题 | 已知局限、隐患或可改进之处？ |
三个示例使用同一代码逻辑，仅改变输入，形成对比。
示例 1 — 基础场景
[具体值] → 执行过程： [关键变量变化] → 输出： [结果]示例 2 — 复杂/典型场景
[更复杂值] → 关键差异： [与示例 1 的差异] → 结果： [输出]示例 3 — 边界或异常情况
[极值/空值/非法输入] → 处理方式： [是否有保护？崩溃还是降级？] → 结果及原因使用此片段时需注意（≥2条，每条2句以上）：
可考虑的改进（≥1条）：
---
### 第 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 个最有价值的测试用例，说明它们揭示了哪些仅看代码容易遗漏的细节]
### 测试质量评估
- 正常流程：✅/⚠️/❌
- 边界输入：✅/⚠️/❌
- 异常输入：✅/⚠️/❌
- 并发场景：✅/⚠️/❌
### 测试质量建议
[如测试不足，提出具体改进建议]
目标： 检验概念能否迁移到不同场景，验证真实理解
必须包含： 至少 2 个不同领域的应用场景，每个场景说明：
输出格式：
## 应用迁移场景
### 场景 1：[原始场景] → [新场景]
**不变的原理：** [列出保持不变的核心思想]
**需要修改的部分：**
[代码对比，含 WHY 注释]
**学到的通用模式：** [提取可复用的抽象模式]
### 场景 2：[原始场景] → [新场景]
[同上结构]
每个依赖必须说明： WHY 选择 + WHY 不用替代方案
输出格式：
## 依赖关系分析
### 外部库
**[库名] (v[版本])**
- **用途：** [简述]
- **WHY 选择：** [2-3 条理由]
- **WHY 不用 [替代方案]：** [原因]
### 内部模块依赖
**[模块A] → [模块B]**
- **依赖原因：** [原因]
- **WHY 这样设计：** [设计原则]
## 完整使用示例
[完整可运行示例，含详细 WHY 注释]
## 质量验证清单
### 理解深度
- [ ] 每个核心概念都回答了 3 个 WHY（需要/实现/不用其他）
- [ ] 自我解释测试：不看代码能解释每个核心概念
- [ ] 概念连接：标注了依赖/对比/组合关系及 WHY
### 技术准确性
- [ ] 算法：复杂度 + WHY 选择 + WHY 可接受 + 参考资料
- [ ] 设计模式：模式名 + WHY 使用 + 不用会怎样
- [ ] 代码解析：逐行 WHY + 具体数据执行示例 + 易错点
### 实用性
- [ ] 应用迁移：至少 2 个场景，不变原理 + 修改部分
- [ ] 使用示例：代码完整 + WHY 注释 + 执行结果
- [ ] 改进建议：指出问题 + WHY 是问题 + 改进方案
### 最终"四能"测试
根据这份分析文档（不看原代码）：
1. ✅ 能否理解代码的设计思路？
2. ✅ 能否独立实现类似功能？
3. ✅ 能否应用到不同场景？
4. ✅ 能否向他人清晰解释？
**任何一项答"否"，说明分析不够深入，需要补充。**
| 阶段 | 执行者 | 操作 | 输出 |
|---|---|---|---|
| 1. 项目地图 | 主 Agent | 枚举所有文件，建立完整目录树和模块清单 | 项目地图.md |
| 2. 框架准备 | 主 Agent | 基于项目地图，生成大纲、核心概念列表、章节到文件映射 | 00-框架.json |
| 3. 任务分发 | 主 Agent | 为每个章节创建独立任务，附上具体文件路径列表 | 任务列表 |
| 4. 并行执行 | 子 Agents | 每个子 Agent 专注一个章节，读取指定文件深度生成 | 章节-N.md |
| 5. 覆盖率校验 | 主 Agent | 对比项目地图，检查哪些文件/模块未被覆盖 | 覆盖率报告 |
| 6. 结果汇总 | 主 Agent | 合并所有章节，统一格式，写入最终文档 | 完整分析.md |
| 7. 质量验证 | 主 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%）
### 未覆盖内容处理
- 重要文件（核心业务）：立即补充分析
- 次要文件（配置/工具）：在依赖关系章节简要提及
- 测试文件：确认已在测试用例分析章节覆盖
## 章节深度自检
### 内容完整性
- [ ] 所有子项已覆盖（不能有"略"、"详见上文"、"同上"）
- [ ] 每个 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/模块/阶段等词打断编号**
| 模式 | 生成方式 | 文件数量 |
|---|---|---|
| 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 + [模块名]-分析.mdwork/项目地图.md + work/chapters/章节-N.md + [项目名]-完全掌握分析.md分析文档必须读起来像有经验的工程师在讲解，而非照本宣科堆砌术语。
核心要求：
禁止的写法：
自检问题： 一个刚入行的工程师能看懂吗？有没有让读者有"原来如此！"的感觉？