← 文件教學

評審規則

告訴 OCR 每個檔案要「關注什麼」——四層優先級鏈與五重門過濾

四層優先級鏈

對每個檔案路徑，依序嘗試各層；第一個匹配的模式生效。

優先級來源路徑說明
1（最高）--rule 參數使用者指定CLI 覆蓋；只要提供就生效
2專案配置<repoDir>/.opencodereview/rule.json專案級——可安全提交
3全域配置~/.opencodereview/rule.json使用者級偏好
4（最低）系統內建內嵌 system_rules.json永遠存在，涵蓋常見語言

規則檔格式

{
  "include": ["src/**/*.{ts,tsx}", "src/**/*.go"],
  "exclude": ["**/*.test.ts", "**/generated/**"],
  "rules": [
    { "path": "src/api/**/*.go", "rule": "All exported handlers must validate request bodies before use." },
    { "path": "**/*mapper*.xml", "rule": "Check SQL for injection risks, parameter errors, and missing closing tags." }
  ]
}

glob 能力（bmatcuk/doublestar/v4）

語法含義
*匹配除 / 外任意字元
**跨目錄邊界（src/**/*.go 覆蓋任意深度）
{a,b,c}花括號展開（*.{ts,tsx}）
? / [abc]單字元 / 字元類

模式匹配不區分大小寫（路徑先小寫化）。不確定時用 ocr rules check <path> 確認。

五重門檔案過濾

對每個 diff，OCR 依序問：

  1. binary——二進位？排除。
  2. user_exclude——命中你的 exclude？排除。
  3. user_include——有 include 且命中？立即保留（繞過下面兩門）。
  4. unsupported_ext——擴展名在白名單？不在則排除。
  5. default_path——命中內建測試檔排除模式（**/*_test.go…）？排除。

全部通過才發給 LLM。用 ocr review --preview 可不花 token 印出過濾結果。

內建排除（節選）

**/*_test.go            **/*.test.{js,jsx,ts,tsx}
**/src/test/**/*.java   **/__tests__/**
**/*_test.py            **/*_spec.rb
**/*Test.java           **/*_test.rs

每檔規則解析

過濾決定某檔會審後，OCR 依序試 --rule → 專案 rule.json → 全域 rule.json → 系統內建。解析出的規則正文成為 plan 與 main task prompt 的 {{system_rule}}。

查看哪條規則生效：ocr rules check

$ ocr rules check src/main/java/com/example/UserService.java
File: src/main/java/com/example/UserService.java
Source: System built-in
Pattern: **/*.java
Rule:
────────────────────────
…java.md 內容…
────────────────────────

配方

專案級：強制編碼規範

{
  "rules": [
    { "path": "src/api/**/*.go", "rule": "Every public handler must `defer tx.Rollback()` immediately after starting a transaction." },
    { "path": "**/*mapper*.xml", "rule": "Check SQL for injection risks, missing parameter binding, and unclosed XML tags." }
  ]
}

跳過生成碼，聚焦 src

{ "include": ["src/**/*.{ts,tsx,js,jsx}"], "exclude": ["**/*.gen.ts", "**/generated/**"] }

按 PR 覆蓋

ocr review --rule ./.review-rules-only-for-this-pr.json
📖 教學解說：評審規則深入

四層優先級鏈的「為什麼」

四層不是任意順序——它們有明確的覆蓋邏輯：

  • --rule（CLI）→ 臨時覆蓋，不改配置
  • 專案 .opencodereview/rule.json → 團隊共識，可提交
  • 全域 ~/.opencodereview/rule.json → 個人偏好
  • 系統內建 → 永遠兜底

「首條匹配生效」意味著更具體的規則要放前面。

include 是「繞過機制」不是白名單

這是最多人誤解的：include 不是「只審這些檔」——它是「這些檔繞過後面兩門排除」。五重門的第三門 user_include 命中後立即保留，跳過 unsupported_ext 和 default_path。這就是為什麼你可以用 include 強制保留測試檔。

用 ocr rules check 除錯

「規則沒觸發？」→ 跑 ocr rules check <path>。它顯示：① 匹配的層（CLI/專案/全域/內建）→ ② glob 模式 → ③ 規則正文。如果層不對（應該匹配專案但匹配了內建），多半是宣告順序問題——把更具體的規則前移。

🔍 Worked Example：自訂規則 + 除錯

Step 1 — 建立專案級規則檔

cat > .opencodereview/rule.json << 'EOF'
{
  "include": ["src/**/*.go"],
  "exclude": ["**/*_test.go"],
  "rules": [
    { "path": "src/api/**/*.go", "rule": "Check for missing error handling after db.Begin()." }
  ]
}
EOF

Step 2 — 確認規則是否匹配

ocr rules check src/api/handler.go

Step 3 — 跑 preview 看過濾結果

ocr review --preview

Step 4 — 真正跑評審

ocr review

預期產出

File: src/api/handler.go
Source: Project .opencodereview/rule.json
Pattern: src/api/**/*.go
Rule:
────────────────────────
Check for missing error handling after db.Begin().
────────────────────────

常見錯誤與診斷

錯誤訊息診斷修復
規則沒觸發glob 模式不匹配或宣告順序不對跑 ocr rules check 確認
我的檔案沒被評審被五重門過濾跑 ocr review --preview 看排除原因

練習 / 驗收清單

  • 能說出四層優先級鏈的順序
  • 能解釋 include 是繞過機制而非白名單
  • 能描述五重門各擋什麼
  • 能用 ocr rules check 除錯規則沒觸發
看完這頁你應該能說出：四層優先級鏈的順序、include 是繞過機制而非白名單、五重門各擋什麼、以及如何用 ocr rules check 除錯「規則沒觸發」。

延伸閱讀：CLI 參考 · 架構 · FAQ