Vibe Research

Appearance

OpenCode 自定义命令系统深度研究 ​

执行摘要 ​

本研究对 OpenCode 的自定义命令(Custom Commands)系统进行了深度技术分析。OpenCode 提供了强大的斜杠命令(Slash Commands)功能,允许用户创建可重复使用的命令,类似于"oh-my-zsh"的插件系统。该系统采用文件系统驱动的架构,支持 Markdown 文件和 JSON 配置两种方式定义命令,提供了项目级和全局级的命令管理机制,并支持 YAML 前置元数据、模板变量替换、参数处理等高级功能。

核心发现 ​

  1. 架构设计:文件系统驱动,支持 Markdown 和 JSON 两种配置方式,采用分层命令发现机制
  2. 命令优先级:项目级命令 > 全局命令 > 配置文件命令,支持命令覆盖
  3. 高级特性:支持 YAML Frontmatter 元数据、模板变量替换、参数传递、Agent/Model 选择
  4. 集成方式:与 TUI 和 CLI 深度集成,支持自动补全和命令发现

技术价值 ​

实用性评估:生产可用(Production Ready)

  • ✅ 完整的命令定义和发现机制
  • ✅ 支持项目级和全局级命令管理
  • ✅ 丰富的元数据和模板功能
  • ✅ 与 OpenCode 生态深度集成
  • ⚠️ 需要理解 YAML Frontmatter 语法
  • ⚠️ 模板变量功能需要文档参考

文档导航 ​

核心内容 ​

1. 系统架构 ​

命令存储层 ​

支持两种存储方式:

  1. Markdown 文件

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

  2. JSON 配置

    • opencode.jsonc 或 opencode.json
    • 通过 command 对象定义

命令发现机制 ​

命令发现优先级:

  1. 项目级命令:.opencode/commands/ (最高优先级)
  2. 全局命令:~/.config/opencode/commands/
  3. 配置文件命令:JSON 配置中的 command 对象

同名命令时,项目级命令覆盖全局命令。

命令执行流程 ​

用户输入 /command
    ↓
命令发现与解析
    ↓
YAML Frontmatter 解析
    ↓
模板变量替换
    ↓
参数处理
    ↓
Agent/Model 选择
    ↓
命令执行

2. 命令定义方式 ​

Markdown 文件方式 ​

markdown
---
name: review-pr
description: Review a pull request
args:
  - name: pr_number
    type: number
    required: true
agent: code-reviewer
---

Please review pull request #{{pr_number}}. Focus on:
1. Code quality and best practices
2. Security concerns
3. Performance implications

JSON 配置方式 ​

json
{
  "command": {
    "review-pr": {
      "description": "Review a pull request",
      "args": ["pr_number"],
      "prompt": "Please review pull request #{{pr_number}}"
    }
  }
}

3. 高级特性 ​

YAML Frontmatter 元数据 ​

支持的元数据字段:

  • name:命令名称(必需)
  • description:命令描述
  • args:参数定义
  • agent:指定使用的 Agent
  • model:指定使用的模型
  • temperature:模型温度参数
  • maxTokens:最大 Token 数

模板变量系统 ​

支持的变量类型:

  • 参数变量:{{arg_name}}
  • 环境变量:{{env.VAR_NAME}}
  • 系统变量:{{date}}, {{time}}, {{user}}
  • 条件变量:{{#if condition}}...{{/if}}

参数定义 ​

yaml
args:
  - name: file_path
    type: string
    required: true
    description: Path to the file
  - name: format
    type: string
    required: false
    default: json
    enum: [json, yaml, xml]

4. 使用示例 ​

代码审查命令 ​

创建 .opencode/commands/review.md:

markdown
---
name: review
description: Perform code review on changed files
agent: code-reviewer
---

Please review the following changes:

1. Check for code quality issues
2. Identify potential bugs
3. Suggest improvements
4. Verify test coverage

使用:

bash
opencode /review

生成文档命令 ​

创建 .opencode/commands/docs.md:

markdown
---
name: docs
description: Generate documentation for a file
args:
  - name: file
    type: string
    required: true
---

Generate comprehensive documentation for {{file}}:

1. Module overview
2. Function descriptions
3. Usage examples
4. API reference

使用:

bash
opencode /docs src/utils.ts

重构命令 ​

创建 .opencode/commands/refactor.md:

markdown
---
name: refactor
description: Refactor code with specific pattern
args:
  - name: pattern
    type: string
    required: true
  - name: target
    type: string
    required: true
agent: refactoring-specialist
model: claude-opus-4
---

Refactor {{target}} to follow {{pattern}} pattern:

1. Identify current implementation
2. Plan refactoring steps
3. Apply changes incrementally
4. Ensure tests pass

使用:

bash
opencode /refactor "repository pattern" src/services/user.ts

最佳实践 ​

1. 命令组织 ​

  • 项目特定命令放在 .opencode/commands/
  • 通用命令放在 ~/.config/opencode/commands/
  • 使用描述性命令名称
  • 添加详细的参数描述

2. 提示词编写 ​

  • 明确指定任务目标
  • 提供清晰的步骤指引
  • 包含必要的上下文信息
  • 使用结构化格式(列表、表格等)

3. 参数设计 ​

  • 必需参数优先
  • 提供合理的默认值
  • 使用枚举限制选项
  • 添加参数验证

4. Agent 选择 ​

  • 根据任务类型选择合适的 Agent
  • 代码审查使用 code-reviewer
  • 重构使用 refactoring-specialist
  • 通用任务使用默认 Agent

5. 模板变量 ​

  • 充分利用模板变量减少重复
  • 使用环境变量管理配置
  • 条件变量处理复杂逻辑
  • 保持模板简洁易读

适用场景 ​

适合使用自定义命令的场景 ​

  • 需要重复执行的任务(代码审查、重构、测试等)
  • 团队共享的工作流程
  • 项目特定的开发规范
  • 标准化的文档生成
  • 自动化的代码分析

不适合使用的场景 ​

  • 一次性的临时任务
  • 频繁变化的需求
  • 过于复杂的多步骤流程
  • 需要大量用户交互的任务

核心参考资料 ​

官方文档 ​

社区资源 ​

相关研究 ​

研究日期:2026-01-19
OpenCode 版本:v1.1.x
研究类型:技术系统研究
文档版本:1.0