Gemini CLI：自定义斜杠命令

Posted on Edited on In , ,

banner

概述

Gemini CLI 在 7 月 31 日的更新中引入了一项强大的功能：自定义斜杠命令。这允许用户创建可复用的、带有参数的提示词，从而极大地简化常见任务并提高工作效率。一句话解释，就是用 TOML 将 Prompt 和 Shell 结合起来，并通过斜杠命令（Slash Command）简化调用。

原文链接: Gemini CLI: Custom slash commands

简单总结一下:

  1. Prompt 模板化：您把常用的、复杂的 prompt 写在 TOML 文件里，形成一个可复用的模板。
  2. Shell 能力注入：通过 !{...} 语法，您可以将 shell 命令的执行结果动态嵌入到 prompt 模板中，让 prompt 能获取本地文件的内容或系统信息。
  3. 斜杠命令调用：Gemini CLI 将这些 TOML 文件变成了简单易用的斜杠命令，让您用简短的命令触发复杂的、包含动态本地上下文的 prompt。

核心概念

1. 配置文件格式

自定义命令通过 TOML (.toml) 文件进行定义。这是目前唯一支持的格式。

2. 配置文件位置

Gemini CLI 会在以下两个位置查找命令配置文件：

  • 项目级: 在您项目的根目录下的 .gemini/commands/ 目录中。这允许您为特定项目定义命令。
  • 用户级: 在您用户主目录下的 ~/.gemini/commands/ 目录中。在这里定义的命令在所有项目中都可用。

3. 命令的定义

  • 文件名即命令名: 文件的名称（不含 .toml 后缀）决定了斜杠命令的名称。例如，plan.toml 文件会创建一个名为 /plan 的命令。
  • prompt 键: 每个命令文件都必须包含一个 prompt 键，其值就是您希望执行的提示词内容。

4. 在提示词中使用变量和 Shell 命令

  • 用户参数 ({{args}}): 您可以在 prompt 中使用 {{args}} 占位符，它会被替换为用户在斜杠命令后输入的任何文本。
  • Shell 命令 (!{...}): 您可以通过 !{...} 语法在提示词中嵌入任何 shell 命令的输出。这为与文件系统或其他工具交互提供了极大的灵活性。

5. 使用命名空间

您可以通过在 commands 目录下创建子目录来组织您的命令。例如，一个位于 .gemini/commands/git/commit.toml 的配置文件将创建一个名为 /git:commit 的命令。

6. 关于 """

在 TOML 文件中，您可以使用三重引号 """ 来定义多行字符串。这对于编写长提示词非常有用。类似于js的字符串模板`

实践示例

示例 1: 创建一个规划命令

假设您经常需要 Gemini 为某个任务制定计划而不是直接生成代码。

  1. 创建文件:
1
2
mkdir -p .gemini/commands
touch .gemini/commands/plan.toml
  1. 编辑文件内容:
1
2
3
4
5
6
7
8
9
10
11
12

# .gemini/commands/plan.toml

prompt = """
You are a world-class software engineer.
I want you to act as a thought-partner.
Do not generate code.
I am going to ask you a question, and I want you to describe a plan to answer it.

My question is: {{args}}
"""

  1. 使用命令:
1
2
3

/plan "Refactor the authentication module"

Gemini 将会收到被包裹后的提示词，并为您提供重构计划。

示例 2: 创建一个读取文件的命令

这个例子展示了如何结合 shell 命令来创建一个动态读取文件内容的命令。

  1. 创建文件:
1
touch .gemini/commands/file.toml
  1. 编辑文件内容:
1
2
3
4
5
6
7
8
9
10
# .gemini/commands/file.toml

prompt = """
I am going to ask you a question about the following file.
File path: {{args}}
File content:

!{cat {{args}}}

"""
  1. 使用命令:
1
/file "src/components/Button.tsx"

这会读取 src/components/Button.tsx 的内容，并将其作为上下文提供给 Gemini。

我的自定义命令

自动生成代码提交信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 文件路径: .gemini/commands/commit.toml
# 指令名称: /commit

description = "自动暂存所有更改，并根据 diff 内容生成一个完整的、符合规范的 git commit 命令。"

prompt = """
请严格扮演一个专业的Git提交信息生成器，并遵循 Conventional Commits v1.0.0 规范。
任务是根据以下 `git diff --staged` 的内容，生成一个**完整并且可以直接执行**的 `git commit -m \"...\"` 命令。

Staged Diff 内容:
!{git add -A && git diff --staged}

请遵循以下步骤分析 Diff 并构建提交信息：
1.  **类型(Type)**: 从 `feat`, `fix`, `refactor`, `chore`, `docs`, `style`, `test`, `perf` 中选择最合适的类型。
2.  **范围(Scope)**: 提供一个简短的名词来描述代码中受影响的部分 (例如: `api`, `db`, `ui`)。这是可选的。
3.  **描述(Description)**: 撰写一个简短、清晰的摘要，必须使用现在时祈使句 (例如: 使用 \"add\" 而不是 \"added\" 或 \"adds\")。

最后，将上述内容组合成一个符合 `type(scope): description` 格式的提交信息，并将其包装在一个完整的 shell 命令中。

**最终输出要求:**
- 最终输出**必须**是一个可以直接复制并执行的、单行的 `git commit` 命令。
- **不要**包含任何额外的解释、前言或结尾。
- 如果 diff 内容为空，则输出 `echo \"没有检测到任何更改需要提交。\"`。

请直接输出最终的命令。
"""

plan 模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# ~/.gemini/commands/plan.toml

description="Investigates and creates a strategic plan to accomplish a task."
prompt = """
Your primary role is that of a strategist, not an implementer.
Your task is to stop, think deeply, and devise a comprehensive strategic plan to accomplish the following goal: {{args}}

You MUST NOT write, modify, or execute any code. Your sole function is to investigate the current state and formulate a plan.

Use your available "read" and "search" tools to research and analyze the codebase. Gather all necessary context before presenting your strategy.

Present your strategic plan in markdown. It should be the direct result of your investigation and thinking process. Structure your response with the following sections:

1.  **Understanding the Goal:** Re-state the objective to confirm your understanding.
2.  **Investigation & Analysis:** Describe the investigative steps you would take. What files would you need to read? What would you search for? What critical questions need to be answered before any work begins?
3.  **Proposed Strategic Approach:** Outline the high-level strategy. Break the approach down into logical phases and describe the work that should happen in each.
4.  **Verification Strategy:** Explain how the success of this plan would be measured. What should be tested to ensure the goal is met without introducing regressions?
5.  **Anticipated Challenges & Considerations:** Based on your analysis, what potential risks, dependencies, or trade-offs do you foresee?

Your final output should be ONLY this strategic plan.
"""