| name | code-trace |
| description | 分析代码文件的完整调用链路和数据流，找出上下游调用关系和数据生产源头，审查链路正确性并评分。当用户说"分析链路"、"trace code"、"code-trace"、"链路分析"、"分析代码链路"、"追踪代码调用"、"分析调用关系"、"检查数据流"或需要理解某个文件/函数是如何被调用以及它调用了什么时使用此 skill。 |
Code Trace Analyzer
分析代码文件的完整链路，包括调用链路（上下游调用关系）和数据链路（数据生产源头），然后审查链路的正确性和合理性。
跨端链路分析：自动识别前端/后端代码，并进行跨前后端的完整链路追踪。
使用场景
当用户需要：
- 理解某个文件或函数的完整调用链路
- 追踪数据从哪里来、到哪里去
- 审查代码执行逻辑的正确性
- 检查上下游代码的衔接是否正确
执行步骤
第一步：识别输入文件
- 获取用户提供的文件路径
- 识别文件类型（Python .py 或 TypeScript .ts/.tsx/.vue）
- 读取文件内容，理解其主要功能和结构
- 识别代码类型（用于后续跨端分析）：
- 前端代码：文件路径包含
frontend/ 或扩展名为 .vue, .ts, .tsx, .js, .jsx
- 后端代码：文件路径包含
backend/ 或扩展名为 .py
第二步：构建调用链路
使用以下策略递归追踪调用关系：
下游追踪（被调用的代码）：
- 找出目标文件/函数中所有的函数调用
- 对于每个调用，确定其定义位置：
- 同文件内的函数调用
- 导入的外部模块/函数
- 方法调用（对象的方法）
- 递归追踪每个被调用的函数，直到：
- 到达标准库/第三方库（停止追踪）
- 到达项目边界（同一模块内追踪）
- 记录调用层级和参数传递
上游追踪（调用目标代码的地方）：
- 在项目内搜索引用目标文件/函数的位置
- 使用 Grep 工具搜索函数名、类名、导入语句
- 分析每个调用点的上下文：
- 调用条件（if/else 分支）
- 参数来源
- 调用时机
- 递归追踪上游调用，找到调用链的源头
第三步：构建数据链路
- 识别目标代码中使用的关键数据：
- 函数参数
- 类成员变量
- 从数据库/配置/外部 API 获取的数据
- 追溯每个关键数据的来源：
- 向上追溯一层，找到数据的生产者
- 记录数据的生产方式（计算、查询、配置等）
- 记录数据的流向：
第四步：跨端链路分析（新增，仅前后端代码）
在完成上述基础分析后，如果代码类型为前端或后端，执行跨端分析：
场景A：分析前端代码时
-
提取前端 API 调用：
- 搜索
axios.、fetch(、apiClient. 等关键词
- 提取 API 端点路径（如
/api/chat/sessions）
- 提取请求方法和参数结构
-
定位后端端点：
- 根据 API 路径在
backend/ 目录搜索对应的路由文件
- 匹配规则：
/api/xxx → 搜索 router.prefix = "/xxx" 或 @router.xxx("/xxx")
- 使用 Grep 搜索路径模式，找到对应的后端路由函数
-
分析后端链路：
- 对找到的后端路由文件执行调用链路分析（同第二步）
- 构建前端→后端的完整调用链路图
-
检查前后端匹配：
- API 端点路径是否匹配
- 请求参数字段是否一致
- 响应数据结构是否匹配
- 字段命名风格（camelCase vs snake_case）
场景B：分析后端代码时
-
提取后端 API 端点：
- 搜索
@router.get/post/put/delete 装饰器
- 提取路由路径和方法
- 提取路由 prefix（如
router = APIRouter(prefix="/chat")）
- 构建完整端点路径：
/api/{prefix}/{path}
-
定位前端调用者：
- 在
frontend/ 目录搜索该端点的调用
- 搜索模式：
/api/{完整路径} 或 {完整路径}
- 查找 axios、fetch 等调用
-
分析前端组件：
- 对找到的前端组件进行分析
- 了解如何调用 API、处理响应
-
检查前后端匹配：
第五步：审查链路
对完整的链路进行审查，检查：
执行逻辑正确性：
- 调用顺序是否合理
- 是否存在循环调用风险
- 是否存在未处理的边界情况
衔接正确性：
- 参数类型是否匹配
- 返回值是否被正确使用
- 数据格式是否一致
前后端衔接正确性（仅前后端代码）：
- 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 工具：
Write 工具：
注意事项
- 对于大型项目，设置合理的追踪深度避免输出过长
- 标准库和第三方库调用不进行深度追踪
- 重点关注项目内部的调用关系
- 数据链路只向上追溯一层即可
- 如果分析文件是纯数据模型/配置，调用链路可能为空
- 报告必须保存到项目根目录的
.tracers/ 目录
- 报告命名格式：
- 独立使用：
code-trace-{filename}-{timestamp}.md
- batch-tracer 调用：
code-trace.md（保存到指定的 {file_dir}）
