OpenCode 自定义命令（Commands）系统完全指南：用快捷指令提升 AI 编程效率

在日常开发中，我们经常需要向 AI 编程助手重复提出类似的需求：运行测试、审查代码、创建组件、提交代码等。OpenCode 的自定义命令（Commands）系统正是为解决这一痛点而设计——它允许你将常用的 Prompt 封装为可复用的斜杠命令，一键触发复杂的 AI 任务，显著提升开发效率。

本文将全面介绍 OpenCode 自定义命令系统的配置方式、模板语法、高级选项以及实战案例，帮助你打造属于自己的 AI 指令集。

什么是自定义命令？

OpenCode 内置了一系列斜杠命令，如 /init（初始化项目）、/undo（撤销更改）、/share（分享对话）等。自定义命令在此基础上扩展，让你可以创建属于自己的命令。例如，配置一个 /test 命令后，只需在 TUI 中输入 /test，OpenCode 就会自动执行你预设的 Prompt，无需每次都手动输入冗长的测试指令。

自定义命令支持两种配置方式：JSON 配置（在 opencode.json 中定义）和 Markdown 文件（在 commands/ 目录中创建）。两种方式在功能上等价，你可以根据习惯选择。

配置自定义命令

方式一：JSON 配置

在项目根目录的 opencode.json 或 opencode.jsonc 中，通过 command 字段定义命令：

{
  "$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"
    }
  }
}

每个命令对象包含以下核心字段：

  • template（必填）：发送给 LLM 的 Prompt 模板
  • description（可选）：在 TUI 中输入 / 时显示的描述文本
  • agent（可选）：指定执行该命令的 Agent，如 build、plan 等
  • model（可选）：覆盖默认模型，指定使用某个特定模型
  • subtask（可选）：是否以子任务模式执行，避免污染主会话上下文

方式二：Markdown 文件

在 .opencode/commands/ 目录或全局目录 ~/.config/opencode/commands/ 下创建 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.

文件中的 YAML frontmatter 对应 JSON 配置中的选项，正文内容对应 template。这种方式的优势在于文件结构清晰，便于版本控制和管理。

模板语法与高级占位符

自定义命令的真正威力在于其灵活的模板语法。OpenCode 提供了多种占位符，让命令能够接收动态参数并注入上下文。

参数占位符 $ARGUMENTS

将命令与具体参数结合，可以创建通用的生成工具。例如，创建一个用于生成 React 组件的命令：

.opencode/commands/component.md：

---
description: Create a new React component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing, a basic structure with props interface, and a default export.

使用方式：

/component Button
/component UserProfile
/component DataTable

$ARGUMENTS 会被替换为你输入的实际参数。

位置参数 $1、$2、$3

当你需要多个参数时，位置参数比 $ARGUMENTS 更精确：

.opencode/commands/create-file.md：

---
description: Create a new file with content
---

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

运行命令：

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

OpenCode 会依次替换 $1 为 config.json、$2 为 src、$3 为 { "key": "value" }。

Shell 命令注入 !

你可以在模板中嵌入 Shell 命令，将其输出作为 Prompt 的一部分。语法为 ` !command `。

.opencode/commands/analyze-coverage.md：

---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

另一个实用场景：审查最近的代码更改：

---
description: Review recent changes
---

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

Review these changes and suggest any improvements or potential issues.

Shell 命令在项目根目录执行，其输出会被追加到 Prompt 中，让 AI 能够基于真实的项目状态进行分析。

文件引用 @

如果你想在命令中引用项目中的特定文件，使用 @ 符号：

---
description: Review a component
---

Review the component in @src/components/Button.tsx.
Check for performance issues, accessibility problems, and suggest improvements.

OpenCode 会自动读取文件内容并注入到 Prompt 中。你也可以指定行号范围，如 @src/utils.ts#L37-42。

高级配置选项

指定执行 Agent

通过 agent 字段，你可以让命令使用不同的 Agent 模式执行：

{
  "command": {
    "plan-feature": {
      "template": "Create a detailed plan for implementing user authentication...",
      "description": "Plan a new feature",
      "agent": "plan"
    },
    "implement": {
      "template": "Implement the changes as planned...",
      "description": "Implement changes",
      "agent": "build"
    }
  }
}

这样，/plan-feature 会以计划模式（只输出方案，不执行更改）运行，而 /implement 会以构建模式（直接修改代码）运行。

子任务模式

设置 subtask: true 后，命令会以子 Agent 的形式执行，其上下文不会污染主会话：

{
  "command": {
    "analyze": {
      "template": "Analyze the codebase for security vulnerabilities...",
      "subtask": true
    }
  }
}

这在执行独立的分析任务时非常有用，主会话的上下文窗口不会被打满。

覆盖模型

你可以为特定命令指定不同的模型，例如用更强大的模型进行代码审查，用轻量模型做快速分析：

{
  "command": {
    "quick-lint": {
      "template": "Quickly check @$1 for obvious bugs",
      "description": "Quick code lint",
      "model": "anthropic/claude-3-5-haiku-latest"
    },
    "deep-review": {
      "template": "Perform a thorough security review of @$1...",
      "description": "Deep security review",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

实战案例

案例一：完整的 Git 提交流程

创建一个命令来完成代码审查、生成 commit message 并提交：

.opencode/commands/commit.md：

---
description: Review changes and create a commit
---

Review the current changes:
!`git diff --staged`

Generate a conventional commit message based on the changes.
Then commit with:
!`git commit -m "<generated-message>"`

案例二：API 端点生成器

创建 RESTful API 端点的标准化命令：

.opencode/commands/api.md：

---
description: Create a new API endpoint
---

Create a new API endpoint $1 in the routes/$1.ts file.
Follow the existing patterns in @src/routes/ for consistency.
Include:
- Input validation
- Error handling
- Proper HTTP status codes
- TypeScript types for request/response
- Unit tests in __tests__/$1.test.ts

使用：/api users 或 /api products。

案例三：多文件重构命令

---
description: Refactor a module
---

Refactor the module at @$1 by:
1. Splitting it into smaller, focused functions
2. Extracting types to a separate type file
3. Adding JSDoc comments to all public APIs
4. Writing unit tests for each function

Follow the coding style found in @src/utils/.

内置命令覆盖

值得注意的是，自定义命令可以覆盖内置命令。如果你对内置的 /init 行为不满意，可以创建自己的 .opencode/commands/init.md 来实现定制化的初始化流程。OpenCode 会优先使用自定义版本。

最佳实践

命名清晰：命令名应简短且表达意图，如 /test、/lint、/deploy

提供 description：为每个命令编写清晰的描述，方便团队成员了解命令用途

使用 Shell 注入获取实时状态：利用 ` !command ` 让命令感知当前项目状态

文件引用增强上下文：用 @ 引用关键文件，让 AI 理解项目现有模式

按场景选择模型：耗时任务用强模型，简单任务用轻量模型，平衡质量与成本

团队共享：将 .opencode/commands/ 目录纳入版本控制，团队成员共享同一套命令集

总结

OpenCode 的自定义命令系统是一个强大的效率工具，它将重复性 Prompt 封装为一键触发的快捷指令。通过灵活的模板语法、参数传递、Shell 注入和文件引用，你可以构建出高度智能化的开发助手。无论是日常的测试、审查、提交，还是复杂的代码生成和重构任务，自定义命令都能让 AI 编程体验更上一层楼。

不妨从今天开始，留意你在开发中反复向 AI 提出的需求，将它们逐一封装为自定义命令，打造真正属于你的 AI 编程利器。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客