05 上下文管道 模型看到的，和会话里存的，从来不是一回事

先记住这一句

这个分层解决的问题很具体：一次 !ls 的 bash 执行、一段压缩摘要、一条扩展插入的通知，在 UI 上要各自渲染成不同的东西，在会话文件里要保留各自的结构以便日后回放，但对 LLM 来说它们只能是 user/assistant/toolResult 三选一。

推论有两条，都很容易踩：

• 模型从来没见过「压缩摘要」这个概念。摘要抵达模型时是一条普通 user 消息，靠一段固定的英文前缀说明自己是什么。
• 会话文件里的消息数 ≠ 请求里的消息数。有被过滤掉的（!! 前缀的 bash），有被合并改写的。调试「模型为什么没看到 X」时，要看的是转换之后的结果。

两道闸的位置

循环在每次 LLM 调用前依次过这两道闸，顺序固定：先 transformContext（可选），再 convertToLlm（必需）。agent-loop.ts:290 agent-loop.ts:295

let messages = context.messages;
if (config.transformContext) {
    messages = await config.transformContext(messages, signal);
}

// Convert to LLM-compatible messages (AgentMessage[] → Message[])
const llmMessages = await config.convertToLlm(messages);

// Build LLM context
const llmContext: Context = {
    systemPrompt: context.systemPrompt,
    messages: llmMessages,
    tools: context.tools,
};

闸一：transformContext 在 pi 里等于「扩展说了算」

coding-agent 传给这道闸的实现只有一件事——把消息交给扩展系统，别的什么都不做：sdk.ts:350–354

transformContext: async (messages) => {
    const runner = extensionRunnerRef.current;
    if (!runner) return messages;
    return runner.emitContext(messages);
},

这个设计选择值得停一下：transformContext 是每次 LLM 调用都跑一遍的钩子，扩展在这里的任何操作都乘以 turn 数。它适合做「注入当前时间」「附上打开的文件列表」这类幂等的上下文补充，不适合做重计算。

闸二：convertToLlm 把四种自定义 role 全部压成 user

会话里有六种 role。三种原样透传，另外三种（外加 custom）一律变成 user：messages.ts:148–195

那两段前缀是纯文本常量，不是任何协议字段：messages.ts:11 messages.ts:19

export const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:
export const BRANCH_SUMMARY_PREFIX = `The following is a summary of a branch that this conversation came back from:

唯一会凭空消失的消息

bashExecution 带 excludeFromContext 标志时直接返回 undefined，最后被 filter 掉。messages.ts:154–156 这对应用户敲 !!cmd（双感叹号）：命令执行、输出显示在 UI 上、写进会话文件，但不进模型上下文。

这是全书值得单独记住的一个 UX 设计：给用户一个「我自己看看，别让模型知道」的逃生口，同时会话文件仍然完整——回放和审计不丢信息。

穷尽性检查挡住了「忘了处理新 role」

switch 的 default 分支里放了 const _exhaustiveCheck: never = m;。messages.ts:190 任何人通过声明合并给 AgentMessage 加了新 role 而没在这里处理，类型检查会失败，不会静默地把消息丢掉。

对照 第 03 章看：pi 在「循环控制流」上不给扩展任何余地，但在「消息种类」上开放了声明合并——代价用一个 never 兜住。

为什么是两道闸而不是一道

合成一道也能跑。分开的价值在于职责稳定性：convertToLlm 是类型驱动的、必须穷尽的、跟随 role 定义变化；transformContext 是策略驱动的、可选的、跟随部署环境变化。前者错了是类型错误，后者错了是效果问题。

体现在签名上：convertToLlm 在 AgentLoopConfig 里是必填，transformContext 是可选。agent-loop.ts:290 一个 agent 可以没有任何上下文策略，但不可能没有消息映射。

把摘要降级成普通 user 消息的代价

好处很实在：不依赖任何 provider 的特殊能力，换模型不用改；摘要能被 prompt cache 正常缓存；不需要在 pi-ai 层为「摘要」造一个跨 provider 的抽象。

代价同样实在：模型可能把摘要当成用户的话。「The conversation history before this point was compacted…」是一句请求模型配合的英文，不是一道结构约束。非英语强势的模型、或被大量后续内容淹没时，这个约定的可靠性会下降，而且失败是静默的。

仓库里未见对这一取舍的公开论述；从代码看不出有过 provider 原生机制（如 Anthropic 的 system 块分层）的尝试痕迹。

扩展能改上下文，但改不了「已经存了什么」

两道闸都不写回 context.messages。扩展可以让模型看不到某条消息，但那条消息仍在会话文件里；反过来扩展塞进去的东西，除非显式 appendEntry，否则不会留痕。

这条边界让「会话文件是可信记录」这件事成立——审计一个 run 时看会话文件即可，不必重放所有扩展。代价是「模型当时到底看到了什么」在会话文件里查不到，要靠 telemetry（见 第 14 章）。

• 会话文件不记录转换后的请求。排查「模型为什么没看到 X」时，会话文件只能证明 X 存在过，不能证明 X 进过请求。两者之间隔着扩展的 emitContext。
• transformContext 每 turn 跑一次。在一个 30 turn 的 run 里，一个做网络请求的上下文扩展就是 30 次网络请求。签名上看不出这个频率。
• 摘要前缀是英文硬编码。与中文 / 多语言会话混排时，模型面对的是一段语言切换的提示。messages.ts:11 未见有配置项可改。
• custom role 没有任何标识包装。扩展塞进去的内容直接成为 user 消息，模型无从分辨它来自程序还是来自人。写扩展时必须自己在文本里说清楚。messages.ts:162–169

检查过但未发现问题：convertToLlm 是纯函数，不改入参数组（用 .map().filter() 产出新数组），因此不存在 第 03 章 §2 那种就地修改的隐患。

• 会话历史用自己的 role 体系，别迁就 LLM 的三种角色。UI 渲染、回放、审计各有各的信息需求，压进三种 role 会不可逆地丢掉它们。 适用条件：你需要回放或审计会话。一次性对话不值得这层映射。
• 映射函数用穷尽性检查（TypeScript 的 never）兜底。加新消息类型时忘记处理映射，是这类设计最典型的静默丢消息。 适用条件：消息类型可被下游扩展。封闭类型集不需要。
• 给用户一个「不进上下文」的逃生口，但仍然记进会话文件。pi 的 !!cmd 是个好范例：既省 token，又不牺牲记录完整性。 适用条件：用户能直接执行命令。纯对话式 agent 无此需求。
• 如果你靠一段自然语言前缀让模型区分「摘要」和「用户原话」，把这件事当成 prompt 工程来测，不要当成结构保证。它会失败，而且失败时没有任何信号。 适用条件：所有做上下文压缩的 agent。除非你的 provider 提供了原生的分层机制。