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. 將它印出的收據顯示給開發者，照樣印出：判決、每個發現一行（其編號、嚴重性、類別、標題、檔案與行號）以及 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：沒有完整的審查。輸出會說明缺少什麼（例如當無法啟動審查器時顯示「完整審查不可用」，或「審查不完整」並附上原因）。請確切地告知開發者。切勿將掃描器輸出呈現為審查結果。

審查分支或 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 指令。僅當他們要求你時才執行它：它會改寫他們的代理檔案。
• 當判決為 blocked 時，除非開發者在查看發現後如此指示，否則請勿推送。
• 當 OpenQodex 印出「OpenQodex 遇到問題。尚未傳送任何內容。」並附有 1 create a GitHub issue 和 2 ignore 時，請用一行告知開發者發生什麼問題，並提供他們這兩個選項。切勿自行選擇 1。如果他們選擇 1，請在同一個資料夾中執行 npx -y [email protected] report --send-last。其他情況均視為 2：不做任何事。

閱讀報告

• 報告位於儲存庫中的 .openqodex/reviews/<time>-<id>/ 目錄下：report.html 可在瀏覽器中開啟（每個已變更檔案以 diff 顯示，每個發現位於其程式碼行下方，接著是涵蓋率、掃描器和影響範圍），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：掃描器已執行但發生錯誤；原因會包含其錯誤訊息。掃描器問題永遠不會改變結束代碼。

在沙盒內部

有些代理會在無法連線網路或無法寫入專案外部的沙盒中執行指令。在那裡，第一次執行無法下載掃描器，且審查器可能無法連線到其模型。請告知開發者在他們自己的終端機中（代理外部，儲存庫內部）執行以下指令一次：

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 <topic> 會離線印出一頁文件：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。