opencode 自定义命令与键位绑定

两个小改动、回报很大的点:自定义斜杠命令把重复 prompt 打包成一行调用,键位绑定把 TUI 调成顺手的形状。

自定义斜杠命令

把 markdown 文件放进 .opencode/commands/(项目级)或 ~/.config/opencode/commands/(全局),文件名即命令名:

---
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.

在 TUI 里执行:

/test

frontmatter 设置命令选项,正文是 prompt 模板。自定义命令与 /init、/undo、/redo、/help 等内置命令并存——同名时自定义命令覆盖内置命令。

也可以在 opencode.json 的 command 键下定义,此时 template 必填:

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.",
      "description": "Run tests with coverage"
    }
  }
}

模板占位符

$ARGUMENTS——完整参数字符串:/component Button 把 Button 填进模板。
$1、$2、$3…——按位置取参,适合多槽位模板,如 Create a file named $1 in $2 with content: $3。
!`command`——在项目根目录执行 shell 命令,输出注入 prompt:

---
description: Review recent changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements.

@file——自动把文件内容带进 prompt:审查 @src/components/Button.tsx 里的组件。

命令选项

键	作用
`template`	发给 LLM 的 prompt。JSON 配置里必填;Markdown 文件用正文充当。
`description`	在 TUI 里挑选命令时显示的说明。
`agent`	由哪个 agent 执行(默认当前 agent)。目标是 subagent 时默认触发 subagent 调用。
`subtask`	`true` 强制走 subagent 调用,即使目标 agent 是 `mode: primary`——保持主上下文干净;`false` 关闭。
`model`	按命令覆盖模型。

给评审命令固定 agent: plan,就能保证对 diff 做只读评审。

键位绑定:tui.json

TUI 键位在 tui.json 里配置,不在 opencode.json——那里的旧 keybinds 键已废弃并自动迁移(见配置指南)。映射关系是动作名 → 键位:

{
  "$schema": "https://opencode.ai/tui.json",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "session_new": "<leader>n",
    "session_compact": "<leader>c",
    "agent_cycle": "tab",
    "app_exit": "ctrl+c,ctrl+d,<leader>q"
  }
}

leader 键——默认 ctrl+x,先按 leader 再按快捷键(ctrl+x 然后 n = 新会话)。leader_timeout 控制等待毫秒数。自定义绑定建议走 <leader>,避免与终端冲突。
取值形式——单个快捷键、逗号分隔的多个备用、数组,或带 key、event、preventDefault、fallthrough 的对象。
解绑——把动作设为 "none"(或 false)即可禁用。

常用动作:

动作	默认	作用
`agent_cycle` / `agent_cycle_reverse`	tab / shift+tab	切换主 agent
`session_new`、`session_list`、`session_compact`	`<leader>n`、`<leader>l`、`<leader>c`	会话管理
`session_interrupt`	escape	中断正在生成的回复
`session_child_first` / `session_parent`	`<leader>down` / up	进入 / 离开 subagent 子会话
`model_list`、`agent_list`	`<leader>m`、`<leader>a`	模型与 agent 选择器

完整动作列表见 keybinds 文档。一个坑:部分终端不会发送 Shift+Enter——文档给了各终端的修法,含 Windows Terminal。

v2 差异

v2 命令文档改了几处:JSON 键为 commands(复数);subtask 成为 subagent 的废弃别名——subagent: true 让命令在后台子会话运行。嵌套目录形成命名空间:.opencode/commands/team/review.md 以 /team/review 调用。存储的模板不再展开 @file 引用,改为调用时附加文件。同名时项目级命令覆盖全局命令,命令文件保存即热重载。键位也搬家了:v2 里在 ~/.config/opencode/cli.json 的 keybinds 下——取值形式不变(带 key、event、preventDefault、fallthrough 的对象)但命令 id 从 snake_case 换成点分式(app_exit→app.exit、input_paste→prompt.paste),leader_timeout 变成与之平级的顶层 leader.timeout。见 v1↔v2 对照。

自定义斜杠命令

模板占位符

命令选项

键位绑定:tui.json

v2 差异

延伸阅读