OpenCode 命令：自定义命令、参数与安全复用

OpenCode 提供 /init、/undo、/redo、/share、/help 等内置 TUI 命令。它们不是 Shell 别名，也不是应该写进项目 package.json 的脚本。请在 OpenCode 接收提示词的位置输入，并在继续前阅读确认信息或结果。

不确定当前版本支持哪些命令时，先用 /help。/undo 与 /redo 影响会话中的变更历史，不能取代 Git 提交；/share 可能创建可分享的会话状态，涉及私有仓库或客户代码时要先检查公开范围。内置命令会随版本变化，静态页面不应假设列表永久不变。

1. 在项目根目录创建 .opencode/commands/review.md。
2. 写一条简短的 frontmatter 描述，并让提示词只负责一件事。
3. 在小分支中运行，检查提示词和 diff 后再交给团队使用。

---
description: Review the current changes
---
Review the current Git changes. Explain risky behavior,
missing tests, and the smallest safe follow-up.
Do not edit files until I approve the plan.

文件名会成为命令名，上面的文件通过 /review 调用。全局目录 ~/.config/opencode/commands/ 适合跨项目复用的个人流程，项目目录适合包含本地路径、测试约定和团队规范的命令。提示词应明确输入、输出和边界；“审查变更并给出计划”比“修复一切”更容易验证。

OpenCode 也支持在 JSON 或 JSONC 配置的 command 对象中定义自定义命令。需要指定 agent 或 model，或希望命令和其他项目设置一起审查时，这种方式更紧凑。配置优先级、Schema 和路径仍属于opencode.jsonc 配置指南的范围。

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test-review": {
      "template": "Review the latest test output and list the first three fixes.",
      "description": "Review test output",
      "agent": "plan"
    }
  }
}

配置文件不是密钥存储。API key、token 和私有 endpoint 应放在 Provider 支持的凭据路径中。即使命令只有几行，只要它会引用文件或运行 Shell，就应像脚本一样审查。

---
description: Create a file with supplied values
---
Create a file named $1 in directory $2.
Use this content: $3
Show the proposed path before writing.

/create-file config.json src "{ \"key\": \"value\" }" 会传入三个值。模板需要说明每个值的用途，并要求在写入前显示目标路径。只需要一段自由文本时，$ARGUMENTS 比位置参数更简单。

官方文档还支持用 @ 加文件名引用文件，例如 @src/components/Button.tsx；用 !`npm test` 或 !`git log --oneline -10` 把 Shell 输出注入提示词。命令从项目根目录运行，输出会成为上下文，所以不要把破坏性或可能泄露秘密的命令写进可复用模板。

参数是输入，不是权限。包含路径、Shell 片段或 JSON 的命令仍受 OpenCode 权限策略约束。先做只读测试，再批准最小编辑，最后才考虑在可信仓库中自动化。

如果自定义命令与内置命令同名，它可能覆盖内置行为。除非确实需要并准备好回滚，不要使用 help、undo、share 等名字。像 review-tests 这样的名字更容易让协作者理解预期。

把命令文件当作代码进行 Git 审查：检查提示词 diff、生成结果、引用的文件和拟执行的 Shell。当命令指定 agent 或 model 时，结合Agents 指南检查工具边界；依赖 Skills 或 MCP 时，分别查看Skills 指南和MCP 指南。

1. 范围：用一句话写明输入和输出。
2. 位置：选择项目目录或全局目录，并在 README 中说明。
3. 输入：测试正常、缺失、带引号和路径型参数。
4. 上下文：在请求编辑前检查文件引用和 Shell 输出。
5. 权限：从 ask 或只读行为开始，再批准最小变更。
6. 回滚：把命令放入 Git，并记录如何停用或重命名。

这比临时粘贴一大段提示词慢一点，但下次运行会拥有相同的命名、上下文和审查边界。失败也更容易定位：命令缺失通常是路径问题，结果错误通常是模板或参数问题，编辑被拒绝通常是权限问题，模型失败则回到 Provider 配置。