★ FEATURED ARTICLE 1. 为什么要在 Coding Agent 外面套一层决策层1.1 从两个真实痛点说起用 Claude Code 和 Codex 这类 Coding Agent 干活的人大概率都遇到过两种让人抓狂的场景。第一种是过度思考。你只是让它改一个变量名它先给你分析三分钟项目架构再列一个五步计划最后才动手。等它动手的时候你已经自己改完了。第二种是决策漂移。同一个任务今天让它加个日志它直接改明天让它加个日志它反问你要不要考虑日志级别、轮转策略、输出格式。你没法预测它下一步会怎么走因为每次决策路径都不一样。这两个问题的根子不在模型能力而在决策入口没有被约束。Claude Code 和 Codex 都是通用型 Agent它们的默认行为是先理解全局再行动这在复杂重构里是优点在大量日常小任务里就是纯浪费。Jev 这个项目要解决的就是这件事在 Coding Agent 和实际任务之间插一层轻量决策层让简单任务走快车道复杂任务才进入完整推理流程。说白了就是给 Agent 装一个分流阀。1.2 Jev 到底是个什么东西Jev 本身不是一个模型也不是一个 Agent 框架。它更像是一个决策路由器夹在你和 Claude Code / Codex 之间。你给它一个任务描述它先做一次快速判断这个任务属于哪一类、需要多深的推理、该调用哪个 Agent、要不要拆步骤。判断完之后它把任务转成对应 Agent 能直接执行的指令格式再交给下游。整个过程对使用者是透明的你看到的还是我提了个需求Agent 干活了但实际链路里多了一层决策。这个设计思路其实借鉴了传统后端的网关模式。就像 API 网关不会让每个请求都打到最重的服务上而是先做路由、限流、鉴权再分发。Jev 对 Coding Agent 做的事是一样的先分类、再路由、最后才执行。1.3 适合谁来用这套东西不是给所有人准备的。如果你只是偶尔用 Claude Code 改改脚本那没必要上 Jev直接对话就行。但如果你符合下面任意一条Jev 的价值会非常明显每天有大量重复性的代码任务改配置、加日志、调格式、写测试希望这些任务不要触发完整推理同时用 Claude Code 和 Codex想统一入口、统一决策逻辑团队里多人共用 Agent需要让决策行为可预测、可复现在做 Agent 相关的二次开发需要一个可插拔的决策层我自己的情况是第二和第四条。手头同时挂着两个 Agent任务类型又杂没有统一决策层的时候切换成本很高。Jev 把这部分收拢之后日常效率提升是能感觉到的。2. Jev 的核心设计思路拆解2.1 决策分层的三个档位Jev 最核心的设计是把任务决策分成三个档位我把它叫做快、中、慢三档。快档处理的是那些看一眼就知道怎么做的任务。比如改个字符串、调个缩进、加一行 import。这类任务不需要理解项目上下文直接生成指令丢给 Agent 执行就行。快档的关键是跳过规划阶段不让 Agent 有机会想太多。中档处理需要局部上下文的任务。比如给某个函数加错误处理、给某个模块补测试。这类任务需要 Agent 读一下相关文件但不需要全项目扫描。中档会带上明确的范围限定告诉 Agent只看这几个文件。慢档才是完整推理流程。涉及跨模块重构、架构调整、依赖变更这类任务才走慢档。慢档会允许 Agent 做完整的项目理解、方案对比、分步执行。这个分层的价值在于大部分日常任务其实都是快档和中档但默认情况下它们都被当成慢档处理了。把这一层加上省下来的时间很可观。2.2 为什么不做成规则引擎有人可能会问为什么不直接写一堆 if-else 规则来判断任务类型我一开始也是这么想的试过之后发现不行。原因是任务描述的多样性远超规则能覆盖的范围。你写包含重构关键词就走慢档结果用户写把这个函数拆一下规则就失效了。你写字数少于 20 字就走快档结果用户写删掉所有 console.log字数够短但影响面很大。Jev 的做法是用一个小模型做分类而不是硬编码规则。分类模型只做一件事读任务描述输出档位和范围。它不需要理解任务本身只需要判断这个任务大概需要多深的理解。这个判断比完整推理轻得多速度快、成本低。提示分类模型不需要用最强的模型。实测下来中等规模的模型做这个分类任务准确率已经够用用大模型反而是浪费。2.3 与 Claude Code、Codex 的对接方式Jev 对接两个 Agent 的方式不太一样这是由它们各自的接口特性决定的。Claude Code 的接入相对直接它本身支持通过配置文件定义行为模式。Jev 会生成一份动态配置把决策结果翻译成 Claude Code 能理解的指令前缀。比如快档任务会带上直接执行不要规划的约束慢档任务则不加约束。Codex 的接入更偏向指令拼接。Jev 会把决策结果转成一段结构化的任务描述包含任务类型、范围限定、执行约束然后作为 prompt 的一部分传给 Codex。两个 Agent 的对接逻辑在 Jev 内部是抽象过的新增一个 Agent 只需要实现对应的适配器。这个设计让 Jev 不会被绑死在某个特定 Agent 上。2.4 决策结果的可观测性Jev 有一个我觉得很关键的设计每次决策都会留下记录。记录内容包括原始任务描述、判定档位、判定依据、实际执行结果。这个记录不是为了审计是为了调优。用一段时间之后你可以回看哪些任务被误判了然后针对性调整分类模型的提示词。我自己的记录里最初有大约 15% 的任务档位判错调了两轮提示词之后降到 5% 以下。没有这个记录你根本不知道决策层是在帮忙还是在添乱。3. 核心细节解析与实操要点3.1 任务分类的提示词怎么写分类提示词是 Jev 的心脏。写得好决策准写得烂整个系统就是负优化。我踩过的坑基本都在这。第一版提示词我写得很全面列了十几种任务类型每种都给了详细定义。结果分类模型经常在边界情况上纠结输出不稳定。后来我改成只定义三个档位每个档位给两三个典型例子准确率反而上去了。核心原则是分类提示词要窄不要宽。你不需要让模型理解所有任务类型只需要让它判断这个任务需要多深的理解。判断维度越少输出越稳。我现在的提示词结构大概是这样的你是一个任务分类器。读下面的任务描述判断它属于哪个档位。 快档不需要读项目上下文就能执行的任务。例如改字符串、调格式、加简单语句。 中档需要读少量相关文件的任务。例如给指定函数加错误处理、给指定模块补测试。 慢档需要理解项目整体结构的任务。例如跨模块重构、依赖变更、架构调整。 只输出档位名称和一句话理由不要输出其他内容。 任务描述{task}注意最后那句只输出档位名称和一句话理由。不加这句模型会给你写一段分析反而拖慢速度。3.2 范围限定的传递方式中档任务的关键是范围限定。你得告诉 Agent只看这几个文件否则它还是会全项目扫描。Jev 的做法是在分类阶段就提取出可能的文件范围。提取方式有两种一是从任务描述里直接抓文件名或路径二是让分类模型顺带输出它认为相关的文件。第一种方式准确但覆盖不全第二种方式覆盖全但可能不准。我的做法是两种都用取并集但限制数量。比如最多给 5 个文件超出的按相关性排序截断。范围限定传递到 Agent 那边时要转成明确的约束语句。比如仅阅读以下文件a.py, b.py, c.py不要扫描其他文件。这句话必须显式写出来不能指望 Agent 自己遵守。注意范围限定不是硬约束Agent 有时还是会越界。如果发现越界频繁可以在提示词里加一句如果任务需要超出范围的文件先停下来询问。3.3 快档任务的指令压缩快档任务的目标是最短路径执行。这里有个反直觉的点指令越短执行越快。我最初给快档任务写的指令很详细把任务描述、执行要求、输出格式都写全了。结果 Agent 处理这些指令的时间比处理任务本身还长。后来我把快档指令压缩到极致只保留任务核心和一句直接执行。压缩后的快档指令大概长这样直接执行以下修改不要规划不要解释 {task}就这两行。实测下来快档任务的平均响应时间从原来的十几秒降到三秒以内。但压缩有边界。涉及删除、覆盖、批量修改的任务即使判定为快档也要保留必要的确认语句。我吃过亏一个删掉所有测试文件的任务被判定为快档指令压缩后 Agent 直接执行了幸好是在测试环境。3.4 慢档任务的规划约束慢档任务反过来要给足规划空间但要约束规划的方向。默认情况下Agent 做规划时容易发散列出一堆可以考虑的方案。Jev 在慢档指令里会加一个约束先给出一个推荐方案再列最多两个备选。这样既保留了对比又不会让规划无限膨胀。另外慢档任务要显式要求分步执行。不分步的话Agent 容易一口气改完然后告诉你改好了你根本不知道它改了什么。分步执行让每一步都可检查、可回滚。3.5 决策记录的字段设计决策记录我建议至少包含这几个字段字段说明task_raw原始任务描述tier判定档位reason判定理由scope提取的文件范围agent实际调用的 Agentduration执行耗时result执行结果摘要corrected是否被人工纠正最后那个corrected字段很关键。每次你手动纠正一个误判就标记一下。积累一段时间后这些纠正样本就是调优提示词的最好素材。4. 实操过程与核心环节实现4.1 环境准备与依赖安装Jev 本身是个轻量项目依赖不多。核心依赖是一个能调用分类模型的客户端以及两个 Agent 的适配器。我用的环境是 Python 3.10 以上主要依赖包括模型调用库和配置管理库。安装过程不复杂但有几个点要注意。第一是模型调用的超时设置。分类模型调用必须设短超时我设的是 5 秒。超过 5 秒还没返回说明这次分类卡住了直接降级到中档处理不要让整个流程等下去。第二是配置文件的加载顺序。Jev 的配置分三层默认配置、用户配置、任务级配置。加载顺序是从宽到窄后面的覆盖前面的。这个顺序搞反了会出现配置不生效的问题。第三是Agent 适配器的初始化。两个 Agent 的适配器要分别初始化且要处理其中一个不可用的情况。我的做法是启动时做一次健康检查不可用的 Agent 标记为降级状态任务自动路由到可用的那个。4.2 分类模型的调用与降级分类模型的调用是整个流程的第一环也是最容易出问题的一环。我给它设计了三级降级策略。一级是正常调用。分类模型返回档位和理由流程继续。二级是超时降级。调用超过 5 秒直接判定为中档跳过分类模型的返回。中档是相对安全的默认值既不会像快档那样可能误伤也不会像慢档那样浪费。三级是失败降级。调用报错或返回格式不对判定为慢档。慢档最保守虽然慢但不会出错。这个降级链的设计逻辑是宁可慢一点不能错。分类错误导致的后果比分类慢严重得多。4.3 任务路由的完整链路一个任务从进入到执行完整链路是这样的接收任务描述做基础清洗去多余空格、统一标点调用分类模型得到档位和理由根据档位提取文件范围快档跳过这步根据档位生成对应指令模板选择目标 Agent根据任务类型和 Agent 可用性调用 Agent 适配器传入指令接收执行结果记录决策日志返回结果给调用方这个链路里第 3 步和第 5 步是最容易出问题的。第 3 步的范围提取不准会导致中档任务退化成慢档。第 5 步的 Agent 选择不当会导致任务被不擅长的 Agent 处理。我的经验是Agent 选择要基于历史成功率。记录每个 Agent 在不同任务类型上的成功率选择时优先用成功率高的。这个策略比固定路由效果好很多。4.4 指令模板的具体写法三个档位的指令模板我分别说一下写法。快档模板直接执行以下修改不要规划不要解释 {task}就这一句。如果任务涉及删除或覆盖追加一句执行前确认影响范围。中档模板任务{task} 范围仅阅读以下文件不要扫描其他文件 {scope} 要求先说明修改点再执行修改。中档模板的关键是范围限定和先说明再执行。前者防止越界后者让你有机会在修改前叫停。慢档模板任务{task} 要求 1. 先给出一个推荐方案再列最多两个备选方案 2. 分步执行每步完成后说明改了什么 3. 涉及跨模块修改时先说明影响范围慢档模板不限定范围但要求分步和说明影响。这样即使 Agent 发散你也能及时拉回来。4.5 决策日志的落地方式决策日志我建议用结构化格式存储方便后续分析。我用的是 JSON Lines每行一条记录。存储位置放在项目根目录的.jev/logs/下按日期分文件。这样既不会污染项目结构又方便按时间检索。日志写入要注意异步。同步写日志会拖慢主流程尤其是快档任务本来三秒能完成同步写日志可能变成四秒。我用一个后台线程处理日志写入主流程只负责投递。日志的保留策略也要定。我保留最近 30 天的日志更早的自动归档。归档不是删除是压缩后移到另一个目录需要时还能查。4.6 调优循环的建立Jev 上线不是终点是起点。真正让它变好用的是调优循环。调优循环的步骤是收集误判样本、分析误判原因、修改分类提示词、验证修改效果、重复。我自己的调优节奏是每周一次。每周花半小时看一遍这周的决策日志挑出被纠正的样本分析是提示词问题还是模型能力问题。提示词问题就改提示词模型能力问题就考虑换模型或加规则兜底。两轮调优之后误判率从 15% 降到 5% 以下。这个投入产出比是很划算的。5. 常见问题与排查技巧实录5.1 分类总是偏向慢档怎么办这是最常见的问题。分类模型倾向于保守把很多本该快档的任务判成慢档。原因通常是提示词里慢档的描述太吸引人。如果你把慢档描述成需要深入理解的任务模型会觉得大部分任务都需要深入理解。解决办法是给快档和中档更多正面例子让模型知道这两档也是常见情况。另外可以在提示词里加一句大部分日常任务属于快档或中档给模型一个先验。5.2 范围提取总是漏文件怎么办范围提取漏文件会导致中档任务因为找不到相关文件而退化成慢档。漏文件的原因一般是任务描述里没有明确文件名。这时候要靠分类模型推断但推断不一定准。我的做法是加一个兜底策略如果范围提取结果为空不直接降级到慢档而是让 Agent 先做一次轻量搜索找到相关文件后再限定范围。这样比直接全项目扫描快比直接降级准。5.3 Agent 不遵守范围限定怎么办范围限定是软约束Agent 有时会无视。尤其是任务描述里提到了范围外的文件时。解决办法是在范围限定语句里加明确的禁止语。比如不要阅读以下文件之外的任何文件即使任务描述中提到了它们。这句话要写得足够强硬。如果还是越界可以在 Agent 适配器层面做拦截。比如监控 Agent 的文件读取操作发现越界就中断。这个做法比较重只在越界频繁时用。5.4 快档任务执行出错怎么回滚快档任务跳过规划直接执行出错时没有中间状态可回滚。这是快档的固有风险。缓解办法有两个。一是执行前自动备份把涉及的文件复制一份到临时目录。二是限制快档任务的修改范围单次修改不超过一定行数或文件数。我自己的做法是两者都用。备份用轻量的方式只备份涉及的文件不备份整个项目。修改范围限制在 3 个文件、100 行以内超过就自动升级到中档。5.5 两个 Agent 结果不一致怎么办同一个任务交给 Claude Code 和 Codex结果可能不一样。这在慢档任务里尤其明显。处理方式取决于你的目标。如果你要的是一致性那就固定用一个 Agent另一个只做备份。如果你要的是最优结果那就两个都跑对比后选好的。我自己的做法是分任务类型。快档和中档固定用一个 Agent保证一致性。慢档两个都跑对比后选优。这样兼顾了一致性和质量。5.6 常见问题速查表问题可能原因排查方向解决方式分类偏向慢档提示词慢档描述过强检查提示词各档例子数量增加快中档正面例子范围提取为空任务描述无文件名检查任务描述加轻量搜索兜底Agent 越界范围限定语句太弱检查限定语句加明确禁止语快档出错跳过规划检查任务影响面加备份和范围限制结果不一致两 Agent 差异对比执行日志分类型固定或对比选优分类超时模型响应慢检查模型负载降级到中档日志写入慢同步写入检查写入方式改异步写入配置不生效加载顺序错检查配置层级修正加载顺序5.7 几个我踩过的坑第一个坑是分类模型用太强的。一开始我用最大的模型做分类准确率确实高一点但速度慢、成本高。换成中等模型后准确率降了不到 2%速度提升一倍多。分类任务不需要最强模型。第二个坑是范围限定给太多文件。我一开始把可能相关的文件都给上结果 Agent 读了一堆无关文件反而变慢。后来限制最多 5 个文件效果更好。第三个坑是日志记录太详细。我一开始把 Agent 的完整输出都记下来日志文件涨得飞快。后来只记摘要和关键字段日志体积降了 90%。第四个坑是没有降级策略。分类模型挂掉的时候整个流程就卡住了。加了降级链之后即使分类模型不可用流程也能继续。6. 决策层的扩展方向6.1 从三档到动态档位三档是个简化模型够用但不是最优。后续可以考虑动态档位根据任务复杂度自动决定分几档。比如简单项目可以只用两档复杂项目可以用四档或五档。档位数不固定根据项目特点调整。这个扩展的难点在于档位定义要动态生成不能硬编码。需要一套机制根据项目结构自动划分档位。6.2 决策结果的缓存同类任务反复出现时决策结果可以缓存。比如加日志这个任务第一次判定为中档后续同样的任务直接复用判定结果跳过分类模型调用。缓存的关键是任务相似度判断。完全一样的任务描述可以直接命中相似但不完全一样的任务需要做相似度计算。相似度阈值设太高会漏命中设太低会误命中。6.3 与 CI 流程的集成Jev 目前是交互式使用后续可以集成到 CI 流程里。比如 PR 提交时自动分类变更类型简单变更走快速检查复杂变更走完整检查。这个集成的价值在于让 CI 资源分配更合理。现在很多 CI 流程对所有变更一视同仁简单变更也要跑完整测试浪费资源。6.4 决策层的自我学习最终形态是决策层能自我学习。每次人工纠正都作为训练信号逐步优化分类模型。这个方向的技术难度较高需要一套完整的反馈收集和模型微调流程。但长期来看这是让决策层越来越准的唯一路径。我个人的判断是短期内靠提示词调优就够了自我学习是中长期目标。先把基础流程跑通再考虑进阶能力。7. 我个人的一些实操体会用 Jev 这套东西大半年最大的体会是决策层的价值不在决策本身而在决策的稳定性。一开始我追求的是决策准确率想让分类模型每次都判对。后来发现这不可能总会有边界情况判错。真正重要的是判错的时候系统不会崩能降级、能纠正、能记录。另一个体会是不要过度设计。我最初想做一个很复杂的决策系统支持多级路由、动态权重、自动学习。结果做了一半发现最简单的三档分类加降级链已经解决了 80% 的问题。剩下的 20% 用人工纠正就够了不值得为它做复杂系统。最后一个体会是记录比优化重要。没有决策记录你根本不知道系统哪里有问题。有了记录优化方向自然就出来了。我建议任何做类似系统的人先把记录做扎实再谈优化。这套东西后续还能怎么扩展我还在摸索。目前比较确定的方向是缓存和 CI 集成这两个的投入产出比看起来最高。自我学习那条路我暂时不碰等基础流程再稳定一些再说。
阅读完成 · 觉得有帮助？
