issue-trace — 问题深度根因定位与调用链追溯助手

定位：纯分析阶段的根因诊断中枢。用户描述了一个问题现象，想搞清楚"为什么会这样"，但还没决定要不要修。 核心动作：表象 → 嫌疑点 → 反向追溯 → 根因定论 + 证据链 + 修复建议（不自动进入修复）。 核心原则：证据驱动结论 + 不自动升级 dev-flow + 调用链辅助呈现而非主体。

设计理念

用户描述现象（表象）
   ↓
列出嫌疑点（≥2 条，避免单点假设）
   ↓
反向追溯（沿调用栈/数据流/依赖链）→ 跨项目时强制走 reflex 三步法
   ↓
根因定论（已定 / 未定+待验证假设）+ 证据链
   ↓
修复建议（治本 + 治标 双方案，仅建议不动手）
   ↓
由用户决定下一步（修 → 走 dev-flow / 不修 → 结束）

与其他 skill 的边界：

全局输出规范（最高优先级）

本 Skill 生成的所有根因报告、调用链、证据引用，文件路径、代码位置引用必须遵循 ~/.codebuddy/rules/AI行为规范.mdc 的「文件/代码位置引用」规范（反引号包裹相对路径 `相对路径` + 空格后缀行号 L行号）。 跨项目分析时必须叠加来源标注（见下文 §「调用链与证据链输出格式」）。

触发规则

🏛️ 单一权威源：本章节是 issue-trace 触发规则的唯一权威源。~/.codebuddy/rules/AI行为规范.mdc 仅保留决策指令与优先级，具体动词/场景一律在此维护。

⚡ 显式命令（最高优先级，无歧义）

用法：在 CodeBuddy 对话中输入命令 + 问题描述即可，例如：

trace 为什么 Avatar 组件在中文环境下显示英文
t -c list-component 的 ShareModal 调用链怎么走的
t -s 详情页偶现白屏
t -r                              ← 在新项目中恢复上次分析
t -l                              ← 查看所有未闭环的分析
t --close trace-20260526-173000   ← 关闭已解决的分析

命令解析规则：

• 命令后跟的文本作为「现象描述」输入 Step 1
• -q / --quick 跳过物理门控，输出末尾附加置信度警告
• -c / --chain 自动进入 Step 3 跨项目追溯路径（reflex 三步法）
• -s / --suspects 完成 Step 2 后暂停，等用户选择是否继续深入
• -r / --resume 读取 traces/ 目录下最近一条 status: open 或 status: handed-off 的快照，自动加载上下文后从中断点继续分析
• -l / --list 扫描 traces/ 目录，列出所有非 closed 状态的 trace 摘要（id + 标题 + 状态 + 创建时间）
• --close <id> 将指定 trace 文件的 status 改为 closed，追加关闭时间

💡 与 dev-flow 的关系：trace 是 issue-trace skill 的独立命令。如果分析完用户选择修复，会自然衔接到 dev-flow。

🔴 不触发场景（前置排除，避免误抢入口）

🟡 显式触发（用户直说"分析根因/追溯"或使用命令）

🟢 现象描述型触发（最高频，用户描述问题但没说要修）

🔵 困惑/不确定型触发（用户在分析阶段）

🟣 跨项目链路型触发（用户已意识到涉及多项目）

⚠️ 触发判断可观测性：判定为 issue-trace 触发时，必须在回复开头用一行说明（如"本次走 issue-trace 根因诊断流程，不进入 dev-flow"），让用户可监督判断是否正确（与 AI 行为规范 §「触发判断可观测性」对齐）。

命令参数与工作流映射

💡 参数可组合：t -q -c = 快速给出跨项目调用链结论（跳过门控）

工作流程（5 步法，强制顺序）

Step 1：现象输入解析

收集 4 类信息（用户没主动给的要主动追问，但每轮最多问 2 项，避免审讯感）：

Step 2：嫌疑点拆解（≥2 条，强制）

反单点假设：任何根因分析必须先列出 ≥2 条嫌疑点，禁止上来就锁定单一原因。

输出格式：

## 嫌疑点列表
1. **[嫌疑 A]** {1 句话假设} — 验证方式：{读哪个文件/查哪个数据}
2. **[嫌疑 B]** {1 句话假设} — 验证方式：{读哪个文件/查哪个数据}
3. **[嫌疑 C]**（可选）...

Step 3：反向追溯（核心）

按 4 类追溯路径并行展开：

🚨 跨项目追溯硬约束（与 ~/.codebuddy/rules/AI行为规范.mdc §「跨项目分析 reflex 原则」对齐）：

• 检测到非当前 workspace 的依赖包/上游组件库时，禁止凭推测、禁止仅依赖远端 知识库平台 MCP
• 必须执行 reflex 三步法：① 本地优先探测项目路径 ② 命中本地先做分支感知 ③ 未命中主动提醒用户 4 选项（clone / 知识库 MCP / API 获取代码 / 跳过）
• 引用本地仓库源码时必须标注 [local-repo] 或 [local-repo@{branch}] 来源
• 完整流程见 skills/dev-flow/references/cross-project-flow.md §「分析型跨项目流程」

Step 4：根因定论

输出三选一（禁止含糊其辞）：

Step 5：输出格式（统一模板）

🚨 输出顺序强约束（必须按以下顺序，禁止打乱）： 根因定论 → ASCII 调用链树（主体）→ 关键代码位置 → 证据链 → 修复建议 → 下一步

🚨 调用链格式硬约束：

• 主体必须用 ASCII 树（如下模板），便于终端复制 + IDE 内联展示 + 跨平台稳定渲染
• 禁止用 mermaid 图片作为调用链主体（用户已明确反馈不要图片）
• 仅当链路 ≥ 5 节点且分支 ≥ 2 条时，可在 ASCII 树之后附加 mermaid 作为辅助视图（非替代）

🚨 代码块原文 100% 一致约束（违反即拒收）：

• 所有 ```ts/tsx/js ``` 代码块内容必须等于磁盘原文
• 禁止在代码块内添加 // ❌ // ⚠️ // 🚨 // root cause 等原文不存在的评价性注释
• 需要标注时，把评价写在代码块外（如「⭐ 关键证据 N：xxx」）

## 🎯 根因定论
{已定 / 高度疑似 / 未定}：{1 句话结论}

## 🔗 完整调用链（ASCII 树）
\```
funcA(args)                                  ← `my-project/src/x.tsx` L42
  └─ funcB(options)                          ← `component-lib/src/y.tsx` L120 [local-repo]
        └─ funcC(params)                     ← `base-project/src/z.ts` L88 [local-repo@feature/xxx]
              └─ rootCauseField              ← `base-project/src/z.ts` L95 [local-repo@feature/xxx] 🚨 root cause
\```

## 📍 关键代码位置（按调用顺序）
1. `my-project/src/x.tsx` L42-L58 `[当前 workspace]` — {1 句话说明此处的角色}
   ```tsx
   // 关键 3-5 行代码

2. component-lib/src/y.tsx L120 [local-repo] — {1 句话说明}

   // 关键 3-5 行代码

3. base-project/src/z.ts L88 [local-repo@feature/xxx] — {根因所在}

   // 关键 3-5 行代码（root cause）

🧪 证据链

• 证据 1：{是什么 + 在哪} → 支撑/排除哪条嫌疑
• 证据 2：...

💡 修复建议（仅建议，不自动执行）

• 治本方案：{改 X 项目的 Y 处，影响范围 Z} — 推荐
• 治标方案：{在当前项目 W 处加防御} — 风险/副作用：...

🚦 下一步

• 选 1：进入 dev-flow 修复 → 我会 use_skill('dev-flow')
• 选 2：先用治标方案应急 → 告诉我我帮你写补丁（仍走 dev-flow）
• 选 3：信息不足，先补充 {具体信息} 再分析 → 普通对话继续
• 选 4：暂不修复 → 本次分析结束
• 选 5：需跨项目继续 → 生成 trace 快照，去目标项目新开对话用 t -r 衔接

---

## 调用链与证据链输出格式（强制）

| 引用对象 | 格式 |
|---------|------|
| 当前 workspace 文件 | `` `相对路径` `` L行号（默认，可省略来源标签） |
| 跨项目本地仓库（默认分支） | `` `仓库名/相对路径` `` L行号 `[local-repo]` |
| 跨项目本地仓库（非默认分支） | `` `仓库名/相对路径` `` L行号 `[local-repo@{branch}]` |
| 远端 知识库平台 MCP 拉取 | `` `仓库名/相对路径` `` L行号 `[知识库平台@{commit-sha7}]` |
| Git 平台 get_blob_content 拉取 | `` `仓库名/相对路径` `` L行号 `[代码平台@{ref}]` |

> 与 AI 行为规范 §「输出格式规范」+「跨项目分析 reflex 原则 §来源标注」双向闭环。

---

## 外部参考

> 日志追溯：当问题涉及线上现象，可结合日志查询 MCP 工具（如 `SearchLog`、`LogClassify`）确认错误模式后，切回 Step 3 代码逻辑追溯继续深入分析。日志查询仅用于确认线上现象，不作为根因定论的主要证据。

---

## 输出前物理事实门控（强制，与 dev-flow `.validated` 哲学对齐）

> 🏛️ **设计哲学**：`~/.codebuddy/rules/AI行为规范.mdc` §「Skill 设计哲学」明确——**确定性用代码，模糊性用 LLM**。
> 本章节是 issue-trace 的**物理事实兜底**：把"调用方追溯到位""代码块原文一致"这两条**确定性可程序化**的检查从提示词层下沉到脚本层，AI 不可绕过。

### 触发条件

完成 Step 5 输出**之前**（即生成根因报告 markdown 之前），**必须**对自己即将输出的报告内容做以下两项物理校验：

| 检查项 | 脚本 | 退出码 0 才算通过 |
|--------|------|------------------|
| 调用方追溯深度 | `scripts/trace-depth-check.sh <报告.md>`（v2 纯报告自检）| 报告内 wrapper import 同时必须有实现位置（包名/路径 + L行号）|
| 代码块原文一致性 | `scripts/code-block-purity-check.sh <报告.md>` | 代码块内无自创评价性注释 |

### 执行范式（不可绕过）

```bash
# Step A: 把即将输出的报告先写到临时文件（编辑工具自带 success 不算落盘）
REPORT_TMP=$(mktemp -t issue-trace-report-XXXXXX.md)
cat > "$REPORT_TMP" <<'EOF'
{即将输出给用户的根因报告 markdown 全文}
EOF

# Step B: 运行两个门控脚本（顺序无关，可并行）
bash ~/.codebuddy/skills/issue-trace/scripts/trace-depth-check.sh "$REPORT_TMP"
TRACE_RC=$?
bash ~/.codebuddy/skills/issue-trace/scripts/code-block-purity-check.sh "$REPORT_TMP"
PURITY_RC=$?

# Step C: 任一非 0 → 必须先修报告再重跑，禁止把不合格内容输出给用户
if [[ $TRACE_RC -ne 0 || $PURITY_RC -ne 0 ]]; then
  echo "❌ 物理门控未通过，需修订报告后重跑"
  # 此时回到 Step 3-4 补全追溯链路 / 清理代码块自创注释
fi

例外条款（务实主义）

• 快速咨询模式：报告中没有代码块且未引用任何源文件路径 → 跳过两项门控（无可校验对象）
• 轻量分析模式：用户明确说"先给个结论就行" → 输出极简结论 + 在末尾追加 ⚠️ 已跳过物理门控（轻量模式），结论可信度需用户自行判断
• 门控误报：如果脚本误报（如 wrapper 函数实际无追溯必要），必须在报告末尾显式说明误报理由，而不是静默跳过

反模式（违反即拒收）

• ❌ 编辑工具回报 success 就直接发输出，不走两个门控脚本
• ❌ grep_search/codebase_search 显示通过就当作物理门控通过（与 AI 行为规范 §「编辑工具假性成功兜底」对齐）
• ❌ 门控脚本退出非 0 时强行输出，不修报告
• ❌ 把跳过门控当作"用户没要求"的默认行为（默认必须执行，例外条款必须显式声明）

反模式（违反即拒收）

1. ❌ 单点假设：上来就锁定单一原因，不列嫌疑点 → 必出错判
2. ❌ 凭推测跨项目：检测到外部依赖包不去本地查实际代码 → 违反 reflex 三步法
3. ❌ 未做分支感知：本地仓库分支与期望不一致仍直接读源码 → 可能拿到 feature 分支的中间状态代码
4. ❌ 自动升级 dev-flow：用户没说要修就替用户决定进入修复流程 → 违反"不自动升级"承诺
5. ❌ 结论模糊：输出"可能是 X 也可能是 Y"但不给定论状态/不给下一步 → 用户无法行动
6. ❌ 无证据链：只给结论不给"哪个文件哪一行支撑了这个结论" → 无法被用户验证
7. ❌ 遗漏来源标注：跨项目引用没标 [local-repo] / [local-repo@branch] / [知识库平台@sha] → 用户无法判断证据时效性
8. ❌ 不限定修复建议范围：在分析阶段直接动手改代码 → 越权（本 skill 只建议不动手，要改必须经 dev-flow）
9. ❌ 调用方追溯偷懒（2026-05-20 新增）：业务函数调用了 get/post/request/fetch/http 等通用名时，必须追到该函数内部至少一层（看是不是 wrapper），禁止凭「看起来很简单」就停在第一层。判定标准：报告引用了 A 文件的 xxx() 调用，但 A 文件中 xxx 是从 B 文件 import 的本地函数 → 报告必须同时引用 B 文件 xxx 的实现行号。与「§祖父原则 §B 调用方追溯」对齐
10. ❌ 代码块自创注释污染（2026-05-20 新增）：在引用源码时，代码块内严禁出现 // ❌ / // ⚠️ / // 🚨 / // root cause / // 这里是问题 等原文不存在的评价性注释。需要标注关键点时，必须把评价写在代码块外（如「⭐ 关键证据 N：xxx」），代码块内必须 100% 等于磁盘原文。判定方法：用 sed -n '起,止p' 文件 提取真实内容，与报告代码块字符级比对，任意自创注释 → 拒收

跨对话衔接（Trace Handoff）

设计理念：把 AI 脑中的分析中间态「物化」到文件，使跨对话、跨项目的分析流程不再断裂。

目录结构

~/.codebuddy/skills/issue-trace/traces/
├── .gitkeep
├── TEMPLATE.md                          ← 快照模板（不可删除）
├── 2026-05-26_avatar-i18n.md            ← 具体分析快照
├── 2026-05-24_share-modal-crash.md
└── ...

文件命名规范

{YYYY-MM-DD}_{问题关键词-kebab-case}.md

• 日期取创建时间
• 关键词 2-4 个单词，用连字符连接，全小写
• 例：2026-05-26_avatar-i18n-fallback.md

状态流转

open → handed-off → closed
  │         │
  └────→ closed（直接在当前项目解决）

快照生成时机

以下任一条件满足时，必须提议生成 trace 快照（用户确认后才写入）：

1. 用户选择下一步选项 5（需跨项目继续）
2. Step 3 追溯自然中断：追到非当前 workspace 的代码且本地无该仓库
3. Step 4 结论为 🟡 高度疑似且根因指向外部项目
4. 用户主动说"先到这"/"我去另一个项目看看"

trace --resume 执行流程

用户在目标项目输入 t -r
  ↓
① 扫描 ~/.codebuddy/skills/issue-trace/traces/ 下所有 .md 文件
  ↓
② 找到 status: open 或 status: handed-off 的文件
  ↓
③ 如果有多条，按 created 倒序列出，让用户选择；仅一条则自动加载
  ↓
④ 读取快照内容，解析 frontmatter
  ↓
⑤ 将「现象摘要」作为 Step 1 输入、「剩余嫌疑点」作为 Step 2 起点、
   「下一步排查指引」作为 Step 3 的追溯方向
  ↓
⑥ 从中断点继续分析流程（通常从 Step 3 开始）
  ↓
⑦ 分析完成后，更新原快照的 status → closed，追加闭环信息

trace --list 执行流程

# 扫描 traces/ 目录，过滤非 closed 的文件，输出摘要表格

输出格式：

| # | ID | 标题 | 状态 | 创建时间 | 来源项目 → 目标项目 |
|---|-------|------|------|---------|-------------------|
| 1 | trace-20260526-173000 | 用户头像组件显示异常 | handed-off | 2026-05-26 | my-app → component-lib |
| 2 | trace-20260524-091500 | 弹窗组件渲染错误 | open | 2026-05-24 | my-app → — |

trace --close <id> 执行流程

1. 在 traces/ 目录中找到匹配 id 的文件
2. 将 frontmatter 中 status 改为 closed
3. 追加 closed_at: {ISO8601} 和 close_reason: {用户提供或默认"手动关闭"}

快照自动过期清理

• closed 状态超过 30 天的文件 → 移入 traces/archive/（不删除）
• open 状态超过 7 天未有任何更新 → 下次 t -l 时标注 ⚠️ 超期，提醒用户决定是否关闭
• 清理动作仅在用户执行 t -l 时触发，不后台自动运行

快照与 dev-flow working-context 的关系

• trace 快照不等于 working-context flow 文件
• trace 快照是「分析中间态」，working-context 是「修复执行态」
• 用户选择"修"后，dev-flow 会从 trace 快照中提取关键信息初始化 flow 文件，但两者独立管理
• trace 快照在 ~/.codebuddy/skills/issue-trace/traces/，跨项目共享
• working-context 在 ~/.codebuddy/working-context/，与当前对话绑定

反模式

• ❌ 未经用户确认就生成快照：必须先提议，用户确认后才写文件
• ❌ 在快照中复制完整源码：只记关键 3-5 行 + 文件位置，不做大段 copy
• ❌ t -r 时不验证当前 workspace 与 handoff_target 的匹配：恢复时应提醒用户确认
• ❌ closed 的 trace 被 t -r 恢复：只恢复 open/handed-off 状态

不会自动触发 dev-flow 的承诺

• 本 Skill 完成 5 步流程后，输出截止于「修复建议 + 下一步选项」
• 是否进入 dev-flow 由用户在 §「下一步」中显式选择
• 用户选择"修"后，AI 才能 use_skill('dev-flow') 进入修复流程
• 此承诺与 AI 行为规范 §「工作上下文文件保护」对齐：未触发 dev-flow 期间禁止操作 working-context/

与现有规则的引用闭环

双向闭环验证命令：

grep -n "issue-trace" ~/.codebuddy/rules/AI行为规范.mdc
grep -n "issue-trace" ~/.codebuddy/skills/dev-flow/references/cross-project-flow.md