debugai-mcp

@debugai/mcp

为你的编码 Agent 配备调试器，而不是让它反复使用 grep。

你的 Agent 将错误交给 debug_error，即可获取根本原因、确切的文件和行号，以及最多 3 个按优先级排序、可直接应用的修复方案。每个修复方案都会标明是否通过了机械检查，让 Agent 知道哪些方案经过检查，哪些只是模型自己的估计。

在此之前，lookup_error 会查询项目记忆，确认此错误之前是否在这里发生过，以及当时哪个修复方案有效。它不会调用模型，也不会占用你的使用额度，因此 Agent 可以在每次失败时都调用它。在 Claude Code 中，hook 会在每条命令失败时自动运行，无需 Agent 记住这件事。

自动配置 Claude Code、Claude Desktop、Cursor、Windsurf、Zed、Gemini CLI 和 Cline。也可通过手动添加配置，在其他 MCP 客户端中使用。需要 Node 18.14.1 或更高版本。

**2.7.0 的新增内容：**现在，机器可应用的编辑会注明代码实际所在的文件；工具会提示你在问题发生时立即调用，而不是等你粘贴错误；落后的服务也会在每个会话中提示一次，而不是在每次诊断时都提示。从主文件夹、上级文件夹或文件系统根目录启动的服务，不再将这些目录视为项目：在 Agent 指定 projectRoot 之前，它不会读取本地文件。参阅更新日志。

**如果修复方案不起作用，请告诉我，我会解决。**本次发布的大部分内容，都是根据不起作用的修复方案编写的。 控制面板 → 消息，请附上你发送的错误，以及修复方案实际做了什么。消息会直接送达开发者。

设置

npx -y @debugai/mcp setup

就这么简单。它会通过浏览器为你登录（无需查找或复制密钥），为这台机器上检测到的每个 MCP 客户端写入配置，然后检查一切是否正常运行。

重启它列出的客户端，你的 Agent 就能使用这些工具了。

想先了解详情？debugai.io/start?src=npm 按客户端介绍相同的设置流程。

此命令会对你的机器做什么

运行会修改编辑器配置的命令前，值得先了解以下内容：

• 使用你在浏览器中确认的一次性短码登录。免费账户每天可调试 10 次，无需信用卡。
• 将密钥以 0600 权限存储在 ~/.debugai/config.json 中。这是唯一会存储密钥的文件。
• 在检测到的每个 MCP 客户端的配置中添加 debugai 条目。修改前会备份每个文件（<file>.debugai-backup-<timestamp>），保留文件中的其他所有设置；无法解析的文件则保持原样，并会报告。明确说明一个注意事项：如果配置中包含注释，重写时会丢弃注释，因为 JSON 没有保存注释的位置。install 会先写入，再告知你；备份中仍保留注释。install --dry-run 会在写入任何内容前告知你。
• 默认跳过 VS Code，因为 DebugAI 扩展已在其中注册此服务，重复添加条目会导致每个工具显示两次。如果你想在不安装扩展的情况下使用此服务，可以使用 install --client=vscode 添加。
• 绝不会将密钥写入客户端配置。客户端配置会提交到代码仓库，密钥不应如此。

预览但不写入任何内容：

npx -y @debugai/mcp install --dry-run

撤销所有更改：

npx -y @debugai/mcp uninstall   # removes the entry from every client config
npx -y @debugai/mcp logout      # removes the stored key

命令

命令	作用
setup	先执行 login，再执行 install，然后验证配置。这就是你要用的命令。
login	在浏览器中登录。可用 --key dbg_… 粘贴密钥（用于 CI、隔离网络的机器）。用 --force 重新关联。
logout	移除已存储的密钥。
status	查看当前启用的密钥和账号。
install	写入客户端配置。支持 --list、--client=cursor、--all、--dry-run、--remove。
uninstall	从所有客户端配置中移除该条目。
doctor	诊断配置问题：密钥、API 连通性、各客户端的接入情况、缺少版本号的配置条目，以及以明文形式保存在客户端配置中的密钥。
hook	Claude Code hook。从标准输入读取失败的命令，并输出项目记忆中的相关信息。参见 Claude Code hook。

npx -y @debugai/mcp install --list 会列出所有受支持的客户端、其配置文件在操作系统上的位置，以及 DebugAI 是否已添加到其中。

在聊天中登录

如果你的 Agent 在你登录之前调用 DebugAI 工具，该工具会返回一段简短代码和一个 URL，而不是报错。在浏览器中确认后，让 Agent 重试即可完成调用。无需编辑配置，也无需重启客户端，因为每次调用都会重新读取密钥。

工具

这些工具适用于这样的工作流程：命令失败后，lookup_error 会在一秒内从记忆中给出答案；应用已确认有效的修复后，重新运行命令。如果记忆中没有相关内容，则由 debug_error 进行分析。无论哪种情况，report_outcome 都会记录发生了什么，供下一次查询读取。

lookup_error

此项目以前遇到过这个错误吗？当时哪些方法有效？（2.6）

输入	必填	描述
errorText	是	错误或堆栈跟踪，格式与传给 debug_error 的相同。
projectRoot	否	出错所在仓库的绝对路径；当 Agent 在其他目录启动时使用。
filePath	否	该仓库中的绝对路径。其 Git 根目录用于标识项目。

该工具只执行两次简单的数据库读取，不会调用模型，因此免费：不会计入调试额度（另有宽松的速率限制，以避免滥用）。它会返回该错误在此项目中出现的次数和时间、已存储的修复方案及其当前状态，以及此项目最近报告为失败的修复方案：

• confirmed：有人应用了该修复方案并表示有效。答案会说明是有实时会话观察到错误消失，还是仅仅接受了该修复方案，因为两者的证据强度不同。
• unproven：应用该修复方案后，错误又出现过一次。请结合当前代码检查该方案。
• anti-pattern：应用该修复方案后，错误又出现了两次或更多。答案会指出该方案不可取。

未找到记录时，工具会说明这一点并提示使用 debug_error。错误文本会按照调试准备错误文本的相同方式处理，首先对凭据进行脱敏，因此对同一故障进行查询和调试会读取同一条记忆记录。查询不会写入任何内容：它不是一次调试，也不算一次错误出现记录。

debug_error

提供错误信息，获取分析。

输入	必需	描述
errorText	是	完整的错误消息、异常或堆栈跟踪。没有错误文本的 bug 也可以：说明你预期会发生什么、实际发生了什么，并附上相关代码。
language	否	auto（默认），或指定语言：javascript、typescript、python、java、csharp、go、rust、cpp、c、php、ruby、kotlin、swift、lua、shell、powershell、sql、html、css、scala、dart、elixir、r、perl。除非有理由，否则请保留为 auto：服务会读取错误文本，并且几乎总能正确判断。不在此列表中的名称（markdown、cobol）不算错误：会按 auto 处理。
codeSnippet	否	通常不需要，见下文。提供后会覆盖本地读取的内容。
snippetStartLine	否	与 codeSnippet 配合使用：代码片段首行在文件中的行号。如果片段截取自文件中间，请提供此参数。不提供时，行号从 1 开始，因此错误信息中的 Line 44 无法匹配到只有 15 行的片段。（2.7）
filePath	否	引发错误的文件路径。绝对路径也能标识错误所属的代码库。
projectRoot	否	代码库的绝对路径，适用于 Agent 从其他位置启动的情况。项目记忆和本地读取都会限定在此路径下。（2.6）
reproCommand	否	能复现故障的命令：测试、脚本或 curl。修复方案 #1 旨在让此命令通过；每个修复方案的检查也会改为运行此命令，而不是进行语法检查。DebugAI 不会运行此命令。最多 500 个字符。（2.6）
expected	否	修复 bug 后，reproCommand 应输出或执行的内容。最多 500 个字符。（2.6）

返回根本原因、最多 3 个按置信度排序的修复方案、检测到的框架，以及答案是否来自缓存。每个修复方案还会在可推导时附带：edits（Agent 的编辑工具可直接应用的精确旧字符串／新字符串）、unified_diff，以及应用后要运行的检查 verify_with。如果提供了 reproCommand，该检查就是你的命令以及你所述的预期结果；否则会进行语法级检查。它不会写入你的文件，也不会运行你的复现命令。是否应用修复由你的 Agent 决定。

如果错误超过 API 可接受的 3,000 个字符，内容会被截断，而不是拒绝：保留开头（JavaScript、Java 和 .NET 在此处输出错误）和结尾（Python 在此处输出错误），删除中间部分，并在答案中说明。lookup_error 和钩子也会执行相同的截断，因此三者会为同一个故障读取同一条记忆记录。（2.6）

每个答案的页脚都会注明记录所属的项目、该项目未启用记忆的时间和原因，以及作答所用服务的版本和引擎构建版本。使用旧副本的会话可以发现这一点，答案也可以追溯到生成它的代码。（2.6）

每个修复方案都会标注其验证状态，共有三种，而不是两种：已验证（机械检查已通过，目前包括解析和导入类检查）、检查失败（置信度会受到严格限制）或未经验证（置信度数值只是模型自身的估计，未经任何检查）。我们会标注第三种情况，而不是将其隐藏。

它会读取跟踪信息中提到的源文件（2.2）

粘贴原始回溯信息，不要附加其他内容。此服务在你的机器上运行，因此会解析堆栈跟踪中的文件，并随请求发送相关代码。在 2.2 之前，它无法做到这一点；如果粘贴的错误信息没有附带代码，返回结果通常会是 "Insufficient context for specific fix"，置信度仅为 20%。这是常见情况，而非例外。

响应会列出读取的每个文件（Read locally: src/api.ts, src/db.ts，结构化载荷中的 local_files_read 也是如此），因此错误猜测会明确显示，而不会悄无声息地发生。

它具体会读取和不会读取的内容：

• 仅限项目内部。 边界是你的 git 仓库根目录；如果当前目录不属于仓库，则以工作目录为界。如果工作目录是你的主目录，由于其上方的文件夹或文件系统根目录没有可供限定的读取边界，因此不会读取任何本地文件，并会在回复中说明这一点；传入 projectRoot 即可指定项目。检查会在符号链接解析之后进行，因此错误信息中的路径无法越出项目：../../.ssh/id_rsa 和指向外部的符号链接都会被同样拦截。
• 仅限源文件，扩展名必须在允许列表中（.ts .tsx .js .jsx .mjs .cjs .py .pyi .go .rs .rb .java .kt .kts .scala .groovy .gradle .php .cs .swift .dart .c .cc .cpp .h .hpp .ps1 .psm1 .psd1 .vue .svelte）。.env、.pem、密钥文件、转储文件和图片均不在允许列表中，因此不会被选作候选文件。
• 有大小限制：最多 3 个文件，单个文件不超过 2 MB，所有文件合计不超过 50,000 个字符。对于较大的文件，只会发送出错行附近 ±40 行的内容，而非整个文件。截取的代码块会注明这一点。
• 跳过第三方代码：node_modules、site-packages、dist、.venv 等目录中的代码不会读取。需要解释的是你的代码。
• 你提供的代码片段优先。 传入 codeSnippet 后，不会读取任何源文件。但仍会读取你的清单文件（参见限制与说明）。

读取的所有内容都会与错误文本一样，发送到 DebugAI 的 API 进行分析。如果你不希望发送某个源文件，请明确传入 codeSnippet，这样就不会读取任何源文件。每次调用带有项目根目录的 debug_error 时，都会读取限制与说明中所述的项目清单文件。

report_outcome

在 DebugAI 回答后，告知它结果如何，包括没有采用其修复方案的情况。

输入	必填	说明
debugLogId	是	debug_error 响应中的 debug_log_id。
result	是	worked、worked_modified、failed 或 unused。
fixRank	否	应用了排名第几的修复方案（1-3）。无论排名如何，都会记住该修复方案。
finalFix	worked_modified 时必填	实际奏效的代码，即修改后的代码。记住的是它，而不是建议。最多 4,000 个字符。（2.6）
newError	否	failed 时填写：应用修复后出现的错误。填写错误消息，而非解释。最多 4,000 个字符。
actualFix	否	实际解决问题的方法（当 DebugAI 的回答无效时）。最多 4,000 个字符。
toolFeedback	否	本次调用中哪些改进能让工具更有用。最多 2,000 个字符。

各判定结果代表的含义各不相同：

• worked：应用了修复，错误也消失了。该修复会成为此项目已确认的修复方案。
• worked_modified：只有经过修改后，修复才奏效。必须填写 finalFix，它会取代建议被记入记忆，以便下一个人获得有效的方案。（2.6）
• failed：应用了修复，但没有帮助。之后对该项目的分析和查询会将其显示为不应重复采用的建议。只有再次出现该错误时，已存储的修复方案才会被降级，仅报告失败不会触发降级。
• unused：没有运行我们的任何方案。对于此前已通过较早的 debugLogId 报告过的错误的重复调用，这也是正确的结果，避免同一修复被重复计数。

它使用与 VS Code 扩展反馈相同的处理流程。Agent 会收到提示，要求每次 debug_error 回答后调用一次。

以 Claude Code 为例：

粘贴一个回溯信息并询问“为什么会失败？”。Claude 会调用 debug_error，并收到类似这样的回复：

根本原因： 请求上下文关闭后仍在使用 db.session。 修复方案 1（置信度 94%）： 将查询移到请求处理程序内……

让你的 Agent 主动使用它

服务端会告知连接的 Agent 该工具的用途，但在项目文件中添加规则才是确定可靠的做法。将以下内容添加到 CLAUDE.md、.cursorrules 或 Agent 会读取的其他文件中：

When a command fails, call the debugai lookup_error tool first: it is
instant and free. If it has no confirmed fix, call debug_error before
attempting your own, and pass the command that reproduces the failure
as reproCommand. After applying a fix, call report_outcome so the
project's error memory stays accurate.

Claude Code 钩子

规则仍然依赖 Agent 自行判断某个失败是否值得调用工具，而 Agent 会跳过那些看起来很明显的情况。一位 Agent 亲自描述了它在没有询问的情况下修复的错误：“从消息来看，修复方法很明显；相比之下，网络往返还不如直接修复来得快。” 这些错误会反复出现。

debugai-mcp hook 会替 Agent 做出这个判断。将它配置为 Claude Code 的 PostToolUseFailure 钩子后，每次 Bash 或 PowerShell 命令以非零状态退出，它都会在本项目的记忆中查找命令输出，并在 Agent 作出反应之前，将答案放在失败信息旁边。（2.6）

只有记忆中存在可用信息时，它才会提供结果：已存储的修复方案（已确认、未经验证或反模式），或者本项目报告为失败的建议。未命中、超时、没有网络、没有密钥、命令被中断或命令没有输出时，均不会产生任何输出；所有路径的退出码都是 0，因此它绝不会阻止工具调用。它使用已存储的 login 密钥，绝不会启动登录流程，因为钩子无法响应登录提示。

将以下内容添加到 ~/.claude/settings.json（适用于所有项目），或某个仓库中的 .claude/settings.json：

{
  "hooks": {
    "PostToolUseFailure": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          { "type": "command", "command": "npx -y @debugai/mcp@latest hook", "timeout": 20 }
        ]
      }
    ]
  }
}

然后，在 Claude Code 中运行 /hooks，即可看到钩子已加载。

• 每次命令失败的开销。 npx 每次都会解析 @latest。在一台 Linux 机器上测得，缓存热启动耗时 1.5 到 1.9 秒，冷启动耗时 6.7 秒，这还不包括实际查找所需的时间。若要将耗时缩短到大约三分之一秒，可通过 npm i -g @debugai/mcp@latest 一次性安装，然后使用 "command": "debugai-mcp hook"。全局安装不会自动更新：有新版本发布时，请重新运行该命令。
• 超时。 Claude Code 的命令钩子默认超时为 600 秒。钩子会自行限制耗时（读取输入最多 5 秒，查找最多 8 秒），而 20 可确保网络卡住时，Agent 被阻塞的时间不会超过该值。
• 哪些信息会离开你的设备。 失败命令的输出（最多 3,000 个字符；超出时保留开头和结尾），以及项目 ID（由仓库路径计算出的哈希值）。输出会按原样发送：此软件包不会对其进行脱敏。API 收到输出后、查找开始前会对凭据进行脱敏，并且不会存储任何内容。命令行本身不会发送。
• 项目的判定方式。 钩子会查找命令运行所在的 Git 仓库，判定方式与 debug_error 解析 projectRoot 的方式相同，因此钩子和针对同一失败的调试会读取同一份记忆。在仓库之外，文件夹本身会作为项目，且其输出会被发送。只有你的主目录、主目录的上级文件夹以及文件系统根目录会被拒绝；在 WSL 中，Windows 用户配置文件目录（例如 /mnt/c/Users/<name>）也会被拒绝。在这些位置，钩子会保持静默。

VS Code

你不需要安装此软件包。DebugAI 扩展会自动注册 MCP 服务（VS Code 1.101+），并在此基础上提供一键应用修复、主动扫描和代码库索引功能。它也上架于 Open VSX，适用于 Cursor、Windsurf 和 VSCodium。

两个服务使用相同的协议接口，并通过一个测试保持同步；该测试会将两份副本都作为文本读取，因为过去曾发生过仅靠一条“保持同步”的注释无法奏效的情况。从扩展 2.8.1 开始，内置服务也支持本地源代码解析，而此软件包从 2.2.0 起就已支持此功能。在此之前，如果 Agent 使用内置服务，将回溯信息粘贴到一个尚未建立索引的工作区中，仍会得到“缺少足够上下文，无法提供具体修复方案”，置信度为 20%；这正是此功能旨在消除的回答。

手动配置

setup 会处理这种情况，而 install --client=<id> 则适用于客户端安装在特殊位置的情况。如果你仍然更愿意自行编辑文件，所有客户端的条目都相同：

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp@latest"]
    }
  }
}

请保留 @latest。如果不指定版本，npx 会运行它找到的第一个副本；旧的全局安装会优先于最新版本：有个 Agent 在整个会话中运行的是 7 月发布的 2.1.1 版本，该版本不会发送项目，因此每次调用都无法使用项目记忆。debugai-mcp doctor 会在条目未指定版本时发出警告。

配置文件位置：

对于 Claude Code，关键在于 --scope user。 claude mcp add 默认使用 --scope local，会将服务写入 projects."/your/dir".mcpServers。这样它只会在该目录中生效， 其他地方都不可用，看起来就像 DebugAI 必须针对每个仓库单独配置一样。 debugai-mcp install 始终写入用户级配置。如果你已经运行了 本地范围的版本，debugai-mcp doctor 现在会告诉你当前使用的是哪一种。

客户端	文件
Claude Code	~/.claude.json，顶层的 mcpServers（或 claude mcp add --scope user debugai -- npx -y @debugai/mcp@latest）
Claude Desktop	macOS ~/Library/Application Support/Claude/claude_desktop_config.json，Windows %APPDATA%\Claude\claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Zed	macOS 和 Linux ~/.config/zed/settings.json（设置了 $XDG_CONFIG_HOME 时使用该路径），Windows %APPDATA%\Zed\settings.json。它使用不同的键，见下文
Gemini CLI	~/.gemini/settings.json
Cline	VS Code 全局存储目录，saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Zed 使用不同的键和嵌套命令：

{
  "context_servers": {
    "debugai": {
      "source": "custom",
      "command": { "path": "npx", "args": ["-y", "@debugai/mcp@latest"] }
    }
  }
}

然后运行一次 npx -y @debugai/mcp login 来保存你的密钥。如果你更愿意为每个客户端单独设置密钥，在该客户端的 env 块中设置 DEBUGAI_API_KEY 仍然有效，并且其优先级仍高于已保存的密钥。

环境变量

变量	默认值	描述
DEBUGAI_API_KEY	（无）	你的 API 密钥。覆盖配置文件中的 api_key。
DEBUGAI_API_BASE	DebugAI 生产环境	用于可自托管或暂存环境的覆盖值。未设置时回退到配置文件中的 api_base。
DEBUGAI_TIMEOUT_MS	150000	仅适用于 debug_error 的截止时间。深度分析可能需要 30-90 秒。lookup_error 等待 8 秒，report_outcome 等待 15 秒，钩子会忽略此变量。
DEBUGAI_CONFIG_PATH	~/.debugai/config.json	替代配置文件位置。很少需要设置。

限制与诚实说明

• 免费版：每天可调试 10 次。Pro（$12/月）：每月包含 1,000 次调试，之后按合理使用；1,000 次是软上限，因此达到上限时会通知你，但不会停止。lookup_error 和钩子均不计入这两种额度。
• 达到每日上限时，工具会告知你并停止，不会悄悄重试。
• 简单错误会交由快速模型处理。付费版中，复杂的跨文件错误会交由更强的模型处理。每个响应中的 Model: 标记会告知你使用的是哪个模型。
• 分析在 DebugAI 的服务器上运行。错误文本、你传入的任何代码片段、（自 2.2 起）堆栈跟踪中提及的项目源文件，以及（自 2.5 起）下文所述的项目事实都会发送到服务器，由 Claude（Anthropic）进行分析；如果 Claude 不可用，则由 OpenAI 的 GPT-4o-mini 进行分析。Voyage AI 也会对错误文本进行嵌入，以搜索项目索引。响应会列出读取过的所有文件。范围和限制详见 debug_error。隐私政策：debugai.io/privacy。
• 错误会按项目记录，因此再次遇到同一错误时，会从已确认有效的修复方案开始。项目身份是仓库根目录路径的哈希值。项目 ID 不包含路径，但绝对 filePath 会按原样发送，错误文本中的任何路径也会如此。
• 每次带有项目根目录的 debug_error 调用都会读取项目声明的内容并发送：package.json、requirements.txt、pyproject.toml 以及所有 .csproj、.fsproj 或 .vbproj 文件（从项目根目录向下遍历，在限定深度和数量范围内查找）。发送的内容包括清单中写明的依赖名称和版本、找到的清单类型（例如 package.json 或 *.csproj，但不包含它们的位置）、项目中的 Python 模块名称、任何虚拟环境文件夹的名称，以及是否存在 node_modules 文件夹和 .env 文件。不会打开 .env 的内容。即使你传入 codeSnippet，也会执行此操作。这样引擎就能区分已声明和未声明的包。
• 唯一不会发送的信息是选用了哪个 Python 解释器。VS Code 扩展可以从编辑器读取该信息，因此能区分“未安装”和“安装在其他解释器中”。此服务没有同等能力，因此遇到缺少模块的错误时，只会给出通用回答和需要运行的检查，不会给出确定结论。你可以使用 shell，而它不能，因此由你来运行检查才是诚实的分工。

故障排查

先运行 npx -y @debugai/mcp doctor。它会检查 Node 版本、是否存储了密钥以及密钥来源、密钥是否仍可通过 API 验证、配置文件权限，以及检测到的客户端中哪些缺少 DebugAI 条目。大多数问题的答案都在输出中。

• “authentication failed”：密钥已轮换或撤销。运行 npx -y @debugai/mcp login --force。
• 客户端中未显示工具：客户端尚未重启，或者读取的是另一个配置文件。install --list 会显示写入了哪个文件。
• 运行 npx @debugai/mcp 后没有任何动静：这是正常的。它是一个 stdio 服务，会等待 MCP 客户端先发起通信。使用 --help 验证安装情况。
• 超时：深度分析最多可能需要 90s。如果客户端有自己的工具超时设置，请将其调高。
• 钩子始终没有任何提示：缓存未命中时就是这种情况，而大多数失败都属于缓存未命中。在 Claude Code 中使用 /hooks 查看是否已加载，使用 claude --debug 记录每次运行。它还需要已存储的密钥（npx -y @debugai/mcp login），因为它不会主动索取密钥。

更新日志

更新说明：分析在 DebugAI 的服务器上运行，因此错误解析、检索和根因分析质量的改进无需升级此软件包即可生效。只有会影响你本机的内容变更才会发布客户端更新。 近期的服务器端改进。每项改进都会在包含它的引擎版本部署后，无需升级即可提供给 Agent：

• Agent 报告的故障不再因为“不算错误”而遭到拒绝，即使其措辞不在引擎的错误短语列表中也是如此。No module named、Ubuntu 的 Command 'x' not found、浏览器的 net::ERR_*，以及只输出 Line 44: Undefined symbol、不含“error”一词的编译器错误，过去都会被拒绝。提示词、单独的路径或存根仍会被拒绝。
• 如果从未看到错误所指的那一行，答案会明确说明。 以前，对于一段 19 行代码中报告的 Line 528 错误，系统会根据第 1-19 行进行解释。现在会以低置信度作答，并说明提供了哪些行、错误报告的是哪一行；同时不会缓存答案，因此补充系统要求的代码行后，会重新分析。
• 不再假定缺失的命令是项目中的脚本。 如果精简后的 PATH 找不到 curl、winget 和 powershell，系统会通过完整路径调用它们（它们随 Windows 提供），而不是安装它们；交给命令提示符的 PowerShell 命令（$ws、Get-ChildItem）会被判定为 shell 用错，而不是缺少工具；运行未知名称之前会先查找它。
• Playwright 超时不再被归咎于你的应用。 “Waiting for visible, enabled and stable” 表示驱动程序无法执行操作。答案会先给出能区分“页面上不存在”和“页面上存在但被遮挡或仍在移动”的检查方法，并且只将 force: true 作为明确标注的测试绕过方案提供。
• npm 的 ENOENT ... package.json 会通过 npm --prefix 处理，而不是 cd 到错误中已经指出的文件夹。若路径指向不存在的位置，系统会先逐级向上查找实际存在的文件夹，再重新安装任何内容。浏览器在 localhost 上遇到 ERR_CONNECTION_REFUSED 时，会采用与 Node 相同的推理方式，并建议在能查看服务器首几行输出的位置运行服务器。
• ModuleNotFoundError 不再以安装命令开头。我们检查了已回答的所有此类问题，发现 8 个回答中有 5 个遭到收到它们的 Agent 拒绝，涉及 3 种需要分别采用不同修复方法的原因：软件包安装在另一个解释器下、名称对应本地文件，或导入语句格式错误。现在，排名第一的检查会先区分这些情况。
• Python 的 SyntaxError 不再被诊断为 JavaScript 错误；系统会根据错误文本判断所用的框架，而不是根据仓库中包含的内容来判断。
• 操作系统错误（Access is denied.、No space left on device）现在会被识别为错误。我们测试了 30 条，其中 28 条此前曾遭到拒绝。
• 你发送的文本中的凭据会在存储或传给模型之前被替换。
• pytest、unittest、jest、vitest 和 mocha 的输出现在会提取真实文件路径，因此测试失败时能够获得跨文件上下文，而不再是一无所知。

2.7.0 - 根据第二位 Agent 的实地报告构建；这次报告来自一个从零开始的项目，其使用的库比任何模型训练数据中的库都新（报告日期：2026-09-20）。

• 你的主目录不是项目。 如果服务器在 ~ 或文件系统根目录中启动，且该目录不在任何仓库中，就会将其视为项目根目录：读取并发送其中提及文件路径的堆栈跟踪，并遍历其中的清单文件。现在，服务器不会将该目录视为项目根目录，不会读取任何本地内容、收集任何项目信息，并会在回复中说明这一点。传入 projectRoot 来指定项目。同样的拒绝规则也适用于主目录上方的文件夹、WSL 下的 Windows 配置文件（/mnt/c/Users/<name>），以及从 Windows 访问的网络共享或 WSL 发行版（\\server\share、\\wsl.localhost\Ubuntu）。即使仓库位于你的主目录中，点文件仓库也不再影响 projectRoot：你指定的文件夹会被采用。

• debug_error 中的 snippetStartLine。 你传入的代码片段没有标头，因此此前总是从第 1 行开始计数，导致无法将文件中间的代码片段窗口与错误所指的行匹配。请说明片段的起始行。服务器自行读取的文件会在其标头中注明这一点。

• language 接受任意字符串。 以前，列表之外的名称会导致调用失败，并让 Agent 重试并传入 auto；现在，这些名称会被视为 auto。最常遇到的是 markdown。网关还会将 lua、dart、elixir、r 和 perl 折叠为 unknown，导致它们未被计入语言统计；现在会保留这些名称。

• 编辑会注明代码所在的文件。 此服务会解析堆栈跟踪中提到的所有文件并一并发送；过去，每项修复的 edits[].file 都会填入其中第一个文件，不管修复针对哪个文件，同时还会附上 diff 标头、检查命令和行号。盲目应用这样的编辑会把一个文件的代码写进另一个文件；更常见的是，编辑无法匹配，害你不得不重新读取文件。现在，返回的行号采用对应文件自身的行号；如果修复涉及两个文件，则不提供编辑，而不是给出一个看似可靠、实际错误的路径。

• 工具会描述你实际所处的情境。 过去，每个触发条件都假设是用户在做某件事，例如“用户粘贴错误时使用”。在 Agent 会话中，没人会粘贴任何内容——是 Agent 运行了构建。现在，debug_error 会指示在发生故障的那一刻就调用它，包括故障由 Agent 自己导致时，并列出具体情境：类型检查以非零状态退出、代码检查器报告错误、测试套件失败。

• report_outcome 会区分错误补丁和错误诊断。 如果根本原因判断正确，但修复未能应用，结果应为 unused，而不是 failed。将其标记为失败，会把补丁的问题归咎于诊断；两者需要截然不同的修复方式。

• 客户端过时的提示只会在开头出现一次，不会重复。 过去，每次回答都会将提示追加到 root_cause 中，而 Agent 会把这个字段引用给用户。一名 Agent 将其误认为整个会话都适用的套话，同时运行的版本却落后了五个发布版本。现在，提示被放在独立字段中，显示在诊断上方，每个进程只显示一次。

• 随附的 VS Code 服务会获得与此服务相同的说明。 两者的说明曾经出现偏差，随附版本还丢失了关于读取堆栈跟踪所提及源文件的段落。

• 现在会为更多工具链读取源文件。 MSBuild 和 tsc 的 file(line,col)、javac 和 Maven 的 [line,col]、.NET 的 in path:line N、PowerShell 的 At path:N、Gradle 构建文件、file:// 路径和 JVM 堆栈帧现在都能指明文件。新增文件类型：.c .cc .cpp .h .hpp .pyi .kts .scala .dart .groovy .ps1 .psm1 .psd1 .gradle。

• 从磁盘读取的内容会控制在 API 的限制内。 过去，三份含有长行的文件会超出 50,000 个字符的限制，导致请求被拒，而 Agent 收到的却是空结果。现在，每个文件都会按剩余字符数截取，并在故障行附近保留完整行。现在可以将最大 2 MB 的文件作为窗口读取；旧有的 256 KB 限制则会在行中间截断。

• 空的 codeSnippet 或 filePath 会被视为未提供。 Agent 如果将可选参数填为 ""，过去会收到“文件已读取”的提示，实际却没有收到任何代码。

• 未读取的清单不会再被当作未声明任何内容。 UTF-16 编码的 requirements.txt、超过 512 KB 的文件、带字节顺序标记或无法解析的 package.json，以及提前停止的目录遍历，过去都会发送一份自称完整的列表，导致引擎回答“未声明”。现在，这些情况都会标记列表可能不完整。读取 pyproject.toml 时会逐个表格读取，因此 testpaths 和作者姓名不再被当作依赖项发送。

• 错误消息会说明该怎么做。 对于每月限额，或 API 不认识的 debugLogId，系统会说明重试没有意义。遇到短暂的速率限制时，会告知需要等待多久。发生服务中断时，会传达引擎自身的提示。代理或登录页面代替 API 返回响应时，会明确指出这一点，而不是将其称为无效 JSON。现在，请求的截止时间涵盖整个响应过程，而不仅仅是等待响应头的时间。

• 登录更加稳健。 即使 API 短暂中断也能继续使用；配置文件无法写入时，会保留收到的密钥；只会打开 http(s) 地址；在 Windows 上不再通过 cmd 执行；并且会显示服务端报告的免费额度，而不是固定数字。

• install 会保留配置文件原有的状态。 它会保留文件权限，通过符号链接写入而不是替换链接本身，也会读取以字节顺序标记开头的文件。uninstall 还会移除 VS Code 条目和 Claude Code 的按目录配置条目。

• 在 Windows 上，无论路径写法如何，主文件夹都不能作为项目。 2.6.0 - 根据一位 Agent 在一周真实使用后的实地报告逐项改进（2026-09-16）。

• lookup_error，一款新工具：无需调用模型，也不会产生费用，即可查询本项目中记录的错误。报告中的 Agent 有 5 次遇到错误时跳过了 DebugAI，因为全面分析感觉比直接修复更慢，而每次跳过都让错误记忆错过了一条记录。

• debugai-mcp hook 会在 Claude Code 中每次 Shell 命令执行失败时运行查询，因此是否调用它不再由 Agent 自行判断。请参阅 Claude Code hook。

• debug_error 中新增 reproCommand 和 expected。报告中的 6 个回答都建议用 python -m py_compile 或 node --check 来确认修复，涉及无法扫描的二维码和陷入循环的模型。Agent 每次都有真实的检查可用。现在，修复 #1 会以该检查为目标，而这项检查也会成为每个修复的验证方式。DebugAI 仍然不会运行它。

• report_outcome 中新增 worked_modified 和 finalFix。如果某个修复只有在 Agent 修改后才有效，以前只能报告为 worked, rank 1，因此记忆保存的是建议，而非实际奏效的内容。现在，如果奏效的是排名第 2 或第 3 的修复，也会将其记住。

• 新增 projectRoot，绝对路径的 filePath 也会标明所属仓库。Agent 从一个文件夹启动，却在另一个文件夹中工作时，所有错误都会被记到错误的项目下，而且所有本地文件读取都会遭到拒绝。现在，每个回答的页脚都会注明项目，并说明记忆何时关闭以及原因。

• 每个回答都会标明此 MCP 服务的版本和引擎构建版本。报告中的 Agent 曾在不知情的情况下使用 7 月版 2.1.1，因为它收到的内容里没有版本信息。安装程序会写入 @debugai/mcp@latest，doctor 会标出配置中没有版本号的条目，以及明文保存在客户端配置中的密钥；旧版服务每天会收到一次有新版本可用的提示。

• 来自大文件的代码窗口现在会使用文件中的实际行号编号，因此关于第 539 行的回答不会再把它标成第 4 行。

• 每个修复的改动只会在正文中展示一次。结构化结果中仍会保留完整差异。

• 超过 3,000 个字符的错误现在会截断以适应长度限制，同时保留开头和结尾；不再返回 Agent 必须设法处理的 400 错误。

2.5.1 - language 支持的语言从 6 种增至 24 种。此前支持的只有 javascript、 typescript、python、go、rust 和 auto，因此 Agent 指定其他语言时会被拒绝调用， 不得不改用 auto 重试。9 月日志中最繁忙的 10 个账户里，有 4 个遇到了这个问题—— java、csharp、css 和 lua，合计调试 52 次。较少活跃的账户情况更糟：重试会成功，因此 这些记录中的 language = unknown 从未改变。这会让 Java 堆栈跟踪看起来像是检测失败， 也会导致各语言的计数都低报，恰好漏掉那些缺失的语言。auto 仍是默认选项，而且几乎 总是正确的选择。

2.5.0 - 服务现在会读取项目声明的内容，并与错误一起发送：依赖项名称以及项目清单中 锁定的版本，包括 .NET 的 .csproj 和 monorepo 中的嵌套清单。引擎过去无法查看你的 磁盘，因此只能猜测第三方 API；现在，它能准确识别锁定的版本，也会在没有锁定版本时 明确表示不知道。不会打开 .env；只会报告它是否存在。

2.4.2：打包的服务现在会输出它所宣传的记忆功能。本软件包中的服务与 VS Code 扩展 打包的副本是同一个服务，但此前只有本软件包会显示复现次数和已确认的修复；两者都承诺 会在连接时向 Agent 提供这些信息。现在，这部分内容已整理为一个模块，两个副本都会调用， 无需再手动保持同步。

2.4.1：修复了两处工具描述。此前，破折号清理操作在句子中途截断了这两段描述。这 一点比看起来更重要：工具描述是 Agent 在决定是否调用此服务之前唯一能看到的内容。 2.4.0：report_outcome 新增 unused。如果 Agent 用自己的方式解决了问题，就只能报告 failed，这会将某个修复标记为已尝试且未奏效，即使我们提供的修复从未运行过。现在，两个工具界面（npm 服务和 VS Code 扩展内置的服务）都使用相同的字段。

2.3.0：Agent 现在可以使用与编辑器面板相同的四种记忆状态。 debug_error 以前只有两种分支，而已尝试过却仍然失败的修复，与从未尝试过的修复显示完全相同。对 Agent 来说，这两种情况的描述相同，因此很自然就会再次提出那个已经无效的修复。现在，四种状态与面板一致：已确认并验证、已确认、未经验证和反模式。

2.2.0：修复了两项曾对外宣传却未实际提供的功能。

• 本地源码解析。 服务现在会读取堆栈跟踪中提到的文件，并将它们随请求一并发送。在此之前，如果 Agent 粘贴了回溯信息，就会收到“缺少足够上下文，无法提供具体修复建议”，置信度为 20%，因为唯一其他的代码来源是索引，而 VS Code 扩展之外的任何工具都不会填充该索引。解析范围限定在你的仓库根目录、源码扩展名和 3 个文件内。响应会列出读取的文件。
• 项目范围的错误记忆。 此软件包从未发送过 project_id，而引擎会根据该 ID 判断错误复现次数和已确认的修复，因此每个 Agent 请求都无法获取历史记录，也不会记录任何信息，尽管服务说明告诉 Agent 它具备这些功能。现在，项目 ID 根据你的 git 仓库根目录生成；同一份检出目录生成的 ID 与 VS Code 扩展一致，因此两个界面可以共享同一份记忆。适用时，debug_error 会显示“此前出现过 3 次，修复已确认”。

2.1.1：仅更新元数据。新增 mcpName，用于验证其官方 MCP 注册表所有权；修复 npm 软件包页面上的仓库链接。

2.1.0：一键设置。通过设备链接在浏览器中登录（无需粘贴密钥）、自动写入客户端配置并创建备份、使用 doctor 诊断故障配置，以及在 Agent 尚未登录时调用工具，可在对话中完成登录。

2.0.0：新增 report_outcome 工具、每项修复提供可直接应用的 edits，以及三种状态的验证标签。

开发

npm install
npm test        # builds, then runs unit + spawned-process e2e tests

源码

github.com/1shizaan/debugai-mcp 是此软件包的源码仓库，内容同步自该软件的开发目录。仓库包含这些文件的完整提交历史，因此 git log 和 git blame 都可以正常使用。

客户端采用 MIT 许可证，且功能完整：stdio 服务、设备链接登录、配置写入器和测试都在此仓库中。分析本身在 DebugAI 的服务端运行，不属于此软件包。

欢迎在该仓库提交问题和拉取请求。

MIT © DebugAI