项目理解skill-v1

codebase_architecture_analyzer_v1/reference/system-analysis.md

@@ -0,0 +1,124 @@
+# 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` 语法突出显示核心子系统