Deebo：自主调试代理 MCP 服务器

Deebo 是一个自主调试系统，旨在集成到使用模型上下文协议 (MCP) 的编码代理工作流程中。它充当一个委托工具，可以调查软件错误，在隔离的 Git 分支中运行实验，并报告经过验证的修复，通过并行生成假设异步进行，无需人工干预。

Deebo 基本上是 Cursor、Cline、Claude、Windsurf、ChatGPT（即将推出）、Devin 等 AI 代理的最佳朋友和队友。他们一起务实地迭代，以找到代码库中棘手问题的有用解决方案。

这是 Deebo 理解 test53 linearizer 失败的 $100 tinygrad bug bounty 的一些日志，它通过生成 17 个场景代理并提出了 2 个有效的修复方案。查看 progress.md 了解 Deebo 提出的解决方案。

注意：自述文件有意冗长，以便 LLM 代理更容易安装。我强烈建议将此自述文件复制并粘贴到 chatGPT 中，或者让您的编码代理读取此文件并引导您完成该过程。

需要安装方面的帮助？在 Twitter 上私信我：@sriramenn

🔧 什么是 Deebo？

Deebo 是一个完全兼容 MCP 的代理系统，当您的编码代理（例如，Claude Desktop、Cline、Cursor、Windsurf 等）遇到无法自信修复的错误时，可以调用它。

Deebo 不依赖于单个步骤或建议，而是：

• 生成多个子进程（“场景代理”）来测试相互竞争的假设
• 在专用的 Git 分支中运行每个场景
• 验证或证伪每种方法
• 返回结构化报告和解决方案
• 可选择将会话历史记录和上下文记录到内存库中

编码代理不一定擅长调试，因为它们的主要目的是生成可用的端到端应用程序。Deebo 使您的代理能够卸载棘手的错误，否则需要多次聊天才能解决，从而使您可以更加专注于交付。

🛠️ 公开的 MCP 工具

Deebo 充当单个 MCP 服务器并公开四个工具：

工具	描述
start	开始调试会话
check	返回调试会话的当前状态
cancel	终止给定调试会话的所有进程
add_observation	记录代理的外部观察结果（例如，来自 Cline 等其他工具）

🚀 用法（这部分是为 LLM 准备的，而不是人类）

启动会话

<deebo>
  <start
    error="ReferenceError: x is not defined"
    repoPath="/my/project/path"
    context="// suspect function below\nfunction handleClick() { ... }"
    filePath="src/ui/buttons.ts"
    language="typescript"
  />
</deebo>

检查会话状态

<deebo>
  <check sessionId="session-1712268439123" />
</deebo>

这将返回一个人类可读的会话脉冲，包括：

• 母代理的当前状态
• 正在运行与已完成的场景代理
• 报告的假设
• 找到的任何 <solution>

取消会话

<deebo>
  <cancel sessionId="session-1712268439123" />
</deebo>

添加观察结果（例如，来自 Cline）

<deebo>
  <add_observation
    agentId="scenario-session-1712268439123-2"
    observation="The error disappears if we disable memoization"
  />
</deebo>

🧠 内存库（可选）

如果设置了 USE_MEMORY_BANK=true，Deebo 将启用结构化内存日志记录：

文件	描述
activeContext.md	母代理的可编辑实时日志
progress.md	已完成调试会话的摘要结果
sessions/<id>/reports/	结构化场景代理报告
sessions/<id>/logs/	来自母代理和场景的原始日志
sessions/<id>/observations/	来自 Cline 等工具的外部观察结果的日志

内存库允许 Deebo 从其错误中学习，并随着时间的推移个性化您的代码库。如果 Deebo 可以从中受益，您还可以在启动与 Deebo 的调试会话时使用 context 字段，如果需要指导，您还可以在会话中向特定代理添加观察结果。

📦 安装

先决条件

在开始之前，请确保您的系统上已安装以下内容：

• Git：克隆存储库所必需。
• Node.js：建议使用 18 或更高版本。这包括 npm，安装依赖项需要它。您可以从 nodejs.org 下载 Node.js。
• 此存储库根目录中的 docs.txt 对于粘贴到 LLM 中以请求安装 deebo 的指导非常有帮助

1. 克隆存储库

git clone https://github.com/snagasuri/deebo-prototype.git
cd deebo-prototype

2. 安装所需的 MCP 工具

Deebo 依赖于其他 MCP 服务器来与 Git 和文件系统交互。

a) 安装 uv（包括 uvx）

uv 是一个快速的 Python 包安装程序和解析器。我们建议使用官方脚本或 pipx 安装它：

• 使用独立安装程序（推荐用于 macOS/Linux）：

  curl -LsSf https://astral.sh/uv/install.sh | sh
  # 确保 ~/.local/bin 在您的 PATH 中（脚本通常会处理此问题）
  

• 使用 pipx（推荐用于隔离安装）：

  pip install pipx
  pipx ensurepath
  pipx install uv
  

  （有关 Windows 和其他方法，请参阅 uv 安装文档。）

在 config/tools.json 中，可执行文件可能无法扩展 Windows 上 npx 或 uvx 的完整路径，因此您可能必须包含绝对路径（例如 "command": "/Users/sriram/.local/bin/uvx"，对于您的 npx 路径类似，如果您遇到 ENOENT 或 spawn 错误）

b) 使用 uvx 安装 mcp-server-git

uvx install mcp-server-git

（或者，如果 uvx 失败，您可以尝试 pip install mcp-server-git。）

c) 设置 desktop-commander

Deebo 使用 desktop-commander 进行文件系统操作和运行命令。通过运行其设置命令，确保它已安装并配置为您的客户端（如 Cline 或 Claude Desktop）的 MCP 服务器：

npx @wonderwhy-er/desktop-commander@latest setup

此命令安装 desktop-commander（如果需要）并自动将其配置添加到您的 MCP 客户端的设置中。但是，如果您使用的是 Mac，您可能甚至不需要显式安装它，它将在运行时从 tools/config.json 安装。

3. 安装 Deebo 依赖项并构建

npm install
npm run build

4. 将 Deebo 注册为 MCP 服务器

将 Deebo 服务器配置添加到您的 MCP 客户端的设置文件中。

• 配置文件位置（示例）：

  • Cline (VS Code 扩展): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS), ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (Linux), %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json (Windows)
  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), ~/.config/Claude/claude_desktop_config.json (Linux), %APPDATA%\Claude\claude_desktop_config.json (Windows)

  注意：您绝对可以通过 GUI 编辑 Cline 或 Claude MCP 设置来添加 deebo。

  Claude --> 设置 --> 开发者 --> 编辑配置

  Cline --> 右上角的汉堡菜单 --> 已安装 --> “配置 MCP 服务器”

Deebo 支持 OpenRouter、Anthropic 和 Gemini 模型的任何组合。您只需将“openrouter”替换为“anthropic”或“gemini”并相应地更新模型选择即可切换它们。有关更多信息，请参阅 src/util/agent-utils.ts。将以下条目添加到该 JSON 文件中的 mcpServers 对象中。请记住将占位符值（如 /absolute/path/to/...）和 API 密钥替换为您的实际信息。

{
  "mcpServers": {
    "deebo-prototype": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 30,
      "command": "node",
      "args": [
        "--experimental-specifier-resolution=node",
        "--experimental-modules",
        "--max-old-space-size=4096",
        "/absolute/path/to/deebo-prototype/build/index.js"
      ],
      "env": {
        "NODE_ENV": "development",
        "USE_MEMORY_BANK": "true",

        "MOTHER_HOST": "openrouter",
        "MOTHER_MODEL": "anthropic/claude-3.5-sonnet",

        "SCENARIO_HOST": "openrouter",
        "SCENARIO_MODEL": "anthropic/claude-3.5-sonnet",

        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "GEMINI_API_KEY": "AIzaSy...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      },
      "transportType": "stdio"
    }
  }
}

注意： config/tools.json 中的设置适用于 Deebo 代理本身使用的工具。如果您在尝试启动 Deebo 会话时发现错误（通过转到 Cline MCP 设置 --> 已安装 --> Deebo MCP 服务器上方应显示红色文本进行检查）。仅提供与您选择的 MOTHER_HOST 和 SCENARIO_HOST 对应的 API 密钥。可以省略或留空未使用提供商的密钥。

重要提示： 修改配置文件后，重新启动您的 MCP 客户端（Cline、Claude Desktop 等），以使更改生效。

💡 工作原理

架构

• 母代理：协调调查，生成场景并编写解决方案。
• 场景代理：每个代理在其自己的 Git 分支中调查单个假设，并通过 <report> 报告发现。
• 进程隔离：所有代理都作为具有超时强制执行和独立生命周期的 Node.js 子进程运行。

工具

• git-mcp：Git 操作（分支、差异、日志）
• desktopCommander：文件 I/O、终端命令、目录

Deebo 代理本身就是客户端 - 它们使用 git-mcp 和 desktopCommander MCP 服务器进行调查。

✅ 为什么要使用 Deebo？

当您想将错误调查卸载到自我指导的代理时，Deebo 是理想的选择，该代理：

• 在您的代码库中运行真实的实验
• 使用 Git 分支进行完全隔离
• 优雅地处理失败 - 多个代理可以并行运行
• 返回经过验证的修复（不仅仅是猜测）
• 水平扩展 - 插入任何 Claude/MCP 兼容的代理

🔒 设计原则

• 工具隔离：所有突变都通过 MCP 工具完成（代理内部没有原始 fs/git 调用）
• 无状态场景代理：没有共享内存；纯函数行为
• 原始日志，而不是主观的 UI：人类可读、可跟踪的日志和报告
• 专为委托而设计：旨在由 Claude 等其他代理调用，而不是手动调用

📜 许可证

Apache 2.0