自定义命令

自定义命令允许您将喜欢的或最常用的提示保存并重用为 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 会将该占位符替换为用户在命令名称后键入的文本。

此注入的行为取决于其使用位置：

A. 原样注入（在 Shell 命令之外）

当在提示的正文中使用时，参数将按用户键入的原始方式注入。

示例 (git/fix.toml)：

# 通过以下方式调用： /git:fix "Button is misaligned"

description = "为给定问题生成修复方案。"
prompt = "请为此处描述的问题提供代码修复方案：{{args}}。"

模型收到的内容为：请为此处描述的问题提供代码修复方案："Button is misaligned"。

B. 在 Shell 命令中使用参数（在 !{...} 块内）

当您在 shell 注入块（!{...}）中使用 时，参数会在替换前自动进行shell 转义。这允许您安全地将参数传递给 shell 命令，确保生成的命令在语法上正确且安全，同时防止命令注入漏洞。

示例 (/grep-code.toml)：

prompt = """
请总结模式 `{{args}}` 的搜索结果。

搜索结果：
!{grep -r {{args}} .}
"""

当您运行 /grep-code It\'s complicated 时：

1. CLI 检测到 在 !{...} 块内外均有使用。
2. 外部：第一个 被原样替换为 It\'s complicated。
3. 内部：第二个 被替换为转义后的版本（例如，在 Linux 上："It\'s complicated"）。
4. 执行的命令是 grep -r "It\'s complicated" .。
5. CLI 会提示您确认此精确、安全的命令，然后才执行。
6. 最终提示被发送。

2. 默认参数处理

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

如果您向命令提供参数（例如 /mycommand arg1），CLI 会将您键入的所有命令附加到提示的末尾，并用两个换行符分隔。这使得模型可以看到原始指令以及您刚刚提供的特定参数。

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

示例 (changelog.toml)：

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

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

description = "向项目的 CHANGELOG.md 文件添加新条目。"
prompt = """
# 任务：更新变更日志

您是该软件项目的专家维护者。用户已调用命令以向变更日志添加新条目。

**用户的原始命令附加在您的指令下方。**

您的任务是从用户的输入中解析 `<version>`、`<change_type>` 和 `<message>`，并使用 `write_file` 工具正确更新 `CHANGELOG.md` 文件。

## 预期格式
命令遵循以下格式：`/changelog <version> <type> <message>`
- `<type>` 必须是以下之一：“added”、“changed”、“fixed”、“removed”。

## 行为
1. 读取 `CHANGELOG.md` 文件。
2. 查找指定 `<version>` 的部分。
3. 在正确的 `<type>` 标题下添加 `<message>`。
4. 如果版本或类型部分不存在，则创建它。
5. 严格遵守“Keep a Changelog”格式。
"""

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

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

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

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

工作原理：

1. 注入命令： 使用 !{...} 语法。
2. 参数替换： 如果块内存在 ，它将被自动进行 shell 转义（参见上面的 上下文感知注入）。
3. 健壮的解析： 解析器能正确处理包含嵌套大括号的复杂 shell 命令，例如 JSON 负载。注意： !{...} 内的内容必须具有平衡的大括号（{ 和 }）。如果您需要执行包含不平衡大括号的命令，请考虑将其包装在外部脚本文件中，并在 !{...} 块内调用该脚本。
4. 安全检查和确认： CLI 会对最终解析的命令（在参数转义和替换后）执行安全检查。将出现一个对话框，显示要执行的确切命令。
5. 执行和错误报告： 命令将被执行。如果命令失败，注入到提示中的输出将包含错误消息（stderr）以及状态行，例如 [Shell command exited with code 1]。这有助于模型理解失败的上下文。

示例 (git/commit.toml)：

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

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

description = "根据暂存的更改生成 Git 提交消息。"

# 该提示使用 !{...} 来执行命令并注入其输出。
prompt = """
请根据以下 git diff 生成一个 Conventional Commit 消息：

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

"""

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

4. 使用 @{...} 注入文件内容

您可以使用 @{...} 语法直接将文件内容或目录列表嵌入到您的提示中。这对于创建操作特定文件的命令非常有用。

工作原理：

• 文件注入： @{path/to/file.txt} 将被 file.txt 的内容替换。
• 多模态支持： 如果路径指向支持的图像（例如 PNG、JPEG）、PDF、音频或视频文件，它将被正确编码并作为多模态输入注入。其他二进制文件将被妥善处理并跳过。
• 目录列表： @{path/to/dir} 将被遍历，并且目录中存在的所有文件及其所有子目录中的文件都将被插入到提示中。这会尊重 .gitignore 和 .geminiignore（如果已启用）。
• 工作区感知： 命令会在当前目录和任何其他工作区目录中搜索路径。如果绝对路径在工作区内，则允许使用。
• 处理顺序： 文件内容注入（使用 @{...}）在 shell 命令（!{...}）和参数替换（）之前进行处理。
• 解析： 解析器要求 @{...}（路径）内的内容具有平衡的大括号（{ 和 }）。

示例 (review.toml)：

此命令注入固定最佳实践文件（docs/best-practices.md）的内容，并使用用户的参数为审查提供上下文。

# 在： <project>/.gemini/commands/review.toml
# 通过以下方式调用： /review FileCommandLoader.ts

description = "使用最佳实践指南审查提供的上下文。"
prompt = """
您是一位专业的代码审查员。

您的任务是审查 {{args}}。

在提供审查时，请使用以下最佳实践：

@{docs/best-practices.md}
"""

当您运行 /review FileCommandLoader.ts 时，@{docs/best-practices.md} 占位符将被该文件的内容替换，并且 将被您提供的文本替换，然后最终提示才会被发送给模型。

---

示例：“纯函数”重构命令

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

1. 创建文件和目录：

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

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

2. 向文件添加内容：

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

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

description = "要求模型将当前上下文重构为纯函数。"

prompt = """
请分析我在当前上下文中提供的代码。
将其重构为纯函数。

您的响应应包括：
1. 重构后的纯函数代码块。
2. 对您所做的关键更改及其如何有助于纯粹性的简要解释。
"""

3. 运行命令：

就是这样！您现在可以在 CLI 中运行您的命令了。首先，您可能需要向上下文中添加一个文件，然后调用您的命令：

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

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