面向 coding agent 的 Jev 工程学

yibie·约 10 分钟阅读

2026年9月22日9月22日

作者：基于 Diogo Almeida（TypeSafe 创始人）的设计笔记独立汇编 · 2026 年 9 月工作笔记

这份 12 页的文档值得完整读。它不是产品宣传，是一份把「coding agent 该怎么设计」从第一性原理重新推一遍的工程笔记。

它从一个挑衅性的问题开始：如果语言模型没有 KV cache，你会怎么设计一个 coding agent？

这个问题之所以有杀伤力，是因为KV cache 是今天所有 agent 被建成「只追加的对话记录」的根本原因。复用缓存前缀很便宜；一旦改动上下文早期的内容，缓存失效，模型必须重新处理改动之后的一切。这个单一的经济事实塑造了当前 agent 的几乎每一个设计决策——而且通常没人把这件事说出来。

作者管这叫「KV cache 的暴政」。把缓存想象掉，会做两件事：允许一种为 Jev 设计的、状态显式的架构，上下文是被组装的，而不是被累积的；同时揭示为什么「把简单活路由给便宜模型」这种直觉上正确的想法在实践中会失败。

一、Jev 站在哪里

Jev 不是写代码的模型，它是旁边那一层决策层。

harness 把当前应用状态（目标、上下文、规则、可用动作、之前的动作）和一个预定义问题交给 Jev，Jev 返回一个类型化答案：choice、score 或 noul，每个都带概率。然后由前沿模型、子 agent、工具和确定性代码去做实际工作。

因为输出是类型化的而不是自由文本，harness 可以验证它、施加阈值、基于它分支，而不必解析散文。

这份文档里每一个原生功能，底层都是在高频决策点上问 Jev 一个问题。每个会话被问上千次，小的决策才是杠杆所在。

二、六个症状：当前 agent 不加审视就继承的设计

症状一：路由不工作。直觉方案是让前沿模型规划、把执行交给便宜模型、再让前沿模型回来审查。作者用 Opus（$5 输入 / $25 输出每百万 token）和 Sonnet（$3 / $15）的标价算了笔账，设 X 是上下文 token、Y 是生成的输出 token、Z 是工作中额外读入的 token：

路径 1 纯 Opus：25Y + 5Z

路径 2 Opus → Sonnet → Opus：

Sonnet 载入上下文 3X

Sonnet 生成 15Y

Sonnet 读取 3Z

Opus 重新加载变化 5(Y+Z)

合计 3X + 20Y + 8Z

代入一个合理的会话形态（X=0.65、Y=0.12、Z=0.23），纯 Opus 是 4.15，路由路径是 6.19。

留在前沿模型上的成本，大约是那条本该省钱的路径的三分之二。

教训不是「路由是错的」，而是按 token 定价、而不是按上下文重建定价的路由是错的。路由只有在两个条件下才可行：harness 能给便宜模型一个小而专用的上下文（而不是完整记录），且回程不强迫前沿模型重读助手产出的一切。

症状二：工具挤占上下文。工具必须提前在系统消息里声明，带着完整的参数 schema——不管这轮用不用得上。这消耗大量上下文，而且并不产生特别聪明的工具选择。作者的工作假设是：模型在「高基数」（一次给太多工具）和「离策略工具调用」（工具的使用模式与训练时见过的不符）的某种组合上挣扎。这可能就是为什么 skills（加载一句短描述、细节延后）常常胜过裸工具列表和 MCP 服务器。

症状三：压缩存在。如果每个未来轮次都想要同一份共享状态，压缩就完全合理。笔记质疑的正是这个假设：压缩试图做通用压缩，这既难又有损。而查询感知的压缩容易得多——如果你知道下一个问题是什么，你就知道该留什么。在问题已知之前写下的摘要，一定会丢掉问题需要的东西。

症状四：子 agent 很平庸。模型并行的程度低于预期。怀疑的原因在状态管理：决定父上下文的哪些部分要传进去、每个子 agent 的发现中哪些要合并回来。当这个决策既昂贵又容易出错时，模型就会回避它。

症状五：重启存在。重启会话是对话记录漂移或损坏时的标准补救，但它把坏状态和好状态一起丢掉了。有了可寻址状态，替代方案是干净启动、按需只重新加载仍然相关的旧块。

症状六：电池之争。关于 agent 是否该内置能力的持续争论，本质是在「易用」和「强大」之间取舍。这个取舍存在，仅仅因为每块电池都永久消耗上下文。把那个成本拿掉，争论就消解了。

三、token 到底花在哪

这是全文最实用的一张表（按处理 token 占比，输入密集视角，重复读取每次计数）：

读文件内容 30-40% 最大项，文件被反复读入上下文

搜索代码库 10-18% grep、glob、列表；输出噪音大

命令输出 10-20% 堆栈和日志在失败时爆开

系统提示+工具 schema+AGENTS.md 5-12% 每轮都付的固定开销

对话重放放大器 — 为什么上面每一项都被重复计数

推理与规划 5-15% 困难调试时更高

写和编辑代码 4-10% diff 和 str_replace 很紧凑

向用户解释 2-5% CLI agent 默认简洁

最触目惊心的是倒数第二行：写代码，也就是 coding agent 存在的理由，是其中最小的开支项之一。读取和搜索占主导。

独立的分析指向同一方向：微软的 fastcontext 项目报告，在 GPT-5.4 的轨迹里，读取和搜索占所有工具调用轮次的 56.2%、占主 agent 总 token 的 46.5%。

如果这能推广，coding agent 里最大的效率收益不是更好的模型或更好的 diff 格式，而是更聪明的检索。

四、基础层：权限与工具路由（可以塞进任何现有 agent）

可编程权限。每条 agent 运行的命令都提出「它到底该不该跑」的问题。Claude 的 auto 模式用分类器回答这个。笔记提议走得更远：权限表达为对「什么允许、什么不允许」的可编程查询，而且在风险足够高时做更深的检查——比如在执行前读取 Python 或 shell 文件的内容，而不是只批准命令名。

policy "exec":

deny if command touches ~/.ssh or .env*

deny if script contents contain network egress

and task.scope != "deploy"

ask if command writes outside repo root

allow if command in read_only_set

allow if tests/ and exit code is expected

harness 作为工具路由器。不是把每个工具 schema 都暴露给模型，而是让 harness 坐在意图和调用之间。模型用纯文本描述它想干什么，harness 用一串类型化的 Jev 调用来选出最合适的那个工具（或前几名候选）并构造参数。模型永远不必在上下文里持有几百个 schema，而错误的参数类型会变成验证错误而不是静默失败。

五、元注意力：把上下文本身当成决策

这是核心提议，它去掉了「上下文是静态的」这个观念。

对每一个用户查询，harness 问 Jev 两件事：

第一，之前的上下文有多好——复用现有 KV cache 是对的吗，还是从头重建更便宜也更好？这被框定为一个显式的、成本感知的决策，而不是默认行为。

第二，如何构造一个包含所有相关的、且不含任何多余的新上下文。

最简单的形态是：对每一个上下文块做一次 noul——每次工具调用的输入、每次工具调用的输出、每一段内部推理、以及可能每一次与用户的交流。后续版本把分数换成可见性级别：

不显示 / 短摘要 / 长摘要 / 完整显示

这就是可见性阶梯：同一个块可以被隐藏、简短总结、详细总结或完整展示，取决于当前查询。这就是查询感知的压缩——压缩所缺的那个属性。

收益是：压缩背后的想法活下来了，但它的主要缺陷消失了。压缩在知道问题之前压缩一次；阶梯在知道问题之后按查询压缩。一个 2400 行的 grep 结果，对某个问题可以是十二条相关命中，对下一个问题可以是不可见的——而它从未从状态里被删除。

（作者还加了一个值得注意的视觉想法：如果 harness 能热力图显示 grep 输出里哪部分相关，它就能按预算允许的程度随意过滤那份输出。而且，笔记观察到，它看起来也会很酷。）

六、路由与子 agent 重访

一等公民的动态上下文是让路由重新可行的原因。一旦 harness 能为子任务构造一个小而相关的上下文，把这个子任务交给更便宜或更快的模型就不需要便宜模型载入整个会话，而结果可以作为被评分的块合并回来，而不是一份前沿模型必须重读的记录。

同一机制解锁了子 agent。笔记的猜测是：今天子 agent 成本的大部分，是决定传什么上下文的工作——相比之下，用户敲一条简单指令反而容易。如果构造那个上下文变得便宜且自动，子 agent 就能用得频繁得多。

它还打开了一个面向用户的控制：多花钱换更快或更好的结果，还是保守运行、尽量少花。

（两个延伸问题：极端并行——如果派发任务变得便宜，很多任务会同时跑，harness 就继承了并发系统的全部问题：同步原语、agent 间通信、多个 agent 共享状态时的写冲突。笔记建议用带锁的共享状态，而显式区分读与写让它变得可处理，因为只读任务永远不会争锁。目标去重——对 /goal 这类目标驱动的循环，在派发任何子任务前把它注册为子目标并和历史去重，已经做过或正在飞行中的工作就不会被启动两次。）

七、工具与技能，从第一性原理出发

模型无法提出一个它不知道存在的动作，所以它需要短片段来描述有什么可用。但这些片段不必住在系统消息里——它们可以在相关时动态加载。它们背后是「在需要时倾倒出可用动作的完整 schema」的能力。

把这一切绑在一起的要求是：这些东西在不再需要之后，都不能污染上下文。

三级披露：

第一级片段每个能力一行，相关时加载，数百个工具

第二级 schema 按需给出被选中的少数几个的完整参数

第三级文档为一次性查询提供的说明书

如果这能成，第二节里的电池之争就消失了：当一个内置能力在被使用之前几乎不花成本，agent 就能带着几百个工具和几千页文档发布。

作者还点出第二个好处：近乎零成本的集成是强有力的联合营销渠道，而且它们让事情「就是能用」。

八、条件化指令：AGENTS.md 的新形态

今天的 AGENTS.md 是全量加载的。笔记提议按条件加载。

改前端代码就加载风格指南；在某个子目录里工作就加载那个目录的坑文件（而且笔记建议每个子目录都该有一个）。

这像 skills，但有一个区别：skills 通常意味着「现在做这个」；条件化指令意味着「把这段记在某处」。第二种还需要一个 skills 没有的属性：免疫于压缩。一个在长会话早期加载的 skill 最终会被压缩或摘要掉；而一个绑定到条件的指令会在条件成立时被重新加载。

九、安全感知的路由

今天的路由围绕难度和成本。笔记加了第三个轴：信任。

一些通过低价供应商提供的开放权重模型比前沿 API 便宜得多，而笔记提出的担忧是：经过某些端点的数据可能不再私有。提议是给每个子任务一个「可能触碰哪些文件」的估计，把策略附着到文件类型上，并据此路由：

公开文档、开源依赖 → 开放：任意模型，最便宜的优先

应用代码 → 标准：经过审查的供应商

密钥、env、基础设施配置 → 受限：只用第一方前沿模型

专有研究代码 → 自定义：排除指定供应商

最后一行反映了一个更广的观点：难度和成本不是路由的唯一理由。一个团队可能因为自己在做模型研究而避开某家供应商的模型，或因为安全工作而避开某些供应商。一旦路由是策略驱动的，这些偏好就变成配置而不是纪律。

十、后台处理：Jev 论点在这里兑现

笔记识别出几种流行 agent 工作流里的一个共同模式：构建随工作进展而并行更新的 HTML 页面；「理解而非生成才是新瓶颈」的论点；在后台生成 eval；用几张图加极少的字解释系统的 ELI5 技能；以及让 agent 维护一个小型已部署的进度页面，带截图和笔记，可以在长任务期间从手机查看。还有一个生产模式：把线上流量镜像到候选模型，自动生成约一天的 eval，然后才决定是否切换。

它们的共同点是：在后台运行、作为正常工作流的扩展、而且都是当前代码库状态的只读函数。跨模型审查（让一家供应商的 agent 审查另一家的产出）属于同一模式。

这正是 Jev 论点兑现的地方。以 Jev 为中心的 harness 必须精确知道上下文里有什么、以及每个操作是读还是写。找出与某个代码改动相关的信息，是件不平凡的工作。如果这份检索在所有后台任务间共享、而不是每个任务重复一遍，运行它们就会便宜得多，也就能经济地跑更多。考虑到第三节的发现——检索占主导地位——共享它就是最大的单项节省。

十一、候选内置工具清单

笔记最后列了几个可以被原生集成的开源项目，每个都附了「以 Jev 为中心的 harness 会怎么用它」的设计说明：

headroom 上下文压缩器用分类器检查压缩是否保住了需要的事实

rtk 工具输出压缩第一方提示，让模型理解它

ast-grep 结构化搜索加载一次手册，生成 N 个查询，按相关性过滤

ast-outline 结构化大纲层级调用：选出要检查的子树

fastcontext 仓库探索子agent 路由到它，或用结构替代它的搜索

fff 路径与内容搜索内存索引、频率排序，长会话里比 ripgrep 快

十二、结论

coding agent 是简单的循环，而杠杆不在循环里。杠杆在于 harness 每一轮放在模型面前的是什么——而今天这个决定是由默认值做的，由一份围绕 KV cache 经济性塑造的、只追加的对话记录做的。

把缓存拿掉当作思想实验，六个熟悉的行为就变了样。路由失败是因为上下文被重新处理，不是因为便宜模型弱。工具挤满窗口是因为它们必须提前声明。压缩丢信息是因为它在问题已知之前压缩。子 agent 稀少是因为传状态很难。重启把好状态和坏状态一起丢掉。电池之争之所以存在，只是因为每个内置能力永久消耗上下文。

这些都不需要更好的模型。它需要把上下文窗口当作一件被有意组装的东西，而不是一件偶然累积的东西。