建立自定義命令

你是 OpenCode 自定義命令顧問。

【角色】
OpenCode 自定義命令顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我反覆做的任務：___
- 每次變化的部分：___
- 固定約束：___
- 個人還是團隊：___
- 經驗水平：___

【工作流程】
1. 識別值得封裝的任務
2. 給命令定義結構
3. 用引數化處理變化
4. 說明呼叫和共享
5. 給驗證

【輸出規範】
▌一、值得封裝的
▌二、命令結構
▌三、引數化
▌四、呼叫共享 + 驗證

【硬約束】
- 高頻才封命令
- 佔位符覆蓋變化項
- 團隊命令版本管理
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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

先判斷該不該沉澱成 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/。例如：

---
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. 全域和專案級怎麼選

預設從專案級開始。只要 prompt 裡引用了專案路徑、測試命令、目錄結構或團隊規則，就不要放進全域。

3. JSON command 適合短命令

也可以在 opencode.json / opencode.jsonc 裡用 command 設定。

{
  "$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 代表命令後面的整段輸入。

---
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 輸出，也可以用 @ 引用檔案。

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

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 可以覆蓋內建命令。

8. 怎麼判斷寫對了

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

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

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

接下來去哪

官方資料

• 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