Hungsiro506/x-review

# x-review 针对 git 分支的多模型代码审查。它会在你的改动上运行多个 AI 模型，让它们展开辩论并用代码支撑每一个论断，最终为你提供一份排名靠前的审查报告，而不是几份相互冲突的报告。 在终端中运行： ``` cd ~/your/repo x-review ``` 或者无需离开 Claude Code 即可运行。安装程序会添加一个 `/x-review` skill，因此你可以在聊天中向 Claude 提供上下文，并让它来驱动： ``` > here's the design doc for this change: . focus on the locking. > /x-review feature/my-branch ``` 该 skill 会从你的会话中收集上下文，并以此运行审查。更多内容请见[从 Claude Code 会话开始](#starting-from-a-claude-code-session)。 ## 为什么 我使用 AI 模型来审查 pull request，却得到了相互矛盾的答案：Claude 标记了一个 data race，而另一个模型则称同一段代码没有问题。因此我不再信任任何单一模型，转而去查看数据。 一项基准测试让五个旗舰级模型（Claude、Gemini、Codex、Qwen、MiniMax）针对 15 个真实的 pull request 进行了测试，这些 PR 都在被合并后遭到回退或热修复，因此每个 PR 都有一个已知的 bug 作为评分标准。在更棘手的 bug（那些需要周边上下文或系统级理解的 bug）上： - 最好的单一模型发现了约 53%， - 五个模型相互辩论五个回合发现了约 80%， - 最难的、系统级的 bug 从偶尔发现变成了 100% 被揪出， - 最大的飞跃在于普通的中级 bug：单一模型仅为 10 个中的 3 个，而辩论组达到了 10 个中的 7 个， - 两个模型组合在一起就已经达到了五模型约 91% 的效果，这就是为什么 x-review 默认使用两个模型。 辩论之所以有效，是因为模型有不同的盲区。一个会阅读调用链和枯燥的错误路径；另一个虽然简练，但能抓住每个人都略过的 off-by-one 错误。让它们争论，并且每个论断都与特定代码行绑定，这比单独运行任何一个模型都能发现更多问题。多个模型达成共识的发现，才是真正值得你花时间关注的。 还有第二个问题：辩论可能会产生更多而非更少的阅读量。因此，最后一步反其道而行之。它将整个论点浓缩为一个排名列表（从 Blocker 到 Low）、一份简短的通俗易懂的总结、一个提供给代码修复者的详细部分，以及一个合并决定。你只需要阅读结论，而不是来回的争论。 ## 工作原理 三个步骤： 1. 每个模型都会自行审查 diff 和更改过的文件，以及你提交的任何上下文（设计文档、ticket、重点关注说明）。 2. 每个模型都会看到其他模型的发现（匿名化）并进行修正。它只能在有代码证据的情况下放弃某个观点，同时提出它注意到的任何新问题。 3. 一个模型负责合并结果、去除重复项、进行排名，并编写包含合并决定的最终报告。随后，一次确定性的检查过程会强制执行你设置的任何已编码的[rules](#rules--codified-standards-caught-every-time)： 确认的 `blocks_merge` 违规会将判定强制更改为 `REQUEST CHANGES`。 审查器仅仅是一个模型 CLI、一个简短的角色设定，以及一些包含审查知识的 markdown “skill packs”。只需放入一个文件即可添加 skill；添加一个配置项即可添加模型。该工具是与供应商无关的；没有任何内容被硬编码到特定模型上。 项目 **rules** 在此基础上添加了基于路径范围的团队标准 —— 请参阅 [Rules](#rules--codified-standards-caught-every-time)。 ## 安装 **最快方式：一行命令。** 如果你已经安装并登录了 `claude` 和/或 `codex`，这将一次性安装 `x-review` 命令和 `/x-review` Claude Code skill： ``` curl -fsSL https://raw.githubusercontent.com/Hungsiro506/x-review/main/get.sh | bash ``` 它会将 x-review 克隆到 `~/.local/share/x-review`，安装命令并添加该 skill。随时重新运行同一行命令即可进行更新。然后检查它是否正常工作： ``` x-review --list-skills # prints: concurrency, general, go, python ``` 如果打印出了 skill 列表，说明你已经完成了；直接跳到[快速开始](#quick-start)。 如果提示 `x-review` “command not found”，安装程序会打印出一行需要添加到你的 shell rc 文件中的 `PATH`。想要手动安装或先阅读脚本？下面的步骤执行的是完全相同的操作。 **1. 前置条件。** 你需要 `python3` (3.10+) 和 `git`，以及至少一个已安装并登录的审查器 CLI： - [`claude`](https://claude.com/claude-code) (Claude Code) - [`codex`](https://developers.openai.com/codex/cli) (Codex CLI) 辩论需要**两个不同的供应商**才能发挥良好效果，因此建议两者都安装。但如果你目前只有一个，也不会被阻塞：请参阅下文的[只有一个模型？](#only-have-one-model)。检查你拥有的工具： ``` python3 --version claude --version # at least one of these two codex --version ``` **2. 安装 x-review。** ``` git clone https://github.com/Hungsiro506/x-review cd x-review bash install.sh # installs the `x-review` command + the Claude Code skill ``` `install.sh` 会依次尝试 `pip install -e .`，然后是 `pipx`，最后是一个独立的启动垫片，因此它在你从 Homebrew 或最近的 Debian/Ubuntu 获得的“外部管理”的 Python (PEP 668) 上也能正常工作，在这些环境中，单纯的 `pip install` 是被阻止的。 **3. 确保它位于你的 PATH 中。** 如果安装程序打印出类似 `⚠ 'x-review' not on PATH yet` 的行，请运行它显示的 `export PATH=...`（并将其添加到你的 `~/.zshrc` 或 `~/.bashrc` 中使其永久生效），然后打开一个新的 shell。 **4. 验证（无模型调用，无 API 成本）。** ``` x-review --list-skills # should print: concurrency, general, go, python ``` 如果打印出了 skill 列表，说明该工具已正确安装。如果提示“command not found”，请重新检查第 3 步。 ### 只有一个模型？ 默认情况下会运行 `claude` 和 `codex`。如果只安装了一个，请明确指定它，以便预检不会阻止你： ``` x-review --reviewers claude # or: --reviewers codex ``` 这会运行一次单审查器流程。它仍然会生成一份排名报告，但没有辩论，而辩论才是大部分价值所在。尽可能安装第二个供应商的 CLI。在任何模型运行之前，x-review 都会检查你请求的 CLI，并准确告诉你缺少哪一个以及如何修复，因此你永远不必等待几分钟才发现缺少登录凭据。 ## 快速开始 你的首次审查：进入任何 git 仓库，切换到一个包含一些改动的分支，然后运行该命令。 ``` cd ~/your/repo git switch -c my-change # or just be on an existing feature branch with commits # ... 进行或已经进行一些更改 ... x-review ``` 它会在运行过程中打印进度。根据改动的大小和轮次，预计花费的时间从不到一分钟到几分钟不等，并且它在运行期间会消耗你的 `claude`/`codex` 额度。完成后，排名报告将被打印并保存在 `~/.cache/x-review/...` 下。 更多调用方式： ``` cd ~/any/repo x-review # current branch vs auto-detected base (+ uncommitted work) x-review feature/foo # a specific branch x-review --base develop # override the base branch x-review HEAD~3..HEAD # explicit commit range x-review --deep # more rounds + all configured reviewers x-review --skills go,concurrency --rounds 3 x-review --explore # let reviewers walk the live repo (read-only) x-review --context "focus on the redis counter race" # free-form guidance x-review --context-file design-doc.md # hand in a spec/doc x-review --list-skills x-review --list-rules # show resolved project rules (no model calls) x-review --rules team.yaml --rounds 3 # add codified rules for this run x-review --no-rules # ignore project rules for this run ``` 在 Claude Code 中你可以运行 `/x-review`：它会从你的会话中收集上下文（你粘贴的文档、ticket、重点关注说明），使用该上下文运行审查，带回报告，并帮助你在同一会话中修复问题（“fix #2”）。 报告会输出到 stdout，同时保存在 `~/.cache/x-review///.md` 下。被审查的仓库中不会写入任何内容。 ## 从 Claude Code 会话开始 有两种方式可以运行审查：`x-review` 命令，或者 Claude Code 内部的 `/x-review` skill。该 skill 由 `install.sh` 为你安装，并且它符合通常启动审查的方式：你已经在与 Claude 谈论某个改动，你打开了设计文档或 ticket，而你希望在不离开对话的情况下获得第二意见。 在 Claude Code 会话中： 1. 给它分支和你拥有的任何上下文。粘贴设计文档，链接 ticket，说明关注重点。你只需要正常交流。 2. 运行 `/x-review `（对于当前分支则使用 `/x-review`）。 3. 该 skill 从你的对话中收集上下文，将其写入文件，并使用 `--context-file` 调用 `x-review` CLI，以便每个委员会成员都能看到你给 Claude 的相同上下文。 4. 它会流式传输进度，带回排名报告，当你选择某个发现（“fix #2”）时，它会在你的工作区中进行更改。然后你可以重新运行以确认。 会话负责收集上下文并进行驱动；CLI 运行真正的跨供应商委员会（Claude + Codex）。除非你主动要求，否则任何内容都不会被发送到外部。 **从 Cursor 或其他终端 agent 运行。** 该 skill 是 Claude Code 特有的，但该命令可以在任何地方使用。在 Cursor 的终端（或任何 shell）中运行 `x-review --context-file notes.md`，然后让你的 agent 读取保存在 `~/.cache/x-review/...` 下的报告并应用修复。 ## 目标解析的工作原理 - `target` 是分支参数，否则为当前分支。 - `base` 是 `--base`，否则为自动检测到的默认分支 (`origin/HEAD`)。 - diff 为 `base...target`（merge-base 三点差异），这样已经前进的 base 就不会污染审查结果。 - 未提交的工作区更改仅在审查当前分支时才会被包含，也就是“审查我正在处理的内容”这种情况。 ## 为审查器提供上下文 你通常审查的方式是：打开 Claude 或 Cursor，给它分支，并添加一些上下文或指导。x-review 直接支持这一点。你传递的任何内容都会被放置在 prompt 的顶部，并交给**每一个**委员会成员（以及 synthesizer），因此它们都从相同的理解出发。 ``` x-review feature/foo --context "this PR lazy-loads PKs; watch the fetch ordering" x-review feature/foo --context-file design-doc.md # a spec or ticket cat ticket.md | x-review feature/foo --context - # from stdin ``` 这两个 flag 可以重复和组合。陈述的设计意图被视为检查 diff 的规范；重点说明缩小了审查器的关注范围，但不会阻止它们报告其他任何问题。上下文在 prompt 预算中有自己的份额，因此大型文档永远不会挤占 diff 的空间。 在 Claude Code 会话中，这是自动完成的：`/x-review` 收集你在对话中积累的上下文，将其写入文件，并通过 `--context-file` 传递。会话收集上下文并进行驱动；CLI 运行跨供应商委员会。 ## 扩展它 你可以在不改动其代码的情况下扩展该工具： - **添加 skill pack。** 将一个 markdown 文件放入 `~/.config/x-review/skills/.md`（或打包的 `xreview/data/skills/`），并通过 `--skills`、仓库本地的 `.x-review.yaml` 或配置中的 `skill_defaults` 来引用它。Skill pack 是你向审查器传授架构规则、领域知识或反复出现的 bug 的方式。 - **添加 rule。** 在 `~/.config/x-review/rules/.yaml`（或你仓库的 `.x-review/rules/`）中放入一个 YAML 文件，以编纂基于路径范围的团队标准。请参阅 [Rules](#rules--codified-standards-caught-every-time)。无需更改代码。 - **添加审查器。** 在配置文件中的 `reviewers:` 下添加一个条目。如果它的 CLI 调用方式与其他不同，请在 `xreview/reviewers.py` 中添加一个分支。 - **设置每个仓库的默认值。** 在仓库根目录提交一个 `.x-review.yaml`： reviewers: [claude, codex] skills: [general, concurrency] - **全局覆盖。** 将 `config.yaml` 放入 `~/.config/x-review/` 即可更改审查器和默认设置，而无需编辑软件包。 ## Rules —— 编码的标准，每次都能捕获 辩论是对 **recall** 的押注：更多的模型、更多的争论，能抓住更多单一模型遗漏的问题。但辩论无法评判你的团队已经写明的标准 —— 分层边界、被禁的 import、每个人都知道但模型无法知晓的规则。那是一个 **precision** 问题，而大规模的 precision 正是阿里巴巴开源的 [Open Code Review][ocr] (OCR) 旨在解决的问题。 OCR 绝非玩具。它起初是阿里巴巴集团的内部 AI 代码审查助手，在数以万计的开发者中运行了两年，在被开源前标记了数百万个缺陷。在一项包含 10 种语言的 50 个仓库中 200 个真实 PR 的基准测试中（1,505 个真实问题由 80 多名资深工程师交叉验证），通过有意地牺牲 recall 换取 precision，它在相同模型上比通用 agent 实现了更高的 Precision 和 F1，并且只使用了大约 **1/9 的 token**。它的核心杠杆是确定性的、基于路径范围的规则检查。 x-review 为其规则层借鉴了这一杠杆，**而没有**采用 OCR “让规则凌驾于模型之上”的立场。这两个工具处于截然相反的两端，却又相辅相成：OCR 最大化单一模型的 precision，而 x-review 最大化多个模型的 recall。将 OCR 风格的规则引入辩论让你可以鱼与熊掌兼得：辩论依然能发现任何规则都未预料到的问题，同时每次都能捕获已编纂的标准。 规则是一个知道它适用于哪些文件的 skill pack，加上可选的评分元数据： ``` rules: - id: go-domain-no-infra match: "**/domain/**/*.go" # ** crosses dirs, * within a segment, {a,b} alternates severity: high # optional: blocker|high|medium|low blocks_merge: true # optional text: "Domain layer must not import infrastructure packages (db, kafka, http clients)." ``` ### 你将获得什么 - **辩论的共享评分标准。** 匹配的规则会与 skill packs 一起注入到每个审查器中。一个发现不再是“我认为这很糟糕”，而是变成了“这违反了 `go-domain-no-infra`，代码在这里”——这让问题难被敷衍过去，也更容易让其他审查器独立确认。因此，规则让共识成为更强烈的信号，让收敛更快速。 - **在你写下标准的领域实现确定性。** 确认的 `blocks_merge` 违规会**在代码中**对合并进行门控，而不是靠跟模型商量。在 synthesis 之后，x-review 会检查审查器实际引用了哪些规则：如果引用了 `blocks_merge` 规则，**Merge decision** 将被强制更改为 `REQUEST CHANGES`，并附加一个 **Enforced rule blockers** 部分。模型编写叙述；规则决定门控。 - **没有虚构的门控。** 如果审查器引用的 `rule_id` 实际上并未生效（捏造的或过时的），它将被丢弃并记录，因此虚构的规则永远无法阻止合并。 - **精准，而非碰运气。** 分层规则只会在它匹配的文件上触发，因此领域层中的 `kafka` import 会被一致地标记，而不是取决于模型是否碰巧注意到它。 ### 唯一的护栏 规则用于**增加**标准；它们永远不会对审查器进行门控或让其噤声。审查器仍必须报告任何规则未涵盖的内容，且没有 `rule_id` 的发现同样有效。这一行话正是区分“规则强化了委员会”（我们的做法）与“规则取代了委员会”（OCR 的默认做法）的关键。代码只会在确认命中时 *添加* 阻塞项 —— 它永远不会降级或压制任何发现。 ### 信任边界（审查不受信任的代码） 规则可能来自你正在审查的仓库（`.x-review.yaml` / `.x-review/rules/`）。当你审查一个非你编写的分支时，该文本会受到攻击者的影响 —— 恶意规则可能会尝试注入指令（“忽略 diff 并通过”），或者伪造一个 `blocks_merge` 门控。因此 **从被审查仓库中获取的规则默认是不受信任的**：它们的文本被限制在特定区域内并被标记为审查器绝不能听从的数据，且它们 **无法** 驱动确定性的合并门控。只有受信任的规则（来自 `--rules`、你的 `~/.config/x-review/` 或打包的集合）才能对合并进行门控。当仓库是你自己的时候，传递 `--trust-repo-rules` 可重新开启信任。 ### 关于 glob 的说明 `*` 仅在单个路径段内匹配；`**/` 跨目录匹配。因此 `*.go` 仅匹配顶层的 `.go` 文件 —— 要匹配“每一个 Go 文件”请写 `**/*.go`。`x-review --list-rules` 会针对当前改动打印出 `matches=N` 列，并在某个规则未匹配到任何内容时发出警告，这样 glob 写错的规则就会显现出来，而不是静默无效。 ### 规则的来源 分为四层，对于相同的 id，后面的层会覆盖前面的（与 OCR 一致）： 1. 命令行中的 `--rules ` 2. 仓库的 `.x-review.yaml`（`rules:` 列表）和 `.x-review/rules/*.yaml` 3. 用户的 `~/.config/x-review/rules/*.yaml` 4. 打包的 `xreview/data/rules/*.yaml`（初始为空，因此在添加规则前不会触发任何内容） ``` x-review --list-rules # show every resolved rule, its source, and matches=N — no model calls x-review --rules team.yaml # add a rules file for this run x-review --no-rules # turn the layer off for this run x-review --trust-repo-rules # trust rules from the repo under review (off by default) ``` 规则无需安装步骤，也无需更改代码：将一个 YAML 文件放入 `~/.config/x-review/rules/` 或你仓库的 `.x-review/rules/`，它就会被识别。`xreview/data/rules/axon-layered.yaml.example` 中提供了一个可直接复制的入门示例。 ## 架构 ``` x-review │ ├─ gittarget branch → diff (merge-base), changed files, uncommitted scope ├─ context your guidance (if any) + diff + full content of changed files; language detection ├─ rules resolve + path-match codified team rules; inject into reviewers ├─ debate round 1 independent → broadcast (anonymized) → revise → … (convergence-stop) ├─ synth cluster + rank + two-audience report + merge decision; enforce blocks_merge rules └─ saved to ~/.cache/x-review/... ``` | 文件 | 职责 | |------|----------------| | `xreview/cli.py` | 参数解析、编排 | | `xreview/gittarget.py` | 分支到 diff 的解析 | | `xreview/context.py` | 上下文打包、语言检测 | | `xreview/reviewers.py` | 模型 CLI 调用 + 输出解析 | | `xreview/debate.py` | 多轮辩论循环 | | `xreview/synth.py` | 最终合并、排名、双受众报告、确定性规则强制执行 | | `xreview/rules.py` | 规则加载（4 层）、glob 匹配、prompt 渲染 | | `xreview/config.py` | 配置 + skill 解析 + 预检 | | `xreview/data/config.yaml` | 审查器、默认值、skill 路由 | | `xreview/data/skills/*.md` | 知识包 | | `xreview/data/rules/*.yaml` | 打包规则（初始为空）+ `.example` 入门示例 | ## 成本 x-review 用金钱和时间换取正确性，因此低成本的路径是默认的，而昂贵的路径则需要你主动选择。 每次运行会发起 `(reviewers × rounds) + 1` 次模型调用。默认的 2 个审查器和 2 轮大约是 5 次调用。`--deep`（3 个审查器，5 轮）大约是 16 次，并且后面的每一轮还会在 prompt 中携带前面的发现，因此 token 成本的增长速度会比调用次数快。一旦发现停止变化，辩论就会提前结束，因此你通常花费的会少于预期。 关于实际耗时的一个参考：在默认设置下，极小的 diff 在不到一分钟内完成，而真实的 24 个文件的改动在 2 轮中花费了大约 11 分钟。金钱成本则是底层模型 CLI（Claude Code、Codex）根据你的套餐收取的费用；x-review 只是调用它们，不额外加价。 上面提到的基准测试就是为什么在重要时刻值得花费更多成本的原因。单次流程能发现显而易见且被广泛认同的 bug（约 53%）。更深入的模式（更多轮次、更多供应商、`--explore`）才能触及系统级 bug，并将检出率推向 80%。在值得的改动上使用它们。 ## 局限性 - 模型输出不是确定性的。将一次运行视为一个强烈的信号，而不是铁证。信任那些由多个审查器独立得出的发现。 - 例外情况是规则：一旦某个 `blocks_merge` 规则被指出遭到违反，合并门控就会在代码中被强制执行，因此这部分判定是可重复的。 - 规则仅在你写明标准的地方提高了 precision。它们不能取代辩论 —— 规则是否被 *违反* 仍然属于从代码中提取的模型判断；x-review 只是将 *后果* 变为确定性的。 - 收益来源于审查器的多样性。如果只有单一供应商，你从中获得的收益就会减少，因此请添加第二个供应商的 CLI，或者改变 skill packs 和 persona。 - 支撑这些数字的基准测试包含了来自一个 Go/C++ 项目的 15 个 PR。其趋势（辩论胜过单一模型，模型有不同的盲区）是经得起考验的；具体的百分比并不是一种承诺。 ## 致谢 多供应商辩论的想法和基准测试数据来自一项公开的代码审查基准测试和报告。x-review 是该想法作为本地 CLI 的一项独立重新实现。（文章链接待添加。） **rules** 层借鉴了阿里巴巴开源 [Open Code Review][ocr] 的 precision 模型，这是一款久经沙场的工具：作为阿里巴巴内部审查助手运行两年，历经数以万计的开发者，标记了数百万个缺陷；并且在一项公开基准测试中（200 个 PR，50 个仓库，10 种语言，1,505 个由 80 多名工程师验证的问题）展现出在仅使用通用 agent 约 1/9 token 的情况下，实现了更高的 Precision 和 F1。x-review 将 OCR 基于路径范围的确定性规则检查融入到了辩论中，从而在不凌驾于审查器之上的前提下强制执行已编纂的标准。x-review 是一个独立项目，不隶属于 Open Code Review 团队，也未获得其认可。 ## License MIT。请参阅 [LICENSE](LICENSE)。

标签：AI辅助编程, DLL 劫持, Git, SOC Prime, 代码审查, 大语言模型, 开发工具, 网络安全研究, 逆向工具