deepseek-harness/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md

Agent Note: 将上下文注入与轮次执行分离

Status: implemented

English | 中文

问题

agent API 曾用三种相互重叠的方式表示面向模型的补充输入：调用方通过 SendOptions.contexts 附加 HookContext[]，拦截钩子和工具钩子返回 additionalContexts，插件则调用 agent.inject()。这些路径最终都把上下文写入同一份模型历史，但各自携带不同的放置、元数据、准入、队列和轮次生命周期规则。

将上下文原子附加到收件箱消息后，agent loop（智能体循环）曾被迫让上下文跟随提示词准入、steering（中途引导）转换、取消和终止丢弃的完整生命周期。prompt-prefix 放置方式又曾把上下文与直接提示词合并为一个事件，因此 transcript（文本记录）消费方不得不依赖模型不可见的封套，才能还原用户实际输入。这样一来，outbox 条目、会话投影和 UI 回放都曾负责处理本应由生产方负责的区分。

空闲状态下的 inject() 还暴露了另一处语义错位。注入当时并不请求模型执行，但实现仅为了满足轮次封闭不变量并获得持久性检查点，就会打开并关闭一个零步骤的 injection 轮次。于是，当时的轮次有时表示「运行 agent loop」，有时却表示「不运行 agent，仅持久化上下文」。

HookContext 的名字也描述了生产方，而非该值的职责。它可能来自原生插件、hook bridge、提示词准入或工具后处理；其稳定含义是带来源信息的额外模型上下文。

决策

inject() 是调用方交付补充模型输入的唯一操作，而轮次表示一次模型循环执行。

SendOptions 只包含 target 和 wakeup。拥有上下文的调用方通过 inject() 交付带标识且冻结的 UserMessage，再独立使用 send() 或 steer() 提交直接消息。

提示词和工具扩展点仍可返回 additionalContexts。这些值是扩展点的输出，而不是从调用方收件箱条目捕获的附件。提示词准入在 run() 打开轮次之前执行。获准的提示词及其返回的额外上下文会作为独立消息进入新轮次；提示词被阻止时，两者都不写入，也不打开轮次。工具产生的额外上下文则在对应工具结果之后进入 outbox。

每项额外上下文都是独立的 user/message，并由 source 记录来源。不再有 context/message、prompt-prefix 放置方式、稳定请求分隔符或提示词封套。transcript 与 UI 消费方通过 source 区分直接用户消息和注入上下文。

注入生命周期

提示词准入期间或轮次打开时，inject() 会将上下文暂存在 loop outbox 中。私有的 next-step 接受窗口在 agent/prompt-submit 前打开，并在 turn/end 前关闭，因此同一边界接受的 steering 和上下文会进入后续同一次请求，而 turn/end 监听器提交的晚到 steering 则成为排队提示词。agent loop 会在安全的步骤边界排空 outbox，同时保持工具协议要求的相邻关系：在助手工具调用批次期间接受的上下文，只能出现在该批次所有有序结果之后。

在该窗口之外，inject() 会立即追加对应的 user/message。它不会增加轮次编号、发出 turn/start 或 turn/end、改变 agent 状态，也不会运行模型；持久化通过 session/event 观察这次追加。

如果提示词准入被阻止或失败，调用方暂存的仅含上下文的批次会立即追加，且不产生轮次。steering 及与其一同暂存的上下文会留在 outbox 中，供后续获准提示词使用；取消或 dispose（资源释放）可能丢弃它们。钩子产生的 additionalContexts 属于被拒绝的准入决策，因此永远不会落入日志。

会话不变量允许 user/message 位于两个轮次之间，同时继续要求核心执行事件、steering、助手输出和工具事件均受轮次边界约束。可合并扩展事件的关系由声明它们的插件拥有，而不是采用核心默认规则。持久化、恢复、resume、fork 和压缩会把合法的轮次间事件当作已提交会话历史，而不是中断轮次或可丢弃的日志尾部。

扩展点与调用方语义

PromptDecision.content 仍只替换直接提示词。PromptDecision.additionalContexts 和工具结果的 additionalContexts 保留 FIFO 顺序及各自来源，但不再选择放置方式。waterfall（瀑布式事件）监听器调用 next() 委托时，必须保留下游返回的提示词内容和额外上下文，除非它有意返回替代值。

调用方主动注入与钩子产生的额外上下文具有不同的准入归属。钩子的额外上下文只会在该钩子允许提示词或工具结果后落入日志。在 next-step 接受窗口之外，调用方执行 inject(context) 后再执行 send(prompt) 时，会独立提交上下文；需要全有或全无语义的调用方应使用领域专用的准入包装层。

跨会话引用采用这种领域组合方式：TUI 先准备快照，然后在接受窗口之外将其加入提示词准入决策，或在窗口期间将其注入到 steering 旁。目标日志包含两条简单消息，因此来源会话后续变化不会改变回放，transcript 消费方也不需要提示词封套。本决策取代跨会话引用决策中的附件机制，但保留其快照与信任边界规则。

本决策保留移除注入内容封套确立的调用方自主管理框架原则，以及一次 send、一个轮次确立的单条目轮次规则。后续的独立纯日志事件决策将同样的「轮次仅表示执行」语义应用于插件所属记录。

曾考虑的替代方案

保留 SendOptions.contexts 作为原子附件。 提示词准入阻止消息时，这种方式能保留全有或全无交付，但也会让上下文继续成为收件箱生命周期状态的一部分，并迫使每次队列转换和观察事件携带它。大多数调用方都可以通过先注入上下文、再交付消息来表达需求，通用 agent API 不应内置领域事务。

保留独立的 context/message 会话事件。 独立事件可以缩小轮次外事件的例外范围，但面向模型的 user-role 输入会再次拥有两个投影完全相同的事件类型。user/message.source 已能为策略、transcript 和回放消费方提供所需区分。

为空闲注入保留一次性轮次。 这种方式能保留通用轮次封闭和方便的刷新边界，却会让轮次计数与轮次观察方报告从未运行模型的工作。持久性是独立的会话关注点，无需伪造执行即可等待。

保留 prompt-prefix 可选放置方式。 前缀烘焙可以让上下文和请求位于同一条提供方消息中，但它会引入直接提示词的第二种表示，并把放置处理扩散到准入、steering、日志、回放和 UI 代码。需要文本框架的生产方可以直接把它写入自身上下文内容。

让钩子直接调用 inject()，而不是返回额外上下文。 直接注入会破坏扩展点的准入归属：下游监听器阻止操作之前，上游监听器就可能已经追加上下文。返回 additionalContexts 能维持 waterfall 结果的最终权威性，同时复用准入后的 outbox 路径。

验证

• SendOptions 与 steering 收件箱记录不包含附加上下文；agent/inbox/enqueue 只报告消息及其已解析的 queued 或 steering 放置方式。
• UserMessage 是提示词拦截、工具执行、hook bridge、guard 和上下文生产方共享的带标识且冻结的形状。
• 公共类型、持久事件、投影和 UI 回放中均不存在 prompt-prefix 放置方式、提示词封套与 context/message。
• 空闲 inject() 在不产生轮次或模型调用的情况下，追加一条带来源的 user/message。
• 准入期间和活跃轮次中的注入会在完整工具结果批次之后的安全边界排空，并在消费它们的请求之前进入日志。
• 被阻止的提示词准入不会打开轮次，也不会追加提示词或钩子产生的额外上下文；仅有调用方上下文时会回退为空闲追加，而带 steering 的边界仍可重试。
• 单元测试、持久化与 resume 测试、不变量测试、宿主／客户端队列测试和 TUI 覆盖会固定事件顺序、准入归属和重连分类。

后果

• 一个表层事件可以合法位于轮次之外，因此持久化扫描、崩溃恢复、fork、压缩和会话查询需要区分执行封闭与会话历史。
• 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器会保留这一顺序。
• 在接受窗口之外，inject() 后跟一个被阻止的 send() 会留下缺少预期直接提示词的上下文，除非调用方提供领域专用的准入归属。
• 公共投递契约和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。