用途:把一项有边界的编码任务交给独立的 OpenCode CLI 实现者执行,再由编排者自己审查其 diff 并落地提交。仅当用户明确要求委派给该实现者时使用;任务小到可自行内联完成、未安装或未认证 opencode CLI、或只需审查时不应使用(审查可用 --read-only 的 plan 代理)。
前提:opencode --version 成功;否则 npm i -g opencode-ai 或从 opencode.ai 安装原生版并执行 opencode auth login。用 command -v opencode 确认 PATH 中的二进制;opencode auth list 至少有一项凭据;处于或将 --cd 指向目标 git 仓库。OpenCode 没有安全默认值,裸 opencode run 会报错,新运行必须通过 --model 或设置模型的 fleet --lane 指定模型;人类决定允许哪些模型,编排者按任务从中挑选。
五步循环:1 写 brief(目标、现状、要改与不要改的内容、项目真实 gate 命令、报告契约,并告知不会提交);2 用内置 helper 派发:node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo,可选 --lane、--read-only、--resume-last、--timeout 2h;3 等待完成(helper 会阻塞,可后台运行并轮询 result.json,缺少二进制退出 127 仍写 result.json);4 审查,不信自报,自己重跑 gate、按 brief 读 diff、检查 touchedFiles、跑 guard 技能、对 schema/迁移做往返验证、对删除做引用 grep;5 落地,gate 通过且 diff 成立后由编排者自行提交,如需修改用 --resume-last 发增量 brief。
自主性:relay 默认用可写的 build 代理,权限默认自动批准(传递 --auto),--no-auto 则遵循代理自身权限配置;read-only(plan)运行从不加 --auto。委派需人类主动选择;授权后提交通过 gate 的工作是约定契约,但应上报而非吸收 OpenCode 的设计决策,范围变化时先询问。
限制:helper 脚本 scripts/relay.mjs 按 UPSTREAM-NOTICE.md 记录的版本打包,需对应已安装并认证的 CLI、Node 18+ 与 git;relay 从不提交,只返回结构化 result JSON。