调试
让你的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等)——添加这个
到客户端的配置文件:```json
{
"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.调试一些东西
- 在VS Code中启动调试会话(
F5) - 问你的AI: “设置一个用户身份验证失败的断点,并向我显示
请求对象中有什么“ - 看着它工作
类型 / 在聊天中查看指导工作流程,如 /debug-crash 或
/trace-variable.
两种模式
辅助(默认): 您可以控制执行(F5,步骤,继续)。AI设置
断点并检查状态。有利于学习和动手。
全自动化: AI控制一切——开始会话,继续
过去的断点,工作。适用于“只是找到bug”的场景。```json
{ "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”:
|设置|默认值|它的作用|
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| `debugssy.mcp.port` | `3000` |服务器端口。如果使用3000,请更改。 |
| `debugssy.automationLevel` | `assisted` | `assisted` 或 `full` |
| `debugssy.expressionValidationLevel` | `moderate` |有多多疑 `evaluate_expression`.选项: `strict`, `moderate`, `permissive`, `disabled` |
| `debugssy.maxExpressionLength` | `100` |已求值表达式的最大字符数|
| `debugssy.waitForBreakpointTimeout` | `5000` |多长时间 `wait_for_breakpoint` 等待时间(ms)|
| `debugssy.allowStepOperations` | `false` |在完全模式下启用step_over/into/out|
为了更严格的安全性,请在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块的东西:```bash
# 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` --调试适配器协议集成
______________________________________________________________________
## 从源头构建```bash
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吉列尔莫·加西亚·马内兹
