推理引擎约束下的 Agent 框架设计

来源：X @ashfold

Model Infra 的能力决定了 Agent Harness 的上限：框架的性能与成本不由应用层代码主导，而受推理引擎物理约束限制 ^[0]。多数 Harness 把模型 API 当黑盒：发送 messages、接收 responses、拼装 tool call，然后在应用层进行“优化”——动态注入 system prompt、按场景切换 tool schema、手动裁剪对话历史 ^[0]。这些操作在 API 层看似合理，但进入推理引擎后，每一步都可能破坏缓存、增加成本、降低解析可靠性 ^[0]。模型基础设施本身是一组可编程原语，而非不可拆分的黑盒：Translator 的 availability() 静态方法返回给定配置下 AI 模型的可用性枚举值 ^[20]；prompt 式调用直接把上下文交给模型 ^[10,11]；真实项目会将“检查后端模型配置（api_key / api_base / 模型可用性）并查看服务日志”纳入 Harness 工程流程 ^[17]。

Agent 每轮循环中，Harness 需要完成四件事：拼上下文、发请求、解析响应、执行工具，然后将工具结果拼回上下文进入下一轮 ^[0]。这个环路受到四个硬约束：缓存存活周期、缓存命中率、历史 token 序列的稳定性、解析结果的确定性 ^[0]。下文按这四个约束展开。

冷启动与 KV Cache：物理内容与三级存储

第一轮请求的所有 input token 均为冷数据，推理引擎执行全量 prefill，TTFT 取决于 prompt 长度和模型规模 ^[0]。若第二轮请求的前缀 token 序列与第一轮完全一致，引擎直接复用上一轮计算的 K、V 矩阵，只处理增量部分 ^[0]。KV cache 的作用是避免在解码阶段重复计算键和值的投影 ^[14]。类比洗衣房：第一缸放水加液开转是 prefill，5 分钟内追加衣物是 cache hit，超时或换机器则需重新开始 ^[0]。

缓存中物理存储的内容：经典 transformer 图景下，自回归解码时模型需要将所有输入 token 的键值张量存放在 GPU 内存中，K 提供匹配标准、V 提供信息内容 ^[15]。公式“K = embeddings × WK、V = embeddings × WV”是对此图景的简化描述 ^[0]——现代架构已将其进一步拆分：降低 KV cache 的内存与计算开销是近年研究重点，MQA 等共享键值方案是代表性方向 ^[16]；潜变量注意力不再缓存完整 K 和 V，而是压缩为低维潜变量，推理时用上投影矩阵恢复 ^[13]。

缓存存放位置取决于部署架构。多数服务商和自建集群使用 vLLM 或 SGLang，二者均实现 prefix caching——vLLM 的 paged attention 是其内存管理基础，SGLang 对应 RadixAttention ^[4]。缓存分为三层：GPU HBM 延迟最低但容量有限（以一台 H200 约 141GB HBM、跑 GLM-5.2 级别模型为例，扣除权重后剩余容量约够存十几个活跃用户的上下文 ^[0]）；CPU DDR 容量大但读写慢，HBM 过期后可转移至此，命中时需多一次拷回 GPU 的传输开销；NVMe SSD 或分布式存储将冷缓存落盘持久化，恢复延迟最高 ^[0]。服务商的缓存 token 定价对应这三个层级，离 GPU 越近折扣越大 ^[0]。KV cache 的内存占用是推理集群的第一瓶颈，有工程指南提出的优化目标是将单个用户占用从 42GB 压缩到 6GB 以下 ^[5]。

“GPU 热缓存通常 5 分钟”并非随意设定——有论文在公有云 GPU 集群上实验验证了 5 分钟量级的窗口 ^[3]；也有服务商在 H200 + vLLM 0.24.0 上实测 prompt caching 的成本拐点 ^[7]。但 TTL 只是服务商的承诺上限，实际命中受容量限制：机器满载时，新请求会逐出旧缓存，高峰期缓存可能仅存两分钟，窗口是概率事件而非定时器 ^[0]。跨机场景下，只有调度系统采用 prefix affinity routing，将同一用户的连续请求路由到同一组机器，A 机算好的 K、V 才能被 B 机复用 ^[0]。

什么在破坏前缀

前缀匹配要求 token 序列严格一致：system prompt 中若写入“当前时间：2025-07-15 14:30:22”，每轮变化会导致 token 序列自此行起与上轮不匹配，其后所有历史的 K、V 全部失效 ^[0]。常见破坏操作包括：动态时间戳、用户 ID、workspace 路径；按用户意图切换 system prompt；tool schema 字段顺序变化（许多 JSON 库不保证 key 顺序）；thinking 内容被删减、重排或转义；模型版本升级导致 chat template 变化；图片占位符格式不一致 ^[0]。

最隐蔽的一种：有些服务商通过向 system prompt 注入指令实现 thinking_effort 参数，修改参数值会改变注入指令文本，token 序列随之变化，缓存失效 ^[0,8]。限定“有些服务商”——thinking_effort 作为公开参数确实存在（Anthropic 将扩展思考简化为 thinking 与 thinking_effort，取值 low/medium/high ^[12]），但哪些服务商采用 system prompt 注入以及具体实现机制，没有公开资料说明 ^[9]。部分服务商提供分层前缀缓解，如 DeepSeek 在 message 边界建立子前缀，整段历史失配后可退回前面几个完整 message 的缓存——前提是 Harness 保持 message 边界和角色稳定 ^[0]。

本地执行在偷缓存窗口

缓存窗口约 5 分钟 ^[0,3]，这段时间内需完成解析响应、执行工具、拼装结果、发起下一轮请求 ^[0]。工具若依赖 MCP Server，每次调用需初始化本地进程、启动 server、建立连接，从数秒到十几秒的启动时间直接占用窗口；工具链长时，最后一轮请求到达时缓存已过期 ^[0]。工具执行超过 6 分钟，推理引擎侧已变成冷机器 ^[0]。素材作者承认当时未意识到本地执行时间也属于推理性能预算 ^[0]。

解析一致性：环路的可调试性

模型输出经 parser 拆分为 thinking、content、tool call；启用 interleaved thinking 时，模型在思考与工具调用间切换，parser 依靠特殊 token 和状态机分辨片段 ^[0]。上一轮 thinking 回传时若标签字符顺序错误、开闭标记缺失、thinking 与 content 被交换，parser 可能解析错本轮 tool call，错误参数被执行，错误信息塞回上下文，导致下一轮错误叠加 ^[0]。这类错误在 JSON 层面合法，只有对照原始 token 序列和 parser 状态机才能定位断裂点 ^[0]。服务商响应中混有用户可见文本、工具参数、reasoning 内容、parser 中间态、调试字段、安全过滤标记，直接塞回下一轮 messages 会污染协议 ^[0]；素材采用三层分离——展示给用户的、回传给模型的、进日志审计的——互不干扰 ^[0]。

上下文编译：让 token 序列贴近训练分布

缓存之外，上下文拼装还需考虑模型是否愿意认真读取。给 tool call 套格式提示、将多轮历史压成摘要但语体与原意不符、在 system prompt 中用大写、星号、emoji 强调指令——这些格式标记与 Chat Template 预设的特殊 token 叠加，使模型看到的 token 序列偏离训练分布 ^[0]。tool schema 本身也需注入 prompt 以告知模型可用能力 ^[19]。更隐蔽的是模型内置的 tool call parser，对 thinking tag、tool call tag、content 段的包裹方式有严格约定；Harness 手工拼接标签（如自行书写 <thinking> 开闭标记、合并多段思考），任何嵌套、顺序、换行与 parser 预期不一致，都会导致本轮 tool call 输出偏离，错误回灌并逐轮叠加 ^[0]。模型不会报错，只会照常生成，但内容越来越偏离 ^[0]。因此上下文拼装应尽量交由 Provider Adapter，依据特定模型版本的 Chat Template 和 parser 约定生成请求视图，注入内容放在已有消息结构之内，不绕过 template ^[0]。

稳定下来的做法

稳定前缀：system prompt 在请求周期内保持不变，时间戳、goal mode、workspace 以追加式 addon 形式按预定义层级后插；system prompt 只定义长期规则 ^[0]。
Tool call 异步执行：同步循环会迫使模型等待最慢的工具，超过缓存窗口；每个工具调用异步派发，结果按协议汇聚，长任务通过通知或 continuation 处理，不长期占用主循环 ^[0]。
Fork 不原地修改：compaction、sidechat、安全检查从主 transcript 某位置 fork 独立运行，仅将决策结果合并回来，主历史不可变 ^[0]。
历史只追加：所有事件以不可变记录追加——用户输入、实际请求、原始响应、解析后的 turn、工具调用与结果、compaction、correction；下一轮请求视图从事件链确定性生成，便于精确回溯 ^[0]。
Compaction 一次压缩到位：频繁小幅摘抄会导致语义损失，应在 checkpoint 边界做一次完整压缩，保留未完成任务、关键约束、工具状态、对象引用，压缩结果作为新 checkpoint，原始记录保留 ^[0]。

判断环路是否健康

关注四组指标。缓存：cached input tokens 占比、不同轮次命中分布、工具执行时长与缓存失效的相关性、compaction 前后输入成本差。一致性：transcript 回放成功率、请求 hash 稳定性、parser 在线离线解析一致率、tool call 解析失败率。体验：TTFT、单轮完整循环耗时、工具异步省下的墙钟时间。成本：每个成功任务的总 token 成本、compaction 自身成本与后续节省、fork 辅助模型的性价比、解析失败与重试的浪费 ^[0]。

素材以一句话收束：Harness 的工程质量最终落在缓存命中率上，缓存命中率取决于前缀稳定性，前缀稳定性取决于上下文编译逻辑，编译逻辑取决于对推理引擎工作方式的理解 ^[0]。