企业官网建设流程全解析

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 决策记录的字段设计

决策记录我建议至少包含这几个字段：

最后那个corrected字段很关键。每次你手动纠正一个误判，就标记一下。积累一段时间后，这些纠正样本就是调优提示词的最好素材。

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

Jev 本身是个轻量项目，依赖不多。核心依赖是一个能调用分类模型的客户端，以及两个 Agent 的适配器。

我用的环境是 Python 3.10 以上，主要依赖包括模型调用库和配置管理库。安装过程不复杂，但有几个点要注意。

第一是模型调用的超时设置。分类模型调用必须设短超时，我设的是 5 秒。超过 5 秒还没返回，说明这次分类卡住了，直接降级到中档处理，不要让整个流程等下去。

第二是配置文件的加载顺序。Jev 的配置分三层：默认配置、用户配置、任务级配置。加载顺序是从宽到窄，后面的覆盖前面的。这个顺序搞反了会出现配置不生效的问题。

第三是Agent 适配器的初始化。两个 Agent 的适配器要分别初始化，且要处理其中一个不可用的情况。我的做法是启动时做一次健康检查，不可用的 Agent 标记为降级状态，任务自动路由到可用的那个。

4.2 分类模型的调用与降级

分类模型的调用是整个流程的第一环，也是最容易出问题的一环。我给它设计了三级降级策略。

一级是正常调用。分类模型返回档位和理由，流程继续。

二级是超时降级。调用超过 5 秒，直接判定为中档，跳过分类模型的返回。中档是相对安全的默认值，既不会像快档那样可能误伤，也不会像慢档那样浪费。

三级是失败降级。调用报错或返回格式不对，判定为慢档。慢档最保守，虽然慢但不会出错。

这个降级链的设计逻辑是：宁可慢一点，不能错。分类错误导致的后果比分类慢严重得多。

4.3 任务路由的完整链路

一个任务从进入到执行，完整链路是这样的：

1. 接收任务描述，做基础清洗（去多余空格、统一标点）
2. 调用分类模型，得到档位和理由
3. 根据档位提取文件范围（快档跳过这步）
4. 根据档位生成对应指令模板
5. 选择目标 Agent（根据任务类型和 Agent 可用性）
6. 调用 Agent 适配器，传入指令
7. 接收执行结果，记录决策日志
8. 返回结果给调用方

这个链路里，第 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 常见问题速查表

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 集成，这两个的投入产出比看起来最高。自我学习那条路我暂时不碰，等基础流程再稳定一些再说。