AIEC_Skills/codebase_architecture_analyzer_v1/reference/system-analysis.md

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 系统架构图

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