gemini-agent

Installation

SKILL.md

Gemini Agent

通过 Gemini CLI 将任务委派给独立的 Gemini 会话执行。

Gemini CLI 的默认入口是 gemini（交互式 REPL）。自动化调用走 headless 模式，它在两种情况下会触发：

运行在 non-TTY 环境（例如 CI、管道 stdin、run_in_background）
显式传 -p / --prompt

headless 下 Gemini 不会进交互提示，把最终结果打印到 stdout。想拿可解析输出再叠加 --output-format json 或 stream-json。

前置条件

安装 Gemini CLI 并完成认证（首次运行 gemini 会引导登录）
建议在目标项目目录下运行；Gemini 会把当前工作目录作为 workspace 根
需要跨目录访问时，用 --include-directories 显式追加

调用方式

新建会话（默认）

gemini -p "你的任务描述" --output-format json --approval-mode auto_edit --model pro

-p, --prompt 强制非交互模式；自动化调用必备
--output-format json 让 stdout 变成可解析的单对象结果
默认 --approval-mode=default 会在写操作前确认；编码任务改成 auto_edit，无监督脚本才用 yolo
--model 建议显式传：auto（默认）/ pro / flash / flash-lite

--output-format json 的返回 schema（官方 headless reference）：

{
  "response": "模型的最终回答文本",
  "stats": { "...": "token 用量和 API 延迟" },
  "error": { "...": "可选；请求失败时才有" }
}

自动化里取 response 作为最终答案
stats 用来记账 token 用量和延迟
如果出现 error 字段，配合非 0 的退出码一起当失败处理

事件流输出（`stream-json`）

gemini -p "你的任务描述" --output-format stream-json --model pro

stream-json 输出 newline-delimited JSON（JSONL），每行一个事件。官方定义的事件类型：

`type`	含义
`init`	会话元数据，含 session ID 和使用的 model
`message`	用户 / assistant 的消息片段
`tool_use`	工具调用请求及参数
`tool_result`	工具执行结果
`error`	非致命 warning 或系统错误
`result`	最终结果事件，聚合 stats 和各 model 的 token 用量

自动化脚本以 result 事件为终态，从里面拿最终输出和聚合指标
message 只适合做实时展示；不要把中途片段当成最终答案
error 是 non-fatal 的 warning；真正的失败用退出码判断
需要调试更多内部细节时再追加 --debug

继续最近会话

gemini -r latest "后续提问" --output-format json --model flash

-r, --resume 接 latest、session 索引号（见下面的 --list-sessions）或完整 session ID
只提供 -r latest 而不带 query，可以直接进入最近一次会话的交互模式

继续指定会话

gemini -r "<session-id>" "后续提问" --output-format json --model flash
gemini --resume 5 "后续提问" --output-format json --model flash

脚本里需要确定绑定某次会话时，保存并复用 session ID 或索引号，比 latest 更稳
当前目录下不同任务的 session 互不干扰

列出 / 删除本地会话

gemini --list-sessions
gemini --delete-session 3

脚本里要挑选历史会话时用 --list-sessions 拿到索引号和 session ID
--delete-session 按索引号删除；运行前先 --list-sessions 对应清楚，避免误删

管道输入 / stdin

cat logs.txt | gemini -p "Explain the failure in these logs" --output-format json --model flash
cat ./prompt.md | gemini -p --output-format json --model pro

-p 的 prompt 文本会追加到 stdin 内容之后；想完全由 stdin 驱动 prompt，就只传 -p 不带文本
适合把日志、长 Markdown、脚本拼接的 prompt 直接喂给 Gemini，而不是再落临时文件
不需要非交互结果时也可以 cat file | gemini（不加 -p），CLI 会直接把内容作为一次 query 处理

Interactive 追加一句（`-i`）

gemini -i "先帮我看下这个项目的结构"

-i, --prompt-interactive 会先执行一次 prompt，然后留在交互式 REPL
适合“问一句再接着手动对话”的场景；不要在脚本或 CI 里用它

gemini CLI 参数

输出与结果

Flag	说明
`-p, --prompt TEXT`	非交互模式；`json` / `stream-json` 输出都依赖它
`-i, --prompt-interactive TEXT`	执行一次 prompt 后继续进入交互式 REPL
`-o, --output-format FORMAT`	`text`（默认）/ `json` / `stream-json`
`-d, --debug`	打开调试模式；会输出更详细的日志到 stderr

会话管理

Flag	说明
`-r, --resume TARGET`	恢复会话：`latest` / 索引号（如 `5`）/ 完整 session ID
`--list-sessions`	列出当前项目可恢复的会话并退出
`--delete-session INDEX`	按索引号删除会话

权限与工具边界

Flag	说明
`--approval-mode MODE`	`default` / `auto_edit` / `yolo` / `plan`
`-y, --yolo`	已废弃；等价于 `--approval-mode=yolo`
`-s, --sandbox`	在沙箱环境里执行，增加一层隔离
`--allowed-mcp-server-names LIST`	允许哪些 MCP server（多值用逗号或重复传）
`--allowed-tools LIST`	已废弃；改用 Policy Engine

--approval-mode 的分档：

default：写操作前二次确认，适合交互；脚本不要用，否则会卡在确认提示
auto_edit：自动放行文件编辑，其它敏感动作仍需确认，适合大多数编码任务
yolo：自动放行全部动作；只在完全可信的自动化里使用
plan：只读规划模式，不执行写动作，最适合代码审查 / 诊断 / recon

模型与上下文

Flag	说明
`-m, --model MODEL`	`auto`（默认）/ `pro` / `flash` / `flash-lite`，也可直接传模型全名
`--include-directories DIRS`	额外加入 workspace 的目录（逗号分隔或重复）
`--screen-reader`	屏幕阅读器可访问性模式

模型 alias 映射（来自官方 cheatsheet）：

auto → gemini-2.5-pro 或 gemini-3-pro-preview（视 preview 开关而定）
pro → 同上，适合复杂推理 / 多文件编码
flash → gemini-2.5-flash，快速均衡
flash-lite → gemini-2.5-flash-lite，最快但最轻量

运行环境

Flag	说明
`-w, --worktree [NAME]`	在独立 git worktree 里启动；实验特性，需要 settings 打开 `experimental.worktrees: true`
`-e, --extensions NAMES`	只加载指定的 Gemini extensions
`-l, --list-extensions`	列出所有 extensions 并退出
`--experimental-acp`	以 ACP（Agent Code Pilot）模式启动，实验特性
`--experimental-zed-integration`	Zed 编辑器集成模式，实验特性

退出码

Headless 模式下 Gemini 返回标准退出码，脚本可以直接按它判成败：

退出码	含义
`0`	成功
`1`	通用错误或 API 失败
`42`	输入错误（无效 prompt 或参数）
`53`	超过 turn 上限

推荐脚本同时看两个信号：

退出码为 0 且 json 里无 error 字段 → 成功
非 0 退出码 → 按上表分类处理（尤其 42 是自己的 prompt / flag 组合有问题，53 说明任务跑太深，需要拆细或加重试）

子命令

Gemini CLI 除了主命令外，还有若干管理子命令：

子命令	说明
`gemini update`	升级到最新版本
`gemini extensions <...>`	管理 extensions：`install` / `uninstall` / `list` / `enable` / `disable` / `link` / `update`
`gemini mcp <...>`	管理 MCP servers：`add` / `remove` / `list`，支持 stdio 和 http
`gemini skills <...>`	管理 agent skills：`install` / `link` / `enable` / `disable` / `list`

这些子命令一般不在委派流程里用，属于环境配置。遇到缺失的 extension 或 MCP server 时，提醒用户先用对应子命令安装。

多轮对话

首次 gemini -p "..." --output-format json ... 获取结果；若后续要追问，记录 session ID 或索引
追问用 gemini -r <session-id> "..."，或同目录下用 -r latest
不同任务各自新建会话；多个 session 互不干扰
要定位已有会话，先 gemini --list-sessions 查索引和 ID

模型与 approval-mode 选择

根据任务复杂度显式指定 --model；根据风险面选 --approval-mode：

任务复杂度	model	适用场景
高	`pro`	架构设计、复杂重构、多文件编码
中	`flash`	单文件功能实现、bug 修复、一般分析
低	`flash-lite`	简单问答、代码解释、快速续问

风险面	approval-mode	适用场景
高（不可回滚 / 多步写动作）	`default` 交互	脚本里别用，会卡在确认
中（标准编码任务）	`auto_edit`	文件编辑放行，其它敏感动作仍要确认
低（沙箱 / 完全受控）	`yolo`	全放行，只在隔离环境或完全可信任务里用
只读	`plan`	代码审查、诊断、recon、测试缺口检查

使用规则

自动化调用默认用 -p + --output-format json：拿稳定可解析的单对象结果；只有确实需要事件流时再切 stream-json
始终显式传 --model：默认 auto 会跟着 preview flag 漂移，自动化里要指定 pro / flash / flash-lite
始终显式传 --approval-mode：默认 default 会卡在交互确认；脚本至少要 auto_edit，只读任务用 plan
不要用 --yolo 这个旧 flag：等价物是 --approval-mode=yolo，后者语义更清晰
不要用 --allowed-tools：官方已废弃，改走 Policy Engine 配置
始终在目标项目目录运行：先 cd /path/to/project，需要跨目录再用 --include-directories
编码任务默认 auto_edit，审查任务默认 plan：写动作尽量和风险面匹配，而不是一把 yolo
保持对话连续：追问时用 -r latest 或 -r <session-id>；不要每轮都重新开 session
-r latest 适合“继续刚才那个任务”；脚本跨目录或长时间跑，绑定 session ID 更稳
向用户报告结果时优先取 response 字段：--output-format json 下最终答案在 response；stream-json 下以最后一条 type == "result" 事件为终态，不要把中途 message 片段当成终态
靠退出码判成败，不光看 stdout：0 成功 / 1 通用错误或 API 失败 / 42 输入错误（prompt 或 flag 有问题） / 53 超过 turn 上限；error 事件是 non-fatal warning，别和退出码混用
大风险动作叠加 --sandbox：yolo 放全权限时，至少要配沙箱做兜底
--worktree 是实验特性：需要先在 settings 打开 experimental.worktrees: true；不确定是否开启时，用普通 git worktree + cd 更稳
-p 模式里不要依赖交互式 slash commands：/skills reload 这类只在 REPL 里生效；自动化用自然语言描述任务即可
长 prompt 走 stdin：cat prompt.md | gemini -p --output-format json --model pro，比把长文本塞进位置参数更稳

Prompt References

按任务类型按需加载对应 reference，不要把所有默认 prompt 一次性塞进主上下文：

编码 / 诊断 / 规划 / 窄修复：读 references/task-prompt-recipes.md
代码审查 / 挑战式审查 / 测试缺口检查：读 references/review-prompt-recipes.md
委派 handoff / 独立 worker / 续接同一 session：读 references/delegation-prompt-recipes.md

这些 reference 提供的是可直接复用或轻改的默认 prompt 模板；优先复制最接近的模板，再删掉不需要的块。

示例

编码任务

cd /path/to/project && gemini -p \
  "Implement a REST API for TODO items with CRUD endpoints. Use Express.js." \
  --output-format json \
  --approval-mode auto_edit \
  --model pro

适合一次委派一整段实现；结果通过 stdout 的 JSON 对象返回。

继续最近会话

cd /path/to/project && gemini -r latest \
  "Continue from the current state. Add unit tests for the new endpoints and report only the final outcome." \
  --output-format json \
  --approval-mode auto_edit \
  --model flash

适合“刚才那个任务继续做”，不想手动保存 session ID 的场景。

指定 session 继续

# 先列出现有会话拿到索引 / ID
gemini --list-sessions

# 再按 ID 续接
cd /path/to/project && gemini -r "019d32fc-..." \
  "Pick up where we left off and finish the remaining test coverage." \
  --output-format json \
  --approval-mode auto_edit \
  --model flash

适合脚本需要明确绑定某次会话，或在多个 session 并存时避免 latest 歧义。

代码审查

cd /path/to/project && gemini -p \
  "Review git diff HEAD~1. Focus on correctness, regression risk, and missing tests. Findings first." \
  --output-format json \
  --approval-mode plan \
  --model flash

plan 模式下 Gemini 不会执行写动作，适合 PR 审查 / 诊断 / recon。

事件流输出给上层工具

cd /path/to/project && gemini -p \
  "Review the current diff and stream progress plus a final verdict." \
  --output-format stream-json \
  --approval-mode plan \
  --model flash

适合上层 agent 或脚本按 JSONL 消费中间事件，最后一条结果事件作为终态答案。

管道输入长 prompt

# 1. 把复杂 prompt 写进文件
cat > /tmp/task-prompt.md <<'PROMPT_EOF'
请在当前仓库完成以下任务：
1. 先阅读 README 和 tests
2. 只修改与 issue 直接相关的文件
3. 先补测试，再改实现，最后运行验证
PROMPT_EOF

# 2. 从 stdin 喂给 Gemini，避免长位置参数
cat /tmp/task-prompt.md | gemini -p \
  --output-format json \
  --approval-mode auto_edit \
  --model pro

适合多段 Markdown 约束、脚本拼装 prompt，或任何已经超过一屏的任务描述。

管道输入日志

cat logs.txt | gemini -p \
  "Explain the failure in these logs. Return root cause, evidence, and the smallest safe next step." \
  --output-format json \
  --approval-mode plan \
  --model flash

-p 的 prompt 文本会追加到 stdin 末尾，适合“上下文走 stdin、指令走 -p”的组合。

隔离 worktree 执行（实验特性）

cd /path/to/project && gemini -p \
  "Implement the fix in an isolated worktree, run the most relevant tests, and summarize the final result." \
  --output-format json \
  --approval-mode auto_edit \
  --model pro \
  --worktree fix-login-timeout

先确认 settings 里 experimental.worktrees: true 已打开；否则这个 flag 会报错。

沙箱里放开权限

cd /path/to/project && gemini -p \
  "Apply and verify the upgrade plan end-to-end." \
  --output-format json \
  --approval-mode yolo \
  --sandbox \
  --model pro

yolo 放全权限时，至少配 --sandbox 兜底，避免 Gemini 对宿主环境做不可回滚的写动作。

Related skills

More from ben2pc/g-claude-code-plugins

Installs

Repository

ben2pc/g-claude…-plugins

First Seen

Apr 22, 2026

Security Audits

Gen Agent Trust HubPass

SocketPass

SnykPass

场景	model	approval-mode	其他 flags
复杂编码	`pro`	`auto_edit`	`--output-format json`
一般编码	`flash`	`auto_edit`	`--output-format json`
只读问答 / 分析	`flash`	`plan`	`--output-format json`
代码审查	`flash`	`plan`	`--output-format json`
挑战式审查	`pro`	`plan`	`--output-format json`
快速问答	`flash-lite`	`default`	`--output-format json`
工具链消费事件流	`flash` 或 `pro`	视任务而定	`--output-format stream-json`
隔离执行	`pro`	`auto_edit`	`--worktree feature-x`（实验特性）
沙箱里放得更开	`flash` 或 `pro`	`yolo`	`--sandbox`

gemini-agent

Gemini Agent

前置条件

调用方式

新建会话（默认）

事件流输出（stream-json）

继续最近会话

继续指定会话

列出 / 删除本地会话

管道输入 / stdin

Interactive 追加一句（-i）

gemini CLI 参数

输出与结果

会话管理

权限与工具边界

模型与上下文

运行环境

退出码

子命令

多轮对话

模型与 approval-mode 选择

推荐参数组合

使用规则

Prompt References

示例

编码任务

继续最近会话

指定 session 继续

代码审查

事件流输出给上层工具

管道输入长 prompt

管道输入日志

隔离 worktree 执行（实验特性）

沙箱里放开权限

More from ben2pc/g-claude-code-plugins

deep-review

parallel-implementation

test-designer

codex-agent

claude-code-agent

ip-diagnosis

事件流输出（`stream-json`）

Interactive 追加一句（`-i`）