125 lines
3.5 KiB
Markdown
125 lines
3.5 KiB
Markdown
|
# 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 架构图（使用 `<br/>` 换行）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 步骤 3: 执行过程
|
|||
|
|
|
|||
|
|
1. **Explore sub-agent 自动执行**：使用 Glob、Grep、Read 工具搜索代码
|
|||
|
|
2. **接收结果**：sub-agent 返回分析报告
|
|||
|
|
3. **验证结果**：检查是否包含所有子系统和通信关系
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 预期输出格式
|
|||
|
|
|
|||
|
|
### 1. Mermaid 系统架构图
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TB
|
|||
|
|
User[用户] --> Frontend[前端<br/>React + TypeScript]
|
|||
|
|
Frontend -->|HTTP POST /api/research| Backend[后端 API<br/>FastAPI]
|
|||
|
|
Frontend -->|WebSocket /ws| Backend
|
|||
|
|
Backend -->|invoke| AgentLayer[Agent 编排层<br/>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` 语法突出显示核心子系统
|