Bug Hunter
面向 AI 编程代理的对抗式代码审计技能：多角色流水线找出安全漏洞、逻辑错误和运行时缺陷，默认只扫描，修复需显式授权。
证据显示极少权限与明确确认模型设计良好：默认仅扫描、编辑/提交需显式批准、--autonomous/--auto-commit 被明确警示、fail-closed 边界与 SECUEITY.md 中 Fixer 范围/锁/worktree 设计相印证，外部效果与最小权限可得高分。但依赖安全仅凭 devDependencies（ajv、esbuild）与 CI 描述推断，未见 lockfile、CVE 审计或供应链验证证据，扣至 1；敏感数据处理仅由 SECURITY.md 的'环境变量/密钥不外泄'原则间接支撑，未见实现；回滚仅在 fix-report 字段中被提及，未见机制描述；发布者未经验证，归因以一致但未核实的 URL 为限，扣至 2。
自洽性高：README、package.（3.2.0）、CI 工作流（Node 22/24 矩阵、测试、基准门禁、preflight）相互一致，fail-closed 与 schema 校验贯穿描述，扣分点少；依赖可用性方面 Node>=22、pnpm 固定版本、frozen-lockfile 可见，但 doctor 自检与运行时依赖解析只有描述未见源码；失败消息仅以'失败即为失败阶段/不得伪装成功'的政策性语言呈现，具体错误消息与恢复指引未在证据文件中出现，扣至 2。
受众、能力边界与触发精确度证据充分：明确排除风格类问题、将未定结论归为 MANUAL_REVIEW/unreviewed、多代理安装目标表、标志到工作流的一一对应、扫描/循环/计划/修复各模式区分清晰，可得满分；环境适配方面列出八类代理与 Node 版本，但各代理环境差异（上下文预算、权限模式差异）仅有概括性说明，未见逐环境验证细节，扣至 2。
信息架构与安装说明出色：TL;DR、代理表、工作流表、阶段表、文档链接层次分明，npx/npm 双通道安装与显式 --agent 建议具体可执行；许可证 MIT 全文在案可得满分；已知局限声明诚实（基准数字仅验证捆绑夹具、无零误报承诺）。但命名稳定性存疑：README 描述 v3.2.0 与历史版本文档（hero 图固定旧 commit、'最接近的标志模式'等措辞）显示界面在演进；examples/FAQ 主要是指向未提供文件的链接（usage-guide、troubleshooting 均不在证据内）；CHANGELOG.md 虽列入打包清单但未提供内容；维护责任仅由 SECURITY.md 响应时限与 CI 门禁间接体现，未见治理/维护者承诺，均扣至 2。
输出可用性强：canonical JSON 工件 + report.md 双层、确认/驳回/待审/未审四类分离、bug ID 与计数一致性校验均有描述，可直接服务 CI/CD，可得满分；边际价值方面，Hunter/Skeptic/Referee 对抗结构与误报惩罚激励机制设计有辨识度，但唯一量化证据是自报的捆绑夹具指标（precision 1.00 等），明确声明非独立基准，扣至 2；成本收益方面给出 token 中位数与 p95 时延，但未提供与替代工具的成本对比，扣至 2。
事实与推断分离做得好：README 明确区分'验证捆绑夹具'与'独立基准'、承认 Context Hub 不可用时不得虚构保证、MANUAL_REVIEW 不伪装为干净结果，可得满分；声称可追溯性方面，各阶段到 schema 工件的映射清晰，但引用的 docs/world-class-protocol.md、SKILL.md、实际脚本源码均不在证据内，无法静态核实核心机制，扣至 2；跨源印证薄弱：性能与精度数字全部来自项目自身文件与 CI 门禁，无第三方测试、审计或独立基准，扣至 1。
- 静态审查未执行任何扫描或安装；所有性能与精度数字（precision 1.00 等）为项目自报的捆绑夹具结果，不应视为独立基准。
- 核心机制（SKILL.md、提示词、脚本源码、CHANGELOG、usage-guide）不在本次证据内，fail-closed、Fixer 范围与回滚等安全声明无法从源码核实。
- 依赖安全证据薄弱：未提供 lockfile 内容或依赖 CVE 审计结果，安装时建议用 --path 限定到单仓库并先在隔离环境审查安装内容。
- 避免使用 --autonomous 或 --auto-commit，除非明确愿意授予无人值守写权限；首次运行应使用文档推荐的仅扫描模式。
- 发布者未经验证，npm 包与 GitHub 源可能不同步（README 自述 npm 可能滞后 main），生产使用前应锁定具体 commit 并核对差异。
这个 Agent 能做什么，适合哪些场景？
Bug Hunter 是一个可安装到多种 AI 编程代理（Claude Code、Codex、Cursor、GitHub Copilot、Kiro、Windsurf、OpenCode、Factory Droid CLI 等）的代码审计技能。其流水线包括确定性风险分诊、架构侦察、假设驱动的检索，以及三个对抗角色：Hunter 提出证据支撑的缺陷主张，Skeptic 尝试反驳每一条主张，Referee 给出 REAL_BUG、NOT_A_BUG 或 MANUAL_REVIEW 的最终裁决。默认运行只扫描、单轮执行，任何源码修改、自主修复和提交都需要单独的显式权限。所有阶段产出经 schema 校验的 JSON 工件，写入 .bug-hunter/ 目录，供 CI/CD、安全看板和 PR 门禁消费。v3.2.0 引入了基于精确率、召回率、F1、校准误差和稳定性的可度量质量门禁，以及 fast/balanced/assurance 自适应执行档位。修复流程采用金丝雀优先发布、批次间验证、熔断器和回滚机制，修复分支在专用 fix 分支上进行。
通过你已安装的编程代理调用安装后的技能（例如发送 /bug-hunter src/auth），而非在 shell 中直接运行扫描。流程为：scripts/triage.cjs 先做无模型消耗的确定性风险分诊并选定扫描范围；Recon 梳理技术栈、架构与信任边界；Hunter 读取生产代码，查找条件错误、越界、竞态、注入、XSS、SSRF、路径穿越、资源泄漏等可触达缺陷，主张须包含源码位置、证据和运行时触发条件；Skeptic 依据 14 条硬性排除规则反驳主张并追踪防御路径；Referee 独立复核并给出裁决，Critical/High 安全发现附带 STRIDE 类别、CWE 编号和 CVSS 3.1 向量；混合验证运行 argv 限定测试、类型检查、静态检查、模糊检查，失败即整体失败。可选标志扩展能力：--deps 做 npm/pnpm/Yarn/Bun 锁文件的 CVE 扫描与可达性判定，--threat-model 生成 STRIDE 威胁模型，--pr/--pr-security 审查 PR 与变更代码。确认的缺陷经 fix-strategy. 分级为 safe-autofix、manual-review 等类别，--plan 生成修复计划，--fix --approve 在授权范围内于专用分支执行金丝雀修复、批次验证与回滚，产出 fix-report.。
- 需要在合并前对整个仓库做一次只读安全与逻辑审计、又不想让 AI 动代码的开发团队，直接运行 /bug-hunter 即可。
- 负责 PR 审查的工程师，用 --pr 或 --pr-security 将审计范围缩小到即将合并的变更，并结合 STRIDE 和依赖证据。
- 维护 JavaScript/TypeScript 项目的团队，用 --deps 扫描 npm、pnpm、Yarn 或 Bun 锁文件中的高危 CVE 并判定可达性。
- 上线前需要 STRIDE 威胁模型的安全负责人，用 --threat-model 生成含信任边界、资产与威胁清单的 .bug-hunter/threat-model.md。
- 希望在人工审批下自动修复已确认缺陷的开发者，用 --fix --approve 在专用 fix 分支上获得带验证与回滚的修复流程。
- 想把审计结果接入 CI/CD 门禁或安全看板的团队，消费 .bug-hunter/scan-report. 等机器可读工件。
这个 Agent 有哪些优点和局限？
- Hunter/Skeptic/Referee 三角色对抗结构，配合证据硬性要求和 Skeptic 的 14 条排除规则，系统性降低误报，未定结论显式标记为 MANUAL_REVIEW 而非静默放过。
- 默认 scan-only 且修复、提交各自独立授权，配合 fix 分支、金丝雀发布、批次验证、熔断器和回滚，权限模型精细且失败即关闭（fail-closed）。
- 所有阶段产出 schema 校验的 JSON 工件（scan-report.、fix-plan. 等），可直接接入 CI/CD、PR 门禁和安全看板。
- 一个技能覆盖 14 种语言的源码审计，外加 STRIDE 威胁建模、npm/pnpm/Yarn/Bun 依赖 CVE 扫描和 PR 变更审查，并可安装到八种以上编程代理。
- 附带确定性回归基准夹具与质量门禁（精确率、召回率、F1、校准、稳定性指标），可通过 pnpm quality:world-class 验证。
- 依赖一个已安装的文件型编程代理作为运行时，不是独立 CLI 扫描器；扫描通过代理启动而非 bug-hunter scan 命令。
- 依赖审计仅支持 JavaScript/TypeScript（npm、pnpm、Yarn、Bun 锁文件）；Python、Go、Rust 返回 scanner-unsupported，不会给出清洁结论。
- 需要 Node.js 22+，且较大型扫描会消耗可观的模型 token（基准夹具中每个真阳性中位数约 12,090 token），高频使用有成本。
- 自动回滚依赖 commit 检查点；无提交权限时可能需要手工恢复仓库状态，且行级范围、符号链接等合规性不能在补丁后独立验证。
- 自主修复相关标志（--autonomous、--auto-commit）授权边界敏感，官方建议在敏感仓库先阅读 SECURITY.md；误用可能扩大写入权限。
如何安装或部署这个 Agent？
要求 Node.js 22 或更新版本和一个受支持的文件型编程代理。安装到当前 GitHub 源（与文档一致）：npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex，其中 --agent 可替换为 claude-code、codex、cursor、copilot、kiro、windsurf、opencode、droid 或 agents。然后运行 doctor 验证：npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex。若要安装最新发布的 npm 版本（可能落后于 GitHub main）：npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter install --agent codex。安装多个代理时务必显式传 --agent。若安装时代理处于打开状态，需重启代理。卸载需手动完成。
如何使用这个 Agent？
在要审计的仓库中向编程代理发送自然语言提示，例如："Use the bug-hunter skill to scan this repository. Do not edit files. Return the final report and call out every item that needs manual review."。这是推荐的首次运行：只扫描、单轮。支持 /bug-hunter 语法：/bug-hunter（全仓库一次扫描）、/bug-hunter src/auth（指定路径）、--staged、--pr、--pr-security、--deps、--threat-model、--plan（只出修复计划不改动）、--fix --approve（授权经审查的修复）、--loop（完成排队覆盖）。无标志即 scan-only 单轮；--autonomous 和 --auto-commit 会授予无人值守修复和提交权限，须谨慎使用。结果写入 .bug-hunter/ 目录（建议加入 .gitignore），核心产物为 scan-report. 与 report.md。
这个 Agent 与同类方案有什么区别？
README 将自身与产生大量候选问题清单、留给开发者自行甄别的通用 AI 代码审查工具和安全扫描器对比：Bug Hunter 的差异点在于每个发现都必须经过 Skeptic 反驳和 Referee 独立裁决，未定结论显式呈现而非伪装成清洁结果。文中未点名具体竞品。