命令

为重复性任务创建自定义命令。

自定义命令允许你在 TUI 中执行时，自动发送预先配置好的提示词（prompt）。

/my-command

自定义命令是对内置命令的补充，例如 /init、/undo、/redo、/share、/help 等。了解更多。

创建命令文件

在 command/ 目录中创建 Markdown 文件即可定义自定义命令。

例如新建 .opencode/command/test.md：

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

文件的 frontmatter 用于定义命令属性，正文内容则作为提示词模板。

在 TUI 中输入 / 加命令名即可使用该命令：

"/test"

配置

你可以通过 OpenCode 配置文件或在 command/ 目录中创建 Markdown 文件来添加自定义命令。

JSON

在 OpenCode 配置中使用 command 选项：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // 这里是命令名称
    "test": {
      // 这是发送给 LLM 的提示词
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      // 这是在 TUI 中显示的描述
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

现在你就可以在 TUI 中运行该命令：

/test

Markdown

你也可以通过 Markdown 文件来定义命令。放置位置可以是：

全局：~/.config/opencode/command/
项目级：.opencode/command/

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Markdown 文件的文件名会成为命令名称。例如，test.md 对应的命令为：

/test

提示词配置

自定义命令中的提示词支持多种占位符和特殊语法。

参数

使用 $ARGUMENTS 占位符向命令传递参数：

---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

使用参数运行命令：

/component Button

此时 $ARGUMENTS 会被替换为 Button。

你也可以使用位置参数访问各个独立参数：

$1 - 第一个参数
$2 - 第二个参数
$3 - 第三个参数
以此类推……

例如：

---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

运行命令：

/create-file config.json src "{ \"key\": \"value\" }"

替换效果为：

$1 → config.json
$2 → src
$3 → { "key": "value" }

Shell 输出

使用 !command 语法，将 Bash 命令的输出注入到提示词中。

例如，创建一个分析测试覆盖率的自定义命令：

---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

或者用于审查最近的变更：

---
description: Review recent changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements.

命令会在项目根目录执行，其输出会被注入到提示词中。

文件引用

可以在命令中使用 @ 加文件名来引用文件：

---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

文件内容会自动被包含到提示词中。

选项

下面是各配置项的详细说明。

Template

template 选项定义了执行命令时发送给 LLM 的提示词内容：

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
    }
  }
}

这是一个必需的配置项。

Description

description 选项用于为命令提供一句简短描述：

{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}

这段描述会在你输入命令名时显示在 TUI 中。

Agent

使用 agent 选项可以指定该命令应由哪个 Agent 执行。如果这是一个子 Agent，则该命令默认会以“子任务”形式调用它。若要禁用这一行为，可以将 subtask 设置为 false。

{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}

这是一个可选配置项。如果未设置，将使用当前会话所选的 Agent。

Subtask

使用布尔值 subtask 可以强制命令以子 Agent 方式执行。

这在你希望命令不要污染当前主上下文时非常有用，会强制以子 Agent 模式运行，即使在 Agent 配置中 mode 设置为 primary。

{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}

这是一个可选配置项。

Model

使用 model 选项可以为该命令覆盖默认模型：

{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

这是一个可选配置项。

内置命令

opencode 内置了多个命令，例如 /init、/undo、/redo、/share、/help 等；详细说明见 TUI 文档。

如果你定义了一个与内置命令同名的自定义命令，它会覆盖对应的内置命令行为。