Unreal Agent Context Builder 设计解析：纯内存上下文构建与截断压缩报告机制

Unreal Agent Context Builder 设计解析纯内存上下文构建与截断压缩报告机制【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent在 AI Agent 框架中上下文构建决定了模型每一轮能看到什么、看不到什么。Unreal Agent 是一个异步优先async-first的智能体框架其 Context Builder 采用纯内存上下文构建策略不发起任何 I/O、不依赖持久化只在内存中组装发给大模型的请求并附带一份截断压缩报告Report透明地记录被省略、截断或压缩的内容。本文将带你读懂这套机制的设计思路。Context Builder 在 Unreal Agent 中的位置 Unreal Agent 的 harness 库由多个协作组件构成Context Builder 是其中职责最纯粹的一个。官方组件表对它的定义只有一句话见 README.md有状态地在内存中组装模型输入返回模型输入以及任何被省略、截断或压缩内容的记录不执行 I/O不接受持久化依赖。它和相邻组件的分工如下组件职责与 Context Builder 的关系Session Inbox会话级输入去重产出的输入交给 Builder 拼装Coordinator执行 LLM 轮次每轮调用Build()取请求Session Store持久化会话历史Builder 完全不碰它LLM Adapter发送请求、认证、取消只接收 Builder 构建好的请求这种单一职责 零 I/O的划分让上下文构建逻辑可以独立测试、独立替换——这是理解后续所有设计决策的起点。纯内存设计为什么禁止 I/O核心约束写在包注释里contextbuilder.go// Package contextbuilder defines I/O-pure, in-memory model request construction.禁止 I/O 带来三个实际好处可预测性——构建请求是同步、确定性的操作不会因网络或磁盘延迟阻塞 Coordinator 的事件循环可测试性——所有行为都能在纯内存中用单元测试覆盖参考实现的全部行为由 builder_test.go、control_test.go、submission_test.go 验证可替换性——接口 Builder 不绑定任何存储后端你可以实现一个带真实截断/压缩策略的 Builder 注入进来。截断压缩报告机制Report 与 Change 这套机制是 Context Builder 最有辨识度的设计。构建结果不是裸请求而是Result结构contextbuilder.gotype Result struct { Request llm.Request // 发给模型的请求 Report Report // 构建过程中发生什么变化 }报告由若干Change记录组成每种变化都有明确的类型变化类型含义omitted省略某段内容完全没进上下文truncated截断某段内容被截短compacted压缩某段内容被摘要或重写每条Change还带有Source来源和Reason原因字段contextbuilder.go。这个设计的价值在于上下文透明性调试模型为什么没看到某个文件内容这类问题时你不需要猜直接看 Report 即可。参考实现目前返回空报告builder.go因为内置策略不做删减但接口已为自定义的截断/压缩策略预留了上报通道。两段式状态committedPrefix 与 stagedSuffix ✂️Builder 的内部状态只有一组核心字段builder.gotype builder struct { request llm.Request preamble string systemPrompt string committedPrefix []llm.Item // 已提交前缀 stagedSuffix []llm.Item // 暂存后缀 }这体现了一种两阶段提交思想暂存staged外部输入、心跳消息、工具结果先进入stagedSuffix尚未定稿提交Commit调用 Commit() 把暂存区整体并入前缀构建BuildBuild()把committedPrefix stagedSuffix拼成最终输入并返回不改变 Builder 自身状态。Coordinator 在每个 LLM 轮次开始前调用Build()loop.go拿到请求后交给 LLM Adapter 发送。Builder 本身作为 Coordinator 的依赖注入coordinator.go整个过程对持久层完全无感。各类事件如何进入上下文Builder 接口按事件类型划分入口方法contextbuilder.go每类事件的处理策略值得细看1. 外部输入——AddExternalInput校验输入类型后解码为文本作为用户消息进入暂存区builder.go。2. 控制消息—— 分两种模式builder.goUpdateSettings只更新模型的推理强度等配置不产生对话内容Heartbeat心跳唤醒则把唤醒原因作为用户消息加入上下文。3. 模型响应——AddModelResponse直接把模型输出追加到已提交前缀因为模型自己的历史是定稿的。4. 工具结果与运行占位符—— 这是异步优先架构的精华。Unreal Agent 的工具调用是异步的发起后立即返回后台执行。尚未完成时上下文里放一个占位结果builder.goTool call is still running. Its result arrives in a later turn: continue with independent work, or end your turn to wait for it.结果真正到达后AddToolResult会用真实输出替换掉占位符builder.go避免上下文里出现过期状态。5. 技能Skills—— 通过go:embed嵌入提示词模板把宿主选择的技能列表序列化成 XML 清单追加到系统提示词末尾skills.go让模型知道有哪些专长可用、何时用SkillUse加载。系统提示词本身 内置前导词 宿主提示词 技能清单。内置前导词prompts/preamble.md专门教模型理解异步轮次语义每个轮次都会重发完整对话所以应并行发起相互独立的工具调用调用运行中结束轮次等于睡觉等待而没有任何运行中调用时结束轮次则意味着会话结束。这套设计给 Agent 开发者的启发 ✅把 harness/contextbuilder/ 作为参照实现可以提炼出四条实践请求构建与持久化解耦——上下文组装是纯函数式的内存操作持久化交给 Session Store两边各自可测透明优于静默——任何对上下文的删改都应通过 Report 上报省略/截断/压缩 来源 原因这是可调试性的关键占位符模式处理异步结果——运行中的工具调用先占坑结果到达再替换模型永远看不到矛盾状态两阶段提交管理定稿边界——已定稿的前缀与未定稿的暂存区分离Commit明确划定提交点。如果你想动手实践可以从 harness/contextbuilder/contextbuilder.go 的接口定义读起再看 builder.go 的参考实现最后结合 harness/coordinator/loop.go 观察它在真实轮次中的调用位置。纯内存 报告机制的组合让模型到底看到了什么从玄学变成了可以逐条审计的工程问题——这正是 Unreal Agent Context Builder 设计中最值得借鉴的部分。【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考