commit ae83b9d4d81239e805b66da94b490404a86a90b2 Author: 闫旭隆 <15945644+yan-xulong@user.noreply.gitee.com> Date: Wed Nov 12 10:27:56 2025 +0800 项目理解skill-v1 diff --git a/codebase_architecture_analyzer_v1.zip b/codebase_architecture_analyzer_v1.zip new file mode 100644 index 0000000..0494393 Binary files /dev/null and b/codebase_architecture_analyzer_v1.zip differ diff --git a/codebase_architecture_analyzer_v1/assets/report.md b/codebase_architecture_analyzer_v1/assets/report.md new file mode 100644 index 0000000..6a45729 --- /dev/null +++ b/codebase_architecture_analyzer_v1/assets/report.md @@ -0,0 +1,204 @@ +# {PROJECT_NAME} 架构分析报告 + +> 生成时间: {TIMESTAMP} +> 分析工具: Claude Code - Codebase Architecture Analyzer + +--- + +## 一、项目概览 + +### 1.1 基本信息 + +- **项目类型**: {PROJECT_TYPE} +- **主要语言**: {PRIMARY_LANGUAGE} ({PRIMARY_FILE_COUNT} 个文件) +- **次要语言**: {SECONDARY_LANGUAGE} ({SECONDARY_FILE_COUNT} 个文件) +- **代码规模**: 约 {TOTAL_LINES} 行代码 + +### 1.2 技术栈 + +**后端**: +{BACKEND_STACK} + +**前端**: +{FRONTEND_STACK} + +**数据库**: +{DATABASE_STACK} + +**基础设施**: +{INFRASTRUCTURE_STACK} + +### 1.3 子系统组成 + +{SUBSYSTEMS_LIST} + +--- + +## 二、系统架构 + +### 2.1 架构图 + +```mermaid +{SYSTEM_ARCHITECTURE_DIAGRAM} +``` + +### 2.2 子系统详情 + +{SUBSYSTEMS_DETAILS} + +### 2.3 通信机制 + +{COMMUNICATION_MECHANISMS} + +--- + +## 三、核心业务流程 + +### 3.1 识别的架构模式 + +**核心模式**: {DETECTED_PATTERN} + +{PATTERN_DESCRIPTION} + +### 3.2 业务流程图 + +```mermaid +{WORKFLOW_DIAGRAM} +``` + +### 3.3 执行单元清单 + +{EXECUTION_UNITS_LIST} + +### 3.4 关键决策点 + +{DECISION_POINTS} + +--- + +## 四、数据流分析 + +### 4.1 数据流序列图 + +```mermaid +{SEQUENCE_DIAGRAM} +``` + +### 4.2 核心数据模型 + +{DATA_MODELS_LIST} + +### 4.3 数据转换链路 + +{DATA_TRANSFORMATION_CHAIN} + +--- + +## 五、快速上手指南 + +### 5.1 环境要求 + +{ENVIRONMENT_REQUIREMENTS} + +### 5.2 安装步骤 + +```bash +{INSTALLATION_STEPS} +``` + +### 5.3 启动命令 + +```bash +{STARTUP_COMMANDS} +``` + +### 5.4 核心入口文件 + +{ENTRY_POINTS_LIST} + +--- + +## 六、代码位置索引 + +### 6.1 核心业务逻辑 + +{CORE_LOGIC_INDEX} + +### 6.2 API 端点 + +{API_ENDPOINTS_INDEX} + +### 6.3 数据模型定义 + +{DATA_MODELS_INDEX} + +### 6.4 配置文件 + +{CONFIG_FILES_INDEX} + +--- + +## 七、代码质量概览 + +### 7.1 统计指标 + +- 总文件数: {TOTAL_FILES} +- 代码行数: {CODE_LINES} +- 注释行数: {COMMENT_LINES} +- 空行数: {BLANK_LINES} + +### 7.2 目录结构树 + +``` +{DIRECTORY_TREE} +``` + +--- + +## 八、外部资源 + +### 8.1 文档链接 + +{DOCUMENTATION_LINKS} + +### 8.2 学术论文 + +{PAPERS_LIST} + +### 8.3 参考资料 + +{REFERENCES_LIST} + +--- + +## 九、注意事项 + +### 9.1 已知限制 + +{KNOWN_LIMITATIONS} + +### 9.2 待验证事项 + +{TODO_VERIFY} + +--- + +## 附录 + +### A. 依赖清单 + +{DEPENDENCIES_LIST} + +### B. 环境变量 + +{ENVIRONMENT_VARIABLES} + +### C. 分析方法 + +本报告基于以下方法生成： +- 静态代码分析（AST 解析） +- 配置文件解析 +- 目录结构分析 +- 模式匹配识别 + +所有结论均基于代码事实，标注了具体的文件位置以供验证。 diff --git a/codebase_architecture_analyzer_v1/assets/sequence.mermaid b/codebase_architecture_analyzer_v1/assets/sequence.mermaid new file mode 100644 index 0000000..47e697e --- /dev/null +++ b/codebase_architecture_analyzer_v1/assets/sequence.mermaid @@ -0,0 +1,24 @@ +sequenceDiagram + participant U as 用户 + participant F as {FRONTEND_NAME} + participant B as {BACKEND_NAME} + participant C as {CORE_LOGIC_NAME} + participant D as {DATABASE_NAME} + + U->>F: {USER_ACTION} + Note over F: {FRONTEND_PROCESSING} + + F->>B: {API_REQUEST}
{REQUEST_PAYLOAD} + Note over B: {BACKEND_PROCESSING} + + B->>C: {CORE_INVOCATION}
{INVOCATION_PARAMS} + Note over C: {CORE_PROCESSING} + + C->>D: {DATA_OPERATION} + D-->>C: {DATA_RESPONSE} + + C-->>B: {CORE_RESULT} + B-->>F: {API_RESPONSE} + + Note over F: {FRONTEND_RENDERING} + F-->>U: {USER_RESULT} diff --git a/codebase_architecture_analyzer_v1/reference/data-flow-analysis.md b/codebase_architecture_analyzer_v1/reference/data-flow-analysis.md new file mode 100644 index 0000000..ab3c0dc --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/data-flow-analysis.md @@ -0,0 +1,204 @@ +# Phase 4: 数据流追踪指南 + +**执行时间**：约 1-2 分钟 + +**目标**：追踪核心数据的转换链路 + +--- + +## ⚠️ 重要约束 + +**在调用 Task tool 时，必须在 prompt 开头包含以下约束：** + +``` +⚠️ 重要约束：本次分析只返回文本结果，禁止生成任何文件（.md, .txt 等）。 +所有 Mermaid 图表、数据模型清单、转换链路都应包含在你的文本回复中，不要使用 Write 或其他文件创建工具。 +``` + +**Explore agent 只返回文本结果，不要生成任何文件。** + +--- + +## 分析步骤 + +### 步骤 1: 识别核心数据模型 + +使用 Grep 工具搜索数据模型定义： + +#### Python 项目 + +```bash +# Pydantic 模型 +grep -r "class.*BaseModel" --include="*.py" + +# Dataclass +grep -r "@dataclass" --include="*.py" + +# SQLAlchemy 模型 +grep -r "class.*Base" --include="*.py" +``` + +#### TypeScript 项目 + +```bash +# Interface 定义 +grep -r "interface.*{" --include="*.ts" + +# Type 别名 +grep -r "type.*=" --include="*.ts" + +# Class 定义 +grep -r "export class" --include="*.ts" +``` + +#### Go 项目 + +```bash +# Struct 定义 +grep -r "type.*struct" --include="*.go" +``` + +### 步骤 2: 追踪数据转换 + +1. **定位数据入口** + - 从 API 端点的请求体开始 + - 识别请求参数的类型定义 + +2. **追踪转换链路** + - 读取每个业务函数的参数类型和返回值类型 + - 记录每次类型转换的代码位置 + - 识别数据验证、清洗、增强步骤 + +3. **标注关键转换点** + - 序列化/反序列化 + - 数据库 ORM 映射 + - DTO（Data Transfer Object）转换 + - 业务逻辑处理 + +### 步骤 3: 生成序列图 + +使用 `assets/sequence.mermaid` 模板生成 Mermaid 序列图。 + +**⚠️ sequenceDiagram 语法约束（版本 11.x）**： +- `alt/loop/par` 块必须正确配对 `end` +- 使用 `
` 换行 + +--- + +## 预期输出格式 + +### 1. Mermaid 序列图 + +```mermaid +sequenceDiagram + participant U as 用户 + participant F as Frontend + participant B as Backend + participant R as Researcher + participant W as Writer + + U->>F: 输入查询 "AI 发展趋势" + F->>B: POST /api/research
{query, depth: 3} + Note over B: 构造 ResearchTask + B->>R: invoke(ResearchTask) + R->>R: 搜索引擎调用 + R-->>B: SearchResults (10 个文档) + B->>W: 传递 SearchResults + W->>W: GPT-4 生成报告 + W-->>B: Report (2000 字) + B->>F: 返回 HTML + F->>U: 展示报告 +``` + +### 2. 数据模型清单 + +列出所有核心数据模型及其位置： + +``` +核心数据模型: +1. ResearchTask (models/task.py:8) + - 用途: 用户查询任务 + - 字段: query: str, depth: int, filters: Optional[List[str]] + +2. SearchResults (models/results.py:15) + - 用途: 搜索结果集合 + - 字段: documents: List[Document], total: int, timestamp: datetime + +3. Report (models/report.py:22) + - 用途: 最终生成的报告 + - 字段: content: str, score: float, metadata: Dict[str, Any] +``` + +### 3. 数据转换链路 + +``` +数据流转路径: +用户输入 (str) + → ResearchTask (构造于 backend/routes.py:42) + → SearchResults (返回于 agents/researcher.py:67) + → Report (生成于 agents/writer.py:89) + → HTML (渲染于 backend/routes.py:58) + → 前端展示 +``` + +--- + +## 分析技巧 + +### 1. 类型提示追踪 + +Python 示例： +```python +# 从函数签名追踪类型流转 +def process_query(task: ResearchTask) -> SearchResults: + # task 类型: ResearchTask + results = search_engine.search(task.query) + # results 类型: SearchResults + return results +``` + +TypeScript 示例： +```typescript +// 从接口定义追踪 +interface ApiRequest { + query: string; + depth: number; +} + +async function handleRequest(req: ApiRequest): Promise { + // req 类型: ApiRequest + const results = await research(req); + // results 类型: Report + return results; +} +``` + +### 2. ORM 映射识别 + +SQLAlchemy 示例： +```python +# 数据库模型 → Pydantic 模型 +class UserDB(Base): + __tablename__ = "users" + id = Column(Integer, primary_key=True) + +class UserSchema(BaseModel): + id: int + # 从 UserDB 转换到 UserSchema +``` + +### 3. DTO 转换模式 + +```python +# 请求 DTO → 领域对象 → 响应 DTO +RequestDTO → DomainModel → ResponseDTO +``` + +--- + +## 注意事项 + +1. **关注核心路径**：只追踪主要业务流程的数据转换，忽略辅助功能 +2. **最多 5 层深度**：避免追踪过深导致图表过于复杂 +3. **标注转换位置**：每次类型转换都记录文件名和行号 +4. **区分同步/异步**：在序列图中用实线（同步）和虚线（异步）区分 diff --git a/codebase_architecture_analyzer_v1/reference/examples.md b/codebase_architecture_analyzer_v1/reference/examples.md new file mode 100644 index 0000000..7513e08 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/examples.md @@ -0,0 +1,452 @@ +# 使用示例 + +本文档提供实际使用场景的示例。 + +## 示例 1: 分析 Multi-Agent AI 项目 + +### 项目结构 + +``` +ai-research-assistant/ +├── frontend/ +│ ├── src/ +│ │ ├── components/ +│ │ └── main.tsx +│ └── package.json +├── backend/ +│ ├── app/ +│ │ ├── main.py +│ │ └── routes.py +│ └── requirements.txt +└── agents/ + ├── graph.py + └── nodes.py +``` + +### 用户操作 + +``` +用户: 理解项目 +``` + +### Skill 执行过程 + +#### Phase 1: 快速扫描 (30秒) + +``` +⏳ 正在扫描项目结构... + +✓ 检测到配置文件: + - backend/requirements.txt (Python) + - frontend/package.json (JavaScript) + +✓ 读取依赖: + - Python: fastapi, langgraph, openai + - JavaScript: react, typescript + +✓ 扫描目录: + - frontend/ (82 个 .tsx 文件) + - backend/ (45 个 .py 文件) + - agents/ (8 个 .py 文件) + +✓ 快速扫描完成 + +项目类型: AI 驱动的 Web 应用 +主语言: Python (后端 + AI) +次要语言: TypeScript (前端) +核心框架: FastAPI + LangGraph + React +架构: 前后端分离 + Multi-Agent +``` + +#### Phase 2: 系统架构分析 (2分钟) + +``` +⏳ 调用 Explore sub-agent 分析系统架构... + +[Sub-agent 执行] +- 搜索 API 端点: @app.post, @router. +- 发现端点: /api/research, /api/status +- 搜索 WebSocket: WebSocket( +- 发现: /ws 实时通信端点 +- 搜索数据库: Redis, PostgreSQL +- 发现: Redis 缓存, PostgreSQL 持久化 + +✓ 系统架构分析完成 + +识别出 3 个子系统: +├─ Frontend (frontend/) +│ ├─ 技术: React 18 + TypeScript +│ └─ 入口: src/main.tsx:1 +├─ Backend (backend/) +│ ├─ 技术: FastAPI + Python 3.11 +│ └─ 入口: app/main.py:1 +└─ Agent Layer (agents/) + ├─ 技术: LangGraph 0.2.5 + └─ 入口: graph.py:1 + +通信机制: +- Frontend → Backend: WebSocket (/ws) +- Frontend → Backend: HTTP POST (/api/research) +- Backend → Agent Layer: 直接调用 invoke() +- Agent Layer → Redis: 缓存中间结果 +- Agent Layer → PostgreSQL: 持久化数据 +``` + +**生成的架构图**: + +```mermaid +graph TB + User[用户] --> Frontend[前端
React + TypeScript] + Frontend -->|WebSocket /ws| Backend[后端 API
FastAPI] + Frontend -->|POST /api/research| Backend + Backend -->|invoke| AgentLayer[Agent 编排层
LangGraph] + AgentLayer -->|缓存| Redis[(Redis)] + AgentLayer -->|持久化| DB[(PostgreSQL)] + + style AgentLayer fill:#f9f,stroke:#333,stroke-width:3px +``` + +**代码位置索引**: +- Frontend 入口: `frontend/src/main.tsx:1` +- Backend 入口: `backend/app/main.py:1` +- API 定义: `backend/app/routes.py:42` +- Agent 调用: `backend/app/routes.py:58` + +#### Phase 3: 核心流程提取 (5分钟) + +``` +⏳ 检测到 agents/ 目录，正在深度分析 Multi-Agent 编排... + +⏳ 调用 Explore sub-agent 提取工作流... + +[Sub-agent 执行] +- 搜索 StateGraph 定义 +- 发现: agents/graph.py:23 +- 提取 Agent 节点: + * researcher (agents/nodes.py:45) + * writer (agents/nodes.py:78) + * reviewer (agents/nodes.py:112) +- 分析流转规则: + * researcher → writer (顺序) + * writer → reviewer (顺序) + * reviewer → researcher (条件: quality < 7) + * reviewer → END (条件: quality >= 7) + +✓ Multi-Agent 编排流程解析完成 + +识别出 3 个 Agent: +1. Researcher (agents/nodes.py:45) + - 职责: 调用搜索 API 收集资料 + - 输入: ResearchTask + - 输出: List[Document] + +2. Writer (agents/nodes.py:78) + - 职责: 基于资料生成报告 + - 输入: List[Document] + - 输出: Report + +3. Reviewer (agents/edges.py:12) + - 职责: 评估报告质量 + - 决策: quality < 7 → 返回 Researcher + quality >= 7 → 结束流程 +``` + +**生成的流程图**: + +```mermaid +stateDiagram-v2 + [*] --> Researcher: 用户查询 + Researcher --> Writer: 研究完成 + Writer --> Reviewer: 生成草稿 + Reviewer --> Researcher: 质量不足
评分 < 7 + Reviewer --> [*]: 质量通过 + + note right of Researcher + agents/nodes.py:45 + 调用 Tavily 搜索 API + 返回 List[Document] + end note + + note right of Writer + agents/nodes.py:78 + 基于搜索结果 + 调用 GPT-4 生成报告 + end note + + note right of Reviewer + agents/edges.py:12 + 评估报告质量 + 决定是否重新研究 + end note +``` + +#### Phase 4: 数据流追踪 (1分钟) + +``` +⏳ 追踪数据流... + +✓ 识别核心数据模型: + - ResearchTask (models/task.py:8) + - SearchResults (models/results.py:15) + - Report (models/report.py:22) + +✓ 数据转换链路: + 用户输入 (str) + → ResearchTask (models/task.py:8) + → SearchResults (agents/researcher.py:45) + → Report (agents/writer.py:78) + → HTML (backend/routes.py:65) +``` + +**生成的序列图**: + +```mermaid +sequenceDiagram + participant U as 用户 + participant F as Frontend + participant B as Backend + participant R as Researcher + participant W as Writer + + U->>F: 输入查询 "AI 发展趋势" + F->>B: POST /api/research
{query, depth: 3} + Note over B: 构造 ResearchTask + B->>R: invoke(ResearchTask) + R->>R: 调用搜索引擎 + R-->>B: SearchResults (10 文档) + B->>W: 传递 SearchResults + W->>W: GPT-4 生成报告 + W-->>B: Report (2000 字) + B->>F: 返回 HTML + F->>U: 展示报告 +``` + +#### Phase 5: 生成报告 (30秒) + +``` +⏳ 生成最终报告... + +✓ 分析完成！ + +报告已保存: PROJECT_ARCHITECTURE.md + +核心发现: +- 采用 LangGraph 编排 Multi-Agent 工作流 +- 支持条件路由和循环优化 +- 数据流: 查询 → 搜索 → 写作 → 审核 → 报告 + +快速上手: +1. 安装依赖: pip install -r backend/requirements.txt +2. 配置环境: cp .env.example .env +3. 启动后端: cd backend && uvicorn app.main:app --reload +4. 启动前端: cd frontend && npm install && npm start +5. 访问: http://localhost:3000 +``` + +--- + +## 示例 2: 分析微服务项目 + +### 项目结构 + +``` +ecommerce-platform/ +├── docker-compose.yml +├── services/ +│ ├── api-gateway/ +│ ├── user-service/ +│ ├── order-service/ +│ └── notification-service/ +└── shared/ +``` + +### 用户操作 + +``` +用户: 分析代码库架构 +``` + +### 执行过程（简化版） + +``` +[30s] ✓ 检测到 docker-compose.yml + 识别为微服务架构 + 发现 4 个服务: api-gateway, user-service, order-service, notification-service + +[2min] ✓ 服务调用拓扑图已生成 + api-gateway → user-service (HTTP GET /users/:id) + api-gateway → order-service (HTTP POST /orders) + api-gateway → notification-service (HTTP POST /notify) + +[5min] ✓ 报告已保存: PROJECT_ARCHITECTURE.md +``` + +**生成的架构图**: + +```mermaid +graph TB + Client[客户端] --> Gateway[API Gateway
:8000] + + Gateway -->|GET /users/:id| UserSvc[User Service
:8001] + Gateway -->|POST /orders| OrderSvc[Order Service
:8002] + Gateway -->|POST /notify| NotifySvc[Notification Service
:8003] + + UserSvc --> UserDB[(User DB
PostgreSQL)] + OrderSvc --> OrderDB[(Order DB
PostgreSQL)] + + style Gateway fill:#ff6b6b + style UserSvc fill:#4ecdc4 + style OrderSvc fill:#45b7d1 + style NotifySvc fill:#f9ca24 +``` + +--- + +## 示例 3: 分析 ETL 数据管道 + +### 项目结构 + +``` +data-pipeline/ +├── pipeline.py +├── extractors/ +├── transformers/ +└── loaders/ +``` + +### 执行结果 + +``` +[30s] ✓ 检测到 ETL 模式 + 识别函数: extract_from_csv, transform_data, load_to_database + +[3min] ✓ 数据管道流程图已生成 +``` + +**生成的流程图**: + +```mermaid +flowchart LR + CSV[CSV 文件] --> Extract[Extract
提取数据] + Extract --> Clean[Clean
去重] + Clean --> Enrich[Enrich
添加元数据] + Enrich --> Validate[Validate
校验] + Validate --> DB[(PostgreSQL)] + Validate --> S3[(S3 存储)] +``` + +--- + +## 示例 4: 只分析特定模块 + +### 用户操作 + +``` +用户: 只分析 agents/ 目录的工作流编排 +``` + +### 执行过程 + +``` +✓ 限定分析范围: agents/ + +[跳过 Phase 1, Phase 2] + +[3min] ✓ 深度分析 agents/ 目录完成 + +识别出 LangGraph 编排: +- 3 个 Agent 节点 +- 2 个条件分支 +- 1 个循环优化路径 + +流程图已生成（仅包含 agents/ 的逻辑） +``` + +--- + +## 示例 5: 更新现有分析 + +### 场景 + +项目代码已更新，需要重新分析。 + +### 用户操作 + +``` +用户: 更新架构分析报告 +``` + +### 执行过程 + +``` +✓ 检测到已存在 PROJECT_ARCHITECTURE.md + +[对比文件时间戳] +- agents/graph.py 已修改（2 天前） +- backend/routes.py 未修改 + +⏳ 只重新分析有变更的部分... + +[2min] ✓ 增量分析完成 + - Agent 层新增 1 个节点: Optimizer + - 流程图已更新 + +✓ 报告已更新: PROJECT_ARCHITECTURE.md +``` + +--- + +## 最佳实践 + +### 1. 项目克隆后立即分析 + +```bash +git clone https://github.com/user/project.git +cd project +# 打开 Claude Code +``` + +``` +理解项目 +``` + +优势：快速建立项目全景认知。 + +### 2. 结合其他 Skills + +``` +理解项目，然后生成开发者入门文档 +``` + +先分析架构，再基于分析结果生成文档。 + +### 3. 针对性分析 + +``` +只分析后端的 API 路由和业务逻辑 +``` + +节省时间，聚焦关键部分。 + +--- + +## 故障排除示例 + +### 问题: 无法识别自定义框架 + +**场景**: 公司内部自研框架 + +**解决方案**: + +手动提示： + +``` +这个项目使用了内部框架 InternalFlow，它的工作流定义在 workflows/ 目录， +请分析 workflows/ 中的 YAML 文件来理解流程编排。 +``` + +--- + +## 更多示例 + +查看 `patterns.md` 了解各种架构模式的详细识别案例。 diff --git a/codebase_architecture_analyzer_v1/reference/knowledge.md b/codebase_architecture_analyzer_v1/reference/knowledge.md new file mode 100644 index 0000000..d351647 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/knowledge.md @@ -0,0 +1,511 @@ +# 架构分析方法论 + +本文档提供代码库架构分析的核心方法论和最佳实践。 + +## 目录 + +- [1. 子系统边界识别](#1-子系统边界识别) +- [2. 工作流模式识别](#2-工作流模式识别) +- [3. 通信机制识别](#3-通信机制识别) +- [4. Mermaid 图表选择策略](#4-mermaid-图表选择策略) +- [5. 业务函数识别规则](#5-业务函数识别规则) + +--- + +## 1. 子系统边界识别 + +### 规则 1: 目录命名模式 + +通过目录名称识别子系统： + +| 目录模式 | 子系统类型 | 常见技术栈 | +|---------|-----------|-----------| +| `frontend/`, `ui/`, `web/`, `client/` | 前端子系统 | React, Vue, Angular | +| `backend/`, `api/`, `server/` | 后端子系统 | FastAPI, Express, Django | +| `agent/`, `agents/`, `workers/` | Agent 系统 | LangGraph, CrewAI, Celery | +| `services/` + 多个子目录 | 微服务集群 | Spring Boot, Go microservices | +| `database/`, `models/`, `schema/` | 数据层 | SQLAlchemy, Prisma | +| `shared/`, `common/`, `lib/` | 共享库 | 工具函数、类型定义 | + +### 规则 2: 独立配置文件识别 + +每个子系统通常有独立的配置文件： + +``` +frontend/ +├── package.json → 独立的 Node.js 项目 +├── tsconfig.json +└── vite.config.js + +backend/ +├── requirements.txt → 独立的 Python 项目 +├── pyproject.toml +└── Dockerfile +``` + +**识别方法**： +```bash +# 查找独立的依赖文件 +find . -name "package.json" -o -name "requirements.txt" -o -name "go.mod" +``` + +### 规则 3: Docker Compose 服务划分 + +分析 `docker-compose.yml` 识别服务边界： + +```yaml +services: + frontend: # 前端服务 + build: ./frontend + api: # API 服务 + build: ./backend + worker: # 后台任务 + build: ./worker + db: # 数据库 + image: postgres:15 +``` + +每个 service 通常对应一个独立的子系统。 + +--- + +## 2. 工作流模式识别 + +### 模式 1: Multi-Agent 编排 + +**特征**： +- 导入 `langgraph`, `crewai`, `autogen` +- 存在 `StateGraph()`, `Crew()`, `Sequential()` 调用 +- 使用 `add_node()`, `add_edge()` 方法 + +**提取方法**： + +1. **定位编排定义** + ```bash + grep -r "StateGraph\|Crew\|AutoGen" --include="*.py" + ``` + +2. **提取 Agent 节点** + ```python + # 示例代码 + graph = StateGraph(AgentState) + graph.add_node("researcher", research_agent) # Agent 1 + graph.add_node("writer", writing_agent) # Agent 2 + graph.add_node("reviewer", review_agent) # Agent 3 + ``` + +3. **分析状态流转** + ```python + graph.add_edge("researcher", "writer") # 顺序流转 + graph.add_conditional_edges("writer", should_revise, { + "revise": "researcher", # 条件分支 + "finish": END + }) + ``` + +**生成图表类型**: `stateDiagram-v2` + +--- + +### 模式 2: 数据管道（ETL/Pipeline） + +**特征**： +- 目录名包含 `pipeline`, `etl`, `workflow` +- 函数名包含 `extract`, `transform`, `load` +- 使用 Airflow, Prefect, Dagster 框架 + +**提取方法**： + +1. **识别管道阶段** + ```python + # 示例代码 + def run_pipeline(source): + raw = extract(source) # 阶段 1 + clean = transform(raw) # 阶段 2 + load(clean) # 阶段 3 + ``` + +2. **追踪数据转换** + - 输入：CSV 文件 + - → DataFrame (pandas) + - → 清洗后 DataFrame + - → PostgreSQL 表 + +**生成图表类型**: `flowchart LR` (从左到右) + +--- + +### 模式 3: 事件驱动架构 + +**特征**： +- 使用 `EventEmitter`, `event_bus`, `@subscribe` +- 发布订阅模式：`emit()`, `on()`, `subscribe()` +- 消息队列：RabbitMQ, Kafka, Redis Pub/Sub + +**提取方法**： + +1. **识别事件定义** + ```python + # 发布事件 + event_bus.emit("order_created", order) + ``` + +2. **识别订阅者** + ```python + @event_bus.on("order_created") + def handle_order(order): + send_confirmation(order) + + @event_bus.on("order_created") + def update_inventory(order): + inventory.decrease(order.items) + ``` + +**生成图表类型**: `graph TB` (显示发布-订阅关系) + +--- + +### 模式 4: 微服务调用链 + +**特征**： +- `docker-compose.yml` 中有多个 services +- 使用 `requests.get()`, `httpx.get()` 调用其他服务 +- gRPC 调用：`stub.MethodCall()` + +**提取方法**： + +1. **识别服务间调用** + ```python + # api-gateway 调用其他服务 + user = requests.get("http://user-service/users/{id}") + order = requests.post("http://order-service/orders", ...) + ``` + +2. **绘制调用拓扑** + - api-gateway → user-service + - api-gateway → order-service + - order-service → payment-service + +**生成图表类型**: `graph TB` (服务拓扑) + +--- + +### 模式 5: 传统分层架构（MVC） + +**特征**： +- 目录结构：`controllers/`, `services/`, `models/` +- 装饰器：`@app.route`, `@Controller` +- ORM 使用：SQLAlchemy, Sequelize + +**提取方法**： + +1. **识别三层结构** + - Controller: 处理 HTTP 请求 + - Service: 业务逻辑 + - Model: 数据模型 + +2. **追踪调用链** + ``` + routes.py (@app.route) + → UserService.create() + → User model + → Database + ``` + +**生成图表类型**: `graph TD` (分层图) + +--- + +## 3. 通信机制识别 + +### HTTP/REST API + +**搜索关键词**： +```bash +# 服务端 +grep -r "@app\.(get|post|put|delete)" --include="*.py" +grep -r "router\.(get|post)" --include="*.js" +grep -r "@RestController" --include="*.java" + +# 客户端 +grep -r "axios\.(get|post)" --include="*.js" +grep -r "requests\.(get|post)" --include="*.py" +grep -r "fetch(" --include="*.ts" +``` + +### WebSocket + +**搜索关键词**： +```bash +grep -r "WebSocket\|socket.io\|ws://" --include="*.{py,js,ts}" +``` + +### 消息队列 + +**搜索关键词**： +```bash +# RabbitMQ +grep -r "pika\|RabbitMQ" --include="*.py" + +# Kafka +grep -r "kafka\|KafkaProducer" --include="*.{py,java}" + +# Redis Pub/Sub +grep -r "redis.*publish\|redis.*subscribe" --include="*.py" +``` + +### gRPC + +**搜索关键词**： +```bash +grep -r "grpc\|\.proto" --include="*.{py,go,java}" +``` + +--- + +## 4. Mermaid 图表选择策略 + +根据识别到的模式选择合适的图表类型： + +| 场景 | 图表类型 | 适用情况 | +|------|---------|---------| +| 状态转换明显（Multi-Agent） | `stateDiagram-v2` | 有明确的状态节点和转换条件 | +| 顺序+条件流程（业务流程） | `flowchart TD` | 顺序执行 + if/else 分支 | +| 数据管道（ETL） | `flowchart LR` | 线性的数据转换流程 | +| 系统拓扑（微服务） | `graph TB` | 多个系统/服务的交互关系 | +| 时序交互（API 调用） | `sequenceDiagram` | 多个参与者的时序消息传递 | +| 并发任务 | `graph TB` + subgraph | 多个并行任务分组 | + +### 语法注意事项 + +**⚠️ Mermaid 语法约束（基于版本 11.x）**： +- **stateDiagram-v2**: 禁用 `--` 分隔符（会报错 "No such shape: divider"） +- **stateDiagram-v2**: 不支持 `
` 标签 +- **sequenceDiagram**: `alt/loop/par` 块必须正确配对 `end` +- **所有类型**: 避免过深嵌套的控制结构 + +**stateDiagram-v2 限制**： +- ❌ 不支持 `
` 标签，使用 `note` 块代替 +- ❌ 不支持 `--` 分隔符 +- ❌ 标签文本避免 `!=`, `==` 等比较运算符 +- ✅ 复杂信息放在 `note right/left of NodeName` 块中 + +**flowchart/graph**： +- ✅ 可使用 `
` 换行 +- ✅ 支持富文本标签 +- ✅ 使用 `style` 设置节点颜色 + +### 示例：选择决策树 + +``` +检测到的特征: + ├─ 有状态变量 + 转换逻辑？ + │ → 是：使用 stateDiagram-v2 + │ → 否：继续判断 + │ + ├─ 有多个参与者 + 时序消息？ + │ → 是：使用 sequenceDiagram + │ → 否：继续判断 + │ + ├─ 线性数据转换？ + │ → 是：使用 flowchart LR + │ → 否：继续判断 + │ + └─ 默认：使用 graph TB 或 flowchart TD +``` + +--- + +## 5. 业务函数识别规则 + +### 排除辅助函数 + +**规则**：以下函数不算业务逻辑 + +```python +# 1. 私有函数（下划线开头） +def _internal_helper(): + pass + +# 2. 工具函数 +def format_date(date): + pass + +def validate_email(email): + pass + +# 3. Getter/Setter +def get_user(): + pass + +def set_config(): + pass + +# 4. 过短的函数（< 5 行） +def simple_wrapper(): + return another_function() +``` + +### 识别业务函数 + +**特征 1：函数名包含业务关键词** + +```python +业务动词: +- process_*, handle_*, execute_*, run_* +- create_*, update_*, delete_* +- generate_*, analyze_*, calculate_* +- search_*, fetch_*, query_* +- build_*, transform_*, convert_* +``` + +**特征 2：处理核心数据模型** + +```python +# 函数参数或返回值包含核心数据类 +def process_order(order: Order) -> OrderResult: # ✓ 业务函数 + ... + +def format_string(s: str) -> str: # ✗ 工具函数 + ... +``` + +**特征 3：函数体较长（> 10 行）** + +通常业务逻辑较复杂，函数体较长。 + +**特征 4：调用外部服务或数据库** + +```python +def create_user(data): + user = User(**data) + db.session.add(user) # ✓ 数据库操作 + db.session.commit() + send_email(user.email) # ✓ 外部服务 + return user +``` + +--- + +## 6. 调用链追踪深度控制 + +### 最大深度策略 + +**问题**：递归追踪可能陷入无限循环 + +**解决方案**：限制最大深度 + +```python +MAX_DEPTH = 5 # 最多追踪 5 层 + +def trace_calls(func_name, current_depth=0): + if current_depth >= MAX_DEPTH: + return + + calls = extract_function_calls(func_name) + for call in calls: + trace_calls(call, current_depth + 1) +``` + +### 广度优先 vs 深度优先 + +**广度优先（BFS）**： +- 优先展示同一层级的所有函数 +- 适合识别并发任务 + +**深度优先（DFS）**： +- 优先追踪单一调用链 +- 适合追踪数据转换流程 + +**推荐**：对于流程分析，使用 **广度优先**。 + +--- + +## 7. 最佳实践 + +### ✅ 应该做的 + +1. **先宽后深** - 先了解整体结构，再深入细节 +2. **只读分析** - 不修改任何代码 +3. **标注位置** - 所有结论都附带文件:行号 +4. **可视化优先** - 用图表表达复杂关系 +5. **分阶段输出** - 边分析边展示进度 + +### ❌ 不应该做的 + +1. **不要臆测** - 所有结论必须基于代码事实 +2. **不要分析 node_modules/** - 跳过第三方依赖 +3. **不要暴露敏感信息** - 不读取 `.env`, `secrets.yaml` +4. **不要过度深入** - 不需要分析每一个辅助函数 +5. **不要修改代码** - 纯只读分析 + +--- + +## 8. 故障排除 + +### 问题 1: 找不到入口点 + +**症状**：无法识别主函数 + +**解决方案**： +```bash +# 多种方式查找 +grep -r "if __name__ == '__main__'" --include="*.py" +grep -r "@app.route\|@app.post" --include="*.py" +grep -r "func main()" --include="*.go" +ls -la | grep -i "main\|index\|app" +``` + +### 问题 2: 调用链太复杂 + +**症状**：函数调用超过 100 层 + +**解决方案**： +- 只追踪业务函数，忽略工具函数 +- 限制最大深度为 5 +- 聚焦核心路径（最常用的调用链） + +### 问题 3: 动态导入无法追踪 + +**症状**：Python 的 `importlib`, JavaScript 的 `require(variable)` + +**解决方案**： +- 结合运行时日志分析 +- 搜索字符串模式猜测可能的模块名 +- 在报告中标注"动态导入，无法静态分析" + +--- + +## 9. 工具推荐 + +### Python 项目 + +- `ast` 模块 - 解析 Python AST +- `radon` - 复杂度分析 +- `pydeps` - 依赖可视化 + +### JavaScript/TypeScript 项目 + +- `@typescript-eslint/parser` - 解析 TS AST +- `madge` - 依赖关系图 +- `dependency-cruiser` - 依赖验证 + +### Go 项目 + +- `go-callvis` - 调用图可视化 +- `gocyclo` - 圈复杂度 + +### 通用工具 + +- `tree` - 目录结构可视化 +- `tokei` - 代码统计 +- `cloc` - 代码行数统计 + +--- + +## 10. 参考资源 + +- **C4 模型**: 系统架构可视化的四层模型 +- **UML 类图**: 面向对象系统的标准表示 +- **事件风暴**: 领域驱动设计的建模方法 +- **架构决策记录 (ADR)**: 记录架构决策的最佳实践 diff --git a/codebase_architecture_analyzer_v1/reference/patterns.md b/codebase_architecture_analyzer_v1/reference/patterns.md new file mode 100644 index 0000000..4ce5294 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/patterns.md @@ -0,0 +1,641 @@ +# 常见架构模式参考 + +本文档提供各种架构模式的识别方法和 Mermaid 模板。 + +## 目录 + +- [1. Multi-Agent 架构](#1-multi-agent-架构) +- [2. 微服务架构](#2-微服务架构) +- [3. 事件驱动架构](#3-事件驱动架构) +- [4. 数据管道（ETL）](#4-数据管道etl) +- [5. 分层架构（MVC）](#5-分层架构mvc) +- [6. CQRS 架构](#6-cqrs-架构) + +--- + +## 1. Multi-Agent 架构 + +### 模式 1.1: LangGraph 编排 + +**代码特征**： +```python +from langgraph.graph import StateGraph, END + +# 定义状态 +class AgentState(TypedDict): + query: str + data: List[str] + result: str + +# 创建图 +graph = StateGraph(AgentState) + +# 添加节点（Agent） +graph.add_node("researcher", research_agent) +graph.add_node("writer", writing_agent) + +# 添加边（流转规则） +graph.add_edge("researcher", "writer") +graph.add_conditional_edges( + "writer", + should_continue, + { + "continue": "researcher", + "end": END + } +) + +# 设置入口 +graph.set_entry_point("researcher") +``` + +**识别方法**： +1. 搜索 `from langgraph` 或 `StateGraph` +2. 提取所有 `add_node()` 调用 → Agent 清单 +3. 提取所有 `add_edge()` 和 `add_conditional_edges()` → 流转规则 +4. 读取每个 Agent 函数的实现 + +**Mermaid 模板**： +```mermaid +stateDiagram-v2 + [*] --> Researcher: 用户查询 + Researcher --> Writer: 数据收集完成 + Writer --> QualityChecker: 生成草稿 + + QualityChecker --> Researcher: 质量不足
评分 < 7 + QualityChecker --> [*]: 质量通过 + + note right of Researcher + 文件: agents/researcher.py:45 + 职责: 调用搜索 API 收集资料 + 输入: ResearchTask + 输出: List[Document] + end note + + note right of Writer + 文件: agents/writer.py:78 + 职责: 基于资料生成报告 + 输入: List[Document] + 输出: Report + end note +``` + +**关键信息提取**： +- Agent 名称 +- 文件位置（文件:行号） +- 职责描述 +- 输入/输出类型 +- 条件分支逻辑 + +--- + +### 模式 1.2: CrewAI 编排 + +**代码特征**： +```python +from crewai import Agent, Task, Crew + +# 定义 Agent +researcher = Agent( + role="Researcher", + goal="Collect comprehensive information", + tools=[search_tool] +) + +writer = Agent( + role="Writer", + goal="Write engaging articles", + tools=[writing_tool] +) + +# 定义任务 +research_task = Task( + description="Research AI trends", + agent=researcher +) + +writing_task = Task( + description="Write article based on research", + agent=writer +) + +# 创建 Crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential +) +``` + +**识别方法**： +1. 搜索 `from crewai` 或 `Agent(` +2. 提取所有 `Agent()` 定义 +3. 提取所有 `Task()` 定义 +4. 分析 `Crew()` 的 process 类型（sequential/hierarchical） + +**Mermaid 模板**： +```mermaid +flowchart TD + Start([开始]) --> Task1[Research Task
Agent: Researcher] + Task1 --> Task2[Writing Task
Agent: Writer] + Task2 --> End([结束]) + + style Task1 fill:#e1f5ff + style Task2 fill:#fff4e1 +``` + +--- + +### 模式 1.3: AutoGen 多智能体 + +**代码特征**： +```python +from autogen import AssistantAgent, UserProxyAgent + +# 定义 Agent +assistant = AssistantAgent( + name="assistant", + llm_config={"config_list": config_list} +) + +user_proxy = UserProxyAgent( + name="user_proxy", + code_execution_config={"work_dir": "coding"} +) + +# 发起对话 +user_proxy.initiate_chat( + assistant, + message="Analyze this dataset" +) +``` + +**Mermaid 模板**： +```mermaid +sequenceDiagram + participant User as UserProxy + participant Asst as AssistantAgent + + User->>Asst: 发起任务 + Asst->>Asst: 生成代码 + Asst->>User: 返回代码 + User->>User: 执行代码 + User->>Asst: 反馈执行结果 + Asst->>User: 最终答案 +``` + +--- + +## 2. 微服务架构 + +### 模式 2.1: Docker Compose 微服务 + +**代码特征**： +```yaml +# docker-compose.yml +services: + api-gateway: + build: ./api-gateway + ports: + - "8000:8000" + + user-service: + build: ./services/user-service + environment: + - DATABASE_URL=postgres://... + + order-service: + build: ./services/order-service + + notification-service: + build: ./services/notification-service +``` + +```python +# api-gateway/routes.py +@app.post("/orders") +def create_order(order_data): + # 调用 user-service + user = requests.get(f"http://user-service:8001/users/{user_id}") + + # 调用 order-service + order = requests.post("http://order-service:8002/orders", json=order_data) + + # 调用 notification-service + requests.post("http://notification-service:8003/notify", json={ + "user_id": user_id, + "order_id": order["id"] + }) + + return order +``` + +**识别方法**： +1. 读取 `docker-compose.yml`，提取所有 services +2. 在每个服务的代码中搜索 `requests.get|post`, `httpx.` +3. 提取目标 URL，识别服务间调用关系 + +**Mermaid 模板**： +```mermaid +graph TB + Client[客户端] --> Gateway[API Gateway
:8000] + + Gateway -->|GET /users/:id| UserSvc[User Service
:8001] + Gateway -->|POST /orders| OrderSvc[Order Service
:8002] + Gateway -->|POST /notify| NotifySvc[Notification Service
:8003] + + UserSvc --> UserDB[(User DB
PostgreSQL)] + OrderSvc --> OrderDB[(Order DB
PostgreSQL)] + + style Gateway fill:#ff6b6b + style UserSvc fill:#4ecdc4 + style OrderSvc fill:#45b7d1 + style NotifySvc fill:#f9ca24 +``` + +**关键信息提取**： +- 服务名称 +- 端口号 +- 服务间调用关系（from → to） +- 数据库连接 + +--- + +### 模式 2.2: Kubernetes 微服务 + +**代码特征**： +```yaml +# k8s/user-service.yaml +apiVersion: v1 +kind: Service +metadata: + name: user-service +spec: + selector: + app: user-service + ports: + - port: 8001 +``` + +**识别方法**： +1. 查找 `k8s/`, `kubernetes/`, `.yaml` 文件 +2. 提取所有 `kind: Service` 定义 + +--- + +## 3. 事件驱动架构 + +### 模式 3.1: 事件总线（Event Bus） + +**代码特征**： +```python +# event_bus.py +class EventBus: + def __init__(self): + self._listeners = {} + + def on(self, event_name, handler): + self._listeners.setdefault(event_name, []).append(handler) + + def emit(self, event_name, data): + for handler in self._listeners.get(event_name, []): + handler(data) + +# handlers.py +@event_bus.on("order_created") +def send_confirmation_email(order): + email.send(order.customer_email, ...) + +@event_bus.on("order_created") +def update_inventory(order): + inventory.decrease(order.items) + +@event_bus.on("order_created") +def log_order(order): + logger.info(f"Order {order.id} created") + +# service.py +def create_order(order_data): + order = Order(**order_data) + db.save(order) + event_bus.emit("order_created", order) # 发布事件 +``` + +**识别方法**： +1. 搜索 `emit(`, `publish(`, `dispatch(` +2. 搜索 `@on(`, `@subscribe(`, `.on(` +3. 提取事件名称和对应的处理器 + +**Mermaid 模板**： +```mermaid +graph TB + OrderService[Order Service] -->|emit| Event[order_created 事件] + + Event --> Handler1[send_confirmation_email
handlers.py:15] + Event --> Handler2[update_inventory
handlers.py:28] + Event --> Handler3[log_order
handlers.py:42] + + Handler1 --> EmailSvc[Email Service] + Handler2 --> InventoryDB[(Inventory DB)] + Handler3 --> Logger[Logger] + + style Event fill:#ffd93d,stroke:#333,stroke-width:3px +``` + +--- + +### 模式 3.2: 消息队列（RabbitMQ/Kafka） + +**代码特征**： +```python +# producer.py +import pika + +connection = pika.BlockingConnection(pika.ConnectionParameters('localhost')) +channel = connection.channel() +channel.queue_declare(queue='tasks') + +def publish_task(task_data): + channel.basic_publish( + exchange='', + routing_key='tasks', + body=json.dumps(task_data) + ) + +# consumer.py +def callback(ch, method, properties, body): + task = json.loads(body) + process_task(task) + +channel.basic_consume( + queue='tasks', + on_message_callback=callback, + auto_ack=True +) +``` + +**Mermaid 模板**： +```mermaid +graph LR + Producer[任务生产者] -->|发布| Queue[(RabbitMQ
tasks 队列)] + Queue -->|消费| Consumer1[Worker 1] + Queue -->|消费| Consumer2[Worker 2] + Queue -->|消费| Consumer3[Worker 3] + + style Queue fill:#ff6b6b +``` + +--- + +## 4. 数据管道（ETL） + +### 模式 4.1: 顺序管道 + +**代码特征**： +```python +def run_pipeline(source_file): + # Step 1: Extract + raw_data = extract_from_csv(source_file) + + # Step 2: Transform + cleaned_data = remove_duplicates(raw_data) + enriched_data = add_metadata(cleaned_data) + validated_data = validate_schema(enriched_data) + + # Step 3: Load + load_to_database(validated_data) + load_to_s3(validated_data) +``` + +**Mermaid 模板**： +```mermaid +flowchart LR + CSV[CSV 文件] --> Extract[Extract
提取数据] + Extract --> Clean[Clean
去重] + Clean --> Enrich[Enrich
添加元数据] + Enrich --> Validate[Validate
校验] + Validate --> DB[(PostgreSQL)] + Validate --> S3[(S3 存储)] + + style Extract fill:#e1f5ff + style Clean fill:#fff4e1 + style Enrich fill:#e8f5e8 + style Validate fill:#ffe1e1 +``` + +--- + +### 模式 4.2: Airflow DAG + +**代码特征**： +```python +from airflow import DAG +from airflow.operators.python import PythonOperator + +dag = DAG('data_pipeline', schedule_interval='@daily') + +extract_task = PythonOperator( + task_id='extract', + python_callable=extract_data, + dag=dag +) + +transform_task = PythonOperator( + task_id='transform', + python_callable=transform_data, + dag=dag +) + +load_task = PythonOperator( + task_id='load', + python_callable=load_data, + dag=dag +) + +extract_task >> transform_task >> load_task +``` + +**Mermaid 模板**： +```mermaid +graph LR + Start([每日触发]) --> Extract[Extract Task] + Extract --> Transform[Transform Task] + Transform --> Load[Load Task] + Load --> End([完成]) +``` + +--- + +## 5. 分层架构（MVC） + +### 模式 5.1: 三层架构 + +**代码特征**： +```python +# routes.py (Controller 层) +@app.route("/users", methods=["POST"]) +def create_user(): + data = request.json + user = UserService.create(data) # 调用 Service 层 + return jsonify(user.to_dict()) + +# services/user_service.py (Service 层) +class UserService: + @staticmethod + def create(data): + # 业务逻辑 + if not validate_email(data["email"]): + raise ValueError("Invalid email") + + user = User(**data) # 使用 Model 层 + db.session.add(user) + db.session.commit() + return user + +# models/user.py (Model 层) +class User(db.Model): + id = db.Column(db.Integer, primary_key=True) + email = db.Column(db.String(120), unique=True) + name = db.Column(db.String(80)) +``` + +**Mermaid 模板**： +```mermaid +graph TD + Client[HTTP 客户端] -->|POST /users| Controller[Controller
routes.py] + + Controller --> Service[Service 层
user_service.py] + Service --> Model[Model 层
user.py] + Model --> DB[(Database)] + + Service --> Validator[验证器
validate_email] + + style Controller fill:#ff6b6b + style Service fill:#4ecdc4 + style Model fill:#45b7d1 +``` + +--- + +## 6. CQRS 架构 + +### 模式 6.1: 命令查询分离 + +**代码特征**： +```python +# commands/create_order.py (写操作) +class CreateOrderCommand: + def execute(self, order_data): + order = Order(**order_data) + write_db.save(order) + event_bus.emit("order_created", order) + +# queries/get_order.py (读操作) +class GetOrderQuery: + def execute(self, order_id): + return read_db.query(Order).filter_by(id=order_id).first() +``` + +**Mermaid 模板**： +```mermaid +graph TB + Client[客户端] + + Client -->|写操作| CommandHandler[Command Handler] + CommandHandler --> WriteDB[(Write DB
PostgreSQL)] + CommandHandler -->|发布事件| EventBus[Event Bus] + + Client -->|读操作| QueryHandler[Query Handler] + QueryHandler --> ReadDB[(Read DB
Redis/Elasticsearch)] + + EventBus -->|同步| ReadDB + + style CommandHandler fill:#ff6b6b + style QueryHandler fill:#4ecdc4 +``` + +--- + +## 7. 混合架构识别 + +### 示例：微服务 + 事件驱动 + CQRS + +**特征**： +- 多个独立服务（微服务） +- 服务间通过事件通信（事件驱动） +- 每个服务内部 CQRS（命令查询分离） + +**Mermaid 模板**： +```mermaid +graph TB + subgraph "Order Service" + OrderCmd[Command Handler] + OrderQuery[Query Handler] + OrderWriteDB[(Write DB)] + OrderReadDB[(Read DB)] + end + + subgraph "Inventory Service" + InvCmd[Command Handler] + InvQuery[Query Handler] + InvWriteDB[(Write DB)] + InvReadDB[(Read DB)] + end + + EventBus[Event Bus
RabbitMQ] + + OrderCmd --> OrderWriteDB + OrderCmd --> EventBus + OrderQuery --> OrderReadDB + + EventBus -->|order_created| InvCmd + InvCmd --> InvWriteDB + InvQuery --> InvReadDB + + style EventBus fill:#ffd93d +``` + +--- + +## 8. 模式识别决策树 + +``` +1. 检测 docker-compose.yml 或 k8s/ 目录 + → 是: 可能是微服务架构 + → 否: 继续 + +2. 检测 agents/ 目录 OR langgraph/crewai 导入 + → 是: Multi-Agent 架构 + → 否: 继续 + +3. 检测 emit/publish/subscribe + → 是: 事件驱动架构 + → 否: 继续 + +4. 检测 extract/transform/load 函数 + → 是: 数据管道架构 + → 否: 继续 + +5. 检测 routes/ + services/ + models/ + → 是: 分层架构（MVC） + → 否: 继续 + +6. 默认: 通用应用，分析主要调用链 +``` + +--- + +## 9. 使用建议 + +1. **不要生搬硬套** - 并非所有项目都符合标准模式 +2. **可以组合** - 一个项目可能同时使用多种模式 +3. **关注核心** - 识别最重要的架构特征 +4. **标注依据** - 在报告中注明识别依据（代码位置） + +--- + +## 10. 扩展阅读 + +- **Martin Fowler's Architecture Patterns**: https://martinfowler.com/architecture/ +- **Microservices Patterns**: https://microservices.io/patterns/ +- **Event Driven Architecture**: https://martinfowler.com/articles/201701-event-driven.html diff --git a/codebase_architecture_analyzer_v1/reference/quick-scan.md b/codebase_architecture_analyzer_v1/reference/quick-scan.md new file mode 100644 index 0000000..4b62774 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/quick-scan.md @@ -0,0 +1,408 @@ +# 快速扫描指南 + +本指南提供项目快速扫描的详细步骤。 + +## 目标 + +在 30 秒内识别： +- 项目类型 +- 主要编程语言 +- 核心框架 +- 子系统组成 + +--- + +## 步骤 1: 运行技术栈检测脚本（推荐） + +**使用自动化脚本**： + +```bash +python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py . +``` + +**脚本输出示例**： + +```json +{ + "project_path": "/path/to/project", + "stacks": [ + { + "language": "Python", + "frameworks": ["FastAPI", "LangGraph"], + "config_file": "pyproject.toml", + "version": "3.11" + }, + { + "language": "TypeScript", + "frameworks": ["React", "Next.js"], + "version": ">=18" + } + ], + "docker": { + "containerized": true, + "compose": true, + "services": ["backend", "frontend", "redis"] + } +} +``` + +**从输出提取信息**： + +- `stacks[].language` - 主要编程语言 +- `stacks[].frameworks` - 核心框架列表 +- `stacks[].version` - 语言/运行时版本 +- `docker.services` - Docker 服务列表（如果有） + +**脚本支持的语言**： +- Python (FastAPI, Django, Flask, LangGraph, CrewAI) +- JavaScript/TypeScript (React, Vue, Next.js, Express, NestJS) +- Go (Gin, Gorilla Mux, Fiber) +- Rust (Actix Web, Rocket, Axum) +- Java (Spring Boot, Quarkus) + +--- + +## 步骤 1.5: 分析依赖关系（可选，用于深度分析） + +**使用依赖分析脚本**： + +```bash +python ~/.claude/skills/codebase-architecture-analyzer/scripts/extract_dependencies.py . +``` + +**脚本输出示例**： + +```json +{ + "project_path": ".", + "analyses": [ + { + "language": "Python", + "files_analyzed": 45, + "total_imports": 23, + "third_party_imports": ["fastapi", "pydantic", "langchain", "openai"], + "declared_dependencies": ["fastapi", "pydantic", "langchain", "openai", "requests"], + "undeclared_usage": [], + "unused_dependencies": ["requests"] + }, + { + "language": "JavaScript/TypeScript", + "dependencies": ["react", "next", "tailwindcss"], + "dev_dependencies": ["typescript", "@types/react", "eslint"], + "total_dependencies": 6 + } + ] +} +``` + +**关键信息提取**： + +- `third_party_imports` - 实际使用的第三方包 +- `declared_dependencies` - 在配置文件中声明的依赖 +- `undeclared_usage` - **缺失的依赖**（代码中使用了，但未在 requirements.txt/pyproject.toml 中声明） +- `unused_dependencies` - **冗余的依赖**（声明了但代码中未使用） + +**使用场景**： + +✅ **推荐使用**（当满足以下条件时）： +- 需要验证依赖完整性 +- 准备部署到生产环境 +- 项目有复杂的依赖关系 +- 发现依赖相关的 bug + +⚠️ **可跳过**（当满足以下条件时）： +- 快速了解项目即可 +- 项目很小（< 10 个文件） +- 只关注整体架构 + +**输出解读**： + +1. **缺失依赖警告**：如果 `undeclared_usage` 不为空，说明需要更新 requirements.txt +2. **冗余依赖清理**：如果 `unused_dependencies` 不为空，可以移除不需要的依赖 +3. **依赖健康度**：`total_imports` vs `declared_dependencies` 的比例 + +--- + +## 步骤 2: 检测技术栈（手动方法） + +如果脚本无法运行或需要更详细分析，使用以下手动方法： + +### Python 项目 + +**识别文件**： +```bash +# 优先级从高到低 +1. pyproject.toml # 现代 Python 项目（Poetry/Hatch） +2. setup.py # 传统 Python 包 +3. requirements.txt # 依赖清单 +4. Pipfile # Pipenv 项目 +5. environment.yml # Conda 项目 +``` + +**提取信息**： +```bash +# 从 pyproject.toml 提取 +cat pyproject.toml | grep "python =" # Python 版本 +cat pyproject.toml | grep "\[tool.poetry.dependencies\]" -A 20 # 依赖 + +# 从 requirements.txt 提取 +cat requirements.txt | grep -E "fastapi|django|flask|langgraph" +``` + +--- + +### JavaScript/TypeScript 项目 + +**识别文件**： +```bash +1. package.json # Node.js 项目 +2. yarn.lock # Yarn 包管理 +3. pnpm-lock.yaml # pnpm 包管理 +4. tsconfig.json # TypeScript 配置 +``` + +**提取信息**： +```bash +# 从 package.json 提取 +cat package.json | grep "\"react\"\|\"vue\"\|\"express\"\|\"next\"" +``` + +--- + +### Go 项目 + +**识别文件**： +```bash +1. go.mod # Go modules +2. go.sum # 依赖锁文件 +``` + +**提取信息**： +```bash +cat go.mod | grep "require" -A 20 +``` + +--- + +### Rust 项目 + +**识别文件**： +```bash +1. Cargo.toml # Rust 项目配置 +2. Cargo.lock # 依赖锁文件 +``` + +--- + +### Java 项目 + +**识别文件**： +```bash +1. pom.xml # Maven 项目 +2. build.gradle # Gradle 项目 +``` + +--- + +## 步骤 3: 扫描目录结构 + +### 列出顶层目录 + +```bash +ls -d */ | head -20 +``` + +### 识别子系统模式 + +| 目录名 | 子系统类型 | +|-------|-----------| +| `frontend/`, `ui/`, `web/`, `client/` | 前端 | +| `backend/`, `api/`, `server/` | 后端 | +| `agents/`, `workers/` | Agent 系统 | +| `services/` + 多个子目录 | 微服务 | +| `src/components/` | React/Vue 组件 | +| `app/` | Next.js/Django 应用 | + +--- + +## 步骤 4: 检测关键配置文件 + +### Docker 相关 + +```bash +# docker-compose.yml → 多服务架构 +cat docker-compose.yml | grep "services:" -A 50 + +# Dockerfile → 容器化应用 +ls -la | grep Dockerfile +``` + +### 环境配置 + +```bash +# .env.example → 环境变量配置 +cat .env.example | grep -E "DATABASE_URL|REDIS_URL|API_KEY" +``` + +--- + +## 步骤 5: 识别项目规模 + +### 统计代码文件 + +```bash +# 统计各语言文件数量 +find . -type f -name "*.py" | wc -l +find . -type f -name "*.ts" -o -name "*.tsx" | wc -l +find . -type f -name "*.go" | wc -l +``` + +### 估算代码规模 + +```bash +# 使用 cloc（如果已安装） +cloc . --exclude-dir=node_modules,venv,.git +``` + +--- + +## 输出格式模板 + +``` +✓ 项目类型: [AI 研究助手 / Web 应用 / CLI 工具 / ...] +✓ 主语言: Python 3.11 (156 个文件) +✓ 次要语言: TypeScript (89 个文件) +✓ 核心框架: + - 后端: FastAPI 0.104.1 + - 前端: React 18.2.0 + - AI: LangGraph 0.2.5 +✓ 子系统: + - frontend/ (React + TypeScript) + - backend/ (FastAPI + Python) + - agents/ (LangGraph) +✓ 容器化: 是（docker-compose.yml） +✓ 代码规模: 约 12,500 行 +``` + +--- + +## 常见框架识别规则 + +### Python Web 框架 + +```python +依赖中包含: +- fastapi → FastAPI +- django → Django +- flask → Flask +- starlette → Starlette +- aiohttp → aiohttp +``` + +### Python AI 框架 + +```python +依赖中包含: +- langgraph → LangGraph +- crewai → CrewAI +- autogen → AutoGen +- langchain → LangChain +- transformers → Hugging Face +``` + +### JavaScript 框架 + +```json +dependencies 中包含: +- "react" → React +- "vue" → Vue.js +- "next" → Next.js +- "express" → Express.js +- "nestjs" → NestJS +``` + +--- + +## 快速判断项目类型 + +### CLI 工具 + +**特征**： +- 存在 `cli.py`, `main.py`, `cmd/` 目录 +- 依赖包含 `click`, `typer`, `argparse` +- `pyproject.toml` 中有 `[project.scripts]` + +### Web 应用 + +**特征**： +- 存在 `routes.py`, `views.py`, `app.py` +- 依赖包含 `fastapi`, `django`, `express` +- 存在 `assets/`, `static/` 目录 + +### AI/ML 项目 + +**特征**： +- 存在 `models/`, `agents/`, `pipelines/` +- 依赖包含 `tensorflow`, `pytorch`, `langchain` +- 存在 `notebooks/` 目录（Jupyter） + +### 数据工程项目 + +**特征**： +- 存在 `etl/`, `pipelines/`, `dags/` +- 依赖包含 `airflow`, `prefect`, `dbt` +- 存在 `sql/`, `queries/` 目录 + +--- + +## 故障排除 + +### 问题 1: 无法识别项目类型 + +**解决方案**： +1. 查看 README.md 的描述 +2. 搜索常见入口文件：`main.*`, `index.*`, `app.*` +3. 查看 git 提交历史：`git log --oneline | head -20` + +### 问题 2: 多语言混合项目 + +**解决方案**： +- 统计各语言文件数量，确定主次 +- 识别前后端分离：`frontend/` + `backend/` + +--- + +## 完整示例 + +```bash +# 1. 检测配置文件 +ls -la | grep -E "package.json|pyproject.toml|go.mod|Cargo.toml" + +# 输出: pyproject.toml, package.json (前后端分离项目) + +# 2. 读取 Python 依赖 +cat pyproject.toml | grep -A 30 dependencies + +# 输出: fastapi, langgraph, openai (AI Web 应用) + +# 3. 读取 JS 依赖 +cat package.json | grep -A 20 dependencies + +# 输出: react, typescript (React 前端) + +# 4. 扫描目录 +ls -d */ + +# 输出: frontend/, backend/, agents/, docs/ + +# 5. 统计代码 +find backend -name "*.py" | wc -l # 156 个文件 +find frontend -name "*.ts*" | wc -l # 89 个文件 + +# 最终识别结果: +✓ 项目类型: AI 驱动的 Web 应用 +✓ 主语言: Python (后端 + AI) +✓ 次要语言: TypeScript (前端) +✓ 核心框架: FastAPI + LangGraph + React +✓ 架构: 前后端分离 + Multi-Agent +``` diff --git a/codebase_architecture_analyzer_v1/reference/report-generation.md b/codebase_architecture_analyzer_v1/reference/report-generation.md new file mode 100644 index 0000000..9381a91 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/report-generation.md @@ -0,0 +1,259 @@ +# Phase 5: 报告生成指南 + +**执行时间**：约 30 秒 + +**目标**：汇总所有分析结果，生成完整的架构分析报告 + +--- + +## 生成步骤 + +### 步骤 1: 收集所有分析结果 + +从前 4 个 Phase 收集以下信息： + +1. **Phase 1 - 快速扫描** + - 项目类型 + - 主要编程语言 + - 核心框架 + - 子系统列表 + - 代码规模 + +2. **Phase 2 - 系统架构** + - 系统架构 Mermaid 图 + - 子系统清单（名称、路径、技术栈、入口文件） + - 通信关系列表 + +3. **Phase 3 - 核心流程** + - 工作流 Mermaid 图（stateDiagram-v2 / flowchart） + - 执行单元清单（Agent / 服务 / 函数） + - 关键决策点 + +4. **Phase 4 - 数据流** + - 序列图 Mermaid + - 数据模型清单 + - 数据转换链路 + +### 步骤 2: 使用模板生成报告 + +使用 `assets/report.md` 模板，将收集的信息填充到相应章节。 + +### 步骤 3: 添加快速上手指南 + +从项目文件中提取以下信息： + +1. **环境要求** + - 从 README.md 或 pyproject.toml 提取 + - Python/Node.js 版本要求 + - 系统依赖（Docker、Redis 等） + +2. **安装步骤** + - 依赖安装命令 + - 环境变量配置 + - 数据库初始化 + +3. **启动命令** + - 开发环境启动命令 + - 生产环境部署命令 + - 测试运行命令 + +4. **核心入口文件** + - 主入口文件路径 + - 配置文件路径 + - 关键模块路径 + +### 步骤 4: 生成代码位置索引 + +汇总所有关键文件的位置： + +``` +代码位置索引: +├─ 入口文件 +│ ├─ 后端入口: backend/app/main.py:1 +│ └─ 前端入口: frontend/src/main.tsx:1 +├─ 核心模块 +│ ├─ Agent 编排: agents/graph.py:23 +│ ├─ 研究 Agent: agents/nodes.py:45 +│ └─ 写作 Agent: agents/nodes.py:78 +├─ API 端点 +│ ├─ 研究 API: backend/app/routes.py:42 +│ └─ WebSocket: backend/app/routes.py:58 +└─ 数据模型 + ├─ ResearchTask: models/task.py:8 + └─ Report: models/report.py:22 +``` + +### 步骤 5: 保存报告 + +将生成的报告保存到项目根目录： + +- **保存路径**: `PROJECT_ARCHITECTURE.md` + +--- + +## 报告结构模板 + +```markdown +# [项目名] 架构分析报告 + +> 生成时间: [YYYY-MM-DD HH:MM:SS] +> 分析工具: Claude Code - Codebase Architecture Analyzer + +--- + +## 一、项目概览 + +**项目类型**: [自动推断] +**主要语言**: [Python 3.11] +**核心框架**: [FastAPI + LangGraph] +**代码规模**: [156 个 Python 文件, 89 个 TypeScript 文件] + +**子系统**: +- frontend/ (React + TypeScript) +- backend/ (FastAPI + Python) +- agents/ (LangGraph) + +--- + +## 二、系统架构 + +### 2.1 架构图 + +```mermaid +[Phase 2 生成的 Mermaid 图] +``` + +### 2.2 子系统详情 + +[Phase 2 生成的子系统清单] + +### 2.3 通信机制 + +[Phase 2 生成的通信关系列表] + +--- + +## 三、核心业务流程 + +### 3.1 流程图 + +```mermaid +[Phase 3 生成的 Mermaid 图] +``` + +### 3.2 执行单元清单 + +[Phase 3 生成的 Agent/服务/函数清单] + +### 3.3 关键决策点 + +[Phase 3 识别的条件分支和路由规则] + +--- + +## 四、数据流分析 + +### 4.1 序列图 + +```mermaid +[Phase 4 生成的 Mermaid 序列图] +``` + +### 4.2 数据模型清单 + +[Phase 4 生成的数据模型列表] + +### 4.3 数据转换链路 + +[Phase 4 追踪的数据流转路径] + +--- + +## 五、快速上手指南 + +### 5.1 环境要求 + +- Python 3.11+ +- Node.js 18+ +- Docker (可选) + +### 5.2 安装步骤 + +```bash +# 1. 安装后端依赖 +pip install -r backend/requirements.txt + +# 2. 安装前端依赖 +cd frontend && npm install + +# 3. 配置环境变量 +cp .env.example .env +``` + +### 5.3 启动命令 + +```bash +# 启动后端 +cd backend && uvicorn app.main:app --reload + +# 启动前端 +cd frontend && npm start +``` + +### 5.4 核心入口文件 + +- 后端入口: `backend/app/main.py` +- 前端入口: `frontend/src/main.tsx` +- Agent 编排: `agents/graph.py` + +--- + +## 六、代码位置索引 + +[Phase 2-4 汇总的所有关键文件位置] + +--- + +## 附录：分析方法说明 + +本报告由 Claude Code 的 `codebase-architecture-analyzer` Skill 自动生成。 + +分析方法: +- Phase 1: 快速扫描（识别技术栈） +- Phase 2: 系统架构分析（Explore sub-agent） +- Phase 3: 核心流程提取（智能模式识别） +- Phase 4: 数据流追踪（类型追踪） +- Phase 5: 报告生成（本文档） +``` + +--- + +## 输出示例 + +执行完成后，向用户显示： + +``` +✓ 分析完成！ + +报告已保存: PROJECT_ARCHITECTURE.md + +核心发现: +- 采用 LangGraph 编排 Multi-Agent 工作流 +- 支持条件路由和循环优化 +- 数据流: 查询 → 搜索 → 写作 → 审核 → 报告 + +快速上手: +1. 安装依赖: pip install -r requirements.txt +2. 配置环境: cp .env.example .env +3. 启动后端: uvicorn app.main:app --reload +4. 启动前端: cd frontend && npm start +``` + +--- + +## 注意事项 + +1. **Mermaid 图表检查**：确保所有 Mermaid 代码块语法正确 +2. **代码位置准确性**：所有文件路径和行号必须准确 +3. **快速上手可用性**：安装步骤必须可执行，不能遗漏关键步骤 +4. **避免敏感信息**：不要在报告中包含 `.env` 文件内容或 API 密钥 diff --git a/codebase_architecture_analyzer_v1/reference/system-analysis.md b/codebase_architecture_analyzer_v1/reference/system-analysis.md new file mode 100644 index 0000000..9af8ae9 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/system-analysis.md @@ -0,0 +1,124 @@ +# Phase 2: 系统架构分析指南 + +**执行时间**：约 2 分钟 + +**目标**：识别子系统边界和通信机制 + +--- + +## ⚠️ 重要约束 + +**Explore agent 只返回文本结果，不要生成任何文件。** + +--- + +## 分析方法 + +使用 **Task tool** 调用内置的 **Explore sub-agent** 进行深度分析。 + +### 步骤 1: 启动 Task tool + +指定以下参数： +- `subagent_type: Explore` +- `description: "系统架构分析"` +- `prompt`: 包含下面的详细任务 + +### 步骤 2: Sub-agent 任务定义 + +``` +⚠️ 重要约束：本次分析只返回文本结果，禁止生成任何文件（.md, .txt 等）。 +所有 Mermaid 图表、清单、分析结论都应包含在你的文本回复中，不要使用 Write 或其他文件创建工具。 + +分析项目的子系统划分和通信机制： + +1. 子系统边界识别 + - 扫描顶层目录，识别 frontend/, backend/, agents/ 等模式 + - 查找独立配置文件（package.json, requirements.txt） + - 解析 docker-compose.yml 中的 services + +2. API 端点定位 + - 搜索：@app.(get|post|put|delete) + - 搜索：@router., app.route + - 提取端点路径和处理函数位置 + +3. 通信协议识别 + - HTTP: requests.get/post, axios, fetch + - WebSocket: WebSocket, socket.io + - 消息队列: RabbitMQ, Kafka, Redis pub/sub + - gRPC: grpc, .proto + +4. 数据库连接 + - PostgreSQL: psycopg2, SQLAlchemy + - Redis: redis.Redis + - MongoDB: pymongo + +输出格式： +- 子系统清单（名称、路径、技术栈、入口文件:行号） +- 通信关系（from → to, 协议, 端点） +- 生成 Mermaid graph TB 架构图（使用 `
` 换行） +``` + +### 步骤 3: 执行过程 + +1. **Explore sub-agent 自动执行**：使用 Glob、Grep、Read 工具搜索代码 +2. **接收结果**：sub-agent 返回分析报告 +3. **验证结果**：检查是否包含所有子系统和通信关系 + +--- + +## 预期输出格式 + +### 1. Mermaid 系统架构图 + +```mermaid +graph TB + User[用户] --> Frontend[前端
React + TypeScript] + Frontend -->|HTTP POST /api/research| Backend[后端 API
FastAPI] + Frontend -->|WebSocket /ws| Backend + Backend -->|invoke| AgentLayer[Agent 编排层
LangGraph] + AgentLayer -->|缓存| Redis[(Redis)] + AgentLayer -->|持久化| DB[(PostgreSQL)] + + style AgentLayer fill:#f9f,stroke:#333,stroke-width:3px +``` + +### 2. 代码位置索引 + +- Frontend 入口: `frontend/src/main.tsx:1` +- Backend 入口: `backend/app/main.py:1` +- API 定义: `backend/app/routes.py:42` +- Agent 调用: `backend/app/routes.py:58` + +### 3. 子系统清单 + +``` +识别出 3 个子系统: +├─ Frontend (frontend/) +│ ├─ 技术: React 18 + TypeScript +│ └─ 入口: src/main.tsx:1 +├─ Backend (backend/) +│ ├─ 技术: FastAPI + Python 3.11 +│ └─ 入口: app/main.py:1 +└─ Agent Layer (agents/) + ├─ 技术: LangGraph 0.2.5 + └─ 入口: graph.py:1 +``` + +### 4. 通信机制 + +``` +- Frontend → Backend: WebSocket (/ws) +- Frontend → Backend: HTTP POST (/api/research) +- Backend → Agent Layer: 直接调用 invoke() +- Agent Layer → Redis: 缓存中间结果 +- Agent Layer → PostgreSQL: 持久化数据 +``` + +--- + +## 注意事项 + +1. **配置文件优先**：优先解析 docker-compose.yml，它通常包含完整的服务拓扑 +2. **多种通信协议**：一个项目可能同时使用 HTTP、WebSocket、消息队列 +3. **入口文件定位**：确保记录每个子系统的主入口文件和行号 +4. **Mermaid 样式**：使用 `style` 语法突出显示核心子系统 diff --git a/codebase_architecture_analyzer_v1/reference/workflow-extraction.md b/codebase_architecture_analyzer_v1/reference/workflow-extraction.md new file mode 100644 index 0000000..7476f48 --- /dev/null +++ b/codebase_architecture_analyzer_v1/reference/workflow-extraction.md @@ -0,0 +1,582 @@ +# 工作流提取详细指南 + +本指南提供通用的工作流提取算法，适用于各种架构模式。 + +## ⚠️ 重要约束 + +**在调用 Task tool 时，必须在 prompt 开头包含以下约束：** + +``` +⚠️ 重要约束：本次分析只返回文本结果，禁止生成任何文件（.md, .txt 等）。 +所有 Mermaid 图表、清单、分析结论都应包含在你的文本回复中，不要使用 Write 或其他文件创建工具。 +``` + +**Explore agent 只返回文本结果，不要生成任何文件。** + +--- + +## 核心思想 + +**不预设架构类型，而是从代码中提取执行流程特征。** + +--- + +## 算法概览 + +``` +1. 定位入口点（CLI/Web/定时任务） +2. 提取函数调用链（递归追踪） +3. 识别业务函数（排除辅助函数） +4. 分析流程模式（顺序/分支/循环/并发） +5. 生成 Mermaid 图表 +``` + +--- + +## 步骤 1: 定位入口点 + +### 1.1 CLI 应用 + +**Python**: +```bash +grep -rn "if __name__ == '__main__'" --include="*.py" +grep -rn "@click.command\|@click.group" --include="*.py" +grep -rn "argparse.ArgumentParser" --include="*.py" +``` + +**示例**: +```python +# main.py:45 +if __name__ == "__main__": + main() # ← 入口函数 +``` + +**Go**: +```bash +grep -rn "func main()" --include="*.go" +``` + +--- + +### 1.2 Web 应用 + +**FastAPI/Flask**: +```bash +grep -rn "@app\.(get|post|put|delete)" --include="*.py" +grep -rn "@router\." --include="*.py" +``` + +**示例**: +```python +# routes.py:42 +@app.post("/api/research") # ← 入口点 +def research_endpoint(query: str): + ... +``` + +**Express.js**: +```bash +grep -rn "app\.(get|post)" --include="*.js" +grep -rn "router\." --include="*.js" +``` + +--- + +### 1.3 定时任务 + +**Celery**: +```bash +grep -rn "@celery.task\|@shared_task" --include="*.py" +``` + +**Airflow**: +```bash +grep -rn "DAG(" --include="*.py" +``` + +**Cron/APScheduler**: +```bash +grep -rn "@schedule\|@cron" --include="*.py" +``` + +--- + +### 1.4 消息消费者 + +**RabbitMQ/Kafka**: +```bash +grep -rn "basic_consume\|KafkaConsumer" --include="*.py" +``` + +**示例**: +```python +# consumer.py:25 +def callback(ch, method, properties, body): # ← 入口点 + process_message(body) +``` + +--- + +## 步骤 2: 提取函数调用链 + +### 2.1 读取入口函数 + +从步骤 1 识别的入口点开始： + +```python +# 示例：routes.py:42 +@app.post("/api/research") +def research_endpoint(query: str): + task = create_task(query) # 调用 1 + results = executor.run(task) # 调用 2 + return format_response(results) # 调用 3 +``` + +**提取调用清单**: +``` +research_endpoint +├── create_task +├── executor.run +└── format_response +``` + +--- + +### 2.2 递归追踪 + +读取 `executor.run` 的实现： + +```python +# executor.py:78 +def run(self, task): + data = self.fetch_data(task) # 调用 2.1 + processed = self.process(data) # 调用 2.2 + return self.finalize(processed) # 调用 2.3 +``` + +**更新调用树**: +``` +research_endpoint +├── create_task +├── executor.run +│ ├── fetch_data +│ ├── process +│ └── finalize +└── format_response +``` + +--- + +### 2.3 控制递归深度 + +**问题**: 可能陷入无限递归 + +**解决方案**: 限制最大深度 + +```python +MAX_DEPTH = 5 # 最多追踪 5 层 + +def trace_calls(func_name, depth=0): + if depth >= MAX_DEPTH: + return [] + + calls = extract_calls_from_function(func_name) + result = [] + + for call in calls: + result.append(call) + result.extend(trace_calls(call, depth + 1)) + + return result +``` + +--- + +## 步骤 3: 识别业务函数 + +### 3.1 排除辅助函数 + +**规则**: + +| 函数特征 | 是否保留 | +|---------|---------| +| 私有函数 `_helper()` | ❌ 排除 | +| 工具函数 `format_date()` | ❌ 排除 | +| Getter/Setter | ❌ 排除 | +| 函数体 < 5 行 | ❌ 排除 | +| 包含业务关键词 | ✅ 保留 | +| 调用数据库/外部 API | ✅ 保留 | +| 处理核心数据模型 | ✅ 保留 | + +--- + +### 3.2 业务关键词清单 + +```python +BUSINESS_KEYWORDS = [ + # 处理动词 + "process", "handle", "execute", "run", + + # CRUD 操作 + "create", "update", "delete", "query", "fetch", + + # 业务逻辑 + "calculate", "analyze", "generate", "transform", + "search", "filter", "validate", "verify", + + # 工作流 + "orchestrate", "coordinate", "schedule" +] +``` + +**示例判断**: +```python +✅ process_order() # 包含 "process" +✅ create_user() # 包含 "create" +✅ analyze_data() # 包含 "analyze" +❌ format_string() # 工具函数 +❌ _internal_helper() # 私有函数 +❌ get_config() # Getter +``` + +--- + +### 3.3 检测数据库/API 调用 + +**数据库调用**: +```python +def create_user(data): + user = User(**data) + db.session.add(user) # ✅ 数据库操作 + db.session.commit() + return user +``` + +**外部 API 调用**: +```python +def fetch_weather(city): + response = requests.get( # ✅ 外部 API + f"https://api.weather.com/{city}" + ) + return response.json() +``` + +**搜索模式**: +```bash +# 数据库 +grep -n "db\.session\|query(\|execute(" file.py + +# HTTP 请求 +grep -n "requests\.\|httpx\.\|fetch(" file.py +``` + +--- + +## 步骤 4: 分析流程模式 + +### 4.1 顺序流程 + +**代码特征**: +```python +def process(): + step1() + step2() + step3() +``` + +**识别**: 连续的函数调用，无分支 + +**生成图表**: `flowchart TD` (从上到下) + +--- + +### 4.2 条件分支 + +**代码特征**: +```python +def process(data): + if validate(data): + path_a() + else: + path_b() +``` + +**识别**: `if/else`, `match/case`, 三元运算符 + +**生成图表**: `flowchart TD` (带菱形决策节点) + +--- + +### 4.3 循环优化 + +**代码特征**: +```python +def optimize(data): + while not is_good_enough(data): + data = improve(data) + return data +``` + +**识别**: `while` + 条件判断 + +**生成图表**: `flowchart TD` (带循环边) + +--- + +### 4.4 状态机 + +**代码特征**: +```python +state = "init" + +if state == "init": + state = "processing" +elif state == "processing": + if condition: + state = "done" + else: + state = "error" +``` + +**识别**: 状态变量 + 状态转换逻辑 + +**生成图表**: `stateDiagram-v2` + +--- + +### 4.5 并发编排 + +**Python asyncio**: +```python +results = await asyncio.gather( + task1(), + task2(), + task3() +) +``` + +**JavaScript Promise.all**: +```javascript +const results = await Promise.all([ + fetchUser(), + fetchOrders(), + fetchProducts() +]); +``` + +**识别**: `asyncio.gather`, `Promise.all`, `WaitGroup` + +**生成图表**: `graph TB` + subgraph (并行任务分组) + +--- + +### 4.6 图编排（LangGraph） + +**代码特征**: +```python +graph = StateGraph(State) +graph.add_node("a", func_a) +graph.add_node("b", func_b) +graph.add_edge("a", "b") +graph.add_conditional_edges("b", router, { + "continue": "a", + "end": END +}) +``` + +**识别**: `add_node`, `add_edge`, `add_conditional_edges` + +**生成图表**: `stateDiagram-v2` + +--- + +## 步骤 5: 生成 Mermaid 图表 + +**⚠️ Mermaid 语法约束（版本 11.x）**： +- **stateDiagram-v2**: 禁用 `--` 分隔符，不支持 `
` +- **sequenceDiagram**: `alt/loop/par` 块必须正确配对 `end` +- **所有类型**: 使用 `
` 换行（stateDiagram-v2 除外） + +### 5.1 选择图表类型 + +```python +def select_diagram_type(flow_pattern): + if flow_pattern == "state_machine": + return "stateDiagram-v2" + + elif flow_pattern == "concurrent": + return "graph TB" # 带 subgraph + + elif flow_pattern == "sequential_with_conditions": + return "flowchart TD" + + elif flow_pattern == "linear_pipeline": + return "flowchart LR" + + else: + return "graph TB" # 默认 +``` + +--- + +### 5.2 生成状态图（Multi-Agent） + +**输入数据**: +```python +nodes = [ + {"name": "researcher", "file": "agents/nodes.py", "line": 45}, + {"name": "writer", "file": "agents/nodes.py", "line": 78} +] + +edges = [ + {"from": "researcher", "to": "writer"}, + { + "from": "writer", + "to": "researcher", + "condition": "quality < 7" + } +] +``` + +**生成代码**: +```python +def generate_state_diagram(nodes, edges): + mermaid = "stateDiagram-v2\n" + mermaid += f" [*] --> {nodes[0]['name']}\n" + + for edge in edges: + if "condition" in edge: + mermaid += f" {edge['from']} --> {edge['to']}: {edge['condition']}\n" + else: + mermaid += f" {edge['from']} --> {edge['to']}\n" + + # 添加注释 + for node in nodes: + mermaid += f"\n note right of {node['name']}\n" + mermaid += f" {node['file']}:{node['line']}\n" + mermaid += f" end note\n" + + return mermaid +``` + +--- + +### 5.3 生成流程图（顺序+分支） + +**输入数据**: +```python +steps = [ + {"name": "extract", "type": "process"}, + {"name": "validate", "type": "decision"}, + {"name": "transform", "type": "process"}, + {"name": "load", "type": "process"} +] + +connections = [ + {"from": "extract", "to": "validate"}, + {"from": "validate", "to": "transform", "condition": "valid"}, + {"from": "validate", "to": "error_handler", "condition": "invalid"} +] +``` + +**生成代码**: +```python +def generate_flowchart(steps, connections): + mermaid = "flowchart TD\n" + + # 定义节点 + for step in steps: + if step["type"] == "decision": + mermaid += f" {step['name']}{{{step['name']}}}\n" # 菱形 + else: + mermaid += f" {step['name']}[{step['name']}]\n" # 矩形 + + # 连接 + for conn in connections: + if "condition" in conn: + mermaid += f" {conn['from']} -->|{conn['condition']}| {conn['to']}\n" + else: + mermaid += f" {conn['from']} --> {conn['to']}\n" + + return mermaid +``` + +--- + +## 完整示例 + +### 示例代码 + +```python +# routes.py:42 +@app.post("/api/research") +def research_endpoint(query: str): + task = create_research_task(query) + results = execute_research(task) + return results + +# research.py:15 +def execute_research(task): + # 并发搜索 + search_results = asyncio.gather( + search_google(task.query), + search_arxiv(task.query) + ) + + # 生成报告 + if len(search_results) > 5: + report = generate_detailed_report(search_results) + else: + report = generate_summary(search_results) + + return report +``` + +--- + +### 提取结果 + +**入口点**: `research_endpoint` (routes.py:42) + +**调用链**: +``` +research_endpoint +├── create_research_task +└── execute_research + ├── search_google (并发) + ├── search_arxiv (并发) + └── generate_detailed_report OR generate_summary (条件) +``` + +**流程模式**: 顺序 + 并发 + 条件分支 + +--- + +### 生成 Mermaid 图 + +```mermaid +flowchart TD + Start([API 请求]) --> CreateTask[创建研究任务] + CreateTask --> Concurrent{并发搜索} + + Concurrent --> Google[搜索 Google] + Concurrent --> ArXiv[搜索 ArXiv] + + Google --> Merge[合并结果] + ArXiv --> Merge + + Merge --> Decision{结果数量} + Decision -->|> 5 篇| Detailed[生成详细报告] + Decision -->|≤ 5 篇| Summary[生成摘要] + + Detailed --> End([返回结果]) + Summary --> End +``` + +## 最佳实践 + +1. **先广度后深度** - 先了解整体流程 +2. **限制递归深度** - 避免无限循环 +3. **过滤辅助函数** - 只关注业务逻辑 +4. **标注代码位置** - 便于验证 +5. **可视化优先** - 图表比文字更直观 diff --git a/codebase_architecture_analyzer_v1/scripts/detect_tech_stack.py b/codebase_architecture_analyzer_v1/scripts/detect_tech_stack.py new file mode 100644 index 0000000..7350c8c --- /dev/null +++ b/codebase_architecture_analyzer_v1/scripts/detect_tech_stack.py @@ -0,0 +1,266 @@ +#!/usr/bin/env python3 +""" +技术栈检测脚本 + +用法: python detect_tech_stack.py [项目路径] + +输出: JSON 格式的技术栈信息 +""" + +import json +import sys +from pathlib import Path +from typing import Dict, List, Optional + + +def detect_python_stack(project_path: Path) -> Optional[Dict]: + """检测 Python 技术栈""" + result = {"language": "Python", "frameworks": [], "dependencies": []} + + # 查找配置文件 + pyproject = project_path / "pyproject.toml" + requirements = project_path / "requirements.txt" + setup_py = project_path / "setup.py" + + if pyproject.exists(): + content = pyproject.read_text(encoding='utf-8') + result["config_file"] = "pyproject.toml" + + # 检测 Python 版本 + if 'python = "^' in content: + version = content.split('python = "^')[1].split('"')[0] + result["version"] = version + + # 检测框架 + if "fastapi" in content.lower(): + result["frameworks"].append("FastAPI") + if "django" in content.lower(): + result["frameworks"].append("Django") + if "flask" in content.lower(): + result["frameworks"].append("Flask") + if "langgraph" in content.lower(): + result["frameworks"].append("LangGraph") + if "crewai" in content.lower(): + result["frameworks"].append("CrewAI") + + elif requirements.exists(): + content = requirements.read_text(encoding='utf-8') + result["config_file"] = "requirements.txt" + + # 检测框架 + for line in content.split('\n'): + line = line.strip().lower() + if line.startswith('fastapi'): + result["frameworks"].append("FastAPI") + elif line.startswith('django'): + result["frameworks"].append("Django") + elif line.startswith('flask'): + result["frameworks"].append("Flask") + elif line.startswith('langgraph'): + result["frameworks"].append("LangGraph") + + else: + return None + + return result + + +def detect_javascript_stack(project_path: Path) -> Optional[Dict]: + """检测 JavaScript/TypeScript 技术栈""" + package_json = project_path / "package.json" + + if not package_json.exists(): + return None + + result = {"language": "JavaScript/TypeScript", "frameworks": [], "dependencies": []} + + try: + import json as json_module + content = json_module.loads(package_json.read_text(encoding='utf-8')) + + # 检测框架 + deps = {**content.get("dependencies", {}), **content.get("devDependencies", {})} + + if "react" in deps: + result["frameworks"].append("React") + if "@types/react" in deps: + result["language"] = "TypeScript" + if "vue" in deps: + result["frameworks"].append("Vue.js") + if "next" in deps: + result["frameworks"].append("Next.js") + if "express" in deps: + result["frameworks"].append("Express.js") + if "@nestjs/core" in deps: + result["frameworks"].append("NestJS") + + # 检测 Node 版本 + if "engines" in content and "node" in content["engines"]: + result["version"] = content["engines"]["node"] + + except Exception as e: + print(f"Error parsing package.json: {e}", file=sys.stderr) + return None + + return result + + +def detect_go_stack(project_path: Path) -> Optional[Dict]: + """检测 Go 技术栈""" + go_mod = project_path / "go.mod" + + if not go_mod.exists(): + return None + + result = {"language": "Go", "frameworks": [], "dependencies": []} + + content = go_mod.read_text(encoding='utf-8') + + # 检测 Go 版本 + for line in content.split('\n'): + if line.strip().startswith('go '): + result["version"] = line.strip().split()[1] + break + + # 检测框架 + if "gin-gonic/gin" in content: + result["frameworks"].append("Gin") + if "gorilla/mux" in content: + result["frameworks"].append("Gorilla Mux") + if "fiber" in content: + result["frameworks"].append("Fiber") + + return result + + +def detect_rust_stack(project_path: Path) -> Optional[Dict]: + """检测 Rust 技术栈""" + cargo_toml = project_path / "Cargo.toml" + + if not cargo_toml.exists(): + return None + + result = {"language": "Rust", "frameworks": [], "dependencies": []} + + content = cargo_toml.read_text(encoding='utf-8') + + # 检测框架 + if "actix-web" in content: + result["frameworks"].append("Actix Web") + if "rocket" in content: + result["frameworks"].append("Rocket") + if "axum" in content: + result["frameworks"].append("Axum") + + return result + + +def detect_java_stack(project_path: Path) -> Optional[Dict]: + """检测 Java 技术栈""" + pom_xml = project_path / "pom.xml" + build_gradle = project_path / "build.gradle" + + if pom_xml.exists(): + result = {"language": "Java", "frameworks": [], "build_tool": "Maven"} + content = pom_xml.read_text(encoding='utf-8') + + # 检测框架 + if "spring-boot" in content: + result["frameworks"].append("Spring Boot") + if "quarkus" in content: + result["frameworks"].append("Quarkus") + + return result + + elif build_gradle.exists(): + result = {"language": "Java", "frameworks": [], "build_tool": "Gradle"} + content = build_gradle.read_text(encoding='utf-8') + + # 检测框架 + if "spring-boot" in content: + result["frameworks"].append("Spring Boot") + + return result + + return None + + +def detect_docker_usage(project_path: Path) -> Dict: + """检测 Docker 使用情况""" + docker_compose = project_path / "docker-compose.yml" + dockerfile = project_path / "Dockerfile" + + result = {"containerized": False, "services": []} + + if docker_compose.exists(): + result["containerized"] = True + result["compose"] = True + + # 简单解析 services + content = docker_compose.read_text(encoding='utf-8') + in_services = False + for line in content.split('\n'): + if line.strip() == "services:": + in_services = True + continue + if in_services and line.startswith(' ') and ':' in line and not line.strip().startswith('#'): + service_name = line.strip().rstrip(':') + if service_name and not service_name.startswith('-'): + result["services"].append(service_name) + + elif dockerfile.exists(): + result["containerized"] = True + result["compose"] = False + + return result + + +def main(): + # 获取项目路径 + if len(sys.argv) > 1: + project_path = Path(sys.argv[1]) + else: + project_path = Path.cwd() + + if not project_path.exists(): + print(f"Error: Path {project_path} does not exist", file=sys.stderr) + sys.exit(1) + + # 检测各种技术栈 + stacks = [] + + python_stack = detect_python_stack(project_path) + if python_stack: + stacks.append(python_stack) + + js_stack = detect_javascript_stack(project_path) + if js_stack: + stacks.append(js_stack) + + go_stack = detect_go_stack(project_path) + if go_stack: + stacks.append(go_stack) + + rust_stack = detect_rust_stack(project_path) + if rust_stack: + stacks.append(rust_stack) + + java_stack = detect_java_stack(project_path) + if java_stack: + stacks.append(java_stack) + + # 检测 Docker + docker_info = detect_docker_usage(project_path) + + # 输出结果 + result = { + "project_path": str(project_path), + "stacks": stacks, + "docker": docker_info + } + + print(json.dumps(result, indent=2, ensure_ascii=False)) + + +if __name__ == "__main__": + main() diff --git a/codebase_architecture_analyzer_v1/scripts/extract_dependencies.py b/codebase_architecture_analyzer_v1/scripts/extract_dependencies.py new file mode 100644 index 0000000..ad420ac --- /dev/null +++ b/codebase_architecture_analyzer_v1/scripts/extract_dependencies.py @@ -0,0 +1,167 @@ +#!/usr/bin/env python3 +""" +依赖提取脚本 + +用法: python extract_dependencies.py [项目路径] + +输出: JSON 格式的依赖信息 +""" + +import ast +import json +import sys +from pathlib import Path +from typing import Dict, List, Set + + +def extract_python_imports(file_path: Path) -> Set[str]: + """从 Python 文件提取 import""" + imports = set() + + try: + with open(file_path, 'r', encoding='utf-8') as f: + tree = ast.parse(f.read(), filename=str(file_path)) + + for node in ast.walk(tree): + if isinstance(node, ast.Import): + for alias in node.names: + # 只保留顶层包名 + module = alias.name.split('.')[0] + imports.add(module) + + elif isinstance(node, ast.ImportFrom): + if node.module: + module = node.module.split('.')[0] + imports.add(module) + + except Exception as e: + print(f"Warning: Failed to parse {file_path}: {e}", file=sys.stderr) + + return imports + + +def analyze_python_project(project_path: Path) -> Dict: + """分析 Python 项目的依赖""" + all_imports = set() + file_count = 0 + + # 遍历所有 Python 文件 + for py_file in project_path.rglob("*.py"): + # 跳过虚拟环境和 node_modules + if any(part in py_file.parts for part in ['venv', 'env', '.venv', 'node_modules', '__pycache__']): + continue + + file_count += 1 + imports = extract_python_imports(py_file) + all_imports.update(imports) + + # 读取声明的依赖 + declared_deps = set() + + requirements_txt = project_path / "requirements.txt" + if requirements_txt.exists(): + for line in requirements_txt.read_text(encoding='utf-8').split('\n'): + line = line.strip() + if line and not line.startswith('#'): + # 去掉版本号 + dep = line.split('==')[0].split('>=')[0].split('~=')[0].strip() + declared_deps.add(dep) + + pyproject_toml = project_path / "pyproject.toml" + if pyproject_toml.exists(): + content = pyproject_toml.read_text(encoding='utf-8') + # 简单提取（不使用 toml 库） + in_deps = False + for line in content.split('\n'): + if '[tool.poetry.dependencies]' in line or '[project.dependencies]' in line: + in_deps = True + continue + if in_deps and line.strip().startswith('['): + break + if in_deps and '=' in line: + dep = line.split('=')[0].strip().strip('"') + if dep != 'python': + declared_deps.add(dep) + + # Python 标准库（部分常见的） + stdlib = { + 'os', 'sys', 'json', 'time', 'datetime', 'collections', 'itertools', + 'functools', 'pathlib', 're', 'math', 'random', 'typing', 'abc', + 'asyncio', 'logging', 'unittest', 'argparse', 'subprocess', 'io', + 'copy', 'pickle', 'sqlite3', 'http', 'urllib', 'email', 'uuid' + } + + # 区分第三方包和标准库 + third_party = all_imports - stdlib + + return { + "language": "Python", + "files_analyzed": file_count, + "total_imports": len(all_imports), + "third_party_imports": list(sorted(third_party)), + "declared_dependencies": list(sorted(declared_deps)), + "undeclared_usage": list(sorted(third_party - declared_deps)), + "unused_dependencies": list(sorted(declared_deps - third_party)) + } + + +def analyze_javascript_project(project_path: Path) -> Dict: + """分析 JavaScript 项目的依赖""" + package_json = project_path / "package.json" + + if not package_json.exists(): + return None + + try: + import json as json_module + content = json_module.loads(package_json.read_text(encoding='utf-8')) + + dependencies = content.get("dependencies", {}) + dev_dependencies = content.get("devDependencies", {}) + + return { + "language": "JavaScript/TypeScript", + "dependencies": list(dependencies.keys()), + "dev_dependencies": list(dev_dependencies.keys()), + "total_dependencies": len(dependencies) + len(dev_dependencies) + } + + except Exception as e: + print(f"Error parsing package.json: {e}", file=sys.stderr) + return None + + +def main(): + # 获取项目路径 + if len(sys.argv) > 1: + project_path = Path(sys.argv[1]) + else: + project_path = Path.cwd() + + if not project_path.exists(): + print(f"Error: Path {project_path} does not exist", file=sys.stderr) + sys.exit(1) + + results = [] + + # 分析 Python + python_result = analyze_python_project(project_path) + if python_result["files_analyzed"] > 0: + results.append(python_result) + + # 分析 JavaScript + js_result = analyze_javascript_project(project_path) + if js_result: + results.append(js_result) + + # 输出结果 + output = { + "project_path": str(project_path), + "analyses": results + } + + print(json.dumps(output, indent=2, ensure_ascii=False)) + + +if __name__ == "__main__": + main() diff --git a/codebase_architecture_analyzer_v1/skill.md b/codebase_architecture_analyzer_v1/skill.md new file mode 100644 index 0000000..2e554c5 --- /dev/null +++ b/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 等常见依赖目录 + +--- + +现在开始分析当前项目。