AIEC_Skills/codebase_architecture_analyzer_v1/reference/examples.md

# 使用示例

本文档提供实际使用场景的示例。

## 示例 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[前端<br/>React + TypeScript]
    Frontend -->|WebSocket /ws| Backend[后端 API<br/>FastAPI]
    Frontend -->|POST /api/research| Backend
    Backend -->|invoke| AgentLayer[Agent 编排层<br/>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: 质量不足<br/>评分 < 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<br/>{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<br/>:8000]

    Gateway -->|GET /users/:id| UserSvc[User Service<br/>:8001]
    Gateway -->|POST /orders| OrderSvc[Order Service<br/>:8002]
    Gateway -->|POST /notify| NotifySvc[Notification Service<br/>:8003]

    UserSvc --> UserDB[(User DB<br/>PostgreSQL)]
    OrderSvc --> OrderDB[(Order DB<br/>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<br/>提取数据]
    Extract --> Clean[Clean<br/>去重]
    Clean --> Enrich[Enrich<br/>添加元数据]
    Enrich --> Validate[Validate<br/>校验]
    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` 了解各种架构模式的详细识别案例。