openqodex

OpenQodex：在推送前审查变更

OpenQodex 用一条命令审查变更。它会冻结变更的快照，运行与变更文件匹配的确定性扫描器（gitleaks、semgrep、bandit、hadolint、shellcheck、actionlint、osv-scanner 等），只保留这些扫描器在变更行上报告的内容，然后启动自己的审查器：一个独立的 Claude Code 或 Codex 进程，仅读取该快照。审查器检查每一条扫描发现，获取所有变更行并按固定格式作答；OpenQodex 用脚本检查答案并输出一份报告。无需任何密钥或账户，只需开发者的 Claude Code 或 Codex 登录即可。代码会发送到该登录所用的模型。审查器还可以搜索网页和打开网页，除非在 ~/.openqodex/config.yaml 中设置了 reviewer_web: off。有四个扫描器需要联网，但它们不会发送代码。semgrep 每次运行都会从 Semgrep 注册表下载规则包。当变更涉及依赖文件时，osv-scanner 会将依赖的名称和版本发送到 osv.dev。kubeconform 会下载 Kubernetes 模式。cargo-deny 会下载 RustSec 咨询数据库。使用 --offline 会跳过 semgrep、osv-scanner、kubeconform 和 cargo-deny。

何时运行

• 任何 git push 之前。
• 当开发者要求你审查他们的变更时。
• 当推送被 OpenQodex 钩子阻止或警告时。
• 修复发现后，重新检查变更。

谁来审查

OpenQodex 会为每次审查启动自己的审查器进程，该进程没有本次会话的记忆。你不需要为其启动子代理，也不需要亲自审查变更：只需运行该命令并展示其输出。

如果 review 显示“完整审查不可用”并打印了一种用你当前所在的代理进行审查的方法，请按照指示操作：运行它命名的命令，并按照它打印的简要说明执行。

操作步骤

当文件 ~/.openqodex/bin/openqodex 存在时，使用它来替代本技能所有命令中的 npx -y openqodex@<version>：它是 openqodex init 安装的副本。当该文件不存在时，表示本技能是单独安装的，没有推送检查：在首次审查之前，在仓库中运行一次 npx -y [email protected] init --yes --agent <host>，其中 <host> 是你所使用的代理（claude-code、codex、cursor 或 cline）。它会为你安装 OpenQodex，然后在审查器可以启动时审查变更，所以可能需要几分钟。请在后台运行它并等待其退出。当它打印出 First review: finished 时，该行上方的收据就是本次审查的结果：按照步骤 3 的说明展示它，然后从步骤 4 继续。

1. 在仓库中运行：

   npx -y [email protected] review
   

   它将审查变更：未推送的提交以及所有未提交的内容，包括未跟踪的文件。要审查整个仓库，请运行：

   npx -y [email protected] review --all
   

2. 等待它完成。一次审查可能需要几分钟。OpenQodex 会在 30 分钟后停止审查器，使用 --all 时则为 2 小时后。许多代理会提前停止命令。所以请在后台运行它并等待其退出。审查器工作时，每隔 15 秒会在 stderr 上打印一行进度。不要在它运行时第二次启动它。

3. 按原样向开发者展示其打印的收据：verdict、每行一个发现（编号、严重性、类别、标题、文件和行号）以及 report.html 的绝对路径。不要重新措辞、缩短或添加你自己的发现。将 report.html 路径提供给开发者：该页面会显示每个变更文件，每个发现位于其代码行下方。当收据以 Observations (do not count toward the verdict): 结尾且下方有带编号的行时，也按原样展示这些行。观察项是风格、命名、文档或测试方面的注释。除非开发者指定了其编号，否则它们不是需要修复的发现。

4. 询问开发者：“全部修复，还是告诉我哪些？” 在他们回答之前不要更改任何代码。如果他们已告诉你要修复什么，例如“审查并修复所有内容”，则直接执行，无需再次询问。

5. 只修复他们指定的发现。通过收据中的编号打印这些发现的完整信息（位置、问题、为什么重要、修复方法和来源）：

   npx -y [email protected] findings 1,3
   

   findings all 会打印所有发现。修复完成后，再次运行审查并向开发者展示新的收据。

6. 根据退出代码执行操作：

   • 0：审查完成，没有任何内容阻止推送。
   • 1：审查完成，其 verdict 为 blocked。不要推送。向开发者展示收据并询问要修复哪些发现；只有当他们看到发现后明确表示可以推送时才推送。
   • 2：没有完整的审查。输出会说明缺少什么（例如“完整审查不可用”表示无法启动审查器，或“审查不完整”并附带原因）。准确告知开发者。切勿将扫描器输出作为审查结果呈现。

审查分支或 Pull Request

当开发者要求你审查一个非当前工作的分支或 Pull Request 时，请指定它：

npx -y [email protected] review feature/login
npx -y [email protected] review '#42'

对 #42 加引号：在 shell 中 # 会开始一个注释。Pull Request 链接也可以。OpenQodex 会获取目标，在临时文件夹中检出它，并审查它相对于其基础分支新增的内容。这是别人的代码：永远不要运行其测试、脚本、构建或服务，也不要编辑它。

规则

• 在审查期间绝不编辑代码。先审查，展示收据，然后只修复开发者指定的发现（步骤 3 到 5）。
• 未经询问开发者，绝不运行 openqodex trust。它会批准一个自定义扫描器，这是一个会在其机器上运行的命令。
• 绝不设置 OPENQODEX_SKIP。这是开发者的开关，不是你的。
• 当 OpenQodex 打印出它为你代理写入的文件来自旧版本且 init 会刷新它们时，用一句话告知开发者并提供该 init 命令。只有当他们要求你运行时才运行它：它会重写他们的代理文件。
• 当 verdict 为 blocked 时，除非开发者在看到发现后明确表示可以推送，否则不要推送。
• 当 OpenQodex 打印出“OpenQodex 遇到了问题。未发送任何内容。”并附有 1 create a GitHub issue 和 2 ignore 时，用一句话告知开发者发生了什么问题，并给他们两个选项。永远不要自己选择 1。如果他们选择 1，在相同目录下运行 npx -y [email protected] report --send-last。其他任何情况都表示选择 2：不做任何操作。

阅读报告

• 报告位于仓库中的 .openqodex/reviews/<时间>-<ID>/ 目录下：report.html 用于在浏览器中打开（每个变更文件显示为差异对比，每个发现位于其代码行下方，然后是覆盖率、扫描器和爆炸半径），report.md 用于以文本方式阅读，report.json 和 report.sarif 用于工具处理。收据会给出 report.html 和 report.md 的绝对路径。.openqodex/latest.json 指向最新的审查结果。报告不会出现在 git status 中：.openqodex/.gitignore 会将其排除。该文件夹中的另外两个文件 config.yaml 和 custom-instructions.md 属于团队，应被提交。
• verdict 为 passed（有或没有警告）或 blocked。只有当仓库的配置（.openqodex/config.yaml 或根目录的 .openqodex.yaml）设置了 block_on_severity 且某个发现达到或超过该级别时，才会是 blocked。如果没有配置，OpenQodex 会发出警告但不会阻止。
• 完整的审查意味着每个阶段都已运行，每个扫描器发现都已被检查，并且每个变更行都已提供给审查器；任何未涵盖的内容都会在报告中说明。这并不意味着没有遗漏：没有审查能发现所有问题。
• 覆盖率列表会说明每个扫描器是否运行。未运行的扫描器会有一行原因说明：
  • no matching files：变更中没有它可读取的文件类型。
  • installing：正在首次下载；下次运行时会包含它。这样告知开发者，而不是等待。
  • not installed：无法在此安装；原因会说明为什么。
  • needs Ruby 或 needs Go：brakeman 需要 Ruby 3.0 或更新版本，rubocop 需要 Ruby 2.7 或更新版本，golangci-lint 需要 Go。OpenQodex 不会安装语言运行时。如果开发者想要这些扫描器，他们需要按系统常规方式安装 Ruby 或 Go（例如在 Mac 上使用 brew install ruby go）并重新运行审查。
  • untrusted：来自仓库配置的自定义扫描器，开发者尚未批准。告知开发者；批准与否由他们决定（npx -y [email protected] trust）。
  • failed：扫描器运行并崩溃了；原因中会有其错误信息。扫描器问题绝不会改变退出代码。

在沙箱内

某些代理会在无法访问网络或无法写入项目外部的沙箱中运行命令。此时首次运行无法下载扫描器，审查器也可能无法连接其模型。告知开发者在他们自己的终端中（代理外部，在仓库内）运行一次：

npx -y [email protected] doctor --install

它会将此仓库文件所需的扫描器下载到 ~/.openqodex/tools/，并说明每个扫描器的原因；--all-scanners 会下载所有扫描器。如果沙箱内的审查仍然显示“完整审查不可用”，开发者需要在自己的终端中运行 npx -y [email protected] review。

更多信息

npx -y [email protected] guide 会打印本指南。npx -y [email protected] guide <主题> 会打印离线文档的某个页面：quickstart、config、scanners、custom-scanners、security、agents、cli、for-agents。for-agents 涵盖安装、配置、自定义扫描器以及每条消息的含义。

在读取大量文件以查找谁调用了某个函数、谁实现了它、两部分如何连接或变更影响了什么之前，你可以使用代码图查询：npx -y [email protected] graph help 列出其问题，或使用 openqodex MCP 服务器的 graph_ 工具（当你的代理拥有它们时）；如果答案是 unknown.floor 为 true，则可能缺少调用者，因此绝不要将其解读为“未使用”。

不要自行向 review.instructions_files 添加文件。询问开发者审查器可能使用哪些文件，然后只设置他们指定的那些。默认值为 []；选择的文件会添加到 .openqodex/custom-instructions.md 中。