14.3 Command 系统

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

Command（命令）系统是 OpenCode 用户交互的另一个扩展点——它允许用户定义自定义的 Slash Command（斜杠命令），将常用的提示词模板化、参数化，实现一键触发复杂操作。

14.3.1 自定义 Slash Command 机制

Slash Command 以 / 开头，用户在 TUI 的输入框中输入 /init 或 /review 等命令来触发预定义的操作。

Command 的数据模型：

// command/index.ts
export const Info = z.object({
  name: z.string(),                    // 命令名称
  description: z.string().optional(),  // 描述
  agent: z.string().optional(),        // 指定 Agent
  model: z.string().optional(),        // 指定模型
  source: z.enum(["command", "mcp", "skill"]).optional(),  // 来源
  template: z.promise(z.string()).or(z.string()),           // 提示词模板
  subtask: z.boolean().optional(),     // 是否作为子任务执行
  hints: z.array(z.string()),          // 参数提示列表
})

模板变量

Command 的模板支持两种变量：

• 编号变量（$1、$2、$3...）：按位置替换用户提供的参数。

• $ARGUMENTS：替换为用户输入的完整参数字符串。

# /review 命令的模板示例
Review the changes in ${path}.
$1 defaults to uncommitted changes.
Focus on: $ARGUMENTS

hints() 函数从模板中提取所有变量，用于在 TUI 中显示参数提示：

export function hints(template: string): string[] {
  const result: string[] = []
  const numbered = template.match(/\$\d+/g)
  if (numbered) {
    for (const match of [...new Set(numbered)].sort()) result.push(match)
  }
  if (template.includes("$ARGUMENTS")) result.push("$ARGUMENTS")
  return result
}

14.3.2 内置命令

OpenCode 内置了两个命令：

const Default = {
  INIT: "init",
  REVIEW: "review",
} as const

const result: Record<string, Info> = {
  [Default.INIT]: {
    name: "init",
    description: "create/update AGENTS.md",
    source: "command",
    get template() {
      return PROMPT_INITIALIZE.replace("${path}", Instance.worktree)
    },
    hints: hints(PROMPT_INITIALIZE),
  },
  [Default.REVIEW]: {
    name: "review",
    description: "review changes [commit|branch|pr], defaults to uncommitted",
    source: "command",
    get template() {
      return PROMPT_REVIEW.replace("${path}", Instance.worktree)
    },
    subtask: true,
    hints: hints(PROMPT_REVIEW),
  },
}

• /init：引导 Agent 创建或更新项目的 AGENTS.md 文件（项目规范说明）。

• /review：让 Agent 审查代码变更。subtask: true 表示该命令会创建一个子会话来执行，不影响当前会话的上下文。

14.3.3 三种命令来源

Command 系统统一了三种不同来源的命令：

用户配置命令

通过 opencode.json 的 command 字段定义：

{
  "command": {
    "test": {
      "description": "Run and fix failing tests",
      "template": "Run `npm test` in ${path}. If any tests fail, fix them. $ARGUMENTS",
      "agent": "build"
    }
  }
}

MCP Prompt 命令

MCP Server 暴露的 Prompt 会被自动注册为命令：

for (const [name, prompt] of Object.entries(await MCP.prompts())) {
  result[name] = {
    name,
    source: "mcp",
    description: prompt.description,
    get template() {
      // 异步获取 MCP Prompt 内容
      return new Promise<string>(async (resolve, reject) => {
        const template = await MCP.getPrompt(prompt.client, prompt.name, /* args */)
        resolve(template?.messages.map(m => m.content.text).join("\n") || "")
      })
    },
    hints: prompt.arguments?.map((_, i) => `$${i + 1}`) ?? [],
  }
}

注意 template 使用了 getter + Promise——因为 MCP Prompt 的内容需要异步从 MCP Server 获取。Zod Schema 使用 z.promise(z.string()).or(z.string()) 来同时支持同步和异步模板。

Skill 命令

每个 Skill 也会被注册为一个命令（除非已有同名命令）：

for (const skill of await Skill.all()) {
  if (result[skill.name]) continue  // 不覆盖已有命令
  result[skill.name] = {
    name: skill.name,
    description: skill.description,
    source: "skill",
    get template() {
      return skill.content
    },
    hints: [],
  }
}

用户输入 /git-master 时，实际上会将 git-master Skill 的完整内容作为提示词发送给 Agent。这提供了一种快捷方式——不需要 Agent 自己决定加载哪个 Skill，用户直接通过命令指定。

14.3.4 命令优先级

当三种来源出现同名命令时，优先级为：

内置命令 > 用户配置命令 > MCP Prompt 命令 > Skill 命令

这种优先级确保了内置功能不会被意外覆盖，同时用户配置可以覆盖外部来源的命令。

14.3.5 命令事件

命令执行时会发布一个事件：

export const Event = {
  Executed: BusEvent.define("command.executed", z.object({
    name: z.string(),
    sessionID: Identifier.schema("session"),
    arguments: z.string(),
    messageID: Identifier.schema("message"),
  })),
}

这个事件被 Plugin 的 command.execute.before 钩子捕获，允许 Plugin 在命令执行前注入额外的上下文。

14.3.6 小结

Command 系统将三种不同来源（用户配置、MCP Prompt、Skill）的命令统一到一个接口下，提供了一致的用户体验：

特性	用户配置	MCP Prompt	Skill
定义位置	opencode.json	MCP Server	SKILL.md
模板	同步字符串	异步 Promise	同步字符串
参数	$1、$ARGUMENTS	$1、$2	无参数
可指定 Agent	✅	❌	❌
可指定 Model	✅	❌	❌
子任务模式	✅	❌	❌

这种统一设计使得用户不需要关心命令的来源——无论是手写的模板、MCP Server 提供的 Prompt，还是一个 Skill 文件，都可以通过 /命令名 的方式一键触发。