Gemini CLI 备忘清单

Vertex AI 还需要 GOOGLE_CLOUD_PROJECT 与 GOOGLE_CLOUD_LOCATION。

系统要求： Node.js 20+、macOS 15+、Windows 11 24H2+ 或 Ubuntu 20.04+

可通过 -m flash 或 GEMINI_MODEL 环境变量设置。

可在提示词中包含文件或目录内容：

# 引入单个文件
@src/main.ts fix the bug on line 42

# 引入一个目录
@src/ what does this module do?

# 引入多个路径
@package.json @src/ audit dependencies

具备 Git 感知能力：目录引入时会遵守 .gitignore。

# 运行单条 shell 命令
!ls -la

# 切换持久 shell 模式
!

# 将 shell 输出注入上下文
!git diff HEAD~1

所有 shell 子进程都会自动设置 GEMINI_CLI=1。

# 列出全部会话
$ gemini --list-sessions

# 恢复最近一次会话
$ gemini -r latest

# 恢复指定会话
$ gemini -r <session-id>

# 按索引删除
$ gemini --delete-session 3

在 /resume 浏览器中：

• ↑↓：浏览会话
• Enter：恢复选中会话
• x：删除会话
• 直接输入可搜索

输入 /rewind 或连按两次 Esc 可打开 rewind 对话框：

仅作用于 AI 造成的文件变更，不影响手动编辑或 ! shell 命令。

通过保存和恢复命名检查点来探索多种方案：

# 1. 保存当前状态
/resume save my-decision-point

# 2. 尝试方案 A...

# 3. 恢复到保存状态
/resume resume my-decision-point

# 4. 尝试方案 B...

上下文文件按以下顺序加载（最终会合并）：

# 在 GEMINI.md 中导入其他文件

@./docs/architecture.md
@./docs/conventions.md

可通过 settings.json 中的 context.fileName 自定义文件名（也可设为数组：["AGENTS.md", "GEMINI.md"]）。

# 显示全部已加载上下文
/memory show

# 强制重载全部上下文文件
/memory reload

# 向全局 GEMINI.md 追加文本
/memory add "Always use TypeScript strict mode"

# 生成项目级 GEMINI.md
/init

在项目根目录创建 .geminiignore（遵循 .gitignore 语法）：

# 排除一个目录
/packages/

# 排除指定文件
apikeys.txt
*.log

# 排除所有 .md，但保留 README
*.md
!README.md

这些文件会对 CLI 工具隐藏，但对 Git 和其他服务仍然可见。

# 从 GitHub 安装
$ gemini extensions install https://github.com/org/ext

# 从本地路径安装
$ gemini extensions install ./my-extension

# 列出已安装扩展
$ gemini extensions list

# 更新全部扩展
$ gemini extensions update --all

# 更新指定扩展
$ gemini extensions update my-ext

# 启用 / 禁用
$ gemini extensions enable my-ext
$ gemini extensions disable my-ext --scope user

# 以链接方式用于开发
$ gemini extensions link ./dev-extension

# 创建新扩展
$ gemini extensions new ./my-new-ext

# 校验结构
$ gemini extensions validate ./my-ext

扩展可打包：提示词、MCP 服务器、自定义命令、主题、hooks、子代理与 skills。

Skills 提供按需加载的专长能力，只有在调用 activate_skill 时才会加载。

发现位置（按优先级）：

# 列出全部 skills
$ gemini skills list --all

# 从 Git 或本地安装
$ gemini skills install https://github.com/org/skill
$ gemini skills install ./local-skill

# 以链接方式用于开发
$ gemini skills link ./my-skill

# 启用 / 禁用
$ gemini skills enable my-skill
$ gemini skills disable my-skill

可将可复用提示词保存为 slash 命令。

文件位置：

• 用户：~/.gemini/commands/
• 项目：.gemini/commands/

# .gemini/commands/git/commit.toml
description = "生成提交信息"
prompt = """
请为以下内容生成一条 conventional commit 提交信息：

!{git diff --staged}

{{args}}
"""

该命令会变成 /git:commit。子目录 / 会映射成 : 命名空间。

占位符：

# 通过参数一次性启用
$ gemini --approval-mode=plan

# 自然语言触发
> let's plan the refactor first

# Slash 命令触发
/plan redesign the auth module

# 会话中可用 Shift+Tab 循环切换模式

可在 settings.json 中设为默认：

{
  "general": {
    "defaultApprovalMode": "plan"
  }
}

只读工具（始终可用）：

• read_file, list_directory, glob
• grep_search, google_web_search
• web_fetch (with confirmation)
• codebase_investigator, cli_help
• ask_user

写入工具（受限）：

• write_file, replace — only for .md files inside plans directory

记忆相关：

• save_memory, activate_skill

1. 设定目标
  └─ 使用自然语言或 /plan <goal>

2. 讨论策略
  └─ Gemini 可能会提出澄清问题

3. 审阅计划
  └─ Markdown 文件会写入 plans 目录
  └─ 可用 Ctrl+X 在外部编辑器中修改

4. 批准或继续迭代

5. 切换到 YOLO/auto_edit 执行实现

自动模型路由：规划阶段使用 Pro，实施阶段切换到 Flash。

优先级（越靠前越高）： CLI 参数 → 环境变量 → 系统设置 → 项目设置 → 用户设置 → 系统默认值

常见设置：

{
  "general": {
    "defaultApprovalMode": "default",
    "checkpointing": { "enabled": true }
  },
  "ui": {
    "theme": "dark"
  },
  "model": {
    "name": "auto"
  },
  "tools": {
    "sandbox": "docker"
  }
}

可通过 /settings 打开可视化编辑器。

可持久写入 ~/.bashrc、~/.zshrc 或 .gemini/.env。