shanemhamilton/bugsweep

# bugsweep — 针对代码库的 AI Bug 查找与自动修复 [](https://github.com/shanemhamilton/bugsweep/releases) [](LICENSE) [](https://claude.ai/code) [](https://github.com/openai/codex) [](#configure) 一个 Claude Code 和 Codex 技能，用于查找并修复代码库中的 bug —— 足够安全， 可以无人值守运行，甚至在夜间完全自主运行。它会寻找真实的运行时 bug （安全漏洞、逻辑错误、竞态条件、错误的错误处理、数据完整性 问题），并且在你允许的情况下，会在一次性分支上修复它们，如果 修复破坏了任何内容，则会自动回滚。 它做四件事，使其在真实的大型代码库中非常有效： - **整个仓库的上下文。** 在寻找之前，它会构建一个关于你的 架构的精炼模型 —— 信任边界、敏感接收点以及进入它们的调用链 —— 这样它就可以 捕获*大型*的跨文件 bug（例如，在一条通向 数据库写入的路径上缺少授权检查），而不仅仅是局部 bug。 - **感知技术栈的研究。** 它检测你的语言/框架，并使用为 这类代码常见的 bug 精选库来为自身做准备（默认关闭，可选择开启针对特定版本公告的 网络研究）。 - **对抗性审查。** 每一个发现都要经历一道关卡 —— Hunter 找到它，Skeptic 试图反驳它，中立的 Referee 做出最终裁决 —— 因此误报 很少能进入修复阶段。 - **上下文连续性。** 所有进度都会写入磁盘，因此在长时间运行中，它可以重置 工作记忆并继续运行，而不会丢失发现、修复或覆盖率。 ## 需要理解的一件事 **任何核心运行的最坏情况就是一个你删除的分支。** bugsweep 在 hunt/fix 循环期间永远不会在你的 真实分支上工作，永远不会推送到任何地方，永远不会合并，并且永远不会 删除文件。它切出一个新的 `bugsweep/` 分支，在那里进行修复，每次修复作为一个 提交，并在每次修复后重新运行你的测试 —— 自动撤销任何破坏了 某些东西的修复。你审查分支并决定保留什么。你永远是 合并把关人。 危险的、不可逆转的操作（分支、暂存你的工作、回滚）由 `scripts/` 中的简短 shell 脚本完成，你可以在几分钟内读完它们 —— 而不是由 AI 的判断来完成。这就是使其对于长时间无人值守运行值得信赖的原因。 ## 工作原理 ### 完整运行 pipeline ``` flowchart TD A(["/bugsweep invoked"]) --> B subgraph scripts ["⚙️ Shell scripts — deterministic, auditable"] B["preflight.sh\ncut bugsweep/<timestamp> branch\nstash uncommitted work\nwrite RUN_DIR + ledger"] C["run_checks.sh baseline\nrecord test / build / lint state"] L["run_checks.sh verify\ndiff against baseline"] Q["guard.sh\ncheck iteration / time / fix caps"] FIN["finalize.sh\nrestore original branch\npop stash\npersist audit coverage\nwrite handoff JSON"] end subgraph ai ["🤖 AI phases — reasoning only, no git ops"] D["context-build\nbuild whole-repo model\narchitecture · trust boundaries\nsensitive sinks · call chains"] E["research\nprime with stack-specific\nanti-pattern catalogs"] F["hunt\nbatch through files\nHunter generates candidates"] G["challenge\nSkeptic tries to disprove\neach candidate"] H["referee\nneutral final verdict"] K["fix.md\nsurgical minimal patch\none commit per confirmed bug"] end B --> C --> D --> E --> F --> G --> H H --> |detect-only| RPT["📄 write report\nno code changes"] H --> |fix / approve / autonomous| K K --> L L --> |pass| N["commit fix\nappend to ledger"] L --> |fail| O["auto-revert\nquarantine bug"] N --> Q O --> Q RPT --> FIN Q --> |CONTINUE| F Q --> |STOP| FIN FIN --> HANDOFF["post-finalize handoff\nbranch preserved\none compound next action"] HANDOFF --> DECIDE{"User replies do it?"} DECIDE --> |"No"| R(["Review manually\ngit diff main..bugsweep/<timestamp>"]) DECIDE --> |"Yes"| LAND["land preserved branch\nre-run proof on target\npush if safe\nsmoke + remote read-back\ncleanup merged branch"] ``` ### 对抗性审查 —— 为什么 bugsweep 的误报率很低 每一个候选发现都必须经过一个三角色关卡的考验，然后才能被修复或报告。模型永远不会评估自己的发现。 ``` flowchart LR H["🔍 **Hunter**\n`hunt.md`\nfinds candidate bug\nwith supporting evidence"] S["🛡️ **Skeptic**\n`challenge.md`\ntries to disprove:\nalternate explanations\ncode paths that prevent the bug\ntest coverage that catches it"] R["⚖️ **Referee**\n`referee.md`\nneutral final verdict\nbased on both sides"] H --> S --> R R --> |"Confirmed\n(high confidence)"| FIX["Promoted to fix queue"] R --> |"Dismissed or uncertain"| DISC["Dropped — not fixed\nnot reported"] ``` ### 覆盖率优先状态 —— bugsweep 如何在旧的、未更改的代码中查找 bug bugsweep 不是 diff 扫描器。仓库中的每个文件始终都在范围内。跨运行状态允许它跟踪哪些文件已经在当前目录版本下被审查过，并优先处理尚未审查的文件。 ``` flowchart TD subgraph state ["📁 .bugsweep/state/ (persists across runs)"] AL["audit-log.jsonl\nper-file: last-audited run, catalog version"] RJ["risk.jsonl\nrisk scores per file"] MJ["meta.json\ncurrent catalog version"] end P["preflight.sh\n→ state.sh prime"] -->|reads state| PC["prior-coverage.json\nbatch priority plan"] PC --> T1["**Tier 1 — Critical**\nnever-audited\nstale (catalog bumped)\ncontent-changed\nhigh-risk\nsink-bearing"] PC --> T2["**Tier 2 — Re-confirm**\nrecently audited, fresh"] T1 --> HUNT["hunt loop"] T2 --> HUNT HUNT --> FIN["finalize.sh\n→ state.sh persist\nupdate audit-log + risk\nwrite handoff JSON"] FIN -->|next run| P ``` ## 安装 **一条命令 —— 适用于 Claude Code、Codex 或两者：** ``` curl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash ``` 该脚本会自动检测你安装了哪些 AI 工具（`~/.claude` → Claude Code， `~/.codex` → Codex）并分别设置它们。重新运行它会进行就地更新。 **强制指定特定工具：** ``` # 仅 Claude Code curl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --claude # 仅 Codex curl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --codex # 两者皆可 curl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --all ``` **固定到特定发布版本**（而不是跟踪最新的 `main`）： ``` curl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --version v0.1.0 ``` 使用 `--version` 重新运行安装程序将检出该发布标签；不带参数重新运行 它将带你返回最新的 `main`。请参阅[发布](https://github.com/shanemhamilton/bugsweep/releases) 和 [CHANGELOG](CHANGELOG.md)。 **手动安装（如果你倾向于先检查）：** ``` git clone https://github.com/shanemhamilton/bugsweep.git bash bugsweep/install.sh # then delete the clone — it installs to ~/.claude or ~/.codex ``` **安装程序的作用：** - *Claude Code* — 克隆到 `~/.claude/skills/bugsweep/`。Claude Code 会在那里 自动发现技能；无需配置。 - *Codex* — 克隆到 `~/.codex/skills/bugsweep/` 并向 `~/.codex/instructions.md` 追加一个存根，以便 Codex 知道脚本存放在哪里。 ## 使用 在你的项目中打开 Claude Code（或启动 Codex）并输入以下命令之一： | 命令 | 作用 | | --- | --- | | `/bugsweep` | 查找 bug 并编写报告。**不进行任何更改。** 从这里开始。 | | `/bugsweep --approve` | 查找 + 修复，但在每次修复前都会询问你。使用此命令来建立信任。 | | `/bugsweep --autonomous` | 在循环中查找 + 修复，直到干净或达到限制为止。即夜间模式。 | | `/bugsweep src/api` | 将扫描限制在一个文件夹或文件中。 | | `/bugsweep --severity high` | 仅修复高/严重级别的 bug；报告其余的 bug。 | 推荐路径：运行一次 `/bugsweep` 看看它能找到什么，然后运行 `/bugsweep --approve` 观察它是如何修复的，最后在你信任它后运行 `/bugsweep --autonomous`。 ## 运行后 它会告诉你分支名称以及如何审查： ``` git diff ..bugsweep/ ``` 它还会写入 `/post-finalize-handoff.json`，这是一个机器可读的交接文件，包含 保留的分支、报告路径、修复提交、质量门禁、冒烟检查、推送策略、 清理策略、删除证明以及最终的回读命令。 对于 `/bugsweep --autonomous`，推荐的下一步特意设为一个复合批准命令： 这并没有削弱信任契约。核心运行仍然在 finalize（完成）阶段停止，并 将修复滞留在 `bugsweep/` 上，直到你批准继续。 批准的后续操作使用交接 JSON 和可选的清理脚本，因此父级 agent 在合并后不需要再次询问。 只有在证明该分支包含在目标分支（`git merge-base --is-ancestor `）中之后，才允许 删除分支。如果该分支在一个 链接的 worktree 中被检出，那么只有当它是干净的时，清理操作才会移除该 worktree：没有未暂存的 更改、没有已暂存的更改，也没有未跟踪的文件。脏的 worktree 和未合并的分支 将被保留。 手动审查仍然以相同的方式进行：使用 cherry-pick 或 merge 保留你喜欢的内容，或者 如果你认为该分支不值得保留，则明确丢弃它。你的原始分支和 未提交的工作完全与你离开时一样。 ### 可重复的、无人值守的运行 按计划运行 bugsweep 会使其随着时间的推移自行挖掘得更深 —— 覆盖率优先的 跨运行状态意味着每次运行都会优先处理尚未审计的文件。唯一 累积的内容是每次运行产生的一个 `bugsweep/` 分支，因为 bugsweep 从不合并 或删除（你是合并把关人）。为了让计划的运行干净地结束，可选的 配套脚本 `scripts/bugsweep-cleanup.sh` 在 finalize *之后*且 在批准之后自动化了该门禁：它将经过验证的修复分支合并到你选择的分支中，仅删除 被证明包含在该目标中的分支，并保留脏的 worktree 或未合并的 分支 —— 仅使用纯 git，在核心 hunt/fix 循环之外。请参阅 [`references/autonomous-maintenance.md`](references/autonomous-maintenance.md) 获取 可复制粘贴的提示词、设置和调度说明。 ## 配置 编辑 `config/bugsweep.config.json` 以设置限制（它运行多长时间、进行多少次修复）， 排除文件夹，或者如果自动检测遗漏了它们，则指定你的测试/构建命令。请参阅 `references/tuning.md`。 ## 常见问题解答 **bugsweep 与 Snyk、CodeQL、SonarQube 或 Dependabot 有何不同？** 这些主要是模式/diff 扫描器和依赖审计工具。bugsweep 是一个 *agentic*（智能体式） 审查者：它构建整个仓库的架构模型并推断行为，因此它 能捕获模式匹配器遗漏的跨文件逻辑 bug（比如在一条通向 数据库写入的路径上缺少授权检查）。它补充了这些工具而不是 取代它们 —— 并且它可以修复它发现的问题，而不仅仅是标记它们。 **它支持哪些语言和框架？** Claude Code 或 Codex 可以读取的任何语言。它为 常见的技术栈（JavaScript/TypeScript、Python、Go、Rust、Swift/iOS 等）提供了精选的反模式目录，并 自动检测你的技术栈以准备寻找工作。 **在生产代码库上运行安全吗？** 是的 —— 这正是设计的核心。bugsweep 从不在你的分支上工作，从不推送，从不 合并，从不删除文件。它切出一个一次性的 `bugsweep/` 分支，并且 不可逆的 git 操作是你可以在几分钟内审计的简短 shell 脚本。任何 运行的的最坏情况都是一个你删除的分支。 **bugsweep 会把我的代码发送到任何地方吗？** 没有第三方服务，没有遥测，也没有网络调用 —— 除非你明确选择 加入针对特定版本公告的受限网络研究（默认关闭）。你的代码 只会发送到你已经在使用的 AI 工具。 **它可以在无人值守或 CI 环境下运行吗？** 是的。`/bugsweep --autonomous` 会运行一个查找和修复循环，直到代码库干净或 达到配置的限制（时间、迭代或修复计数），在每次修复后重新运行你的测试。状态持久化到磁盘，因此长时间的运行可以度过上下文重置。落地、推送、 冒烟检查、远程回读和分支清理通过显式的 finalize 后续操作发生，因此合并门禁保持可见。 **它也适用于 OpenAI Codex，还是仅适用于 Claude Code？** 两者都可以。安装程序会设置你拥有的任何一个（`--claude`、`--codex` 或 `--all`）。 ## 内部结构 - `SKILL.md` — Claude 遵循的指令。 - `scripts/` — 确定性安全 + 状态层：`preflight`（分支/暂存设置）， `run_checks`（测试/构建），`guard`（停止条件），`session`（连续性锚点）， `finalize`（安全返回加上 `post-finalize-handoff.json`）。加上两个*可选的*、 用户拥有的用于计划运行的配套脚本（在核心 hunt/fix 循环之外）： `bugsweep-prepare.sh`（如果树是脏的，它会推迟到一个活动的会话，或者提交 真正闲置的工作以关闭树 —— 从不挂起，从不丢弃）和 `bugsweep-cleanup.sh`（运行后的合并门禁；唯一一个执行合并或删除的脚本， 并且仅在你选择运行它时执行）。 - `prompts/` — 各个阶段，保持分离以便 AI 从不盲目批准自己的发现： `context-build`（整个仓库的模型），`research`（反模式准备），`hunt`（局部 + 架构视角），`challenge`（Skeptic），`referee`（最终仲裁者），`fix`。 - `references/` — 安全原理、无测试 playbook、调整说明、 上下文/连续性模型，以及 `antipatterns/`（按技术栈精选的目录）。 - `config/bugsweep.config.json` — 你的设置（上限、排除项、命令，以及 对抗/研究/会话开关）。 没有第三方依赖，没有网络调用（除非你选择加入网络研究），没有 遥测。在信任它之前，请阅读 `scripts/` 和 `references/safety-rationale.md` —— 这才是拥有它的全部意义所在。

标签：AI辅助开发, Claude Code, Codex, Cutter, Homebrew安装, 代码安全审计, 模块化设计, 自动化修复, 错误基检测, 静态代码分析