Back to Details

dynamic-debugger

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dynamic Debugger Skill

动态调试Skill

Interactive debugging capability fer Claude Code via DAP-MCP integration. Debug yer code in natural language without leavin' the conversation.
为Claude Code提供通过DAP-MCP集成实现的交互式调试能力。无需离开对话界面，即可用自然语言调试你的代码。

Overview

概述

This skill enables interactive debuggin' through the Debug Adapter Protocol (DAP) via MCP server integration. Set breakpoints, step through code, inspect variables, and control execution flow across multiple programming languages using natural language commands.
What ye get:
  • Natural language debugging commands ("set breakpoint at line 42")
  • Current support: Python (debugpy), C/C++/Rust (lldb)
  • Planned support: JavaScript/TypeScript, Go, Java, .NET (see configs/future/)
  • Automatic intent and language detection
  • Session management with resource limits
  • Graceful error handling and recovery
该Skill通过Debug Adapter Protocol（DAP）与MCP服务器集成，实现交互式调试。支持使用自然语言命令在多种编程语言中设置断点、单步执行代码、检查变量以及控制执行流程。
你将获得：
  • 自然语言调试命令（如“在第42行设置断点”）
  • 当前支持语言： Python（debugpy）、C/C++/Rust（lldb）
  • 计划支持语言： JavaScript/TypeScript、Go、Java、.NET（详见configs/future/目录）
  • 自动意图与语言检测
  • 带资源限制的会话管理
  • 优雅的错误处理与恢复机制

Activation (Opt-In)

激活方式（需主动开启）

This skill is DISABLED by default (
disableModelInvocation: true
).
To enable:
  1. Explicit invocation (recommended):
    "Use the dynamic-debugger skill to debug this function"
  2. Auto-activation (edit SKILL.md frontmatter):
    yaml
    disableModelInvocation: false # or remove this line
Why opt-in?
  • Requires external dap-mcp server installation
  • Starts debugger processes (resource intensive)
  • Full filesystem access needed
  • Best enabled only when actively debugging
该Skill默认处于禁用状态（
disableModelInvocation: true
）。
启用方法：
  1. 显式调用（推荐）：
    "使用dynamic-debugger skill调试这个函数"
  2. 自动激活（编辑SKILL.md前置配置）：
    yaml
    disableModelInvocation: false # 或删除该行配置
为何需主动开启？
  • 需要安装外部dap-mcp服务器
  • 会启动调试进程（占用较多系统资源）
  • 需要完整的文件系统访问权限
  • 仅在实际调试时启用最佳

Prerequisites

前置条件

Required:
  • dap-mcp server installed (
    pip install dap-mcp
    or 
    uv pip install dap-mcp
    )
  • Language-specific debuggers (current support):
    • Python: debugpy (
      pip install debugpy
      )
    • C/C++/Rust: lldb-dap (install lldb with DAP support)
Verification:
bash
undefined
必需组件：
  • 已安装dap-mcp服务器（
    pip install dap-mcp
    或 
    uv pip install dap-mcp
    ）
  • 对应语言的调试器（当前支持）：
    • Python：debugpy（
      pip install debugpy
      ）
    • C/C++/Rust：lldb-dap（安装支持DAP的lldb版本）
验证方法：
bash
undefined

Check dap-mcp installation

检查dap-mcp安装情况

python3 -m dap_mcp --help
python3 -m dap_mcp --help

Check language debuggers

检查语言调试器

python -c "import debugpy; print('debugpy ready')" which gdb dlv version
undefined
python -c "import debugpy; print('debugpy ready')" which gdb dlv version
undefined

Quick Start

快速开始

Scenario 1: Python Async Bug

场景1：Python异步函数Bug

User: "This async function isn't awaiting properly. Debug it."
Skill activates automatically:
  1. Detects debugging intent (high confidence)
  2. Identifies Python from file extensions
  3. Starts debugpy session
  4. Sets breakpoint at async function
  5. Shows await state and variable values
用户： "这个异步函数没有正确执行await，帮我调试。"
Skill自动激活：
  1. 检测到调试意图（高置信度）
  2. 通过文件扩展名识别为Python语言
  3. 启动debugpy会话
  4. 在异步函数处设置断点
  5. 展示await状态与变量值

Scenario 2: C++ Segfault

场景2：C++段错误

User: "Getting segfault in malloc. Set a breakpoint."
Skill response:
  1. Explicit trigger detected ("set a breakpoint")
  2. Identifies C++ from file extensions
  3. Starts gdb session
  4. Catches segfault with stack trace
  5. Inspects pointer values at crash point
用户： "调用malloc时出现段错误，帮我设置断点。"
Skill响应：
  1. 检测到显式触发词（“设置断点”）
  2. 通过文件扩展名识别为C++语言
  3. 启动gdb会话
  4. 捕获段错误并生成堆栈跟踪
  5. 检查崩溃点的指针值

Scenario 3: JavaScript Promise Chain

场景3：JavaScript Promise链问题

User: "Why is this Promise chain not resolving?"
Skill response:
  1. Implicit trigger detected ("why is")
  2. Asks confirmation (medium confidence)
  3. Identifies JavaScript from package.json
  4. Sets breakpoints in .then() handlers
  5. Steps through async flow
用户： "为什么这个Promise链没有resolve？"
Skill响应：
  1. 检测到隐式触发词（“为什么”）
  2. 询问用户确认（中等置信度）
  3. 通过package.json识别为JavaScript语言
  4. 在.then()处理器处设置断点
  5. 单步执行异步流程

Common Workflows

常见工作流

Starting a Debug Session

启动调试会话

Explicit triggers (auto-start):
  • "debug this"
  • "set a breakpoint at line X"
  • "step through this function"
  • "inspect variable X"
Implicit triggers (may ask confirmation):
  • "Why is X wrong?"
  • "This isn't working"
  • "Trace execution of X"
  • "Test is failing in X"
显式触发词（自动启动）：
  • "调试这段代码"
  • "在第X行设置断点"
  • "单步执行这个函数"
  • "检查变量X的值"
隐式触发词（可能需要确认）：
  • "为什么X运行异常？"
  • "这段代码不工作"
  • "跟踪X的执行流程"
  • "测试在X处失败"

Debugging Commands

调试命令

Breakpoint management:
  • "Set breakpoint at line 42"
  • "Remove breakpoint at line 42"
  • "List all breakpoints"
Execution control:
  • "Step over" (execute current line)
  • "Step into" (enter function call)
  • "Step out" (exit current function)
  • "Continue" (run until next breakpoint)
Variable inspection:
  • "What's the value of userId?"
  • "Show all local variables"
  • "Evaluate expression: x + y"
Session management:
  • "Show call stack"
  • "List threads/goroutines"
  • "Stop debugging"
断点管理：
  • "在第42行设置断点"
  • "移除第42行的断点"
  • "列出所有断点"
执行控制：
  • "单步跳过"（执行当前行）
  • "单步进入"（进入函数调用）
  • "单步退出"（退出当前函数）
  • "继续执行"（运行至下一个断点）
变量检查：
  • "userId的值是多少？"
  • "显示所有局部变量"
  • "计算表达式：x + y"
会话管理：
  • "显示调用栈"
  • "列出线程/协程"
  • "停止调试"

Navigation Guide (MANDATORY)

导航指南（强制要求）

Load these files on demand based on context:
需根据上下文按需加载以下文件：

When to Load reference.md

何时加载reference.md

Trigger: User needs specific API details, configuration syntax, or error codes Contains: Complete API reference, language configurations, session management API, error handling details, resource limits Size: 3,000-4,000 tokens Example queries: "How do I configure the Go debugger?", "What are the resource limits?", "Show me all error codes"
触发条件： 用户需要特定API细节、配置语法或错误码 包含内容： 完整API参考、语言配置、会话管理API、错误处理细节、资源限制 Token规模： 3000-4000 Token 示例查询： "如何配置Go调试器？"、"资源限制有哪些？"、"展示所有错误码"

When to Load examples.md

何时加载examples.md

Trigger: User wants working code examples or specific debugging scenarios Contains: Production-ready debugging examples for all 6 languages with complete workflows Size: 2,000-3,000 tokens Example queries: "Show me a Python async debugging example", "How do I debug a Rust panic?", "Example of goroutine deadlock debugging"
触发条件： 用户需要可运行的代码示例或特定调试场景 包含内容： 支持全部6种语言的生产级调试示例及完整工作流 Token规模： 2000-3000 Token 示例查询： "展示Python异步调试示例"、"如何调试Rust panic？"、"协程死锁调试示例"

When to Load patterns.md

何时加载patterns.md

Trigger: User asks about best practices, architectural patterns, or debugging strategies Contains: Production debugging patterns, performance techniques, security best practices, common pitfalls Size: 1,500-2,000 tokens Example queries: "What are best practices for debugging?", "How do I debug performance issues?", "Common security mistakes?"
Default behavior: Use only SKILL.md for basic debugging commands. Load supporting files only when explicitly needed.
触发条件： 用户询问最佳实践、架构模式或调试策略 包含内容： 生产环境调试模式、性能优化技巧、安全最佳实践、常见陷阱 Token规模： 1500-2000 Token 示例查询： "调试的最佳实践有哪些？"、"如何调试性能问题？"、"常见安全错误？"
默认行为： 基础调试命令仅使用SKILL.md。仅在明确需要时加载支持文件。

Session Management

会话管理

Single concurrent session: Only one debugging session per user at a time Timeouts:
  • Session idle: 30 minutes
  • Connection idle: 5 minutes
  • Startup: 10 seconds max
Resource limits:
  • Memory: 4GB max for debugged process
  • No CPU limits (debugging is resource-intensive)
  • Automatic cleanup on session end
单并发会话限制： 每个用户同一时间仅能存在一个调试会话 超时设置：
  • 会话闲置超时：30分钟
  • 连接闲置超时：5分钟
  • 启动超时：最长10秒
资源限制：
  • 内存：调试进程最大占用4GB
  • 无CPU限制（调试本身属于资源密集型操作）
  • 会话结束时自动清理资源

Language Detection

语言检测

Automatic detection via:
  1. File extensions (primary signal)
  2. Manifest files (package.json, Cargo.toml, go.mod)
  3. Project structure analysis
Confidence thresholds:
  • High (>90%): Auto-select language
  • Medium (70-90%): Ask user confirmation
  • Low (<70%): Prompt user to specify
Manual override: "Debug this as Python code" (bypasses auto-detection)
自动检测方式：
  1. 文件扩展名（主要依据）
  2. 清单文件（package.json、Cargo.toml、go.mod）
  3. 项目结构分析
置信度阈值：
  • 高置信度（>90%）：自动选择对应语言
  • 中等置信度（70-90%）：询问用户确认
  • 低置信度（<70%）：提示用户指定语言
手动覆盖： "将这段代码作为Python进行调试"（绕过自动检测）

Troubleshooting

故障排除

dap-mcp Server Not Found

dap-mcp服务器未找到

Symptom: "dap-mcp server not available" Solution:
bash
npm install -g dap-mcp
npx dap-mcp --version
症状： "dap-mcp server not available" 解决方案：
bash
npm install -g dap-mcp
npx dap-mcp --version

Language Debugger Missing

语言调试器缺失

Symptom: "debugpy not found" or "gdb not available" Solution: Install language-specific debugger (see Prerequisites)
症状： "debugpy not found" 或 "gdb not available" 解决方案： 安装对应语言的调试器（详见前置条件部分）

Session Timeout

会话超时

Symptom: "Session timed out after 30 minutes" Solution: Start new session with "debug this"
症状： "Session timed out after 30 minutes" 解决方案： 使用“调试这段代码”重新启动会话

Concurrent Session Blocked

并发会话被阻止

Symptom: "Another debugging session is active" Solution: Stop existing session with "stop debugging" or wait for timeout
症状： "Another debugging session is active" 解决方案： 使用“停止调试”结束现有会话，或等待超时自动结束

Memory Limit Exceeded

内存限制超出

Symptom: "Debugged process exceeded 4GB memory limit" Solution: Reduce data structures or use sampling for large datasets
症状： "Debugged process exceeded 4GB memory limit" 解决方案： 减小数据结构规模，或对大型数据集使用采样方式

Error Recovery

错误恢复

All errors provide:
  1. Clear description of what failed
  2. Actionable recovery steps
  3. Manual fallback commands if needed
Graceful degradation: If dap-mcp unavailable, skill suggests manual debugger commands.
所有错误提示包含：
  1. 清晰的失败描述
  2. 可执行的恢复步骤
  3. 必要时提供手动调试命令作为备选
优雅降级： 若dap-mcp不可用，Skill会推荐手动调试命令。

Token Budget

Token预算

  • Orchestration overhead: <100 tokens per command
  • Intent detection: <20 tokens
  • Language detection: <30 tokens (cached after first detection)
  • Error messages: <50 tokens
Design philosophy: Keep skill orchestration minimal. Most tokens spent on actual debugging interaction, not overhead.
  • 编排开销：每个命令<100 Token
  • 意图检测：<20 Token
  • 语言检测：<30 Token（首次检测后缓存结果）
  • 错误提示：<50 Token
设计理念： 尽量简化Skill的编排逻辑。大部分Token用于实际调试交互，而非系统开销。

Security

安全

⚠️ IMPORTANT SECURITY CONSIDERATIONS:
  • Full Filesystem Access: This skill can read/write ANY file on your system (required for debugging)
  • Process Execution: Starts debugger processes with full system permissions
  • No Sandboxing: Debugged code runs with your user privileges
  • Local-Only Default: Server binds to localhost only (do NOT expose to network)
  • Sensitive Data: Debugger can access memory, environment variables, credentials in running processes
Best Practices:
  • Only debug code you trust
  • Review debugger configurations before use
  • Be cautious with production credentials in environment
  • Use dedicated development environments for sensitive projects
  • Never debug untrusted binaries
Process Isolation:
  • Debugger runs in separate process from Claude Code
  • Cleanup script terminates all debugger processes on exit
⚠️ 重要安全注意事项：
  • 完整文件系统访问权限： 该Skill可读写系统上的任意文件（调试必需）
  • 进程执行权限： 以完整系统权限启动调试进程
  • 无沙箱隔离： 被调试代码以当前用户权限运行
  • 默认仅本地访问： 服务器默认绑定localhost（请勿暴露至网络）
  • 敏感数据风险： 调试器可访问内存、环境变量及运行进程中的凭证信息
最佳实践：
  • 仅调试你信任的代码
  • 使用前检查调试器配置
  • 谨慎处理环境中的生产级凭证
  • 对敏感项目使用专用开发环境
  • 绝不调试不可信的二进制文件
进程隔离：
  • 调试器与Claude Code运行在独立进程中
  • 退出时清理脚本会终止所有调试进程

Performance Targets

性能目标

  • Server startup: <10 seconds
  • Breakpoint operations: <2 seconds
  • Step operations: <3 seconds
  • Variable inspection: <2 seconds
  • 服务器启动时间：<10秒
  • 断点操作：<2秒
  • 单步操作：<3秒
  • 变量检查：<2秒

Next Steps

下一步操作

  1. Verify prerequisites (see Prerequisites section)
  2. Start debugging with natural language ("debug this")
  3. Load supporting files only when needed (see Navigation Guide)
  4. Review examples for specific scenarios (see examples.md)
  5. Learn patterns for production debugging (see patterns.md)
Philosophy: Ruthlessly simple orchestration. All complexity lives in dap-mcp server, not in this skill. We're just the friendly pirate captain givin' orders to the debugger crew.
  1. 验证前置条件（详见前置条件章节）
  2. 开始调试：使用自然语言命令（如“调试这段代码”）
  3. 按需加载支持文件（详见导航指南）
  4. 查看示例：获取特定场景的调试方法（详见examples.md）
  5. 学习调试模式：掌握生产环境调试技巧（详见patterns.md）
设计理念： 极致简化的编排逻辑。所有复杂逻辑均在dap-mcp服务器中实现，而非该Skill。我们只是给调试团队下达指令的友好“海盗船长”。