建立自定義命令

Custom commands 讓你把重複提示詞做成 TUI 裡的 /xxx 入口。它不是為了少打幾個字，而是把任務邊界、執行 agent、模型選擇、引數和輸出結構固定下來。

這一篇用 10 分鐘換什麼：你會知道什麼時候該寫 command、Markdown 和 JSON 兩種方式怎麼選、$ARGUMENTS / $1 怎麼用、! 和 @ 怎麼注入上下文，以及為什麼不要隨便覆蓋內建命令。

先判斷該不該沉澱成 command

一條提示詞至少反覆用過幾次，再考慮寫成 command。

flowchart LR
    Prompt["一次性提示詞"] --> Repeat{"同類流程反覆出現?"}
    Repeat -->|否| Keep["繼續在對話裡寫"]
    Repeat -->|是| Stable{"邊界和輸出穩定?"}
    Stable -->|否| Improve["先打磨提示詞"]
    Stable -->|是| Command["寫成 /command"]
    Command --> Share{"團隊也需要?"}
    Share -->|是| Project["放 .opencode/commands/"]
    Share -->|否| Global["放 ~/.config/opencode/commands/"]

    style Command fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Project fill:#dcfce7,stroke:#22c55e

適合做成 command：

每週都會做的固定動作，例如測試、審查、生成釋出說明。
需要穩定輸出結構的動作，例如“先列風險，再給改法，再列測試”。
團隊希望統一做法的動作，例如 PR 自檢、遷移檢查、文件審查。

不適合：一次性問題、邊界還沒想清楚的複雜需求、開放式探索任務、已經有內建命令覆蓋的動作。

1. Markdown command 推薦起步

專案級命令放在 .opencode/commands/。例如：

.opencode/commands/test.md

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report.
If anything fails, identify the failing case, likely cause, and smallest next fix.

文件名就是命令名。test.md 对应：

/test

Markdown 文件更适合长 prompt，因为它容易阅读、review、版本化。项目命令可以提交到 Git，让团队使用同一套任务入口。

2. 全局和项目级怎么选

位置	适合什么
`.opencode/commands/`	当前仓库的测试、发布、迁移、PR 审查、文档检查
`~/.config/opencode/commands/`	个人跨项目通用命令，例如总结 diff、解释报错、整理提交信息

默认从项目级开始。只要 prompt 里引用了项目路径、测试命令、目录结构或团队规则，就不要放进全局。

3. JSON command 适合短命令

也可以在 opencode.json / opencode.jsonc 里用 command 配置。

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "review": {
      "template": "Review the current git diff. Focus on bugs, regressions, security, and missing tests.",
      "description": "Review current changes",
      "agent": "plan"
    }
  }
}

template 是必填项，description 会显示在 TUI 命令列表里。JSON 适合一两个短命令；长提示词、步骤和示例更适合 Markdown 文件。

4. 参数怎么用

$ARGUMENTS 代表命令后面的整段输入。

.opencode/commands/component.md

---
description: Create a component plan
---

Create an implementation plan for $ARGUMENTS.
Include files to touch, edge cases, and tests.

运行：

/component Button

这里 $ARGUMENTS 会变成 Button。

也可以使用位置参数：$1、$2、$3。但位置参数越多，命令越像脚本，越容易误用。新手优先用 $ARGUMENTS。

5. 注入 shell 输出和文件

Command prompt 可以使用 ! 注入 shell 输出，也可以用 @ 引用文件。

.opencode/commands/review-diff.md

---
description: Review current diff
---

Current changes:
!`git diff --stat`
!`git diff`

Review only. Do not modify files.

檔案引用示例：

Review @src/components/Button.tsx for performance and accessibility issues.

! 會執行命令並把輸出放進 prompt。只讀命令適合，刪除、釋出、資料庫寫操作和修改全域性環境的命令不適合寫進 command。

6. agent、subtask 和 model

Command 可以指定執行它的 agent 和 model。

幾個邊界要記住：

agent 可選；不指定時使用當前 agent。
如果 agent 是 subagent，官方文件說明 command 預設會觸發 subagent invocation。
如果不想讓 subagent 預設執行，可以設定 subtask: false。
subtask: true 可以強制讓命令作為 subagent 執行，避免汙染主會話上下文。
model 可以覆蓋當前預設模型，但只在確實需要特殊模型時配置，不要每個 command 都硬綁模型。

7. 不要覆蓋內建命令

OpenCode 已有 /init、/undo、/redo、/share、/help 等內建命令。官方文件說明 custom commands 可以覆蓋內建命令。

除非你明確知道後果，否則不要建立 init.md、undo.md、share.md 這類同名 command。要改變安全邊界，用 config 和 permission；不要靠覆蓋內建命令製造隱性行為。

8. 怎麼判斷寫對了

一個可交付的 command 應該滿足：

名字短，一眼能看懂。
一個 command 只做一類任務。
輸出結構穩定，不需要每次再補說明。
引數少，最好先用 $ARGUMENTS。
shell 注入只用只讀命令。
專案級命令可 review、可刪除、可追蹤影響範圍。

如果每次執行還要補一大段解釋，說明 command 沒有把任務邊界寫清楚。

接下來去哪

配置

理解 command 應該放在專案配置、Markdown 檔案還是全域性配置。

Rules

長期約束寫進 rules，重複流程寫成 command，不要混用。

Agents

當 command 需要固定角色、模型或許可權時，再考慮自定義 agent。

TUI

Command 最終在 TUI 裡使用，先理解 `/` 命令和快捷鍵。

官方資料

OpenCode Commands：https://opencode.ai/docs/commands
OpenCode TUI Commands：https://opencode.ai/docs/tui#commands
OpenCode Config：https://opencode.ai/docs/config
OpenCode Agents：https://opencode.ai/docs/agents

建立自定義命令

配置

Rules

Agents

TUI

本頁目錄