debugssy (Gmaynez)

调试

  

让你的AI助手驱动调试器。

Debugssy将AI助手（Cursor、Copilot、Claude Desktop）连接到VS Code的 通过调试引擎 模型上下文协议。而不是单击 通过调试器UI，描述您要查找的内容。

安装 ·

______________________________________________________________________

它的作用

You: "Figure out why users get null when logging in"

AI: Sets breakpoint in auth handler → waits for hit → inspects `user` object →
    traces call stack → spots missing WHERE clause in the query. Done.

AI获得了设置断点的工具（包括条件、点击次数、日志点）， 通过MCP读取变量、遍历调用堆栈和计算表达式。 你保持控制 _当_ 调试运行或完全移交控制权。

适用于VS Code可以调试的任何语言：JavaScript、TypeScript、Python、， Go、Java、C++、Rust，随便你怎么说。

推荐型号： 克劳德4.5俳句或格罗克4.1快速（速度+成本）。

______________________________________________________________________

快速开始

1.安装扩展

搜索 “调试” 在VS Code的扩展面板中(Ctrl+Shift+X)，或者抓住它 发件人：

• VS代码市场
• 打开VSX （VSCodium、Gitpod、，

等等）

2.连接你的AI

VS代码（副本）和游标——零配置。 扩展注册其MCP 服务器自动。只需安装Debugssy并开始聊天。无JSON编辑 需要。

如果你有旧的手册 "debugssy" 在设置中输入，将其删除到 避免重复。

其他MCP客户端 （克劳德桌面、克劳德代码、OpenCode等）——添加这个 到客户端的配置文件：

{
  "mcpServers": {
    "debugssy": { "url": "http://localhost:3000/mcp" }
  }
}

配置文件位置：

• 克劳德桌面：

~/Library/Application Support/Claude/claude_desktop_config.json （Mac）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）

• 克劳德代码/开放代码/其他： 查看客户的文档——URL为

总是 http://localhost:3000/mcp

3.调试一些东西

1. 在VS Code中启动调试会话(F5)
2. 问你的AI： _“设置一个用户身份验证失败的断点，并向我显示

请求对象中有什么“_

1. 看着它工作

类型 / 在聊天中查看指导工作流程，如 /debug-crash 或 /trace-variable.

______________________________________________________________________

两种模式

辅助（默认）： 您可以控制执行（F5，步骤，继续）。AI设置 断点并检查状态。有利于学习和动手。

全自动化： AI控制一切——开始会话，继续 过去的断点，工作。适用于“只是找到bug”的场景。

{ "debugssy.automationLevel": "full" }

副驾驶用户：切换模式后重新启动VS Code（它不会刷新工具 动态）。

______________________________________________________________________

可用工具

您的AI通过MCP看到这些：

检查 （始终可用）： get_debug_state, get_variables, get_call_stack, evaluate_expression, get_console_output, get_threads

断点 （始终可用）： set_breakpoint, remove_breakpoint, list_breakpoints, toggle_breakpoint, remove_all_breakpoints

set_breakpoint 支持条件(user.role === 'admin')，点击次数 (> 10)，并记录消息（日志点）。

执行控制 （仅限全模式）： start_debugging, stop_debugging, continue, pause, restart, wait_for_breakpoint

步骤操作(step_over, step_into, step_out)全部可用 模式（如果启用） debugssy.allowStepOperations.通常是不必要的--战略性的 断点+继续对于AI调试更快。

______________________________________________________________________

设置

打开VS Code设置并搜索“debugssy”：

为了更严格的安全性，请在MCP客户端中配置一个分配列表——请参阅 允许_用户.md.

______________________________________________________________________

安全

Debugssy仅在本地主机上运行。你的代码永远不会离开你的机器。

表达式验证器阻止明显的注入尝试(eval, require('fs'), process.exit等），并要求确认任何事情 可疑。偏执的四个层次： strict （仅白名单）， moderate （默认情况下，阻止已知的危险模式）， permissive （仅屏蔽恐怖内容 东西）， disabled （你只能靠自己了）。

人工智能辅助调试的最佳实践：

1. 重新开始。 在调试会话中使用新的AI对话以避免提示

从早期背景中注入。

1. 跳过网络搜索。 不要在同一次对话中搜索网络——外部

内容物是及时注射的主要载体。

1. 回顾启发提示。 当验证器询问表达式时，

在批准之前，请仔细阅读。

详细信息： 安全.md, MCP_合作.md

______________________________________________________________________

故障排除

“没有活动的调试会话” --开始调试(F5)在要求AI 检查事物。调试器需要运行。

端口3000正在使用中 --更改 debugssy.mcp.port 对于其他事物（3001、8080、3003）， 不管怎样）。或者杀了那些占了3000块的东西：

# Windows
netstat -ano | findstr :3000
taskkill /PID 
 /F

# Mac/Linux
lsof -ti:3000 | xargs kill -9

AI无法连接 --检查VS代码输出面板 (View → Output → Debugssy).验证服务器是否已启动 curl http://localhost:3000/health确保你的AI配置指向 http://localhost:3000/mcp.

变量为空 --必须在断点处暂停执行。如果它正在运行， 没有什么可检查的。也试试 scope: "Local" 以滤除噪声。

副驾驶看不到新工具 --重新启动VS代码。Copilot缓存工具 列表。

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────┐
│  VS Code Extension                              │
│                                                 │
│   MCP Server (localhost:3000)                   │
│        ↓                                        │
│   ToolRouter → Security Layer → Tool Registry   │
│        ↓                                        │
│   DAP Client ← → VS Code Debug API              │
└─────────────────────────────────────────────────┘
        ↑
        │ HTTP + MCP Protocol
        ↓
┌─────────────────────┐
│   AI Assistant      │
│ (Cursor/Copilot/    │
│  Claude Desktop)    │
└─────────────────────┘

MCP服务器使用流式HTTP（规范版本2025-06-18）。会话ID为 crypto.randomUUID()所有工具输入都经过Zod验证。

关键文件，如果你正在潜水：

• src/MCPServer.ts --服务器设置和MCP协议处理
• src/routing/ToolRouter.ts --工具调度
• src/security/ExpressionValidator.ts --偏执狂引擎
• src/dap/Client.ts --调试适配器协议集成

______________________________________________________________________

从源头构建

git clone https://github.com/gmaynez/debugssy.git
cd debugssy
npm install
npm run compile    # Build
npm run package    # Creates .vsix
npm test           # Run tests

按 F5 在VS Code中启动扩展开发主机进行实时测试。

______________________________________________________________________

已知限制

• 一次一个MCP客户端。 如果多个AI助手连接到同一个

Debugssy实例，最新连接接管。

• Copilot缓存工具。 更改后重新启动VS代码 automationLevel.
• 没有手表表情。 使用 evaluate_expression 相反。
• 单线程假设。 默认为线程ID 1。
• 辅助模式对手动步骤视而不见。 如果在UI中单击“继续”，

AI不知道。

• 嵌套对象被截断。 责怪调试器，而不是我们。

______________________________________________________________________

贡献

发现bug了吗？ 打开一个问题.

想贡献吗？分叉它，创建一个分支，打开一个PR。遵循现有代码 风格（TypeScript、ESLint）。添加新功能的测试。

检查 好的第一个问题 对于初学者任务。

______________________________________________________________________

更多文档

• 安全.md --威胁模型、安全策略
• 允许_用户.md --锁定您的哪些工具

AI可以使用

• DEBUGSSY_PROMPT.md --AI助手详细指南
• MCP规范 --协议本身
• 调试适配器协议

--VS Code在幕后说什么

______________________________________________________________________

许可证

Apache 2.0。看 许可证.

版权所有©2025-2026吉列尔莫·加西亚·马内兹