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