9.6 KiB
9.6 KiB
使用示例
本文档提供实际使用场景的示例。
示例 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: 持久化数据
生成的架构图:
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 → 结束流程
生成的流程图:
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)
生成的序列图:
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
生成的架构图:
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] ✓ 数据管道流程图已生成
生成的流程图:
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. 项目克隆后立即分析
git clone https://github.com/user/project.git
cd project
# 打开 Claude Code
理解项目
优势：快速建立项目全景认知。
2. 结合其他 Skills
理解项目，然后生成开发者入门文档
先分析架构，再基于分析结果生成文档。
3. 针对性分析
只分析后端的 API 路由和业务逻辑
节省时间，聚焦关键部分。
故障排除示例
问题: 无法识别自定义框架
场景: 公司内部自研框架
解决方案:
手动提示：
这个项目使用了内部框架 InternalFlow，它的工作流定义在 workflows/ 目录，
请分析 workflows/ 中的 YAML 文件来理解流程编排。
更多示例
查看 patterns.md 了解各种架构模式的详细识别案例。