基于认知科学的源代码深度理解助手（中文改进版）。支持三种分析模式：Quick（快速概览）、Standard（标准理解）、Deep（深度掌握，大型项目自动使用并行处理）。结合精细询问法、自我解释测试和检索练习，帮助真正理解和掌握代码。
基于认知科学的源代码深度理解助手（中文改进版）。支持三种分析模式：Quick（快速概览）、Standard（标准理解）、Deep（深度掌握，大型项目自动使用并行处理）。结合精细询问法、自我解释测试和检索练习，帮助真正理解和掌握代码。
npx skills add https://github.com/notlate-cn/code-reader-skills --skill code-reader-v2-cn复制此命令并粘贴到 Claude Code 中以安装该技能
| 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分析文档必须读起来像有经验的工程师在讲解，而非照本宣科堆砌术语。
核心要求：
禁止的写法：
自检问题： 一个刚入行的工程师能看懂吗？有没有让读者有"原来如此！"的感觉？