用 BugTape 把线上报错变成 Agent 能读的证据：免注册演示服、OAuth 接入与浏览器 SDK 埋点实操

在决定接入之前，先花两分钟验证链路。官方提供了一个公开的只读演示 MCP 端点，不需要账号也不需要密钥，里面放着一个样本工作区，项目是一个虚构的鞋店。样本捕获里包含一次结账接口的 500 与它背后的服务端类型错误、一个 Safari 上的脚本错误、一个卡住的支付请求、一次愤怒点击，以及一个 404。人和域名都是虚构的。

claude mcp add --transport http bugtape-demo https://app.bugtape.ai/demo/mcp

# 其他客户端用同一个地址，不需要 Authorization 头
# Cursor 的 .cursor/mcp.json 里：
# { "mcpServers": { "bugtape-demo": { "url": "https://app.bugtape.ai/demo/mcp" } } }

接好之后直接向 Agent 提问就行，比如「找出这个鞋店项目里最紧急的问题，读一下复现上下文，告诉我根因和修法」。演示端点只列出读取类工具：列出推荐的关键问题、列出问题分组、取单条问题、取复现上下文、取问题事件、取问题出现次数、取受影响用户等。确认、认领、评论与实时监听流需要你自己的工作区才有。

正式端点是远程 HTTP 服务，所有套餐都能用，免费档也包括在内。最快的接法是跑一条命令，它会打印一个链接和一个校验码：打开链接、核对校验码、点允许，Agent 就被加进工作区了。这条路径在没有浏览器的服务器与云端 Agent 上同样可用。想手动配也行，各客户端的写法不一样，下面几个是常见的。

# 最快：一条命令，后面可换成 cursor / codex / grok / grok-bot
npx -y bugtape connect claude

# Claude Code
claude mcp add --transport http bugtape https://app.bugtape.ai/mcp
# 加 --scope project 写入 .mcp.json 与团队共享，--scope user 对全部项目生效

# Cursor（.cursor/mcp.json）
{ "mcpServers": { "bugtape": { "url": "https://app.bugtape.ai/mcp" } } }

# Codex（~/.codex/config.toml）
[mcp_servers.bugtape]
url = "https://app.bugtape.ai/mcp"

授权这一层做得很标准：它发布了 OAuth 受保护资源与授权服务器的两个发现文档，未授权时返回 401 并带上资源元数据的 WWW-Authenticate 头，支持客户端 ID 元数据文档、动态客户端注册与 PKCE，并且会轮换刷新令牌。如果客户端本身支持 MCP 登录，只需要给它那个地址就行，不需要先造令牌。确实需要令牌的场景，可以在 Team 页面添加 Agent 生成，或者跑 npx -y bugtape login；生成的连接会出现在 Team 页面，随时可以移除。

读的一侧通了之后，就该让真实报错进来了。在你的应用仓库里跑 init，它会把这一串事情一次做完：建项目、生成密钥、给出与当前版本匹配的安装步骤，并上报一条测试报告让你确认链路通。之后按平台装对应的 SDK 即可。

# 在应用仓库里执行
npx -y bugtape init
# 产出：项目、捕获密钥、与你当前版本匹配的安装步骤、一条测试上报

# 需要令牌时用（也可在 Team 页面 Add an agent 生成）
npx -y bugtape login

SDK 覆盖四条线：浏览器端带重建的页面活动回放，Node.js 与 Python 用于服务端，Swift 目前是只处理已捕获错误的 alpha 版。服务端与浏览器端的证据可以在同一条 issue 里汇合——后面会讲到，平台字段不参与去重指纹，所以 Web 与原生可以归到同一个问题下面。

浏览器 SDK 的核心是一个滚动缓冲：它在浏览器里保留最近若干分钟的页面变化（用于重建页面回放，不是屏幕录像）、带状态与耗时的请求、控制台行与错误，然后随每一条上报一起送出。错误与失败请求会自动上报，人也可以点那个浮动按钮主动报；把 showButton 设成 false 就隐藏按钮。

npm install @bugtape/sdk

import BugTape from '@bugtape/sdk';

BugTape.init({
  apiKey: 'bt_live_your_key_here',
  endpoint: 'https://app.bugtape.ai/v1/ingest',  // 默认值
  recordingWindow: 10,                            // 分钟
  context: { platform: 'web', userId: 'user_123', reporterEmail: '[email protected]' },
  onSuccess: (receipt) => console.log('Bug captured:', receipt.id),
  onError: (error) => console.error(error.message),
  onQueueEvent: ({ state, reason, count }) => {
    // saved | delivered | dropped | unavailable；不含载荷与凭据
    console.log('BugTape retry queue:', state, reason, count);
  },
});

脱敏是这个 SDK 值得单独说的一点：表单输入默认会被遮蔽；把 privacy 设成 strict，则页面文本、查询串与请求体在离开浏览器之前就全部被遮蔽。需要更严的场景还有一条硬边界——请求体与响应体根本不采集，所以再怎么配置也不会有完整报文离开你的用户浏览器。截图是遮蔽后带复核的，而且投递需要一个能存图的服务端，官方托管服务目前还不存图；语音备注只能通过你自己的 onSubmit 回调处理。

身份与平台的两个细节也容易踩。登录后可以用 identify 把人挂到后续捕获上，登出时传空对象清除；队列里已存的捕获会保留捕获那一刻记录到的人与证据，不会采用后来设的值。平台字段由 context.platform 决定，缺省是 web；网页视图以原生外壳上报时要显式设成 react-native 之类的值，客户端省略时服务端会按 UA 推断。平台不参与去重指纹，所以一条 issue 可以同时跨 Web 与原生。

链路通了之后，日常的形态是这样的：BugTape 把同一类失败的多次上报归成一个问题并按紧急度排序，Agent 通过 MCP 列出推荐的关键问题、取某一条问题及其复现上下文与事件序列，判断根因，然后开一个合并请求交给人审查。支持的 Agent 包括 Claude Code、Cursor、Codex、ChatGPT 与 Grok。免费档与预付费档下，Agent 每读一次某条问题已捕获的事件消耗 2 个积分，其他读取不计费；Pro 档读取免费。

套餐与计费口径（以官方页面为准）

免费档      1 个项目，每月 100 条新问题，150 积分
Pro         每月 29 美元，项目数不限，Agent 经 MCP 读取免费
预付费      10 美元换 2000 积分

积分消耗：Agent 读取某条问题已捕获的事件 = 2 积分/次
其他读取免费；Pro 全部读取免费

演示端点上只能读，确认、认领、评论与监听流这几类动作要有自己的工作区才能用——这个区别在规划时要想清楚：如果打算让 Agent 自动认领并开工，就至少需要 Pro 档。还有一条运营上的建议：先让 Agent 只做「读证据 + 给根因与修法」，人确认之后再让它动手改；直接让它开 PR 也可以，但要保留人审这一步。

这一节讲的是它在不可靠网络下的行为，出问题时你会需要它。每条上报都带 schemaVersion、一个新的 UUIDv4 捕获 ID、捕获时间戳、SDK 名与版本，并且只序列化一次；网络重试、压缩回退与磁盘重放都复用同一份 JSON 与同一个 ID，所以服务端可以对一次「响应丢失的重试」做出确认而不新增一次出现。瞬时失败的请求会在 1 秒后重试一次；每次尝试有 10 秒截止时间，包含响应 JSON，所以一条卡住的排队捕获不会无限期堵住后面的。

重试与队列规则

可重试：408、425、429 与 5xx
不排队也不重试：其他 HTTP 拒绝，含 401/403 凭据与 409 捕获冲突
瞬时失败：1 秒后重试一次，每次尝试 10 秒截止（含响应 JSON）

磁盘队列：每条捕获单独存在 localStorage
作用域 = 精确端点 + 凭据的 SHA-256 指纹；凭据本身不落盘
换端点或换密钥后，旧作用域下的捕获被隔离

失败的请求不能证明服务端没收到——这正是同一 ID 复用的意义

实例方法这边也有几条要记：init 返回实例，open 打开上报组件，destroy 停掉记录器并移除组件，同时取消进行中的提交、回放与重试退避，且之后不再触发传输回调；已入队的捕获会保留，而在落盘之前被取消的新捕获不会被保存。它没有公开的 submit 方法，所以想程序化提交只能走自动上报或按钮。最后一句预期管理：请求体与响应体不采集、表单输入默认遮蔽、strict 模式遮蔽页面文本，这些是它的默认姿态；但它是你系统里的一个上报组件，上线前仍应过一遍数据合规与第三方传输的审批。