9.5 KiB
Agent Note: 将上下文注入与轮次执行分离
Status: proposed
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.contexts。拥有上下文的调用方通过 inject() 交付上下文，再独立使用 send() 或 steer() 提交直接消息。将 HookContext 重命名为 AdditionalContext；这个共享结构只保留 content 和 source，移除放置方式与模型不可见元数据。
提示词和工具扩展点仍可返回 additionalContexts。这些值是扩展点的输出，而不是从调用方收件箱条目捕获的附件。提示词准入在 run() 打开轮次之前执行。提示词获准后，它与返回的额外上下文一同进入 outbox；提示词被阻止时，两者都不写入，也不打开轮次。工具产生的额外上下文则在对应工具结果之后进入同一个 outbox。
每项额外上下文都成为独立的 user/message，并由 source 记录来源。移除 context/message、prompt-prefix 放置方式、稳定请求分隔符和提示词封套。transcript 与 UI 消费方通过 source 区分直接用户消息和注入上下文，无需从合并后的模型内容中恢复隐藏的直接提示词字段。
注入生命周期
轮次打开时，inject() 将上下文暂存在 loop outbox 中。agent loop 会在安全的步骤边界排空 outbox，同时保持工具协议要求的相邻关系：在助手工具调用批次期间接纳的上下文，只能出现在该批次所有有序结果之后。系统整体取走 outbox，确保同一边界接纳的 steering 和注入上下文对后续同一次请求可见。
没有打开的轮次时，inject() 会立即追加对应的 user/message 并启动会话刷新。它不会增加轮次编号、发出 turn/start 或 turn/end、改变 agent 状态，也不会运行模型。同步 API 仍会在异步刷新完成前返回；whenIdle() 和 agent dispose（资源释放）会把尚未结束的空闲注入刷新纳入静止边界。
空闲刷新失败时不存在合法的轮次或步骤坐标。系统通过日志或持久化所属的错误接口报告该失败，而不是为不存在的轮次伪造 agent/error 载荷。内存中的事件仍已接纳，后续刷新可以重试持久化。
因此，会话不变量允许 user/message 位于两个轮次之间，同时继续要求执行事件、steering、助手输出、工具事件以及默认的包扩展事件均受轮次边界约束。持久化、恢复、resume、fork、压缩和查询逻辑必须把合法的轮次外 user/message 当作已提交会话历史，而不是中断轮次或可丢弃的日志尾部。
扩展点与调用方语义
PromptDecision.content 仍只替换直接提示词。PromptDecision.additionalContexts 和工具结果的 additionalContexts 保留 FIFO 顺序及各自来源，但不再选择放置方式。waterfall（瀑布式事件）监听器调用 next() 委托时，必须保留下游返回的提示词内容和额外上下文，除非它有意返回替代值。
调用方主动注入与钩子产生的额外上下文具有不同的准入归属。钩子的额外上下文只会在该钩子允许提示词或工具结果后落入日志。调用方执行 inject(context) 后再执行 send(prompt) 时，上下文已独立提交；后续提示词准入即使阻止该提示词，注入上下文仍保留在历史中。需要领域级全有或全无语义的调用方，必须在执行任一操作前自行完成准备，或提供领域专用的准入 seam。
跨会话引用使用普通组合方式：宿主先准备快照，以会话引用来源调用 inject()，再发送或 steer 可读的直接提示词。目标日志包含两条简单消息，因此来源会话后续变化不会改变回放，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/queued只报告保留的消息和 steering 事实。AdditionalContext在提示词拦截、工具执行、hook bridge、guard 和上下文生产方中取代HookContext，且只包含content与source。- 公共类型、持久事件、投影和 UI 回放中均不存在 prompt-prefix 放置方式、提示词封套与
context/message。 - 空闲
inject()在不产生轮次或模型调用的情况下，追加并刷新一条带来源的user/message；whenIdle()和 dispose 会等待该刷新。 - 活跃轮次注入和钩子产生的上下文会在完整工具结果批次之后的安全边界排空，并在消费它们的请求之前进入日志。
- 被提示词准入阻止的消息不会打开轮次，也不会追加提示词或钩子产生的额外上下文；调用方此前独立注入的上下文仍保留。
- 单元测试、持久化与 resume 测试、不变量测试、ACP/TUI 回放测试，以及无需密钥的组装应用快照覆盖新的事件顺序和持久性语义。
风险
- 允许一个表层事件位于轮次之外，会削弱一条简单不变量，并可能暴露持久化扫描、崩溃恢复、fork、压缩和会话查询中的隐含假设。
- 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器和缓存行为必须接受并保留这一顺序。
- 如果调用方不能接受独立提交契约，
inject()后跟一个被阻止的send()会留下缺少预期直接提示词的上下文。 - 同步注入 API 无法返回刷新失败。只记录日志的结构化程度低于
agent/error，但仅为此场景增加新的持久化事件也可能产生另一个不必要的 seam。 - 移除附件、放置方式、元数据、封套和一种持久事件类型，是一次影响面较广的预发布迁移，必须原子更新所有生产方和消费方。