自訂指令

摘要

自訂指令（Custom Commands）是 OpenCode 最強大的生產力功能之一。你可以將常用的提示詞、操作流程封裝成斜線指令，在 TUI 中以 /<command> 的形式快速呼叫。本章介紹 JSON 與 Markdown 兩種設定方式，以及參數、注入、檔案參照等進階功能。

學習目標

• 理解自訂指令的兩種設定格式
• 學會使用 $ARGUMENTS 與位置參數 $1, $2, $3
• 掌握 Shell 輸出注入與檔案參照
• 熟悉指令的進階選項（agent、model、subtask）
• 能夠覆寫內建指令

JSON 設定方式

在 opencode.json 的 commands 欄位中定義：

{
  "commands": {
    "explain": {
      "description": "解釋選取的程式碼",
      "prompt": "請用繁體中文解釋以下程式碼的工作原理：\n\n$ARGUMENTS"
    },
    "refactor": {
      "description": "重構選取的程式碼",
      "prompt": "請重構以下程式碼，使其更簡潔、可讀性更高：\n\n$ARGUMENTS"
    },
    "test": {
      "description": "為選取的程式碼產生測試",
      "prompt": "請為以下程式碼撰寫單元測試：\n\n$ARGUMENTS"
    }
  }
}

$ARGUMENTS 是一個特殊變數，在執行時會被替換為使用者在指令後輸入的全部內容。

Markdown 設定方式

在 AGENTS.md 或獨立的 .mdc 檔案中使用 YAML frontmatter 定義：

---
command: explain
description: 解釋選取的程式碼
---

請用繁體中文解釋以下程式碼的工作原理：

$ARGUMENTS

Markdown 方式的好處是提示詞可以寫得更長、更結構化，且易於版本控制。

你也可以建立目錄來組織多個指令：

.opencode/
  commands/
    explain.mdc
    refactor.mdc
    test.mdc

位置參數

除了 $ARGUMENTS（全部參數），你也可以使用位置參數精確控制輸入：

{
  "commands": {
    "commit": {
      "description": "產生 git commit message",
      "prompt": "根據以下 diff 產生一個簡潔的 git commit message：\n\n$1"
    },
    "review": {
      "description": "審查 PR",
      "prompt": "請審查以下 PR diff（變更語言：$1）：\n\n$2\n\n請專注於：架構、安全性、效能。"
    }
  }
}

使用方式：/commit "feat: add login" 或 /review python "diff內容"。

Shell 輸出注入

可以在提示詞中嵌入 Shell 指令的輸出，使用 !`command` 語法：

{
  "commands": {
    "fix": {
      "description": "修正編譯錯誤",
      "prompt": "以下是專案中最近的編譯錯誤：\n\n!`cargo build 2>&1 | tail -50`\n\n請分析並提供修復方案。"
    },
    "status": {
      "description": "分析專案狀態",
      "prompt": "當前 Git 狀態：\n\n!`git status`\n\n最近提交：\n\n!`git log --oneline -10`\n\n請根據以上資訊提供建議。"
    }
  }
}

Shell 注入在指令執行時即時執行，讓提示詞永遠基於最新狀態。

檔案參照

使用 @filename 語法參照專案中的檔案：

{
  "commands": {
    "document": {
      "description": "為函式產生文件",
      "prompt": "請為 @$1 中的每個公開函式撰寫 JSDoc 註解。\n\n$ARGUMENTS"
    },
    "refactor-file": {
      "description": "重構指定檔案",
      "prompt": "請重構 @$1，使其遵循 SOLID 原則。\n\n$ARGUMENTS"
    }
  }
}

使用方式：/document src/utils.ts 加入型別註解。

進階選項

自訂指令支援多個進階選項，讓你可以精細控制行為：

{
  "commands": {
    "security-audit": {
      "description": "執行安全性稽核",
      "prompt": "請稽核以下程式碼的安全性漏洞：\n\n$ARGUMENTS",
      "agent": "explore",        // 指定使用的代理
      "model": "claude-opus-4-20250514:high",  // 指定模型（含變體）
      "temperature": 0.2,        // 控制創造力（0-1）
      "subtask": true,           // 在子任務中執行
      "hidden": false            // 是否隱藏於指令清單
    },
    "quick": {
      "description": "快速回答",
      "prompt": "請簡潔回答：$ARGUMENTS",
      "model": "claude-haiku-4",
      "temperature": 0.7
    }
  }
}

選項說明

• agent — 指定由哪個代理執行（build、plan、general、explore、scout）
• model — 指定使用的模型，支援變體語法（如 :high）
• temperature — 控制回覆的隨機性，0.0 = 確定性，1.0 = 高創造力
• subtask — 設為 true 時在子代理中執行，不阻塞主對話
• hidden — 設為 true 時從指令清單中隱藏，但仍可手動輸入

內建指令覆寫

你可以覆寫 OpenCode 的內建指令，自訂其行為：

{
  "commands": {
    "help": {
      "description": "顯示自訂說明",
      "prompt": "你是 OpenCode 使用專家。請根據使用者的問題提供幫助：\n\n$ARGUMENTS"
    },
    "clear": {
      "description": "清除對話（含確認）",
      "prompt": "請先確認使用者是否真的要清除對話，然後回覆 CLEAR_CONFIRMED。"
    }
  }
}

可覆寫的內建指令包括：help、clear、new、search 等。覆寫時需注意原指令的功能是否仍可透過其他方式存取。

實戰練習

{
  "commands": {
    "doc": {
      "description": "為程式碼產生文件註解",
      "prompt": "請為以下程式碼產生完整的文件註解（繁體中文）：\n\n$ARGUMENTS"
    },
    "find-bug": {
      "description": "尋找程式碼中的潛在錯誤",
      "prompt": "請仔細檢查以下程式碼，找出所有潛在的錯誤、邊界情況和效能問題：\n\n$ARGUMENTS"
    },
    "simplify": {
      "description": "簡化複雜的程式碼",
      "prompt": "請將以下程式碼簡化，在保持相同功能的同時減少行數和提高可讀性：\n\n$ARGUMENTS"
    }
  }
}

{
  "commands": {
    "project-status": {
      "description": "分析專案健康狀態",
      "prompt": "請根據以下資訊分析專案狀態並給出建議：\n\n## 未提交的變更\n!`git diff --stat`\n\n## 最近提交\n!`git log --oneline -5`\n\n## 未追蹤檔案\n!`git status --porcelain | head -20`\n\n## 分支\n!`git branch -a`"
    }
  }
}

{
  "commands": {
    "quick-review": {
      "description": "快速程式碼審查（Haiku）",
      "prompt": "請快速審查以下程式碼，列出 3 個最重要的改進點：\n\n$ARGUMENTS",
      "agent": "general",
      "model": "claude-haiku-4"
    },
    "deep-review": {
      "description": "深度程式碼審查（Opus）",
      "prompt": "請進行深度程式碼審查，包含：安全性、效能、可維護性、測試覆蓋率：\n\n$ARGUMENTS",
      "agent": "explore",
      "model": "claude-opus-4-20250514:max",
      "temperature": 0.3
    }
  }
}