OpenCode AI 命令系统完全指南：从入门到自定义

引言

OpenCode AI 是一个开源的 AI 编程助手，支持在终端、桌面和 IDE 环境中使用。它提供了强大的命令系统，允许用户创建自定义命令来自动化重复性开发任务。本文将深入介绍 OpenCode AI 的命令系统，包括内置命令的使用方法以及如何创建完全自定义的命令。

内置命令详解

核心内置命令

OpenCode AI 提供了一套标准的内置命令，这些命令是日常开发工作的基础工具：

• /init：初始化项目环境，自动检测项目类型并配置相应的开发环境，创建或更新 AGENTS.md 项目规则文件
• /models：添加 AI 提供商，配置 API 密钥
• /connect：选择模型，Free标记的是免费模型，
• /session：压缩/总结当前会话内容（别名：/summarize，
• /compact：选择对话，历史对话，可以选择某个对话继续未完成的任务，
• /new：开始新会话
• /thinking：切换思考/推理块的显示
• /undo：撤销上一次操作，支持多级撤销，可以回退多个步骤
• /redo：重做被撤销的操作，与 undo 形成互补
• /share：生成分享链接，可以将当前会话分享给团队成员
• /help：显示帮助信息和命令列表，快速了解可用功能

自定义命令创建方法

方法一：Markdown 文件方式

这是最推荐的创建自定义命令的方式，因为它更易于管理和版本控制。

1. 命令文件存放位置

• 全局配置：~/.config/opencode/commands/
• 项目配置：.opencode/commands/

2. 创建示例命令

创建一个测试命令 ~/.config/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.

命令文件名（不含扩展名）将成为命令名称。上例中，文件名为 test.md，对应的命令就是 /test。

3. 命令文件结构说明

每个命令文件由两部分组成：

• YAML 前置元数据：定义命令的属性
• 模板内容：定义命令执行时的具体行为

方法二：JSON 配置文件方式

对于喜欢集中管理的用户，也可以在 opencode.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"
    }
  }
}

命令配置选项详解

Template（模板）【必需】

模板是命令的核心，定义了当命令执行时发送给 AI 模型的提示词。这是唯一必需的选项。

"template": "Run the full test suite with coverage report and show any failures."

Description（描述）【可选】

描述信息会在 TUI 中显示，帮助用户理解命令的用途。

"description": "Run tests with coverage"

Agent（代理）【可选】

指定执行命令的代理类型，不同的代理有不同的专长领域。

"agent": "build"

常见代理类型包括：

• build：构建和测试相关任务
• plan：规划和分析任务
• debug：调试和问题诊断

Subtask（子任务）【可选】

设置为 true 时，命令将作为子代理执行，避免污染主上下文，这在需要并行处理多个任务时特别有用。

"subtask": true

Model（模型）【可选】

可以覆盖默认模型，使用特定的 AI 模型来执行命令。

"model": "anthropic/claude-3-5-sonnet-20241022"

高级功能

参数传递

自定义命令支持参数传递，这使得命令更加灵活和通用。

使用 $ARGUMENTS 传递所有参数

---
description: Create a new component
---
Create a new React component named $ARGUMENTS with TypeScript support.

执行：/component Button，$ARGUMENTS 将被替换为 Button

使用位置参数 $1, $2, $3...

---
description: Create a new 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 命令的输出，这在需要根据实时数据做决策时非常有用。

---
description: Analyze test coverage
---
Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

Shell 命令在项目根目录执行，输出结果会成为提示词的一部分。

文件引用

使用 @ 符号可以引用文件，文件内容会自动包含在提示词中。

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

实用自定义命令示例

代码审查命令

---
description: Review recent code changes
agent: build
---
Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements, focusing on:
1. Code quality issues
2. Potential bugs
3. Performance concerns
4. Best practices violations

组件创建命令

---
description: Create React component
model: anthropic/claude-3-5-sonnet-20241022
---
Create a new React component named $ARGUMENTS with:
- TypeScript support
- Proper prop types
- Basic styling
- Unit tests

测试覆盖分析命令

---
description: Analyze code coverage
agent: build
---
Current test coverage results:
!`npm run test:coverage`

Analyze the coverage report and suggest:
1. Areas needing more tests
2. Unnecessary test redundancy
3. Coverage improvement strategies

最佳实践

命名规范

• 使用动词开头的命令名，如 test-coverage、review-pr 等
• 保持命令名简洁明了
• 使用连字符分隔单词，提高可读性

描述优化

• 为每个命令提供清晰的描述
• 描述应该说明命令的主要功能
• 在 TUI 中展示时，用户应该能够快速理解命令用途

代理选择

• 根据任务复杂度选择合适的代理
• 简单任务使用默认代理
• 复杂构建任务使用 build 代理
• 分析性任务使用 plan 代理

模板设计

• 保持提示词简洁明确
• 指定具体的输出格式要求
• 包含必要的上下文信息

命令覆盖机制

重要提示：自定义命令可以覆盖内置命令。如果定义了与内置命令同名的自定义命令，将优先使用自定义版本。这提供了极大的灵活性，但也需要谨慎使用，避免意外覆盖重要命令。

文件引用系统

基础文件引用

在 TUI 中，你可以使用 @ 符号引用文件：

How is auth handled in @packages/functions/src/api/index.ts?

系统会自动模糊搜索匹配的文件，并将内容添加到对话上下文中。

高级文件引用

• 支持相对路径和绝对路径
• 可以引用整个目录
• 自动处理文件编码

故障排除

常见问题

命令不执行：

• 检查文件路径是否正确
• 验证 YAML 格式是否有效
• 确认文件扩展名为 .md

参数替换失败：

• 确认使用了正确的参数占位符
• 检查参数格式是否正确
• 验证参数数量是否匹配

Shell 命令无输出：

• 验证命令在项目根目录的执行权限
• 检查命令是否正确安装
• 确认命令语法是否正确

AI 回复不符合预期：

• 优化提示词模板
• 调整模型配置
• 检查是否选择了合适的代理

总结

OpenCode AI 的命令系统提供了极大的灵活性和扩展性。通过创建自定义命令，开发者可以将重复性任务自动化，显著提高开发效率。从简单的参数替换到复杂的 Shell 命令注入，命令系统支持各种使用场景。建议开发者根据实际工作流程，创建一套符合自己需求的自定义命令库，这将极大地提升日常开发体验和效率。