BugProof

BugProof

https://github.com/user-attachments/assets/2315cfee-3ccf-40d7-830e-3a3d23731ab8

---

---

为什么选择 BugProof

“在我的机器上能运行”不是 Bug 报告。

如今提交后端或 CLI Bug 通常是这样的：

• 一张终端截图
• 一段复制粘贴的堆栈跟踪
• 一份列出可能相关文件的清单
• 对报告者如何运行程序的猜测性描述

然后维护者要花数小时重现故障：匹配版本、复现环境、找到正确命令、猜测配置。大部分时间都浪费了。

BugProof 捕获的是 Bug 本身，而不是对它的描述。 一条命令即可生成一个 .bug 文件，其中包含源代码快照、确切命令、环境变量架构、故障指纹和重放元数据。另一位开发者运行 bugproof replay bug.bug，即可确定性地复现故障。

可以把它看作 面向 Bug 的 Git：一种可移植、内容可寻址且可验证的文件，让“你能复现吗？”变成一行命令。

---

亮点

• 一条命令即可捕获。 使用 bugproof capture -- 包装任何失败的命令，然后发送生成的文件。
• 确定性重放。 源代码、环境、命令和指纹一并保存。自动判定结果。
• 无需 Docker。无需守护进程。 使用操作系统原生机制——Linux 命名空间、Windows Job Objects、macOS Seatbelt。
• 加密签名。 内置 Ed25519 签名和验证功能。通过 bugproof keygen / --sign / verify 生成具备防篡改能力的文件。
• 自修复重放。 --self-heal 会在沙箱中自动安装缺失的 npm/pip 依赖并重试。
• 尽力而为的凭据脱敏。 通过模式匹配和 Shannon 熵扫描环境变量。可检测常见密钥格式（API 密钥、令牌、JWT）；低熵密码和二进制凭据仍可能泄露。
• 支持多种语言。 自动检测 Node.js、Python、Ruby、Go、Rust、Java、C/C++、.NET 和 Kotlin 构建环境。
• 跨平台。 支持 Windows ↔ Linux ↔ macOS 之间重放，并提供命令和环境变量转换及架构不匹配防护。

---

安装

npm install -g bugproof

要求： Node.js 18+ 和 Git。只有在捕获的命令使用相应语言时，才需要安装可选语言工具链（Python、Java、Go、Rust 等）。

安装后运行一次健康检查：

bugproof doctor

---

GitHub Action — 自动捕获 CI 失败

在任意 GitHub Actions 工作流中添加一个步骤，即可自动将不稳定或失败的命令捕获为 .bug 工件。

- name: Capture flaky test
  uses: sidinsearch/BugProof/.github/actions/bugproof-action@main
  with:
    command: 'npm test -- --run flaky-suite'
    name: flaky-test-failure
    timeout: 300000

工作原理：该 Action 从 npmjs.org 安装 bugproof（npm install -g bugproof）→ 使用 bugproof capture 包装命令 → 命令失败时，将 .bug 工件上传到 Actions 运行记录。开发者下载后，可使用 bugproof replay 在本地复现。

使用场景：

• 不稳定的 CI 测试：捕获确切的失败情况，便于本地调试
• 跨平台失败：测试在 Linux CI 上通过，却在 macOS 上失败——分别捕获失败情况并进行比较
• 间歇性崩溃：bugproof capture -- node app.js 会打包崩溃状态、环境和源代码

所有输入：

输入	必填	默认值	说明
command	✅	—	要捕获的命令（例如 npm test）
name	—	bug_<timestamp>	工件名称
timeout	—	300000	命令超时时间，单位为毫秒
skip-secrets	—	false	跳过环境变量密钥扫描
upload-artifact	—	true	将 .bug 文件上传为 Actions 工件
node-version	—	24	bugproof 使用的 Node.js 版本

该 Action 位于此仓库的 .github/actions/bugproof-action/action.yml。通过 uses: sidinsearch/BugProof/.github/actions/bugproof-action@main 引用。BugProof 始终从 npmjs.org 安装——无需 GitHub Packages 令牌。

---

MCP 服务 — AI Agent 集成

BugProof 内置了 MCP（模型上下文协议）服务，为 AI Agent 提供 10 个工具，以及资源和提示词。它已列入官方 MCP 注册表，名称为 io.github.sidinsearch/bugproof。

设置

Claude Code

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "bugproof": {
      "command": "npx",
      "args": ["-y", "bugproof", "mcp"]
    }
  }
}

Cursor

添加到 Cursor MCP 配置（Settings → Features → MCP）：

{
  "mcpServers": {
    "bugproof": {
      "command": "npx",
      "args": ["-y", "bugproof", "mcp"]
    }
  }
}

Continue.dev

添加到 ~/.continue/config.json：

{
  "experimental": {
    "mcpServers": {
      "bugproof": {
        "command": "npx",
        "args": ["-y", "bugproof", "mcp"]
      }
    }
  }
}

已全局安装 bugproof

如果你已全局安装 bugproof（npm install -g bugproof），请省略 npx -y：

{
  "mcpServers": {
    "bugproof": {
      "command": "bugproof",
      "args": ["mcp"]
    }
  }
}

无需单独安装 MCP。 npx -y bugproof mcp 会自动从 npmjs.org 下载，并通过 stdio 启动服务。

工具

工具	说明	AI Agent 的使用场景
capture	运行命令，并捕获为 .bug 工件	“捕获这个失败的测试，并告诉我发生了什么变化”
replay	重放 .bug 文件并返回结果	“重放 CI 中的工件，确认它是否仍然失败”
inspect	显示工件元数据	“不运行这个 .bug 文件，能告诉我里面有什么吗？”
diff	比较两个工件	“比较 CI 捕获内容和我的本地捕获内容——有什么不同？”
doctor	检查沙箱功能	“这台机器支持完整的沙箱隔离吗？”
share	通过 GitHub Gist 分享工件	“把这个错误分享给我的团队”
pull	从 Gist 下载工件	“从这个 URL 拉取错误工件”
watch	命令失败时自动捕获	“监视 npm test，失败时进行捕获”
list	列出目录中的 .bug 工件	“显示此项目中的所有错误工件”
clean	删除 .bug 工件	“清理此目录中的旧错误工件”

资源

AI Agent 可以通过资源 URI 直接读取 .bug 工件内容：

• bugproof://artifact/{path} — 读取原始 .bug 工件（Base64 编码的 ZIP）

提示词

用于常见 AI Agent 任务的预构建工作流：

提示词	说明
capture-failure	引导捕获失败的命令并生成 .bug 工件
replay-and-analyze	重放工件并分析根本原因
compare-bugs	比较两个工件以找出差异

AI 会话示例

User:   Capture the failing test and tell me what went wrong
Agent:  [calls bugproof capture -- npm test -- --run flaky-suite]
        [calls bugproof inspect on the result]
        "The test failed with a timeout. Fingerprint matches a known
         Redis-unreachable pattern. Here's the captured stderr..."

MCP 服务通过 stdio（JSON-RPC 2.0）进行通信。它会调用本地的 bugproof CLI，并使用 --json 输出，然后返回包含易读摘要和原始数据的结构化结果。如果尚未安装 bugproof，npx -y 会从 npmjs.org 获取，无需全局安装。

---

AI Agent 技能

BugProof 提供一款可分发的 AI Agent 技能，帮助 AI 编码 Agent（Claude Code、Cursor、OpenCode、OpenClaw、Gemini CLI、GitHub Copilot 等）有效使用 BugProof。该技能遵循开放的 Agent Skills 标准——构建一次，即可在任何兼容的 Agent 中使用。

技能功能

加载后，该技能会让 AI Agent 全面掌握：

• 全部 14 条 BugProof 命令及其标志和示例
• 捕获、重放、比较和检查工作流
• 跨平台重放模式
• MCP 服务配置
• 命名、安全和工件管理的最佳实践
• 8 个真实示例（Node.js、Python、Go、Java、CI/CD、跨平台、不稳定测试）

AI Agent 如何使用技能

当用户提到以下内容时，Agent 会自动加载该技能：

• “捕获这个 Bug”
• “重放这个 Bug”
• “复现这个故障”
• “分享这个 Bug”
• “.bug 文件”
• “在我的机器上能运行”
• “可执行 Bug”

也可以直接调用：/bugproof

安装技能

选项 1：克隆此仓库

# Clone the BugProof repository
git clone https://github.com/sidinsearch/BugProof.git

# Copy the skill to your agent's skills directory
# Claude Code:
cp -r BugProof/skills/bugproof ~/.claude/skills/

# OpenCode:
cp -r BugProof/skills/bugproof ~/.config/opencode/skills/

# OpenClaw:
cp -r BugProof/skills/bugproof ~/.agents/skills/

# Cursor:
cp -r BugProof/skills/bugproof ~/.cursor/skills/

选项 2：直接下载技能

# Download just the skill
curl -L https://github.com/sidinsearch/BugProof/archive/refs/heads/main.tar.gz | tar xz
cp -r BugProof-main/skills/bugproof ~/.claude/skills/

技能结构

skills/bugproof/
├── SKILL.md                    # Main instructions (required)
├── reference/
│   └── commands.md             # Full command reference
└── examples/
    └── usage-examples.md       # Real-world usage examples

支持的 AI Agent

Agent	技能目录
Claude Code	~/.claude/skills/bugproof/
OpenCode	~/.config/opencode/skills/bugproof/
OpenClaw	~/.agents/skills/bugproof/
Cursor	~/.cursor/skills/bugproof/
Gemini CLI	~/.gemini/skills/bugproof/
GitHub Copilot	.github/skills/bugproof/

该技能遵循开放的 Agent Skills 规范——任何支持该标准的 Agent 都可以使用。

---

60 秒快速开始

# 1. Reproduce a failure
$ npm test
FAIL  Tests failed because Redis was unreachable.

# 2. Capture it
$ bugproof capture -- npm test
  ✔  Artifact captured!
  Path        ./bug_1778049738215.bug
  Files       42 files (28.4 KB)
  Fingerprint sha256:c8b3...

# 3. Share the file (Slack, email, gist, attachment...)

# 4. Anyone replays it on their machine
$ bugproof replay bug_1778049738215.bug
  ✔  REPRODUCTION CONFIRMED
  Exit code    exit 1 (match)
  Verdict      Reproduction confirmed (exact fingerprint match)

可选流程：

$ bugproof inspect bug.bug        # peek at the contents
$ bugproof diff old.bug new.bug   # what changed between two captures
$ bugproof share bug.bug          # publish as a GitHub Gist

命令

BugProof 提供 14 条命令。每条命令都支持 --help 和 --json，以输出机器可读的信息。

命令	用途
bugproof capture	运行命令、记录所有内容，并生成 .bug 工件
bugproof replay	重新执行工件，并与预期指纹进行比较
bugproof watch	透明地包装命令——仅在命令失败时捕获
bugproof inspect	显示工件内容（清单、命令、指纹、文件）
bugproof diff	并排比较两个工件
bugproof verify	验证 .bug 上的 Ed25519 签名（独立运行）
bugproof keygen	生成用于签署工件的 Ed25519 密钥对
bugproof share	将工件发布为 GitHub Gist
bugproof mcp	启动 MCP 服务以集成 AI Agent
bugproof init	创建 .bugproofrc 配置文件
bugproof prune	垃圾回收孤立的沙盒临时目录
bugproof clean	从当前目录中删除所有 .bug 工件
bugproof pull	从 GitHub Gist 下载共享的 .bug 工件
bugproof doctor	检查操作系统对沙盒隔离功能的支持情况
bugproof help	获取任意命令的帮助信息

---

bugproof capture [command...]

端到端运行命令，并将失败打包为 <name>.bug。

bugproof capture -- npm test
bugproof capture -n auth-crash -d "Login fails on expired session" -- node server.js
bugproof capture -o ./bugs/ -- npm test
bugproof capture --include-untracked -- python app.py
bugproof capture -x "*.log" -x "node_modules/**" -- go test ./...
bugproof capture --timeout 600000 -- java -cp . Main
bugproof capture --include-compiled -- mvn test    # force include .class/.jar files
bugproof capture --sign --signer "[email protected]" -- ./run.sh
bugproof capture --json -- node script.js

标志	描述
-n, --name <name>	工件名称（将成为 <name>.bug）
-d, --description <desc>	嵌入清单中的人类可读描述
-o, --output <dir>	输出目录（默认：当前目录；遵循 .bugproofrc 中的 outputDir）
-x, --exclude <pattern>	按 glob 排除文件（可重复指定）
--include-untracked	也打包未跟踪文件（git ls-files -o）
--include-compiled	强制包含编译产物（.class、.jar、.pyc 等）——默认自动检测
--timeout <ms>	N 毫秒后终止命令（默认 300000）
--skip-secrets	不扫描环境变量中的机密（跳过确认提示）
--sign [key]	使用默认密钥、指定名称的密钥或 .key 文件路径签名
--signer <id>	嵌入签名者身份（电子邮件、gist URL 等）
--json	输出结构化 JSON

默认行为： 未指定 -n 时，工件命名为 bug_<timestamp>.bug。如果配置了 .bugproofrc 中的 nameTemplate，则使用该模板。未指定 -o 时，工件保存到当前目录。

---

bugproof replay <artifact>

重新执行捕获的工件并比较结果。

bugproof replay bug.bug
bugproof replay bug.bug --sandbox isolated
bugproof replay bug.bug --self-heal
bugproof replay bug.bug --verify-signature
bugproof replay bug.bug --source-dir .
bugproof replay bug.bug --json

标志	描述
--sandbox <level>	workspace（默认）、isolated 或 full
--self-heal	自动安装缺失的 npm/pip 依赖并重试（最多 3 轮）
--verify-signature	要求有效的 Ed25519 签名；若缺失或无效则退出码为 2
--source-dir <dir>	覆盖 git 操作的源目录（使用当前目录中的仓库，而非捕获时的路径）
--json	输出结构化 JSON

回放隔离： 回放始终在隔离的临时目录中运行。文件来源为以下之一：(1) 捕获时提交对应的 git worktree/克隆仓库；(2) 当前目录中的 git 仓库（如果原始路径无法访问）；或 (3) 工件中打包的 files/ 快照。绝不会从当前目录读取源文件。

---

bugproof keygen / verify — 加密来源验证

使用 Ed25519（RFC 8032）为工件签名。基于 Node 内置的 crypto 实现，无需外部依赖。

# One-time: create your signing key
bugproof keygen
# → writes default.pub / default.key to ~/.bugproof/keys/

# Capture with a signature
bugproof capture --sign --signer "[email protected]" -- npm test

# Verify a received artifact
bugproof verify bug.bug
  ✔  SIGNATURE VALID
  Algorithm   ed25519
  Fingerprint 179721ef7e63f6b3
  Signed at   2026-05-10T22:09:30Z
  Signer      [email protected]

# Enforce signatures at replay time
bugproof replay --verify-signature bug.bug

签名涵盖清单的规范化哈希、失败指纹，以及捆绑包中每个文件的 SHA-256。篡改源代码、输出、退出码或元数据都会使签名失效。

注意： 身份/PKI 有意不在此功能的范围内。信任通过将内嵌公钥指纹与已知指纹进行比较来建立（例如固定 gist、团队 wiki、密钥服务器等）。

---

bugproof watch [command...]

透明包装器。照常运行命令；仅在失败时捕获。可直接替代任何原本需要手动运行的命令。

bugproof watch -- npm test
bugproof watch -o ./bugs -- python app.py
bugproof watch --always -- node script.js    # capture even on success

---

bugproof inspect <artifact> / diff <a> <b>

bugproof inspect bug.bug                          # manifest, fingerprint, file list, env schema
bugproof diff captured-v1.bug captured-v2.bug     # what changed between two captures

---

bugproof share <artifact>

将工件发布为 GitHub Gist。支持企业网络环境下的 HTTPS_PROXY / HTTP_PROXY。

bugproof share bug.bug
bugproof share --public bug.bug

需要具有 gist 权限范围的 GITHUB_TOKEN（或 BUGPROOF_GITHUB_TOKEN）。

---

bugproof init / prune / doctor

bugproof init       # scaffold .bugproofrc in the current directory
bugproof prune      # garbage-collect orphan BugBox temp directories
bugproof doctor     # check OS support for sandbox isolation (namespaces, Job Objects, Seatbelt)

---

配置（.bugproofrc）

由 bugproof init 生成。所有字段均为可选。

{
  "exclude": ["node_modules/**", "dist/**", "*.bug"],
  "outputDir": ".",
  "timeout": 300000,
  "skipSecrets": false,
  "includeUntracked": false
}

---

智能源文件策略

即使代码库很庞大，BugProof 也能保持工件体积小巧：

策略	适用情况	打包内容	典型大小
git-full	干净的 git 仓库	仅提交引用	~2 KB
git-patch	有未提交更改的 git 仓库	提交引用 + diff 补丁	~5 KB
git-files	强制模式 / 有未跟踪文件	所有已跟踪和未跟踪文件	不定
full-copy	非 git 仓库	完整代码库（不含 node_modules 等）	~10–100 MB

强烈建议使用 Git，但并非必需。

编译型语言支持

BugProof 会自动检测编译型语言，并自动打包构建产物：

语言	源文件	编译产物	自动包含？
Java	.java	.class、.jar、.war、.ear	✅ 是（来自 target/、build/、out/）
Python	.py	.pyc、.pyo	✅ 是（来自 __pycache__/）
Go	.go	bin/、编译后的二进制文件	✅ 是（来自 bin/、dist/）
Rust	.rs	target/ 二进制文件	✅ 是（来自 target/）
.NET/C#	.cs、.csproj	.dll、.exe	✅ 是（来自 bin/、obj/）
WebAssembly	—	.wasm	✅ 是（来自任何构建目录）
Node 原生模块	—	.node	✅ 是（来自 build/、dist/）
C/C++	.c、.cpp	.o、.obj、.exe	❌ 否（与平台相关，仅包含源文件）

工作原理： 当 BugProof 检测到编译型语言项目（通过 pom.xml、go.mod、Cargo.toml 等），并在标准构建目录中找到编译产物时，会自动将其包含在内。无需设置标志。

使用 --include-compiled 可强制包含编译产物，即使自动检测未能发现；也可用于处理特殊情况。

---

沙箱与隔离模型

BugProof 在分层沙箱中运行重放的命令——基于原生操作系统原语构建，提供类似 Docker 的隔离。

层	Linux	Windows	macOS
进程	PID 命名空间（unshare --pid）	Job Objects	sandbox-exec
网络	网络命名空间（unshare --net）	netsh advfirewall 规则	(deny network*)
文件系统	fuse-overlayfs（只读源文件 + 可写覆盖层）	隔离的临时目录	受限的写入路径
资源限制	cgroups v2（内存、CPU、PIDs）	Job Object 限制	—
环境清理	移除 LD_PRELOAD、NODE_OPTIONS、…	同左	同左
临时目录	私有 /tmp	私有 %TEMP%	私有 /tmp

可通过 --sandbox 指定三个沙箱级别：

• workspace （默认） — 最低限度的隔离，速度快。适用于可信的产物。
• isolated — 命名空间 + 临时目录隔离。建议用于不可信的产物。
• full — 启用所有层，包括网络屏蔽和资源限制。

注意： 在 Windows 上，isolated 和 full 只能提供尽力而为的加固，无法达到虚拟机级别的隔离。对于来自完全不可信来源的产物，请在专用虚拟机中重放。

---

环境快照

记录捕获时的运行时版本，并在重放时进行差异比较：

  Environment Mismatches
    •  node version mismatch: captured 18.0.0, current 22.1.0
    ✘  python 3.11.0 was available at capture but is not installed now.

跟踪：Node.js、Python、Ruby、Go、Rust、Java、npm、pip、操作系统平台、架构。

---

跨平台重放

捕获 ↘ / 重放 ↗	Windows	Linux	macOS
Windows	✅	✅	✅
Linux	✅	✅	✅
macOS	✅	✅	✅

转换层会规范化命令（python3 ↔ python、gradlew ↔ gradlew.bat、make ↔ mingw32-make、Shell 路径）。架构不匹配（x64 ↔ arm64）时会发出明确警告，并提供 Rosetta/转换建议。

---

安全模型

区域	机制
密钥 — 已知模式	捕获时会对匹配 *_TOKEN、*_KEY、*_SECRET 以及 AWS/GCP/Stripe 格式的环境变量进行脱敏
密钥 — 未知值	香农熵分析会标记高熵值（≥4.5 位/字符），即使键名看起来无害也不例外
stdout/stderr 清理	主动式正则流清理器会从捕获的输出中删除邮箱、IP、信用卡号、GitHub 令牌和 Stripe 密钥
路径遍历	每次文件复制都会经过验证，确保不会超出制品和项目的边界
脚本注入	沙箱命令通过参数数组启动，绝不使用 Shell 字符串
来源验证	Ed25519 签名覆盖清单、指纹和每个文件的 SHA-256。验证在本地进行，不会发起网络请求
沙箱环境清理	回放前会移除 LD_PRELOAD、NODE_OPTIONS、DYLD_* 及类似的运行时劫持向量
加密	仅使用 Node 原生 crypto，不依赖外部加密库。不进行遥测。不回传数据

只有在你自行审核过环境后，才使用 --skip-secrets。

---

文件关联

Windows

在 HKCU\Software\Classes\.bug 下注册为 BugProof.Artifact，打开命令为 node <package>/dist/cli.js replay "%1"。

Linux

注册 MIME 类型 application/x-bugproof、bugproof.desktop 处理程序，以及用户级图标条目 ~/.local/share/icons/hicolor/。

macOS

通过捆绑脚本尽力设置。如果 Finder 关联未生效，请手动重新运行：

bash scripts/bugproof-file-association-macos.sh

---

架构

bugproof/
├── src/
│   ├── capture/          # Execution + env snapshot + language detection + packaging
│   ├── replay/           # Restore + sandbox orchestration + verdict + self-heal
│   ├── sandbox/          # OS-specific isolation (filesystem, network, process)
│   ├── share/            # Gist publisher
│   ├── diff/             # Two-artifact diff engine
│   ├── config/           # .bugproofrc loader and validation
│   ├── utils/            # signing, secrets, fingerprint, dependencies, security, …
│   └── cli.ts            # Commander entrypoint (14 commands)
├── tests/                # 40 suites / 502 tests (Jest)
├── scripts/              # Postinstall, e2e matrix, file-association helpers
└── .github/workflows/    # CI/CD (tri-platform matrix, signed npm publish)

模块	职责
capture/engine.ts	执行用户的命令，将输出流写入临时文件，并记录 stdout/stderr/退出状态
capture/packager.ts	打包为 .bug zip；可选使用 Ed25519 签名
capture/language-support.ts	检测 Node/Python/Java/Go/Rust/.NET/C++/Kotlin，并自动检测编译制品
capture/env-snapshot.ts	记录运行时版本，以便回放时比较环境差异
capture/source-strategy.ts	智能选择源代码：git-full、git-patch、stacktrace、minimal
replay/engine.ts	在沙箱中重现命令
replay/self-heal.ts	检测缺失的依赖，在沙箱中安装并重试
replay/verdict.ts	比较指纹和规范化后的错误模式
replay/hints.ts	根据捕获的输出生成可操作的调试提示
sandbox/bugbox.ts	协调各操作系统的隔离层
sandbox/cross-platform.ts	在 Windows/Linux/macOS 之间转换命令
utils/signing.ts	Ed25519 签名/验证/规范化载荷构建器
utils/secrets.ts	基于模式和熵的环境变量扫描、PII 流清理器
utils/fingerprint.ts	确定性故障指纹生成、路径规范化
utils/dependencies.ts	从 stderr 中检测缺失的 npm/pip/系统依赖
utils/ui.ts	终端 UI：颜色、旋转指示器、进度条、摘要框
diff/engine.ts	并排比较制品
share/gist.ts	支持代理的 GitHub Gist 发布器
config/loader.ts	加载并验证 .bugproofrc 配置

---

贡献

欢迎提交 PR。请参阅 CONTRIBUTING.md，了解指南、开发环境设置和测试矩阵要求。每个 PR 都会运行完整的三平台 CI；新增行为时请添加测试。

---

许可证

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0）许可。

使用场景	是否允许？
个人及非商业用途	✅ 免费，无限制
Fork 及修改	✅ 必须以 AGPL-3.0 发布，并提供源代码
作为网络服务（SaaS）运行	✅ 必须公开修改后的源代码
商业／专有用途	❌ 需要单独的商业许可证

---

由 sidinsearch 用 ❤️ 制作  ·  Copyright © 2026 sidinsearch  ·  AGPL-3.0 许可证