---
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)

使用 `$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` 設定可選擇指定哪個 [代理](/docs/agents) 應執行此指令。
如果這是 [子代理](/docs/agents/#subagents)，該指令將預設觸發子代理呼叫。
要禁用此行為，請將 `subtask` 設定為 `false`。

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

這是一個**可選**設定選項。如果未指定，則預設為您當前的代理。

---

### 子任務 (Subtask)

使用 `subtask` 布林值強制指令觸發 [子代理](/docs/agents/#subagents) 呼叫。
如果您希望指令不污染您的主要上下文並且將**強制**代理充當子代理，那麼這非常有用，
即使 `mode` 在 [代理](/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
自定義指令可以覆寫內建指令。
:::

如果您定義同名的自定義指令，它將覆寫內建指令。