Gemini CLI 使用指南

何时使用Gemini

当被要求激活时
代码审查：跨多个文件的全面代码审查
方案审查：分析架构方案、技术规范或项目路线图
大上下文处理：需要超过200k tokens上下文的任务（如整个代码库、文档集）
多文件分析：理解多个文件之间的关系和模式

⚠️ 重要提示：后台/非交互模式警告

绝对不要在后台或非交互shell中使用
--approval-mode default
参数（例如Claude Code工具调用场景）。它会无限期挂起，等待无法被响应的审批提示。

对于自动化/后台审查场景：

✅ 使用
```
--approval-mode yolo
```
实现完全自动化执行
✅ 或者添加超时包装：
```
timeout 300 gemini ...
```
❌ 绝对不要在无交互终端的情况下使用
```
--approval-mode default
```

Gemini挂起的症状：

进程运行20分钟以上，CPU使用率为0%
无网络活动
进程状态显示为'S'（休眠）

修复挂起的进程：

bash

# 检查是否挂起
ps aux | grep gemini | grep -v grep

# 必要时终止进程
pkill -9 -f "gemini.*gemini-3-pro-preview"

运行任务

通过
```
AskUserQuestion
```
工具，在一个单独的提示中询问用户要使用哪个模型。可用模型包括：
- ```
gemini-3-pro-preview
```
  ⭐（旗舰模型，最适合编码和复杂推理任务，在软件工程任务上的表现比2.5 Pro高出35%）
- ```
gemini-3-flash
```
  （亚秒级延迟，由3 Pro蒸馏得到，最适合对速度要求极高的任务）
- ```
gemini-2.5-pro
```
  （旧版选项，综合性能强劲）
- ```
gemini-2.5-flash
```
  （旧版选项，兼具成本效益和思考能力）
- ```
gemini-2.5-flash-lite
```
  （旧版选项，处理速度最快）
根据任务选择审批模式：
- ```
default
```
  ：提示用户审批（⚠️ 仅适用于交互终端会话）
- ```
auto_edit
```
  ：仅自动批准编辑工具（适用于带建议的代码审查）
- ```
yolo
```
  ：自动批准所有工具（✅ 后台/自动化任务必须使用此模式）
使用合适的选项组装命令：
- ```
-m, --model <MODEL>
```
  ：选择模型
- ```
--approval-mode <default|auto_edit|yolo>
```
  ：控制工具审批权限
- ```
-y, --yolo
```
  ：
```
--approval-mode yolo
```
  的简写形式
- ```
-i, --prompt-interactive "prompt"
```
  ：执行指定提示并进入交互模式
- ```
--include-directories <DIR>
```
  ：添加工作区包含的额外目录
- ```
-s, --sandbox
```
  ：在沙箱模式下运行以实现隔离
**对于后台/自动化任务，必须始终使用
```
--approval-mode yolo
```
**或添加超时包装。绝对不要在非交互shell中使用
```
default
```
模式。

运行命令并捕获输出。对于后台/自动化模式：

bash

# 推荐：后台任务使用yolo模式
gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase for security issues"

# 或者添加超时限制（5分钟）
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase"

带初始提示的交互会话：

bash

gemini -m gemini-3-pro-preview -i "Review the authentication system" --approval-mode auto_edit

Gemini执行完成后，告知用户：“Gemini分析已完成。你可以启动新的Gemini会话进行后续分析，或继续探索当前分析结果。”

快速参考

使用场景	审批模式	关键参数
后台代码审查	`yolo` ✅	`-m gemini-3-pro-preview --approval-mode yolo`
后台分析	`yolo` ✅	`-m gemini-3-pro-preview --approval-mode yolo`
带超时的后台任务	`yolo` ✅	`timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo`
交互式代码审查	`default`	`-m gemini-3-pro-preview --approval-mode default` (仅交互终端)
带自动编辑的代码审查	`auto_edit`	`-m gemini-3-pro-preview --approval-mode auto_edit`
自动化重构	`yolo`	`-m gemini-3-pro-preview --approval-mode yolo`
对速度要求极高的后台任务	`yolo` ✅	`-m gemini-3-flash --approval-mode yolo`
成本优化的后台任务	`yolo` ✅	`-m gemini-2.5-flash --approval-mode yolo`
多目录分析	`yolo` （后台场景）	`--include-directories <DIR1> --include-directories <DIR2>`
带初始提示的交互会话	`auto_edit` 或 `default`	`-i "prompt" --approval-mode <mode>`

模型选择指南

模型	适用场景	上下文窗口	核心特性
`gemini-3-pro-preview` ⭐	旗舰模型：复杂推理、编码、Agent任务	1M输入 / 64k输出	Vibe coding、SWE-bench得分76.2%、输入成本$2-4/百万tokens
`gemini-3-flash`	亚秒级延迟、对速度要求极高的应用	1M输入 / 64k输出	由3 Pro蒸馏得到、TPU优化
`gemini-2.5-pro`	旧版：综合性能强劲	1M输入 / 65k输出	思考模式、成熟稳定
`gemini-2.5-flash`	旧版：成本效益高、高吞吐量任务	1M输入 / 65k输出	价格最优（$0.15/百万tokens）、思考模式
`gemini-2.5-flash-lite`	旧版：处理速度最快、高吞吐量	1M输入 / 65k输出	速度最快、延迟极低

Gemini 3优势：在软件工程任务上准确率提升35%，在SWE-bench（76.2%）、GPQA Diamond（91.9%）和WebDev Arena（1487 Elo）上达到业界领先水平。知识截止日期：2025年1月。

即将推出：

gemini-3-deep-think

，针对超复杂推理任务，具备增强的思考能力。

常见使用场景

代码审查（后台/自动化）

bash

# 后台执行场景（Claude Code、CI/CD等）
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review focusing on:
   1. Security vulnerabilities
   2. Performance issues
   3. Code quality and maintainability
   4. Best practices violations"

# 带超时安全限制（5分钟）
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Perform a comprehensive code review..."

方案审查（后台/自动化）

bash

# 后台执行场景
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Review this architectural plan for:
   1. Scalability concerns
   2. Missing components
   3. Integration challenges
   4. Alternative approaches"

大上下文分析（后台/自动化）

bash

# 后台执行场景
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Analyze the entire codebase to understand:
   1. Overall architecture
   2. Key patterns and conventions
   3. Potential technical debt
   4. Refactoring opportunities"

交互式代码审查（仅终端）

bash

# 仅在交互终端中使用default模式
gemini -m gemini-3-pro-preview --approval-mode default \
  "Review the authentication flow for security issues"

后续操作

Gemini CLI会话通常是一次性或交互式的。与Codex不同，它没有内置的恢复功能。
如需后续分析，启动新的Gemini会话并传入之前分析结果的上下文。
提出后续操作建议时，需重申所选的模型和审批模式。
每次执行Gemini命令后，使用
```
AskUserQuestion
```
确认下一步操作或收集澄清信息。

错误处理

当
```
gemini --version
```
或任何Gemini命令执行失败（返回非零状态码）时，立即停止操作并报告失败情况。
重试失败命令前，需先请求用户指导。
在使用高影响参数（
```
--approval-mode yolo
```
、
```
-y
```
、
```
--sandbox
```
）之前，除非已获得用户许可，否则需使用
```
AskUserQuestion
```
向用户请求权限。
当输出包含警告或部分结果时，需进行总结并使用
```
AskUserQuestion
```
询问用户如何调整。

排查Gemini进程挂起问题

检测

bash

# 检查挂起的进程
ps aux | grep -E "gemini.*gemini-3" | grep -v grep

# 查找以下症状：
# - 进程运行20分钟以上
# - CPU使用率为0%
# - 进程状态为'S'（休眠）
# - 无网络连接

诊断

bash

# 获取详细进程信息
ps -o pid,etime,pcpu,stat,command -p <PID>

# 检查网络活动
lsof -p <PID> 2>/dev/null | grep -E "(TCP|ESTABLISHED)" | wc -l
# 如果结果为0，说明进程已挂起

解决方法

bash

# 终止挂起的Gemini进程
pkill -9 -f "gemini.*gemini-3-pro-preview"

# 或者终止指定PID的进程
kill -9 <PID>

# 验证清理结果
ps aux | grep gemini | grep -v grep

预防措施

后台/自动化任务必须始终使用
--approval-mode yolo
添加超时包装以确保安全：
```
timeout 300 gemini ...
```
绝对不要在非交互shell中使用
```
--approval-mode default
```
使用
```
ps
```
命令监控首次运行，确保进程正常完成

大上下文处理技巧

明确需求：提供清晰、结构化的分析提示
使用include-directories参数：明确指定所有相关目录
选择合适的模型：
- 复杂推理、编码任务和追求最高分析质量时，使用
```
gemini-3-pro-preview
```
  （推荐默认选项）
- 对速度要求极高、需要亚秒级响应的任务，使用
```
gemini-3-flash
```
- 成本优化的高吞吐量处理任务，使用
```
gemini-2.5-flash
```
发挥Gemini 3的优势：在软件工程任务上表现提升35%，在Agent工作流和Vibe coding方面表现出色
拆分复杂任务：即使有大上下文支持，结构化分析仍然更有效
保存分析结果：要求Gemini输出可保存的结构化报告，以便后续参考

CLI版本要求

如需支持Gemini 3模型，需要Gemini CLI v0.16.0或更高版本。检查版本：

gemini --version

gemini

NPX安装

标签

SKILL.md 内容（中文）

Gemini CLI 使用指南

何时使用Gemini

⚠️ 重要提示：后台/非交互模式警告

运行任务

快速参考

模型选择指南

常见使用场景

代码审查（后台/自动化）

方案审查（后台/自动化）

大上下文分析（后台/自动化）

交互式代码审查（仅终端）

后续操作

错误处理

排查Gemini进程挂起问题

检测

诊断

解决方法

预防措施

大上下文处理技巧

CLI版本要求