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 每次审查都会启动自己的审查器进程，该进程不会记住本会话的内容。不要为它启动子 Agent，也不要自行审查变更：运行命令并展示它输出的内容。

如果 review 提示“Full review unavailable”（无法进行完整审查），并给出使用当前 Agent 进行审查的方法，请按提示操作：运行它指定的命令，并遵循该命令输出的说明。

流程

如果文件 ~/.openqodex/bin/openqodex 存在，请在此技能的每条命令中用它替代 npx -y openqodex@<version>：它是 openqodex init 安装的副本。如果该文件不存在，说明此技能是单独安装的，尚未进行推送检查：首次审查前，请在仓库中运行一次 npx -y [email protected] init --yes --agent <host>，其中 <host> 是你使用的 Agent（claude-code、codex、cursor 或 cline）。它会为你安装 OpenQodex，然后在审查者可以启动时审查更改，因此可能需要几分钟。请在后台运行并等待其退出。当它输出 First review: finished 时，该行上方的回执就是审查结果：按第 3 步所述展示，然后从第 4 步继续。

1. 在仓库中运行：

   npx -y [email protected] review
   

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

   npx -y [email protected] review --all
   

2. 等待审查完成。审查可能需要几分钟。使用 --all 时，OpenQodex 会在 30 分钟后停止审查者，或在 2 小时后停止。许多 Agent 会更早停止命令。因此，请在后台运行并等待命令退出。审查者工作期间，它会每 15 秒在 stderr 上输出一行进度信息。已有一个审查正在运行时，不要再次启动。

3. 按原样向开发者展示它输出的回执：结论、每条发现各一行（包括编号、严重程度、类别、标题、文件和行号），以及 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：审查已完成，结论为 blocked。不要推送。向开发者展示回执，并询问要修复哪些发现；只有在他们看过发现后明确要求推送，才可以推送。
   • 2：没有完整的审查。输出会说明缺少什么（例如，在无法启动审查者时显示 "Full review unavailable"，或显示原因及 "Review incomplete"）。请将内容原样告知开发者。绝不能将扫描器输出当作审查结果。

审查分支或拉取请求

当开发者要求你审查一个并非其当前工作的分支或拉取请求时，请指定目标：

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

引用 #42：在 shell 中，# 会开始注释。也可以使用拉取请求链接。OpenQodex 会获取目标、在临时文件夹中检出，然后审查它从基分支分离后新增的内容。这是他人的代码：绝不要运行其中的测试、脚本、构建或服务，也不要编辑它。

规则

• 评审期间绝不编辑代码。先评审并展示回执，然后只修复开发者指定的问题（步骤 3 到 5）。
• 未先征得开发者同意，绝不运行 openqodex trust。它会批准自定义扫描器，而扫描器是会在开发者的机器上运行的命令。
• 绝不设置 OPENQODEX_SKIP。这是开发者的开关，不是你的。
• 当 OpenQodex 提示它为你的 Agent 写入的文件版本较旧，并说明 init 会刷新这些文件时，用一行告知开发者，并给出该 init 命令。只有开发者要求时才运行它：该命令会重写他们的 Agent 文件。
• 当判定结果为 blocked 时，除非开发者看过问题后明确要求推送，否则不要推送。
• 当 OpenQodex 打印 "OpenQodex had a problem. Nothing has been sent."，并显示 1 create a GitHub issue 和 2 ignore 时，用一行告诉开发者出了什么问题，并列出这两个选项。绝不要自行选择 1。如果他们选择 1，请在同一目录运行 npx -y [email protected] report --send-last。其他任何回复都表示选择 2：不做任何操作。

阅读报告

• 报告位于仓库中的 .openqodex/reviews/<time>-<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 属于团队，应该提交。
• 判定结果为 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：扫描器已运行但失败；原因中会包含错误信息。扫描器出现问题不会改变退出代码。

在沙盒中

有些 Agent 会在沙盒中运行命令，无法访问网络或写入项目目录之外的文件。在这种情况下，首次运行无法下载扫描器，评审者也可能无法访问其模型。请告知开发者在仓库内、Agent 环境之外，使用自己的终端运行一次以下命令：

npx -y [email protected] doctor --install

该命令会将此仓库文件所需的扫描器下载到 ~/.openqodex/tools/，并逐一说明原因；--all-scanners 会下载所有扫描器。如果沙盒中仍显示 "Full review unavailable"，开发者应在自己的终端运行 npx -y [email protected] review。

更多信息

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

在阅读许多文件以查找哪个函数调用了某个函数、哪个部分实现了它、两个部分如何连接，或某项更改会影响哪些内容之前，你可以询问代码图：npx -y [email protected] graph help 会列出它能回答的问题；如果你的 Agent 有 openqodex MCP 服务的 graph_ 工具，也可以使用这些工具；如果答案中的 unknown.floor 为 true，可能缺少调用方，因此绝不能据此认定“未使用”。

切勿自行将文件添加到 review.instructions_files。请询问开发者审核者可以使用哪些文件，然后只设置他们指定的文件。默认值为 []；选定的文件会添加到 .openqodex/custom-instructions.md。