---
title: "自動化指令碼"
description: "Gemini CLI 自動化指令碼：管道輸入、批次生成文件、JSON 提取和 smart commit 這類 shell 封裝。"
verifiedAt: "2026-05-09"
---

自動化指令碼的核心是把 Gemini CLI 當成 Unix pipeline 裡的一個處理器：從 `stdin` 讀上下文，從 `stdout` 輸出結果。

## 管道輸入

常見寫法是把日誌、diff 或命令輸出透過管道交給 Gemini CLI，例如 `cat error.log | gemini -p "Explain why this failed"`，或 `git diff | gemini -p "Write a concise commit message"`。

這種方式適合把已有命令輸出交給模型解釋、壓縮、分類或改寫。

不適合把未過濾的全量目錄直接 pipe 給模型。批次指令碼前要明確輸入白名單，例如只處理 `.log`、`.md`、`.ts`，並排除 `.env`、構建產物和大檔案。

輸入列表應先列印出來。dry run 階段先輸出將處理的檔案、預計輸出路徑和跳過原因，不要第一輪就呼叫模型。

## 批次生成文件

批次任務可以遍歷檔案，把每個檔案用 `@file` 注入上下文，再把 Gemini CLI 輸出重定向到對應 Markdown。生產指令碼要額外處理空輸出、失敗退出碼和配額重試。

落地時要加三件事：

- 對輸入檔案做過濾，避免誤讀大檔案或敏感檔案。
- 對輸出做格式檢查，避免空檔案或非預期文本。
- 批次任務之間加間隔或重試，避免配額錯誤。
- 寫正式檔案前先寫臨時檔案，確認非空且格式正確後再替換。

## 結構化 JSON

需要結構化結果時，使用 `--output-format json`，再用 `jq -r '.response'` 提取模型最終回答。

> [!WARNING]
> 讓模型“返回 JSON”不等於結果一定可被解析。生產指令碼要加 `jq` 校驗和失敗分支。

## Smart commit

Smart commit 的思路是讀取 `git diff --staged`，讓 Gemini CLI 輸出一條 Conventional Commit message，再交給人確認後提交。

更穩的版本應先人工確認 message，再提交。

| 自動化動作 | 是否可自動寫入 | 控制方式 |
| --- | --- | --- |
| 總結日誌 / diff | 可以寫報告 | 校驗非空和格式 |
| 生成 commit message | 不直接提交 | 人工確認 message |
| 批次生成文件 | 可寫臨時檔案 | 校驗後再替換 |
| 修改原始碼 | 謹慎 | 先計劃、diff、測試 |
| 釋出 / push | 不預設自動 | 獨立審批 |

## 生產指令碼骨架

自動化指令碼至少包含這些防線：

```bash
set -euo pipefail

out="$(mktemp)"
if gemini --output-format json -p "Summarize @README.md" > "$out"; then
  jq -e '.response | length > 0' "$out" >/dev/null
else
  echo "gemini failed" >&2
  exit 1
fi
```

這段不是完整業務指令碼，但展示了生產思路：嚴格 shell、臨時輸出、退出碼檢查、JSON 校驗。不要把 `gemini ... > final.md` 作為批次生成的唯一保護。

## 驗收方式

自動化指令碼要跑 dry run。檢查輸入檔案列表、輸出檔案數量、空輸出、失敗日誌、重試策略和是否讀取了敏感路徑。Smart commit 這類會執行 Git 動作的封裝，必須保留人工確認，不要預設直接提交。

dry run 日誌應能復現輸入範圍。
便於複核。

生產指令碼還要能斷點續跑。批次任務中途失敗時，應該知道哪些檔案已完成、哪些失敗、哪些未開始，不能靠重新跑全量覆蓋結果。

## 輸出落地

批次寫檔案時，推薦輸出到臨時目錄，全部校驗透過後再移動到正式目錄。校驗至少包括非空、副檔名、frontmatter 或 JSON schema、重複檔名和敏感詞掃描。自動化越長，越不能只看最後一條命令的 exit code。

失敗要能重試，成功要可複核。

## 接下來去哪

<Cards>
  <Card title="GitHub Action" description="準備接儲存庫自動化時，繼續看 run-gemini-cli Action。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/74-github-action" />
  <Card title="Headless mode" description="自動化指令碼的基礎仍然是 headless、退出碼和 JSON 解析。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="Policy engine" description="指令碼里的工具許可權要用 policy 約束，不靠 prompt 口頭提醒。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
</Cards>

## 官方來源

- [Gemini CLI automation tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/automation.md)
- [Gemini CLI headless mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/headless.md)
