設定

情境

你們團隊 5 個人各自在本機亂設 config.json，有人用 dashscope、有人用 siliconflow、模型也不一致，評審品質忽高忽低。你要建立一套版本化的團隊設定：每個人 clone 下來直接可用，CI 與本機行為一致。

Step 1 — 建立團隊設定腳本（版本化、可重放）

# scripts/ocr-configure.sh —— 團隊唯一事實來源
ocr config set provider                    siliconflow
ocr config set model                       deepseek-v3
ocr config set language                    中文
ocr config set max_tokens                  120000
ocr config set llm.retry_codes             "403,400"
ocr config set providers.siliconflow.timeout_sec 180

Step 2 — 用 extra_body 關掉不需要的 thinking 輸出（省 token）

ocr config set providers.siliconflow.extra_body \
  '{"thinking":{"type":"disabled"}}'

某些廠商回傳的 reasoning tokens 也會計費。用 extra_body 傳廠商專屬欄位——這是 ocr config set 能帶 JSON 值的實例。

Step 3 — 驗證端點連通性 + 確認生效的設定

ocr llm test
ocr config set 2>/dev/null || cat ~/.opencodereview/config.json | jq .

Step 4 — 把腳本提交進 repo，新人一鍵設定

git add scripts/ocr-configure.sh && git commit -m "chore: team ocr config"

為什麼選這條審查路徑

與其讓每個人手工按 TUI，不如把「決策點」鎖進腳本：誰是預設 provider、用哪個模型、多少 token、幾秒超時、retry 哪些碼——全部是可 review 的 diff。改設定 = 開 PR = 走 code review，這本身就是在 dogfood OCR 的工程紀律。CI 不跑這個腳本（它有自己的 OCR_LLM_* env），因為 env 優先級更高、且 CI 用 secret 更安全。

預期產出

✓ LLM endpoint reachable
✓ Model: deepseek-v3
✓ language=中文, max_tokens=120000
Config file at ~/.opencodereview/config.json (rewritten by next set)

情境

你的 OCR 要跑在 開發者本機（dev）、CI（staging）、內部模型閘道（prod） 三個環境，但每個環境的 provider、模型、超時、retry 都不一樣。你要一套「設定即程式碼」的治理方案：環境分層、secret 不外洩、變更可 review。

Step 1 — 用環境變數表達「環境差異」

# .env.example（提交進 repo，不含 secret）
# dev（本機）: 開發者自己的 key
export OCR_LLM_URL="https://api.siliconflow.com/v1"
export OCR_LLM_MODEL="deepseek-v3"
# ci（GitHub Actions secret）: 集中管理的 key
export OCR_LLM_URL="https://gateway.internal.com/v1"
export OCR_LLM_MODEL="claude-opus-4-6"
# prod（內部閘道）: 內網模型，diff 不出網
export OCR_LLM_URL="http://vllm.internal:8000/v1"
export OCR_LLM_MODEL="qwen3-32b"

因為「env > config」，每個環境只需注入對應的 OCR_LLM_*，config.json 只放「三個環境共用的決策」。

Step 2 — config.json 只放「共用決策」

# 共用決策（提交進 repo 給人 review）
ocr config set language            中文
ocr config set max_tokens          150000
ocr config set telemetry.enabled   true
ocr config set telemetry.exporter  otlp
# secret 一律走 env，永遠不寫進 config.json

Step 3 — 建立「環境生效驗證」腳本

# scripts/verify-env.sh <dev|ci|prod> —— 每次改設定後先驗證再上
source ".env.$1"
env | rg 'OCR_LLM|ANTHROPIC' | sed 's/=.*/=/'   # 確認沒有殘留
ocr llm test   # 確認三元組真的生效

Step 4 — 把設定流程接進 CI（secret 只在 CI 注入）

# GitHub Actions: secrets 裡放 prod 的 OCR_LLM_*，跑評審前不用任何 ocr config set
# 本機 dev 的人用 .env.dev + 自己的 key —— 兩者互不污染

為什麼選這條路徑

多環境設定的核心規則是「環境差異走 env、共用決策走 config、secret 只走 env」。因為解析鏈「env > config」，只要每環境注入 OCR_LLM_*，config 就退居「共用預設」——不用在 config 裡做條件分支。secret 永不進 config.json（它是純文字、易被 commit），一切可 review、可重放。

預期產出

dev:  siliconflow / deepseek-v3 / 自己的 key
ci:   gateway / claude-opus-4-6 / 集中 key（Actions secret）
prod: vllm / qwen3-32b / 內網、無 key
驗證: 三環境 ocr llm test 全過，git diff 只看到 .env.example 與共用 config