免费开源工具审查AI代码，比Claude Code自带多抓bug

Claude Code 的多阶段代码审查——并行子代理检测、验证通过、持久化 JSON 状态，以及一个自动修复循环，在提交前重新审查并回退回归问题。

在我自己的 PR 上，它捕获的真实 bug 数量远超 Claude Code 内置的 /review、/ultrareview、CodeRabbit、Greptile 和 Codex 内置审查——同时产生的误报更少。（个人经验，样本量 n=1。）该工具以内置的 /review 为模型，扩展成一个六命令管道。它使用你常规的 Claude Code 订阅（推荐 Max 计划）运行——与 /ultrareview 不同，后者会从你的额外使用池中扣费。

/plugin marketplace add adamjgmiller/adamsreview /plugin install adamsreview@adamsreview

六个命令

/adamsreview:review——对分支或 PR 进行多视角代码审查。最多七个并行子代理视角（正确性、安全性、用户体验等）输入一个去重阶段、一个先简单后深入的验证门，以及（可选）一个整体的 Opus 交叉检查阶段。高置信度的自动修复建议会预先计算，以便 :fix 和 :walkthrough 可以在一次确认中批量接受它们。--ensemble 会在内部 Claude 视角之上额外添加一个 Codex CLI 阶段和 PR 机器人评论抓取。

/adamsreview:codex-review——与 :review 对等的 Codex CLI 审查。相同的工件结构，可直接替换下游所有命令（:fix、:add、:walkthrough、:promote）。可通过 --effort low|medium|high|xhigh（默认为 high）调整工作量。

/adamsreview:add——将外部来源的发现（Claude Code 云 /ultrareview 粘贴、Opus 快速审查、团队成员的笔记）注入到最近一次审查的工件中。与已有内容去重，通过相同的门进行验证，并重新发布到现有的 PR 评论中。

/adamsreview:walkthrough——:fix 会跳过的发现的交互式驱动。使用框架的 AskUserQuestion UI 逐个处理不确定或需要人工判断的项目——提升你想要自动修复的，跳过其余部分。预先计算的自动修复建议会提前批量接受；其余部分会获得每个发现的简报、选项和建议。将决策日志发布到 PR。

/adamsreview:fix——自动修复循环。并行分派每个修复组的子代理，然后使用 Opus 重新审查工作，回退任何回归问题，并提交幸存的部分（默认一个合并提交；--granular-commits 为每个组一个提交）。

/adamsreview:promote——人工覆盖，将单个发现提升为可自动修复，绕过通道过滤器和分数阈值。

命令文件位于 commands/ 下的裸主干路径；共享的阶段片段和提示引用位于 fragments/；辅助脚本和工件模式位于 bin/。插件运行时在加载时自动将 bin/ 添加到 $PATH——无需符号链接，无需安装脚本。

推荐流程

对于非平凡的 PR，命令按以下顺序效果最佳：

1. 审查。 /adamsreview:review——或者如果你已安装 Codex CLI 并希望在内部 Claude 视角之上合并一个 Codex 阶段和 PR 机器人评论抓取（更高的 token 成本），则使用 /adamsreview:review --ensemble。或者使用 /adamsreview:codex-review [--effort <level>] 进行 Codex 驱动的同行审查（可直接替换下游所有命令；工作量可调；无 --ensemble）。

2. 添加。（可选）/adamsreview:add <paste...>——如果你运行了并行审查（云 /ultrareview、Opus 快速审查、手动扫描等）并发现了原始审查遗漏的 bug，请在此处粘贴结果。这些发现会通过第 4 阶段验证并进入同一个工件，与已有内容去重。自动符合条件的添加内容会进入第 4 步；不符合条件的会在第 3 步中显示。

3. 走查。（可选）/adamsreview:walkthrough [threshold]——逐步处理修复命令会跳过的发现（深度手动、深度报告以及整个轻量通道，包括轻量 confirmed_mechanical），仅限于分数达到或超过 $threshold（默认 60）的项目，以免低信号项目拖慢会话。第 4.5 步在一次确认中批量接受所有带有预先计算自动修复建议的发现（快速路径）；其余部分通过框架的 AskUserQuestion UI 获得每个发现的简报、选项和建议。提升你想要自动修复的，并附带定制的修复提示，跳过其余部分。将决策日志发布到 PR 以供审计。传递较低的阈值（例如 /adamsreview:walkthrough 30）并在预检提示中选择 Full 层级，以同时审计第 3 阶段降级的 below_gate 发现。

4. 修复。 /adamsreview:fix——应用每个自动符合条件的发现（包括第 2 步添加和第 3 步提升的内容）。第 7.5 步在第 8 步分派之前，会显示任何剩余的自动修复建议（轻量通道/手动/报告发现），供一次确认批量接受。默认：所有幸存修复的一个合并提交；传递 --granular-commits 为每个修复组一个提交。无论哪种方式，每个组的第 9 步结果都会进入提交消息。

每个命令都是独立的——如果你只关心自动符合条件的发现，可以直接从审查进入修复，或者完全跳过审查，直接对现有工件运行 :fix。第 2-4 步可以在第 1 步之后数天或数周进行；审查工件持久存储在 ~/.adams-reviews/<slug>/<branch>/ 下。

/adamsreview:promote <id> 在走查流程之外仍然可用于一次性手动提升（例如使用 --force 提升一个被证伪的发现，或者概念性地循环处理一组 ID——F003、F037、F039——每个都使用 --defer-publish，以便只有最终调用才重新发布到 PR）。

文档

- CLAUDE.md——在此仓库中工作的 Claude Code 会话的操作指南。自包含，适用于日常工作；在新会话中首先阅读。 - docs/state-and-gates.md——发现状态模型、分数门、深度/轻量通道（规范性规范）。 - docs/pipeline.md——每个命令的阶段树和 token 统计语义。 - docs/helpers.md——辅助脚本清单和批量辅助模式。 - bin/schema-v1.json——artifact.json 的 JSON Schema（工件形状的权威来源）。 - docs/archive/——冻结的设计和构建文档（自 2026-04-19 起）。DESIGN.md（修订版 8）是原始的规范性规范；BUILD.md 是分阶段日志。不再维护；仅用于历史背景参考。 - plans/——每个分支的计划文件。活跃的后续工作位于 GitHub issues 中；历史积压工作位于 plans/old-backlog.md（自 2026-05-04 起冻结）。

依赖项

运行时

| 工具 | 版本 | 使用者 | 备注 | | :--- | :--- | :--- | :--- | | uv | 0.7+ | artifact-patch.py, artifact-render.py | brew install uv。脚本使用 PEP 723 内联脚本 shebang (#!/usr/bin/env -S uv run --quiet --script)，因此 uv 会在首次运行时获取并缓存 jsonschema——无需 venv，无需全局 pip install | | python3 | 3.10+ | 由 uv 调用 | 如有需要，uv 会安装匹配的 Python 版本 | | bash | 3.2+ | 所有 *.sh 辅助脚本 | 辅助脚本特意兼容 3.2（无 declare -A、mapfile、${var,,}），因此 macOS 默认的 /bin/bash 可以直接使用。在 Windows 上，Git for Windows 通过 Git Bash 提供 bash 5+，Claude Code 会自动通过它路由 | | jq | 1.6+ | artifact-read.sh, 日志辅助脚本 | brew install jq | | gh | 2.x | artifact-publish.sh, external-scrape.sh | brew install gh, gh auth login | | git | 2.x | 各处 | 标准 |

安装

macOS / Linux

1. 安装依赖项：brew install uv jq gh git（macOS）或发行版等效命令。（macOS 默认的 /bin/bash 3.2 没问题——辅助脚本兼容 3.2。） 2. 在 Claude Code 会话中：/plugin marketplace add adamjgmiller/adamsreview 3. 在同一个会话中：/plugin install adamsreview@adamsreview

Windows（原生）

1. 安装 Git for Windows——提供 Git Bash（bash 5+）和 git，Claude Code 内部使用它们。Claude Code 自动将 #!/usr/bin/env bash 辅助脚本通过 Git Bash 路由；如果 Git Bash 位于非默认位置，请设置 CLAUDE_CODE_GIT_BASH_PATH（参见故障排除）。 2. 安装 uv、jq 和 GitHub CLI。 3. 在 Claude Code 会话中：/plugin marketplace add adamjgmiller/adamsreview 和 /plugin install adamsreview@adamsreview。

从本地检出安装

如果你已克隆此仓库并希望从源代码运行——或者你想固定到特定提交——有两种方法无需通过 GitHub marketplace 往返：

- 从本地路径持久安装。 在 Claude Code 会话中，运行 /plugin marketplace add /path/to/adamsreview，然后运行 /plugin install adamsreview@adamsreview。最终状态与上述 GitHub marketplace 流程相同——插件注册在 ~/.claude/ 下，并在重启后持续存在。如果你的当前工作目录已经是克隆目录，可以使用 . 代替绝对路径。 - 通过 --plugin-dir 一次性使用。 claude --plugin-dir /path/to/adamsreview 会启动 Claude Code，并将该克隆作为插件加载，仅限该会话。不会向 ~/.claude/ 写入任何内容；不带标志重新启动后，插件将消失。方便在不产生任何持久状态的情况下试用插件，或与已安装版本并排运行特定检出。

两种方法仍然需要上述运行时依赖项（uv、jq、gh、bash、git）。

命令（安装后）

所有调用都带有插件命名空间：

/adamsreview:review [--ensemble] [--full] /adamsreview:codex-review [--effort <low|medium|high|xhigh>] [--full] /adamsreview:add [<paste...>] [--file <path> --line <N> --claim "..."] /adamsreview:walkthrough [threshold] /adamsreview:fix [threshold] /adamsreview:promote <finding_id> [--reason "..."] [--fix-hint "..."]

--full（在 :review 和 :codex-review 上）选择退出琐碎模式优化，强制每个检测视角即使在小型或仅文档的差异上也能运行。当你希望对故意小的 PR 进行全面覆盖时很有用；否则，默认的琐碎模式分类器是正确的选择。

无需单独的 Python 依赖项安装。首次调用任何 *.py 辅助脚本会触发 uv 解析声明的依赖项（jsonschema 等）并缓存它们——这在新机器上可能需要几秒钟（参见故障排除）。后续运行很快。

插件作者迭代

如果你在修改插件本身（而不仅仅是使用它），scripts/dev-run.sh 会通过 claude --plugin-dir "$(pwd)" 启动 Claude Code，并将工作树作为插件加载——无需 marketplace 安装。要从工作树模拟安装路径，请在 Claude Code 会话中运行 /plugin marketplace add .。

审查状态位置

/adamsreview:review 将每次运行的状态（工件、跟踪、阶段日志、token 日志）写入 ~/.adams-reviews/<repo-slug>/<branch>/<review_id>/。如果需要将状态放在其他位置，请使用 export ADAMS_REVIEW_REVIEWS_ROOT=/some/other/path 覆盖。

为什么不是 ~/.claude/reviews/？Claude Code 对写入 ~/.claude/... 的操作硬编码了一个敏感文件权限提示，即使 bypassPermissions 模式也无法避免，并且 ~/.claude/reviews 不在豁免子目录的短名单中（.claude/commands、.claude/agents、.claude/skills）。将审查状态保持在 ~/.claude/ 之外可以避免每次运行出现数十个权限提示。

从 Stage 2.5 之前的状态迁移

如果你在 ~/.claude/reviews/ 下有审查记录，请执行以下任一操作：

# 选项 A：将状态移动到新的规范根目录（推荐）。 mv ~/.claude/reviews ~/.adams-reviews

# 选项 B：通过环境变量将状态保留在旧位置（接受提示）。 export ADAMS_REVIEW_REVIEWS_ROOT=~/.claude/reviews

Token 计数：它们衡量什么

渲染的报告可以显示两个数字：

- 子代理 token——从每次审查的 tokens.jsonl 日志汇总。计算为此特定审查分派的每个子代理（视角、验证器、修复代理、修复后审查器等）。精确。始终显示。 - 编排器 token——从 ~/.claude/projects/<cwd-slug>/ 下的 Claude Code 会话记录汇总，过滤到时间戳 >= review_started_at 的助手轮次。捕获子代理 token 有意排除的主会话开销。可选——见下文。

当两者都填充时，它们是互补的（无重叠），并且共同估算总成本。

编排器 token 是可选的

macOS Sequoia 和 Tahoe 会在 shell 辅助脚本首次读取带有 com.apple.provenance 扩展属性的文件时显示“kitty（或你的终端）想要访问来自其他应用的数据”提示。每个 Claude Code 记录都带有一个，而 bin/orchestrator-tokens.sh 会读取它们——因此该辅助脚本会在每次审查的第一个生命周期命令时触发提示，并且（由于此门的 TCC 缓存不完整）之后会重复触发。为避免打扰用户，该辅助脚本默认跳过。

要启用，请执行以下任一操作：

- 推荐——授予你的终端应用完全磁盘访问权限（系统设置 → 隐私与安全性 → 完全磁盘访问权限 → + 你的终端）。一次切换，永久生效，为从终端启动的所有内容静默此类提示。然后在你的 shell rc（~/.zshrc、~/.bashrc 等）中导出 ADAMS_REVIEW_TALLY_ORCHESTRATOR=1，以便辅助脚本实际运行。 - 仅选择加入，无需 FDA——导出 ADAMS_REVIEW_TALLY_ORCHESTRATOR=1，并在 macOS 提示触发时接受它们。每次授权持续到下一次操作系统更新或终端应用更新；如果你希望权限更窄但需要定期点击“允许”，请选择此选项。

当选择退出时（默认），辅助脚本以 0 退出，输出一行 orchestrator-tally: skipped，并让工件的 orchestrator_tokens 字段保持缺失。PR 评论仅显示“子代理 token”——仍然是精确的每次审查计数器，也是主要的成本信号。子代理 token 记录在 ~/.adams-reviews/ 下，该目录没有 provenance xattr，因此该路径不会触发任何提示。

过时数据行为

如果你在初始审查时选择加入，然后在运行 /adamsreview:fix 之前选择退出，辅助脚本会保留先前写入的 orchestrator_tokens 值，而不是擦除它。渲染的行显示最后测量的值，而不是新跳过的零——这意味着它可能低估后续修复时间的活动。在下一个生命周期命令上重新选择加入会刷新。相反方向（审查时选择退出，修复时选择加入）没有过时问题：修复时间统计的 --since review_started_at 窗口覆盖完整的审查→修复弧，因此第一次选择加入写入会捕获所有内容。

编排器 token 可能高估（当选择加入时）

记录扫描是一个纯时间窗口过滤器，因此在 review_started_at 和最后一次统计之间，同一工作目录中的任何 Claude Code 轮次都会被计数——即使是不相关的工作。实际上这意味着：

- 干净： 审查→修复连续进行，或审查→对更新后的代码库进行新审查（每次审查的 review_started_at 排除前一次审查的轮次）。 - 高估： 审查→同一 cwd 中的不相关工作→修复（不相关的轮次会进入修复运行的重新统计）。 - 缓解措施： 将生命周期命令运行得紧密一些，或者在不同的工作树中执行不相关的工作（不同的 cwd → 不同的记录目录 → 不会被扫描）。

子代理 token 没有这个问题——它们的日志是按审查划分的。如果你需要精确的总数，请信任子代理 token，并将编排器 token 视为粗略上限。有关完整警告列表，请参见 bin/orchestrator-tokens.sh 头部。

为什么使用 uv 而不是普通的 pip

PEP 668（Python 3.12+ 与 Homebrew）将系统和用户 site-packages 标记为外部管理，并拒绝直接 pip install。原始计划假设使用普通的 pip；uv 的内联脚本依赖规范是最干净的解决方法：每个 Python 辅助脚本都是自包含的，无需激活仪式即可运行，其依赖列表位于导入它的代码旁边。权衡：需要机器上安装 uv 才能运行脚本。

布局

adamsreview/ ← 此仓库（插件根目录） ├── CLAUDE.md ← 操作指南（首先阅读） ├── README.md ← 此文件 ├── .claude-plugin/ │ ├── plugin.json ← 插件清单（名称：adamsreview） │ └── marketplace.json ← 单插件市场 ├── .gitattributes ← LF 强制执行 ├── docs/ │ └── archive/ ← 冻结的历史参考（不再维护） │ ├── README.md ← 冻结时横幅 │ ├── DESIGN.md ← 原始规范性设计（修订版 8） │ └── BUILD.md ← 构建日志（第 1-3 阶段 + 加固 + 走查） ├── plans/ ← 每个分支的计划文件（总括 + 可选的 PRD/PLAN/JOURNAL） ├── test/ ← 烟雾测试框架 + 夹具 ├── commands/ ← 裸主干命令文件（插件命名空间） │ ├── review.md ← /adamsreview:review │ ├── codex-review.md ← /adamsreview:codex-review │ ├── add.md ← /adamsreview:add │ ├── walkthrough.md ← /adamsreview:walkthrough │ ├── fix.md ← /adamsreview:fix │ └── promote.md ← /adamsreview:promote ├── fragments/ ← 共享阶段片段 + 提示引用 │ ├── _prelude-shared.md ← 每个命令加载 │ ├── promote-core.md ← 共享前提条件 + 补丁（promote + walkthrough） │ ├── 00-preflight.md … 10-post-fix-and-commit.md │ │ （包括第 5.5 阶段的 06b-auto-fix-hint.md） │ ├── 02-ensemble-adapter.md ← --ensemble 池化 │ ├── 01-codex-detection.md ← Codex 第 1 阶段变体 │ ├── 05-codex-validation.md ← Codex 第 4 阶段变体 │ ├── 06-codex-cross-cutting.md ← Codex 第 5 阶段变体 │ ├── lens-prompts/ ← 每个视角的检测提示 │ └── lens-*-reference.md ├── bin/ ← 辅助脚本（插件运行时自动添加到 $PATH） │ ├── include ← !include <fragment>.md 包装器 │ ├── schema-v1.json ← artifact.json 的 JSON Schema │ ├── _common.py ← 共享的 Python 辅助函数 │ ├── artifact-patch.py ← 机器状态写入器 │ ├── artifact-render.py ← JSON → Markdown │ ├── artifact-validate.sh ← 模式检查（bash 包装器） │ ├── artifact-read.sh ← jq 包装器 │ ├── artifact-publish.sh ← PR 评论发布/补丁 │ ├── artifact-seed.sh ← 初始工件脚手架 │ ├── claude-md-paths.sh ← 向上查找 CLAUDE.md 查找器 │ ├── staleness.sh ← git diff 交集 │ ├── freshness-gate.sh ← 跟踪新鲜度检查 │ ├── trivial-check.sh ← 琐碎模式分类器 │ ├── codex-poll.sh ← Codex CLI 调用 + 看门狗 │ ├── parse-validator-result.py ← 验证器输出解析器 │ ├── parse-with-repair.py ← 带修复的 JSON 解析器 │ ├── source-family-map.py ← 源家族查找 │ ├── log-phase.sh ← trace.md + phases.jsonl 追加器 │ ├── log-tokens.sh ← tokens.jsonl 追加器 │ └── （其他辅助函数：group-fixes.py、repo-slug.sh、comment-freshness.sh、 │ origin-crosscheck.sh、prior-fix-diff.sh、external-scrape.sh、 │ assign-finding-ids.sh、line-range-check.sh、tally-subagent-tokens.sh、 │ orchestrator-tokens.sh） ├── hooks/ │ ├── hooks.json ← SessionStart 注册 │ └── dep-check.sh ← 会话启动时的软依赖缺失警告 └── scripts/ └── dev-run.sh ← claude --plugin-dir 包装器（插件作者迭代）

无符号链接，无安装脚本。插件运行时在通过 /plugin install adamsreview@adamsreview 安装插件后，按约定发现 commands/、fragments/、bin/ 和 hooks/。

故障排除

首次调用很慢

Python 辅助脚本（artifact-patch.py、artifact-render.py）使用 PEP 723 内联脚本 shebang (#!/usr/bin/env -S uv run --quiet --script)。在新机器上，首次运行会暂停几秒钟，因为 uv 会解析匹配的 Python 解释器并将 jsonschema 依赖项获取到其缓存中。后续运行会命中缓存，几乎是即时的。这是每台机器的一次性成本，而不是每次审查的成本。

--ensemble 模式要求

/adamsreview:review --ensemble 额外需要 codex Claude Code 插件（本地 Codex CLI 通过插件的 codex-companion.mjs 调用，而不是作为 $PATH 上的独立 CLI）。如果没有安装该插件，就绪门会提示你要么在没有 Codex 的情况下继续（在 PR 模式下，这意味着仅 PR 评论抓取；在本地模式下，这意味着仅内部视角——第 1.5 阶段没有工作要做），要么停止并运行 /codex:setup。默认（非 ensemble）模式没有此要求。

Windows：未找到 Git Bash

Claude Code 在 Windows 上自动发现 Git Bash，并将 #!/usr/bin/env bash 辅助脚本通过它路由。如果自动发现失败（非默认 Git Bash 安装路径、便携式安装等），请在启动 Claude Code 之前将 CLAUDE_CODE_GIT_BASH_PATH 设置为 bash.exe 的绝对路径——例如：

set CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

或 PowerShell 中的等效 $env:CLAUDE_CODE_GIT_BASH_PATH = ...。

状态

当前版本：v0.4.0（自动修复提示功能：第 5.5 阶段 + 第 7.5 阶段 + 第 4.5 步）。所有六个命令均已发布并日常使用。/adamsreview:codex-review 在 v0.3.0 中发布；最近的版本侧重于加固（扇出站点的反序列化调用、并行分派正确性、JSON 管道反斜杠安全性）以及自动修复提示流程，该流程允许 :fix 和 :walkthrough 在一次确认中批量接受 Sonnet 提出的修复。

活跃的后续工作位于 GitHub issues 中。冻结的历史背景：plans/old-backlog.md 和 docs/archive/。