Debugg AI
官方使您的代码生成代理能够通过Debugg AI测试平台,在远程浏览器中针对新的代码变更创建并运行零配置的端到端测试。
你可以用 Debugg AI MCP 做什么?
- 运行 AI 浏览器测试 — 通过
check_app_in_browser使用自然语言指令测试任何 URL 或 localhost 应用,返回通过/失败结果及截图。 - 快速探测多个页面 — 使用
probe_page批量检查 1-20 个 URL 的控制台错误、网络问题和渲染状态,无需 LLM 成本。 - 管理测试环境 — 使用
environment工具创建、更新或列出包含凭据和授权 SSO 主机的环境。 - 触发站点爬取 — 调用
trigger_crawl通过服务端浏览器代理爬取,填充项目的知识图谱。 - 运行和跟踪测试套件 — 创建套件、触发异步运行,并通过
test_suite操作获取每个测试的结果。 - 检查执行工件 — 通过
executions检索完整的运行详情、HAR 网络跟踪和控制台日志,以调试运行时问题。
文档
Debugg AI — MCP 服务器
通过模型上下文协议实现AI驱动的浏览器测试。将其指向任意URL(或localhost)并描述要测试的内容——AI代理会浏览您的应用并返回通过/失败结果及截图。
设置
需要 Node.js 20.20.0 或更高版本(来自 posthog-node@^5.26.0 的传递依赖)。
测试 http://localhost:... URL 需要 caddy 二进制文件 —— check_app_in_browser、
probe_page 和 trigger_crawl 通过本地 Caddy 反向代理隧道传输 localhost 目标。
这会自动安装:@radically-straightforward/caddy npm 依赖会在 npm install/npx 期间
为您的平台下载固定版本的 Caddy 发行版——正常情况下无需自行安装任何内容。它现在是此包下载的唯一二进制文件;隧道客户端本身是纯 TypeScript——它取代了获取 ngrok 代理的 ngrok 包。
如果该下载从未运行(npm install --ignore-scripts,离线/隔离环境安装),请将 CADDY_BIN 指向
您自己的安装(brew install caddy / apt install caddy / 参见
caddyserver.com/docs/install)——缺失时会在首次 localhost-URL 调用时
以清晰的错误提示,而不是静默挂起。公共 URL 调用、所有非浏览器工具以及
test_suite {action:"run"}(使用其专用隧道并完全绕过 Caddy)无论哪种情况都不需要它。
在 debugg.ai 获取 API 密钥,然后添加到您的 MCP 客户端配置中:
{
"mcpServers": {
"debugg-ai": {
"command": "npx",
"args": ["-y", "@debugg-ai/debugg-ai-mcp"],
"env": {
"DEBUGGAI_API_KEY": "your_api_key_here"
}
}
}
}
或使用 Docker:
docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp
Dockerfile 的 npm install 步骤原则上会以本地安装相同的方式自动获取 caddy——但截至撰写本文时,Dockerfile 不 COPY 构建现在需要的几个目录(handlers、tools、types、config),并且仍引用一个不再存在的 tunnels/ 目录,因此全新构建很可能在此之前就失败。这是一个预先存在的缺口,与 Caddy 无关。当前发布的 quinnosha/debugg-ai-mcp 镜像无论如何都早于 Caddy 依赖——在该镜像中,对 check_app_in_browser/probe_page/trigger_crawl 的 localhost-URL 调用将因 CaddyBinaryNotFoundError 而失败,直到重新构建(修复 Dockerfile)并重新发布,或者 CADDY_BIN 指向单独内置的版本。公共 URL 调用、非浏览器工具和 test_suite {action:"run"} 无论哪种情况都不受影响。
工具
服务器暴露 8 个工具:三个 浏览器 工具,外加每个受管实体一个基于操作的工具。主打工具是 check_app_in_browser(完整 AI 代理)和 probe_page(轻量级无 LLM 页面探测)。其余工具——project、environment、test_suite、test_case、executions——各自接受一个 action 判别器(例如 {"action":"list"})来选择操作。破坏性的 delete 操作需要确认(在支持的地方使用提示提示,否则使用 confirm: true)。
浏览器
check_app_in_browser
针对您的应用运行 AI 浏览器代理。代理会导航、交互并返回带截图的报告。Localhost URL 会自动通过 debugg 隧道服务器进行隧道传输。
| 参数 | 类型 | 描述 |
|---|---|---|
description | 字符串 必填 | 要测试的内容(自然语言) |
url | 字符串 必填 | 目标 URL——http://localhost:3000 会自动隧道传输 |
environmentId | 字符串 | 特定环境的 UUID |
credentialId | 字符串 | 特定凭据的 UUID |
credentialRole | 字符串 | 按角色选择凭据(例如 admin、guest) |
username | 字符串 | 登录用户名(临时——不持久化) |
password | 字符串 | 登录密码(临时——不持久化) |
loginCredentials | 数组 | 代理在任务期间遇到的登录账户——[{username, password, label?}] |
useEnvironmentCredentials | 布尔值 | 默认 true。false 禁止自动填充环境存储的凭据;未指定账户时意味着完全不登录 |
freshSession | 布尔值 | 默认 false。true 强制真实登录,而不是重用该账户持有的热会话 |
auth | 对象 | 认证前置条件——{precondition, entryUrl, deepUrl, environmentId, username, password} |
repoName | 字符串 | 覆盖自动检测的 git 仓库名称(例如 my-org/my-repo) |
每次调用只做一项聚焦检查。代理有约 25 步的内部预算;将更广泛的测试套件拆分为多次调用。
凭据:作为参数传递,而非叙述文本
仅在 description 中命名账户不会让代理使用它——它会回退到环境存储的凭据,而应用拒绝错误账户的结果看起来就像应用故障。您作为参数传递的任何内容在运行中的每次登录都会覆盖环境默认值,而不仅仅是第一次:
username/password(或credentialId/credentialRole)——运行的身份。auth.username/auth.password——当您同时使用auth.precondition: "login"时,固定前置条件登录。loginCredentials——代理在任务中途遇到的登录表单的账户。这适用于诸如设置密码 → 被弹回登录页 → 以刚创建的账户登录之类的流程,如果拆分为多次调用会丢失浏览器状态。
当静默回退到默认测试用户会使检查失效时,设置 useEnvironmentCredentials: false。
跨域 SSO? 运行只在应用自身主机及其子域上输入凭据;其他域上的登录页面会被拒绝为 offscope_host。将身份提供方的主机添加到环境的 authorizedCredentialHosts(参见 environment)。
检查完全不需要登录的页面? 传递 useEnvironmentCredentials: false 且不命名任何账户。该组合的含义正是字面意思——不登录——运行将完全跳过身份验证,而不是寻找登录表单。适用于公共页面、营销网站、文档以及任何预认证内容。它也更快:在默认(auto)下,代理会在评估任何内容之前跟随页面上的"登录"链接并尝试环境存储的账户。
会话重用:为什么检查会报告"无登录表单"
运行不会每次都登录。验证登录后,后端会捕获该账户的会话,并在下次针对相同身份运行时恢复它,从而完全跳过登录——这就是检查可以合法地返回 submitted: false 且无登录表单的原因:它已经登录了。恢复的运行会在 logins 中报告自身为 reason: "restored_session",因此您可以将其与真正未找到表单的运行区分开来。
会话按账户键控,因此命名不同的账户绝不会重用他人的会话。两种绕过重用的方式:
- 单次调用上的
freshSession: true——这次真实登录,然后重新捕获。当登录流程就是您要检查的内容、怀疑存储的会话已过期、或应用在角色之间唯一的路径是注销时使用。 environment工具,action: "clearSessions"——使存储的会话失效,以便后续运行登录。使用username/credentialId缩小范围;无范围清除需要确认,因为环境上的每个账户随后都会重新认证。
使用 action: "sessions" 查看环境当前持有的内容以及每个是否会被重用。
结果报告实际使用的身份,因此错误的身份是可见的,而不是伪装成应用故障:
"logins": [
{ "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true },
{ "username": "qatest123@example.com", "source": "env_default", "submitted": false, "authenticated": false,
"reason": "offscope_host", "detail": "refused to enter credentials on auth.idp.example: not part of this run's scope …" }
],
"credentialWarning": {
"requested": "qa+invitefix@example.com",
"used": ["qatest123@example.com"]
}
source 是 task | explicit | credential_id(您命名的账户)或 env | env_default(环境存储的账户)。submitted 仅在凭据实际输入并提交时为 true;reason 说明发生了什么(例如 offscope_host、restored_session),detail 在存在时是对其的人类可读解释——对于 offscope_host 拒绝,它会指明主机及如何授权。credentialWarning 仅在您命名了账户且实际提交了不同账户的环境默认值时出现——绝不会出现在被拒绝或跳过的登录中。loginError 在命名账户无法解析且运行拒绝替换为其他账户时出现。
每次成功运行都会返回一个 browserSession 块以及截图——捕获的 HAR(完整网络跟踪)和控制台日志(每条 JS 控制台消息)的预签名 S3 URL。使用它们检测重取循环、水合错误以及其他通过类型检查和单元测试的运行时问题:
"browserSession": {
"harUrl": "https://...session_18139.har?X-Amz-...",
"consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
"recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
"harStatus": "downloaded",
"consoleLogStatus": "downloaded",
"harRedactionStatus": "redacted",
"consoleLogRedactionStatus": "redacted"
}
URL 是短时有效的预签名 S3——通过 executions {action:"get", uuid} 重新获取父执行以续期。harStatus / consoleLogStatus 区分 'downloaded'(URL 可获取)、'not_available'(页面未产生任何内容)、'failed'(捕获中断)。在新运行时,URL 通常为 null,因为捕获在代理完成后异步上传——轮询 executions {action:"get", uuid: executionId} 直到状态达到 'downloaded'。授权 / Cookie / token/secret/api_key 头会在工件持久化之前在服务端被清除。
trigger_crawl
触发服务端浏览器代理爬取以填充项目的知识图谱。Localhost URL 自动隧道传输。成功摄取时返回 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} 及 knowledgeGraph.skipped === false。crawlSummary 和 knowledgeGraph 仅携带后端爬取/导入节点报告的键——缺失的计数就是缺失,绝不会填充为 0。browserSession 块(HAR + 控制台日志 URL,形状与上述相同)在完成爬取时也存在。
probe_page
轻量级无 LLM 批量页面探测。 传递 1-20 个 URL;每个 URL 导航、在内容上稳定(DOM 静默,有界——绝不会在网络静默上,因为活跃应用永远不会达到网络空闲),并返回渲染状态——截图 + 页面元数据 + 结构化控制台错误 + 网络摘要。无代理循环、无 LLM 成本、无场景断言。用于"我是否刚破坏了 /settings?"、重构后的多路由冒烟测试、CI 每次 PR 扫描,以及 check_app_in_browser 的 60-150 秒代理循环过于冗余时的快速可用性检查。
| 参数 | 类型 | 描述 |
|---|---|---|
targets | 数组 必填 | 1-20 个条目:[{url, waitForSelector?, waitForLoadState?, timeoutMs?}] |
targets[].url | 字符串 必填 | 公共 URL 或 localhost(自动隧道传输) |
targets[].waitForLoadState | 枚举 | 'domcontentloaded'(默认,+ 有界内容稳定)/ 'load'(还阻塞第三方嵌入)/ 'networkidle'(接受但从不发出——活跃站点的网络不会空闲) |
targets[].waitForSelector | 字符串 | 可选 CSS 选择器,导航后等待 |
targets[].timeoutMs | 数字 | 每个 URL 超时,1000-30000(默认 10000) |
includeHtml | 布尔值 | 在每个结果中返回原始 HTML(默认 false) |
captureScreenshots | 布尔值 | 每个目标返回一个 PNG(默认 true) |
批次中的所有目标共享一个会话隧道,但只有同端口(或全公共)批次共享单个后端执行——一次调用中同一端口上的 5 个 URL 比 5 个并行的单 URL 调用快得多。混合多个本地端口的批次会分解为每个端口组一个顺序后端执行(仍然是一次调用,仍然是一个按原始顺序合并的 results[],但 N 次后端往返而不是一次——更慢,但不被拒绝)。每个 URL 的 error 字段保持批次弹性:单个失败目标不会导致其他目标失败。
networkSummary 聚合键为 origin + pathname — 重复获取循环(?n=0..4 反复命中同一端点)会折叠为单条记录并附带计数,因此带有 count: 47 的 /api/poll 就是用户最初要求的可操作的“无限重复获取循环”信号。
性能预算:1 个 URL 小于 10 秒,20 个小于 25 秒。Localhost 死端口在 2 秒内返回 LocalServerUnreachable,且不消耗工作流执行。
project
| 操作 | 参数 | 结果 |
|---|---|---|
get | {uuid} | 精选项目详情 |
list | {q?, page?, pageSize?} | 分页摘要 |
create | {name, platform, (teamUuid|teamName), (repoUuid|repoName)} | 已创建项目 |
团队和仓库通过 uuid 或 名称 解析(不区分大小写的精确匹配;无匹配时返回 NotFound,多个匹配时返回 AmbiguousMatch)。没有 update/delete — 请从 DebuggAI Web 应用重命名或删除项目。
environment
| 操作 | 参数 | 结果 |
|---|---|---|
get | {uuid, projectUuid?} | 环境及内联凭据(密码永不返回) |
list | {projectUuid?, q?, page?, pageSize?} | 分页环境,每个都带凭据数组 |
create | {name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?} | 已创建环境(可选地预置凭据) |
update | {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?} | 已修补环境;凭据操作按 删除 → 更新 → 添加 顺序执行 |
delete | {uuid, projectUuid?, confirm?} | 删除环境(级联删除凭据)— 需要确认 |
sessions | {uuid, username?, credentialId?} | 环境持有的已捕获登录会话,按账户分组,每个都有各自的 isUsable |
clearSessions | {uuid, username?, credentialId?, confirm?} | 使其失效,以便下次运行真正登录 — 无范围清除需要确认 |
省略时,projectUuid 会从 git 仓库自动解析。单个凭据失败会在 credentialWarnings[] 中显示,而不会阻塞环境操作。
authorizedCredentialHosts 列出除应用自身主机外,运行可能进入此环境凭据的主机 — 对于跨域 SSO,请在此添加 IdP 主机(例如 ["auth.example.com"])。仅限裸主机名:无协议、路径、端口或通配符(应用主机的子域已在范围内)。在 update 上,它会替换列表;[] 会清除它。当服务器支持时,get/list 会返回它。响应会回显保存的列表;如果服务器未持久化它(旧服务器忽略该字段),结果会携带 authorizedCredentialHostsWarning: {requested, returned} 而不是静默成功。
sessions / clearSessions 管理后端复用以跳过登录的预热认证会话(参见 会话复用)。会话内容永不返回 — 会话 cookie 是持有者凭据。clearSessions 将会话标记为无效而不是删除行,因此复用会立即停止,同时捕获历史保持可读。
test_suite
| 操作 | 参数 | 结果 |
|---|---|---|
list | {projectUuid|projectName, search?, page?, pageSize?} | 分页套件,带状态和通过率 |
create | {name, description, projectUuid|projectName} | 已创建套件 |
run | {suiteUuid|(suiteName+project), targetUrl?} | 异步触发所有测试 |
results | {suiteUuid|(suiteName+project)} | 套件及每个测试的结果 |
delete | {suiteUuid|(suiteName+project), confirm?} | 软删除 — 需要确认 |
test_case
| 操作 | 参数 | 结果 |
|---|---|---|
create | {name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?} | 已创建测试用例(不自动运行) |
update | {testUuid, name?, description?, agentTaskDescription?} | 已修补测试用例 |
delete | {testUuid, confirm?} | 软删除 — 需要确认 |
executions
| 操作 | 参数 | 结果 |
|---|---|---|
get | {uuid} | 完整详情(nodeExecutions + 状态 + errorInfo)+ 截图/GIF 工件 |
list | {status?, projectUuid?, page?, pageSize?} | 分页摘要 |
后端的 404 会以带 {error: 'NotFound', message, uuid} 的 isError: true 形式呈现。凭据始终在无密码的情况下返回。
分页
每个 list 响应都是分页的。响应结构:
{
"pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
"<items>": [ ... ]
}
传递可选的 page(从 1 开始,默认 1)和 pageSize(默认 20,最大 200;超大的值会被截断)。任何响应都不会被静默截断。
get 会在其单数名称下返回一个对象 — {project}、{execution}、{project, environment} — 没有 pageInfo。
资源
除了工具之外,服务器还将只读实体作为 MCP 资源 暴露,以便客户端可以浏览并将它们作为上下文 @提及:
| URI | 内容 |
|---|---|
debugg-ai://projects | 所有项目(第一页) |
debugg-ai://environments | 自动检测项目的环境 |
debugg-ai://executions | 最近的执行(第一页) |
debugg-ai://project/{uuid} | 一个项目,完整详情 |
debugg-ai://environment/{uuid} | 一个环境(凭据内联,密码已编辑) |
debugg-ai://execution/{uuid} | 一次执行,完整节点详情 + 工件链接 |
读取操作分派到与 project / environment / executions 工具相同的处理程序,因此数据和认证是相同的。资源是附加的 — 不支持资源的客户端继续使用工具。
安全不变量
- 密码是只写的。它们永远不会出现在任何工具的任何响应体中。
- 隧道 URL(
*.tunnel.debugg.ai,以及历史运行仍引用的已退役的*.ngrok.debugg.ai)会从所有浏览器代理响应中剥离,包括代理撰写的文本。 - 后端的 404 会以带
{error: 'NotFound', ...}的isError: true形式呈现,绝不会作为抛出的异常。 - 缺失的
DEBUGGAI_API_KEY会在首次调用时以结构化工具错误的形式呈现 — 服务器仍会正常注册和列出工具。
迁移到 v6.0.0(后端判定,无 MCP 撰写的文本)
运行判定为 pass | fail | error,后端的 reason 会逐字转发。从未尝试测试的运行读取为 outcome: null、skipped: true、skipReason。
| 已移除 | 替代 |
|---|---|
success | outcome |
failureCategory | outcome + reason |
stepsTaken / stepsBudget / stepsRemaining | budget: {maxSteps, usedSteps} |
failedNode | errorInfo |
get → projects[0] / executions[0] / environments[0] + pageInfo + filter | {project} / {execution} / {project, environment} |
警告和结果上的 message / note | 仅结构化字段 |
完整列表:CHANGELOG.md 6.0.0。
迁移到 v3.0.0(基于操作的工具)
v3 将 20 个按动词划分的工具整合为 8 个基于操作的工具。旧工具 → 新 tool {action}:
| 已移除 | 替代 |
|---|---|
search_projects | project {action:"get"} / project {action:"list"} |
create_project | project {action:"create"} |
update_project、delete_project | 已移除 — 请使用 DebuggAI Web 应用 |
search_environments | environment {action:"get"} / {action:"list"} |
create_environment / update_environment / delete_environment | environment {action:"create"|"update"|"delete"} |
create_test_suite / search_test_suites / run_test_suite / get_test_suite_results / delete_test_suite | test_suite {action:"create"|"list"|"run"|"results"|"delete"} |
create_test_case / update_test_case / delete_test_case | test_case {action:"create"|"update"|"delete"} |
search_executions | executions {action:"get"|"list"} |
trigger_crawl headless 参数 | 已移除 — 始终无头 |
delete 操作现在需要确认(引导提示,或 confirm: true)。客户端在 MCP 重启时获取新的界面。
从 v1.x 迁移(v2.0.0 中的破坏性变更)
v2 将 22 个工具的界面缩减为 11 个。旧工具 → 新工具映射:
| 已移除 | 替代 |
|---|---|
list_projects、get_project | search_projects(uuid 模式 vs 过滤模式) |
list_environments、get_environment | search_environments |
list_credentials、get_credential | search_environments — 凭据内联在每个环境上 |
create_credential | create_environment({credentials: [...]}) 预置,或 update_environment({addCredentials: [...]}) |
update_credential | update_environment({updateCredentials: [{uuid, ...patch}]}) |
delete_credential | update_environment({removeCredentialIds: [uuid]}) |
list_teams、list_repos | create_project({teamName, repoName}) — 带歧义处理的名称解析 |
list_executions、get_execution | search_executions |
cancel_execution | 已移除 — 后端自动缩减 |
响应结构变更:列表响应上的裸 count 字段已移除 — 请使用 pageInfo.totalCount。
配置
| 环境变量 | 必需 | 用途 |
|---|---|---|
DEBUGGAI_API_KEY | 是 | 后端 API 密钥。别名:DEBUGGAI_API_TOKEN、DEBUGGAI_JWT_TOKEN。 |
DEBUGGAI_API_URL | 否 | 后端基础 URL。默认为 https://api.debugg.ai。 |
DEBUGGAI_TOKEN_TYPE | 否 | token(默认)或 bearer。 |
DEBUGGAI_EVAL_TEMPLATE | 否 | 覆盖 check_app_in_browser 分派到的 App Evaluation 工作流 slug。默认为 flow/e2es/app-eval。分派固定到此 slug,因此后端模板重命名不会破坏它。 |
LOG_LEVEL | 否 | error / warn / info(默认) / debug。 |
POSTHOG_API_KEY | 否 | 覆盖嵌入的遥测项目密钥(例如私有 fork)。 |
DEBUGGAI_TELEMETRY_DISABLED | 否 | 设置为 1 / true / yes / on 以完全禁用遥测。 |
DEBUGGAI_API_KEY=your_api_key
远程 / HTTP 传输(可选)
默认情况下,服务器使用 stdio(本地 npx)。它也可以作为托管的多用户远程 MCP 通过 无状态 Streamable HTTP + OAuth 运行:
DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest
它是一个 OAuth 资源服务器:每个 POST /mcp 都需要 Authorization: Bearer <token>;缺失/无效的令牌会得到带 WWW-Authenticate 的 401,指向 RFC 9728 元数据,客户端会针对通告的授权服务器运行 OAuth 流程。持有者令牌是请求范围的 — api.debugg.ai 会验证它。
| 端点 | 用途 |
|---|---|
POST /mcp | MCP Streamable HTTP(持有者令牌保护) |
GET /.well-known/oauth-protected-resource | RFC 9728 元数据(授权服务器发现) |
GET /health | 负载均衡器 / ECS 健康检查 |
| 环境变量 | 默认 | 用途 |
|---|---|---|
DEBUGGAI_MCP_TRANSPORT | stdio | 设置为 http 以启用远程传输 |
PORT | 3000 | HTTP 监听端口 |
DEBUGGAI_MCP_PUBLIC_URL | https://mcp.debugg.ai | 此服务器的公共资源 URL(RFC 9728 resource) |
DEBUGGAI_OAUTH_ISSUER | https://auth.debugg.ai | 向客户端通告的授权服务器 |
DEBUGGAI_TOKEN_TYPE | token | 设置为 bearer 以便 OAuth 令牌作为 Authorization: Bearer 转发 |
stdio 安装都不需要这些。
多副本部署(上线前必须确认): 隧道状态(会话隧道、其 Caddy 实例及其端口路由锁)是进程内的,按调用者通过持有者令牌的哈希键控 — 没有跨进程协调。在普通轮询负载均衡器后运行多个副本意味着一个调用者的调用可能落在不同的副本上,并为它们命中的每个副本创建一个隧道,而不是为整个会话创建一个(受副本数量限制,通过现有的 55 分钟空闲自动关闭自愈 — 绝不是跨会话的正确性错误,因为任何单个工具调用在其整个持续时间内都停留在单个副本上)。要在多副本 HTTP 部署上获得预期的“每个会话一个隧道”行为,请在负载均衡器上配置会话亲和路由(粘性/一致性哈希,键控于 getSessionKey() 派生的相同身份 — 实际上,是调用者的 Authorization 持有者令牌)。有关完整推理以及未配置时的诚实降级路径,请参阅 docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1。
遥测
该 MCP 服务器默认启用遥测功能——内置一个仅写入的 PostHog 项目密钥(phc_*),以便团队观察整个安装群中的缓存命中率、轮询节奏、隧道可靠性及其他运维指标。捕获的事件:
| 事件 | 触发时机 |
|---|---|
tool.executed / tool.failed | 每次工具调用 |
workflow.executed | 每次浏览器代理执行(携带 pollCount、durationMs、finalIntervalMs) |
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped | 每次隧道生命周期事件 |
template.lookup / project.lookup | 缓存命中/未命中,冷调用时携带 durationMs |
隐私策略:
- 唯一标识符为
SHA-256(api_key).slice(0, 16)——绝不使用原始密钥,不包含任何个人身份信息。 - 根据 PostHog 约定,
phc_*密钥为仅写入;可安全嵌入源代码。 - 设置
DEBUGGAI_TELEMETRY_DISABLED=1可完全退出(解析为无操作提供程序;不会有任何事件离开进程)。
活动模式在启动时记录:
Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)
本地开发
npm install
npm run build
npm run test:e2e # real end-to-end evals against the backend
评估套件会将构建好的 MCP 服务器作为子进程启动,针对真实后端逐一测试每个工具,并将每个流程的产物写入 scripts/evals/artifacts/<timestamp>/。各场景详情请参阅 scripts/evals/flows/。
MCP 注册:debugg-ai-local 与 debugg-ai
本仓库附带一个 .mcp.json,用于注册一个名为 debugg-ai-local 的项目级服务器,指向 node dist/index.js——即刚构建的本地代码。它仅在 Claude Code 的工作目录为本仓库时激活。
你的其他项目应使用用户级的 debugg-ai 注册,从已发布的 npm 包中拉取:
npm run mcp:global # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp
在此处编辑代码后,运行 npm run mcp:local(仅重新构建),以便下次调用 debugg-ai-local 时能获取你的更改。
链接
Dashboard · Docs · Issues · Discord
Apache-2.0 许可证 © 2025 DebuggAI