Headless mode

你是 Gemini CLI Headless 顧問。

【角色】
Gemini CLI Headless 顧問，按最小夠用、安全合規優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 要自動化的任務：___
- 執行環境（指令碼 / CI）：___
- 只讀還是會改：___
- 輸出怎麼用：___
- 經驗水平：___

【工作流程】
1. 判斷適不適合 headless
2. 按最小給許可權認證
3. 設計可解析的輸出
4. 給失敗兜底
5. 給驗證

【輸出規範】
▌一、是否適合 headless
▌二、許可權 + 認證
▌三、輸出設計
▌四、兜底 + 驗證

【硬約束】
- headless 任務設計成不需越界
- 會改的限定範圍
- 憑據走環境變數，失敗有兜底
- 不要替我臆測情況或編造不存在的設定，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

Headless mode 是 Gemini CLI 的程式化入口。它不會開啟互動式終端 UI，而是執行一次任務並把結果輸出到標準輸出。

觸發方式

兩種常見觸發方式：

gemini -p "Explain this error"
gemini --prompt "Write a commit message"

或在非 TTY 環境中執行，例如管道、重定向、CI。

如果沒有 -p 且沒有 pipe / redirect，Gemini CLI 會進入互動 UI。自動化指令碼應顯式使用 -p 或 --prompt，避免 CI 因為等待互動輸入卡住。

官方還支援 --prompt-interactive 這類混合入口，但生產指令碼不要依賴互動追問。能一次性給出輸入、上下文、輸出格式和失敗策略，指令碼才可復現。

輸出格式

預設輸出普通文本。需要給指令碼消費時，使用結構化輸出：

gemini --output-format json -p "Summarize @package.json"

JSON 模式通常包含：

• response：最終回答。
• stats：token 與延遲統計。
• error：失敗時的錯誤資訊。

Streaming JSON 輸出適合長期任務或即時消費事件，事件可能包括初始化、訊息片段、工具呼叫、工具結果、錯誤和最終結果。

指令碼消費 JSON 時，要用真正的 JSON parser，不要用 grep 或字串切分。模型輸出和錯誤欄位都可能包含換行、引號和程式碼塊。

退出碼

0   成功
1   通用錯誤或 API 失敗
42  輸入錯誤
53  turn limit exceeded

指令碼里不要只讀 stdout。必須同時處理退出碼和 stderr；response 為空但退出碼為 0、或者模型返回了不可解析結構，都要算失敗分支。

什麼時候用

• CI 裡自動總結 diff。
• 批次處理記錄。
• 為內部工具包一層 AI wrapper。
• 生成結構化 JSON 後交給 jq 或後續指令碼。

生產指令碼注意

• prompt 要固定，不要依賴互動追問。
• 輸入先限流和過濾，避免把大檔案、金鑰、二進位制檔案塞進上下文。
• 需要 JSON 時使用 --output-format json，再用 jq 或語言內 JSON parser 校驗。
• 對 429、網路錯誤、turn limit exceeded 做重試或失敗記錄。
• 批次任務寫入檔案時先寫臨時檔案，校驗後再替換正式檔案。

驗收方式

用成功樣例、無效輸入、超長輸入、API 失敗四種情況跑指令碼。確認退出碼、JSON 解析、空輸出處理和記錄記錄都符合預期，再接入 CI。

指令碼里建議把失敗分成三類記錄：輸入不合法、模型或網路失敗、輸出不符合 schema。三類失敗的重試策略不同，不要統一寫成“再跑一次”。

CI 中還要設定超時。

失敗記錄要可追溯。 方便複查。

還要記錄輸入摘要和模型資訊。否則同一個 headless 指令碼在配額、fallback 或模型選擇變化後，失敗很難復現。

上線前檢查

上線前至少跑三種輸入：正常輸入、空輸入、超長輸入。再模擬一次非零退出和一次 JSON 解析失敗。指令碼能穩定處理這五類情況，才適合放進 CI 或定時任務。

失敗分支要寫入記錄，且保留輸入摘要、任務編號和退出碼。

接下來去哪

官方來源

• Gemini CLI headless mode
• Gemini CLI automation tutorial