Command

Command 定义了可执行的命令模板和配置。

概述

Command 是 OpenCode 中的命令抽象，类似于快捷指令或预定义的提示词模板。用户可以通过命令名称快速触发特定的任务模式。命令可以来自内置定义、用户配置或 MCP 服务器。

定义位置

packages/opencode/src/command/index.ts:23-41

属性说明

| 属性名 | 类型 | 必填 | 说明 | | ------------- | ---------------- | ------- | -------------------------------------- | -------------------- | | name | string | 是 | 命令唯一名称 | | description | string | 否 | 命令描述 | | agent | string | 否 | 指定使用的 Agent | | model | string | 否 | 指定使用的模型（格式：provider/model） | | mcp | boolean | 否 | 是否来自 MCP 服务器 | | template | Promise<string> | string | 是 | 命令模板（支持异步） | | subtask | boolean | 否 | 是否为子任务命令 | | hints | string[] | 是 | 参数提示列表 |

TypeScript 类型定义

export type Command = {
  name: string
  description?: string
  agent?: string
  model?: string
  mcp?: boolean
  template: Promise<string> | string
  subtask?: boolean
  hints: string[]
}

内置命令

OpenCode 内置以下命令：

1. init

  • 描述: 创建或更新 AGENTS.md
  • 用途: 项目初始化
  • 模板: 包含项目路径的初始化提示词

2. review

  • 描述: 审查变更 [commit|branch|pr]，默认为未提交的变更
  • 用途: 代码审查
  • 子任务: true
  • 模板: 审查提示词，包含项目路径

命令模板语法

命令模板支持以下占位符：

占位符说明
$1, $2, ...位置参数（按编号引用）
$ARGUMENTS所有剩余文本参数

示例模板：

Please review the following changes:

$1

Additional context:
$ARGUMENTS

调用示例：

opencode review "Fix login bug" "in auth module"
# $1 = "Fix login bug"
# $ARGUMENTS = "in auth module"

从 MCP 加载命令

MCP 服务器可以提供 prompts，这些会被自动转换为 Command：

// MCP Prompt 转换为 Command
{
  name: "mcp_server:prompt_name",
  mcp: true,
  description: prompt.description,
  template: loadFromMCP(prompt),
  hints: ["$1", "$2"], // 来自 prompt.arguments
}

典型使用场景

1. 获取内置命令

const initCmd = await Command.get("init")

console.log(initCmd.name) // "init"
console.log(initCmd.description) // "create/update AGENTS.md"
console.log(initCmd.hints) // ["$ARGUMENTS"]

2. 列出所有可用命令

const commands = await Command.list()

for (const cmd of commands) {
  console.log(`${cmd.name}: ${cmd.description || "No description"}`)
}

3. 执行命令（获取模板）

const cmd = await Command.get("init")
const template = typeof cmd.template === "string" ? cmd.template : await cmd.template

console.log(template) // 输出完整的提示词模板

4. 替换模板占位符

const cmd = await Command.get("review")
let template = await cmd.template

// 替换 $1
template = template.replace(/\$1/g, "Fix authentication bug")

// 替换 $ARGUMENTS
template = template.replace(/\$ARGUMENTS/g, "in login.js")

console.log(template)

5. 用户自定义命令

在 opencode.jsonc 中定义：

{
  "command": {
    "deploy": {
      "description": "Deploy to production",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet",
      "subtask": false,
      "template": "Deploy the following changes:\n\n$1\n\nUse standard deployment procedures.",
      "hints": ["$1", "$ARGUMENTS"],
    },
  },
}

命令执行流程

对象关系

命令提示生成

OpenCode 自动从模板中提取提示：

function hints(template: string): string[] {
  const result: string[] = []

  // 提取 $1, $2, ... $N
  const numbered = template.match(/\$\d+/g)
  if (numbered) {
    for (const match of [...new Set(numbered)].sort()) {
      result.push(match)
    }
  }

  // 提取 $ARGUMENTS
  if (template.includes("$ARGUMENTS")) {
    result.push("$ARGUMENTS")
  }

  return result
}

变更历史

版本变更内容日期
v1初始 Command 架构-
v1.1添加 MCP 命令支持-
v1.2添加 subtask 字段-

相关文档