把编码任务委托给 OpenCode CLI…

当你想把有边界的编码任务交给 OpenCode CLI 在独立会话中实现、自己只做审查和提交时使用。

适用场景

解决思路

1. 确认前置条件：`opencode --version` 成功（否则 `npm i -g opencode-ai` 或从 opencode.ai 安装原生包，并 `opencode auth login`）；用 `command -v opencode` 确认 PATH 上的二进制；用 `opencode auth list` 确认至少有一个模型凭据；处于或准备用 `--cd` 指向目标 git 仓库。
2. 选择实现模型：OpenCode 没有安全默认值，裸 `opencode run` 会报错，新运行必须通过 `--model` 或设置模型的 `--lane` 指定模型（恢复运行会继承会话模型）。由人类决定允许哪些模型（`opencode models` 列出数百个，多数按 token 计费，CLI 无法区分是否为包月订阅），最好在仓库的 `AGENTS.md` 或 `CLAUDE.md` 中一次性声明；你按任务从该集合中挑选——机械性工作（重命名、迁移、删除）用便宜快速的模型，微妙 bug 或涉及金钱/安全的路径用强模型；若没有声明可用集合，直接询问人类，不要猜测以免产生意外账单。
3. 写简报：OpenCode 只能看到你发送的文本加上它能从工作树读取的内容，没有聊天历史或共享上下文。简报中要包含目标、当前状态、要改什么、不要动什么、项目真实的 gate 命令（从仓库的 AGENTS.md/CLAUDE.md/Makefile 中发现，不要假设）以及报告契约；告诉 OpenCode 它不会提交（由你来提交）；每个简报只放一个任务。
4. 派发：用捆绑的 helper 把简报发给 OpenCode，它包装 `opencode run`、捕获运行并写出结构化的 `result.json`。命令：`node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo`。新运行必须带 `--model`（或设置模型的 `--lane`）；可选 `--lane <name>`（来自 delegate-setup 的 fleet lane，flags 仍优先）、`--read-only`（用 plan agent 做审查/诊断，不编辑）、`--resume-last`（继续上一个 OpenCode 会话，只发增量简报，保留模型）、`--timeout 2h`（看门狗硬时限，默认关闭，实现运行通常需要 1-2 小时）；用 `node .../relay.mjs --help` 查看全部选项。helper 默认使用可写的 `build` agent，产物写到临时目录以保持仓库干净，且从不提交。
5. 等待完成：helper 会阻塞直到 OpenCode 结束，用你的编排器提供的能力支撑它并在返回时恢复——Claude Code 用 `run_in_background: true` 运行 Bash 调用并在完成时收到通知；普通 shell 或其他 agent 对短任务前台运行，或后台运行并轮询结果文件（bash/zsh 包括 Git Bash/WSL 用 `… &`，PowerShell 用 `Start-Job`，cmd 用 `start /b`）。当 `result.json` 存在且有 `status` 时运行完成（运行前的用法错误如参数错误或空简报会以退出码 2 退出且不写结果文件，所以也要检查退出码；缺少 `opencode` 二进制会以 127 退出但会写 `status` 为 `opencode_unavailable` 的 `result.json`）。不要相信进度跟踪器胜过现实：读工作树，不要读状态行。实现者的完整报告在 `result.json` 的 `finalMessage` 字段（也会在 stdout 的报告标记之间完整打印）。
6. 审查——不要相信自我报告：`result.json` 包含 OpenCode 自己的最终消息和 gate 声明，要重新验证而非接受。自己重新运行项目的 gate（第 1 步中的测试/lint/build 命令），绝不轻信“gate 通过”；对照简报读 diff，看 OpenCode 是否做了要求的事、没有多做（范围蔓延）也没有少做，`touchedFiles` 是起点；如果安装了相关 guard 技能（如 guard-skills 的 clean-code-guard、test-guard 等）就在 diff 上运行——本技能产出工作，那些技能评判工作；对 schema/迁移变更做往返测试，对删除操作 grep 悬空引用。
7. 落地：实现者编辑工作树，编排者提交——提交应是验证工作的一方的行为。只有在 gate 通过且 diff 成立后才自己提交已验证的工作并写清晰的消息；如果需要修改，用 `--resume-last` 发送增量简报（不要重述整个任务）并再次审查。
8. 自主性模型：OpenCode 的自主性由 agent 而非沙箱枚举控制——`build`（relay 默认）可写，无头编辑工作目录文件，相当于“让它实现”；`plan`（通过 `--read-only`）只读，审查和诊断而不碰工作树，相当于“让它看但不编辑”。权限默认自动批准：relay 传 `--auto` 使无头运行不会阻塞在无人能回答的提示上，这是无人值守委托的意义——编排者的 diff 审查和实现者清扫（第 4 步）是安全网，而非逐操作提示。传 `--no-auto` 改为遵守 agent 自己的权限配置（按操作 allow/ask/deny），并搭配工作区内权限设为 allow 的 agent，否则无头运行可能挂起等待 ask。只读（`plan`）运行永远不加 `--auto`——自动批准会让 plan agent 的 ask 门控编辑/bash 权限通过，破坏“只读”，使审查无法被诱骗去碰工作树。
9. 授权模型：委托是人类选择加入的。一旦他们同意（“运行这个队列”“继续”），提交已验证、通过 gate 的工作就是约定的契约——这正是重点。对该授权的两个限制：暴露而非吸收（报告 OpenCode 的设计决策、可辩护但未被要求的转向以及非阻塞的小问题，而不是默默保留）和为范围变更停下（如果正确完成需要超出简报，询问——不要自己扩大授权）。

适用边界 · 注意事项

• 任务小到可以直接内联完成——委托开销不值得。
• `opencode` CLI 未安装或未认证（需运行 `opencode auth login`）。
• 你想自己写代码，或只需要审查（用 `plan` agent 加 `--read-only`）。