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

一、引言

OpenCode 是一个开源的 AI 编程助手，提供了强大的自定义命令（Custom Commands）功能。这个系统允许用户创建可重复使用的斜杠命令（Slash Commands），类似于 "oh-my-zsh" 的插件系统，因此也被用户戏称为 "oh my opencode"。本报告将深入分析 OpenCode 自定义命令系统的架构、配置机制、执行原理以及最佳实践。

二、系统架构

2.1 整体架构概览

OpenCode 的自定义命令系统采用文件系统驱动的架构，主要包含以下组件：

命令存储层：支持两种存储方式
- Markdown 文件：.opencode/commands/ 或 ~/.config/opencode/commands/
- JSON 配置：通过 opencode.jsonc 或 opencode.json 配置文件
命令发现层：自动扫描指定目录和配置文件
- 项目级命令：.opencode/commands/ 目录
- 全局命令：~/.config/opencode/commands/ 目录
- 配置文件命令：JSON 配置中的 command 对象
命令解析层：
- YAML 前置元数据（Frontmatter）解析
- 模板变量替换
- 参数处理
命令执行层：
- 与 TUI（终端用户界面）集成
- 与 CLI 命令行接口集成
- Agent 和 Model 选择机制

2.2 命令发现机制

OpenCode 按照以下优先级发现和加载自定义命令：

项目级命令优先：.opencode/commands/ 目录中的命令
全局命令补充：~/.config/opencode/commands/ 目录中的命令
配置文件命令：JSON 配置文件中定义的命令

如果存在同名命令，项目级命令会覆盖全局命令。这种设计允许团队共享全局命令，同时每个项目可以有特定的自定义命令。

2.3 命令加载流程

用户启动 OpenCode
    ↓
扫描配置目录（~/.config/opencode/）
    ↓
扫描项目目录（.opencode/）
    ↓
读取 JSON 配置文件（如果存在）
    ↓
合并所有发现的命令
    ↓
在 TUI 中注册命令
    ↓
用户输入 / 触发命令补全

三、配置方法详解

3.1 Markdown 文件配置方法

这是最常用和推荐的配置方式，使用 YAML 前置元数据来定义命令属性。

3.1.1 文件结构

markdown

---
description: 命令描述
agent: build 或 plan
model: provider/model-name
---

命令模板内容

3.1.2 Frontmatter 属性详解

必填属性：

description：命令的简短描述，显示在 TUI 的命令补全列表中

可选属性：

agent：指定使用的 Agent 类型
- build：默认 Agent，具有完整的开发权限
- plan：只读 Agent，用于分析和探索
model：指定使用的模型
- 格式：provider/model-name
- 示例：anthropic/claude-3-5-sonnet-20241022

3.1.3 命令模板

Frontmatter 之后的所有内容都作为命令模板，当命令被触发时，这些内容会被发送给 LLM。

示例：测试命令

markdown

---
description: 运行测试套件
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

运行完整的测试套件并生成覆盖率报告。

请关注失败的测试并建议修复方案。

使用方式： 在 TUI 中输入 /test

3.2 JSON 配置方法

JSON 配置方法适用于需要集中管理多个命令的场景。

3.2.1 配置文件位置

opencode.jsonc（支持注释）
opencode.json（标准 JSON）
位置：项目根目录或 ~/.config/opencode/

3.2.2 配置结构

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "命令名称": {
      "template": "命令模板内容",
      "description": "命令描述",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

3.2.3 完整示例

jsonc

{
  "$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"
    },
    "review": {
      "template": "Review the current changes for security issues, performance problems, and code quality concerns.",
      "description": "Review code for issues",
      "agent": "plan"
    }
  }
}

3.3 两种配置方法的对比

特性	Markdown 文件	JSON 配置
易用性	高（所见即所得）	中（需要 JSON 语法）
可读性	高（格式清晰）	中（JSON 格式限制）
多行文本	自然支持	需要使用 `\n`
注释支持	支持（Markdown 注释）	仅 JSONC 支持
团队协作	好（文件独立）	一般（集中配置）
版本控制	好（每个命令独立）	一般（整体文件）

推荐： 对于大多数场景，推荐使用 Markdown 文件方法，因为它更直观且易于维护。

四、命令执行机制

4.1 命令触发流程

用户输入触发
- 用户在 TUI 中输入 / 键
- OpenCode 显示命令补全列表
- 用户选择或输入命令名称
命令解析
- OpenCode 读取对应的命令文件或配置
- 解析 YAML Frontmatter（如果是 Markdown 文件）
- 提取命令模板
上下文注入
- 当前会话上下文自动注入
- 选中的文件或代码块可以引用
- 使用 @ 符号引用项目文件
模板处理
- 变量替换（如果支持）
- 占位符展开
- 参数注入
发送给 LLM
- 根据 agent 属性选择对应的 Agent
- 根据 model 属性选择对应的模型
- 将处理后的模板发送给 LLM
响应处理
- LLM 返回响应
- OpenCode 根据响应执行操作
- 显示结果给用户

4.2 Agent 选择机制

OpenCode 提供了两个内置 Agent：

build Agent

默认 Agent
具有完整的文件编辑权限
可以执行 bash 命令
适合实际的开发工作

plan Agent

只读 Agent
默认拒绝文件编辑
执行 bash 命令前请求许可
适合代码探索和规划

通过在命令中指定 agent 属性，可以控制命令的行为模式。

4.3 模型选择机制

命令可以指定特定的模型：

model: provider/model-name

支持的提供商包括：

Anthropic（Claude 系列）
OpenAI（GPT 系列）
Google（Gemini 系列）
OpenCode Zen（优化过的模型）
其他通过 Models.dev 提供的 75+ LLM 提供商

4.4 文件引用机制

在命令模板中，可以使用 @ 符号引用项目文件：

Review the authentication logic in @packages/functions/src/api/index.ts

OpenCode 会自动：

搜索匹配的文件
读取文件内容
将内容注入到发送给 LLM 的提示中

4.5 参数处理机制

虽然 OpenCode 的自定义命令系统不直接支持复杂的参数传递，但可以通过以下方式实现：

方法 1：使用占位符

markdown

---
description: 分析指定文件
---

请分析 @${file} 的代码质量和潜在问题。

用户需要在命令后手动替换占位符。

方法 2：结合文件选择

markdown

---
description: 审查选中的代码
---

请审查当前选中的代码，检查：
1. 安全问题
2. 性能问题
3. 代码质量

提供详细的改进建议。

用户先选中代码或文件，然后执行命令。

方法 3：交互式命令

markdown

---
description: 交互式代码重构
---

请帮我重构代码。

首先，询问我：
1. 要重构的文件或功能
2. 重构的目标
3. 任何特定的约束或偏好

然后根据我的回答进行重构。

让 LLM 通过对话收集信息。

五、最佳实践

5.1 命令设计原则

5.1.1 单一职责

每个命令应该只做一件事，避免过于复杂。

好的例子：

markdown

---
description: 运行测试并显示失败用例
---

运行完整的测试套件，并重点显示失败的测试用例。

不好的例子：

markdown

---
description: 运行测试、构建部署、发送通知
---

运行测试，如果通过则构建应用，部署到生产环境，并发送邮件通知。

5.1.2 明确的描述

描述应该简洁明了，让用户快速理解命令的作用。

markdown

---
description: 运行测试并显示失败用例
---

比

markdown

---
description: 测试
---

更好。

5.1.3 提供上下文

在命令模板中提供足够的上下文和指导。

markdown

---
description: 代码审查最佳实践
---

请审查代码变更，重点关注：

1. **安全性**
   - SQL 注入风险
   - XSS 漏洞
   - 认证和授权问题

2. **性能**
   - 查询优化
   - 缓存策略
   - 资源使用

3. **代码质量**
   - 可读性
   - 可维护性
   - 遵循项目规范

对于每个问题，提供：
- 问题描述
- 严重程度
- 具体改进建议

5.2 常见用例命令示例

5.2.1 代码审查命令

markdown

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

请对代码变更进行全面的审查，包括：

## 安全性
- 输入验证
- 输出编码
- 认证和授权
- 敏感数据处理

## 性能
- 算法复杂度
- 数据库查询效率
- 缓存使用
- 资源释放

## 可维护性
- 代码组织
- 命名规范
- 注释和文档
- 错误处理

请提供详细的发现和改进建议。

5.2.2 文档生成命令

markdown

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

请为当前选中的代码或文件生成完整的 API 文档，包括：

1. **函数/方法签名**
2. **参数说明**
   - 类型
   - 是否必填
   - 默认值
3. **返回值说明**
4. **使用示例**
5. **注意事项**
6. **相关文档链接**

使用 Markdown 格式输出。

5.2.3 重构建议命令

markdown

---
description: 提供重构建议
agent: plan
---

分析当前代码并提供重构建议：

**分析维度：**
- 代码重复
- 复杂度
- 可读性
- 可测试性
- 设计模式应用

**输出格式：**
1. 当前问题描述
2. 重构建议
3. 预期收益
4. 风险评估
5. 实施步骤

请不要直接修改代码，只提供分析和建议。

5.2.4 测试生成命令

markdown

---
description: 生成单元测试
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

为当前选中的代码生成完整的单元测试套件。

**要求：**
1. 使用项目现有的测试框架
2. 包含正常场景测试
3. 包含边界条件测试
4. 包含异常情况测试
5. 每个测试都有清晰的描述
6. 使用有意义的测试数据

**测试覆盖：**
- 所有公共方法
- 关键的私有方法
- 边界情况
- 错误处理路径

5.2.5 调试辅助命令

markdown

---
description: 调试辅助
agent: build
---

帮助调试以下问题：

1. 分析提供的错误信息
2. 识别可能的根本原因
3. 建议调试步骤
4. 提供验证假设的方法
5. 推荐调试工具和技术

请提供系统化的调试方法，而不是直接给出解决方案。

5.3 命令组织策略

5.3.1 按功能分类

.opencode/commands/
├── testing/
│   ├── test.md
│   ├── test-coverage.md
│   └── test-watch.md
├── review/
│   ├── security-review.md
│   ├── performance-review.md
│   └── code-review.md
├── docs/
│   ├── generate-api-docs.md
│   └── update-readme.md
└── refactor/
    ├── suggest-refactor.md
    └── apply-refactor.md

5.3.2 按团队角色分类

.opencode/commands/
├── frontend/
│   ├── component-review.md
│   └── style-check.md
├── backend/
│   ├── api-review.md
│   └── database-review.md
└── devops/
    ├── ci-pipeline.md
    └── deployment.md

5.3.3 命令命名约定

使用清晰、描述性的命令名称：

使用动词开头：test、review、generate、refactor
使用连字符分隔：code-review、test-coverage
避免缩写：generate-docs 而不是 gen-docs
保持简短：security-review 而不是 security-code-review-and-analysis

5.4 高级技巧

5.4.1 链式命令

创建可以相互配合的命令：

markdown

---
description: 步骤 1：分析性能瓶颈
agent: plan
---

分析代码的性能瓶颈。重点关注：
- 慢查询
- 内存泄漏
- 低效算法

输出分析报告，但不进行任何修改。

markdown

---
description: 步骤 2：应用性能优化
agent: build
---

基于之前的性能分析，应用代码优化：
- 优化慢查询
- 修复内存泄漏
- 改进算法效率

确保每个更改都有注释说明原因。

5.4.2 条件性命令

创建根据上下文提供不同建议的命令：

markdown

---
description: 上下文感知的代码建议
---

分析当前代码并提供建议。

如果代码是前端代码：
- 专注于 UI/UX 问题
- 检查性能优化（虚拟化、懒加载）
- 验证可访问性

如果代码是后端代码：
- 专注于 API 设计
- 检查数据库查询优化
- 验证安全措施

如果代码是测试代码：
- 检查测试覆盖率
- 验证测试质量
- 建议改进测试策略

5.4.3 模板化命令

创建可重用的命令模板：

markdown

---
description: 自定义审查模板
agent: plan
---

请从以下维度审查代码：

${REVIEW_DIMENSIONS}

对于每个发现，提供：
- 严重程度（高/中/低）
- 问题描述
- 具体位置
- 改进建议

使用时，用户可以修改 ${REVIEW_DIMENSIONS} 变量。

5.5 错误处理和调试

5.5.1 常见问题

问题 1：命令不显示在补全列表中

可能原因：

文件路径错误
YAML 格式错误
描述属性缺失

解决方法：

验证文件在正确的目录中
检查 YAML 语法
确保有 description 属性

问题 2：命令执行后没有响应

可能原因：

模板内容为空
Agent 配置错误
模型不可用

解决方法：

检查模板内容
验证 Agent 和 Model 配置
检查 API 密钥和网络连接

问题 3：命令输出不符合预期

可能原因：

模板不够清晰
缺少上下文
模型理解偏差

解决方法：

改进模板描述
提供更多上下文
调整模型选择

5.5.2 调试技巧

技巧 1：使用 plan Agent 调试

在开发命令时，先使用 agent: plan 来观察 AI 的理解：

markdown

---
description: 调试：测试命令
agent: plan
---

这是我想要你做的事情：

[具体任务描述]

请告诉我你理解了什么，以及你会如何执行。

技巧 2：逐步增加复杂度

从简单的命令开始，逐步增加功能：

第一版：基本功能
第二版：添加错误处理
第三版：优化输出格式
第四版：添加高级特性

技巧 3：记录和迭代

为每个命令创建变更日志：

markdown

---
description: 代码审查命令
---

## 版本历史
- v1.0 (2026-01-19): 初始版本
- v1.1 (2026-01-20): 添加性能检查
- v1.2 (2026-01-21): 改进输出格式

## 审查内容

[命令内容...]

六、与类似系统的比较

6.1 vs Claude Code Slash Commands

相似之处：

都使用 Markdown 文件定义命令
都支持 YAML Frontmatter
都提供类似的功能集

OpenCode 的优势：

完全开源
提供商无关（支持多种 LLM）
内置 LSP 支持
更注重终端用户体验

6.2 vs oh-my-zsh 插件系统

相似之处：

都是文件系统驱动的插件系统
都支持全局和项目级配置
都有强大的社区支持

不同之处：

OpenCode 使用 Markdown 和 JSON，而 oh-my-zsh 使用 Shell 脚本
OpenCode 命令是 AI 驱动的，而 oh-my-zsh 是脚本驱动的
OpenCode 更适合智能辅助，而 oh-my-zsh 更适合自动化

七、总结

OpenCode 的自定义命令系统是一个强大而灵活的功能，它允许用户：

标准化工作流程：通过创建可重复使用的命令模板
提高效率：避免重复输入相同的提示
团队协作：共享最佳实践和规范
灵活定制：根据项目需求定制命令
持续改进：迭代和优化命令以获得更好的结果

通过理解其架构、配置方法、执行机制和最佳实践，开发者可以充分利用这个系统，显著提高开发效率和代码质量。

核心要点总结

架构：文件系统驱动，支持 Markdown 和 JSON 配置
发现：自动扫描项目级和全局配置目录
配置：推荐使用 Markdown 文件方法，支持 YAML Frontmatter
执行：与 TUI 集成，支持 Agent 和 Model 选择
最佳实践：单一职责、明确描述、提供上下文、组织良好
高级技巧：链式命令、条件命令、模板化命令
调试：使用 plan Agent、逐步迭代、记录变更

OpenCode 的自定义命令系统是一个值得深入学习和应用的强大工具，它将 AI 辅助编程推向了一个新的高度。

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

一、引言 ​

二、系统架构 ​

2.1 整体架构概览 ​

2.2 命令发现机制 ​

2.3 命令加载流程 ​

三、配置方法详解 ​

3.1 Markdown 文件配置方法 ​

3.1.1 文件结构 ​

3.1.2 Frontmatter 属性详解 ​

3.1.3 命令模板 ​

3.2 JSON 配置方法 ​

3.2.1 配置文件位置 ​

3.2.2 配置结构 ​

3.2.3 完整示例 ​

3.3 两种配置方法的对比 ​

四、命令执行机制 ​

4.1 命令触发流程 ​

4.2 Agent 选择机制 ​

4.3 模型选择机制 ​

4.4 文件引用机制 ​

4.5 参数处理机制 ​

五、最佳实践 ​

5.1 命令设计原则 ​

5.1.1 单一职责 ​

5.1.2 明确的描述 ​

5.1.3 提供上下文 ​

5.2 常见用例命令示例 ​

5.2.1 代码审查命令 ​

5.2.2 文档生成命令 ​

5.2.3 重构建议命令 ​

5.2.4 测试生成命令 ​

5.2.5 调试辅助命令 ​

5.3 命令组织策略 ​

5.3.1 按功能分类 ​

5.3.2 按团队角色分类 ​

5.3.3 命令命名约定 ​

5.4 高级技巧 ​

5.4.1 链式命令 ​

5.4.2 条件性命令 ​

5.4.3 模板化命令 ​

5.5 错误处理和调试 ​

5.5.1 常见问题 ​

5.5.2 调试技巧 ​

六、与类似系统的比较 ​

6.1 vs Claude Code Slash Commands ​

6.2 vs oh-my-zsh 插件系统 ​

七、总结 ​

核心要点总结 ​

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

一、引言

二、系统架构

2.1 整体架构概览

2.2 命令发现机制

2.3 命令加载流程

三、配置方法详解

3.1 Markdown 文件配置方法

3.1.1 文件结构

3.1.2 Frontmatter 属性详解

3.1.3 命令模板

3.2 JSON 配置方法

3.2.1 配置文件位置

3.2.2 配置结构

3.2.3 完整示例

3.3 两种配置方法的对比

四、命令执行机制

4.1 命令触发流程

4.2 Agent 选择机制

4.3 模型选择机制

4.4 文件引用机制

4.5 参数处理机制

五、最佳实践

5.1 命令设计原则

5.1.1 单一职责

5.1.2 明确的描述

5.1.3 提供上下文

5.2 常见用例命令示例

5.2.1 代码审查命令

5.2.2 文档生成命令

5.2.3 重构建议命令

5.2.4 测试生成命令

5.2.5 调试辅助命令

5.3 命令组织策略

5.3.1 按功能分类

5.3.2 按团队角色分类

5.3.3 命令命名约定

5.4 高级技巧

5.4.1 链式命令

5.4.2 条件性命令

5.4.3 模板化命令

5.5 错误处理和调试

5.5.1 常见问题

5.5.2 调试技巧

六、与类似系统的比较

6.1 vs Claude Code Slash Commands

6.2 vs oh-my-zsh 插件系统

七、总结

核心要点总结