项目理解skill-v1

codebase_architecture_analyzer_v1/skill.md

@@ -0,0 +1,165 @@
+---
+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 等常见依赖目录
+
+---
+
+现在开始分析当前项目。