code-reader-v2-cn

# 源代码深度理解分析器 v2.3 (中文版) 基于认知科学研究的专业代码分析工具，支持三种分析深度，确保真正理解代码，而非产生流畅幻觉。 **核心原则：理解 WHY，而非只知道 WHAT。像有经验的工程师给朋友讲解，而非照本宣科堆砌术语。** 研究支撑：[Dunlosky et al.](https://www.aft.org/ae/fall2013/dunlosky) · [Chi et al.](https://onlinelibrary.wiley.com/doi/10.1207/s15516709cog1803_3) · [Karpicke & Roediger](https://science.sciencemag.org/content/319/5865/966) --- ## 三种分析模式 | 用户意图 | 模式 | 触发词示例 | 分析时长 | |---------|------|-----------|---------| | 快速浏览/代码审查 | 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 分钟） ```markdown # [代码名称] 快速分析 ## 1. 快速概览 - 编程语言和版本 / 代码规模和类型 / 核心依赖 ## 2. 功能说明 - 主要功能是什么 (WHAT) + 简要 WHY ## 3. 核心算法/设计 - 复杂度（如有）+ 设计模式（如有）+ WHY 选择 ## 4. 关键代码段 - 3-5 个核心代码段，每段简要说明作用 ## 5. 依赖关系 - 外部库列表及用途 ## 6. 快速使用示例 ``` ### Standard Mode（15-20 分钟）⭐ ```markdown # [代码名称] 深度理解分析 ## 理解验证状态 | 核心概念 | 自我解释 | 理解"为什么" | 应用迁移 | 状态 | |---------|---------|-------------|---------|------| | [概念] | ✅/❌ | ✅/⚠️/❌ | ✅/❌ | [状态] | ## 1. 快速概览 ## 2. 背景与动机（3 个 WHY） ## 3. 核心概念说明（每个概念 2-3 个 WHY） ## 4. 算法与理论（复杂度 + WHY + 参考） ## 5. 设计模式（WHY 使用 + 不用会怎样） ## 6. 关键代码深度解析（见第 6 步） ## 7. 依赖关系与使用示例（含 WHY 注释） ``` ### Deep Mode（30+ 分钟） **完整章节结构（严格按此编号，禁止引入 Phase/Part/Section 等额外层级）：** ```markdown # [代码名称] 深度理解分析 ## 理解验证状态 ## 项目完整地图（文件数 > 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）必须额外生成项目地图：** ```markdown ## 项目完整地图 ### 完整目录树 [使用工具枚举所有文件，生成树状结构] ### 文件清单（分类） | 类别 | 文件路径 | 行数 | 职责摘要 | |------|---------|------|---------| | 核心逻辑 | [路径] | [行数] | [职责] | | 工具模块 | [路径] | [行数] | [职责] | | 测试 | [路径] | [行数] | [职责] | | 配置 | [路径] | [行数] | [职责] | ### 入口文件 + 核心调用链 ``` **此步骤必须在分析任何具体代码之前完成，是防止遗漏信息的基础。** --- ### 第 2 步：背景与动机（精细询问） **必须回答的 3 个 WHY：** 1. WHY 需要这段代码？（解决什么问题，不写会怎样） 2. WHY 选择这种技术方案？（替代方案 + 权衡） 3. WHY 这个时机/场景需要它？（应用场景 + 前后置条件） **输出格式：** ```markdown ## 背景与动机分析 ### 问题本质 **要解决的问题：** [一句话描述] **WHY 需要解决：** [不解决的后果] ### 方案选择 **WHY 选择这个方案：** 优势 / 劣势 / 权衡 **替代方案对比：** - 方案 A：[简述] - WHY 不选：[原因] - 方案 B：[简述] - WHY 不选：[原因] ### 应用场景 **适用场景：** [描述] — **WHY 适用：** [原因] **不适用场景：** [边界条件] — **WHY 不适用：** [原因] ``` --- ### 第 3 步：概念网络构建 **目标：** 建立概念间的连接，而非孤立记忆 **必须包含：** - 每个核心概念回答 3 个 WHY（是什么 / WHY 需要 / WHY 这样实现 / WHY 不用其他） - 概念关系映射：依赖/对比/组合，每条关系说明 WHY - 连接到已有知识：设计模式、算法理论、领域原则 **输出格式：** ```markdown ## 概念网络图 ### 核心概念清单 **概念 N：[名称]** - **是什么：** [简述] - **WHY 需要：** [原因] - **WHY 这样实现：** [原因] - **WHY 不用其他方式：** [原因] ### 概念关系矩阵 | 关系类型 | 概念 A | 概念 B | WHY 这样关联 | |---------|--------|--------|-------------| | 依赖/顺序/对比 | [A] | [B] | [原因] | ``` --- ### 第 4 步：算法与理论分析 **每个算法/理论必须包含：** 1. 时间/空间复杂度 2. WHY 选择这个算法（且复杂度可接受） 3. 什么时候会退化 4. 权威参考资料链接 **输出格式：** ```markdown ## 算法与理论分析 ### 算法：[名称] - **时间复杂度：** [O(...)] **空间复杂度：** [O(...)] - **WHY 选择：** [2-3 条理由] - **WHY 复杂度可接受：** [说明] - **WHY 不选其他：** [对比其他算法的理由] - **退化场景：** [何时退化 + 如何规避] - **参考：** [权威链接] ``` --- ### 第 5 步：设计模式识别 **每个设计模式必须包含：** 1. 模式名称 + 应用位置 2. WHY 使用这个模式 3. 不用这个模式会怎样 4. 标准参考链接 **输出格式：** ```markdown ## 设计模式分析 ### 模式 N：[模式名] **应用位置：** [类/函数名] **WHY 使用：** [2-3 条理由] **WHY 不用会怎样：** [后果] **潜在问题：** ⚠️ [已知局限] **参考：** [Refactoring Guru 等链接] ``` --- ### 第 6 步：关键代码深度解析（两阶段工作流） 本步骤是整个分析的核心，分两个阶段。 --- #### 阶段 6A：核心片段识别 **适用条件：** 文件数 > 5 或代码 > 500 行。小型/单文件代码跳过 6A，直接对全部代码执行 6B（1-3 个片段）。 **识别标准（按优先级）：** | 优先级 | 片段类型 | 识别特征 | |--------|----------|----------| | ★★★ | 核心算法实现 | 复杂逻辑、循环嵌套、位运算 | | ★★★ | 关键接口/抽象 | 系统边界处、被大量调用 | | ★★☆ | 精妙设计 | 不常见实现方式、有趣权衡 | | ★★☆ | 易错点集中区 | 边界处理、并发控制、内存管理 | | ★☆☆ | 胶水代码 | 连接多模块的协调逻辑 | **输出格式：** ```markdown ## 核心片段清单 | 编号 | 片段名称 | 所在文件:行号 | 优先级 | 识别理由 | |------|----------|--------------|--------|----------| | #1 | [函数名] | [文件:起止行] | ★★★ | [理由] | | #2 | [函数名] | [文件:起止行] | ★★☆ | [理由] | **跳过说明：** - [文件]：[跳过原因，如：仅数据结构定义，无复杂逻辑] ``` **识别完成后，对每个片段单独执行阶段 6B。** --- #### 阶段 6B：逐片段深度解读（6 节模板） **对每个核心片段，严格按以下 6 节结构输出：** **⚠️ 硬性红线（主流程同样适用）：** - 任何一节不得出现"略"、"同上"、"详见上文"、"此处省略" - N.3 必须贴出真实代码片段（30行以上），不能只描述逻辑 - 每个 WHY 至少 2 句话，禁止单句结论 - 每片段 6 节合计不得少于 1000 字 ```markdown ### 片段 #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字） | 设计维度 | 分析内容（每项不少于2句） | |----------|----------| | **实现选择** | 为什么采用这种方式？有哪些备选方案？WHY不选备选？ | | **性能优化** | 内存、计算、并发方面的优化？量化说明（如有） | | **编译器相关** | IR 变换/Pass 设计/调度策略？（不涉及则写"不涉及"） | | **安全与健壮性** | 边界检查、错误处理、异常路径？ | | **可扩展性** | 扩展点在哪里？如何扩展？ | | **潜在问题** | 已知局限、隐患或可改进之处？ | #### N.5 完整示例（三组对比，≥150字） > 三个示例使用同一代码逻辑，仅改变输入，形成对比。 **示例 1 — 基础场景** - **输入：** `[具体值]` → **执行过程：** [关键变量变化] → **输出：** `[结果]` **示例 2 — 复杂/典型场景**