tracebug

TraceBug

捕获 Bug。让 AI 修复它。
本地优先，无需后端。只需一个 .html 文件——包含完整回放、控制台错误、网络请求和复现时间线，AI 编码 Agent 可通过 MCP 读取并修复问题。人类也可以离线打开。

▶ 观看 15 秒演示 · 观看 Claude 调试真实 Bug · 在沙盒中实时试用

---

TraceBug 是一款本地优先的调试助手。捕获 Bug → 生成一个独立的 .html 文件 → 交给你的 AI 编码 Agent（Claude Code、Cursor、Windsurf），它会通过本地 MCP 服务读取证据并修复问题；也可以通过电子邮件或 Slack 发给能离线打开文件的人类开发者。每份报告还会嵌入一个失败测试，供 Agent 运行以验证修复效果。

每份报告打开后都会显示：

🔍 Possible Cause (high confidence): API POST /orders failed with 500 after clicking 'Place Order'
> TL;DR: TypeError thrown on /checkout when clicking 'Place Order' button

无需账号。没有 SaaS 锁定。默认情况下，数据保留在浏览器中。

可选云端分享（功能已实现，默认由 UI 禁用）：如果你更愿意分享 URL 而不是文件，只需登录一次，即可获取内容相同的分享链接。代码通过功能标志（PHASE2-CLOUD）控制；在门户启用前，“分享”按钮会保持禁用状态。目前支持的分享方式是导出本地 .html 文件。

适用于任何前端框架：React、Angular、Vue、Next.js、Nuxt、Vite、Svelte、SvelteKit、Remix、Astro 或纯 HTML。

⚡ 30 秒快速入门

初次使用？在 2 分钟内报告你的第一个 Bug →

npx tracebug init

就这么简单。CLI 会检测你的框架，并打印出准确的两行代码片段。将它粘贴到应用中，运行 npm run dev，TraceBug 工具栏就会出现在右侧边缘。

两步报告 Bug：

1. 按 Ctrl+Shift+B（或点击工具栏上的 ⚡ 按钮）
2. 检查自动填充的报告，点击 “复制 GitHub Issue”
3. 粘贴到你的代码仓库中。完成。

TraceBug 的功能

Tester opens the page
  ↓
Arm a session (idle until you act):
  • ⚡ Quick Bug      — Ctrl+Shift+B opens the ticket-review modal
  • 📷 Screenshot / Region
  • 🔴 Record         — Sentry mode: rolling video buffer + HUD with timestamped
                        comments. File multiple bugs from one screen-share.
  • ⏺ Track session   — event-only capture (no video). Survives full-page
                        navigation, so clicking a link keeps recording.
  ↓
The SDK captures: clicks, inputs, navigation, API calls, console, errors, the DOM
stream (rrweb), environment, and a redacted Web-Storage snapshot
  ↓
Review the ticket, then export:
  • Export .html          — self-contained interactive DOM replay (KB, not MB)
  • Export for AI (.html) — tiny text-only report to paste into a chat
  • Download report (.md) · .zip (GitHub-attachable) · failing test (.spec.ts)
  • Export HAR · file a real GitHub/Linear/Slack/Jira issue
  ↓
Complete report includes:
  - Auto-generated title + smart summary + root-cause hint (high/medium/low confidence)
  - Steps to reproduce, full session timeline
  - Interactive DOM replay (or screen recording .webm), screenshots
  - Console errors + stack traces, failed network requests with response snippets
  - Environment (browser, OS, viewport, device)
  ↓
Send the .html → developer opens it offline and sees exactly what happened,
or an MCP-connected coding agent reads it and debugs from it.

扫描页面（通过 axe-core 检查无障碍、损坏的图片、混合内容、挫败信号、失败或缓慢的 API、JS 错误）可通过编程方式使用 TraceBug.scanPage()；它不再是工具栏按钮。

两种使用 TraceBug 的方式

选项 1：npm 包（面向开发者）

在项目中安装 SDK——最适合希望 TraceBug 始终在开发/预发布环境中运行的团队。

npm install tracebug-sdk

import TraceBug from "tracebug-sdk";
TraceBug.init({ projectId: "my-app" });

选项 2：Chrome 扩展程序（面向非开发者）

安装浏览器扩展程序，无需编写代码。QA 测试人员、PM 和客户可以在任何网站上使用它。

从 Chrome Web Store 安装——一键安装，即刻可用。

浏览器	支持情况
Chrome	支持——从 Chrome Web Store 安装
Edge	支持——可原生使用 Chrome Web Store 扩展程序
Brave	支持——可原生使用 Chrome Web Store 扩展程序
Opera	支持——请先安装 "Install Chrome Extensions" 附加组件
Firefox	暂不支持——请改用 npm SDK

浏览器支持

浏览器	npm SDK	扩展程序
Chrome	✅	✅
Edge	✅	✅
Brave / Opera	✅	✅
Firefox	✅	⏳（移植已暂停——仅 SDK）
Safari	✅¹	❌（仅 SDK）

SDK 与框架和浏览器无关，可在任何支持现代 JS 的环境中运行。 ¹ 交互式 DOM 回放导出功能使用浏览器原生的 CompressionStream / DecompressionStream（Chrome 80+、Firefox 113+、Safari 16.4+）；在较旧的引擎上， 导出器会以未压缩形式提供回放，查看器则会回退到截图图库。扩展程序目前仅支持 Chromium（Firefox 移植已暂停； 没有 Safari 版本）——这些浏览器请使用 npm SDK。

功能

🧠 调试助手（v1.3）

每份报告都会列出四项推导出的信号，帮助从“发生了什么”转向“可能是什么原因导致的”：

信号	示例
🔍 根因提示	"点击 'Place Order' 后，API POST /orders 请求失败，返回 500"，并附带置信度等级（高/中/低）
TL;DR	结合网络、错误、点击和页面信号的一句话摘要
用户点击了什么	Bug 发生前最后一次点击的 tag、文本、选择器、id、aria-label、testId
近期操作	最近约 10 项用户操作，以通俗易懂的步骤呈现（"点击了 'Edit' 按钮"、"跳转到 /checkout"）

此外：

• 网络响应片段——异步捕获每个失败的 fetch/XHR 响应正文的前 200 个字符（绝不会阻塞请求）
• 内存中的失败缓冲区——最近 10 个失败请求可通过 TraceBug.getNetworkFailures() 访问
• 确定性——纯函数，不调用 AI API，对已计算的报告字段执行 O(1) 操作

这四项信号都会内嵌在 GitHub issue、Jira 工单、PDF 报告和快速 Bug 弹窗中。完整输出示例请参阅 docs/bug-reporting.md。

🤖 MCP 服务 — AI Agent 调试你的报告（v1.5）

你的编码 Agent（Claude Code、Cursor、Windsurf、VS Code）读取 TraceBug 错误报告并修复问题——完全在本地进行，不会上传任何内容：

claude mcp add tracebug -- npx -y tracebug mcp --dir ./bug-reports

服务会读取 TraceBug 导出的同样独立 .html 文件。测试人员将报告文件交给开发人员，开发人员把它放进代码仓库，Agent 就能使用 9 个工具：list_bug_reports、get_bug_report、get_console_errors、get_network_activity、get_repro_steps、get_screenshot（真实图像内容）、get_playwright_test、resolve_stack 和 get_fix_context。get_bug_report 会根据报告内容生成一份优先级明确的调查指南，让 Agent 确切知道接下来要调用哪些工具。控制台堆栈 + 失败请求正文 + 复现步骤 + 挫败感信号——从错误报告到修复，Agent 所需的一切信息。

最后 3 个工具补齐了修复闭环（v1.9）：get_playwright_test 会返回生成的失败 Playwright 测试规范，它会重放会话并断言捕获到的故障已消失——修复错误前测试为红色，修复后为绿色——这样 Agent 就能运行测试、应用补丁，然后重新运行，直到测试变绿。resolve_stack 使用服务运行所在代码仓库中的 .map 文件，将报告里的压缩堆栈帧映射到原始源文件和行号。get_fix_context 是一键启动修复的工具：返回失败请求及响应片段、触发请求的用户操作、通过 source map 解析出的顶部堆栈帧，以及是否有可用的失败测试。

开始使用只需粘贴一段内容：每次导出 .html 后，扩展都会显示现成的 Agent 提示词（并自动复制）；导出的文件本身也会在其 AI 标签页中附带相同的提示词；在 Claude Code 中，你也可以直接输入 /tracebug:debug_bug_report。

其他工具的 MCP 服务托管在云端：你的错误数据必须先存储在它们的服务上。TraceBug 则通过 stdio 在你的设备上运行，不会建立任何网络连接。立即试用——此代码仓库附带一个演示报告和预配置的 .mcp.json。参见 docs/mcp.md。

🎭 Playwright 报告器 — 从失败的测试生成错误报告（v1.6）

每个失败的 Playwright 测试都会生成同样独立的 .html 错误报告——断言错误 + 代码片段、作为复现步骤的步骤时间线、页面控制台 + 网络活动（通过可选 fixture 获取）、失败截图，以及根因提示。将 bug-reports/ 作为 CI 构建产物上传，然后通过 MCP 服务使用你的 Agent 调试：

// playwright.config.ts — that's the whole setup
reporter: [["list"], ["tracebug-sdk/playwright", { outputDir: "bug-reports" }]],

目前没有其他工具能将测试运行中发现的错误保存为可移植文件——云端工具无法将其查看器附加到 CI 构建产物上。参见 docs/playwright.md。

🧠 AI 调试器 — 使用自带密钥的 LLM 分析（v1.6）

使用你自己的密钥运行真正的大模型根因分析——支持 Anthropic、OpenAI 或本地 Ollama。调用会直接从你的浏览器发送到服务提供方：TraceBug 不会获取密钥、提示词或响应；提示词在离开页面前也会清除类似密钥的内容。无需按量计费，也不经过供应商云端。

结合本地启发式提示和本地 MCP 服务，这就是绝不与外部通信的 AI 调试——云端托管、按量计费的竞争产品都无法复制这一独特优势。参见 docs/ai-debugger.md。

🌐 HAR 导出（v1.6）

只需点击一次，即可将捕获的网络活动导出为标准的 HAR 1.2 文件，并在 DevTools、Charles、Fiddler 或 Postman 中打开。没有竞争产品提供此功能——Jam 甚至宣传“涵盖 HAR 提供的一切”，却不提供导出。你的网络捕获数据是归你所有的可移植文件，而不是存储在他人云端的一条记录。参见 docs/har-export.md。

🧪 自动生成的失败 Playwright 测试（v1.9）

每次导出都会附带一个可运行的 Playwright 测试规范，用于重放捕获的会话（定位器优先级为 data-testid → id → aria-label → role+name → 捕获的 CSS 选择器），并断言捕获到的故障已消失——失败的端点必须不再失败，控制台错误必须不再抛出。Bug 存在时测试显示红色，修复后显示绿色。可通过三种方式获取：在 Quick Bug More 菜单中选择 Download failing test (.spec.ts)、从 .html 导出文件中获取，或使用 MCP get_playwright_test 工具——这样 Agent 就可以运行测试、修补代码并重新运行，直至测试通过。

🔎 检查模式——为设计 QA Bug 提供样式证据（v1.9）

现在，“按钮看起来不对”也有据可查。类似 DevTools 的检查模式（扩展弹出窗口 → Inspect element，或 TraceBug.activateInspectMode()）：悬停时会显示盒模型高亮和计算样式摘要提示框；点击后会将元素附加到报告中，并提供经过筛选的样式快照——包括排版、十六进制颜色、盒模型——以及 WCAG 文本对比度判定结果（比例 + AA 通过/未通过）。这些信息会显示在标注卡片、生成的 GitHub issue 和导出文件中，并作为结构化数据提供给通过 get_bug_report 获取数据的 MCP Agent。

🎬 录制前选项 + 元素级模糊处理（v1.9）

扩展弹出窗口的 ⚙ Record options 面板提供可选的 3s/5s 倒计时和 Blur before recording——在捕获第一帧之前就遮盖敏感区域。（捕获屏幕和麦克风的选项对应屏幕录制；该功能在 1.11 版本的扩展中暂停，并将在 1.11.1 版本中恢复。）完整功能集通过公共 SDK API 提供，目前视频录制可用：TraceBug.prepareRecording({ blurFirst, delaySec, surfaceMode, withMicrophone })。

模糊处理本身是元素级的，点击即可模糊：悬停时高亮显示，点击后应用 filter: blur(12px)，作用于元素本身；再次点击即可取消模糊。由于模糊效果属于元素自身的渲染，因此滚动时绝不会出现延迟。被模糊的元素还会添加 tb-mask，因此 DOM 重放也会遮盖其文本，而不只是视频像素。

📦 收件人可直接操作的报告（v1.8）

• Download .zip (attach to GitHub)——将相同的离线重放内容打包为 .zip，因为 GitHub issue 支持拖放 .zip 附件，但不接受单独的 .html 文件。
• 导出报告中的 issue 操作——查看器标题栏中有 Open GitHub issue（如果导出器配置了 githubRepo，则会提供预填充的 URL）和 Copy issue markdown（完全离线，可粘贴到任何问题跟踪器中）。两者都在导出时根据已脱敏的报告预先生成。

自动捕获（无需操作）

内容	详情
点击	元素标签、文本、id、className、aria-label、role、data-testid、href、按钮类型
输入	字段名称、类型、值（敏感字段会自动脱敏）、占位文本
下拉菜单	所选选项的文本 + 值、所有可用选项
表单提交	表单 id、action、method、所有字段值（密码会脱敏）
导航	路由起点 → 终点（支持 pushState、replaceState、popstate）
API 请求	URL、method、状态码、响应时间（同时支持 fetch 和 XMLHttpRequest）
错误	消息、堆栈跟踪、源文件、行号、列号
控制台	console.error + warn + info + log（每个非错误级别每个会话最多记录 50 条）；warn/info 会显示在复现时间线上
未处理的拒绝	Promise 拒绝原因 + 堆栈
环境	浏览器、操作系统、视口、设备类型、网络连接、语言、时区

哨兵模式 — 循环视频缓冲

在 QA 会话开始时点击一次 Record，即可通过同一次屏幕共享创建任意数量的 Bug 工单。灵感来自 NVIDIA Shadowplay / OBS 回放缓冲。

功能	作用
一次性选择	点击 Record → 在系统对话框中选择屏幕/窗口/标签页。HUD 随即显示，你可以照常进行 QA。
📸 Capture 按钮	将正在录制的视频截取为已完成的 .webm 文件，并打开工单弹窗。录制会继续进行。
带时间戳的评论	在 HUD 中输入备注 → 按 Enter → 备注会与当前视频时间戳一并保存。
出错时自动捕获	录制启动后发生 JS 错误时，错误提示会提供“Capture with video”选项——点击一次即可捕获缓冲内容。
智能停止	如果至少捕获过一次，点击 Stop 会静默结束录制。否则会打开弹窗，显示完整录制内容。

自动扫描器

点击 Scan，即可并行运行六种浏览器内检测器，找出你可能没注意到的问题：

检测器	检测内容
a11y	通过 axe-core 检测 WCAG 2.0/2.1 A+AA 违规
损坏的图像	加载失败的 <img> 元素
混合内容	HTTPS 页面上的 http:// 资源（被 CSP 拦截或降级）
JS 错误	去重后的控制台错误和未处理的拒绝
请求失败	带有响应正文片段的 4xx/5xx/API 网络错误
缓慢的 API	耗时超过 2 秒的成功调用

每个问题都提供 Locate（闪烁显示出问题的元素）、File ticket（预填快速 Bug 弹窗）和 Dismiss（忽略）。

QA 工具（一键使用）

工具	作用
快速 Bug 捕获	按 Ctrl+Shift+B，打开自动填入标题和描述的工单审核弹窗
截图	捕获视口并自动生成名称（例如，01_click_add_vendor.png）；添加到当前工单
区域截图	以拖动选择的方式进行类似截图工具的截取；添加到工单
语音备注	通过语音描述 Bug — 使用 Web Speech API 进行语音转文字
GitHub Issue	生成完整的 GitHub markdown — 复制到剪贴板，截图和 .webm 文件自动下载
Jira 工单	生成包含优先级和标签的 Jira 标记文本

可通过编程方式使用（v1.0 中已从默认 UI 移除）

这些功能仍包含在发布包中，但不再有工具栏按钮。高级用户可以直接调用：

TraceBug.activateAnnotateMode();   // element annotate mode (Ctrl+Shift+A no longer wired)
TraceBug.activateDrawMode();       // live-page rectangles/ellipses
TraceBug.downloadPdf();            // PDF report
TraceBug.exportAnnotationsJSON();  // JSON / Markdown export

自动生成

输出	详情
Bug 标题	根据会话上下文生成智能标题（例如，“供应商更新失败 — TypeError”）
复现步骤	根据事件时间线生成编号步骤
会话时间线	调试时间线，列出每个事件及其经过时间戳
环境快照	浏览器版本、操作系统、视口、设备类型、连接信息

智能过滤

• SDK 自过滤：TraceBug 从不记录自身 UI 交互（点击仪表板、注释画布和按钮）
• 移除框架噪声：内部开发服务器请求（webpack HMR、Vite ping、Next.js 堆栈帧）会自动从时间线和报告中排除
• 重复错误去重：连续出现的相同错误会合并

用户识别与 Bug 工作流

// Identify who's using the app (persisted in localStorage)
TraceBug.setUser({ id: "user_123", email: "[email protected]", name: "Jane" });

// Flag current session as a bug (adds red BUG badge)
TraceBug.markAsBug();

// Get a 2-sentence Slack-friendly summary
const summary = TraceBug.getCompactReport();
// "Bug on /vendor — TypeError: Cannot read 'status' after clicking Edit → selecting Inactive..."

插件与钩子系统

无需分叉即可扩展 TraceBug — 过滤事件、丰富报告或触发自定义操作：

TraceBug.use({
  name: "slack-webhook",
  onReport: (report) => { fetch("https://hooks.slack.com/...", { method: "POST", body: JSON.stringify(report) }); return report; },
});

TraceBug.on("error:captured", (error) => console.log("Bug found:", error.data.error.message));

CI/CD 辅助工具

// In Playwright/Cypress tests
expect(TraceBug.getErrorCount()).toBe(0);

// Upload full session as test artifact on failure
const json = TraceBug.exportSessionJSON();

安装

从 npm 安装

npm install tracebug-sdk

从 GitHub 安装

npm install github:prashantsinghmangat/tracebug-ai

Chrome 扩展（无需编写代码）

请参阅下方的 Chrome 扩展 部分。

配置

TraceBug.init({
  projectId: "my-app",        // Required: identifies your app
  maxEvents: 200,             // Max events per session (default 200)
  maxSessions: 50,            // Max sessions in localStorage (default 50)
  enableDashboard: true,      // Show the floating bug button (default true)
  enabled: "auto",            // Control when SDK is active (see below)
});

enabled option

Value	Behavior
"auto"	在开发/预发布环境中启用，在生产环境中禁用（默认）
"development"	仅在 NODE_ENV 为 "development" 时启用
"staging"	在开发环境和预发布主机上启用（主机名中包含 staging、stg、uat、qa）
"all"	始终启用，包括生产环境
"off"	完全禁用
string[]	自定义主机名，例如 ["localhost", "staging.myapp.com"]

编程 API

核心

import TraceBug from "tracebug-sdk";

TraceBug.pauseRecording();
TraceBug.resumeRecording();
TraceBug.startRecording();   // alias for resumeRecording
TraceBug.stopRecording();    // alias for pauseRecording
TraceBug.isRecording();
TraceBug.getSessionId();
TraceBug.destroy();

截图

// Capture full-viewport screenshot (auto-named from last event context)
const screenshot = await TraceBug.takeScreenshot();
// → { filename: "01_click_add_vendor.png", dataUrl: "data:image/png;...", ... }

// Snipping-tool style: user drags a region, press Esc to cancel
const region = await TraceBug.takeRegionScreenshot();
// → { filename: "02_click_..._region.png", ... } | null

const allScreenshots = TraceBug.getScreenshots();

语音录制

// Check if voice recording is supported in the browser
if (TraceBug.isVoiceSupported()) {
  // Start recording — speech-to-text via Web Speech API (free, no API keys)
  TraceBug.startVoiceRecording({
    onUpdate: (text, interim) => console.log("Transcript:", text),
    onStatus: (status, msg) => console.log("Status:", status),
  });

  // Stop recording — returns the transcript
  const transcript = TraceBug.stopVoiceRecording();
  // → { id, timestamp, text: "When I click update the page breaks", duration }

  // Get all voice transcripts
  TraceBug.getVoiceTranscripts();
}

语音转录内容会自动包含在 GitHub Issue、Jira Ticket 和 PDF 报告中。

测试人员备注

TraceBug.addNote({
  text: "Button doesn't respond after selecting Inactive status",
  expected: "Vendor should update successfully",
  actual: "App throws TypeError and freezes",
  severity: "critical",  // "critical" | "major" | "minor" | "info"
});

报告

// Generate complete bug report object
const report = TraceBug.generateReport();

// Get auto-generated bug title
const title = TraceBug.getBugTitle();
// → "Vendor Update Fails — TypeError"

// Get GitHub issue markdown (copies to clipboard in dashboard)
const markdown = TraceBug.getGitHubIssue();

// Get Jira ticket payload
const ticket = TraceBug.getJiraTicket();
// → { summary, description, environment, priority, labels }

// Download PDF report
TraceBug.downloadPdf();

// Get environment info
const env = TraceBug.getEnvironment();
// → { browser: "Chrome", browserVersion: "122", os: "Windows 10/11", ... }

数据访问

import { getAllSessions, clearAllSessions, deleteSession } from "tracebug-sdk";

const sessions = getAllSessions();
const bugs = sessions.filter(s => s.errorMessage);
clearAllSessions();
deleteSession("session-id");

独立工具

import {
  generateReproSteps,
  captureEnvironment,
  buildReport,
  generateGitHubIssue,
  generateJiraTicket,
  generateBugTitle,
  buildTimeline,
  formatTimelineText,
} from "tracebug-sdk";

元素标注与绘制

// Activate modes programmatically
TraceBug.activateAnnotateMode();   // Click elements to annotate
TraceBug.activateDrawMode();       // Draw shapes on the page

// Check state
TraceBug.isAnnotateModeActive();
TraceBug.isDrawModeActive();

// Export all annotations
const report = TraceBug.getAnnotationReport();
const md = TraceBug.exportAnnotationsMarkdown();
await TraceBug.copyAnnotationsToClipboard("markdown");

// Deactivate
TraceBug.deactivateAnnotateMode();
TraceBug.deactivateDrawMode();
TraceBug.clearAnnotations();

控制面板

屏幕右侧的紧凑工具栏提供以下功能：

• ⚡ Quick Bug — 打开工单审核弹窗（Ctrl+Shift+B）
• 📷 截图 — 捕获页面并打开标注编辑器
• ▢ 区域 — 捕获选定区域
• 🔴 录制 — 屏幕录制（Sentry 模式：滚动缓冲区 + HUD）
• ⏺ 跟踪会话 — 仅捕获事件，不录制视频（切换页面后仍会保留）
• ✓ 查看已保存工单 — 离线的已保存工单列表
• ✕ — 在此页面关闭 TraceBug

标注和绘制模式仍包含在构建包中，但在 v1.0 中不再作为独立工具栏按钮提供 — 可通过编程方式或录制 HUD 中的画笔按钮使用。请参阅 docs/annotate-and-draw.md。

Quick Bug 弹窗

审核并编辑工单，然后导出或提交：

• 自动生成标题、摘要、根因提示、复现步骤和时间线
• 交互式 DOM 回放（或屏幕录制）、截图集
• 选项卡：信息 · 控制台 · 网络 · 操作 · AI · 事件
• 导出：导出 .html（回放） · 为 AI 导出（.html） · 下载报告（.md） · 下载 .zip（可附加到 GitHub） · 下载失败测试（.spec.ts） · 导出 HAR
• 直接提交：GitHub · Linear · Slack · Jira（配置令牌后可创建实际问题）

键盘快捷键

快捷键	操作
Ctrl+Shift+B	打开 Quick Bug 工单弹窗
Ctrl+Shift+S	截图
Esc	退出当前模式 / 关闭弹窗

注意：默认不再绑定 Ctrl+Shift+A（标注）和 Ctrl+Shift+D（绘制）。底层模式仍可通过编程 API（TraceBug.activateAnnotateMode() / activateDrawMode()）调用；也可通过录制 HUD 上的 ✎ 按钮进入绘制模式。

文档

完整文档位于 docs/ 文件夹中：

• 快速入门 — 安装、设置和首次使用
• API 参考 — 完整的编程 API
• 配置 — 所有配置选项的说明
• 错误报告 — 截图、备注、语音和导出
• MCP 服务 — 让 AI Agent（Claude Code、Cursor）调试你的报告
• 标注与绘制 — UI 标注功能
• Chrome 扩展程序 — 扩展程序的安装与使用
• 架构 — TraceBug 的内部工作原理
• ADR — 为什么选择本地优先、单文件 HTML、rrweb、MV3 和零依赖
• 性能 — 实测数据和可复现的基准测试
• 兼容性 — 浏览器矩阵、支持政策和已知限制
• 迁移指南 — 升级说明和 API 稳定性
• 路线图 — 已发布 · 进行中 · 计划中 · 长期规划

Chrome 扩展程序

TraceBug Chrome 扩展程序让非开发人员无需编写代码即可使用 TraceBug 的所有功能。

安装方法

推荐：从 Chrome 网上应用店安装——适用于 Chrome、Edge、Brave 和 Opera。

从源代码安装（适用于开发者）：

1. git clone 此仓库，然后运行 npm install && npm run build
2. 打开 chrome://extensions/ → 启用开发者模式 → 加载已解压的扩展程序 → 选择 tracebug-extension/

使用方法

1. 访问任意网站（测试环境、生产环境、localhost、内部工具）
2. 点击工具栏中的 TraceBug 扩展图标
3. 切换 “在此网站启用”——页面将重新加载并启用 TraceBug
4. 页面上会出现悬浮的错误按钮
5. 使用所有 QA 工具：截图、备注、GitHub/Jira 问题、PDF 报告
6. 也可以直接从扩展弹出窗口使用快捷操作

扩展功能

• 按网站切换——仅在你测试的网站上启用
• 徽章指示器——在当前标签页启用时显示绿色的“ON”
• 快捷操作——从弹出窗口使用批注、绘图、截图、PDF 报告、GitHub 问题、Jira 工单
• 已启用网站列表——从弹出窗口管理所有已启用的网站
• 页面上的紧凑工具栏——与 npm SDK 功能完整的工具栏相同
• 兼容 CSP——使用 chrome.scripting.executeScript 和 world: "MAIN" 绕过内容安全策略限制

浏览器兼容性

浏览器	支持情况
Google Chrome	是
Microsoft Edge	是
Brave	是
Opera	是（请先安装“Install Chrome Extensions”附加组件）
Firefox	尚不支持——请使用 npm SDK

Chrome 网上应用店

TraceBug 已发布在 Chrome 网上应用店：

安装 TraceBug 扩展

从源代码构建

# Clone the repo
git clone https://github.com/prashantsinghmangat/tracebug-ai.git
cd tracebug-ai

# Install dependencies
npm install

# Build SDK (produces CJS + ESM + IIFE for extension)
npm run build

# Output:
#   dist/index.js              — ESM (npm package)
#   dist/index.cjs             — CJS (npm package)
#   dist/index.d.ts            — TypeScript declarations
#   tracebug-extension/tracebug-sdk.js — IIFE (Chrome Extension)

运行示例应用

cd example-app
npm install
npm run dev
# Open http://localhost:3000

测试示例错误

1. 前往 /vendor
2. 点击“Edit”
3. 将 Status 更改为“Inactive”
4. 点击“Update”——触发 TypeError
5. 点击错误按钮，查看包含复现步骤的报告

隐私

• 自动屏蔽敏感字段（password、secret、token、ssn、credit）
• 捕获时屏蔽约 20 种符合令牌特征的模式（JWT、Bearer 标头、云服务提供商密钥）——已记录的密钥绝不会进入报告对象
• 导出流程和导出的报告会准确显示屏蔽内容：🛡 N sensitive values auto-masked
• 通过配置中的 redact: { fields, patterns } 覆盖特定应用的 PII——也可在扩展弹出窗口的 🛡 Redaction rules 部分设置
• 所有数据都保存在 localStorage 中——不会发送给 TraceBug。你可以选择要发送给 GitHub、Linear、Slack 或 AI 提供商的内容
• SDK 绝不会捕获自身 UI 的交互
• 没有外部服务、跟踪或分析

框架兼容性

格式	文件	适用对象
ESM（import）	dist/index.js	Vite、Next.js、Nuxt、SvelteKit、现代 webpack
CJS（require）	dist/index.cjs	Angular CLI、较旧版本的 webpack、Node.js
IIFE（全局）	tracebug-extension/tracebug-sdk.js	Chrome 扩展、普通 <script> 标签
TypeScript	dist/index.d.ts	ESM 和 CJS 均提供完整类型支持

卸载

npm 包

npm uninstall tracebug-sdk

然后从应用的入口文件中移除 TraceBug.init() 调用。

---

⭐ 如果它为你节省了时间，请给这个仓库点个星

如果 TraceBug 帮你更快地交付了项目，点个星就是最好的感谢方式，也能帮助其他开发者找到它。

帮忙宣传：

• 分享到 Twitter/X
• 分享到 LinkedIn
• 分享到 Hacker News

发现了 Bug 或有功能建议？ 提交 issue — TraceBug 的诞生是因为 Bug 报告太糟糕了。我们希望让它们没那么糟糕。

---

由 Prashant Singh Mangat 倾情打造 ❤
_{MIT 许可 · 不追踪 · 无后端 · 你的数据留在浏览器中}

Chrome 扩展

前往 chrome://extensions/ → 点击 TraceBug 上的 移除。

许可证

MIT

作者

Prashant Singh Mangat

• GitHub：prashantsinghmangat
• npm：tracebug-sdk