Headless 模式：批次、JSON 與腳本

Headless（非互動）模式適合把 Gemini CLI 接到腳本：輸入一段文字，取得回覆與執行狀態，再由程式決定是否儲存。本篇用虛構公告示範單次摘要與小批次處理，區分 CLI 的 JSON 外層、模型產出的文字，以及真正透過驗證的工作結果。

開始前：先在互動模式完成一次

準備 Gemini CLI 0.59.0 與已完成的登入認證。先手動整理同一段公告，確認模型、提示詞與帳號都能正常使用，再移到非互動模式。這樣發生錯誤時，才容易分辨是認證問題、腳本解析問題，還是資料本身缺漏。

本篇不把排程帳號假設成你正在使用的桌面帳號。工作排程器或伺服器可能使用不同家目錄、PATH、環境變數與設定檔；手動登入成功，不代表另一個執行環境也成功。認證資訊應由受控環境提供，不寫進腳本或提交到版本庫，額度與計費請參考API 成本與錯誤處理及認證篇。

CLI 不需要互動視窗時，可使用 -p 傳入提示詞。-o json 會輸出包含 response、stats 等資訊的 JSON；response 仍可能是一段普通文字。選擇 JSON 輸出，只保證外層可供腳本解析，不會讓活動日期自動變成你設計的資料欄位。

單次執行：先看回覆與退出狀態

在 PowerShell 執行下面命令。提示詞使用固定的虛構資料，並要求不使用工具，先把讀檔權限等變因排除。執行後立即記錄退出碼，再解析輸出；若中間先執行其他外部程式，最後退出碼可能已被改變。

$raw = gemini -p "只使用本段文字，不使用工具。摘要：社群讀書會在青葉中心舉辦，日期未公告。請列出已知資訊與待確認事項。" -o json
$runExitCode = $LASTEXITCODE
if ($runExitCode -ne 0) { throw "Gemini CLI 執行失敗：$runExitCode" }
$result = ($raw -join "`n") | ConvertFrom-Json
if ($result.error -or -not $result.response) { throw "沒有可用回覆" }
$result.response

預期回覆保留活動地點，並指出日期未公告。除了有文字，還要核對它沒有補出年月日。本文提供的是可重跑範例與驗收標準，連線產出取決於讀者的登入、模型與額度；退出碼零也不代表內容事實已通過審查。

小批次流程：先存草稿，再核對結果

1. 準備兩份純文字公告，每份資料先去除不需要的個人資訊，並賦予唯一編號。
2. 一次只送一份資料，沿用同一提示詞；不要把所有檔案混成一段難以定位的長文字。
3. 每次儲存編號、時間、CLI 版本、退出碼與回覆，讓失敗可以單獨重跑。
4. 發生錯誤時停止該批次，確認已完成專案，避免重新執行後產生重複成果。
5. 抽查原文與摘要，再把合格結果移到正式目錄；初始輸出只當待審草稿。

下面 Python 範例使用引數陣列呼叫程式，資料直接作為標準輸入傳入，不把公告內容串成 shell 命令。GEMINI_BIN 可以指定 CLI 執行入口；Windows 若找到的是 .cmd 啟動器，採 Node 與已安裝 gemini.js 的明確入口，避免用 shell=True 繞過引數處理。第一次先用前面的 PowerShell 範例確認環境。

import json
import os
import subprocess
from pathlib import Path

# GEMINI_BIN 指向可直接執行的 CLI；Windows 可改為 ["node", "實際的 gemini.js 路徑"]。
command = [os.environ.get("GEMINI_BIN", "gemini")]
prompt = "只整理標準輸入的公告，不使用工具。列出已知資訊及待確認事項，不猜測。"
output = Path("drafts")
output.mkdir(exist_ok=True)
for source in sorted(Path("announcements").glob("*.txt")):
    destination = output / (source.stem + ".json")
    if destination.exists():
        raise RuntimeError(f"輸出已存在，請先核對：{destination}")
    run = subprocess.run(
        command + ["-p", prompt, "-o", "json"],
        input=source.read_text(encoding="utf-8"),
        text=True, encoding="utf-8", capture_output=True, timeout=180,
    )
    if run.returncode:
        raise RuntimeError(f"{source.name} 執行失敗，退出碼 {run.returncode}")
    result = json.loads(run.stdout)
    if result.get("error") or not result.get("response"):
        raise RuntimeError(f"{source.name} 沒有可用回覆")
    destination.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")

串流與權限：腳本要能處理結束狀態

若使用 -o stream-json，輸出會是逐行 JSON 事件，適合顯示進度或接到其他程式。不能把整份輸出一次交給普通 JSON 物件解析器；應逐行解析，並等到最終結果事件後再標記完成。只有收到部分文字、程式被中斷或逾時，都不能當作成功。

需要工具的批次任務，要先在最小範圍確認權限設定與Hooks。沒有互動介面時，無人能替你回答臨時核准問題。不要只為了讓排程跑完就啟用全部自動核准；把任務拆成能預先驗證的讀取與草稿產出，才容易追蹤每次執行的影響。

常見問題與正式串接前檢查

正式交給排程前，再做一次故意失敗的演練：把輸入檔案留空、指定不存在的執行入口，或讓輸出檔案預先存在。這些情況應留下明確失敗狀態，並停止後續正式提交。確認你的監控是檢查程式與結果，而不是只檢查「今天有沒有建立檔案」，才能避免空白或重複成果被誤收。

「輸出不是合法 JSON」先把 stdout 與 stderr 分開儲存，確認沒有 shell 提示訊息被混進正文。檢查是否真的帶了 -o json，以及是否誤把 stream-json 當成單一物件。解析失敗時保留原始輸出供排查，不直接刪掉所有檔案重來。

「手動能用、排程不能用」比較兩邊的使用者、工作目錄、CLI 路徑與認證來源。用絕對路徑指定輸入目錄及執行入口，讓腳本不依賴當下開在哪個資料夾。先在排程環境跑無工具的小提示詞，成功後再加入檔案處理。

「可以失敗就無限重試嗎」不適合。額度、認證與無效輸入應先分類，只有暫時性失敗才採有限次數與間隔重試。每份公告使用唯一編號，避免重新產生同名成果。需要嚴格欄位、服務端驗證與長期維護的應用，可接著學API 結構化輸出，用清楚的資料模型管理結果。

完成後的檢核

接著可以閱讀 Hooks、API 額度與錯誤，把本篇的操作接到下一個工作流程。

返回 Gemini 教學總目錄

• AI 工具
• 教學
• Gemini CLI 與 API