LowHow 文档

中文

English

中文

English

深色模式

OpenCode 自定义命令实战教程：从零创建可复用 AI 工作流 ​

📚 分类: 开发工具配置 ⏱️ 预计耗时: 20-30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并运行 OpenCode 终端 AI 编程助手 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 自定义命令的核心概念和存储位置
  • [ ] 创建带有动态参数（命名参数）的基础命令
  • [ ] 使用子目录组织和管理多个命令
  • [ ] 区分用户级命令和项目级命令，并掌握其用途
  • [ ] 通过 Git 与团队成员共享项目命令

最终效果 ​

你将能够创建一系列可复用的、参数化的 .md 文件。当你需要在 OpenCode 中执行特定任务（如审查代码、分析 Issue、运行测试）时，只需输入命令名，OpenCode 会提示你输入必要的参数，然后自动执行你预设的一系列指令，从而大幅提升工作效率。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证命令
OpenCode已安装并可运行在终端输入 opencode 后能正常启动

1. 确认命令目录 ​

OpenCode 会自动创建命令目录。为了确保一切就绪，我们手动验证一下。在终端执行：

bash
$ mkdir -p ~/.config/opencode/commands    // 创建用户级命令目录（如果不存在）
$ mkdir -p .opencode/commands             // 创建项目级命令目录（如果不存在，需在项目根目录执行）

✅ 验证：执行后没有报错，说明目录已存在或已成功创建。

第 1 步：创建你的第一个基础命令 ​

🎯 目标：创建一个最简单的命令，用于快速获取项目的上下文信息（列出所有文件并显示 README）。

📝 操作：

  1. 创建一个名为 prime-context.md 的文件，路径为 ~/.config/opencode/commands/prime-context.md。
  2. 在文件中写入以下内容：
markdown
# Project Prime Context
RUN git ls-files
READ README.md

RUN 指令告诉 OpenCode 执行一个 shell 命令，READ 指令则将文件内容发送给 AI 模型。

✅ 验证：

  1. 在任意一个 Git 项目目录下启动 OpenCode。
  2. 输入命令 user:prime-context。
  3. 你应该会看到 OpenCode 执行了 git ls-files 和 READ README.md 这两个操作。

💡 提示：user: 前缀表明这是一个用户级的命令。我们稍后会解释它的含义。

第 2 步：创建带参数的动态命令 ​

🎯 目标：创建一个可以解释任意指定文件的命令，而不是只能解释一个写死的文件。

📝 操作：

  1. 创建一个名为 explain-file.md 的文件，路径为 ~/.config/opencode/commands/explain-file.md。
  2. 在文件中写入以下内容：
markdown
# Explain File: $FILE_PATH
RUN ls -la $FILE_PATH
READ $FILE_PATH
Please explain what this file does and document its main components.

🎯 关键概念：命名参数$FILE_PATH 就是一个命名参数。当命令被执行时，OpenCode 会提示你输入它的值。参数规则： * 以 $ 开头，后跟大写字母。 * 只能包含大写字母、数字和下划线。 * 例如：$ISSUE_NUMBER, $DATABASE_NAME。

🤔 为什么要这样做？ 这样做的好处是，一个命令可以处理不同的文件。你不需要为每个要解释的文件都创建一个新的命令文件。

✅ 验证：

  1. 在 OpenCode 中执行命令 user:explain-file。
  2. 你会看到一个输入框，提示你输入 FILE_PATH 的值。
  3. 输入项目中的一个文件路径，例如 src/index.js，然后按回车。
  4. 观察 OpenCode 是否执行了 ls -la src/index.js 和 READ src/index.js 指令。

⚠️ 常见错误： 如果 OpenCode 没有提示你输入参数，请检查：

  • 文件名是否以 .md 结尾。
  • 参数格式是否正确，例如 $FILE_PATH（注意是大写字母，且没有空格）。

第 3 步：组织多个命令 ​

🎯 目标：使用子目录将相关命令分组，让结构更清晰。

📝 操作：

  1. 在 ~/.config/opencode/commands/ 目录下创建一个名为 git 的文件夹。
  2. 在 git 文件夹内创建一个名为 review-prep.md 的文件。
  3. 在 review-prep.md 中写入以下内容：
markdown
# Review Changes for $BRANCH_NAME
RUN git checkout $BRANCH_NAME
RUN git diff main...$BRANCH_NAME
RUN git log main...$BRANCH_NAME --oneline
Please review these changes and:
1. Summarize the key modifications
2. Identify potential issues
3. Check for missing tests

✅ 验证：

  1. 在 OpenCode 中执行命令 user:git:review-prep。
    • user: 是前缀。
    • git: 是子目录名。
    • review-prep 是文件名（不含扩展名）。
  2. 系统会提示你输入 BRANCH_NAME 的值。
  3. 输入一个分支名（例如 feature/new-login），然后观察 OpenCode 是否依次执行了 git checkout、git diff 和 git log 命令。

💡 提示：你可以创建多层子目录，例如 testing/unit.md，对应的命令就是 user:testing:unit。

第 4 步：创建项目级命令 ​

🎯 目标：为当前项目创建一个专用的命令，并通过 Git 与团队成员共享。

📝 操作：

  1. 确保你当前位于项目的根目录。
  2. 在项目根目录下创建 .opencode/commands/ 文件夹（如果不存在）。
  3. 在该文件夹内创建一个名为 api/document-endpoint.md 的文件。
  4. 在 document-endpoint.md 中写入以下内容：
markdown
# Document API Endpoint: $ENDPOINT_PATH
RUN grep -r "$ENDPOINT_PATH" src/
RUN find . -name "*$CONTROLLER_NAME*" -type f
Document the API endpoint at $ENDPOINT_PATH:
1. Describe the HTTP method and route
2. List request parameters
3. Detail the response structure
4. Include error handling

✅ 验证：

  1. 在项目目录下启动 OpenCode。
  2. 输入命令 project:api:document-endpoint。
    • project: 前缀表明这是一个项目级命令。
  3. 你会被提示输入 ENDPOINT_PATH 和 CONTROLLER_NAME 两个参数。
  4. 输入正确的值，观察 OpenCode 是否按预期工作。

🤔 为什么要这样做？ 项目级命令存储在项目的 .opencode/commands/ 目录中。你可以将这个目录提交到 Git 仓库中：

bash
$ git add .opencode/commands/
$ git commit -m "Add custom OpenCode commands for this project"
$ git push

一旦推送，你的团队成员只需拉取代码，就能自动获得这些命令。他们不需要进行任何额外的配置。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 环境感知命令：创建一个命令，根据不同的环境（如 development、staging）执行不同的操作。

    markdown
    # Deploy to $ENVIRONMENT
RUN echo "Environment: $ENVIRONMENT"
RUN cat .env.$ENVIRONMENT
Prepare deployment to $ENVIRONMENT:
- Generate deployment checklist
- Run pre-deployment validation

  2. 组合多个命令：创建更复杂的工作流。例如，一个“代码审查准备”命令可以调用“运行测试”和“检查代码风格”两个子命令的思路，通过在一个 .md 文件中按顺序编写 RUN 指令来实现。

常见问题 (FAQ) ​

Q1: 我创建了命令文件，但在 OpenCode 中找不到它。A: 请检查以下几点：

  • 文件扩展名必须是 .md。
  • 文件必须放在正确的命令目录下（~/.config/opencode/commands/ 或 .opencode/commands/）。
  • 尝试重启 OpenCode，它会重新加载所有命令。
  • 检查文件权限，确保 OpenCode 有读取权限 (chmod +r your-file.md)。

Q2: 我的命令有参数，但 OpenCode 没有提示我输入。A: 请确保：

  • 参数格式正确：$NAME，其中 NAME 以大写字母开头，只能包含大写字母、数字和下划线。例如 $ISSUE_NUMBER 是正确的，$issue_number 和 $1 是错误的。
  • 参数名是唯一的，并且在文件中没有拼写错误。
  • 你没有在参数输入对话框中意外地按了 Escape 键取消。

Q3: 用户命令和项目命令有什么区别？A: 主要区别在于作用域和共享方式：

  • 用户命令 (user: 前缀)：存储在 ~/.config/opencode/commands/，适用于你个人的通用工作流，所有项目都能用。
  • 项目命令 (project: 前缀)：存储在项目内的 .opencode/commands/，适用于特定项目的工作流。它可以被提交到 Git 仓库，从而与团队成员共享。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 命令的存储位置：用户级 (~/.config/opencode/commands/) 和项目级 (<PROJECT_DIR>/.opencode/commands/)。
  2. 创建基础命令：通过编写包含 RUN 和 READ 指令的 .md 文件。
  3. 使用命名参数：通过 $ARGUMENT_NAME 让命令变得更加灵活和可复用。
  4. 组织命令：使用子目录对命令进行分组，形成 user:git:review-prep 这样的命令结构。
  5. 共享命令：将项目级命令提交到 Git 仓库，让团队协作更高效。

© 2026 LowHow