# Gemini CLI

> Wield Google's Gemini CLI as a powerful auxiliary tool for code generation, review, analysis, and web research. Use when tasks benefit from a second AI perspective, current web information via Google Search, codebase architecture analysis, or parallel code generation. Also use when user explicitly requests Gemini operations. 需代理的网络环境需配置代理。

- Skill: `asura-2010/gemini-cli` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add asura-2010/gemini-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asura-2010/gemini-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: Asura-2010 (https://skillmd.com/u/asura-2010)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/asura-2010/gemini-cli

---


# Gemini CLI Integration Skill

整合 Gemini CLI (v0.16.0+) 与 Gemini 3.x 系列，专为需要代理的网络环境优化。

## 前提条件

- Gemini CLI 已安装并可用 (`gemini` 命令)
- 已通过 Google 账户认证
- **网络要求**：需代理的网络环境需配置代理访问 Google API

## 代理配置（需代理的网络环境必读）

Gemini CLI 需要访问 Google API，在需要代理的网络环境必须使用代理。

### 检查代理状态

```bash
echo "https_proxy=$https_proxy http_proxy=$http_proxy"
```

### 推荐：配置 Shell Alias

为避免每个命令都手写代理变量，建议配置 alias：

```bash
# 添加到 ~/.zshrc 或 ~/.bashrc
alias pgemini='https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 gemini'
alias pgemini-pro='https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 gemini -m gemini-3.1-pro-preview --skip-trust'
alias pgemini-flash='https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 gemini -m gemini-3.5-flash-preview --skip-trust'

# 后续命令简化为：
pgemini-pro -p "提示词"
pgemini-flash -p "提示词"  # 快速模型
```

### 单命令代理设置（临时）

如未配置 alias，可单命令设置代理：

```bash
https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 \
gemini -m gemini-3.1-pro-preview --skip-trust --yolo -p "提示词"
```

### 代理地址参考

| 代理软件 | 默认端口 |
|---------|---------|
| Clash | 7890 |
| V2RayN | 10809 |
| Shadowsocks | 1080 |

> 根据实际代理软件调整端口

## 模型版本（已更新）

| 优先级 | 模型 | 说明 |
|-------|------|------|
| 首选 | `gemini-3.1-pro-preview` | 最强推理能力 |
| 备用 | `gemini-3.5-flash-preview` | 最新 Flash 模型，速度极快，Pro 额度用完时自动切换 |

## 使用时机

### 适用场景

1. **第二意见 / 交叉验证**
   - 代码审查（不同 AI 视角）
   - 安全审计
   - 发现 Claude 可能遗漏的问题

2. **Google Search 实时搜索**
   - 需要当前网络信息的问题
   - 最新库版本、API 变化、文档更新
   - 当前事件或最新发布

3. **代码库架构分析**
   - 使用 Gemini 的 `codebase_investigator` 工具
   - 理解陌生代码库
   - 映射跨文件依赖关系

4. **并行处理**
   - 后台执行任务时继续其他工作
   - 同时运行多个代码生成
   - 后台文档生成

5. **专门生成**
   - 测试套件生成
   - JSDoc/文档生成
   - 代码语言翻译

### 不适用场景

- 简单快速任务（开销不值得）
- 需要即时响应的任务（速率限制导致延迟）
- 上下文已加载和理解的情况
- 需要对话式交互优化的任务

## 核心指令

### 1. 验证安装

```bash
command -v gemini || which gemini
```

### 2. 基本命令模式

```bash
# 需代理的网络环境带代理（使用 alias 后）
pgemini -p "[prompt]" --yolo -o text

# 或完整写法
https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 \
gemini -p "[prompt]" --yolo -o text 2>&1
```

关键参数：
- `--yolo` 或 `-y`: 自动批准所有工具调用
- `--skip-trust`: 跳过信任检查
- `-o text`: 人类可读输出
- `-o json`: 结构化输出带统计
- `-m gemini-3.5-flash-preview`: 简单任务用快速模型

### 3. 关键行为注意

**YOLO 模式行为**：自动批准工具调用但不会阻止规划提示。Gemini 可能仍会展示计划并询问"这个计划好吗？"。使用强制语言：
- "现在应用"
- "立即开始"
- "不做确认直接执行"

**速率限制**：免费层有请求频率限制（具体数值以 Google 官方文档为准）。CLI 自动重试带回退。预期看到"quota will reset after Xs"消息。

### 4. 输出处理

JSON 输出 (`-o json`) 解析：
```json
{
  "response": "实际内容",
  "stats": {
    "models": { "tokens": {...} },
    "tools": { "byName": {...} }
  }
}
```

## 快速参考命令

以下示例假设已配置 `pgemini` alias，或请自行添加代理变量。

### 代码生成

```bash
pgemini -p "创建 [描述] 包含 [功能]。输出完整文件内容。" --yolo -o text
```

### 代码审查（管道方式，带正确 fallback）

**重要**：fallback 时必须重新传递输入，否则备用模型无法获取文件内容：

```bash
# 正确写法：重复传递 cat 输入
cat 文件路径 | pgemini-pro -p "审查提示词" || \
cat 文件路径 | pgemini-flash -p "审查提示词"

# 或使用变量存储文件内容
FILE_CONTENT=$(cat 文件路径)
echo "$FILE_CONTENT" | pgemini-pro -p "审查提示词" || \
echo "$FILE_CONTENT" | pgemini-flash -p "审查提示词"
```

### Bug修复

```bash
pgemini -p "修复 [文件] 中的这些bug：[列表]。立即应用修复。" --yolo -o text
```

### 测试生成

```bash
pgemini -p "为 [文件] 生成 [Jest/pytest] 测试。重点关注 [区域]。" --yolo -o text
```

### 文档生成

```bash
pgemini -p "为 [文件] 所有函数生成 JSDoc。输出 markdown 格式。" --yolo -o text
```

### 架构分析

```bash
pgemini -p "使用 codebase_investigator 分析此项目" -o text
```

### 网络研究

```bash
pgemini -p "[主题] 最新情况是什么？使用 Google Search。" -o text
```

## 结构化代码审查流程

### 1. 确认审查范围

- 单文件：直接审查
- Git变更：使用 `git diff`
- 多文件/目录：合并后审查

### 2. 过滤无关文件（重要！）

排除以下文件：
- `package-lock.json`
- `*.min.js`、`*.min.css`
- `.svg` 图片文件
- `node_modules/` 目录
- 自动生成的文件、配置文件（除非用户明确要求）

### 3. 处理超长文件

超过 3000 行的文件：
- 询问用户是否只审查特定部分
- 或使用 `head -n 截取行数` 限制

### 4. 结构化提示词模板

```
请作为资深软件工程师，审核以下代码（文件路径：[路径]，技术栈：[栈]）。

请重点从以下维度审查，按优先级输出：

1. 🚨 **高危问题**：安全漏洞、内存泄漏、崩溃风险
2. ⚠️ **潜在缺陷**：边界情况、竞态条件、错误处理
3. ⚡ **性能与可维持性**：复杂度、代码结构、命名规范

保持精简客观。
注意：请输出精简的修改建议（如 Patch 格式或只展示改动的前后几行），严禁重写未修改的大段原始代码。
```

### 5. 执行审查（带正确 fallback）

```bash
# 正确写法：fallback 时重新传递输入
cat 文件路径 | pgemini-pro -p "审查提示词" || \
cat 文件路径 | pgemini-flash -p "审查提示词"
```

## 错误处理

### 速率限制超出

- CLI 自动重试带回退
- 使用 `-m gemini-3.5-flash-preview` 处理低优先级任务
- 长操作后台运行

### 命令失败

- 检查 JSON 输出获取详细错误统计
- 验证 Gemini 认证：`gemini --version`
- 检查 `~/.gemini/settings.json` 配置问题
- 确认代理设置正确

### 常见错误码

| 错误码/消息 | 含义 | 解决方案 |
|------------|------|----------|
| `429` / `quota will reset` | 速率限制触发 | 等待重置或切换 Flash 模型 |
| `401` / `API key not found` | 认证失败 | 检查 `GEMINI_API_KEY` 或重新 OAuth |
| `403` | 权限不足 | 检查账户权限或模型访问限制 |
| `400` / `context_overflow` | 输入超长 | 使用 `.geminiignore` 或精简输入 |
| `network timeout` | 网络超时 | 检查代理设置或网络连接 |
| `tool_call_failed` | 工具调用失败 | 查看详细日志，检查权限 |

### 生成后验证

始终验证 Gemini 输出：
- 检查安全漏洞（XSS、注入）
- 测试功能符合需求
- 审查代码风格一致性
- 验证依赖适当性

## 集成工作流

### 标准 Generate-Review-Fix 循环

```bash
# 1. 生成
pgemini -p "创建 [代码]" --yolo -o text

# 2. 审查（Gemini 审查自己的工作）
pgemini -p "审查 [文件] 的 bug 和安全问题" -o text

# 3. 修复发现的问题
pgemini -p "修复 [文件] 中的 [问题]。立即应用。" --yolo -o text
```

### 后台执行

长任务后台运行，输出重定向到文件避免干扰终端：

```bash
# 输出重定向到日志文件
pgemini -p "[长任务]" --yolo -o text > gemini_output.log 2>&1 &

# 监控进度
tail -f gemini_output.log

# 查看是否完成
ps aux | grep gemini
```

## Gemini 独特能力

这些工具仅通过 Gemini 可用：

1. **google_web_search** - Google 实时互联网搜索
2. **codebase_investigator** - 深度架构分析
3. **save_memory** - 跨会话持久记忆

## 配置

### 项目上下文（可选）

在项目根目录创建 `.gemini/gemini.md`（全小写，跨平台兼容）作为持久上下文，Gemini 会自动读取。

### 会话管理

列出会话：`gemini --list-sessions`
恢复会话：`echo "follow-up" | gemini -r [index] -o text`

## 参考文档

- `reference.md` - 完整命令和参数参考
- `templates.md` - 常用操作的提示词模板
- `patterns.md` - 高级集成模式
- `tools.md` - Gemini 内置工具文档