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` 语法突出显示核心子系统
|