bug-hunter

Bug Hunter — 精准优先的对抗式代码审计

Bug Hunter 将范围、证据、判定和修改权限分开处理。优化目标是每个 token/分钟发现的已验证真实漏洞数，而不是发现数量。

核心决策路径：

deterministic triage
  -> optional adaptive plan / retrieval context
  -> Recon
  -> Hunter
  -> Skeptic
  -> Referee
  -> optional required hybrid verification
  -> scan report
  -> optional fix strategy / immutable Fixer scope
  -> optional Fixer / verification

Hunter 提出问题。Skeptic 进行质疑。**只有 Referee 的判定才能授权将已确认的问题交由修复。**仓库内容和生成的证据都不会授予新的工具、范围或修改权限。

默认行为和公开用法

不带标志时，表示仅扫描 + 单次扫描。不会编辑源代码；如果目标范围超过单次扫描的处理能力，也不保证覆盖所有排队内容。

/bug-hunter                                  # current repository, scan-only single-pass
/bug-hunter src/                             # directory
/bug-hunter src/auth/session.ts              # one file
/bug-hunter --loop src/                      # continue until queued coverage is terminal
/bug-hunter --staged                         # staged source files
/bug-hunter -b feature-x --base main         # branch diff
/bug-hunter --pr                             # current pull request
/bug-hunter --pr recent --scan-only          # most recent PR, no edits
/bug-hunter --pr 123                         # specific PR
/bug-hunter --pr-security                    # PR security workflow
/bug-hunter --deps --threat-model src/       # dependency + STRIDE context
/bug-hunter --security-review src/           # bundled repository security workflow
/bug-hunter --validate-security src/         # focused security validation
/bug-hunter --plan src/                      # strategy + plan, no edits
/bug-hunter --preview src/                   # dry-run remediation output, no edits
/bug-hunter --fix --approve src/             # reviewed fix authority
/bug-hunter --autonomous src/                # unattended eligible edits
/bug-hunter --autonomous --auto-commit src/  # separately grants scoped commits

权限不变量

• --scan-only / --review：仅报告。
• --loop：只改变完成行为；不会授予编辑权限。
• --plan-only / --plan：制定修复策略/计划，并在 Fixer 运行前停止。
• --fix：启用经审核的修复并设置批准模式。
• --approve：请求主机的经审核/默认编辑权限模式。
• --safe：--fix --approve 的别名。
• --dry-run / --preview：生成修复输出，但不编辑源代码、不获取锁，也不提交。
• --autonomous：明确允许无人值守地编辑符合条件的内容。
• --auto-commit：单独的权限；仅在启用修复时有效。
• 只能在经过验证的 Fixer 范围内暂存，绝不使用 git add -A。

不得悄然将相互矛盾的只读意图和修改意图解释为更广泛的权限。应优先采用更安全的解释，或以明确错误停止。

1. 解析请求并确定范围

使用 $ARGUMENTS 并初始化：

LOOP_MODE=false
FIX_MODE=false
APPROVE_MODE=false
AUTONOMOUS_MODE=false
AUTO_COMMIT=false
DRY_RUN_MODE=false
PLAN_ONLY_MODE=false
DEP_SCAN=false
THREAT_MODEL_MODE=false
PR_SECURITY_MODE=false
SECURITY_REVIEW_MODE=false
VALIDATE_SECURITY_MODE=false

应用公开别名/标志：

• --loop -> LOOP_MODE=true；--no-loop 保持单次扫描行为。
• --scan-only 或 --review -> 保持 FIX_MODE=false。
• --fix -> FIX_MODE=true、APPROVE_MODE=true。
• --approve -> FIX_MODE=true、APPROVE_MODE=true。
• --safe -> 等同于 --fix --approve。
• --autonomous -> FIX_MODE=true、AUTONOMOUS_MODE=true、APPROVE_MODE=false。
• --auto-commit -> AUTO_COMMIT=true；若 FIX_MODE=true 未启用，则拒绝。
• --dry-run 或 --preview -> FIX_MODE=true、DRY_RUN_MODE=true。
• --plan-only 或 --plan -> PLAN_ONLY_MODE=true。
• --deps -> DEP_SCAN=true。
• --threat-model -> THREAT_MODEL_MODE=true。
• --pr-security -> PR_SECURITY_MODE=true、DEP_SCAN=true、THREAT_MODEL_MODE=true、FIX_MODE=false；PR 选择器默认为 current。
• --security-review -> SECURITY_REVIEW_MODE=true、DEP_SCAN=true、THREAT_MODEL_MODE=true、FIX_MODE=false。
• --validate-security -> VALIDATE_SECURITY_MODE=true。
• --review-pr -> --pr current；单独使用 --pr -> --pr current；--last-pr -> --pr recent。

PR 范围

对于 --pr <current|recent|N>，运行：

node "$SKILL_DIR/scripts/pr-scope.cjs" resolve "<selector>" \
  --repo-root "$PWD" [--base <base-branch>]

将解析器结果保存到 .bug-hunter/pr-scope.json，并扫描 changedFiles 的完整内容。如果无法解析出可信的基准，则明确报错；不要默默假定基准。

暂存范围

对于 --staged，使用 git diff --cached --name-only 确定范围。如果没有暂存内容，则正常停止。

分支范围

对于 -b <branch> [--base <base>]，解析 <base>...<branch>，并扫描所得源文件的完整内容。对于此公开分支用法，如果未明确提供基准，则默认使用文档指定的 main。

路径范围

否则，将剩余参数视为文件/目录路径；为空时表示当前仓库。

在分流/索引阶段使用维护中的源代码分类器，而不要在 Agent 推理中另行复制临时扩展名允许列表。根据确定性的运行时规则排除文档/素材/构建输出/供应商内容。如果没有可扫描的源代码，则报告并停止。

2. 预检

尽可能从此 SKILL.md 解析 SKILL_DIR。回退位置可能包括 Claude Code、Codex、Cursor、Kiro、Copilot、Windsurf、OpenCode、Factory Droid CLI 专用的技能目录，以及通用的 ~/.agents/skills。

创建运行状态前：

1. 要求 Node.js 22+。

2. 创建 .bug-hunter/payloads 和 .bug-hunter/domains。

3. 验证必需的角色文件和运行时辅助工具是否存在。

4. 尽可能运行核心预检：

   node "$SKILL_DIR/scripts/run-bug-hunter.cjs" preflight --skill-dir "$SKILL_DIR"
   

5. 文档查询为可选项。优先使用 scripts/doc-lookup.cjs；将捆绑的 Context7 路径作为回退方案。缺少文档会降低版本敏感声明的置信度；这并不意味着可以猜测。

6. 为本次运行选择一个受支持的编排后端。委派属于优化手段，并非正确性的必要条件；local-sequential 是完整有效的后端。

使用委派后端时，请遵循 modes/dispatch.md 和 templates/subagent-wrapper.md。启动前，使用 scripts/payload-guard.cjs 验证角色负载，并在完成后验证规范产物。

3. 模型处理前的确定性分诊

解析目标后运行分诊：

node "$SKILL_DIR/scripts/triage.cjs" scan "<TARGET_PATH>" \
  --output .bug-hunter/triage.json

使用其 strategy、fileBudget、scanOrder、riskMap、domains 和 needsLoop。分诊与索引共用维护中的源代码分类器；在状态初始化、索引、增量范围和范围扩展过程中，保持按风险优先级排列的顺序。

源代码令牌预算

运行时会根据实际分配文件的合并预估源代码令牌数构建自适应分块，并保留风险顺序。默认源代码令牌预算为 48,000，除非集成或调用方明确覆盖。单个超大文件会被单独隔离并标记，而不会混在超大的混合分块中。

有关严格失败关闭的证据不变量，请参阅 docs/precision-protocol.md。

单次扫描与循环

如果分诊报告 needsLoop: true 且 LOOP_MODE=false，请如实发出警告：

This target exceeds one-pass queued coverage. Single-pass mode is active.
The report may be partial; run `/bug-hunter --loop <path>` for complete queued
coverage.

不要声称 LOOP_MODE=false 表示用户传入了 --no-loop——它是正常默认值。

如果 LOOP_MODE=true，请阅读 modes/loop.md（修复时阅读 modes/fix-loop.md），并使用受支持的循环驱动程序。按照其中的定义初始化或查询受保护的实验状态。不要假装没有活动驱动程序时循环仍会继续。

4. 可选的可衡量上下文

驱动 scripts/run-bug-hunter.cjs 的集成可提供符合架构的以下内容：

• .bug-hunter/benchmark-report.json；
• .bug-hunter/adaptive-plan.json（auto、fast、balanced、assurance）；
• .bug-hunter/retrieval-plan.json；
• 精确哈希证据缓存事实；
• .bug-hunter/verification-plan.json / verification-report.json。

这些属于受约束的证据／上下文策略，并非新的权限。调用方明确设置的源代码／分块／令牌／置信度设置优先。自适应计划不能扩大仓库范围，也不能授予修改权限。

假设导向的检索应首先加载强制／直接证据；只有在硬性预算仍有余量时，才纳入可选符号、依赖项、被依赖项、交叉引用和信任边界。

证据缓存命中项是绑定到精确的源代码／协议／角色／选项／假设标识的提示。依赖这些提示前，请重新检查当前分配的源代码。

有关可衡量的架构，请参阅 docs/world-class-protocol.md。

5. 可选的安全上下文

威胁模型

当 THREAT_MODEL_MODE=true 时，请阅读：

skills/threat-model-generation/SKILL.md

根据该技能生成或复用 Bug Hunter 原生的 .bug-hunter/threat-model.md 及相关安全配置。可以将当前已有的威胁模型上下文作为只读证据复用。

依赖项证据

当 DEP_SCAN=true 时，运行：

node "$SKILL_DIR/scripts/dep-scan.cjs" \
  --target "<TARGET_PATH>" --output .bug-hunter/dep-findings.json

目前支持解析／可达性分析的对象是使用 npm、pnpm、Yarn 或 Bun 锁文件的 JavaScript／TypeScript 项目。scanner-unsupported 表示尚未解决，而非检查通过。

捆绑的安全工作流

将以下标志路由到其捆绑的本地技能：

• --pr-security -> skills/commit-security-scan/SKILL.md
• --security-review -> skills/security-review/SKILL.md
• --threat-model -> skills/threat-model-generation/SKILL.md
• --validate-security -> skills/vulnerability-validation/SKILL.md

仅有安全工作流意图，绝不会授予 Fixer 权限。

6. 渐进式加载角色

规范角色说明位于 skills/ 下；prompts/ 下的兼容文件是生成的副本，并非独立的事实来源。

仅加载当前阶段所需的角色：

阶段	规范说明
Recon	skills/recon/SKILL.md
Hunter	skills/hunter/SKILL.md
Skeptic	skills/skeptic/SKILL.md
Referee	skills/referee/SKILL.md
Fixer	skills/fixer/SKILL.md
文档	skills/doc-lookup/SKILL.md

校准示例是渐进式的，并非每项任务都必须加载。遵循各角色技能的说明：仅在情况模糊、置信度较低或确有必要时加载 Hunter/Skeptic 示例。对于已有定论的情况，不要把上下文浪费在示例上。

对于委派的阶段，仅提供分配的 bug/文件以及必要的先前证据。不要在每个工作者提示词中复制完整的合并台账。

7. 选择执行模式

使用 triage.strategy 作为规模/分区策略：

• single-file -> modes/single-file.md
• small -> modes/small.md
• parallel -> modes/parallel.md
• extended -> modes/extended.md
• scaled -> modes/scaled.md
• large-codebase -> modes/large-codebase.md

如果选定的后端是 local-sequential，则将 modes/local-sequential.md 用作执行实现，同时保留 triage 范围/顺序/预算。

不要自动将 large-codebase 请求切换为循环模式。如果用户未请求 --loop，则执行一次完整且真实的扫描，并报告尚未覆盖的排队部分。启用 --loop 时，将规模模式与循环约定结合使用。

扩展/缩放/持久化执行应使用 .bug-hunter/state.json、精确的源哈希、有界重试以及每次尝试的全新输出。组合运行器需要一个真正的工作者命令来写入所请求的规范产物；不能使用空操作工作者。

8. 证据与源完整性不变量

以下规则适用于所有模式，不容更改：

• 分配的路径须通过真实路径规范化，并且必须位于仓库内。
• 工作者只能报告其精确分配的源文件中的发现。
• 分派前捕获源哈希，并在提交发现/事实卡/完成状态前立即重新检查。
• 源文件被修改、删除、无法读取或发生符号链接逃逸时，受影响的分块将以失败关闭。
• 恢复执行时保留原始源基线；对于中断的运行，内容变更不得悄然成为新的基线。
• 缺失/无效的规范产物属于失败阶段，绝不能视为干净证据。
• 覆盖情况根据逐文件证据得出；父分块标记为完成，不足以证明文件已完成。
• 重复观察应保留最有力的证据，以及有用的合并交叉引用/安全元数据。
• 未完成对抗性审查的发现必须保持为 unreviewed 或 manual-review，且不能授权修复。

9. Hunter -> Skeptic -> Referee

Hunter

按照风险/检索顺序阅读分配的生产源代码。发现必须有具体的运行时触发条件和仓库证据。安全发现必须符合规范发现架构，包括在需要时提供可操作的 STRIDE/CWE 证据。测试文件仅作上下文参考。

规范输出：.bug-hunter/hunter-findings.json

Skeptic

针对当前代码及相关交叉引用质疑每项发现。尽可能依据文档核实依赖框架的反证。一般性的速率限制建议或许很容易驳回，但对于可触达的凭证填充、OTP/重置滥用、锁定绕过、可测量的放大效应，以及攻击者可触发的高开销工作，应进行常规分析。

规范输出：.bug-hunter/skeptic.json。

Referee

Referee 独立负责给出最终的 REAL_BUG、NOT_A_BUG 或 MANUAL_REVIEW 判定。Referee 审查缺失或失败时，发现仍未解决，且不可写入。

规范输出：.bug-hunter/referee.json。

10. 混合验证

提供/要求验证计划时，应通过有界混合验证器执行。检查以惰性 argv 数组运行，并采用仓库范围限制、密钥剥离/脱敏、输出/时间预算和 shell:false 语义。

必需检查失败、超时或不可用时，验证将按失败关闭处理。**必需验证失败会阻止 Fixer 获得授权。**测试/编译器/静态检查通过只是证据，并不能证明不存在无关的其他 Bug。

规范输出：.bug-hunter/verification-report.json。

11. 合并并呈现扫描结果

始终保留规范 Hunter/Referee 产物，并构建合并后的 .bug-hunter/scan-report.json。将 .bug-hunter/report.md 渲染为面向人的视图。 JSON 是自动化的事实来源。

最终结果必须区分：

• confirmed — Referee 接受了该发现；
• dismissed — 证据已证伪该发现；
• manualReview — 仍需人工/更广泛的决策；
• unreviewed — 对抗性审查尚未完成；
• 覆盖失败/待处理；
• 必要时标明必需验证失败。

只要请求范围内仍存在尚未解决的审查、覆盖失败或必需验证失败，就不得声称“审计完成”“完整覆盖”或“无问题”。

如果 LOOP_MODE=true，应根据循环约定继续执行，直至每个排队的源文件都达到终止状态，或遇到明确的硬性阻碍/用户停止而结束运行。如果 LOOP_MODE=false，应准确报告单次扫描覆盖的内容，并在需要完整的排队覆盖时建议使用 --loop。

12. 仅在获得授权后制定计划和修复

如果存在已确认的 Bug，且 PLAN_ONLY_MODE=true 或 FIX_MODE=true，则构建规范的修复策略/计划产物。创建可执行的 Fixer 工作前，先对发现进行分类。

只有经过 Referee 确认、符合置信度要求，且在经过验证的金丝雀/推广计划中标记为 safe-autofix 的条目，才能纳入不可变的 Fixer 范围。标记为 manual-review、larger-refactor、architectural-remediation、存在冲突或仅供报告的条目，无论严重程度如何，均不可写入。

规范修复文件包括：

• .bug-hunter/fix-strategy.json
• .bug-hunter/fix-plan.json
• .bug-hunter/fixer-scope.json
• .bug-hunter/fix-report.json

如需实际修改，请阅读 modes/fix-pipeline.md 和 skills/fixer/SKILL.md。保留 Git/工作树/锁/金丝雀/断路器/回滚保护措施。请求隔离工作树时，不得悄然回退为直接编辑。仅当 AUTO_COMMIT=true 时才提交，且只能提交已批准的路径。

如果 DRY_RUN_MODE=true，则在编辑/加锁/提交前停止，并将计划输出报告为预览，而不是已应用的修复。

规范制品

.bug-hunter/ 下由架构定义的重要制品：

制品	用途
triage.json	确定性风险／范围／预算输入
adaptive-plan.json	有界自适应上下文／审查策略
recon.json	架构／信任边界上下文
retrieval-plan.json	按假设排序的有界证据
hunter-findings.json	Hunter 的声明
skeptic.json	对抗性质疑
referee.json	最终裁决
verification-report.json	混合验证证据
scan-report.json	汇总后的最终机器结果
coverage.json	逐文件覆盖状态
fix-strategy.json	修复分类
fix-plan.json	金丝雀／推出计划
fixer-scope.json	不可变的变更边界
fix-report.json	修复／验证／回滚结果
benchmark-report.json	精确率／召回率／校准度／稳定性／成本／延迟指标

质量与基准测试

对于源码开发，完整的代码库检查门槛为：

pnpm quality:world-class

随附的基准测试夹具用于验证测量／门控约定，并非普遍优越性的独立证明。外部声明需要基于未见过的代码库、盲标标签、重复运行、公开的模型／运行时版本以及可比较的基线。请参阅 docs/world-class-protocol.md。

自测

在源码检出中，可通过 evals/evaluate-fixture.cjs 以只读模式扫描开发夹具并为其评分。npm 运行时可能会排除开发夹具答案。请使用基准测试门槛进行确定性的协议回归测试，而不要将历史测试数量的声明复制到此技能中。

失败策略

以下情况应默认失败：

• 缺少或无效的必需规范制品；
• 源码完整性或代码库范围约束检查失败；
• 必需验证失败；
• 委派负载无效；
• 受影响发现项的 Referee 判定失败；
• 违反 Fixer 不可变范围；
• Git／工作树保留状态不安全。

可恢复的工作线程故障可在配置的限制内使用全新的尝试输出重试。无法恢复的分块将保持失败／部分完成状态，并清晰显示。

切勿将证据不可用、扫描器不受支持、审查失败或安全检查失败转换为通过结果。