OpenCode 自定义命令 (Commands) 完全指南

Commands 是 OpenCode 中的快捷指令系统，通过 /command 格式触发预定义的操作流程。无论是初始化项目、运行测试、还是触发一套完整的部署流程，你都可以将其封装为一个命令，然后在对话中一键执行。本文覆盖内置命令、自定义命令的编写与高级用法。

内置命令

OpenCode 预置了以下内置命令，直接输入即可使用：

| 命令 | 功能 | 说明 |
|------|------|------|
| /help | 显示帮助信息 | 列出所有可用命令 |
| /clear | 清空对话 | 保留上下文，但清除屏幕显示 |
| /init | 初始化项目 | 为项目创建 .opencode 目录和配置文件 |
| /model | 切换模型 | /model deepseek 切换到指定模型 |
| /agent | 切换 Agent | /agent plan 切换到 Plan 模式 |
| /mode | 切换模式 | /mode plan 或 /mode build |
| /compact | 压缩上下文 | 总结历史对话释放 Token |
| /cost | 查看费用 | 显示当前会话的 Token 消耗 |
| /context | 查看上下文 | 显示当前上下文中的文件和内容 |
| /status | 查看状态 | 显示模型、Agent 等当前状态 |
| /exit | 退出 | 退出 OpenCode |
| /add-dir | 添加目录 | 将目录加入工作区 |
| /diff | 查看差异 | 显示当前未提交的代码变更 |
| /doctor | 诊断 | 检查配置和环境的健康状态 |
| /memory | 记忆管理 | 查看和管理持久化记忆 |
| /vim | Vim 模式 | 切换终端操作的 Vim 模式 |

命令系统层级

与配置文件类似，Custom Commands 也有多个层级：

优先级高 → 低：

1. 项目级命令：<project>/.opencode/commands/
2. 用户级命令：~/.config/opencode/commands/
3. 内置命令：OpenCode 预置命令

项目级命令会覆盖同名的用户级命令，内置命令优先级最低（可以被自定义命令覆盖）。

编写自定义命令

目录结构

.opencode/commands/
├── test.md        → 触发 /test
├── deploy.md      → 触发 /deploy
├── lint.md        → 触发 /lint
└── review.md      → 触发 /review

命令文件名决定了触发指令，test.md 对应 /test。

基础命令示例

<!-- .opencode/commands/test.md -->
请运行以下项目测试：

npm run test

如果测试失败，请分析失败原因并尝试修复。

使用方式：

/test

带参数的命令

使用 $ARGUMENTS 或 $1、$2 等获取参数：

<!-- .opencode/commands/explain.md -->
请详细解释以下代码的功能和逻辑：

$ARGUMENTS

包括：
1. 代码的整体作用
2. 每一部分的功能说明
3. 潜在的优化点

使用方式：

/explain src/services/auth.ts 中的 login 函数

命令中的上下文引用

命令可以引用文件、目录、Git 状态等上下文：

<!-- .opencode/commands/review-pr.md -->
请审查当前分支相对于 main 的所有变更：

1. 先运行 `git diff main...HEAD --stat` 查看变更文件列表
2. 逐一审查变更内容
3. 指出潜在问题（按严重程度排列）
4. 给出改进建议

使用 $ARGUMENTS 处理参数

<!-- .opencode/commands/commit.md -->
请为当前的代码变更创建提交：

1. 首先查看 `git diff --staged` 暂存区内容
2. 如果没有暂存的文件，运行 `git diff` 查看所有变更
3. 根据变更内容生成符合 Conventional Commits 规范的提交信息
4. 格式：`type(scope): description`
5. 如果有额外说明：$ARGUMENTS
6. 如果用户提供了提交信息，优先使用用户的：$ARGUMENTS

使用方式：

/commit
/commit feat: 添加用户登录功能

命令分类与实战

开发流程命令

<!-- .opencode/commands/feature.md -->
我需要实现一个新功能：$ARGUMENTS

请按以下流程执行：
1. 使用 Plan Agent 分析需求和现有代码
2. 制定实现方案
3. 切换到 Build Agent 编写代码
4. 编写测试用例
5. 运行测试验证
6. 进行 Code Review 自查

每一步完成后向我确认再继续。

调试命令

<!-- .opencode/commands/debug.md -->
我遇到了一个 Bug：$ARGUMENTS

请按以下流程排查：
1. 分析错误日志和堆栈信息
2. 定位问题代码文件
3. 检查相关的数据流和状态变化
4. 提出至少 2 种修复方案
5. 推荐最优方案并实施

在修改代码之前，先向我展示你的分析结果。

代码质量命令

<!-- .opencode/commands/lint-fix.md -->
请检查项目的代码质量：

1. 运行 ESLint：`npx eslint src/ --ext .ts,.tsx`
2. 运行 TypeScript 类型检查：`npx tsc --noEmit`
3. 运行 Prettier 检查：`npx prettier --check src/`
4. 针对每个问题逐一修复
5. 再次运行检查确认全部通过

部署命令

<!-- .opencode/commands/deploy.md -->
执行部署流程：

1. 确认当前在正确的分支上
2. 运行完整测试套件
3. 构建生产版本：`npm run build`
4. 检查构建产物是否正确
5. 如果有数据库迁移，确认迁移脚本
6. 生成部署说明文档

如果任何步骤失败，立即停止并报告问题。

文档生成命令

<!-- .opencode/commands/docs.md -->
为项目生成/更新 API 文档：

1. 扫描 src/ 目录下的所有 API 路由定义
2. 提取每个接口的：
   - HTTP 方法和路径
   - 请求参数（类型、必需性、默认值）
   - 响应结构
   - 认证要求
3. 生成 Markdown 格式的 API 文档
4. 保存到 docs/api.md

如果有 $ARGUMENTS 参数，只处理指定的路由文件。

高级命令技巧

条件执行

<!-- .opencode/commands/smart-test.md -->
智能运行测试：

1. 先用 `git diff --name-only main...HEAD` 查看变更文件
2. 识别变更影响的模块
3. 只运行与变更相关的测试：
   - 如果只有前端变更，运行 `npm run test:frontend`
   - 如果只有后端变更，运行 `npm run test:backend`
   - 如果都有变更，运行全量测试
4. 输出测试结果摘要

链式命令

命令可以依次触发多个操作：

<!-- .opencode/commands/pr.md -->
创建 Pull Request 的完整流程：

1. **代码检查**：运行 lint 和 typecheck
2. **测试**：运行全部测试
3. **提交**：生成符合规范的 commit message 并提交
4. **推送**：推送到远程仓库
5. **创建 PR**：在 GitHub 上创建 Pull Request
   - 标题自动生成
   - 描述包含变更摘要和测试结果

如果用户提供了 PR 描述，使用用户的：$ARGUMENTS

交互式命令

<!-- .opencode/commands/scaffold.md -->
创建一个新的项目模块：$ARGUMENTS

请先问我以下信息：
1. 模块名称是什么？
2. 需要哪些 CRUD 操作？
3. 是否需要数据库迁移？
4. 是否需要前端页面？

收集完整信息后再开始生成代码，每一项生成后向我确认。

命令管理

查看所有命令

/help

这会列出所有可用的内置命令和自定义命令。

禁用内置命令

在 opencode.json 中：

{
  "commands": {
    "disabled": ["/vim", "/memory"]
  }
}

命令别名

在命令文件中可以通过不同的文件名创建别名：

.opencode/commands/
├── t.md      → /t（/test 的快捷方式）
├── d.md      → /d（/deploy 的快捷方式）
└── test.md   → /test（完整命令名）

跨项目复用命令

将常用命令放在全局目录，所有项目都可以使用：

~/.config/opencode/commands/
├── pr.md        # 总是可用的 PR 创建命令
├── git-log.md   # Git 日志分析命令
└── todo.md      # 任务管理命令

实战：高效命令集

以下是一套推荐的自定义命令集，大幅提升日常开发效率：

<!-- .opencode/commands/fix.md -->
修复 lint 和类型错误：

1. 运行 `npx eslint src/ --ext .ts,.tsx --format json` 获取所有问题
2. 运行 `npx tsc --noEmit` 获取所有类型错误
3. 按文件分组，逐个文件修复全部问题
4. 再次验证

<!-- .opencode/commands/refactor.md -->
重构指定的代码：$ARGUMENTS

要求：
- 保持外部 API 不变
- 不引入 breaking change
- 保持现有测试通过
- 如需要添加新测试请告知

<!-- .opencode/commands/new.md -->
根据以下描述创建新文件：$ARGUMENTS

遵循项目的命名规范和目录结构。
创建后运行 lint 确保代码风格一致。

小结

Commands 系统是 OpenCode 中将重复性工作流程化的利器。通过自定义命令，你可以将团队的标准化操作（测试、构建、部署、审查）封装为一键指令，让 AI 编程助手真正融入你的工作流，成为自动化开发的中枢。

下一篇我们将深入 OpenCode 的 CLI 命令行与自动化，学习如何在非交互模式下使用 OpenCode 以及集成 CI/CD 流水线。