gemini

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gemini Skill Guide

Gemini CLI 使用指南

When to Use Gemini

何时使用Gemini

WHEN ASKED TO BE ACTIVATED
Code Review: Comprehensive code reviews across multiple files
Plan Review: Analyzing architectural plans, technical specifications, or project roadmaps
Big Context Processing: Tasks requiring >200k tokens of context (entire codebases, documentation sets)
Multi-file Analysis: Understanding relationships and patterns across many files

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

⚠️ Critical: Background/Non-Interactive Mode Warning

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

NEVER use
--approval-mode default
in background or non-interactive shells (like Claude Code tool calls). It will hang indefinitely waiting for approval prompts that cannot be provided.

For automated/background reviews:

✅ Use
```
--approval-mode yolo
```
for fully automated execution
✅ OR wrap with timeout:
```
timeout 300 gemini ...
```
❌ NEVER use
```
--approval-mode default
```
without interactive terminal

Symptoms of hung Gemini:

Process running 20+ minutes with 0% CPU usage
No network activity
Process state shows 'S' (sleeping)

Fix hung process:

bash

undefined

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

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

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

Gemini挂起的症状：

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

修复挂起的进程：

bash

undefined

Check if hung

检查是否挂起

ps aux | grep gemini | grep -v grep

Kill if necessary

必要时终止进程

pkill -9 -f "gemini.*gemini-3-pro-preview"

undefined

pkill -9 -f "gemini.*gemini-3-pro-preview"

undefined

Running a Task

运行任务

Ask the user (via
```
AskUserQuestion
```
) which model to use in a single prompt. Available models:
- ```
gemini-3-pro-preview
```
  ⭐ (flagship model, best for coding & complex reasoning, 35% better at software engineering than 2.5 Pro)
- ```
gemini-3-flash
```
  (sub-second latency, distilled from 3 Pro, best for speed-critical tasks)
- ```
gemini-2.5-pro
```
  (legacy option, strong all-around performance)
- ```
gemini-2.5-flash
```
  (legacy option, cost-efficient with thinking capabilities)
- ```
gemini-2.5-flash-lite
```
  (legacy option, fastest processing)
Select the approval mode based on the task:
- ```
default
```
  : Prompt for approval (⚠️ ONLY for interactive terminal sessions)
- ```
auto_edit
```
  : Auto-approve edit tools only (for code reviews with suggestions)
- ```
yolo
```
  : Auto-approve all tools (✅ REQUIRED for background/automated tasks)
Assemble the command with appropriate options:
- ```
-m, --model <MODEL>
```
  - Model selection
- ```
--approval-mode <default|auto_edit|yolo>
```
  - Control tool approval
- ```
-y, --yolo
```
  - Alternative to
```
--approval-mode yolo
```
- ```
-i, --prompt-interactive "prompt"
```
  - Execute prompt and continue interactively
- ```
--include-directories <DIR>
```
  - Additional directories to include in workspace
- ```
-s, --sandbox
```
  - Run in sandbox mode for isolation
For background/automated tasks, ALWAYS use
--approval-mode yolo
or add timeout wrapper. NEVER use
```
default
```
in non-interactive shells.

Run the command and capture the output. For background/automated mode:

bash

# Recommended: Use yolo for background tasks
gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase for security issues"

# Or with timeout (5 min limit)
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo "Review this codebase"

For interactive sessions with an initial prompt:

bash

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

After Gemini completes, inform the user: "The Gemini analysis is complete. You can start a new Gemini session for follow-up analysis or continue exploring the findings."

通过
```
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会话进行后续分析，或继续探索当前分析结果。”

Quick Reference

快速参考

Use case	Approval mode	Key flags
Background code review	`yolo` ✅	`-m gemini-3-pro-preview --approval-mode yolo`
Background analysis	`yolo` ✅	`-m gemini-3-pro-preview --approval-mode yolo`
Background with timeout	`yolo` ✅	`timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo`
Interactive code review	`default`	`-m gemini-3-pro-preview --approval-mode default` (interactive terminal only)
Code review with auto-edits	`auto_edit`	`-m gemini-3-pro-preview --approval-mode auto_edit`
Automated refactoring	`yolo`	`-m gemini-3-pro-preview --approval-mode yolo`
Speed-critical background	`yolo` ✅	`-m gemini-3-flash --approval-mode yolo`
Cost-optimized background	`yolo` ✅	`-m gemini-2.5-flash --approval-mode yolo`
Multi-directory analysis	`yolo` (if background)	`--include-directories <DIR1> --include-directories <DIR2>`
Interactive with prompt	`auto_edit` or `default`	`-i "prompt" --approval-mode <mode>`

使用场景	审批模式	关键参数
后台代码审查	`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>`

Model Selection Guide

模型选择指南

Model	Best for	Context window	Key features
`gemini-3-pro-preview` ⭐	Flagship model: Complex reasoning, coding, agentic tasks	1M input / 64k output	Vibe coding, 76.2% SWE-bench, $2-4/M input
`gemini-3-flash`	Sub-second latency, speed-critical applications	1M input / 64k output	Distilled from 3 Pro, TPU-optimized
`gemini-2.5-pro`	Legacy: Strong all-around performance	1M input / 65k output	Thinking mode, mature stability
`gemini-2.5-flash`	Legacy: Cost-efficient, high-volume tasks	1M input / 65k output	Best price ($0.15/M), thinking mode
`gemini-2.5-flash-lite`	Legacy: Fastest processing, high throughput	1M input / 65k output	Maximum speed, minimal latency

Gemini 3 Advantages: 35% higher accuracy in software engineering, state-of-the-art on SWE-bench (76.2%), GPQA Diamond (91.9%), and WebDev Arena (1487 Elo). Knowledge cutoff: January 2025.

Coming Soon:

gemini-3-deep-think

for ultra-complex reasoning with enhanced thinking capabilities.

模型	适用场景	上下文窗口	核心特性
`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

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

Common Use Cases

常见使用场景

Code Review (Background/Automated)

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

bash

undefined

bash

undefined

For background execution (Claude Code, CI/CD, etc.)

后台执行场景（Claude Code、CI/CD等）

gemini -m gemini-3-pro-preview --approval-mode yolo
"Perform a comprehensive code review focusing on:

Security vulnerabilities
Performance issues
Code quality and maintainability
Best practices violations"

gemini -m gemini-3-pro-preview --approval-mode yolo
"Perform a comprehensive code review focusing on:

Security vulnerabilities
Performance issues
Code quality and maintainability
Best practices violations"

With timeout safety (5 minutes)

带超时安全限制（5分钟）

timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo
"Perform a comprehensive code review..."

undefined

timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo
"Perform a comprehensive code review..."

undefined

Plan Review (Background/Automated)

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

bash

undefined

bash

undefined

For background execution

后台执行场景

gemini -m gemini-3-pro-preview --approval-mode yolo
"Review this architectural plan for:

Scalability concerns
Missing components
Integration challenges
Alternative approaches"

undefined

gemini -m gemini-3-pro-preview --approval-mode yolo
"Review this architectural plan for:

Scalability concerns
Missing components
Integration challenges
Alternative approaches"

undefined

Big Context Analysis (Background/Automated)

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

bash

undefined

bash

undefined

For background execution

后台执行场景

gemini -m gemini-3-pro-preview --approval-mode yolo
"Analyze the entire codebase to understand:

Overall architecture
Key patterns and conventions
Potential technical debt
Refactoring opportunities"

undefined

gemini -m gemini-3-pro-preview --approval-mode yolo
"Analyze the entire codebase to understand:

Overall architecture
Key patterns and conventions
Potential technical debt
Refactoring opportunities"

undefined

Interactive Code Review (Terminal Only)

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

bash

undefined

bash

undefined

ONLY use default mode in interactive terminal

仅在交互终端中使用default模式

gemini -m gemini-3-pro-preview --approval-mode default
"Review the authentication flow for security issues"

undefined

gemini -m gemini-3-pro-preview --approval-mode default
"Review the authentication flow for security issues"

undefined

Following Up

后续操作

Gemini CLI sessions are typically one-shot or interactive. Unlike Codex, there's no built-in resume functionality.
For follow-up analysis, start a new Gemini session with context from previous findings.
When proposing follow-up actions, restate the chosen model and approval mode.
Use
```
AskUserQuestion
```
after each Gemini command to confirm next steps or gather clarifications.

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

Error Handling

错误处理

Stop and report failures whenever
```
gemini --version
```
or a Gemini command exits non-zero.
Request direction before retrying failed commands.
Before using high-impact flags (
```
--approval-mode yolo
```
,
```
-y
```
,
```
--sandbox
```
), ask the user for permission using
```
AskUserQuestion
```
unless already granted.
When output includes warnings or partial results, summarize them and ask how to adjust using
```
AskUserQuestion
```
.

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

Troubleshooting Hung Gemini Processes

排查Gemini进程挂起问题

Detection

检测

bash

undefined

bash

undefined

Check for hung processes

检查挂起的进程

ps aux | grep -E "gemini.*gemini-3" | grep -v grep

Look for these symptoms:

查找以下症状：

- Process running 20+ minutes

- 进程运行20分钟以上

- CPU usage at 0%

- CPU使用率为0%

- Process state 'S' (sleeping)

- 进程状态为'S'（休眠）

- No network connections

- 无网络连接

undefined

undefined

Diagnosis

诊断

bash

undefined

bash

undefined

Get detailed process info

获取详细进程信息

ps -o pid,etime,pcpu,stat,command -p <PID>

Check network activity

检查网络活动

lsof -p <PID> 2>/dev/null | grep -E "(TCP|ESTABLISHED)" | wc -l

If result is 0, process is hung

如果结果为0，说明进程已挂起

undefined

undefined

Resolution

解决方法

bash

undefined

bash

undefined

Kill hung Gemini processes

终止挂起的Gemini进程

pkill -9 -f "gemini.*gemini-3-pro-preview"

Or kill specific PID

或者终止指定PID的进程

kill -9 <PID>

Verify cleanup

验证清理结果

ps aux | grep gemini | grep -v grep

undefined

ps aux | grep gemini | grep -v grep

undefined

Prevention

预防措施

ALWAYS use
--approval-mode yolo
for background/automated tasks
Add timeout wrapper for safety:
```
timeout 300 gemini ...
```
Never use
```
--approval-mode default
```
in non-interactive shells
Monitor first run with
```
ps
```
to ensure process completes

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

Tips for Large Context Processing

大上下文处理技巧

Be specific: Provide clear, structured prompts for what to analyze
Use include-directories: Explicitly specify all relevant directories
Choose the right model:
- Use
```
gemini-3-pro-preview
```
  for complex reasoning, coding tasks, and maximum analysis quality (recommended default)
- Use
```
gemini-3-flash
```
  for speed-critical tasks requiring sub-second response times
- Use
```
gemini-2.5-flash
```
  for cost-optimized high-volume processing
Leverage Gemini 3's strengths: 35% better at software engineering tasks, exceptional at agentic workflows and vibe coding
Break down complex tasks: Even with large context, structured analysis is more effective
Save findings: Ask Gemini to output structured reports that can be saved for reference

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

CLI Version

CLI版本要求

Requires Gemini CLI v0.16.0 or later for Gemini 3 model support. Check version:

gemini --version

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

gemini --version