33 — AI 上下文通道:从"字符串后缀"到"语义分道"¶
本文是
builtin/ai上下文体系的新一轮迭代的设计文档,接替 26 / 27 中与 Prompt 前缀、 动态上下文相关的部分。26–29 记录的是上一轮"分层与分包"重构,其中 §D2/D3/D5 与"没有真实消费者不抽象"已在本轮作废,其余契约(A/B/C/E/F/G 组、分包依赖方向)继续有效。状态:
P0–P3已实现(裁剪时机、环境事实、通道模型、原生编码与探测降级);P4待真实流量验证后再决定是否把context_channel默认值切到auto。 v1.83.0 之后auto分支有过一次线上 400 修复(形状选择不再绑定厂商私有 角色、开关作用域覆盖编码侧、思考型端点的历史推理回传,见 §三),P4的 对照数据需在该修复之后重采。
一、问题重述¶
上一轮的结论是"动态上下文只挂在最后一条 user 消息尾部,不写回历史" (27 §D2/D3)。它解决了污染问题:
- 动态内容不进 System,避免每轮前缀从最前面失效;
- 动态内容不写回会话,避免旧时间/旧群状态长期占用上下文。
但它留下了两个未解的成本,本轮直接以它们为目标:
| 成本 | 现状 | 后果 |
|---|---|---|
| 上一轮问答的尾部永久不可复用 | user_N 的内容含 dyn_N,下一轮 user_N 字节已变 |
每轮只保住"上一轮之前",实测命中率天花板 ≈76% |
| 框架事实与用户发言混在同一槽位 | 日期/平台/星期写成 ===== 运行时上下文 ===== 拼进 user |
模型无法区分"用户说的"与"框架提供的",也不便按厂商协议投递 |
因此本轮要回答的问题不是"要不要优雅",而是:哪些上下文可以随历史回放, 哪些只能属于当前回合?
二、核心决策:按"可回放性"分道,而不是按厂商协议分道¶
2.1 两个通道¶
// builtin/ai/promptctx
type Channel int
const (
// Persistent 随会话历史持久化并逐轮原样回传。
Persistent Channel = iota
// Ephemeral 只属于当前回合,永不写回会话。
Ephemeral
)
判据只有一条:回放这条内容,会不会给模型新的指令权限?
- 框架掌握的事实(时间、时区、星期、平台、会话类型)回放不改变权限 →
Persistent; - 群聊窗口、长期记忆、RAG 命中、执行计划、反思/校验指令来自任意成员或被模型
抽取 → 回放等于把不可信内容永久钉成历史 →
Ephemeral。
2.2 信任边界用类型保证,不用字段+运行时检查¶
上一版提案是"每条 Item 带一个 Trust 枚举,Renderer 按 Trust 决定注入位置"。
本轮改为类型级隔离:
// 只有框架事实能构造 Persistent 项
func (f EnvironmentFacts) Items() []Item
// 其余来源只能产 Ephemeral 项
func (s Source) Collect(...) []Item
Trust 枚举被取消。理由:枚举是"可以被赋错的值",而类型是"编译期就写不进去
的位置"。RAG 结果被提升成 system 指令这个隐患,在新模型下不存在可表达路径,
因此也不需要单独的"Trust Boundary"回归用例去守。
2.3 顺序:只追加(append-only)¶
Persistent 项作为独立消息落在对应那一轮的 user 消息之前,随历史一起增长:
turn1 请求: [sys] ctx1 u1 a1
turn2 请求: [sys] ctx1 u1 a1 ctx2 u2
turn3 请求: [sys] ctx1 u1 a1 ctx2 u2 a2 ctx3 u3
上一轮的请求是下一轮请求的严格字节前缀,ctx_n/u_n/a_n 全部永久可复用。
这是唯一能突破 76% 天花板的形状,也是各家"上下文缓存按请求前缀逐块比对"的
直接推论:历史里回放的每一条都在命中范围之内。
同时它天然满足放置约束:ctx 紧跟自己的 user 消息,工具轮在其后追加
assistant/tool,不会把 ctx 挤到 tool_use 与 tool_result 之间。
去重规则(实现时的必要补充):环境事实只按日期粒度表达(见
protocol.EnvFacts 刻意不含时钟),因此同一份事实在多轮之间逐字节相同。
写入前与历史里最近一条环境消息比较,相同则不重复追加——事实已经在历史里,
模型随时能读到;重复追加只会按回合线性占用窗口预算。跨日后事实变化,才写
新的一条。这也让 ctx_n 在一天之内保持稳定,不再逐轮增长。
三、厂商适配:只用两家公开协议里的形状¶
框架只声明兼容两种线格式(config.provider):OpenAI 兼容 / Anthropic 兼容。
两种协议里各有一个官方定义的"应用级指令"形状,都能承载环境事实:
| 线格式 | 原生形状 | 硬约束 |
|---|---|---|
| OpenAI 兼容 | role: "developer" |
官方定义于 o1 之后;部分兼容网关不认(会 400/422)。位置无约束 |
| OpenAI 兼容(退路) | 数组内 role: "system" |
同上;作为 developer 被拒后的第二候选 |
| Anthropic 兼容 | 数组内 role: "system" |
不能是首条;必须紧跟 user 或以 tool_result 结尾的 assistant;不得夹在 tool_use/tool_result 之间;只有部分模型支持 |
刻意不使用任何厂商私有角色。 例如某些端点提供了 latest_reminder 这类
私有角色,字段取值也由该厂商单方面定义(platform 只允许 App/Web、
weekday 必须用该语言书写……)。把它按 base_url 识别后就发出去,等价于在
框架里内置一张必然腐化的厂商名单:新增一个兼容网关要改代码,改错就是整轮
对话 400,而且用户配置的模型是未知的。生产事故(unknown platform 'qq')正是
这条路径的直接结果。
形状只看 provider,不看模型名或域名:
protocol.NativeContextCandidates(provider)
// openai → developer → 中途 system → none
// anthropic → 中途 system → none
8080 网关、Ollama、自建 vLLM 在 OpenAI 兼容线上与 OpenAI 官方完全一样, 因此不需要、也不允许按域名分叉。OpenAI 那条多一个候选,因为"不认 developer、 但认 system"是兼容网关最常见的差异;Anthropic 没有这个退路(官方要求中途 system 紧跟 user,而 developer 角色它根本不认),因此被拒后直接折进 user 文本。
失败处理是逐级探测,而不是一刀切:
- 收到 400/422 且错误体指向该形状(
role/developer/system/unknown variant等)→ 记入ProbeMemory(键 = provider + base_url + 形状), 下一次请求直接跳到下一个候选;全被拒后折进 user 文本。 - 400/422 在推理前拒绝、不消耗 token,因此"探测失败一次"的成本可接受, 换来的是新模型/新网关零维护。
三条相关的修复也在这一层(生产事故的直接原因):
- 开关必须同时作用于编码侧:
envChannelShape()早期只按端点能力返回形状、 不看context_channel,于是"曾经开过 auto"留下的历史记录在改回user_suffix之后仍会被编成原生角色发出去——配置已关掉却依然报错。现在写入与编码共用同一 判定:关闭时形状为None,旧记录折回 user 文本。 include_runtime_context=false不被绕过:它是"完全不注入"的隐私开关, 现在连折回 user 文本都不做(runtime.DropEnvContext)。- 历史工具轮的推理必须能回传(见 §3.2)。
3.1 存储角色与线格式角色必须分离¶
会话历史里存的是 provider 中立的 RoleEnvContext + JSON 载荷(protocol.EnvFacts),
不是某家的线格式。原因:历史一旦落库就长期存在,而端点可以换
(OpenAI 兼容 ↔ Anthropic 兼容 ↔ 任意自建网关);两种形状的角色名与位置约束
都不同(developer 在 user 之前 / 中途 system 必须在 user 之后),存成其中一种
就只能投递给对应的线格式。
编码由装配侧的 runtime.EncodeEnvContext 一处完成,适配器只负责序列化:
| 形状 | 放置 | 正文 |
|---|---|---|
| developer | 保持在 user 之前 | <environment> 指令块 |
| 中途 system | 挪到 user 之后(否则 400) | <environment> 指令块 |
| 兜底 | 删除独立消息,正文折进 user | 散文(不加标签) |
最后一行就是"探测失败后回退到 user 文本"的实现,与 user_suffix 的表达等价。
3.2 思考型模型的推理必须能随历史回传¶
有的端点在思考模式下、且请求携带 tools 时,要求历史里每个
assistant(tool_calls) 都带回它当初产出的推理文本,缺了直接 400
(The reasoning_content in the thinking mode must be passed back to the API.)。
这是端点侧语义,不是厂商判断,因此处理方式同样是"探测 + 记性",而不是名单:
Message.Reasoning/ChatResponse.Reasoning/StreamEvent.Reasoning是 provider 中立的推理文本;OpenAI 适配器把它映射成线格式的reasoning_content,只在非空时才发出——从不产出推理的端点完全不受影响。- 带工具调用的轮次会把推理写回会话历史(普通对话轮不写,避免无谓的历史膨胀)。
- 旧版本落库的轮次没有推理可回传:探测到上面那条 400/422 后,记入
ProbeMemory.RequiresReasoningEcho,后续请求为这些轮次显式补一个空串 (端点接受空串、拒绝缺字段),并重试同一轮。 - Anthropic 线格式不受影响:那边的推理是带签名的 thinking 块,拿不到签名就 无法回传,官方允许缺省。
这条路径同样不认厂商:判据只有"端点返回了这条错误",因此永远不会给不需要它的 端点多发字段。
四、窗口裁剪必须收敛到回合边界(P0,已实现)¶
这是本轮的前置项:只要 TrimMessages 还在回合中途跑,append-only 的
前缀收益就会被抵消——裁剪每发生一次,其后的历史全部失效。
历史实现把裁剪挂在 AppendMessageNoPersist(回合内每条中间消息)和
SessionManager.snapshot(每次 SaveSession,含回合内落库)上,于是:
- 一个 4 轮工具回合会被裁多次;
- 被裁掉的最大受害者恰是本回合刚生成、还没被任何后续请求复用的工具结果。
现在的约定:
// 回合边界唯一裁剪入口
func (sm *SessionManager) TrimWindow(session *Session)
// 回合内追加:不裁剪
func (sm *SessionManager) AppendMessageNoPersist(session *Session, msg protocol.Message)
processWithTools以 defer 调用:回收附件字节 → TrimWindow → SaveSession, 因此落库快照看到的是裁剪后的窗口;touch/snapshot只在!TurnActive()时裁剪(回合进行中不使用头部)。
TrimMessages 的语义本身不变:批量低水位、System 优先、不裁出孤儿 tool 消息、
不破坏 assistant(tool_calls) 与 tool 结果的紧邻关系。变的只是调用次数:
从"每条中间消息一次"降到"每次 processWithTools 一次"。
五、实施顺序¶
| 阶段 | 内容 | 验收 |
|---|---|---|
| P0 ✅ | 裁剪收敛到回合边界 + 时机用例 | 回合内第 n 轮请求是第 n+1 轮的严格前缀;全量测试绿 |
| P1 ✅ | EnvironmentFacts + EnvFacts 载荷:补 weekday / timezone / language / location / conversation kind;RenderEnvProse 保持默认输出逐字节不变 |
facts_test.go 的逐字节用例 + 既有 context_pipeline_test.go 不改即绿 |
| P2 ✅ | Item / Channel / Snapshot / Render:信任边界由类型保证(只有 EnvironmentFacts.PersistentItems 能产 Persistent) |
item_test.go(含指纹稳定性与预算共享) |
| P3 ✅ | RoleEnvContext 存储角色 + 适配器编码(developer / 中途 system / 兜底)+ 端点探测降级 + context_channel 开关 |
envcontext_test.go(放置规则)、capability_test.go(候选顺序与降级边界)、append_prefix_test.go(跨轮严格前缀)、envcontext_channel_test.go(默认不变 + 逐级降级) |
| P3.1 ✅ | 线上修复:形状只看 provider(删除厂商私有角色)、开关作用域覆盖编码侧、include_runtime_context=false 不被绕过、思考型端点要求历史工具轮回传推理时的探测与回补 |
capability_test.go(候选/降级/推理回传判据)、provider_test.go(reasoning 三种线上形状)、runtime/envcontext_test.go(编码失败折回 user)、envcontext_channel_test.go(关闭后不得再发原生角色、全部形状被拒后折进 user) |
| P4 ⏳ | 真实流量对照 ai_llm_tokens_total{type="prompt_cached"} 与 ai_context_channel_total,决定是否把默认值切到 auto |
一周数据(在 P3.1 之后采样) |
P3 必须带开关:freeze_prefix_test 里"动态上下文不写回历史"的断言在
user_suffix 下仍然成立,两条通道可以共存、用数据决胜负。
六、对本轮作废/修改的旧结论¶
| 来源 | 结论 | 处置 |
|---|---|---|
| 27 §D2 | "动态上下文只挂尾部、不写回历史" | 细化为:Ephemeral 不写回;Persistent 必须写回 |
| 27 §D3 | "任何新增 Provider 数据默认不得进入 Stable Prefix" | 作废:Persistent 项就是要进入历史前缀 |
| 27 §D5 | "ToolSet 是唯一跨 History 边界的动态变量" | 作废:Persistent 上下文同样是跨边界变量 |
| 29 不变量 9 | "没有真实消费者不抽象" | 降为建议;P3 的持久化回放就是消费者 |
TestAnthropicDropsMidArraySystemButKeepsUserTail |
把"中途 system 被丢弃"当成期望 | 保留"能力关闭时降级为 user 尾部",新增"能力开启时原位保留" |
freeze_prefix_test.go msgs[:len-1] |
以"除最后一条"作为稳定前缀 | 改为"首个 context-channel 消息之前的全部消息"(P2 时随之调整) |
A/B/C/E/F/G 组契约(ToolSet 语义、Execute 三态、检索权重、策略闸门、运行时语义、 配置/指标/持久化)与 29 的分包依赖方向继续有效。
七、明确不做¶
-
不使用任何厂商私有消息角色(如
latest_reminder)来投递框架事实:字段取值由 该厂商单方面定义、其它端点一律拒绝,写进框架等于内置一张会腐化的厂商名单; 通用形状(developer / 中途 system)+ 逐级探测已能覆盖所有 OpenAI/Anthropic 兼容端点。 -
Source接口外置给第三方插件注册(需要注册/权限/超时/隔离一整套,当前无消费者); Priority × Relevance × Freshness / TokenCost评分公式(现有节序 + 预算已够用);Resource Resolver独立子模块(attachments.go的hydrateAttachmentParts已经是资源解析,protocol.ContentPart已实现引用与二进制分离);Context Delta/ 回合内快照版本化(先保证单回合一致性)。