issue-trace

name	issue-trace
description	分析用户发现的问题，通过构建调用链路和数据链路来验证问题是否真实存在，并对问题严重程度进行评分（1-10）。当用户说"分析问题"、"issue-trace"、"问题链路"、"审查问题"、"trace-issues"或描述具体问题时使用此 skill。这是用于代码审查和问题验证的专用工具，与 code-trace-analyzer 不同，本 skill 专注于验证用户报告的问题而非分析文件结构。

Issue Trace Analyzer

分析用户发现的问题，通过追踪代码调用链路和数据链路来验证问题是否真实存在，并对问题的严重程度和描述准确性进行评分。

核心工作流程

1. 解析问题：从用户输入中提取文件路径和问题描述
2. 构建链路：针对问题相关的代码，追踪完整的调用链路和数据链路
3. 验证问题：通过链路分析判断问题是否真实存在
4. 评分输出：给出 1-10 分的评分并生成详细报告

问题评分标准

分数	级别	描述
1-4	虚假/轻微	问题不存在、描述不准确或特别轻微，不影响系统运行
5-7	部分存在	问题存在但严重程度与描述不同，或只在特定条件下触发
8-10	真实严重	问题真实存在且严重程度与描述完全一致

执行步骤

第一步：解析用户问题

从用户输入中提取以下信息：

格式示例：
- "backend/app/api/chat.py 中的消息保存逻辑可能导致数据丢失"
- "frontend/src/components/Chat.vue 消息列表更新不及时"
- "backend/app/services/completeness_service.py 计算结果不正确"

提取内容：

1. 文件路径：目标代码文件
2. 问题描述：用户声称的问题
3. 关键词：用于搜索相关代码

第二步：定位目标代码

1. 读取用户指定的文件
2. 根据问题描述，定位到具体的函数/类/代码块
3. 如果用户没有指定具体位置，使用 Grep 搜索关键词找到相关代码

第三步：构建完整链路

调用链路分析

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

1. 找出目标代码中所有的函数调用、方法调用
2. 递归追踪每个被调用的函数，直到：
   • 标准库/第三方库（停止）
   • 项目边界内的底层实现
3. 记录：调用位置、调用目标、参数、文件位置

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

1. 在项目内搜索引用目标代码的位置
2. 使用 Grep 搜索函数名、类名、路由定义
3. 递归追踪上游调用，找到调用链的源头：
   • API 路由入口
   • 事件处理器
   • 定时任务
4. 记录：调用者、调用条件、参数来源

数据链路分析

1. 识别目标代码中使用的关键数据：
   • 函数参数
   • 类成员变量
   • 数据库查询结果
   • 配置项
2. 追溯每个关键数据的来源（向上一层）：
   • 数据的生产者是谁
   • 数据是如何产生的（计算/查询/配置）
3. 记录：数据项、来源、生产方式、当前用途

第四步：验证问题

根据构建的链路，验证用户报告的问题：

问题存在性检查：

• 代码中是否真的存在用户描述的缺陷？
• 缺陷在什么条件下会触发？
• 是否有防护机制避免问题发生？

严重程度评估：

• 问题会导致什么后果？
• 触发概率如何？
• 影响范围多大？

描述准确性：

• 用户的描述是否准确反映了问题？
• 是否有误解或夸大？

第五步：生成报告

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

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

注意：

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

报告格式：

# 问题链路分析报告

## 概述
- 分析时间：[时间戳]
- 分析的问题数量：[N]

---

## 问题 1：[问题描述]

### 基本信息
- **文件路径**：[文件路径]
- **相关代码**：[函数名/代码块]
- **用户描述**：[原始问题描述]

### 调用链路分析

#### 下游调用链（该代码调用的模块）

[目标代码] ├── [直接调用 1] │ ├── [间接调用 1.1] │ └── [间接调用 1.2] └── [直接调用 2] └── [间接调用 2.1]

#### 上游调用链（调用该代码的地方）

[调用源头] ├── [中间层 1] │ └── [中间层 2] │ └── [目标代码]

### 数据链路分析

| 数据项 | 来源 | 生产方式 | 当前用途 |
|-------|------|---------|---------|
| [数据1] | [来源] | [生产方式] | [用途] |
| [数据2] | [来源] | [生产方式] | [用途] |

### 问题验证结果

#### 问题存在性：[存在/不存在/部分存在]

**分析结论：**
- [详细说明问题是否真的存在]
- [如果存在，描述触发条件]
- [如果不存在，说明为什么用户会有误解]

#### 严重程度评估：[X/10]

| 评估维度 | 得分 | 说明 |
|---------|-----|------|
| 影响范围 | [1-10] | [说明] |
| 触发概率 | [1-10] | [说明] |
| 后果严重性 | [1-10] | [说明] |
| 描述准确性 | [1-10] | [说明] |

**综合得分：X/10**

**评级：** [虚假问题(1-4) / 部分存在(5-7) / 真实严重(8-10)]

#### 详细分析

[如果有问题，详细描述：
- 问题代码位置（文件:行号）
- 问题原因分析
- 触发条件
- 影响范围
- 可能的修复建议]

---

## 问题 2：[问题描述]

[重复上述结构...]

---

## 总结

| 问题 | 文件路径 | 评分 | 评级 |
|-----|---------|-----|------|
| [问题描述1] | [路径] | [X/10] | [评级] |
| [问题描述2] | [路径] | [X/10] | [评级] |

### 统计
- 真实严重问题（8-10分）：[N] 个
- 部分存在问题（5-7分）：[N] 个
- 虚假/轻微问题（1-4分）：[N] 个

工具使用指南

Grep 工具：

• 搜索函数定义：def function_name (Python) 或 function.*\( (TypeScript)
• 搜索函数调用：function_name\(
• 搜索路由定义：@router. 或 app.route
• 搜索导入：import.*module_name 或 from.*import

Read 工具：

• 读取相关文件以分析代码逻辑

Glob 工具：

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

Write 工具：

• 将报告写入 .tracers/ 目录

多问题处理

当用户提供多个问题时：

1. 逐个问题进行分析，不要混合
2. 每个问题独立的链路分析
3. 最后提供汇总表格
4. 如果多个问题涉及同一文件，可以复用已读取的文件内容

注意事项

1. 客观中立：不要预设用户报告的问题一定存在
2. 完整链路：调用链路要追溯到源头，数据链路向上追溯一层
3. 评分依据：评分要有明确的分析依据，不能凭感觉
4. 报告保存：报告必须保存到项目根目录的 .tracers/ 目录
5. 报告命名格式：
   • 独立使用：issue-trace-{filename}-{timestamp}.md
   • batch-tracer 调用：issue-trace.md（保存到指定的 {file_dir}）
6. 中文输出：所有分析和报告使用中文

示例

用户输入：

分析以下问题：
1. backend/app/api/routes/chat.py 中的消息保存逻辑可能导致数据丢失
2. frontend/src/components/Chat.vue 消息列表更新不及时

预期输出：

1. 分析两个问题各自的调用链路和数据链路
2. 验证问题是否真实存在
3. 给出每个问题的评分（1-10）
4. 生成报告：
   • 独立使用：.tracers/issue-trace-{filename}-{timestamp}.md
   • batch-tracer 调用：{file_dir}/issue-trace.md