mcpField
D
deep-debug

deep-debug

github.com/jezweb开发1.1k162 次安装3 周前更新
代码仓库

关于 deep-debug

面向开发者的引导式调试技能，适用于常规修复无效的问题。它先收集证据，再由三个 Agent 并行调查，并用同类证据验证修复。

主要功能

  1. 01先收集证据再调试
  2. 02三个 Agent 并行调查
  3. 03检查浏览器网络与控制台
  4. 04交叉比对调查结果
  5. 05用相同证据验证修复

适用场景

  1. 01调查重复 API 请求
  2. 02追踪复杂 React 状态问题
  3. 03诊断浏览器与 API 交互故障

MCP 相关

浏览器问题调查时可选用 Chrome MCP 工具检查网络请求、控制台消息和页面状态。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jezweb/claude-skills --skill deep-debug

安装后在 Claude Code 中输入/deep-debug确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
.claude-plugin/
plugin.json
commands/
debug.md
rules/
chrome-evidence-tools.md
evidence-first.md
parallel-agents.md
templates/
investigation-report.md
parallel-agent-prompts.md

详细介绍

深度调试 - 多 Agent 调查

状态：已可用于生产环境 最后更新：2026-02-03 依赖项：Chrome MCP 工具（可选）、调试 Agent、代码审查 Agent

适用场景

  • 陷入循环 - 尝试了多种修复方法，但问题依旧
  • 浏览器与 API 交互问题 - 需要查看 Network 选项卡和控制台日志
  • 症状不符合预期 - 存在更深层的问题
  • 复杂的状态管理问题 - React Hooks、闭包、竞态条件

命令

命令用途
/debug通过收集证据和并行调查，引导完成调试工作流

快速开始

/debug [description of the bug]

也可以直接这样提出请求：

  • “这个错误把我难住了，你能深入调查一下吗？”
  • “这个错误用常规方法很难调试”
  • “我需要你深入查查这个问题”

流程

阶段 1：收集证据（先收集，再提出假设）

对于浏览器相关问题，使用 Chrome MCP 工具：

// Get network requests (look for duplicates, failures, timing)
mcp__claude-in-chrome__read_network_requests

// Get console logs (errors, warnings, debug output)
mcp__claude-in-chrome__read_console_messages

// Get page state
mcp__claude-in-chrome__read_page

对于后端问题，收集：

  • 错误日志和堆栈跟踪
  • 请求/响应负载
  • 数据库查询日志
  • 时间信息
阶段 2：并行启动调查（3 个 Agent）

将收集到的证据同时提供给以下 Agent：

Agent 1：执行跟踪器（debugger）
Task(subagent_type="debugger", prompt="""
EVIDENCE: [paste network/console evidence]

Trace the execution path that leads to this bug. Find:
1. Where the bug originates
2. What triggers it
3. The exact line/function causing the issue

Focus on TRACING, not guessing.
""")
Agent 2：模式分析器（code-reviewer）
Task(subagent_type="code-reviewer", prompt="""
EVIDENCE: [paste evidence]

Review the relevant code for common bug patterns:
- React useCallback/useMemo dependency issues
- Stale closures
- Race conditions
- State update ordering
- Missing error handling

Find patterns that EXPLAIN the evidence.
""")
Agent 3：入口点映射器（Explore）
Task(subagent_type="Explore", prompt="""
EVIDENCE: [paste evidence]

Map all entry points that could trigger this behavior:
- All places [function] is called
- All event handlers involved
- All state updates that affect this

Find if something is being called MULTIPLE TIMES or from UNEXPECTED places.
""")
阶段 3：交叉比对调查结果

Agent 完成后，关注以下情况：

信号含义
3 个 Agent 均认同根本原因置信度高 - 修复问题
2 个认同，1 个不同调查差异
3 个结论各不相同需要更多证据
阶段 4：验证修复

实施修复后，重新收集相同证据进行确认：

  • Network 选项卡显示预期行为
  • 控制台没有错误
  • 状态更新正确

真实示例：API 重复调用问题

收集到的证据

Network 选项卡显示同一条消息触发了 2 个 fetch 请求。

并行调查结果
Agent发现
debuggeruseCallback 依赖项中的 state.messages 导致回调重新创建
code-reviewer发现相同问题，并解释了导致该问题的 React 模式
Explore确认 UI 层没有重复调用（排除该原因）
根本原因（共识）

sendMessage 的 useCallback 在依赖数组中包含 state.messages。每次状态更新都会重新创建回调，导致 React 重新渲染时出现重复调用。

修复方法

使用 stateRef 访问当前状态，无需将其包含在依赖项中：

const stateRef = useRef(state);
stateRef.current = state;

const sendMessage = useCallback(async (text) => {
  // Use stateRef.current instead of state
  const messages = stateRef.current.messages;
  // ...
}, [/* state.messages removed */]);

可发现的常见错误模式

React Hook 问题
  • state 位于 useCallback 依赖项中，导致回调重新创建
  • 缺少依赖项，导致闭包过期
  • useEffect 多次运行
API/网络问题
  • 重复请求（可在 Network 选项卡中看到）
  • 请求之间的竞态条件
  • CORS 失败
  • 超时处理
状态管理问题
  • 状态更新未能正确批处理
  • 乐观更新与服务器响应冲突
  • 多个真实数据源

Chrome 工具速查

工具用途
read_network_requests查看所有 fetch/XHR 调用、重复请求和失败请求
read_console_messages查看错误、警告和调试日志
read_page查看当前 DOM 状态
javascript_tool在页面上下文中执行调试代码

成功提示

  1. 先看证据，再提假设 - 有具体数据之前不要猜测
  2. Network 选项卡很有用 - 大多数前端问题都会在那里显现
  3. 并行 Agent 节省时间 - 一次获取 3 个视角，胜过依次猜测
  4. 交叉比对调查结果 - 结论一致 = 置信度高
  5. 使用相同证据验证 - 用发现问题时使用的相同工具确认修复效果

评论

支持 Markdown