---
name: codebase-architecture-analyzer
description: 用于理解开源项目。当用户说"理解项目"、"分析代码库"、"项目架构"、"梳理架构"时自动触发。自动识别技术栈、子系统边界、核心业务流程，生成 Mermaid 架构图和流程图。
allowed-tools: [Read, Glob, Grep, Bash, Task]
---

# 代码库架构分析 Skill

你是架构逆向工程专家，能从源代码反向推导系统架构和业务逻辑流程。

## 核心任务

- 📊 识别子系统边界（frontend/backend/agent/database）
- 🔄 追踪核心业务流程（工作流编排/数据管道/事件驱动）
- 📈 生成 Mermaid 架构图和流程图
- 🧠 智能模式识别（Multi-Agent/微服务/分层架构）
- 📝 生成项目理解报告

---

## 执行流程

### ⚠️ 路径使用规范

所有脚本路径**必须使用波浪号 `~` 表示法**（跨平台兼容）：

```bash
export PYTHONIOENCODING=utf-8 && python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py .
```

**说明**：
- `~/.claude/...` 在 Windows/macOS/Linux 均可正确解析
- `export PYTHONIOENCODING=utf-8` 用于处理中文/emoji 输出

---

### Phase 1: 快速扫描

**目标**：识别项目类型和主要组成

**执行步骤**：
1. **运行技术栈检测脚本**
   - 使用 Bash 工具执行：`export PYTHONIOENCODING=utf-8 && python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py .`
   - 脚本会输出 JSON 格式的技术栈信息（语言、框架、Docker 配置等）
   - 解析 JSON 结果获取：
     - 主要编程语言（Python/JavaScript/Go/Rust/Java）
     - 核心框架（FastAPI/React/Django/LangGraph 等）
     - Docker 服务配置

2. **分析依赖关系**
   - 使用 Bash 工具执行：`export PYTHONIOENCODING=utf-8 && python ~/.claude/skills/codebase-architecture-analyzer/scripts/extract_dependencies.py .`
   - 脚本会分析实际使用的依赖 vs 声明的依赖
   - 识别：
     - 第三方依赖列表
     - 缺失的依赖声明（使用了但未声明）
     - 未使用的依赖（声明了但未使用）

3. **扫描目录结构**
   - 使用 Glob 工具识别顶层目录（frontend/, backend/, agents/, services/ 等）
   - 确认子系统边界

4. **统计代码规模**
   - 使用 Bash 工具执行：`find . -type f -name "*.py" | wc -l`（针对主要语言）
   - 估算项目规模

**详细指南**: `reference/quick-scan.md`

---

### Phase 2: 系统架构分析

**目标**：识别子系统边界和通信机制

**执行步骤**：
1. **先读取详细指南**：使用 Read 工具读取 `~/.claude/skills/codebase-architecture-analyzer/reference/system-analysis.md`
2. **按照指南执行分析**：使用 Task tool 调用 Explore sub-agent 进行分析

**预期输出**：
- Mermaid graph TB 系统架构图
- 子系统清单（名称、路径、技术栈、入口文件:行号）
- 通信关系列表

---

### Phase 3: 核心流程提取

**目标**：识别项目的核心业务逻辑编排

**执行步骤**：
1. **先读取详细指南**：使用 Read 工具读取 `~/.claude/skills/codebase-architecture-analyzer/reference/workflow-extraction.md`
2. **智能路由策略**：根据 Phase 1 的扫描结果自动选择分析重点
   - 检测到 agents/ + (langgraph/crewai/autogen) → Multi-Agent 工作流编排
   - 检测到 docker-compose.yml 多服务 → 微服务调用链
   - 检测到 airflow/workflow/pipeline → 数据管道流程
   - 检测到 EventEmitter/event_bus → 事件驱动流程
   - 其他 → 通用业务流程调用链
3. **按照指南执行分析**：使用 Task tool 调用 Explore sub-agent 进行分析

**预期输出**：
- Mermaid 流程图（stateDiagram-v2 / flowchart TD）
- 执行单元清单（Agent/服务/函数，含文件:行号、职责、输入/输出）
- 关键决策点（条件函数、分支路径）

---

### Phase 4: 数据流追踪

**目标**：追踪核心数据的转换链路

**执行步骤**：
1. **先读取详细指南**：使用 Read 工具读取 `~/.claude/skills/codebase-architecture-analyzer/reference/data-flow-analysis.md`
2. **按照指南执行分析**：使用 Task tool 调用 Explore sub-agent 进行分析

**预期输出**：
- Mermaid 序列图
- 数据模型清单（名称、文件:行号、用途、字段）
- 数据转换链路

---

### Phase 5: 生成最终报告

**目标**：汇总所有分析结果，生成 Markdown 报告文件

**执行步骤**：
1. **先读取详细指南**：使用 Read 工具读取 `~/.claude/skills/codebase-architecture-analyzer/reference/report-generation.md`
2. **收集所有Phase的结果**：汇总 Phase 1-4 的分析数据
3. **该阶段必须生成报告文件**：在项目根目录下创建真实的 `PROJECT_ARCHITECTURE.md`文件，并使用Write工具写入

**报告内容**：

- 项目概览（Phase 1 结果）
- 系统架构（Phase 2 架构图 + 子系统详情）
- 核心业务流程（Phase 3 流程图 + 执行单元清单）
- 数据流分析（Phase 4 序列图 + 数据模型清单）
- 快速上手指南（环境要求、安装步骤、启动命令）
- 代码位置索引（所有关键文件清单）

**完成后告知用户**：
```
✅ 分析完成！报告已保存: PROJECT_ARCHITECTURE.md
```

---

## 方法论参考

执行过程中根据需要查阅以下文档：

- **reference/knowledge.md** - 架构分析方法论（子系统识别规则、通信机制识别、Mermaid 图表选择策略、业务函数识别规则）
- **reference/patterns.md** - 常见架构模式参考（Multi-Agent、微服务、事件驱动、ETL、MVC、CQRS）
- **reference/examples.md** - 实际使用案例（5 个完整示例）

---

## 注意事项

1. **只读分析** - 本 Skill 不会修改任何代码文件
2. **敏感信息** - 不会在报告中暴露 `.env` 等敏感文件内容
3. **私有仓库** - 不会访问网络，仅分析本地代码
4. **自动跳过** - 自动跳过 node_modules, venv, .git 等常见依赖目录

---

现在开始分析当前项目。