opencode 主/子代理相互通信:原语、身份与调度本文基于 opencode-goal 插件(开源,SDK 1.18)真实实现编写。主题:主代理与子代理间双向自由通信的工具设计,以及配套的调度纪律。1. 问题域opencode 的 Task 子代理默认模型是单次交付:派发、执行、回传一个最终消息。工程规模的自主任务需要更丰富的通信语义:子代理中途遇到问题,主动向主代理提问;主代理确认子代理进度或下达调整;子代理中断后恢复原会话(历史与 task_id 保留)继续执行;并行任务间确认式通信。2. 通信原语:manage_subagent 工具插件暴露单一工具manage_subagent,四种 action:action语义对目标会话的影响relay双向自由通信:直接发送消息不中止目标、不等待空闲;忙时由平台排队prompt救子代理:先中止、等空闲,再发消息继续历史 task_id 保留abort终止子代理同上wait仅确认(无消息)无实现要点(依据src/server.ts::manage_subagent):参数校验:action 白名单、subagent_id必填、relay/prompt 必带 message、禁止向当前会话自身发消息;relay与prompt共用底层send_prompt(promptAsync),因此自动续推与人工通信走同一通道,超时语义一致:发送超时(SDK_CALL_TIMEOUT_MS)返回SEND_TIMEOUT,由调用方决策。3. 身份解析:parent 魔法目标子代理不知道主代理会话 ID。工具支持目标parent自动回程:if(sidparent){constpidawaitresolve_parent_session(context.sessionID)// 失败返回 NO_PARENT(不静默)targetpid}解析来源:官方session.get信息的parentID字段。子代理回程主代理:manage_subagent relay parent 子代理报告:某处卡住,请问如何处理?调度纪律同时要求:委派时主代理告知子代理主会话 ID,子代理回告自己的会话 ID。身份解析是兜底,双向通告是纪律。4. 忙时语义与子孙门relay目标忙时消息由平台排队,不丢弃;插件门链配套:子会话 busy 时父会话不放行续推(续推若排在子代理工作后,顺序被破坏)。两者共同保证直发消息插队不破坏主流程。5. 调度纪律(与工具配套的规则层)通信能力必须配合调度纪律才成体系(MANDATORY_PREAMBLE 规则层):评估再委派:子代理执行更优或任务独立可并行时方委派;按关联度决定等待或并行:后续任务依赖子代理结果则等待;不依赖则立即并行推进,子代理完成后自动接续;中断恢复原会话:经原 task_id 续做,禁止新建子代理重做(历史与上下文不丢,这正是prompt保留历史的原因);双向自由通信:委派时互告会话 ID;子代理遇问题经消息接口提问,主代理必须回答并回传。6. 验证goal-communication-test.mjs(12 断言):relay 直发不中断、prompt 恢复、abort、wait、非法 action 拒绝、parent 解析;门链测试:子代理 busy 阻断父会话续推;超时路径SEND_TIMEOUT覆盖于 helpers 测试。7. 结论主/子代理通信的三要素:一个通道(promptAsync复用)、两种语义(relay 柔性直发 / prompt 抢救续做)、一键回程(parent目标)。配合调度纪律后,多代理协作具备可提问、可中断、可恢复、可并行的一致性,而非一次性交付的脆弱模型。