---
title: 命令
description: 为重复任务创建自定义命令。
---

自定义命令允许您指定在 TUI 中执行该命令时要运行的提示。

```bash frame="none"
/my-command
```

除了 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令之外，还有自定义命令。 [了解更多](/docs/tui#commands)。

---

## 创建命令文件

在 `commands/` 目录中创建 markdown 文件来定义自定义命令。

创建 `.opencode/commands/test.md`：

```md title=".opencode/commands/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 定义命令属性。内容成为模板。

通过键入 `/` 后跟命令名称来使用该命令。

```bash frame="none"
"/test"
```

---

## 配置

您可以通过 opencode 配置或通过在 `commands/` 目录中创建 markdown 文件来添加自定义命令。

---

### JSON

在 opencode [配置](/docs/config) 中使用 `command` 选项：

```json title="opencode.jsonc" {4-12}
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // This becomes the name of the command
    "test": {
      // This is the prompt that will be sent to the LLM
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      // This is shown as the description in the TUI
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```

现在您可以在 TUI 中运行这个命令：

```bash frame="none"
/test
```

---

### Markdown

您还可以使用 Markdown 文件定义命令。将它们放入：

- 全局：`~/.config/opencode/commands/`
- 每个项目：`.opencode/commands/`

```markdown title="~/.config/opencode/commands/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.
```

Markdown 文件名成为命令名。例如，`test.md` 让
你运行：

```bash frame="none"
/test
```

---

## 提示配置

自定义命令的提示支持几个特殊的占位符和语法。

---

### 参数

使用 `$ARGUMENTS` 占位符将参数提交给命令。

```md title=".opencode/commands/component.md"
---
description: Create a new component
---

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

使用参数运行命令：

```bash frame="none"
/component Button
```

`$ARGUMENTS` 将替换为 `Button`。

您还可以使用位置参数访问各个参数：

- `$1` - 第一个参数
- `$2` - 第二个参数
- `$3` - 第三个参数
- 等等...

例如：

```md title=".opencode/commands/create-file.md"
---
description: Create a new file with content
---

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

运行命令：

```bash frame="none"
/create-file config.json src "{ \"key\": \"value\" }"
```

这取代了：

- `$1` 与 `config.json`
- `$2` 与 `src`
- `$3` 与 `{ "key": "value" }`

---

### Shell 输出

使用 _!`command`_ 将 [bash 命令](/docs/tui#bash-commands) 输出注入到提示符中。

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

```md title=".opencode/commands/analyze-coverage.md"
---
description: Analyze test coverage
---

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

Based on these results, suggest improvements to increase coverage.
```

或者查看最近的更改：

```md title=".opencode/commands/review-changes.md"
---
description: Review recent changes
---

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

Review these changes and suggest any improvements.
```

命令在项目的根目录中运行，其输出成为提示的一部分。

---

### 文件引用

使用 `@` 后跟文件名将文件包含在命令中。

```md title=".opencode/commands/review-component.md"
---
description: Review component
---

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

文件内容会自动包含在提示中。

---

## 选项

让我们详细看看配置选项。

---

### template

`template` 选项定义执行命令时将发送到 LLM 的提示。

```json title="opencode.json"
{
  "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` 选项提供命令功能的简要描述。

```json title="opencode.json"
{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}
```

当您输入命令时，这将在 TUI 中显示为描述。

---

### agent

使用 `agent` 配置选择指定哪个 [Agent](/docs/agents) 应执行此命令。
如果是 [Subagents](/docs/agents/#subagents) 该命令将默认触发子代理调用。
要取消此行为，则将 `subtask` 设置为 `false`。

```json title="opencode.json"
{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}
```

这是一个 **可选** 配置选项。如果未指定，则默认为您当前的代理。

---

### subtask

使用 `subtask` 布尔值强制命令触发 [Subagents](/docs/agents/#subagents) 调用。
如果您希望命令不污染您的主要上下文并且将 **强制** 代理充当子代理，那么这非常有用，
即使 `mode` 在 [Agent](/docs/agents) 配置上设置为 `primary`。

```json title="opencode.json"
{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}
```

这是一个 **可选** 配置选项。

---

### model

使用 `model` 配置覆盖此命令的默认模型。

```json title="opencode.json"
{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```

这是一个 **可选** 配置选项。

---

## 内置

opencode 包含 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令；[了解更多](/docs/tui#commands)。

:::note
自定义命令可以覆盖内置命令。
:::

如果您定义同名的自定义命令，它将覆盖内置命令。