205 lines
4.5 KiB
Markdown
205 lines
4.5 KiB
Markdown
# Phase 4: 数据流追踪指南
|
||
|
||
**执行时间**：约 1-2 分钟
|
||
|
||
**目标**：追踪核心数据的转换链路
|
||
|
||
---
|
||
|
||
## ⚠️ 重要约束
|
||
|
||
**在调用 Task tool 时，必须在 prompt 开头包含以下约束：**
|
||
|
||
```
|
||
⚠️ 重要约束：本次分析只返回文本结果，禁止生成任何文件（.md, .txt 等）。
|
||
所有 Mermaid 图表、数据模型清单、转换链路都应包含在你的文本回复中，不要使用 Write 或其他文件创建工具。
|
||
```
|
||
|
||
**Explore agent 只返回文本结果，不要生成任何文件。**
|
||
|
||
---
|
||
|
||
## 分析步骤
|
||
|
||
### 步骤 1: 识别核心数据模型
|
||
|
||
使用 Grep 工具搜索数据模型定义：
|
||
|
||
#### Python 项目
|
||
|
||
```bash
|
||
# Pydantic 模型
|
||
grep -r "class.*BaseModel" --include="*.py"
|
||
|
||
# Dataclass
|
||
grep -r "@dataclass" --include="*.py"
|
||
|
||
# SQLAlchemy 模型
|
||
grep -r "class.*Base" --include="*.py"
|
||
```
|
||
|
||
#### TypeScript 项目
|
||
|
||
```bash
|
||
# Interface 定义
|
||
grep -r "interface.*{" --include="*.ts"
|
||
|
||
# Type 别名
|
||
grep -r "type.*=" --include="*.ts"
|
||
|
||
# Class 定义
|
||
grep -r "export class" --include="*.ts"
|
||
```
|
||
|
||
#### Go 项目
|
||
|
||
```bash
|
||
# Struct 定义
|
||
grep -r "type.*struct" --include="*.go"
|
||
```
|
||
|
||
### 步骤 2: 追踪数据转换
|
||
|
||
1. **定位数据入口**
|
||
- 从 API 端点的请求体开始
|
||
- 识别请求参数的类型定义
|
||
|
||
2. **追踪转换链路**
|
||
- 读取每个业务函数的参数类型和返回值类型
|
||
- 记录每次类型转换的代码位置
|
||
- 识别数据验证、清洗、增强步骤
|
||
|
||
3. **标注关键转换点**
|
||
- 序列化/反序列化
|
||
- 数据库 ORM 映射
|
||
- DTO（Data Transfer Object）转换
|
||
- 业务逻辑处理
|
||
|
||
### 步骤 3: 生成序列图
|
||
|
||
使用 `assets/sequence.mermaid` 模板生成 Mermaid 序列图。
|
||
|
||
**⚠️ sequenceDiagram 语法约束（版本 11.x）**：
|
||
- `alt/loop/par` 块必须正确配对 `end`
|
||
- 使用 `<br/>` 换行
|
||
|
||
---
|
||
|
||
## 预期输出格式
|
||
|
||
### 1. Mermaid 序列图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant F as Frontend
|
||
participant B as Backend
|
||
participant R as Researcher
|
||
participant W as Writer
|
||
|
||
U->>F: 输入查询 "AI 发展趋势"
|
||
F->>B: POST /api/research<br/>{query, depth: 3}
|
||
Note over B: 构造 ResearchTask
|
||
B->>R: invoke(ResearchTask)
|
||
R->>R: 搜索引擎调用
|
||
R-->>B: SearchResults (10 个文档)
|
||
B->>W: 传递 SearchResults
|
||
W->>W: GPT-4 生成报告
|
||
W-->>B: Report (2000 字)
|
||
B->>F: 返回 HTML
|
||
F->>U: 展示报告
|
||
```
|
||
|
||
### 2. 数据模型清单
|
||
|
||
列出所有核心数据模型及其位置：
|
||
|
||
```
|
||
核心数据模型:
|
||
1. ResearchTask (models/task.py:8)
|
||
- 用途: 用户查询任务
|
||
- 字段: query: str, depth: int, filters: Optional[List[str]]
|
||
|
||
2. SearchResults (models/results.py:15)
|
||
- 用途: 搜索结果集合
|
||
- 字段: documents: List[Document], total: int, timestamp: datetime
|
||
|
||
3. Report (models/report.py:22)
|
||
- 用途: 最终生成的报告
|
||
- 字段: content: str, score: float, metadata: Dict[str, Any]
|
||
```
|
||
|
||
### 3. 数据转换链路
|
||
|
||
```
|
||
数据流转路径:
|
||
用户输入 (str)
|
||
→ ResearchTask (构造于 backend/routes.py:42)
|
||
→ SearchResults (返回于 agents/researcher.py:67)
|
||
→ Report (生成于 agents/writer.py:89)
|
||
→ HTML (渲染于 backend/routes.py:58)
|
||
→ 前端展示
|
||
```
|
||
|
||
---
|
||
|
||
## 分析技巧
|
||
|
||
### 1. 类型提示追踪
|
||
|
||
Python 示例：
|
||
```python
|
||
# 从函数签名追踪类型流转
|
||
def process_query(task: ResearchTask) -> SearchResults:
|
||
# task 类型: ResearchTask
|
||
results = search_engine.search(task.query)
|
||
# results 类型: SearchResults
|
||
return results
|
||
```
|
||
|
||
TypeScript 示例：
|
||
```typescript
|
||
// 从接口定义追踪
|
||
interface ApiRequest {
|
||
query: string;
|
||
depth: number;
|
||
}
|
||
|
||
async function handleRequest(req: ApiRequest): Promise<Report> {
|
||
// req 类型: ApiRequest
|
||
const results = await research(req);
|
||
// results 类型: Report
|
||
return results;
|
||
}
|
||
```
|
||
|
||
### 2. ORM 映射识别
|
||
|
||
SQLAlchemy 示例：
|
||
```python
|
||
# 数据库模型 → Pydantic 模型
|
||
class UserDB(Base):
|
||
__tablename__ = "users"
|
||
id = Column(Integer, primary_key=True)
|
||
|
||
class UserSchema(BaseModel):
|
||
id: int
|
||
# 从 UserDB 转换到 UserSchema
|
||
```
|
||
|
||
### 3. DTO 转换模式
|
||
|
||
```python
|
||
# 请求 DTO → 领域对象 → 响应 DTO
|
||
RequestDTO → DomainModel → ResponseDTO
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **关注核心路径**：只追踪主要业务流程的数据转换，忽略辅助功能
|
||
2. **最多 5 层深度**：避免追踪过深导致图表过于复杂
|
||
3. **标注转换位置**：每次类型转换都记录文件名和行号
|
||
4. **区分同步/异步**：在序列图中用实线（同步）和虚线（异步）区分
|