opencode-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenCode Delegate

You are the orchestrator. This skill lets you hand a bounded coding task to a separate implementer — the OpenCode CLI — then review what it produced and land it yourself. You write the brief and own the judgment; OpenCode does the typing in its own session; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell command and read a file, so any agent with those two capabilities — Claude Code, OpenCode driving a sibling session, or a comparable one — can drive it. (It is designed for and run on Claude Code; treat other orchestrators as designed-for, not yet proven.)

你是orchestrator。此技能允许你将一个边界明确的编码任务交给独立的implementer——即OpenCode CLI——然后审查其产出并自行完成落地。你编写任务简报并负责判断；OpenCode在其独立会话中完成代码编写；你进行验证并提交。

这里没有特定于某个编排agent的内容。该循环仅需要能够运行shell命令和读取文件的能力，因此具备这两项能力的任何agent——Claude Code、驱动同级会话的OpenCode，或类似agent——都可以驱动它。（它是为Claude Code设计并运行的；其他orchestrator视为适配设计，但尚未经过验证。）

When NOT to use this

何时不使用此技能

The task is small enough to just do inline — delegation overhead is not worth it.
The
```
opencode
```
CLI is not installed or not authenticated (run
```
opencode auth login
```
).
You want to write the code yourself, or you only need a review (use the
```
plan
```
agent via
```
--read-only
```
).

任务足够小，可以直接在线完成——委托的开销不值得。
```
opencode
```
CLI未安装或未完成认证（运行
```
opencode auth login
```
）。
你希望自己编写代码，或仅需要审查（通过
```
--read-only
```
使用
```
plan
```
agent）。

Prerequisites (check once)

前提条件（检查一次）

```
opencode --version
```
succeeds. If not, install (
```
npm i -g opencode-ai
```
, or the native installer from opencode.ai) and
```
opencode auth login
```
.
Confirm which
opencode
is on PATH.
```
command -v opencode
```
shows the active binary and
```
opencode --version
```
its version. The relay records the version it ran into
```
result.json
```
, so a stale binary is visible after the fact.
A model provider is authenticated —
```
opencode auth list
```
shows at least one credential.
You are in (or will point
```
--cd
```
at) the target git repository.

```
opencode --version
```
执行成功。如果不成功，请安装（
```
npm i -g opencode-ai
```
，或从opencode.ai下载原生安装程序）并运行
```
opencode auth login
```
完成认证。
确认PATH中的
opencode
版本。
```
command -v opencode
```
会显示当前使用的二进制文件路径，
```
opencode --version
```
显示其版本。中继器会将运行的版本记录到
```
result.json
```
中，因此事后可以查看是否使用了过时的二进制文件。
已完成模型提供商的认证——
```
opencode auth list
```
显示至少一个凭证。
你处于（或将通过
```
--cd
```
指向）目标git仓库中。

Choose the implementer model

选择实现模型

OpenCode has no safe default — a bare

opencode run

errors — so the relay requires

--model

on every fresh run (a resumed run inherits its session's model). Naming the model is the one decision a single-model backend like codex-delegate never had, and it has two owners:

The human owns which models are allowed.
```
opencode models
```
lists hundreds of entries, most billed per token (OpenRouter and the like); only the human knows which are their flat-rate subscriptions, and the CLI can't tell them apart. So the usable set is theirs — ideally stated once in the repo's
```
AGENTS.md
```
or their
```
CLAUDE.md
```
(e.g. "delegate mechanical work to
```
opencode-go/…
```
, hard logic to
```
…
```
").
You, the orchestrator, pick per task — from that set. Match the model to the brief: a cheap, fast model for a mechanical sweep (rename, migration, removal); a strong one for a subtle bug or a money/security path.
If no usable set is stated, ask — don't guess. Guessing from the catalog risks a metered model and a surprise bill. Name the constraint to the human and let them choose.

More depth: references/writing-the-brief.md.

OpenCode没有安全默认值——直接运行

opencode run

会报错——因此中继器要求每次新运行都必须指定

--model

（恢复的运行会继承其会话的模型）。指定模型是像codex-delegate这样的单模型后端从未需要做的决策，它有两个负责方：

人类用户决定允许使用哪些模型。
```
opencode models
```
列出了数百个条目，大多数按token计费（如OpenRouter等）；只有人类用户知道哪些是他们的固定费率订阅，CLI无法区分。因此可用模型集由用户决定——理想情况下在仓库的
```
AGENTS.md
```
或
```
CLAUDE.md
```
中一次性说明（例如：“将机械性工作委托给
```
opencode-go/…
```
，复杂逻辑委托给
```
…
```
”）。
作为orchestrator，你根据任务从可用集中选择。使模型与任务简报匹配：便宜、快速的模型用于机械性扫描（重命名、迁移、移除）；强大的模型用于微妙的bug或涉及资金/安全的路径。
如果未说明可用模型集，请询问——不要猜测。从目录中猜测可能会使用按计量收费的模型，导致意外账单。向人类用户说明限制条件并让他们选择。

更多细节：references/writing-the-brief.md。

The loop

工作流程

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

每个任务执行以下五个步骤。步骤1、4和5需要你的判断；步骤2和3是机械性操作。

1. Write the brief

1. 编写任务简报

OpenCode sees only the text you send plus what it can read from the working tree — no chat history, no shared context. Everything the task needs goes in the brief: the goal, the current state, what to change, what to leave untouched, the project's actual gate commands (discover them from the repo's AGENTS.md/CLAUDE.md/Makefile — do not assume), and a report contract. Tell OpenCode it will not commit (you will). Keep one task per brief. Full guidance and a template: references/writing-the-brief.md.

OpenCode只能看到你发送的文本以及它可以从工作树中读取的内容——没有聊天历史，没有共享上下文。任务所需的所有信息都必须包含在简报中：目标、当前状态、需要更改的内容、需要保留不变的内容、项目的实际门禁命令（从仓库的AGENTS.md/CLAUDE.md/Makefile中查找——不要假设），以及报告约定。告知OpenCode它不会提交代码（由你完成）。每个简报对应一个任务。完整指南和模板：references/writing-the-brief.md。

2. Dispatch

2. 分发任务

Send the brief to OpenCode with the bundled helper. It wraps

opencode run

, captures the run, and writes a structured

result.json

— so your only job is "run a command, read a file." (

<skill-dir>

below is this skill's installed directory — the folder containing this

SKILL.md

. Claude Code prints it as "Base directory for this skill" when the skill loads; on other orchestrators use that same directory — if unsure where it landed, run

find ~ -name relay.mjs -path '*opencode-delegate*'

and substitute the directory above it.)

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo

使用捆绑的辅助工具将简报发送给OpenCode。它封装了

opencode run

，捕获运行过程，并写入结构化的

result.json

——因此你只需“运行命令，读取文件”即可。（下面的

<skill-dir>

是此技能的安装目录——包含此

SKILL.md

的文件夹。当技能加载时，Claude Code会将其打印为“Base directory for this skill”；在其他orchestrator上使用相同的目录——如果不确定位置，可以运行

find ~ -name relay.mjs -path '*opencode-delegate*'

并替换其上级目录。）

bash

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo

--model is required on a fresh run (see "Choose the implementer model" above)

新运行必须指定--model（参见上方“选择实现模型”部分）

read-only (review/diagnosis, no edits): add --read-only (uses the plan agent)

只读模式（审查/诊断，不编辑）：添加--read-only（使用plan agent）

continue the previous OpenCode session: add --resume-last (delta brief only; keeps the model)

继续之前的OpenCode会话：添加--resume-last（仅提供增量简报；保留模型）

see all options: node .../relay.mjs --help

查看所有选项：node .../relay.mjs --help


The helper defaults to the write-capable `build` agent and writes its artifacts to a temp dir, so the
repo under review stays clean. It **never commits** — see step 5. Mechanics, flags, and the
`result.json` shape: [references/dispatch-and-poll.md](references/dispatch-and-poll.md).


辅助工具默认使用可写入的`build` agent，并将其产物写入临时目录，因此被审查的仓库保持干净。它**永远不会提交代码**——参见步骤5。机制、标志和`result.json`的结构：[references/dispatch-and-poll.md](references/dispatch-and-poll.md)。

3. Wait for completion

3. 等待完成

The helper blocks until OpenCode finishes, so back it with whatever your orchestrator offers and resume when it returns:

Claude Code: run the Bash call with
```
run_in_background: true
```
; you are notified on completion.
Plain shell / other agents: run it in the foreground for short tasks, or background it and poll the result file —
```
… &
```
in bash/zsh (including Git Bash/WSL), or your shell's equivalent (
```
Start-Job
```
in PowerShell,
```
start /b
```
in cmd). The run is done when
```
result.json
```
exists with a
```
status
```
. (A pre-run usage error — bad args or an empty brief — instead exits with code 2 and writes no result file, so check the exit code too. A missing
```
opencode
```
binary exits 127 but does write a
```
result.json
```
with status
```
opencode_unavailable
```
.)

Do not trust progress trackers over reality: a run is finished when

result.json

is written and the process has exited. Read the working tree, not a status line.

辅助工具会阻塞直到OpenCode完成，因此使用orchestrator提供的方式后台运行它，完成后再恢复：

Claude Code：使用
```
run_in_background: true
```
运行Bash调用；完成时会通知你。
普通shell / 其他agent：短任务在前台运行，或后台运行并轮询结果文件——在bash/zsh中使用
```
… &
```
（包括Git Bash/WSL），或使用shell的等效命令（PowerShell中的
```
Start-Job
```
，cmd中的
```
start /b
```
）。当
```
result.json
```
存在且包含
```
status
```
字段时，运行完成。（运行前的使用错误——参数错误或简报为空——会以代码2退出且不写入结果文件，因此也要检查退出代码。如果缺少
```
opencode
```
二进制文件，会以127退出，但会写入
```
result.json
```
，其中
```
status
```
为
```
opencode_unavailable
```
。）

不要相信进度跟踪器，要以实际情况为准：当

result.json

写入且进程退出时，运行才完成。读取工作树，而不是状态行。

4. Review — do not trust the self-report

4. 审查——不要相信自我报告

OpenCode's

result.json

includes its own final message and any gate claims. Re-verify, don't accept:

Re-run the project's gates yourself (the test/lint/build commands from step 1). Never take "gates passed" on faith.
Read the diff against the brief: did OpenCode do what was asked, nothing more (scope creep) and nothing less?
```
touchedFiles
```
in the result is your starting point.
Run the relevant guard skills on the diff if you have them installed (clean-code-guard, test-guard, etc. from
```
guard-skills
```
) — this skill produces the work; those skills judge it.
For schema/migration changes, round-trip them; for removals, grep for dangling references.

Full checklist: references/review-and-land.md.

OpenCode的

result.json

包含其自己的最终消息和任何门禁声明。重新验证，不要接受：

自行重新运行项目的门禁命令（步骤1中的测试/ lint/构建命令）。永远不要轻信“门禁已通过”。
对照简报查看差异：OpenCode是否完成了要求的工作，不多做（范围蔓延）也不少做？结果中的
```
touchedFiles
```
是你的起点。
如果已安装相关守卫技能，对差异运行这些技能（来自
```
guard-skills
```
的clean-code-guard、test-guard等）——此技能生成工作成果；那些技能负责判断其质量。
对于架构/迁移变更，进行往返测试；对于移除操作，搜索悬空引用。

完整检查清单：references/review-and-land.md。

5. Land it

5. 落地

The implementer edits the working tree; the orchestrator commits. Committing should be the act of the party that verified the work. Only after the gates pass and the diff holds:

Commit the verified work yourself, with a clear message.
If it needs changes, send a delta brief with
```
--resume-last
```
(don't restate the whole task) and review again.

Implementer编辑工作树；orchestrator提交代码。提交应该由验证工作成果的一方执行。只有在门禁通过且差异符合要求后：

自行提交已验证的工作，并附上清晰的提交信息。
如果需要更改，使用
```
--resume-last
```
发送增量简报（不要重述整个任务）并再次审查。

Autonomy model

自治模型

OpenCode's autonomy is governed by the agent, not a sandbox enum:

build
(the relay default) — write-capable; edits files in the working dir headlessly. The equivalent of "let it implement."
plan
(via
```
--read-only
```
) — read-only; reviews and diagnoses without touching the tree. The equivalent of "let it look but not edit."

Permissions auto-approve by default: the relay passes

--auto

so a headless run never blocks on a prompt no one can answer. That is the point of unattended delegation — the orchestrator's diff review and the implementer sweep (step 4) are the safety net, not a per-action prompt. Pass

--no-auto

to honor the agent's own permission config instead (allow/ask/deny per action); pair it with an agent whose in-workspace permissions are set to allow, or a headless run can hang waiting on an

ask

. Read-only (
plan
) runs never get
--auto
— auto-approving would let the plan agent's ask-gated edit/bash permissions through and defeat "read-only," so a review can't be tricked into touching the tree.

OpenCode的自治由agent控制，而非沙箱枚举：

build
（中继器默认）——可写入；在工作目录中无界面编辑文件。相当于“让它实现”。
plan
（通过
```
--read-only
```
）——只读；仅审查和诊断，不修改工作树。相当于“让它查看但不编辑”。

权限默认自动批准：中继器传递

--auto

参数，因此无界面运行永远不会因无人响应的提示而阻塞。这是无人值守委托的意义所在——orchestrator的差异审查和implementer的扫描（步骤4）是安全网，而非每个操作的提示。传递

--no-auto

参数以遵循agent自身的权限配置（每个操作允许/询问/拒绝）；搭配工作区权限设置为允许的agent使用，否则无界面运行可能会因等待

询问

而挂起。只读（
plan
）运行永远不会获得
--auto
参数——自动批准会让plan agent受询问限制的编辑/bash权限生效，从而破坏“只读”特性，因此审查不会被诱使修改工作树。

Authorization model

授权模型

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that mandate: surface, don't absorb (report OpenCode's design decisions, defensible-but-unasked turns, and non-blocking nitpicks rather than silently keeping them) and stop for scope changes (if correct completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment is in references/review-and-land.md.

委托是人类用户主动选择的功能。一旦他们选择（“运行此队列”、“继续”），提交已验证且通过门禁的工作成果就是约定的契约——这正是整个功能的意义所在。该授权有两个限制：披露而非隐瞒（报告OpenCode的设计决策、合理但未被要求的变更以及非阻塞性的小问题，而非默默保留）和范围变更时停止（如果正确完成任务需要超出简报范围，请询问——不要自行扩大授权）。完整说明见references/review-and-land.md。

References

参考资料

references/writing-the-brief.md — how to write a brief OpenCode can execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
references/dispatch-and-poll.md —
```
relay.mjs
```
flags, the
```
result.json
```
contract, backgrounding per orchestrator, and recovery when a run misbehaves.
references/review-and-land.md — the review checklist, the commit boundary, and the rework cycle via
```
--resume-last
```
.
references/multi-task-queues.md — running a sequential queue: carrying constraints forward, progress tracking, and the end-of-run coherence check.

references/writing-the-brief.md —— 如何编写OpenCode可以盲执行的简报：结构、XML块、报告约定、嵌入真实门禁命令。
references/dispatch-and-poll.md ——
```
relay.mjs
```
标志、
```
result.json
```
契约、各orchestrator的后台运行方式，以及运行异常时的恢复方法。
references/review-and-land.md —— 审查清单、提交边界，以及通过
```
--resume-last
```
进行返工的流程。
references/multi-task-queues.md —— 运行顺序队列：传递约束、进度跟踪，以及运行结束时的一致性检查。