code-trace

name	code-trace
description	分析代码文件的完整调用链路和数据流，找出上下游调用关系和数据生产源头，审查链路正确性并评分。当用户说"分析链路"、"trace code"、"code-trace"、"链路分析"、"分析代码链路"、"追踪代码调用"、"分析调用关系"、"检查数据流"或需要理解某个文件/函数是如何被调用以及它调用了什么时使用此 skill。

Code Trace Analyzer

分析代码文件的完整链路，包括调用链路（上下游调用关系）和数据链路（数据生产源头），然后审查链路的正确性和合理性。

跨端链路分析：自动识别前端/后端代码，并进行跨前后端的完整链路追踪。

使用场景

当用户需要：

• 理解某个文件或函数的完整调用链路
• 追踪数据从哪里来、到哪里去
• 审查代码执行逻辑的正确性
• 检查上下游代码的衔接是否正确

执行步骤

第一步：识别输入文件

1. 获取用户提供的文件路径
2. 识别文件类型（Python .py 或 TypeScript .ts/.tsx/.vue）
3. 读取文件内容，理解其主要功能和结构
4. 识别代码类型（用于后续跨端分析）：
   • 前端代码：文件路径包含 frontend/ 或扩展名为 .vue, .ts, .tsx, .js, .jsx
   • 后端代码：文件路径包含 backend/ 或扩展名为 .py

第二步：构建调用链路

使用以下策略递归追踪调用关系：

下游追踪（被调用的代码）：

1. 找出目标文件/函数中所有的函数调用
2. 对于每个调用，确定其定义位置：
   • 同文件内的函数调用
   • 导入的外部模块/函数
   • 方法调用（对象的方法）
3. 递归追踪每个被调用的函数，直到：
   • 到达标准库/第三方库（停止追踪）
   • 到达项目边界（同一模块内追踪）
4. 记录调用层级和参数传递

上游追踪（调用目标代码的地方）：

1. 在项目内搜索引用目标文件/函数的位置
2. 使用 Grep 工具搜索函数名、类名、导入语句
3. 分析每个调用点的上下文：
   • 调用条件（if/else 分支）
   • 参数来源
   • 调用时机
4. 递归追踪上游调用，找到调用链的源头

第三步：构建数据链路

1. 识别目标代码中使用的关键数据：
   • 函数参数
   • 类成员变量
   • 从数据库/配置/外部 API 获取的数据
2. 追溯每个关键数据的来源：
   • 向上追溯一层，找到数据的生产者
   • 记录数据的生产方式（计算、查询、配置等）
3. 记录数据的流向：
   • 数据如何被传递
   • 数据如何被转换

第四步：跨端链路分析（新增，仅前后端代码）

在完成上述基础分析后，如果代码类型为前端或后端，执行跨端分析：

场景A：分析前端代码时

1. 提取前端 API 调用：

   • 搜索 axios.、fetch(、apiClient. 等关键词
   • 提取 API 端点路径（如 /api/chat/sessions）
   • 提取请求方法和参数结构

2. 定位后端端点：

   • 根据 API 路径在 backend/ 目录搜索对应的路由文件
   • 匹配规则：/api/xxx → 搜索 router.prefix = "/xxx" 或 @router.xxx("/xxx")
   • 使用 Grep 搜索路径模式，找到对应的后端路由函数

3. 分析后端链路：

   • 对找到的后端路由文件执行调用链路分析（同第二步）
   • 构建前端→后端的完整调用链路图

4. 检查前后端匹配：

   • API 端点路径是否匹配
   • 请求参数字段是否一致
   • 响应数据结构是否匹配
   • 字段命名风格（camelCase vs snake_case）

场景B：分析后端代码时

1. 提取后端 API 端点：

   • 搜索 @router.get/post/put/delete 装饰器
   • 提取路由路径和方法
   • 提取路由 prefix（如 router = APIRouter(prefix="/chat")）
   • 构建完整端点路径：/api/{prefix}/{path}

2. 定位前端调用者：

   • 在 frontend/ 目录搜索该端点的调用
   • 搜索模式：/api/{完整路径} 或 {完整路径}
   • 查找 axios、fetch 等调用

3. 分析前端组件：

   • 对找到的前端组件进行分析
   • 了解如何调用 API、处理响应

4. 检查前后端匹配：

   • 同场景A的检查项

第五步：审查链路

对完整的链路进行审查，检查：

执行逻辑正确性：

• 调用顺序是否合理
• 是否存在循环调用风险
• 是否存在未处理的边界情况

衔接正确性：

• 参数类型是否匹配
• 返回值是否被正确使用
• 数据格式是否一致

前后端衔接正确性（仅前后端代码）：

• API 端点是否正确对应
• 请求/响应字段是否匹配
• 数据类型是否兼容

代码合理性：

• 是否存在冗余调用
• 是否有更简洁的实现方式
• 是否符合最佳实践

第六步：生成报告

报告目录：项目根目录下的 .tracers/ 目录

报告命名格式：code-trace.md

注意：

• 当作为独立 skill 使用时，报告保存到 .tracers/code-trace-{filename}-{timestamp}.md
• 当被 batch-tracer 调用时，报告保存到指定的 {file_dir}/code-trace.md

按以下格式输出 Markdown 报告：

# 代码链路分析报告

## 概述
- 分析文件：[文件路径]
- 代码类型：[前端/后端]
- 分析时间：[时间戳]
- 语言类型：[Python/TypeScript/Vue]

---

## [前端/后端] 代码分析

### 调用链路图

### 下游调用链（该文件调用的代码）

目标文件 ├── 直接调用 1 │ ├── 间接调用 1.1 │ └── 间接调用 1.2 └── 直接调用 2 └── 间接调用 2.1

### 上游调用链（调用该文件的地方）

调用源头 ├── 中间层 1 │ └── 中间层 2 │ └── 目标文件

### 数据链路图

数据源头 → 数据生产者 → 目标文件 → 数据消费者

---

## 跨端链路分析

### API 端点映射

| # | 前端调用 | 后端定义 | 状态 |
|---|----------|----------|------|
| 1 | [axios.post('/api/xxx')] | [@router.post('/xxx')] | [✅匹配/❌不匹配] |

### 跨端完整调用链

[用户操作] → [前端组件] → [API调用] → [后端路由] → [服务层] → [数据库]

### 前后端数据流

**请求数据流**：

前端发送: {字段: 值} ↓ HTTP请求 ↓ 后端接收: {字段: 值}

**响应数据流**：

数据库查询 ↓ 后端返回: {字段: 值} ↓ HTTP响应 ↓ 前端接收: {字段: 值}

### 前后端匹配检查

**API 端点匹配**：
- 路径：[✅/❌] [说明]
- 方法：[✅/❌] [说明]

**请求参数匹配**：
| 前端字段 | 前端类型 | 后端字段 | 后端类型 | 状态 |
|----------|----------|----------|----------|------|
| fieldName | string | field_name | str | [✅/❌/⚠️] |

**响应数据匹配**：
| 前端期望 | 前端类型 | 后端返回 | 后端类型 | 状态 |
|----------|----------|----------|----------|------|
| fieldName | string | field_name | str | [✅/❌/⚠️] |

**图例**：✅ 完全匹配 | ⚠️ 命名风格差异 | ❌ 不匹配

---

## 链路详情

### 下游调用详情
| 调用位置 | 调用目标 | 参数 | 文件位置 |
|---------|---------|------|---------|
| ... | ... | ... | ... |

### 上游调用详情
| 调用位置 | 调用者 | 条件 | 文件位置 |
|---------|-------|------|---------|
| ... | ... | ... | ... |

### 数据流详情
| 数据项 | 来源 | 生产方式 | 当前用途 |
|-------|------|---------|---------|
| ... | ... | ... | ... |

## 问题清单

### 严重问题（8-10分）
- [ ] 无

### 一般问题（5-7分）
- [ ] 无

### 轻微问题（1-4分）
- [ ] 无

## 建议
[如有问题，提供修复建议]

评分标准

分数	级别	描述
1-4	轻微	不影响执行，如代码风格、命名规范、可优化但不必要
5-7	一般	部分情况会影响执行，如边界条件处理、错误处理不完善
8-10	严重	无法执行或导致错误，如类型不匹配、循环依赖、空指针风险

工具使用指南

Grep 工具：

• 搜索函数定义：def function_name (Python) 或 function_name (TypeScript)
• 搜索函数调用：function_name\(
• 搜索导入：import.*module_name 或 from.*import

Read 工具：

• 读取相关文件以分析调用关系

Glob 工具：

• 查找相关文件：**/*.py 或 **/*.ts

Write 工具：

• 将报告写入 .tracers/ 目录

注意事项

1. 对于大型项目，设置合理的追踪深度避免输出过长
2. 标准库和第三方库调用不进行深度追踪
3. 重点关注项目内部的调用关系
4. 数据链路只向上追溯一层即可
5. 如果分析文件是纯数据模型/配置，调用链路可能为空
6. 报告必须保存到项目根目录的 .tracers/ 目录
7. 报告命名格式：
   • 独立使用：code-trace-{filename}-{timestamp}.md
   • batch-tracer 调用：code-trace.md（保存到指定的 {file_dir}）