將固定的 Codex 任務放進腳本與 CI

互動式 Codex 適合探索程式、補充上下文與來回確認。開發者可以看到中間結果，遇到需求不清或權限擴大時，也能立即調整。這種工作方式能容納臨場判斷，任務內容也能依證據修正。

非互動模式（Non-interactive Mode）透過 codex exec 執行一段已準備好的提示詞（Prompt），不開啟終端使用者介面。

它適合輸入來源明確、規則穩定、輸出格式固定，且失敗後能安全停止的任務。腳本、合併前檢查與持續整合（Continuous Integration, CI）可以重複呼叫同一套流程。

非互動任務需要先在互動流程中穩定

一段提示詞在對話中成功一次，還不足以直接放進持續整合流程中。開發者要先觀察它是否需要補充背景、選擇檔案、批准命令或修正誤解。

這些臨場判斷若沒有轉成固定輸入，無人值守執行時就容易停住，或產生不一致的結果。

前一篇的程式碼審查已具備自動化基礎。輸入是基準分支與目前分支的差異（Diff），審查標準來自 AGENTS.md 與固定提示詞，輸出包含摘要、審查發現（Review findings）、驗證證據與人工確認狀態。

整個流程只需要讀取程式與 Git 歷史，不需要修改工作目錄。

適合腳本化的工作已有清楚邊界，例如產生拉取請求（Pull Request, PR）摘要、整理審查發現、分類測試失敗或檢查文件缺口。

仍在探索需求、需要修改正式資料、會部署環境或必須由人選擇方案的工作，應保留互動停點。

codex exec 將提示詞當成一次性任務執行

最基本的呼叫方式，是在 Git 儲存庫的目錄底下執行 codex exec "任務內容"。

Codex 會在標準錯誤輸出（stderr）串流顯示進度，最後訊息寫到標準輸出（stdout），腳本可以將最後結果導向檔案，或交給下一個工具處理。

codex exec "依 AGENTS.md 摘要目前分支相對於 origin/main 的變更"

加入 --ephemeral 後，這次執行不會將工作階段產出的檔案保存在磁碟。對每次都從固定輸入重新開始的持續整合任務，這能減少工作階段狀態對後續執行的影響。

流程若需要分成兩階段延續同一項分析，可使用 codex exec resume，並明確管理 session ID。

codex exec 預設在唯讀沙箱執行，需要寫入時可以指定 --sandbox workspace-write，若是隔離且受控的執行環境，也可以使用 danger-full-access。

今天的審查摘要不需要寫入專案內容，因此固定使用 read-only。

文字輸出適合閱讀，JSON 適合後續處理

單純將 stdout 導向 Markdown，可以保存人類可閱讀的摘要。腳本若要判斷審查發現的數量、風險等級或執行狀態，就需要穩定欄位。--json 會將執行事件輸出為 JSON Lines（JSONL），其中包含工作階段、命令、工具與代理人訊息等事件。

今天我們只需要最後審查結果，可以使用 --output-schema 指定 JSON Schema，再用 -o 或 --output-last-message 寫入檔案。

Schema 應定義必要欄位、允許值與 additionalProperties: false，避免模型臨時改變欄位名稱，造成後續 jq 判斷失效。

事件串流與最終結果要分開理解。--json 適合保存完整執行軌跡，-o 搭配 Schema 適合交付固定格式結果。CI 可以保留兩者：JSONL 用於排查工作失敗，最終 JSON 提供審查者閱讀及後續規則判斷。

固定格式先由 JSON Schema 定義

我們先建立 scripts/review-summary.schema.json。輸出包含整體摘要、審查發現、已讀取的驗證證據與狀態。

每項審查發現要有嚴重度、檔案、行號、問題、證據與建議。沒有問題時回傳空陣列，不能省略欄位。

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": { "enum": ["high", "medium", "low"] },
          "file": { "type": "string" },
          "line": { "type": ["integer", "null"] },
          "issue": { "type": "string" },
          "evidence": { "type": "string" },
          "suggestion": { "type": "string" }
        },
        "required": ["severity", "file", "line", "issue", "evidence", "suggestion"],
        "additionalProperties": false
      }
    },
    "validation": {
      "type": "array",
      "items": { "type": "string" }
    },
    "status": {
      "enum": ["clear", "needs-human-review", "incomplete"]
    }
  },
  "required": ["summary", "findings", "validation", "status"],
  "additionalProperties": false
}

clear 表示本次輸入與審查條件下沒有高可信度的發現，仍需人工閱讀。needs-human-review 表示至少有一項發現需要核對。incomplete 表示缺少基準分支、規則、差異或驗證資料。狀態名稱直接表達後續動作，避免將模型輸出寫成「可自動合併」。

將審查提示詞放進本機腳本

今天任務會新增 scripts/codex-review-summary.sh，接收一個基準分支，預設值為 origin/main。

腳本先確認目前位於 Git 儲存庫，再要求 Codex 讀取 AGENTS.md、比較分支差異，並依前一篇的標準產生固定格式 Review 摘要。

#!/usr/bin/env bash
set -euo pipefail

base_ref="${1:-origin/main}"
output_dir="artifacts/codex-review"
schema_path="scripts/review-summary.schema.json"

git rev-parse --is-inside-work-tree >/dev/null
git rev-parse --verify "$base_ref" >/dev/null
mkdir -p "$output_dir"

prompt=$(cat <<PROMPT
請讀取 AGENTS.md，審查目前 HEAD 相對於 ${base_ref} 的分支差異。

請檢查架構邊界、測試缺口、錯誤處理、安全風險、資料相容性，以及是否違反 AGENTS.md。每項 finding 都要提供可重現條件與程式證據。

只允許讀取與執行唯讀 Git 命令。不要修改檔案、執行安裝、建立 commit、存取網路或推送遠端。

若缺少基準分支、Diff、規則或驗證證據，將 status 設為 incomplete。
若有需要人工核對的 finding，設為 needs-human-review。
沒有高可信度 finding 時設為 clear，並在 summary 說明仍需人工審查。
PROMPT
)

codex exec \
  --ephemeral \
  --sandbox read-only \
  --ask-for-approval never \
  --output-schema "$schema_path" \
  -o "$output_dir/summary.json" \
  "$prompt"

jq -e '.status == "clear"' "$output_dir/summary.json" >/dev/null

set -euo pipefail 會在命令失敗、未設定變數或管線錯誤時停止腳本。git rev-parse 先檢查儲存庫與基準分支，讓環境問題在呼叫 Codex 前就被辨識。摘要寫入 artifacts/codex-review/summary.json，是否納入版本控制則依專案規則決定。

最後的 jq 會讓 incomplete 與 needs-human-review 回傳非零狀態。這個結果代表持續整合需要人工處理，沒有直接宣告程式錯誤，也不會自動修改分支。

團隊若希望審查發現只顯示提醒，可以移除這個判斷，改由持續整合平台上傳摘要供審查者查看。

先在本機驗證腳本的成功與失敗路徑

將腳本放進持續整合前，先在本機執行。測試時要確認正常分支能產生符合 Schema 的 JSON，也要刻意傳入不存在的基準分支，確認腳本會在 Codex 執行前停止。

接著暫時建立一項可辨識的測試缺口，確認輸出能回報 needs-human-review，完成後還原該變更。

chmod +x scripts/codex-review-summary.sh
scripts/codex-review-summary.sh origin/main
jq . artifacts/codex-review/summary.json
scripts/codex-review-summary.sh origin/not-found

驗證時保留命令、結束碼、stdout、stderr 與產出的 JSON。stdout 是最終代理人訊息，進度多半出現在 stderr，兩者混在同一檔案會讓 JSON 解析失敗。

若要保存完整事件，可另外加上 --json，並將 JSONL 導向獨立檔案。

同一組輸入執行多次，文字內容可能出現差異。Schema 能固定結構，無法保證每次發現描述完全一致。

持續整合應把輸出視為風險提示，既有 Test、Lint、Type Check、Build 與人工 Review 仍要保留。

持續整合中要限制權限與祕密暴露範圍

非互動執行無法停下來詢問開發者，因此批准策略要預先決定。

今天我們使用 read-only 與 --ask-for-approval never：Codex 可以讀取儲存庫及執行允許的唯讀命令，遇到需要寫入或擴大權限的動作就會失敗。這符合 Review 摘要的需求。

認證資訊只能在呼叫 Codex 的步驟中提供，也要避免和不受信任的建置腳本、測試或套件生命週期腳本共享同一個環境。

工作紀錄、產出檔與快取都不能保存金鑰或登入檔。公開儲存庫的外部 PR 還要避免讓未受信任程式取得祕密。

在 GitHub Actions 中，建議使用 openai/codex-action，由 Action 處理安裝與 API 金鑰的代理方式。

儲存庫內容可維持唯讀權限，Review 摘要作為 artifact 保存。後續若需要留言或修改 PR，應放在另一個權限獨立的工作中。

自動化失敗條件要事先寫清楚

腳本層的失敗包含 Git 儲存庫不存在、基準分支缺失、Codex 執行失敗、輸出不符合 Schema，以及摘要檔無法解析。

這些狀況表示流程沒有產生可採用的審查結果，持續整合應直接停止並保留 stderr。

needs-human-review 屬於需要人工處理的阻擋狀態。審查者要回到差異核對審查發現，再決定修正、討論或駁回。clear 只讓自動化步驟通過，仍不等同於程式已經可以合併。這個界線能避免 Codex 同時擔任審查者與最終批准者。

完成本篇任務後，專案會留下 JSON Schema、本機腳本、一次正常執行紀錄與至少一個失敗路徑結果。

開發者應確認腳本只讀取必要內容、權限符合任務、輸出能由工具解析，且任何阻擋狀態都會回到人工審查。

參考資料：

• Codex 非互動模式