---
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="/docs/gemini-cli/official/07-integrations-automation/74-github-action" />
  <Card title="Headless mode" description="自动化脚本的基础仍然是 headless、退出码和 JSON 解析。" href="/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="Policy engine" description="脚本里的工具权限要用 policy 约束，不靠 prompt 口头提醒。" href="/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)
