opencode 注入用户提示词:机制、语义与边界本文基于 opencode-goal 插件(开源,SDK 1.18)真实实现编写。主题:插件如何向会话注入驱动文本,以及该注入必须遵守的约束。1. 问题域opencode 插件无法改写会话历史消息,但可以通过两种钩子与对话发生关系:experimental.chat.system.transform(系统侧,见专题)与client.session.promptAsync(用户侧)。自动续推依赖后者:把生成的续推文本作为一条用户消息注入会话,模型收到后继续推理。注入链路必须回答三个问题:注入什么、注入给谁、注入失败怎么办。2. 注入调用形态src/server.ts::send_prompt的核心调用:awaitpromptFn.call(session,{path:{id:session_id},body:{...(agent?{agent}:{}),...(variant?{variant}:{}),parts:[{type:text,text}],},})2.1 agent 与 variant 的权威读取agent:续推消息携带会话当前 agent(plan 代理不续推,守卫在门链层);variant:发送前实时调用session.get读取模型 variant,避免冷启动把用户选择的思考深度降级为默认值;读取失败回退内存缓存session_variant。该读取必须成功或可回退,不得抛错中断注入:session.get异常时捕获并采用缓存值。2.2 超时语义:发后即忘promptAsync以SDK_CALL_TIMEOUT_MS(默认 10000,envGOAL_SDK_TIMEOUT_MS)为超时上限。实现采用手动时钟标记:定时器触发仅置timed_out true,不取消底层 promise。理由:SDK 超时与成功可能同时返回undefined,with_timeout 的 fallback 无法区分;取消底层 promise 可能造成半发送(副作用不幂等);该注入的副作用(追加一条用户消息)可重试,重复送达由会话自身语义消解。调用方按返回值决策:send_prompt返回是否在时限内完成。TICK 续推忽略该结果(下一 tick 自然重试);manage_subagent必须报告SEND_TIMEOUT,由主代理决定重试。3. 收消息侧:chat.message 钩子用户消息进入时,chat.message钩子不改写消息文本。其职责限定为四项:激活:将会话加入session_user_activated,供重启门裁决;记录:写入last_agent;印记:调用stamp_event,刷新滑动窗口,实施速率限制;活动信号:调用note_user_activity,供批量中止决议判定是否为真实用户操作。禁止改写用户原文的理由:一是静态前缀缓存(KV)不被动态注记击穿;二是改写破坏 opencode 撤销/重放语义。4. 设计约束约束实现驱动文本必须最小续推文本由continuation_prompt生成,不含动态注记不触碰用户原文chat.message 只读,全部写操作落到持久化状态超时不得误报手动时钟标记 不取消 promise失败必须可重试副作用幂等,调用方(TICK)天然重试5. 验证集成测试goal-tick-loop-test.mjs:断言注入后会话收到续推文本;故障注入goal-fault-injection-test.mjs:promptAsync 抛错时目标保持 active、循环不死;单元tests/test-server-helpers.mjs:send_prompt 超时/成功路径。6. 结论用户侧注入的正确定义:发送最小驱动文本,不修改已存在消息;一切量(agent、variant、超时)显式读取并给出失败路径;记录与注入分离,注入与取消分离。违背任一条,注入会污染缓存、破坏撤销或卡死循环。