opencode-delegate

OpenCode Delegate

你是编排者。此技能让你可以将范围明确的编码任务交给单独的实现者——OpenCode CLI，然后审查其产出并亲自提交。你撰写任务说明并负责判断；OpenCode 在自己的会话中编写代码；你负责验证并提交。

这里的内容不专属于某一种编排 Agent。此流程只需要能够运行 shell 命令并读取文件，因此任何具备这两项能力的 Agent——Claude Code、驱动同级会话的 OpenCode，或类似工具——都可以执行此流程。（此流程专为 Claude Code 设计并在其上运行；对于其他编排者，应视为已设计支持，但尚未验证。）

以下情况请勿使用

• 任务足够小，可以直接完成——委派带来的额外开销不值得。
• 未安装 opencode CLI 或尚未完成身份验证（运行 opencode auth login）。
• 你想自己编写代码，或只需要审查（通过 --read-only 使用 plan Agent）。

前置条件（检查一次即可）

1. opencode --version 可成功运行。如果不行，请安装（npm i -g opencode-ai，或从 opencode.ai 获取原生安装程序），然后运行 opencode auth login。
2. 确认 PATH 中的 opencode 是哪个。 command -v opencode 会显示当前使用的二进制文件，opencode --version 会显示其版本。中继程序会将运行时使用的版本记录到 result.json，因此事后可以发现是否使用了过期的二进制文件。
3. 已通过某个模型提供商的身份验证——opencode auth list 会显示至少一项凭据。
4. 当前位于目标 Git 仓库中（或准备通过 --cd 指定该仓库）。

选择实现者模型

OpenCode 没有安全的默认模型——直接运行 opencode run 会报错——因此，新的运行需要通过 --model 指定模型，或使用会设置模型的 fleet --lane（恢复的运行会继承其会话中的模型）。指定模型是 codex-delegate 这类单模型后端从未要求过的唯一决策，而且有两个责任方：

• 由人决定允许使用哪些模型。 opencode models 会列出数百个选项，其中大多数按 token 计费（如 OpenRouter 等）；只有人知道自己订阅了哪些固定费率服务，而 CLI 无法区分。因此，可用模型集合由人决定——最好在仓库的 AGENTS.md 或个人的 CLAUDE.md 中说明一次（例如：“机械性工作委派给 opencode-go/…，复杂逻辑委派给 …”）。
• 由你这个编排者从该集合中为每项任务选择模型。 根据任务说明选择模型：机械性批量操作（重命名、迁移、移除）使用快速、低成本的模型；微妙的 Bug 或涉及资金／安全的路径则使用能力更强的模型。
• 如果没有说明可用模型集合，请询问，不要猜测。 根据目录猜测可能会选到按量计费的模型，导致意外账单。向人说明这一限制，让他们做选择。

更多说明：references/writing-the-brief.md。

流程

每项任务都运行以下五个步骤。步骤 1、4 和 5 需要你做出判断；步骤 2 和 3 则是机械操作。

1. 撰写任务说明

OpenCode 只能看到你发送的文本以及它能从工作树中读取的内容——没有聊天记录，也没有共享上下文。任务所需的一切都必须写入任务说明：目标、当前状态、要修改的内容、要保持不变的内容、项目实际使用的门禁命令（从仓库的 AGENTS.md／CLAUDE.md／Makefile 中查找，不要凭空假设），以及报告要求。告诉 OpenCode 它不会提交（由你提交）。每份任务说明只包含一项任务。完整指南和模板见： references/writing-the-brief.md。

2. 派发

对于 Codex 编排的后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并 报告设置要求；不要悄悄回退到由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，代替下面的 shell 示例。 遵循该技能，使用结构化的通用参数、保持提供方标志不变，并通过 runId 重新连接。让请求保持待处理状态，直到任务完成，然后继续执行此技能的审查和落地步骤。其他编排器继续使用下面的 shell 工作流。

使用随附的辅助工具将简报发送给 OpenCode。它会封装 opencode run、捕获运行过程，并写入结构化的 result.json——所以你只需“运行命令，读取文件”。（下面的 <skill-dir> 是此技能的安装目录——即包含此 SKILL.md 的文件夹。Claude Code 在技能加载时会将其打印为“此技能的基础目录”；在其他编排器中使用同一目录——如果不确定它位于何处，请运行 find ~ -name relay.mjs -path '*opencode-delegate*'，并将上级目录替换为该目录。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo
# --model (or a --lane that sets model) is required on a fresh run
# fleet lane from delegate-setup:           add --lane <name>  (dials apply; flags still win)
# read-only (review/diagnosis, no edits):   add --read-only   (uses the plan agent)
# continue the previous OpenCode session:   add --resume-last  (delta brief only; keeps the model)
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

该辅助工具默认使用可写入的 build Agent，并将其产物写入临时目录，因此受审查的仓库会保持干净。它绝不会提交更改——请参阅第 5 步。运行机制、标志和 result.json 格式：references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会让原始 MCP 请求保持待处理状态：不由模型驱动休眠、状态或日志轮询。只有在请求中断后才使用 delegate_wait 重新连接。

辅助工具会一直阻塞，直到 OpenCode 完成，因此请使用编排器提供的任意机制来处理，并在其返回时继续：

• 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 退出，但仍会写入包含状态 opencode_unavailable 的 result.json。）

不要相信进度跟踪器，而要以实际情况为准：只有在写入 result.json 且进程已退出时，运行才算完成。检查工作树，不要只看状态行。实现者的完整报告位于 result.json 的 finalMessage 字段中（也会在 stdout 的报告标记之间完整打印）。

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

OpenCode 的 result.json 包含其最终消息和任何门禁声明。请重新验证，不要直接接受：

• 亲自重新运行项目的门禁（第 1 步中的测试／lint／构建命令）。不要轻信“门禁已通过”。
• 对照简报阅读差异： OpenCode 是否完成了要求，没有多做（范围蔓延），也没有少做？结果中的 touchedFiles 是你的起点。
• 如果安装了相关的防护技能，请对差异运行它们（例如 guard-skills 中的 clean-code-guard、test-guard 等）——此技能负责产出工作；这些技能负责评判工作。
• 对于架构／迁移更改，进行往返验证；对于删除操作，使用 grep 查找悬空引用。

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

5. 落地

实现者编辑工作树；编排器负责提交。 提交应由验证工作的一方执行。只有在门禁通过且差异符合要求后，才执行以下操作：

• 亲自提交已验证的工作，并使用清晰的提交消息。
• 如果需要修改，使用 --resume-last 发送增量简报（不要重述整个任务），然后再次审查。

自主性模型

OpenCode 的自主性由 agent 控制，而非由沙箱枚举值控制：

• build（中继默认值）——具备写入能力；可在工作目录中以无头模式编辑文件。 相当于“让它来实现”。
• plan（通过 --read-only 启用）——只读；会进行审查和诊断，但不会触碰工作树。 相当于“让它看看，但不编辑”。

默认情况下，权限会自动批准：中继会传入 --auto，确保无头运行不会卡在无人能回应的 提示上。这正是无人值守委派的意义所在——编排器的差异审查和实现者检查（步骤 4）才是安全 保障，而不是每个操作都要询问。传入 --no-auto 可改为遵循 agent 自身的权限配置（针对每项 操作设置 allow/ask/deny）；请将其与工作区内权限设为 allow 的 agent 搭配使用，否则无头 运行可能会因等待 ask 而挂起。 只读（plan）运行绝不会传入 --auto——自动批准会放行 plan agent 中受 ask 限制的编辑 和 bash 权限，破坏“只读”保证，因此无法诱使审查过程触碰工作树。

授权模型

委派由人类主动选择。一旦他们表示同意（“运行这个队列”“继续”），提交已验证且通过门禁的 工作就是双方约定的契约——这正是委派的全部意义。该授权有两项限制：呈现，不擅自消化 （报告 OpenCode 的设计决策、有理可辩但未经要求的处理，以及不会阻塞流程的小问题，而不要 默默保留它们）以及范围变更时停止（如果正确完成需要超出简报范围，就先询问——不要自行 扩大授权）。完整说明见 references/review-and-land.md。

参考资料

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