OpenCode 自定义命令

在 OpenCode 中，自定义命令用于将重复性任务封装为快捷指令，从而大幅提升开发效率。你可以为常见操作（如测试、代码审查、生成组件等）定义统一入口，通过 /command 的形式快速触发。

OpenCode 的命令系统本质上是Prompt 工程 + 自动化工作流的结合。

通过合理设计命令，你可以将复杂操作标准化、一键化，从而将 AI 从工具升级为开发流程的一部分。

一、什么是自定义命令

自定义命令本质上是一个预定义提示词模板（Prompt Template），当你在 TUI 中执行该命令时，OpenCode 会将模板发送给 LLM 执行。

例如：

/test

执行后，会触发你定义好的测试分析逻辑，而无需每次重复输入完整提示词。

它是对内置命令（如 /init、/undo、/redo、/help）的重要补充。

二、创建命令（Markdown 方式）

推荐通过 Markdown 文件创建命令，结构清晰且易维护。

在项目目录中创建：

.opencode/commands/test.md

文件内容：

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

说明：

  • description：命令描述（显示在 UI 中）
  • agent：指定执行代理
  • model：指定使用的模型
  • 正文：实际发送给 LLM 的提示词

执行方式：

/test

三、JSON 配置方式

除了 Markdown 文件，你也可以在 opencode.json 中直接定义命令： 

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

这种方式适合集中配置或动态生成配置的场景。

四、命令参数（Arguments）

自定义命令支持通过参数动态传值，使其更加灵活。

1. 使用 $ARGUMENTS

---
description: Create component
---

Create a new React component named $ARGUMENTS.

执行：

/component Button

结果：

Create a new React component named Button.

2. 使用位置参数

支持按顺序访问参数：

  • $1：第一个参数
  • $2：第二个参数
  • $3：第三个参数

示例：

Create a file named $1 in $2 with content: $3

执行：

/create-file config.json src "{ \"key\": \"value\" }"

五、Shell 输出注入

可以通过 !`command` 将 shell 命令执行结果注入提示词，实现动态上下文。

示例：分析测试结果

Here are test results:
!`npm test`

Suggest improvements.

示例：分析 Git 提交

Recent commits:
!`git log --oneline -10`

Review changes and suggest improvements.

命令会在项目根目录执行，其输出将作为提示词的一部分传递给 LLM。

六、文件引用

使用 @文件路径 可以直接将文件内容注入提示词。

示例：

Review the component in @src/components/Button.tsx.

OpenCode 会自动读取文件内容并附加到上下文中。

七、核心配置项说明

字段 说明
template 命令执行时的提示词（必填）
description 命令描述（显示在 UI 中）
agent 指定执行代理（可选）
model 指定模型（可选）
subtask 是否强制作为子代理执行

八、Subtask（子任务执行）

通过 subtask: true，可以让命令在子代理中运行， 避免污染当前主对话上下文。 

{
  "command": {
    "analyze": {
      "template": "Analyze code quality",
      "subtask": true
    }
  }
}

适用于：

  • 大规模分析任务
  • 临时上下文计算
  • 不希望影响主对话的操作

九、命令覆盖机制

自定义命令可以覆盖内置命令。

例如：

  • 你定义了 /help
  • 则系统默认的 /help 将被替换

这一机制允许你构建完全定制化的工作流。

十、最佳实践

  • 将高频操作封装为命令（测试、审查、生成代码）
  • 结合参数实现动态命令
  • 利用 shell 输出增强上下文能力
  • 使用子任务避免污染主上下文
  • 团队项目建议统一维护 commands 目录