debug-probe

name	debug-probe
description	AI 驱动的运行时调试探针。通过 假设→插桩→收集→收敛→修复→清理 闭环精准定位 bug 根因，用运行时证据替代静态猜测。Use when 用户报告 bug/异常行为且静态分析无法定位、涉及复杂状态/异步时序、或用户说"调试一下""帮我排查""用探针""debug"。

Debug Probe — AI 运行时探针调试

不静态猜测根因，在源码中临时插入日志，用运行时真实数据定位问题。

核心流程（严格按序）

Phase 0: 启动探针服务

每次执行 skill 必须先启动探针服务器：

# 确保之前的进程已清理
kill $(lsof -ti:9876) 2>/dev/null
# 启动探针收集服务
node ~/.claude/skills/debug-probe/debug-probe-server.js &

服务器监听 http://localhost:9876，POST 请求写入 /tmp/debug-probe.log。不依赖 Vite 中间件，避免 ESM/CORS/404 问题。

Phase 1: 假设生成

不要直接修。 先读代码，生成 2-4 个可验证假设：

1. 读 bug 描述 + 相关源码
2. 列出：[H1] 根因可能是...，为真则...可观察到
3. 向用户展示假设，确认方向

Phase 2: 精准插桩

只插与假设相关的位置，2-4 个点即可：

浏览器端：

// DEBUG PROBE — DO NOT COMMIT
fetch('http://localhost:9876', {
  method: 'POST',
  body: JSON.stringify({ loc: 'Comp.vue:47', h: 'H1', ts: Date.now(), ...相关状态 }),
}).catch(() => {});

服务端（Node.js）：

// DEBUG PROBE — DO NOT COMMIT
import { appendFileSync } from 'fs'
appendFileSync('/tmp/debug-probe.log',
  JSON.stringify({ loc: 'api.ts:23', h: 'H1', ts: Date.now(), data: {...} }) + '\n')

原则： 每条标注 h（假设编号）、只放相关变量、加 DO NOT COMMIT 注释。

Phase 3: 收集日志

1. 告知用户"已插入探针，请复现 bug"
2. 用户复现后，读 /tmp/debug-probe.log 或浏览器 Network 面板的 POST 请求
3. 无日志 → 先问用户是否已复现，不要默默换方案
4. 按 h 字段分组分析

Phase 4: 分析收敛

• 数据支持假设 → 定位根因，进入 Phase 5
• 所有假设被排除 → 生成新假设，回到 Phase 2
• 日志不足 → 补插桩，回到 Phase 2

Phase 5: 修复与验证

1. 基于根因生成最小化修复（通常 2-5 行）
2. 用户验证有效 → 进入 Phase 6
3. 无效 → 保留关键插桩，回到 Phase 1

Phase 6: 清理

必须执行：

1. grep -rn "DEBUG PROBE\|\/\/ DEBUG PROBE" --include="*.ts" --include="*.vue" --include="*.js" 找到并删除所有临时日志行
2. 移除新增的 import（如 appendFileSync）
3. 删除 vite.config.ts 中新增的 probe 中间件代码
4. 停止探针服务器：kill $(lsof -ti:9876) 2>/dev/null
5. > /tmp/debug-probe.log 清空日志

安全红线

• 插桩代码绝对不能提交
• 日志不能含密钥/token/密码
• 调试结束清空日志文件

反模式

• ❌ 跳过假设直接修
• ❌ 插桩 20 个位置
• ❌ dump 整个 store
• ❌ 忘记清理插桩
• ❌ 一次不成功就放弃
• ❌ 没看到日志就换方案