adamjgmiller/adamsreview 来源：https://github.com/adamjgmiller/adamsreview

adamsreview

为 Claude Code 提供的多阶段代码审查工具——支持并行子代理检测、验证通道、持久化 JSON 状态，以及一个在提交前重新审查并回退回归问题的自动化修复循环。在我自己的 PR 中，它捕捉到的真实 bug 数量显著多于 Claude Code 内置的 /review、/ultrareview、CodeRabbit、Greptile 和 Codex 内置审查工具，同时产生的误报更少。（个人经验，样本量为 1。）该工具以内置的 /review 为模型，扩展为六命令流水线。运行于常规 Claude Code 订阅（推荐使用 Max 计划）——与消耗额外使用额度的 /ultrareview 不同。

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

六个命令：

• /adamsreview:review — 对分支或 PR 进行多镜头代码审查。最多七个并行子代理镜头（正确性、安全性、UX 等）输入去重通道、先简后深的验证门控，以及（可选的）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/；辅助脚本和工件 schema 位于 bin/。插件运行时加载时会自动将 bin/ 添加到 $PATH —— 无需符号链接，无需安装脚本。

推荐流程

在重要的 PR 上，命令最好按以下顺序使用：

1. 审查。 /adamsreview:review —— 或者如果你安装了 Codex CLI 并希望将 Codex 审查和 PR 机器人评论抓取叠加在内部 Claude 镜头上，使用 /adamsreview:review --ensemble（token 成本更高）。或者 使用 /adamsreview:codex-review [--effort ] 进行 Codex 驱动的同行审查（可替代所有后续流程；努力程度可调；无 --ensemble）。

2. 添加。 （可选） /adamsreview:add —— 如果你运行了并行审查（云端 /ultrareview、Opus 快速浏览、手动扫描等）并发现了原始审查遗漏的 bug，在此粘贴结果。发现将经过第四阶段验证，进入同一工件，并与现有发现去重。符合自动修复条件的添加项进入第 4 步；不符合条件的则在第 3 步中显示。

3. 逐步审查。 （可选） /adamsreview:walkthrough [threshold] —— 逐步审查修复命令会跳过的发现（深度手动、深度报告，以及包括轻量 confirmed_mechanical 在内的整个轻量通道），限制在得分等于或高于 $threshold（默认 60）的项目，以免低信号项目填充会话。步骤 4.5 在一次确认中批量接受所有携带预先计算自动修复建议的发现（快速路径）；其余项目通过框架的 AskUserQuestion UI 获得逐条简报、选项和建议。提升你希望自动修复的项目并附带定制化修复提示，跳过其余项目。向 PR 发布决策日志以供审计。传入较低的阈值（例如 /adamsreview:walkthrough 30）并在预检提示中选择 Full 层级，也可以审计第三阶段降级的 below_gate 发现。

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

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

/adamsreview:promote 对于逐步审查流程之外的一次性手动提升仍然有用（例如，使用 --force 提升 disproven 发现，或者概念上循环一组 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 冻结）。

依赖

运行时

安装

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（https://git-scm.com/downloads/win）—— 提供 Git Bash（bash 5+）和 git，Claude Code 内部使用。Claude Code 会自动将 #!/usr/bin/env bash 辅助脚本路由到 Git Bash；如果 Git Bash 位于非默认位置，请设置 CLAUDE_CODE_GIT_BASH_PATH（见 故障排除）。
2. 安装 uv（https://docs.astral.sh/uv/）、jq（https://jqlang.github.io/jq/download/）和 GitHub CLI（https://cli.github.com/）。
3. 在 Claude Code 会话中：/plugin marketplace add adamjgmiller/adamsreview 和 /plugin install adamsreview@adamsreview。

从本地克隆安装

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

• 从本地路径持久安装。 在 Claude Code 会话中，运行 /plugin marketplace add /path/to/adamsreview 然后 /plugin install adamsreview@adamsreview。与上述 GitHub 市场流程的最终状态相同——插件注册在 ~/.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 ] [--full]
• /adamsreview:add [] [--file --line --claim "..."]
• /adamsreview:walkthrough [threshold]
• /adamsreview:fix [threshold]
• /adamsreview:promote [--reason "..."] [--fix-hint "..."]

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

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

插件作者迭代

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

审查状态位置

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

为什么不是 ~/.claude/reviews/？ Claude Code 对写入 ~/.claude/... 硬编码了敏感文件权限提示，即使在 bypassPermissions 模式下也会生存，而 ~/.claude/reviews 不在豁免子目录短列表中（.claude/commands、.claude/agents、.claude/skills）。将审查状态保持在 ~/.claude/ 之外可以避免每次运行数十个权限提示。

从阶段 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// 下 Claude Code 会话转录的汇总，过滤到 timestamp >= review_started_at 的助手轮次。捕获 subagent_tokens 故意排除的主会话消耗。选择加入 — 见下文。

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

协调器 token 是选择加入

macOS Sequoia 和 Tahoe 在 shell 辅助脚本首次读取标记为 com.apple.provenance 扩展属性的文件时显示“kitty（或你的终端）希望访问其他应用的数据”提示。每个 Claude Code 转录都携带一个，而 bin/orchestrator-tokens.sh 读取它们——因此辅助脚本会在每次审查的每个生命周期命令的首次触发提示，并（因为此门控的 TCC 缓存是部分的）随后反复触发。为避免打扰用户，辅助脚本默认跳过。要启用，任一：

• 推荐 — 授予你的终端应用 完整磁盘访问权限（系统设置 → 隐私与安全 → 完整磁盘访问 → + 你的终端）。一次切换，永久，沉默从此终端启动的所有此类提示。然后在你的 shell rc（~/.zshrc、~/.bashrc 等）中 export ADAMS_REVIEW_TALLY_ORCHESTRATOR=1 使辅助脚本实际运行。
• 仅选择加入而无 FDA — export ADAMS_REVIEW_TALLY_ORCHESTRATOR=1 并在触发时接受 macOS 提示。每次授权持续到下一个 OS 更新或终端应用更新；如果你希望更窄的权限以定期点击 Allow 为代价，请选择此项。

当选择退出（默认）时，辅助脚本退出 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 → 不同的转录目录 → 不扫描）中进行不相关工作。

子代理 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/