6.3 自定义命令

OpenCode支持创建自定义斜杠命令，通过Markdown文件或JSON配置两种方式定义，让你可以快速执行常用的提示模板。

Markdown文件方式

Markdown方式是创建自定义命令最简单、最直观的方法。

文件位置

在以下位置创建.opencode/commands/目录：

• 项目级：.opencode/commands/（当前项目目录）
• 用户级：~/.config/opencode/commands/（全局可用）

基本格式

创建一个.md文件，文件名即为命令名：

# .opencode/commands/review.md

请审查以下代码，检查：

1. 代码质量和可读性
2. 潜在的bug和错误
3. 性能问题
4. 安全漏洞
5. 最佳实践遵循情况

$ARGUMENTS

使用：/review @src/main.ts

带Front Matter的格式

使用YAML front matter添加元数据：

# .opencode/commands/translate.md

---
description: 将代码注释翻译为中文
---

请将以下代码中的所有英文注释翻译为中文，保持代码不变：

$ARGUMENTS

复杂命令示例

# .opencode/commands/refactor.md

---
description: 重构代码以提高可维护性
---

请重构以下代码：

## 重构目标
- 提高代码可读性
- 减少重复代码
- 改善命名
- 优化结构

## 约束条件
- 保持公共API不变
- 不改变功能行为
- 添加必要的注释

$ARGUMENTS

JSON配置方式

JSON方式提供更多配置选项，适合需要复杂设置的命令。

在配置文件中定义

{
  "command": {
    "test": {
      "template": "为 $1 编写单元测试，使用 $2 测试框架",
      "description": "生成单元测试"
    },
    "doc": {
      "template": "为以下代码生成详细的文档注释：\n\n$ARGUMENTS",
      "description": "生成文档注释"
    }
  }
}

完整配置选项

{
  "command": {
    "analyze": {
      "template": "分析 $1 的代码复杂度和质量",
      "description": "代码分析",
      "hidden": false
    }
  }
}

模板变量

自定义命令支持多种模板变量：

变量	说明	示例
$ARGUMENTS	所有输入参数	/cmd hello world → hello world
$1	第一个参数	/cmd a b c → a
$2	第二个参数	/cmd a b c → b
$3 ... $9	第3-9个参数	同上
$FILE	当前文件路径	/path/to/current.ts
$SELECTION	当前选中的文本	IDE中选中的代码
$CLIPBOARD	剪贴板内容	复制的内容

变量使用示例

# 使用位置参数
# .opencode/commands/convert.md
将 $1 格式转换为 $2 格式：

$3

使用：/convert JSON YAML @config.json

# 使用多个变量
# .opencode/commands/compare.md
比较以下两个实现的优缺点：

## 实现A
$1

## 实现B
$2

请从性能、可读性、可维护性角度分析。

命令选项

description - 命令描述

在命令列表中显示的描述文本：

{
  "command": {
    "fix": {
      "template": "修复以下代码中的问题：\n$ARGUMENTS",
      "description": "修复代码问题"
    }
  }
}

hidden - 隐藏命令

命令不会在自动补全列表中显示，但仍可使用：

{
  "command": {
    "internal": {
      "template": "内部调试命令：$ARGUMENTS",
      "description": "内部使用",
      "hidden": true
    }
  }
}

实用示例

代码审查命令

# .opencode/commands/cr.md

---
description: 全面的代码审查
---

请对以下代码进行全面审查：

## 审查清单
- [ ] 代码逻辑正确性
- [ ] 错误处理完整性
- [ ] 边界条件处理
- [ ] 代码风格一致性
- [ ] 性能考量
- [ ] 安全性检查
- [ ] 测试覆盖建议

## 代码
$ARGUMENTS

请按照审查清单逐项给出评价和改进建议。

Git提交消息生成

# .opencode/commands/commit.md

---
description: 生成Git提交消息
---

基于以下代码变更，生成符合Conventional Commits规范的提交消息：

变更内容：
$ARGUMENTS

要求：
1. 使用正确的类型前缀（feat/fix/docs/style/refactor/test/chore）
2. 简洁描述变更内容
3. 必要时添加详细说明

API文档生成

# .opencode/commands/apidoc.md

---
description: 生成API文档
---

为以下API生成文档：

$ARGUMENTS

文档格式要求：
- 使用Markdown格式
- 包含端点描述
- 请求参数说明（包括类型、是否必需）
- 响应格式示例
- 错误码说明
- 使用示例

测试用例生成

{
  "command": {
    "test-unit": {
      "template": "为以下函数生成单元测试：\n\n$ARGUMENTS\n\n要求：\n- 使用 $1 测试框架\n- 覆盖正常情况和边界情况\n- 包含错误处理测试",
      "description": "生成单元测试"
    },
    "test-e2e": {
      "template": "为以下功能生成端到端测试：\n\n$ARGUMENTS\n\n要求：\n- 使用 Playwright/Cypress\n- 覆盖用户主要流程\n- 包含断言验证",
      "description": "生成E2E测试"
    }
  }
}

代码解释

# .opencode/commands/explain.md

---
description: 详细解释代码
---

请详细解释以下代码：

$ARGUMENTS

解释要求：
1. 整体功能概述
2. 逐行/逐块详细解释
3. 使用的设计模式或算法
4. 潜在的注意事项
5. 适合初学者理解的语言

性能优化建议

# .opencode/commands/perf.md

---
description: 性能优化建议
---

分析以下代码的性能，提供优化建议：

$ARGUMENTS

分析维度：
1. 时间复杂度
2. 空间复杂度
3. 内存使用
4. I/O操作
5. 并发处理

请提供具体的优化代码示例。

命令组织建议

查看已有命令

输入/后按Tab键可以查看所有可用命令，包括内置命令和自定义命令。

下一步

接下来学习MCP协议服务器，了解如何通过MCP扩展OpenCode的能力。