yanxulong/AIEC_Skills

Fork 0

Files

闫旭隆 ae83b9d4d8 项目理解skill-v1

2025-11-12 10:27:56 +08:00

4.5 KiB

Raw Permalink Blame History

Phase 4: 数据流追踪指南

执行时间：约 1-2 分钟

目标：追踪核心数据的转换链路

⚠️ 重要约束

在调用 Task tool 时，必须在 prompt 开头包含以下约束：

⚠️ 重要约束：本次分析只返回文本结果，禁止生成任何文件（.md, .txt 等）。
所有 Mermaid 图表、数据模型清单、转换链路都应包含在你的文本回复中，不要使用 Write 或其他文件创建工具。

Explore agent 只返回文本结果，不要生成任何文件。

分析步骤

步骤 1: 识别核心数据模型

使用 Grep 工具搜索数据模型定义：

Python 项目

# Pydantic 模型
grep -r "class.*BaseModel" --include="*.py"

# Dataclass
grep -r "@dataclass" --include="*.py"

# SQLAlchemy 模型
grep -r "class.*Base" --include="*.py"

TypeScript 项目

# Interface 定义
grep -r "interface.*{" --include="*.ts"

# Type 别名
grep -r "type.*=" --include="*.ts"

# Class 定义
grep -r "export class" --include="*.ts"

Go 项目

# Struct 定义
grep -r "type.*struct" --include="*.go"

步骤 2: 追踪数据转换

定位数据入口
- 从 API 端点的请求体开始
- 识别请求参数的类型定义
追踪转换链路
- 读取每个业务函数的参数类型和返回值类型
- 记录每次类型转换的代码位置
- 识别数据验证、清洗、增强步骤
标注关键转换点
- 序列化/反序列化
- 数据库 ORM 映射
- DTO（Data Transfer Object）转换
- 业务逻辑处理

步骤 3: 生成序列图

使用 assets/sequence.mermaid 模板生成 Mermaid 序列图。

⚠️ sequenceDiagram 语法约束（版本 11.x）：

alt/loop/par 块必须正确配对 end
使用 <br/> 换行

预期输出格式

1. 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 示例：

# 从函数签名追踪类型流转
def process_query(task: ResearchTask) -> SearchResults:
    # task 类型: ResearchTask
    results = search_engine.search(task.query)
    # results 类型: SearchResults
    return results

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 示例：

# 数据库模型 → Pydantic 模型
class UserDB(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)

class UserSchema(BaseModel):
    id: int
    # 从 UserDB 转换到 UserSchema

3. DTO 转换模式

# 请求 DTO → 领域对象 → 响应 DTO
RequestDTO → DomainModel → ResponseDTO

注意事项

关注核心路径：只追踪主要业务流程的数据转换，忽略辅助功能
最多 5 层深度：避免追踪过深导致图表过于复杂
标注转换位置：每次类型转换都记录文件名和行号
区分同步/异步：在序列图中用实线（同步）和虚线（异步）区分

4.5 KiB Raw Permalink Blame History Unescape Escape