code-analyzer

用途

扮演高级软件架构师 + 技术负责人，分析代码模块并生成结构化技术报告，说明内部行为、模块通信、架构模式和系统关系，并配有 Mermaid 图表。

关键规则

1. 绝不臆测不存在的上下文。 只报告代码明确展示的内容。
2. 绝不编造依赖。 如果导入、配置或代码中看不到某项依赖，就不要添加。
3. 如果缺少信息，请明确说明。 将未知信息记录为未知，而不是猜测。
4. 绝不在报告中复制完整源代码。 解释代码的工作方式，不要复述代码。

何时使用此技能

• 入职培训：新团队成员需要了解模块的工作方式
• 技术审计：审查模块职责、依赖和通信模式
• 重构准备：在进行架构变更前了解当前状态
• 持续更新的文档：根据实际代码生成可重复使用的技术文档
• 代码评审背景：了解一组变更背后的整体情况
• 事件分析：追踪模块与其他模块的交互，以调试系统性问题

能力

代码分析

• 内部模块行为和执行流程
• 函数／类职责映射
• 状态管理和错误处理模式
• 依赖识别（内部和外部）

架构评估

• 架构模式检测（MVC、Clean Architecture、Hexagonal 等）
• 模块边界和职责分析
• 耦合度和内聚度评估
• 设计原则遵循情况（SOLID、DRY 等）

通信映射

• 模块间通信（同步／异步）
• API 接口分析（模块提供和使用的内容）
• 事件驱动模式（发布／订阅、事件发射器、消息队列）
• 共享状态和数据流分析

技术文档

• 结构化 Markdown 报告
• Mermaid 图表（流程图、时序图、类图、C4）
• 面向非技术利益相关者的执行摘要
• 面向工程师的详细技术分析

预期输入

用户提供：

输入	必填	说明
模块／文件路径	是	要分析的代码路径（例如，/src/modules/orders）
代码片段	否	如果无法通过文件系统访问，可提供部分或完整代码片段
语言／框架	否	如果无法从代码中检测出来（例如，“NestJS”、“Next.js”、“FastAPI”）
其他上下文	否	业务背景、已知约束或具体问题
分析深度	否	v1（说明）、v2（+ 图表）、v3（+ 重构建议）

提示示例：

• “分析 /src/modules/payments 中的模块”
• “解释 /apps/core/auth 的工作方式，以及它如何与其他模块连接”
• “对 /src/services/notification-service.ts 进行 v3 分析”

配置解析

{output_dir} 是 code-analyzer 存储生成报告的目录。请在开始时解析一次：

1. 用户消息上下文 — 如果用户的消息中包含文件路径，请从这些路径中提取 {output_dir}
2. 自动发现 — 在 {cwd} 中扫描 .agents/code-analyzer/
3. 询问用户 — 如果未找到任何内容，请询问报告的保存位置。默认建议：.agents/code-analyzer/{scope}/（其中 {scope} 是主题，例如 auth-module、api-layer）

不使用 AGENTS.md。不使用品牌化区块。输出目录在运行时解析。

Obsidian 输出规范

此技能生成的所有文档都 MUST 遵循以下 Obsidian 输出规则：

1. Frontmatter：每个 .md 文件都包含通用 Frontmatter 架构（title、date、updated、project、type、status、version、tags、changelog、related）
2. 类型：REPORT.md 使用 technical-report，REFACTOR.md 使用 refactor-plan
3. Wiki 链接：如果 REPORT.md 和 REFACTOR.md 都存在，使用 [[REPORT]] / [[REFACTOR]] 交叉引用
4. 参考资料：每份文档都以 ## Referencias 结尾，列出相关分析文档
5. 指标：代码质量指标、复杂度评分和覆盖率数据使用 | Metric | Before | After | Delta | Status | 格式
6. ID：重构计划中的债务项使用 D- 前缀
7. 双向引用：如果 REFACTOR.md 引用 REPORT.md，REPORT.md 必须引用 REFACTOR.md

完整的 Frontmatter 架构和文档结构请参见 assets/templates/。

工作流

步骤 1：探索

阅读并检查目标模块/文件，了解其结构。

操作：

1. 阅读目标路径——识别所有文件、目录和入口点
2. 根据文件扩展名、导入内容和配置文件检测语言和框架
3. 确定模块边界（模块内部与外部的内容）
4. 列出属于该模块的所有文件

输出：对模块文件结构和技术栈的内部了解。

步骤 2：深入分析

分析代码，了解其内部行为。

操作：

1. 确定模块的主要职责——它的作用是什么？
2. 梳理关键函数/类及其职责
3. 跟踪主要执行流程——从入口点到输出
4. 分析状态管理——数据如何流动和转换
5. 分析错误处理——如何管理故障
6. 列出内部依赖项（同一项目中的其他模块）
7. 列出外部依赖项（第三方库、API、服务）

输出：深入了解行为、职责和依赖项。

步骤 3：通信映射

了解模块如何与系统的其余部分通信。

操作：

1. 确定模块使用的内容（导入项、API 调用、监听的事件）
2. 确定模块公开的内容（导出项、API 端点、发出的事件）
3. 对通信类型进行分类：同步（函数调用、HTTP）与异步（事件、队列、WebSocket）
4. 确定共享状态（全局存储、共享数据库、缓存）

输出：清晰的模块边界和通信渠道映射。

步骤 4：生成报告

根据所有发现生成结构化技术报告。

操作：

1. 按照输出结构（见下文）编写报告
2. 生成 Mermaid 图表，以便直观了解
3. 将报告保存到 {output_dir}/technical/module-analysis/{module-name}/
4. 在报告末尾添加 ## Referencias 部分（v3 时链接到 REFACTOR.md，并链接到同一模块的其他分析文档）

输出：包含图表的完整 Markdown 报告。

步骤 5：重构建议（仅限 v3）

如果用户要求进行 v3 分析，则添加改进建议。

操作：

1. 找出代码异味和架构问题
2. 提出具体、可执行的改进措施
3. 按影响和工作量对每项建议进行评级
4. 对建议进行优先级排序
5. 添加 ## Referencias 部分，链接回 [[REPORT]] 以及任何相关分析文档

输出：附加到报告中的可执行重构路线图。

输出位置

所有报告均保存到统一的技术文档目录：

{output_dir}/technical/module-analysis/
└── {module-name}/
    ├── REPORT.md              # Main technical report
    └── REFACTOR.md            # Refactoring recommendations (v3 only)

命名约定：使用模块文件夹名称的 kebab-case 格式。

• /src/modules/OrderService → {output_dir}/technical/module-analysis/order-service/
• /apps/core/payments → {output_dir}/technical/module-analysis/payments/
• /src/services/notification-service.ts → {output_dir}/technical/module-analysis/notification-service/

输出结构

请参阅 assets/templates/，了解完整的文档结构：

• REPORT.md — 技术分析报告模板，包含 Executive Summary、Technical Analysis、Module Communication、Technical Diagrams、Metrics 和 Referencias 部分
• REFACTOR.md — 重构建议模板（仅限 v3），包含 Code Smells、Recommendations、Priority Matrix、Implementation Plan、Impact Analysis、Testing Strategy 和 Referencias 部分

关键部分概览

REPORT.md 包含：

1. Executive Summary（模块概览、用途、关键程度、技术）
2. Technical Analysis（职责、关键函数、执行流程、状态管理、错误处理、依赖项）
3. Module Communication（消费的内容、暴露的内容、通信类型、共享状态）
4. Technical Diagrams（根据复杂度绘制的 Mermaid 图表）
5. Metrics（使用标准格式的代码质量指标）
6. Referencias（指向相关文档的双向链接）

REFACTOR.md（仅限 v3）包含：

1. Code Smells（带严重程度评级的问题）
2. Recommendations（包含优先级、影响和工作量的可执行改进建议）
3. Priority Matrix（建议的可视化呈现）
4. Implementation Plan（分阶段的重构路线图）
5. Impact Analysis（受影响的组件、风险评估、预期收益）
6. Testing Strategy（验证方法）
7. Referencias（回链至 REPORT.md）

分析深度级别

Level	Name	Includes	Use When
v1	说明	Executive Summary + Technical Analysis + Communication	快速了解某个模块
v2	说明 + 图表	v1 的全部内容 + Mermaid 图表	编写文档或帮助新成员熟悉项目（默认）
v3	完整分析	v2 的全部内容 + 重构建议	重构前审计或技术评审

默认值：如果用户未指定级别，请使用 v2。

关键模式

模式 1：先读后写

生成任何分析前，务必先阅读实际代码。切勿仅根据文件名、文件夹结构或假设来生成报告。如果无法读取某个文件，应将其标记为“无法访问”，而不是猜测其内容。

模式 2：解释，而非复制

报告应解释代码的工作方式，而不是复现代码。仅在需要说明特定模式或行为时，使用简短的内联代码片段（1-3 行）。切勿粘贴完整的函数、类或文件。

不佳：将一个 50 行的函数粘贴到报告中
良好：“processPayment() 函数会验证输入，通过 gateway.charge() 调用支付网关，并在成功时发出 payment.completed 事件。”

模式 3：明确说明未知信息

当信息不可用或无法从代码中确定时：

不佳：猜测某个模块可能执行的操作
良好：“该模块导入了 @core/events，但在此范围内无法看到事件处理程序的实现，因此无法确定具体消费了哪些事件。”

模式 4：如实说明依赖项

仅列出代码中明确可见的依赖项（导入语句、require 语句、配置文件、依赖注入）。如果怀疑存在某个依赖项但未能确认，应将其标记为“疑似”，并说明理由。

模式 5：选择符合上下文的图表

有关 Mermaid 图表选择标准、语法示例和最佳实践的详细说明，请参阅 assets/helpers/diagram-guidelines.md。图表的复杂度应与模块复杂度相匹配（简单 = 仅流程图，中等 = 流程图 + 时序图，复杂 = 流程图 + 时序图 + 类图/C4 图）。

模式 6：技术无关的分析

该分析框架适用于任何语言或框架。请调整术语以匹配相应技术：

概念	JavaScript/TypeScript	Python	Go	Java
模块	Module/Package	Module/Package	Package	Package
入口点	index.ts / export	__init__.py	main.go	Application.java
接口	Type/Interface	Protocol/ABC	Interface	Interface
依赖注入	Constructor/Provider	__init__ params	Struct fields	@Inject

最佳实践

分析前

1. 确认目标路径存在 — 开始前验证模块路径
2. 识别项目类型 — 单体仓库、单体应用、微服务、库
3. 检查现有文档 — README、JSDoc、文档字符串、OpenAPI 规范
4. 必要时询问背景信息 — 不要猜测业务需求

分析期间

1. 从入口点入手 — 先找到主导出、路由器或处理程序
2. 先追踪正常路径 — 了解正常流程后再分析边缘情况
3. 随时梳理依赖关系 — 逐步构建依赖图
4. 发现模式时做好记录 — 架构模式应从阅读中发现，而不是靠猜测
5. 检查测试文件 — 测试能揭示预期行为和边缘情况

分析后

1. 检查报告的准确性 — 每项陈述都必须有已阅读代码的支持
2. 验证图表是否正确 — 确保图表与文字分析一致
3. 检查是否缺少章节 — 必须包含所有必需的输出章节
4. 保存到正确位置 — {output_dir}/technical/module-analysis/{module-name}/

与其他技能集成

与 universal-planner 集成

在 universal-planner 的分析阶段（步骤 1）使用 code-analyzer，以了解计划工作将影响的模块当前状态。

与 universal-planner 集成（EXECUTE 模式）

执行修改模块的 sprint 前，运行 code-analyzer 记录“修改前”状态，以便进行对比。

限制

1. 需要文件访问权限：无法分析无法通过文件系统读取的代码。如果用户提供代码片段，分析范围仅限于可见内容
2. 不进行运行时分析：仅分析静态代码，无法检测运行时行为、性能特征或动态分派模式
3. 聚焦单个模块：一次分析一个模块。跨模块分析需要分别运行并手动关联结果
4. 不进行自动化测试：不会执行测试或验证代码是否正常工作，只分析结构和模式
5. 框架检测：可能无法识别自定义或不常见的框架。用户可以提供框架背景信息作为补充

交付阶段

生成技术报告（如果是 v3，还包括重构建议）后，为用户提供以下交付选项：

1. 同步到 Obsidian 知识库 — 以 SYNC 模式调用 obsidian 技能（参见下方调用方式）
2. 移至自定义路径 — 用户指定目标位置，然后将文件移至该位置
3. 保留在暂存目录中 — 将文件留在 {output_dir} 供日后使用

询问用户更倾向于哪种选项。

Obsidian 调用方式（选项 1）：

• 首选：Skill("obsidian")，然后说“将 {output_dir} 中的文件同步到知识库”
• 替代方式：说“将输出同步到 obsidian”（触发 auto_invoke）
• 子 Agent 备用方式：读取 obsidian SKILL.md 并遵循 SYNC 模式工作流

---

故障排查

问题	解决方案
模块路径不存在	向用户确认路径，检查是否有拼写错误、大小写问题或文件已移动
无法确定框架	请用户指定，检查配置文件（package.json、requirements.txt 等）
模块过大	拆分为子模块，分别分析，并创建顶层摘要
依赖关系不明确	附上推理依据并标记为“疑似”，检查 DI 容器和配置文件
报告似乎不完整	确认是否已读取所有文件，检查动态导入或由配置驱动的行为

输出示例

查看 assets/templates/REPORT.md 和 assets/templates/REFACTOR.md，了解完整示例，其中包括执行摘要、通信图、Mermaid 图表和所有其他章节。

后续改进

多模块分析、依赖关系图可视化、自动变更检测、测试覆盖率集成，以及导出到 Confluence/Notion。