tumf/review-gauntlet
GitHub: tumf/review-gauntlet
一个计划优先的 AI 代码审查覆盖率门禁工具，通过构建文件×规则审查矩阵来编排审查器、追踪覆盖率并保留审查证据，确保代码在被最终确认前完成所需的审查义务。
Stars: 2 | Forks: 0
# Review Gauntlet
基于计划优先的 AI 代码审查，具备文件 × 规则的覆盖率。
Review Gauntlet 是一个基于计划优先的覆盖率关卡，用于 AI 代码审查。在运行
审查器之前，它会构建一个文件 × 规则的审查矩阵。每个单元格代表一个
具体的审查义务：必须根据此规则检查此文件。然后，Review Gauntlet 会针对这些单元格运行 AI 审查器、静态分析器或自定义 adapter，记录证据和发现，并且只有在所需的
覆盖率完成后才进行最终确认。
审查器负责发现问题。而 Review Gauntlet 负责证明哪些文件是根据哪些规则进行检查的。
## 快速开始
审查仓库的最快方式：
Review Gauntlet 不是一个独立的审查器。在开始之前，请安装并
认证一个外部审查代理 CLI（例如 opencode），为该代理安装匹配的
Review Gauntlet 技能或 prompt 指南，并创建一个 adapter
配置，以告诉 Review Gauntlet 如何调用它。
```
# 1. 安装 CLI（如已安装请跳过）
uv tool install review-gauntlet
# 2. 单独安装/配置外部 review agent，然后创建一个 adapter config
uvx review-gauntlet config init --preset opencode
# 3. 为当前 repository 启动 review session
review-gauntlet init
# 4. 让 Review Gauntlet 驱动已配置的 agent 直到 session 完成
review-gauntlet run
# 5. 如有需要，检查最终的 checkpoint 和 findings
review-gauntlet status
review-gauntlet findings
```
`run` 会反复向 Review Gauntlet 请求下一个准备就绪的任务，使用该
prompt 调用配置好的外部代理，并在活动会话完成确认后停止。
`review` 对于底层或自定义工作流，每次仍然只推进一个审查批次。`verify-fixes` 会重新检查标记为 `fixed_pending_verification` 的发现，
并将它们移动到 `fixed_verified` 或 `reopened`。只有在所需的
覆盖率完成、活动发现已关闭、并且 `status` 报告
`can_finalize: true` 之后，`finalize` 才会成功。
## 这与 AI 审查工具有何不同？
AI 审查工具通常根据 diff 生成评论。而 Review Gauntlet 起步得更早：
它会创建一个审查计划。它将文件与审查规则交叉以构建
覆盖率矩阵，然后针对所需的单元格运行审查器，
并为每个完成的审查义务记录证据。
| 工具类型 | 主要工作 |
|---|---|
| Codex Review / Open Code Review / opencode | 生成审查评论 |
| 静态分析器 | 检测已知的规则违规 |
| Review Gauntlet | 计划审查，构建文件 × 规则矩阵，跟踪覆盖率，保留证据，并把控最终确认关卡 |
Review Gauntlet 旨在与审查器协同工作，而不是与它们竞争。
## 工作原理
Review Gauntlet 使代码审查变得计划优先且可审计。
1. 定义审查范围
- 文件、目录、diff、commit 或其他审查目标
2. 定义审查规则
- 安全性、正确性、可维护性、架构、项目特定检查或自定义规则
3. 构建审查矩阵
- 每个文件 × 规则对成为一个审查单元格
4. 运行审查器
- AI 审查器、静态分析器、opencode、Codex 风格的代理或自定义 adapter 检查分配的单元格
5. 跟踪证据和发现
- 记录 prompt、输出、发现、覆盖率状态和未解决的问题
6. 仅在完成后进行最终确认
- Review Gauntlet 仅在所需的覆盖率完成且活动发现已关闭时才进行最终确认
## 在运行审查之前
审查会话不能仅靠 CLI 运行。请先安装所有必需的组件：
1. 安装 `review-gauntlet` CLI
2. 安装并配置外部审查代理 CLI
3. 为该代理安装匹配的 Review Gauntlet 技能或 prompt 指南
4. 添加一个可被发现的 adapter 配置，例如 `review-gauntlet.jsonc`
### 安装 CLI
```
uv tool install review-gauntlet
```
### 安装技能
安装 Review Gauntlet 代理技能：
```
npx skills add tumf/review-gauntlet
```
### 创建 adapter 配置
Review Gauntlet 会自动从
`.review-gauntlet/config.jsonc`、`review-gauntlet.jsonc` 或 XDG 用户配置
目录中发现配置。已安装的包中内置了启动预设，因此首次使用的用户
无需任何额外设置即可创建配置。
创建项目配置：
```
review-gauntlet config init --preset opencode
```
或者创建一个全局默认配置：
```
review-gauntlet config init --global --preset opencode
```
检查可用的预设并验证有效的配置：
```
review-gauntlet config preset list
review-gauntlet config preset show opencode
review-gauntlet config validate
review-gauntlet config effective --format json
```
使用 `--force` 覆盖现有的生成配置，使用 `--dry-run` 预览
写入目标和预设内容而不创建文件，使用 `--output ` 写入
到自定义路径。如果你的代理命令或参数不同，请编辑生成的 JSONC，然后
验证 `review-gauntlet review` 是否可以端到端运行。
```
uvx review-gauntlet config init --preset opencode
# （单独安装并认证匹配的外部 review agent）
review-gauntlet init
review-gauntlet run
review-gauntlet status
```
`uvx review-gauntlet config init --preset opencode` 是基于包的启动流程。
对于日常使用，请使用 `uv tool install review-gauntlet` 安装 CLI，以便可以使用相同的
命令作为 `review-gauntlet`。
## 安装
对于日常使用，将 CLI 安装为 `review-gauntlet`：
```
uv tool install review-gauntlet
review-gauntlet --help
```
## 从源码安装
当你想要最新的 GitHub 版本或想要贡献代码时使用此方法：
```
git clone https://github.com/tumf/review-gauntlet.git
cd review-gauntlet
uv sync
make install
review-gauntlet --help
```
`make install` 使用 `uv tool install --reinstall .` 将本地包安装为标准的
`review-gauntlet` 命令。
## 基本用法
首先选择一个明确的审查目标，然后使用 `run` 通过配置的外部代理执行准备就绪的任务，直到会话完成确认：
```
# 审查当前 workspace diff。
review-gauntlet init --worktree
# 或审查 branch/range。
review-gauntlet init --from main --to HEAD
# 或审查完整的 repository。
review-gauntlet init --all
# 推荐：运行就绪任务直到活跃的 session finalize。
review-gauntlet run
# 在调试或审计结果时检查 state 和 findings。
review-gauntlet status
review-gauntlet findings
# 放弃误操作的 init，而不写入 checkpoint。
review-gauntlet cancel
# 可选的隔离工作流：为 session 创建 Git branch 和关联的 worktree。
review-gauntlet init --git-worktree
review-gauntlet run
review-gauntlet finalize --merge
```
`run` 是正常的推进命令。它不会改变 `review` 基于基本规则的行为：
`review` 每次调用只精确推进一个审查批次，而
`run` 通过外部代理协调重复的就绪任务执行。`finalize`
仍然是一个关卡，而不是清理命令：在所需的覆盖率完成
并且活动发现关闭之前，它都会失败。仅使用 `cancel` 放弃意外的 `init`；它会
将会话标记为 `cancelled` 并清除活动会话标记，而不会生成
checkpoint artifacts。
`--worktree` 和 `--git-worktree` 是刻意设计的不同概念。`init
--worktree` 选择当前工作区的 diff 作为审查目标。`init
--git-worktree` 在
`.review-gauntlet/worktrees//` 下创建一个隔离的 Git 链接工作树，并创建一个 `review-gauntlet/` 分支
用于该会话。可以将它们组合为 `init --worktree --git-worktree`，在隔离会话工作的同时
审查工作区的 diff。对于基于 Git-worktree 的会话，
`run` 默认在链接的会话工作树内执行配置的外部代理，因此源码的读取和编辑都发生在会话分支上。Review Gauntlet 的
持久状态，包括运行日志、账本、活动会话标记和 checkpoints，
继续存在于基础仓库的 `.review-gauntlet` 目录下。`finalize
--merge` 写入 checkpoint artifacts，提交会话分支，将其快进合并到记录的基准分支，移除链接的工作树，并删除
会话分支。如果合并成功但清理失败，命令会报告
`cleaned_up: false`，包含清理障碍，并留下 `next_required_action:
cleanup_git_worktree` 以供手动修复。
### 高级 `ready` 用法
`ready` 为 CI 系统、自定义编排器、外部
集成和调试打印下一个审查 prompt。当你想在 Review Gauntlet 之外拥有编排循环时使用它：
```
review-gauntlet ready | opencode run
```
自定义编排器可以重复调用 `ready`，但这不再推荐作为日常的
工作流；对于正常的会话推进，首选 `review-gauntlet run`。
## Shell 补全
已安装的 `review-gauntlet` 命令可以为常见的
交互式 shell 生成补全脚本。为当前会话执行该脚本，或者将其写入 shell 启动文件加载的
位置。
Bash：
```
source <(review-gauntlet completion bash)
```
Zsh：
```
review-gauntlet completion zsh > "${fpath[1]}/_review-gauntlet"
autoload -Uz compinit && compinit
```
Fish：
```
review-gauntlet completion fish > ~/.config/fish/completions/review-gauntlet.fish
```
## 命令
目标选择在 `init` 时发生；`review` 仅推进一次活动会话。
普通的 `init` 现在在存在完整可用 checkpoint 时使用 `.review-gauntlet/checkpoints/latest/status.json`，
从其 `review_base_commit` 审查到 `HEAD`。如果不存在 checkpoint，普通的 `init` 会审查所有符合条件的文件。需要先前工作区 diff 默认行为的脚本必须显式传递 `--worktree`。
兼容 OCR 的目标映射为：
```
# 默认审查：最新 finalized 的 checkpoint -> HEAD，或首次审查的所有文件。
review-gauntlet init
# OCR workspace diff 审查：staged、unstaged 和 untracked 的 non-ignored 文件。
review-gauntlet init --worktree
# OCR branch/range 审查：两个 refs 之间发生变化的文件。
review-gauntlet init --from main --to HEAD
# OCR single-commit 审查：由一个 commit 改变的文件。
review-gauntlet init --commit
# review-gauntlet-only 全 repository 审查：每个符合条件的 inventory 文件。
review-gauntlet init --all
# 推荐：使用配置好的 external agent 编排就绪任务。
review-gauntlet run
# 针对底层/自定义工作流执行确切的单一 review step。
review-gauntlet review
# 在此次运行中选择最多 20 个 cells，并同时执行最多 4 次 adapter 调用。
review-gauntlet review --budget 20 --concurrency 4
```
在运行或审查步骤之后，检查会话状态和发现，可选地记录人类的
发现决定，并且只有在覆盖率和发现都关闭后才进行最终确认：
```
review-gauntlet status
review-gauntlet findings
review-gauntlet mark fixed --reason "fixed in follow-up"
review-gauntlet verify-fixes
review-gauntlet finalize
# Finalize 以原子操作写入 Git 可审查的 JSON/Markdown snapshots。
git add .review-gauntlet/checkpoints/latest
# 如果 init 错误地指向了目标，请取消而不是 finalize。
review-gauntlet cancel
```
`cancel` 是放弃由于错误初始化的活动会话的受支持方式。它在账本中记录 `sessions.state = 'cancelled'`，并移除
`.review-gauntlet/active-session.json`，因此在新的 `init` 之前，后续的 `status`、`review` 和 `ready`
命令表现为无活动会话。与 `finalize` 不同，它不会写入 checkpoints 或声称审查已完成。
`status` 将 `coverage` 报告为按状态划分的审查单元格计数：
| 覆盖率状态 | 含义 |
|---|---|
| `pending` | 文件 × 规则单元格仍需审查。 |
| `reviewed` | 该单元格已根据当前文件摘要进行了审查。 |
| `stale` | 文件在审查后发生了更改，因此该单元格必须重新审查。 |
| `superseded` | 旧的持久化单元格不再是当前目标计划的一部分。 |
`findings` 默认报告开放的发现；传递 `--all` 以包含终止的
发现。每个发现行包括：
| 字段 | 含义 |
|---|---|
| `finding_id` | 稳定的 Review Gauntlet 发现 ID，例如 `RGF-...`。 |
| `fingerprint` | 从仓库、目标、路径、规则、声明、代码锚点和规则集派生的去重键。 |
| `state` | 发现的生命周期状态。开放状态为 `untriaged`、`confirmed`、`fixed_pending_verification` 和 `reopened`；终止状态为 `fixed_verified`、`false_positive`、`waived` 和 `accepted_risk`。 |
| `path` | 最新出现的仓库相对文件路径。 |
| `rule_id` | 产生该发现的审查规则。 |
| `content` | 审查器提供的发现文本。 |
| `metadata` | 人类决策记录的 JSON 元数据，例如所有者或到期时间。 |
| `start_line` / `end_line` | 最新行范围，或者在无精确范围时为 `0`。 |
| `imprecise` | 最新位置是否为近似值。 |
成功的 `finalize` 要求覆盖率和活动发现均已关闭，并且
审查范围的文件与 `HEAD` 匹配；脏的已跟踪、已暂存、未暂存或未跟踪的符合条件的文件将阻止 checkpoint 创建。它会在生成的 checkpoint 目录下（例如 `.review-gauntlet/checkpoints//`）写入
`status.json`、`findings.json`、`events.json` 和 `summary.md`，然后更新
`.review-gauntlet/checkpoints/latest` 作为指向该 checkpoint 的指针，并清除
活动会话，以便下一个命令是 `review-gauntlet init`。这里刻意设计为没有单独的 checkpoint 命令。
`review --concurrency` 默认为 `8`，且必须是正整数。`--budget`
仍然限制为一次审查运行选择的单元格总数；`--concurrency` 仅限制
这些选定的 adapter 调用中有多少同时运行。它不会
自动将并发标志传递给嵌套的外部 adapter
命令。
### 诊断和遗留计划命令
`inventory`、`plan` 和 `report` 命令仍可用于兼容
和检查。使用它们来检查文件发现、审查切片和报告
渲染；它们不是正常的日常审查生命周期。
检查当前仓库清单和分类：
```
review-gauntlet inventory
```
检查带有切片和所需检查的遗留审查计划：
```
review-gauntlet plan
```
渲染遗留的 Markdown 矩阵报告：
```
review-gauntlet report
```
## 默认文件过滤
清单发现保持 Git 行为完整：基于 Git 的仓库仍然使用
`git ls-files --cached --others --exclude-standard` 和现有的有限
子进程超时，因此 `.gitignore` 和其他 exclude-standard 规则在
review-gauntlet 的内置过滤器之前生效。
内置的 artifact 过滤器从完整清单和目标范围的清单中移除生成的或依赖的路径。这包括 Python/编辑器/缓存输出，
例如 `.review-gauntlet/`、`__pycache__/`、`.ruff_cache/`、`build/`、`dist/`、
`wheels/`、`htmlcov/`，以及受 OCR 启发的依赖/构建暂存路径，例如
`vendor/`、`node_modules/`、`target/`、`.happypack/`、`.cachefile/`、`_packages/`、
`rpm/`、`pkgs/` 和 `oh_modules/`。
审查会话在创建单元格和
摘要时应用额外的默认审查路径过滤器。文件可以在一般清单中保持可分类，但 `init` 默认会忽略
`openspec/`、`tests/` 和 `docs/`，以及常见的 OCR 风格的测试或
生成的路径，例如 `__tests`、`*_test.go`、`*Test.java`、`*Test.kt`、
`*.spec.ts`、`*.test.tsx`、`test_*.py`、`*_spec.rb`、`*.spec.ets` 和
`*.test.ets`。审查单元格和目标摘要还忽略常见的 package 清单
和 lock 文件，例如 `uv.lock`、`poetry.lock`、`requirements*.txt`、
`package.json`、`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`Cargo.toml`、
`Cargo.lock`、`go.mod`、`go.sum`、`pom.xml`、`Gemfile.lock`、`composer.lock`、
`Package.resolved`、`pubspec.lock`、`mix.lock`、`vcpkg.json`、`flake.lock`、
`stack.yaml.lock`、`Manifest.toml` 和 `renv.lock`。这些 package 文件并没有
从一般清单中移除，除非有其他 artifact 或 Git 忽略规则排除了
它们。正常的源码文件和与 package 相邻的可执行逻辑文件，例如
`setup.py`、`build.gradle`、`mix.exs` 和 `build.zig` 仍然有资格进行审查
单元格。
`review` 按以下顺序发现配置：显式 `--config`、
`.review-gauntlet/config.jsonc`、`.review-gauntlet/config.json`、
`review-gauntlet.jsonc`、`review-gauntlet.json`、
`$XDG_CONFIG_HOME/review-gauntlet/config.jsonc`，然后是
`$XDG_CONFIG_HOME/review-gauntlet/config.json`。当 `XDG_CONFIG_HOME` 未设置
或为空时，全局回退基准是 `~/.config`，因此 JSONC 回退路径是
`~/.config/review-gauntlet/config.jsonc`。仓库本地配置始终
优先于全局 XDG 配置，并且发现机制只读取现有文件；它
从不创建全局配置目录或文件。命令 adapter 使用 argv
数组，从不使用 shell 字符串；provider 登录、模型选择和密钥保留在
外部 CLI 配置内。
用于 opencode 基于 JSON 文件判定的最小 JSONC 配置：
```
{
"adapter": {
"type": "command",
"command": "opencode",
"args": ["run", "{prompt}"],
"output": {"mode": "file-json", "path": "{output_file}"}
}
}
```
生成的 OCR prompt 作为单个 argv 元素被扩展到 `{prompt}` 中。Prompt
artifacts 仍然作为审计证据被写入，但 prompt-file 传输不是
命令 adapter 契约的一部分。`cwd`、`env` 和 `timeout_seconds` 是
可选的应急手段：省略 `cwd` 时继承调用者的当前工作
目录，省略 `env` 时继承父环境且没有固定的自动
变量，显式 `env` 值会覆盖继承的环境，省略
`timeout_seconds` 时默认为 600 秒。
当配置的代理命令需要应随 Review Gauntlet 配置一起携带的环境变量时，请使用 `adapter.env`，例如模型选择、
feature 标志或特定于 wrapper 的路径：
```
{
"adapter": {
"type": "command",
"command": "opencode",
"args": ["run", "{prompt}"],
"env": {
"OPENCODE_MODEL": "anthropic/claude-sonnet-4",
"REVIEW_GAUNTLET_REPO": "{repo_root}",
"REVIEW_GAUNTLET_STATE": "{state_dir}"
}
}
}
```
环境变量使用与 adapter
参数相同的模板语法进行扩展。它们被添加到父进程
环境之上，因此它们也可以覆盖继承的变量。将 provider 凭据保留在外部 CLI
或密钥管理器中，而不是将它们提交到项目配置中。
判定必须是带有 OCR 风格注释的 JSON：
```
{"comments":[{"path":"src/app.py","content":"Issue","start_line":1,"end_line":1}]}
```
支持的模板变量包括 `{repo_root}`、`{state_dir}`、`{run_id}`、
`{run_dir}`、`{cell_id}`、`{cell_dir}`、`{prompt}`、`{output_file}`、
`{file_path}` 和 `{rule_id}`。
## 开发者工作流
```
uv sync
make check
make format
make lint
make typecheck
make test
make coverage
```
## 设计
Review Gauntlet 将审查视为有状态的覆盖率工作流：
- 从显式目标集初始化会话
- 将符合条件的文件分类为审查切片和覆盖率单元格
- 通过外部命令 adapter 每次只运行一个审查步骤
- 将 prompt、输出、发现和覆盖率状态记录为审计证据
- 仅在所需的覆盖率和活动发现关闭后才进行最终确认
外部审查工具通过命令 adapter 进行集成，而不是通过
硬编码的运行器。该 adapter 接受 argv 数组，将审查 artifacts 扩展为
安全的模板变量，并支持写入 stdout 或文件的 JSON 判定，因此
诸如 opencode、Codex 风格的工具、静态分析器或自定义 wrapper 等 CLI 可以
参与，而无需 review-gauntlet 管理 provider 登录或密钥。
标签：AI编程助手, DevOps工具, LNA, 云安全监控, 代码审查, 工作流编排, 文档结构分析, 自动化审查, 逆向工具, 静态分析