OpenCode 自定义命令（Commands）完全指南：用快捷指令自动化重复性编程任务

OpenCode 自定义命令（Commands）完全指南：用快捷指令自动化重复性编程任务

在日常开发中，我们经常会重复执行一些固定的操作：运行测试、代码审查、创建组件、分析覆盖率……这些操作虽然不复杂，但每次都要输入一长串提示词，既浪费时间又容易遗漏细节。OpenCode 的自定义命令（Commands）功能正是为了解决这个问题而生——它允许你将常用的提示词封装成快捷指令，只需输入 /command-name 即可一键执行。

本文将全面介绍 OpenCode 自定义命令的创建、配置和使用方法，帮助你打造一套属于自己的开发效率工具箱。

什么是自定义命令

自定义命令是 OpenCode 提供的一种快捷方式机制。你可以将一段固定的提示词（prompt）注册为一个命令，在 TUI 界面中输入 / 开头加上命令名即可触发。

比如，你每周都要对整个项目做一次代码审查，手动输入提示词可能是这样的：

Review the entire codebase and look for potential bugs, performance issues, and security vulnerabilities.

有了自定义命令后，只需输入：

/review-all

OpenCode 会自动将你预先定义的提示词发送给 LLM，省去了重复输入的烦恼。更重要的是，自定义命令还支持参数传递、Shell 输出注入、文件引用等高级功能，远远不只是简单的字符串替换。

创建自定义命令

OpenCode 提供了两种方式来定义自定义命令：JSON 配置和 Markdown 文件。

方式一：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"
    }
  }
}

每个命令的键名（如上例的 test）就是你在 TUI 中输入的 /test 命令的名称。配置项中 template 是必需的，它定义了发送给 LLM 的提示词。

方式二：Markdown 文件

你也可以将命令定义为独立的 Markdown 文件，放在以下两个位置：

• 全局级别：~/.config/opencode/commands/
• 项目级别：.opencode/commands/

文件名为命令名，例如创建 .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（两个 --- 之间的部分）用于定义命令属性，后面的正文就是 template 对应的提示词内容。

使用 Markdown 文件方式的优势在于：每个命令都是一个独立文件，便于版本管理和团队共享。

高级提示词技巧

自定义命令的真正威力体现在它支持的几种特殊语法上。

参数传递：$ARGUMENTS

如果你的命令需要根据不同的输入执行不同操作，可以使用 $ARGUMENTS 占位符。例如，创建一个生成 React 组件的命令：

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

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

使用时传入参数：

/component UserCard

$ARGUMENTS 会被替换为 UserCard。如果需要更精细地控制参数，还可以使用位置参数 $1、$2、$3 等：

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

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

执行：

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

Shell 输出注入：` !command `

这是最强大的功能之一。你可以将任意 Shell 命令的输出注入到提示词中，让 LLM 基于实时数据做出判断。

例如，创建一个分析测试覆盖率的命令：

---
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.

Shell 命令在工作目录的根目录执行，输出结果会自动成为提示词的一部分。这意味着你可以编写任意复杂的脚本来收集上下文信息，然后让 LLM 基于这些信息做出分析。

文件引用：@filename

使用 @ 符号可以引用项目中的文件，其内容会被自动包含到提示词中：

---
description: Review component performance
---

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

这种语法与 TUI 中 @ 模糊搜索文件的功能一致，非常适合对特定文件进行深入分析。

配置选项详解

除了 template 之外，自定义命令还提供了多个可选的配置选项，让你精细控制命令的行为。

template

必需的选项，定义发送给 LLM 的提示词内容。

{
  "command": {
    "test": {
      "template": "Run tests and report failures."
    }
  }
}

description

为命令添加描述信息，当你在 TUI 中输入 / 后，这些描述会显示在下拉列表中，方便查找。

{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}

agent

指定执行该命令的 Agent 类型。可以指定为 build、plan 或自定义 Agent。如果指定的是 subagent，命令默认会以子 Agent 的方式执行。

{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}

model

覆盖当前使用的模型，为该命令指定特定的 LLM。比如，分析型任务可以用更强的模型，简单任务用轻量模型。

{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

subtask

设置为 true 时，强制命令以子 Agent（subtask）方式执行。这可以避免命令的上下文污染主对话上下文，适合那些不需要与主对话共享上下文的独立任务。

{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}

内置命令

OpenCode 自带了一些内置命令，了解它们可以避免与自定义命令冲突：

| 命令 | 功能 |
|------|------|
| /init | 初始化项目，创建 AGENTS.md |
| /undo | 撤销上一次变更 |
| /redo | 重做已撤销的变更 |
| /share | 生成当前对话的分享链接 |
| /help | 查看帮助信息 |

需要注意的是，自定义命令的优先级高于内置命令。如果你定义了同名的自定义命令，会覆盖内置命令。

实战案例

下面通过几个实际场景来展示自定义命令的具体用法。

案例 1：规范化的 Git 提交

每次提交代码时，写一个有意义的 commit message 是有挑战的。创建一个命令来自动生成：

---
description: Generate commit message based on changes
---

Analyze the following git diff and suggest a concise, informative commit message:
!`git diff --cached`

The message should follow conventional commits format.

然后在暂存文件后运行：

/commit-message

案例 2：项目架构文档生成

当新成员加入项目时，快速生成架构概览：

---
description: Generate project architecture overview
---

Analyze the project structure at @. and create a comprehensive architecture overview.
Include:
1. Directory structure and purpose of each directory
2. Key dependencies and their roles
3. Data flow between components
4. Entry points and configuration files

Project structure:
!`tree -L 3 -I node_modules`

案例 3：多层次的代码审查

为不同类型的审查创建专用命令：

---
description: Security-focused code review
---

Perform a security-focused review of @$1.
Look for: SQL injection, XSS, CSRF, insecure authentication,
sensitive data exposure, and improper access control.

---
description: Performance review of recent changes
---

Review performance implications of the recent changes:
!`git diff HEAD~3`

Focus on: N+1 queries, memory leaks, unnecessary re-renders,
large bundle sizes, and blocking operations.

案例 4：环境诊断

当你遇到环境问题时，快速收集诊断信息：

---
description: Collect environment diagnostics
---

Analyze the following environment information and identify potential issues:

Node version: !`node --version`
npm version: !`npm --version`
OS Info: !`uname -a`
Memory: !`free -h`
Disk: !`df -h .`
Running processes: !`ps aux | grep -E "node|npm" | head -20`

最佳实践

1. 按项目组织命令

将项目专用的命令放在 .opencode/commands/ 中，全局通用的命令（如代码审查）放在 ~/.config/opencode/commands/ 中。这样既保持了项目的自包含性，又复用了跨项目的通用命令。

2. 使用有意义的命名

命令名应该直观反映其功能。/test、/review-security、/create-component 比 /t1、/r2 更容易记忆和查找。

3. 合理使用 subtask

对于独立的、无需共享上下文的命令，如环境诊断、覆盖率分析，设置 subtask: true 可以避免主对话上下文被大量无关内容污染。

4. 组合 Shell 命令

利用 ` !command ` 语法组合多个 Shell 命令，可以在一条命令中收集丰富的上下文信息。配合管道和重定向，几乎可以实现任意复杂的上下文预处理。

5. 版本控制

将 .opencode/commands/ 目录纳入 Git 版本控制，团队之间共享高效的工作流。结合团队约定的 AGENTS.md，可以让所有成员使用统一的自定义命令集。

总结

OpenCode 的自定义命令功能将常用的提示词封装为快捷指令，大幅减少了重复性的提示词输入工作。从简单的字符串替换到复杂的 Shell 输出注入，从参数传递到文件引用，从 agent 指定到模型覆盖，这套机制足够灵活，可以覆盖几乎所有日常开发场景。

通过合理设计和组织自定义命令，你可以将 OpenCode 从一个通用的 AI 编程助手，打造成一个完全适配你个人或团队工作流的专属开发工具。花点时间搭建一套自己的命令库，每次输入 / 时，你都会感受到效率的提升。