Pi ：上下文工程——Context Assembly、Compaction 与 Memor

这是本系列最重要的横向能力篇。前面所有篇都在讲Agent 怎么运行这一篇讲Agent 每轮调用 LLM 时最终进入模型窗口的那堆 token 到底是怎么来的。每轮给模型构造的上下文才是 Agent 的真正 CPU。模型选错了可以换上下文构造错了Agent 会越跑越傻——这正是本系列一直强调Context 是编译出来的的完整展开。〇、先建立全景一次推理的上下文从哪里来某一轮调用 LLM 时进入窗口的内容可以画成一条流水线用户输入 ↓ System Prompt ↓ 项目级 instructionsAGENTS.md / CLAUDE.md ↓ Skill instructions按需读取的 SKILL.md ↓ 历史 conversation会话树 → 当前叶子路径 ↓ tool result工具执行结果 ↓ 文件内容read 工具读进来的代码/文档 ↓ 错误信息bash 报错、测试失败输出 ↓ 压缩 / 截断 / 摘要compaction 检查点 ↓ 最终 Context ↓ LLMPi 对这条链路的工程化散在本系列各篇里这篇把它们收拢成一个完整学科。记住模型看到什么决定模型做什么。上下文构造是 Agent 的隐性控制器。一、Context Assembly谁有资格进窗口Pi 的上下文由这些来源组装每个来源都有独立的生命周期和信任等级来源Pi 的机制生命周期System Prompt构建链AGENTS.md → skills 目录 → 模板 → before_run 覆盖每 run 构建可覆盖项目 instructionsAGENTS.md/CLAUDE.md/.pi/SYSTEM.md未信任也加载每会话加载Skill instructionsavailable_skills目录 模型按需 read 全文渐进式披露历史对话会话树 → 当前叶子到根的路径append-only工具结果ToolResultMessage 随消息落账每轮追加运行时元数据env 注入的PI_SESSION_ID等每命令解析关键原则本系列反复出现系统提示词保持极简skills 只列描述不内联因为给模型多少判断原料是预算。项目宪法优先AGENTS.md在项目未信任时也加载——这个仓库的规矩优先级高于一切。transform_context是最后一道变换只改 provider 看到的、不改会话存的——呈现层和存储层分离防止为临时目的污染永久记录。二、Context Budget窗口满了谁被扔假设模型窗口 200kAgent 跑久以后历史消息 70k 代码 80k tool output 50k system 5k ---------------- 205k ← 超了谁被扔是决定 Agent 是否越跑越傻的关键决策。候选策略按信息价值从低到高策略丢弃对象代价时间优先最早的消息可能丢关键但早的事实重要度优先低优先级消息闲聊需要消息分级总纲上下文篇工具结果优先旧工具输出模型可能忘了自己做过什么system 永不删系统提示词恒定占固定预算文件重读而非常驻不保存文件内容用时再 read每次重新检索Pi 的立场是追加不变式 一次性失效Across the requests of a lane, provider context only grows at the tail. An insertion before the previous request’s tail invalidates the provider’s KV cache from that point on and multiplies token cost.上下文只允许尾增长——因为中间插入会无效化 KV cache 并放大成本。所以回合中途的写入推迟到 checkpoint 追加compaction 是唯一一次刻意的缓存失效。预算的硬护栏reserveTokens默认 16k 留给响应 溢出判定显式超限错误 / 输入超窗口 / 可恢复 length。预算要在发请求前就算好超了就分类处理事后才裁已经来不及。三、Compaction长周期运行的命脉Compaction 是 Agent 长周期运行的核心技术。完整生命周期Raw history ↓ 触发阈值 / /compact 手动 / overflow 溢出 Summary generationLLM 摘要 ↓ Important state extraction保留关键状态 ↓ Old messages replacementCompactionEntry 落账 ↓ Continue execution从 retainedTail 重建上下文Pi 的CompactionEntry带三样东西summary摘要、firstKeptEntryId保留起点、retainedTail自包含检查点。retainedTail让重建可以从检查点直接往后走不翻旧条目。Compaction 的四个能不能压的判断是工程精华摘要丢信息怎么办分级处理——普通对话可压代码/SQL/合同这类语义敏感内容压了等于改语义。工具执行事实能不能被 summary 覆盖危险。工具做了什么改了哪个文件、结果是什么是审计和继续推理的锚点Pi 的 overflow compaction 明确把链接的那个响应从摘要准备中排除“exact overflow-response omission”——关键事实留原文。文件修改记录该不该压缩不该。修改记录是Agent 对世界做过的改变压掉就无法审计/回滚。用户约束是否允许压缩用户明确说的要求“不要改这个文件”是 CRITICAL 级永不压总纲上下文篇。compaction 的正确姿势压缩的是过程性的旧对话保留的是结论性的状态和约束。四、Working Memory vs Long-term Memory五种不同的存储很多 Agent 项目把记忆当成一个筐但 Pi和 CC 的对照揭示了至少五种不同的存储各有生命周期存储生命周期例子谁来管Conversation History一次会话会话树引擎Working Memory一次 run变量池/车道记录运行时Long-term Memory跨会话CC 的 memory 文件、项目事实应用Project State随项目.pi/settings.json、AGENTS.md应用Artifact State随产物git 历史、生成文件外部关键区分总纲上下文篇知识进上下文靠检索RAG经验进行为靠记忆memory 文件事实靠状态存储项目/产物。三件事别混进一个筐Pi 的会话账本是Conversation History Working Memory的合体append-only lane recordsCC 的 memory 文件是Long-term Memory跨会话的身份/偏好/被纠正过的工作方式项目文件本身就是Project/Artifact StateAgent 不需要记住需要时 read。设计你自己的 Agent 时先回答这五种存储各归谁、各活多久、谁能写。最常见的错误是把 Long-term Memory 塞进 Conversation History——一旦会话压缩记忆跟着丢。五、对照你的工程上下文系统的设计清单能力做法优先级ContextBuilder 单一管道所有模块不许自己拼 prompt总纲P0组装顺序即策略身份→检索→去重→排序→过滤→预算总纲P0预算前置发请求前算 token超了分类处理P0追加不变式上下文只尾增长不中间插入P0compaction 分级普通对话可压约束/事实/敏感内容不压P0五种存储分离对话/工作/长期/项目/产物各归其位P1transform_context 呈现层改 provider 看的不改会话存的P1文件重读而非常驻大文件用时 read不长期占窗口P1一句话收束上下文工程的本质是在有限的窗口里决定模型每一轮该看到什么、不该看到什么。它比模型选择更决定 Agent 质量——因为再强的模型喂错上下文也会胡说。知识卡片本节体系归档┌──────────────────────────────────────────────────────────┐ │ 知识节点上下文工程Agent 的真正 CPU │ │ │ │ What Context Assembly 流水线 Budget谁被扔 │ │ Compaction压过程留结论 五层记忆分离 │ │ │ │ Why 一般原理模型看到什么决定模型做什么。不变量 │ │ ① 上下文只尾增长KV cache 不失效 │ │ ② 预算前置发请求前算好超了就分类处理 │ │ ③ compaction 压的是过程性的旧对话留的是结论和约束 │ │ │ │ How 校验动作 │ │ 画上下文流水线 PaiFlow 预算前置 │ │ │ │ Pits 坑点 │ │ 越跑越傻 / 上下文灌爆 / 记忆混筐 │ │ │ │ Transfer 到 PaiFlowContextBuilder 预算前置 分级压缩 │ └──────────────────────────────────────────────────────────┘