自定义命令

自定义命令可以将常用 Prompt 保存为 Gemini CLI 内的专属快捷方式。你可以为单个项目定义命令，也可以创建全局命令（在所有项目可用），以此规范工作流程并提高效率。

文件位置与优先级

Gemini CLI 按固定顺序从两个位置加载命令：

  1. 用户级命令（全局）：~/.gemini/commands/，在任意项目中均可使用。
  2. 项目级命令（本地）：<project-root>/.gemini/commands/，仅当前项目可用，可提交到版本库供团队共享。

若项目目录与用户目录存在同名命令，以项目命令优先，便于针对项目覆盖全局命令。

命名与命名空间

命令名称由文件在 commands 目录中的相对路径决定。子目录会转为命名空间，路径分隔符（/ 或 \）会转换成冒号（:）。

  • ~/.gemini/commands/test.toml → /test
  • <project>/.gemini/commands/git/commit.toml → /git:commit

TOML 文件格式（v1）

命令定义需使用 TOML，并以 .toml 为后缀。

必填字段

  • prompt（字符串）：执行命令时发送给模型的 Prompt，可为单行或多行。

可选字段

  • description（字符串）：命令的简短说明，会显示在 /help 中。若省略，将基于文件名自动生成描述。

处理参数

自定义命令支持两种强大的参数处理方式。CLI 会根据 prompt 内容自动选择。

1. 使用 {{args}} 进行上下文感知插入

若 prompt 中包含 {{args}}，CLI 会将命令名后的文本替换到该占位符位置。

A. 原样插入（非 Shell 块）

当 {{args}} 出现在 Prompt 主体中时，参数按用户输入原样插入。

示例（git/fix.toml）：

# 使用方式：/git:fix "按钮位置不正确"

description = "针对指定问题生成修复方案。"
prompt = "请根据以下描述给出相应的代码修复：{{args}}。"

模型收到：请为以下问题提供代码修复：“按钮位置不正确”。

B. Shell 命令中的参数（!{...} 内）

当 {{args}} 位于 !{...} 块内时，CLI 会自动对参数进行 Shell 转义，确保命令语法与安全性，防止注入攻击。

示例（/grep-code.toml）：

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

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

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

  1. CLI 发现 {{args}} 同时出现在普通文本与 !{...} 中。
  2. 外部占位符替换为原文 It's complicated。
  3. Shell 内部替换为转义后的 "It's complicated"（例如在 Linux 下）
  4. 实际执行的命令为 grep -r "It's complicated" .
  5. CLI 会提示你确认该命令后再执行。
  6. 处理完成后，将最终 Prompt 发送给模型。

2. 默认参数处理

若 prompt 未 包含 {{args}}，CLI 会采用默认策略：

  • 当命令带参数（如 /mycommand arg1）时，CLI 会将完整命令附加在 Prompt 末尾（前面留两行空行），使模型同时看到指令与参数。
  • 若无参数（如 /mycommand），Prompt 将原样发送，没有附加内容。

示例（changelog.toml）：

# 路径：<project>/.gemini/commands/changelog.toml
# 用法：/changelog 1.2.0 added "Support for default argument parsing."

description = "为项目的 CHANGELOG.md 添加一条新条目。"
prompt = """
# 任务：更新 Changelog

你是该项目的维护者。用户调用了一条命令，希望在 changelog 中新增一项内容。

**用户的原始命令会附在你的指令之后。**

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

## 期望格式
命令形式：`/changelog <version> <type> <message>`
- `<type>` 需要是 "added"、"changed"、"fixed" 或 "removed" 之一。

## 行为要求
1. 读取 `CHANGELOG.md`。
2. 找到指定 `<version>` 的章节。
3. 将 `<message>` 添加到对应的 `<type>` 分类下。
4. 若版本或类型章节不存在，需自动创建。
5. 严格遵循 “Keep a Changelog” 的格式。
"""

当运行 /changelog 1.2.0 added "New feature" 时，模型接收的文本为原始 Prompt 加两行空行再加上完整命令。

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

可以在 prompt 中直接执行 Shell 命令并注入输出，从而根据本地上下文生成动态内容（如读取文件、查看 Git 状态）。

执行自定义命令触发 Shell 命令时，Gemini CLI 会确认后再执行，确保安全。

流程概览：

  1. 使用 !{...} 注入命令。
  2. 若块内包含 {{args}}，会自动进行 Shell 转义（见上文）。
  3. 解析器支持含嵌套花括号的复杂命令；但 !{...} 内必须成对匹配 {}。若需要执行包含不成对括号的命令，建议封装为脚本再调用。
  4. CLI 会在替换参数后展示最终命令，提示你确认。
  5. 命令执行后，若失败，注入的输出会包含错误信息及状态（如 [Shell command exited with code 1]），帮助模型理解上下文。

示例（git/commit.toml）：

# 路径：<project>/.gemini/commands/git/commit.toml
# 用法：/git:commit

description = "根据暂存区的改动生成一条 Git 提交信息。"

# Prompt 中使用 !{...} 执行命令并注入输出。
prompt = """
请根据以下 git diff 生成一条符合 Conventional Commit 规范的提交信息：

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

"""


运行 `/git:commit` 时，CLI 会先执行 `git diff --staged`，再将输出替换到 `!{...}`，然后把完整 Prompt 发给模型。

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

通过 `@{...}` 可以直接在 Prompt 中嵌入文件或目录内容，适合针对特定文件创建命令。

**机制说明：**

- **文件注入：** `@{path/to/file.txt}` 会被替换为该文件内容。
- **多模态支持：** 若路径指向受支持的图片（PNG/JPEG）、PDF、音频或视频，会自动编码为多模态输入；其他二进制文件会被跳过。
- **目录枚举：** `@{path/to/dir}` 会遍历该目录及子目录，将所有文件注入，遵循 `.gitignore` 与 `.geminiignore`（如已启用）。
- **工作区感知：** 命令会在当前目录及其他工作区目录查找路径；若提供绝对路径，需位于工作区内。
- **处理顺序：** `@{...}` 在 `!{...}` 与 `{{args}}` 处理之前执行。
- **解析要求：** `@{...}` 中的路径必须拥有成对的大括号。

**示例（`review.toml`）：**

```toml
# 路径：<project>/.gemini/commands/review.toml
# 用法：/review FileCommandLoader.ts

description = "根据最佳实践指南审查提供的上下文内容。"
prompt = """
你是一名资深代码审查工程师。

请对 {{args}} 进行审查。

审查时请参考以下最佳实践：

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

当运行 /review FileCommandLoader.ts 时，@{docs/best-practices.md} 会被替换为文件内容，{{args}} 会替换为命令参数，最终 Prompt 才会发送给模型。

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

下面创建一个全局命令，请模型将代码重构为纯函数。

  1. 创建文件与目录：
mkdir -p ~/.gemini/commands/refactor
touch ~/.gemini/commands/refactor/pure.toml
  1. 编写命令内容：

在编辑器中打开 ~/.gemini/commands/refactor/pure.toml，添加如下内容：

# 路径：~/.gemini/commands/refactor/pure.toml
# 触发方式：/refactor:pure

description = "请模型将当前上下文中的代码重构为纯函数。"

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

你的回复需包含：
1. 重构后的纯函数代码片段；
2. 对关键改动的简要说明，以及它们如何保证纯函数特性。
"""
  1. 运行命令：
> @my-messy-function.js
> /refactor:pure

Gemini CLI 会先将文件注入，再执行 TOML 中定义的多行 Prompt。