Gemini CLI

Gemini CLI

在 Claude Code 工作流中，利用 Gemini 超过 100 万 token 的上下文窗口作为 AI 编程搭档。

这项技能将教会 Claude Code 如何使用 Google 官方 Gemini CLI（gemini 命令），以获取第二意见、架构建议、调试帮助和全面的代码审查。内容基于使用官方 CLI 工具进行的生产环境测试。

---

目录

1. 快速开始
2. 何时咨询 Gemini
3. 安装
4. 使用 Gemini CLI
5. 模型选择：Flash 与 Pro
6. 主动咨询模式
7. AI 对 AI 提示词编写最佳实践
8. 常见用例
9. 集成示例
10. 故障排除与已知问题

---

快速开始

前置条件：

• 已安装 Gemini CLI（npm install -g @google/gemini-cli）
• 已使用 Google 账号完成身份验证（运行一次 gemini 进行身份验证）

基本用法模式：

# Quick question (non-interactive with -p flag)
gemini -p "Should I use D1 or KV for session storage?"

# Code review with file context (using --all-files)
gemini --all-files -p "Review this auth implementation for security issues"

# Architecture advice using Pro model
gemini -m gemini-2.5-pro -p "Best way to handle WebSockets in Cloudflare Workers?"

# Pipe file content for review
cat src/auth.ts | gemini -p "Review this authentication code for security vulnerabilities"

# Interactive mode for follow-up questions
gemini -i "Help me debug this authentication error"

---

何时咨询 Gemini

始终咨询（关键场景）

在以下情况下，Claude Code 应自动调用 Gemini：

1. 重大架构决策

   • 示例：“会话存储应该使用 D1 还是 KV？”
   • 示例：“对于长时间运行的任务，应该使用 Durable Objects 还是 Workflows？”
   • 原因：Gemini 能提供互补的视角，也可能会优先考虑不同的问题
   • 模式：gemini -m gemini-2.5-pro -p "[architectural question]"

2. 涉及安全的代码更改

   • 身份验证系统
   • 支付处理
   • 数据处理（PII、敏感数据）
   • API 密钥/机密管理
   • 原因：Gemini 2.5 Pro 擅长安全审计
   • 模式：cat [security-file] | gemini -m gemini-2.5-pro -p "Security audit this code"

3. 大型重构

   • 影响 5 个或更多文件
   • 核心架构更改
   • 数据库架构迁移
   • 原因：全新的视角有助于避免思维局限
   • 模式：gemini --all-files -m gemini-2.5-pro -p "Review this refactoring plan"

4. 调试陷入僵局（尝试失败 2 次或更多）

   • 经过 2 次调试尝试后，错误依然存在
   • 堆栈跟踪不清晰
   • 间歇性错误
   • 原因：不同的推理方式可能有助于发现根本原因
   • 模式：gemini -p "Help debug: [error message]" < error.log

5. 上下文窗口压力（已使用 70% 或更多）

   • 接近 token 上限
   • 需要将分析任务交给 Gemini
   • 原因：Gemini 的 100 万 token 上下文窗口可以处理大型代码文件
   • 模式：cat large-file.ts | gemini -p "Analyze this code structure"

可选咨询

6. 不熟悉的技术

   • 首次使用某个库/框架
   • 尝试新的模式
   • 原因：Gemini 的训练数据可能更新
   • 模式：gemini -p "Best practices for [new technology]"

7. 代码审查

   • 提交重大更改前
   • 准备拉取请求
   • 原因：发现边缘情况和改进之处
   • 模式：git diff | gemini -p "Review these changes"

---

安装

1. 安装 Gemini CLI

npm install -g @google/gemini-cli

2. 进行身份验证

gemini

按照身份验证提示关联你的 Google 账号。

3. 验证安装

gemini --version

应显示版本 0.13.0 或更高版本。

4. 测试连接

gemini -p "What is 2+2?"

---

使用 Gemini CLI

核心命令模式

非交互模式（-p 标志）

最适合与 Claude Code 集成：

# Direct question
gemini -p "Your question here"

# With model selection
gemini -m gemini-2.5-flash -p "Quick debugging question"
gemini -m gemini-2.5-pro -p "Complex architectural decision"

# With file context via pipe
cat src/auth.ts | gemini -p "Review this code"

# With all files in current directory
gemini --all-files -p "Analyze project structure"

# With stdin input
echo "Error: Cannot connect to database" | gemini -p "Help debug this error"

交互模式（-i 标志）

用于后续对话：

# Start interactive session with initial prompt
gemini -i "Let's discuss the architecture"

# Interactive with model selection
gemini -m gemini-2.5-pro -i "Help me design a database schema"

YOLO 模式（-y 标志）

自动接受所有操作（请谨慎使用）：

# Dangerous: Auto-executes suggested commands
gemini -y -p "Fix all linting errors"

⚠️ 警告：YOLO 模式可能会在未经确认的情况下执行命令。仅在可信环境中使用。

---

模型选择：Flash 与 Pro

gemini-2.5-flash（默认）

特点：

• 响应速度快：约 5-25 秒
• 能胜任大多数任务，质量良好
• 成本较低
• 适合一般问题，安全可靠

适用场景：

• 代码审查
• 调试
• 一般问题
• 快速咨询
• 需要速度时

示例：

gemini -m gemini-2.5-flash -p "Review this function for performance issues"

gemini-2.5-pro

特点：

• 响应时间：约 15-30 秒
• 质量出色，分析深入
• 成本较高
• 适合关键决策

适用场景：

• 架构决策（关键决策）
• 安全审计（深入审查）
• 复杂推理任务
• 重大重构计划
• 需要准确性而非速度时

示例：

gemini -m gemini-2.5-pro -p "Security audit this authentication system"

gemini-3-pro-preview（预览版 - 2025 年 11 月）

特点：

• Google 最新、最智能的 AI 模型（于 2025 年 11 月 18 日发布）
• 具备先进的推理能力和多模态理解能力
• 在所有主要 AI 基准测试中均优于 Gemini 2.5 Pro
• 支持文本、图像、视频、音频和 PDF 输入
• 响应时间：待定（测试中）
• 成本较高（预览版定价）

适用场景：

• 需要深入分析的最复杂推理任务
• 前沿项目的关键架构决策
• 高级多模态分析（图表、视频、复杂文档）
• 对基准测试至关重要的应用
• 需要最高质量且成本次要时

示例：

gemini -m gemini-3-pro-preview -p "Deep architectural analysis of this distributed system"
cat architecture-diagram.png | gemini -m gemini-3-pro-preview -p "Analyze this system design"

⚠️ 预览状态：该模型处于预览阶段。对于对生产环境至关重要的决策，在 Gemini 3 正式发布之前，请考虑使用 gemini-2.5-pro（稳定版）。

如何选择

Quick question? → Flash
Security/architecture? → 3-Pro-Preview (cutting-edge) or 2.5-Pro (stable)
Debugging? → Flash (try Pro if stuck)
Code review? → Flash
Refactoring 5+ files? → 3-Pro-Preview or 2.5-Pro
Multimodal analysis? → 3-Pro-Preview

---

主动咨询模式

模式 1：架构决策

触发条件：用户询问技术选型 Claude 的操作：自动咨询 Gemini，获取第二意见

# Claude runs:
gemini -m gemini-2.5-pro -p "Compare D1 vs KV for session storage in Cloudflare Workers. Consider: read/write patterns, cost, performance, complexity."

# Then synthesizes both perspectives

模式 2：安全审查

触发条件：处理身份验证、支付或敏感代码 Claude 的操作：请求 Gemini 进行安全审计

# Claude runs:
cat src/auth/verify-token.ts | gemini -m gemini-2.5-pro -p "Security audit this authentication code. Check for: token validation, timing attacks, injection vulnerabilities, error handling."

模式 3：调试协助

触发条件：尝试 2 次后错误仍然存在 Claude 的操作：征询 Gemini 的看法

# Claude runs:
echo "[error message and stack trace]" | gemini -p "Help debug this error. What's the likely root cause?"

模式 4：代码审查

触发条件：重大更改已准备好提交 Claude 的操作：请求全面审查

# Claude runs:
git diff HEAD | gemini --all-files -p "Review these changes for: correctness, edge cases, performance, security, best practices."

---

AI 对 AI 提示词的最佳实践

Claude 应如何向 Gemini 编写提示词

✅ 良好：背景充分、内容具体

gemini -m gemini-2.5-pro -p "I'm building a Cloudflare Worker with user authentication. Should I use D1 or KV for storing session data? Consider: 1) Session reads on every request, 2) TTL-based expiration, 3) Cost under 10M requests/month, 4) Deployment complexity."

❌ 不佳：模糊、缺少背景

gemini -p "D1 or KV?"

提示词结构模板

[Context: What you're building]
[Question]
[Considerations: Key factors (numbered)]

示例：架构决策

gemini -m gemini-2.5-pro -p "
Context: Building a real-time collaborative editing app on Cloudflare Workers.

Question: Should I use Durable Objects or Workflows for managing document state?

Considerations:
1. Need to handle WebSocket connections (100+ simultaneous users per document)
2. Document state must be consistent across all clients
3. Need to persist changes every 5 seconds
4. Budget: <\$100/month at 1000 documents
5. Simple deployment preferred
"

---

常见用例

1. 技术选型

# Compare two technologies
gemini -m gemini-2.5-pro -p "Compare Drizzle ORM vs raw SQL for Cloudflare D1. Consider: type safety, performance, query complexity, bundle size."

2. 安全审计

# Audit authentication code
cat src/middleware/auth.ts | gemini -m gemini-2.5-pro -p "
Security audit this authentication middleware. Check for:
1. Token validation vulnerabilities
2. Timing attack risks
3. Error handling leaks
4. CSRF protection
5. Rate limiting
"

3. 调试根本原因

# Analyze error logs
tail -100 error.log | gemini -p "
These errors started appearing after deploying auth changes. What's the likely root cause?

Context:
- Added JWT validation middleware
- Using @cloudflare/workers-jwt
- Errors only on /api/* routes
"

4. 代码审查

# Review pull request changes
git diff main...feature-branch | gemini --all-files -p "
Review this pull request. Focus on:
1. Breaking changes
2. Edge cases not handled
3. Performance implications
4. Security concerns
"

5. 重构计划

# Plan large refactor
gemini --all-files -m gemini-2.5-pro -p "
I want to refactor this Express app to Cloudflare Workers with Hono. Analyze the codebase and suggest:
1. Migration order (which routes first)
2. Potential blockers (middleware that won't work)
3. Testing strategy
4. Deployment plan
"

6. 性能优化

# Analyze performance
cat src/api/heavy-endpoint.ts | gemini -p "
This endpoint is slow (500ms+ response time). Identify performance bottlenecks and suggest optimizations.

Context:
- Cloudflare Worker
- Fetches data from 3 external APIs
- Processes 1000+ items
"

---

集成示例

示例 1：Claude 自动咨询 Gemini

场景：用户提出架构问题

User: "Should I use D1 or KV for storing user sessions?"

Claude (internal): This is an architectural decision. Consult Gemini for second opinion.

[Runs: gemini -m gemini-2.5-pro -p "Compare D1 vs KV for user session storage in Cloudflare Workers..."]

Claude (to user): "I've consulted Gemini for a second opinion. Here's what we both think:

My perspective: [Claude's analysis]
Gemini's perspective: [Gemini's analysis]

Key differences: [synthesis]
Recommendation: [combined recommendation]"

示例 2：提交前进行安全审查

User: "Ready to commit these auth changes"

Claude (internal): Security-sensitive code. Request Gemini audit.

[Runs: cat src/auth/*.ts | gemini -m gemini-2.5-pro -p "Security audit..."]

Claude (to user): "I've reviewed the code and consulted Gemini for security concerns:

Gemini identified: [security issues]
Additional checks I recommend: [Claude's additions]

Safe to commit after addressing: [list]"

示例 3：调试协助

User: "Still getting this error after trying your suggestions: [error]"

Claude (internal): Two failed attempts. Consult Gemini for fresh perspective.

[Runs: echo "[error details]" | gemini -p "Help debug..."]

Claude (to user): "Let me get a second opinion from Gemini...

Gemini suggests: [Gemini's diagnosis]
This makes sense because: [Claude's analysis]
Let's try: [combined solution]"

---

故障排除与已知问题

问题 1：未通过身份验证

错误：Error: Not authenticated

解决方案：

gemini
# Follow authentication prompts

问题 2：找不到模型

错误：Error: Model not found: gemini-2.5-flash-lite

原因：模型已弃用或更名

解决方案：

# Use stable models
gemini -m gemini-2.5-flash -p "Your question"
gemini -m gemini-2.5-pro -p "Your question"

问题 3：速率限制

错误：Error: Rate limit exceeded

解决方案：等待 1-5 分钟后重试

预防措施：适当间隔请求

问题 4：文件上下文过大

错误：文件对于上下文而言过大

解决方案：谨慎使用 --all-files，或通过管道传入特定部分

# Instead of:
gemini --all-files -p "Review everything"

# Do:
cat src/specific-file.ts | gemini -p "Review this file"

问题 5：命令卡住

原因：预期使用非交互模式，但实际进入了交互模式

解决方案：非交互式命令始终使用 -p 标志

# ✅ Correct
gemini -p "Question"

# ❌ Wrong (will hang waiting for input)
gemini "Question"

---

生产环境最佳实践

1. 自动化时始终使用 -p

# ✅ Good for scripts
gemini -p "Question"

# ❌ Bad for scripts (interactive)
gemini

2. 根据重要性选择模型

# Architecture/security → Pro
gemini -m gemini-2.5-pro -p "[critical question]"

# Debugging/review → Flash
gemini -m gemini-2.5-flash -p "[general question]"

3. 在提示词中提供背景信息

# ✅ Good
gemini -p "Context: Building Cloudflare Worker. Question: Best auth pattern? Considerations: 1) Stateless, 2) JWT, 3) <100ms overhead"

# ❌ Bad
gemini -p "Best auth?"

4. 通过管道传入文件内容进行审查

# ✅ Good
cat src/auth.ts | gemini -p "Review for security"

# ❌ Inefficient
gemini -p "Review src/auth.ts" # Gemini has to read file separately

5. 妥善处理错误

# Add error handling
if output=$(gemini -p "Question" 2>&1); then
  echo "Gemini says: $output"
else
  echo "Gemini consultation failed, proceeding with Claude's recommendation"
fi

6. 综合提炼，而非直接转发

❌ 不佳：直接粘贴 Gemini 的回复

User: "Should I use D1?"
Claude: [runs gemini] "Gemini says: [paste]"

✅ 良好：综合两方观点

User: "Should I use D1?"
Claude: [runs gemini]
"I've consulted Gemini for a second opinion:

My analysis: [Claude's perspective]
Gemini's analysis: [Gemini's perspective]
Key differences: [synthesis]
Recommendation: [unified answer]"

---

版本历史

2.1.0（2025-11-19）：

• 添加 Gemini 3 Pro Preview 模型（gemini-3-pro-preview）
• 更新 Gemini 3 的模型选择指南
• 添加多模态分析用例
• 更新模型对比表

2.0.0（2025-11-13）：

• 为官方 Gemini CLI 完全重写（移除 gemini-coach 封装）
• 直接 CLI 集成模式
• 精简为核心用例
• 更新 gemini CLI v0.13.0+ 的命令示例

1.0.0（2025-11-08）：

• 首次发布，包含 gemini-coach 封装
• 生产环境测试与试验
• 预防了 8 个以上已记录的错误

---

相关技能

• google-gemini-api - 通过 SDK 集成 Gemini API
• google-gemini-embeddings - 用于 RAG 的 Gemini 嵌入
• google-gemini-file-search - 使用 Gemini 的托管式 RAG

---

许可证

MIT - 参见 LICENSE

---

支持

• 问题反馈：https://github.com/jezweb/claude-skills/issues
• 电子邮件：[email protected]
• 官方 Gemini CLI：https://github.com/google-gemini/gemini-cli