AI Coding Tools 文档

简体中文

English

简体中文

English

主题

CLI 命令 ​

Gemini CLI 支持多个内置命令来帮助您管理会话、自定义界面和控制其行为。这些命令以正斜杠（/）、at 符号（@）或感叹号（!）为前缀。

斜杠命令（/） ​

斜杠命令提供对 CLI 本身的元级别控制。

内置命令 ​

  • /bug

    • 描述： 提交关于 Gemini CLI 的问题。默认情况下，问题会在 Gemini CLI 的 GitHub 仓库中提交。您在 /bug 后输入的字符串将成为所提交错误的标题。可以通过 .gemini/settings.json 文件中的 bugCommand 设置修改默认的 /bug 行为。

  • /chat

    • 描述： 保存和恢复对话历史，用于交互式分支对话状态，或从后续会话中恢复先前状态。
    • 子命令：
      • save
        • 描述： 保存当前对话历史。您必须添加一个 <tag> 来标识对话状态。
        • 用法： /chat save <tag>
        • 检查点位置详情： 保存的聊天检查点的默认位置是：
          • Linux/macOS：~/.config/google-generative-ai/checkpoints/
          • Windows：C:\Users\<YourUsername>\AppData\Roaming\google-generative-ai\checkpoints\
          • 当您运行 /chat list 时，CLI 只扫描这些特定目录来查找可用的检查点。
          • 注意： 这些检查点用于手动保存和恢复对话状态。有关在文件修改前创建的自动检查点，请参阅检查点文档。
      • resume
        • 描述： 从先前保存的状态恢复对话。
        • 用法： /chat resume <tag>
      • list
        • 描述： 列出可用于聊天状态恢复的标签。
      • delete
        • 描述： 删除已保存的对话检查点。
        • 用法： /chat delete <tag>

  • /clear

    • 描述： 清除终端屏幕，包括可见的会话历史和 CLI 内的滚动回退。底层会话数据（用于历史回调）可能会根据具体实现而保留，但视觉显示会被清除。
    • 键盘快捷键： 随时按 Ctrl+L 执行清除操作。

  • /compress

    • 描述： 用摘要替换整个聊天上下文。这节省了未来任务使用的令牌，同时保留了已发生事件的高级摘要。

  • /copy

    • 描述： 将 Gemini CLI 产生的最后一个输出复制到剪贴板，便于分享或重用。

  • /directory（或 /dir）

    • 描述： 管理工作区目录以支持多目录。
    • 子命令：
      • add：
        • 描述： 向工作区添加目录。路径可以是绝对路径或相对于当前工作目录的路径。此外，也支持从主目录的引用。
        • 用法： /directory add <path1>,<path2>
        • 注意： 在限制性沙箱配置文件中禁用。如果您使用该配置，请在启动会话时使用 --include-directories。
      • show：
        • 描述： 显示通过 /directory add 和 --include-directories 添加的所有目录。
        • 用法： /directory show

  • /editor

    • 描述： 打开选择支持的编辑器的对话框。

  • /extensions

  • /help（或 /?）

    • 描述： 显示关于 Gemini CLI 的帮助信息，包括可用命令及其用法。

  • /mcp

    • 描述： 列出已配置的 Model Context Protocol (MCP) 服务器、其连接状态、服务器详情和可用工具。
    • 子命令：
      • desc 或 descriptions：
        • 描述： 显示 MCP 服务器和工具的详细描述。
      • nodesc 或 nodescriptions：
        • 描述： 隐藏工具描述，仅显示工具名称。
      • schema：
        • 描述： 显示工具配置参数的完整 JSON 架构。
    • 键盘快捷键： 随时按 Ctrl+T 在显示和隐藏工具描述之间切换。

  • /memory

    • 描述： 管理 AI 的指令上下文（从 GEMINI.md 文件加载的分层内存）。
    • 子命令：
      • add：
        • 描述： 将以下文本添加到 AI 的内存中。用法：/memory add <要记住的文本>
      • show：
        • 描述： 显示从所有 GEMINI.md 文件加载的当前分层内存的完整、连接内容。这让您检查提供给 Gemini 模型的指令上下文。
      • refresh：
        • 描述： 从配置位置（全局、项目/祖先和子目录）中找到的所有 GEMINI.md 文件重新加载分层指令内存。此命令使用最新的 GEMINI.md 内容更新模型。
      • 注意： 有关 GEMINI.md 文件如何贡献分层内存的更多详情，请参阅 CLI 配置文档。

  • /restore

    • 描述： 将项目文件恢复到工具执行之前的状态。这对于撤销工具所做的文件编辑特别有用。如果在没有工具调用 ID 的情况下运行，它将列出可恢复的可用检查点。
    • 用法： /restore [tool_call_id]
    • 注意： 仅在使用 --checkpointing 选项调用 CLI 或通过设置配置时可用。更多详情请参阅检查点文档。

  • /settings

    • 描述： 打开设置编辑器以查看和修改 Gemini CLI 设置。
    • 详情： 此命令提供用户友好的界面来更改控制 Gemini CLI 行为和外观的设置。它等同于手动编辑 .gemini/settings.json 文件，但具有验证和指导功能以防止错误。
    • 用法： 只需运行 /settings，编辑器就会打开。然后您可以浏览或搜索特定设置、查看其当前值并根据需要修改它们。某些设置的更改会立即应用，而其他设置需要重启。

  • /stats

    • 描述： 显示当前 Gemini CLI 会话的详细统计信息，包括令牌使用情况、缓存令牌节省（如果可用）和会话持续时间。注意：缓存令牌信息仅在使用缓存令牌时显示，这在 API 密钥身份验证时发生，但目前在 OAuth 身份验证时不发生。

  • /theme

    • 描述： 打开一个对话框，让您更改 Gemini CLI 的视觉主题。

  • /auth

    • 描述： 打开一个对话框，让您更改身份验证方法。

  • /about

    • 描述： 显示版本信息。提交问题时请分享此信息。

  • /tools

    • 描述： 显示 Gemini CLI 中当前可用的工具列表。
    • 子命令：
      • desc 或 descriptions：
        • 描述： 显示每个工具的详细描述，包括每个工具的名称及其提供给模型的完整描述。
      • nodesc 或 nodescriptions：
        • 描述： 隐藏工具描述，仅显示工具名称。

  • /privacy

    • 描述： 显示隐私声明并允许用户选择是否同意收集其数据用于服务改进目的。

  • /quit（或 /exit）

    • 描述： 退出 Gemini CLI。

  • /vim

    • 描述： 开启或关闭 vim 模式。启用 vim 模式时，输入区域在 NORMAL 和 INSERT 模式下都支持 vim 风格的导航和编辑命令。
    • 功能：
      • NORMAL 模式： 使用 h、j、k、l 导航；使用 w、b、e 按单词跳转；使用 0、$、^ 跳转到行首/行尾；使用 G（或 gg 跳转到第一行）跳转到特定行
      • INSERT 模式： 标准文本输入，按 escape 返回 NORMAL 模式
      • 编辑命令： 使用 x 删除，使用 c 更改，使用 i、a、o、O 插入；复杂操作如 dd、cc、dw、cw
      • 计数支持： 在命令前加数字（例如，3h、5w、10G）
      • 重复上一个命令： 使用 . 重复上一个编辑操作
      • 持久设置： Vim 模式偏好保存到 ~/.gemini/settings.json 并在会话间恢复
    • 状态指示器： 启用时，在页脚显示 [NORMAL] 或 [INSERT]

  • /init

    • 描述： 为了帮助用户轻松创建 GEMINI.md 文件，此命令分析当前目录并生成定制的上下文文件，使他们更容易向 Gemini 代理提供项目特定的指令。

自定义命令 ​

快速入门请参见下面的示例。

自定义命令允许您将最喜欢或最常用的提示保存为 Gemini CLI 中的个人快捷方式并重复使用。您可以创建特定于单个项目的命令或在所有项目中全局可用的命令，简化工作流程并确保一致性。

文件位置和优先级 ​

Gemini CLI 从两个位置发现命令，按特定顺序加载：

  1. 用户命令（全局）： 位于 ~/.gemini/commands/。这些命令在您工作的任何项目中都可用。
  2. 项目命令（本地）： 位于 <your-project-root>/.gemini/commands/。这些命令特定于当前项目，可以检入版本控制以与团队共享。

如果项目目录中的命令与用户目录中的命令同名，项目命令将始终被使用。 这允许项目用项目特定版本覆盖全局命令。

命名和命名空间 ​

命令的名称由其相对于 commands 目录的文件路径确定。子目录用于创建命名空间命令，路径分隔符（/ 或 \）被转换为冒号（:）。

  • ~/.gemini/commands/test.toml 处的文件变成命令 /test。
  • <project>/.gemini/commands/git/commit.toml 处的文件变成命名空间命令 /git:commit。

TOML 文件格式（v1） ​

您的命令定义文件必须以 TOML 格式编写并使用 .toml 文件扩展名。

必需字段 ​
  • prompt（字符串）：执行命令时将发送给 Gemini 模型的提示。这可以是单行或多行字符串。
可选字段 ​
  • description（字符串）：命令功能的简短单行描述。此文本将在 /help 菜单中显示在您的命令旁边。如果省略此字段，将从文件名生成通用描述。

处理参数 ​

自定义命令支持两种强大、低摩擦的参数处理方法。CLI 根据命令 prompt 的内容自动选择正确的方法。

1. 使用 的简写注入 ​

如果您的 prompt 包含特殊占位符 ，CLI 将用用户在命令名称后键入的所有文本替换该确切占位符。这对于需要将用户输入注入到更大提示模板中特定位置的简单、确定性命令非常完美。

示例（git/fix.toml）：

toml
# 在：~/.gemini/commands/git/fix.toml
# 通过以下方式调用：/git:fix "Button is misaligned on mobile"

description = "Generates a fix for a given GitHub issue."
prompt = "Please analyze the staged git changes and provide a code fix for the issue described here: {{args}}."

模型将收到最终提示：Please analyze the staged git changes and provide a code fix for the issue described here: "Button is misaligned on mobile".

2. 默认参数处理 ​

如果您的 prompt 不包含特殊占位符 ，CLI 使用默认行为来处理参数。

如果您为命令提供参数（例如，/mycommand arg1），CLI 将把您键入的完整命令附加到提示的末尾，用两个换行符分隔。这允许模型看到原始指令和您刚刚提供的特定参数。

如果您不提供任何参数（例如，/mycommand），提示将完全按原样发送给模型，不附加任何内容。

示例（changelog.toml）：

此示例显示如何通过为模型定义角色、解释在哪里找到用户输入以及指定预期格式和行为来创建健壮的命令。

toml
# 在：<project>/.gemini/commands/changelog.toml
# 通过以下方式调用：/changelog 1.2.0 added "Support for default argument parsing."

description = "Adds a new entry to the project's CHANGELOG.md file."
prompt = """
# Task: Update Changelog

You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog.

**The user's raw command is appended below your instructions.**

Your task is to parse the `<version>`, `<change_type>`, and `<message>` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file.

## Expected Format
The command follows this format: `/changelog <version> <type> <message>`
- `<type>` must be one of: "added", "changed", "fixed", "removed".

## Behavior
1. Read the `CHANGELOG.md` file.
2. Find the section for the specified `<version>`.
3. Add the `<message>` under the correct `<type>` heading.
4. If the version or type section doesn't exist, create it.
5. Adhere strictly to the "Keep a Changelog" format.
"""

当您运行 /changelog 1.2.0 added "New feature" 时，发送给模型的最终文本将是原始提示，后跟两个换行符和您键入的命令。

3. 使用 !{...} 执行 Shell 命令 ​

您可以通过在 prompt 中直接执行 shell 命令并注入其输出来使命令动态化。这对于从本地环境收集上下文非常理想，比如读取文件内容或检查 Git 状态。

当自定义命令尝试执行 shell 命令时，Gemini CLI 现在会在继续之前提示您确认。这是一项安全措施，确保只有预期的命令才能运行。

工作原理：

  1. 注入命令： 在您的 prompt 中使用 !{...} 语法指定命令应该在哪里运行并注入其输出。
  2. 确认执行： 当您运行命令时，会出现一个对话框，列出提示想要执行的 shell 命令。
  3. 授予权限： 您可以选择：
    • 允许一次： 命令将运行这一次。
    • 在此会话中始终允许： 命令将被添加到当前 CLI 会话的临时允许列表中，不再需要确认。
    • 否： 取消 shell 命令的执行。

CLI 仍然遵守全局 excludeTools 和 coreTools 设置。如果命令在您的配置中被明确禁止，它将被阻止而不会出现确认提示。

示例（git/commit.toml）：

此命令获取暂存的 git diff 并使用它要求模型编写提交消息。

toml
# 在：<project>/.gemini/commands/git/commit.toml
# 通过以下方式调用：/git:commit

description = "Generates a Git commit message based on staged changes."

# 提示使用 !{...} 执行命令并注入其输出。
prompt = """
Please generate a Conventional Commit message based on the following git diff:

```diff
!{git diff --staged}
```

"""

当您运行 /git:commit 时，CLI 首先执行 git diff --staged，然后在将最终完整提示发送给模型之前，用该命令的输出替换 !{git diff --staged}。

示例：一个"纯函数"重构命令 ​

让我们创建一个全局命令，要求模型重构一段代码。

1. 创建文件和目录：

首先，确保用户命令目录存在，然后创建一个 refactor 子目录进行组织和最终的 TOML 文件。

bash
mkdir -p ~/.gemini/commands/refactor
touch ~/.gemini/commands/refactor/pure.toml

2. 向文件添加内容：

在编辑器中打开 ~/.gemini/commands/refactor/pure.toml 并添加以下内容。我们包含可选的 description 作为最佳实践。

toml
# 在：~/.gemini/commands/refactor/pure.toml
# 此命令将通过以下方式调用：/refactor:pure

description = "Asks the model to refactor the current context into a pure function."

prompt = """
Please analyze the code I've provided in the current context.
Refactor it into a pure function.

Your response should include:
1. The refactored, pure function code block.
2. A brief explanation of the key changes you made and why they contribute to purity.
"""

3. 运行命令：

就是这样！您现在可以在 CLI 中运行您的命令。首先，您可能会将文件添加到上下文中，然后调用您的命令：

> @my-messy-function.js
> /refactor:pure

Gemini CLI 然后会执行您在 TOML 文件中定义的多行提示。

At 命令（@） ​

At 命令用于将文件或目录的内容作为您对 Gemini 提示的一部分包含在内。这些命令包括 git 感知过滤。

  • @<path_to_file_or_directory>

    • 描述： 将指定文件或文件的内容注入到您当前的提示中。这对于询问特定代码、文本或文件集合的问题很有用。
    • 示例：
      • @path/to/your/file.txt Explain this text.
      • @src/my_project/ Summarize the code in this directory.
      • What is this file about? @README.md
    • 详情：
      • 如果提供单个文件的路径，则读取该文件的内容。
      • 如果提供目录的路径，命令尝试读取该目录和任何子目录中文件的内容。
      • 路径中的空格应该用反斜杠转义（例如，@My\ Documents/file.txt）。
      • 该命令内部使用 read_many_files 工具。内容被获取，然后在发送给 Gemini 模型之前插入到您的查询中。
      • Git 感知过滤： 默认情况下，git 忽略的文件（如 node_modules/、dist/、.env、.git/）被排除。此行为可以通过 fileFiltering 设置更改。
      • 文件类型： 该命令适用于基于文本的文件。虽然它可能尝试读取任何文件，但二进制文件或非常大的文件可能会被底层 read_many_files 工具跳过或截断，以确保性能和相关性。工具会指示是否跳过了文件。
    • 输出： CLI 将显示一条工具调用消息，指示使用了 read_many_files，以及详细说明状态和处理的路径的消息。

  • @（单独的 at 符号）

    • 描述： 如果您键入单独的 @ 符号而没有路径，查询将按原样传递给 Gemini 模型。如果您在提示中专门谈论 @ 符号，这可能会很有用。

@ 命令的错误处理 ​

  • 如果在 @ 后指定的路径未找到或无效，将显示错误消息，查询可能不会发送给 Gemini 模型，或者将在没有文件内容的情况下发送。
  • 如果 read_many_files 工具遇到错误（例如，权限问题），这也会被报告。

Shell 模式和透传命令（!） ​

! 前缀让您直接从 Gemini CLI 内与系统 shell 交互。

  • !<shell_command>

    • 描述： 在 Linux/macOS 上使用 bash 或在 Windows 上使用 cmd.exe 执行给定的 <shell_command>。命令的任何输出或错误都会在终端中显示。
    • 示例：
      • !ls -la（执行 ls -la 并返回到 Gemini CLI）
      • !git status（执行 git status 并返回到 Gemini CLI）

  • !（切换 shell 模式）

    • 描述： 单独键入 ! 切换 shell 模式。
      • 进入 shell 模式：
        • 激活时，shell 模式使用不同的着色和"Shell 模式指示器"。
        • 在 shell 模式下，您键入的文本直接解释为 shell 命令。
      • 退出 shell 模式：
        • 退出时，UI 恢复到标准外观，正常的 Gemini CLI 行为恢复。

  • 所有 ! 使用的注意事项： 您在 shell 模式下执行的命令具有与直接在终端中运行相同的权限和影响。

  • 环境变量： 当通过 ! 或在 shell 模式下执行命令时，在子进程的环境中设置 GEMINI_CLI=1 环境变量。这允许脚本或工具检测它们是否从 Gemini CLI 内运行。

基于 MIT 许可证发布

版权所有 © 2025-至今