dynamic-debugger

动态调试技能

通过 DAP-MCP 集成，为 Claude Code 提供交互式调试能力。无需离开对话，即可用自然语言调试代码。

概述

此技能通过 MCP 服务集成，使用调试适配器协议（DAP）实现交互式调试。使用自然语言命令设置断点、单步执行代码、检查变量，并控制多种编程语言中的执行流程。

你将获得：

• 自然语言调试命令（“在第 42 行设置断点”）
• **当前支持：**Python（debugpy）、C/C++/Rust（lldb）
• **计划支持：**JavaScript/TypeScript、Go、Java、.NET（参见 configs/future/）
• 自动检测意图和语言
• 带资源限制的会话管理
• 稳健的错误处理和恢复机制

启用（选择加入）

此技能默认处于禁用状态（disableModelInvocation: true）。

启用方法：

1. 显式调用（推荐）：

   "Use the dynamic-debugger skill to debug this function"
   

2. 自动激活（编辑 SKILL.md frontmatter）：

   disableModelInvocation: false # or remove this line
   

为何采用选择加入？

• 需要安装外部 dap-mcp 服务
• 会启动调试器进程（资源占用较大）
• 需要完整的文件系统访问权限
• 最好仅在主动调试时启用

先决条件

必需：

• 已安装 dap-mcp 服务（pip install dap-mcp 或 uv pip install dap-mcp）
• 特定语言的调试器（当前支持）：
  • Python：debugpy（pip install debugpy）
  • C/C++/Rust：lldb-dap（安装支持 DAP 的 lldb）

验证：

# Check dap-mcp installation
python3 -m dap_mcp --help

# Check language debuggers
python -c "import debugpy; print('debugpy ready')"
which gdb
dlv version

快速开始

场景 1：Python 异步 Bug

用户：“这个异步函数没有正确等待。帮我调试一下。”

技能自动激活：

1. 检测到调试意图（置信度高）
2. 根据文件扩展名识别出 Python
3. 启动 debugpy 会话
4. 在异步函数处设置断点
5. 显示 await 状态和变量值

场景 2：C++ 段错误

用户：“malloc 发生段错误了。设置一个断点。”

技能响应：

1. 检测到显式触发词（“设置断点”）
2. 根据文件扩展名识别出 C++
3. 启动 gdb 会话
4. 捕获段错误并显示堆栈跟踪
5. 检查崩溃位置的指针值

场景 3：JavaScript Promise 链

用户：“为什么这个 Promise 链没有解析？”

技能响应：

1. 检测到隐式触发词（“为什么”）
2. 请求确认（置信度中等）
3. 根据 package.json 识别出 JavaScript
4. 在 .then() 处理程序中设置断点
5. 单步跟踪异步流程

常见工作流

启动调试会话

显式触发词（自动启动）：

• “调试这个”
• “在第 X 行设置断点”
• “单步执行这个函数”
• “检查变量 X”

隐式触发词（可能会请求确认）：

• “X 为什么不对？”
• “这个无法正常工作”
• “跟踪 X 的执行过程”
• “X 中的测试失败了”

调试命令

断点管理：

• “在第 42 行设置断点”
• “移除第 42 行的断点”
• “列出所有断点”

执行控制：

• “单步跳过”（执行当前行）
• “单步进入”（进入函数调用）
• “单步跳出”（退出当前函数）
• “继续”（运行至下一个断点）

变量检查：

• “userId 的值是什么？”
• “显示所有局部变量”
• “计算表达式：x + y”

会话管理：

• “显示调用堆栈”
• “列出线程/goroutine”
• “停止调试”

导航指南（必须遵守）

根据上下文按需加载以下文件：

何时加载 reference.md

**触发条件：**用户需要具体的 API 详细信息、配置语法或错误代码 **包含内容：**完整的 API 参考、语言配置、会话管理 API、错误处理详情、资源限制 **大小：**3,000-4,000 个 token 示例问题：“如何配置 Go 调试器？”，“资源限制有哪些？”，“显示所有错误代码”

何时加载 examples.md

触发条件： 用户需要可运行的代码示例或特定调试场景 包含内容： 涵盖全部 6 种语言、包含完整工作流的生产级调试示例 大小： 2,000-3,000 个 token 示例查询：“给我看一个 Python 异步调试示例”“如何调试 Rust panic？”“goroutine 死锁调试示例”

何时加载 patterns.md

触发条件： 用户询问最佳实践、架构模式或调试策略 包含内容： 生产级调试模式、性能技巧、安全最佳实践、常见陷阱 大小： 1,500-2,000 个 token 示例查询：“调试的最佳实践有哪些？”“如何调试性能问题？”“常见的安全错误有哪些？”

默认行为： 基础调试命令仅使用 SKILL.md。仅在明确需要时加载支持文件。

会话管理

单个并发会话： 每位用户一次只能有一个调试会话 超时：

• 会话空闲：30 分钟
• 连接空闲：5 分钟
• 启动：最多 10 秒

资源限制：

• 内存：被调试进程最多 4GB
• 不限制 CPU（调试会大量占用资源）
• 会话结束时自动清理

语言检测

通过以下方式自动检测：

1. 文件扩展名（主要信号）
2. 清单文件（package.json、Cargo.toml、go.mod）
3. 项目结构分析

置信度阈值：

• 高（>90%）：自动选择语言
• 中（70-90%）：询问用户确认
• 低（<70%）：提示用户指定语言

手动覆盖：“将此代码按 Python 调试”（跳过自动检测）

故障排除

未找到 dap-mcp 服务

症状：“dap-mcp 服务不可用” 解决方案：

npm install -g dap-mcp
npx dap-mcp --version

缺少语言调试器

症状：“未找到 debugpy”或“gdb 不可用” **解决方案：**安装对应语言的调试器（参见先决条件）

会话超时

症状：“会话在 30 分钟后超时” **解决方案：**使用“调试此代码”启动新会话

并发会话受阻

症状：“另一个调试会话正在运行” **解决方案：**使用“停止调试”结束现有会话，或等待超时

超出内存限制

症状：“被调试进程超出 4GB 内存限制” **解决方案：**缩减数据结构，或对大型数据集使用抽样

错误恢复

所有错误都会提供：

1. 对失败原因的清晰说明
2. 可执行的恢复步骤
3. 必要时提供手动备用命令

**优雅降级：**如果 dap-mcp 不可用，技能会建议手动调试器命令。

Token 预算

• 编排开销：每条命令 <100 个 token
• 意图检测：<20 个 token
• 语言检测：<30 个 token（首次检测后缓存）
• 错误消息：<50 个 token

**设计理念：**尽量减少技能编排开销。大部分 token 用于实际调试交互，而非开销。

安全

⚠️ 重要安全注意事项：

• **完整文件系统访问权限：**此技能可以读取／写入系统上的任何文件（调试所需）
• **进程执行：**以完整系统权限启动调试器进程
• **无沙箱：**被调试代码以你的用户权限运行
• **默认仅限本地：**服务仅绑定到 localhost（切勿暴露到网络）
• **敏感数据：**调试器可以访问运行中进程的内存、环境变量和凭据

最佳实践：

• 只调试你信任的代码
• 使用前检查调试器配置
• 谨慎处理环境中的生产凭据
• 对敏感项目使用专用开发环境
• 切勿调试不受信任的二进制文件

进程隔离：

• 调试器在独立于 Claude Code 的进程中运行
• 退出时，清理脚本会终止所有调试器进程

性能目标

• 服务启动：<10 秒
• 断点操作：<2 秒
• 单步操作：<3 秒
• 变量检查：<2 秒

后续步骤

1. 确认前置条件（请参阅“前置条件”部分）
2. 使用自然语言开始调试（“调试这个”）
3. 仅在需要时加载辅助文件（请参阅“导航指南”）
4. 查看示例，了解特定场景（请参阅 examples.md）
5. 学习模式，用于生产环境调试（请参阅 patterns.md）

---

理念： 坚持简单的编排。所有复杂性都由 dap-mcp 服务承载，而非这个技能。我们只是一位友好的海盗船长，向调试器船员发号施令。