Jev：给AI编程助手装一个决策层，让Claude Code和Codex先想再做

最近调 AI Coding Agent 调得比较多，Claude Code 和 Codex 这两个命令行工具给我的感觉是：下限很高，但上限全靠“你能不能把任务说清楚”。你跟它说“帮我重构一下登录模块”，它真可能把整个文件给你重写一遍；你跟它说“看一下这个接口兼容性”，它可能扫一个文件就告诉你没问题。不是模型不行，是缺一个拿主意的人。我后来给这两个工具加了一层叫 Jev 的决策层，专管“先想清楚再动手”这一步。这篇文章我把完整的安装思路、配置过程和踩过的坑整理出来，10 分钟跟着走一遍，你也能让 Coding Agent 学会自己拿主意。

在动手之前，先聊聊我为什么要装 Jev，以及它解决的到底是什么问题。这样后面配置的时候，你才知道那些参数是干嘛的，遇到报错也知道往哪个方向查。

1. Coding Agent 为什么需要“拿主意”：先搞懂 Jev 解决的真问题

1.1 现在的 Agent 不是笨，是“不会取舍”

Claude Code 和 Codex 这类工具，本质上是把大模型的代码生成能力包装成交互式的命令行 Agent。模型本身很强，写单文件、补单测、跑命令都很利索。但任务一复杂，问题就来了：你不知道它下一步想干什么，它也不告诉你为什么这么选。

我举个例子。你让 Claude Code“给后端加个缓存”，它大概率直接开始写 Redis 封装或者加装饰器，但它不会先问你：这个缓存是针对读多写少还是写多写少的场景？数据一致性要求多高？要缓存的是查询接口还是整个业务链路？这些信息不明确，写出来的代码就是“看起来在干活，实际上可能跑偏”。

还有一个更典型的场景：你让它“重构一下订单模块”，它可能把模块里所有文件都翻出来改一遍，包括那些跟本次需求毫无关系的旧代码。你问它为什么动那个文件，它说不出个所以然。本质上，模型只知道“生成最可能的下一段 token”，它不知道如何把一个模糊目标收敛成几条候选方案，再从中选一条性价比最高的。这不是智力问题，是结构问题：缺了一个决策前置层。

打个比方你就明白了。以前的 Agent 像个特别勤快的实习生，你给一句话，它马上动手，但方向对不对它不管。装 Jev 之后，相当于给这个实习生配了个项目负责人：接手任务先不着急写码，先把目标、约束、候选方案、风险列清楚，再决定让实习生按哪条路线干。这中间多出来的“想清楚”环节，就是 Jev 存在的意义。

1.2 Jev 在技术栈里到底处于什么位置

Jev 是什么？严格说，它是一个面向 Coding Agent 的决策/规划层。它跑在 Claude Code、Codex 这类“执行型 Agent”和底层大模型之间，负责做意图识别、任务拆解、方案排序和风险标注，然后把结构化结果交给 Agent 去执行。

很重要的一点：Jev 不是用来替代 Claude Code 或 Codex 的，也不是传统的代码补全模型。它更像是一个“参谋部”。主模型负责“打仗”，Jev 负责“定作战方案”。你甚至可以把 Jev 理解为一条独立的推理链路：输入是原始任务描述，输出是一份带目标、约束、候选方案、推荐方案、风险点的结构化计划，而不是代码。

为什么要把决策逻辑单独拆出来？因为主模型的上下文窗口是有限的。你让一个模型同时干“理解意图”“拆解任务”“写实现代码”三件事，Token 消耗会暴涨，而且这三件事会互相干扰。模型在写代码的时候，很容易忘记最开始拆解出来的约束条件。Jev 把“想”和“做”分开，等于给 Agent 装了一条缓存的思维链：决策结果独立存放，随时可查，不占主模型上下文。

关于 Jev 是否开源这个问题，我直接用到的社区版是开源的，可以自己托管，也可以直接用官方 API。商业版多了团队策略模板、权限审批流一类功能，适合多人协作的团队用。我下面所有配置都是基于社区版做的，自己一个人用完全够。

1.3 装 Jev 之前和之后

光说概念你可能没感觉，我放一个对比。假设现在有一个任务：“给支付回调接口加上幂等重试机制”。

这个对比很直观。Jev 不是让 Agent“更聪明”，而是让 Agent“更稳”。它像一个强制 checklist，把人类工程师平时踩坑后才总结出来的经验，前置到了任务开始之前。

2. 10 分钟安装 Jev 到 Claude Code：完整实操

下面进入正题。我自己用的是 macOS + Node.js 环境，Windows 和 Linux 操作基本一致，只有路径和包管理器有差别。整个过程分四步：确认环境、安装 Jev、挂到 Claude Code、验证生效。

2.1 安装前要确认的几件事

装之前别急着敲命令，先确认三件事：

第一，Node.js 版本不低于 18，最好 20 以上。Jev 的 CLI 是 Node 写的，版本太老会有兼容问题。检查命令是node -v。如果你更习惯 Python 生态，Jev 也有 Python 版，但下面的命令示例我统一用 Node 版演示。

第二，Claude Code 已经装好并且能正常对话。检查命令是claude --version，能输出版本号就算就绪。

第三，准备一个独立的 API Key。Jev 官方服务的 key 可以单独申请，如果你不想用它官方服务，也可以在配置里把 provider 指向自己的模型网关。我强烈建议给 Jev 单独配一个 key，别跟 Claude Code 的主 key 混用。混用的问题在于，排查问题的时候你分不清日志里某一条调用是 Jev 发起的还是主模型发起的。分开以后，决策调用和代码生成调用的用量、延迟、错误都能分开看，省很多事。

2.2 安装与初始化 Jev

确认完环境，安装其实就一条命令：

npm install -g @jev/cli

装完以后执行初始化：

jev init

初始化会做几件事：创建~/.jev/目录，生成config.json和profiles/目录，并自动检测当前机器上装了哪些 Agent。它会问你要不要自动识别 Claude Code 和 Codex 的配置路径，这里选 yes 就行。

初始化生成的config.json长这样：

{ "provider": "jev-official", "model": "jev-prod", "apiKey": "sk-xxx", "logLevel": "debug", "timeout": 30, "cache": true }

我解释一下这几个字段：

• provider：决策模型的提供方。默认是 Jev 官方，如果你想用自定义的 OpenAI 兼容接口，改成你自己的服务地址。
• model：决策模型名称。官方模型区分不同档位，社区版默认用jev-prod，本地部署的话可以改成qwen3-coder之类。
• apiKey：独立 key，放这里。
• logLevel：调试阶段建议开debug，跑稳以后改成info。
• cache：Jev 会把相同任务的规划结果缓存起来。相同任务描述再次请求时直接命中缓存，省 Token 也降延迟。

初始化完成以后，先跑一下自检：

jev doctor

它会检查 CLI 版本、config 文件格式、API Key 连通性、以及是否检测到 Claude Code / Codex 的可执行文件。看到all checks passed就可以继续了。

2.3 把 Jev 挂到 Claude Code 上

Claude Code 的集成方式很灵活，但我实测下来最稳的是用 slash command。Claude Code 支持在~/.claude/commands/目录下放自定义命令，每个命令就是一个 Markdown 文件。我创建一个jev.md：

mkdir -p ~/.claude/commands cat > ~/.claude/commands/jev.md <<'EOF' --- description: 让 Jev 做决策规划，Claude Code 严格按计划执行 argument-hint: 任务描述 --- 先运行 `jev plan --input "$1" --json`，仔细阅读输出 JSON 中的以下字段： - objective：本次任务的最终目标 - constraints：必须遵守的约束条件 - candidate_plans：候选方案列表 - recommended_plan：推荐方案，包含具体文件、改动步骤、风险和测试策略 严格按照 recommended_plan 执行。如果 recommended_plan 中标记了 risk_level 为 high 的项，必须先停下来说明风险，不可直接执行。 EOF

这里每个字段都是有用的。objective和constraints是给 Agent 的行为定边界，防止它自由发挥；recommended_plan里给出了涉及文件和步骤，Agent 后续的每一步都应该能对应到计划中的某一项。

配置完以后，重启 Claude Code 或者在新会话里输入：

/jev 给 command_handler.py 加上超时重试，注意只能重试网络类异常

Claude Code 会先调用 Jev，Jev 返回一份 JSON 计划，然后 Claude Code 再按照推荐计划去改代码。这时候你会看到终端里多了一段结构化的计划输出，再往后 Clauaude Code 的每一步都能跟计划对得上。

如果你想让它对每个任务自动先跑 Jev，而不手动敲/jev，可以在CLAUDE.md里加一条强规则：

## 决策规则 当你收到复杂度超过 5 分钟的任务时，必须先执行 `jev plan --input "<任务描述>" --json`，拿到 recommended_plan 后才能开始写代码。禁止跳过规划直接实现。

注意这里的用词是“必须先”“禁止跳过”，要足够硬。你写“建议先跑 Jev”，Agent 大概率不会每次照做。

2.4 验证是否生效

配置完别急着上大任务，先拿一个小任务验证链路通不通。我用的测试任务是：

/jev 给 utils.py 加一个带指数退避的重试函数，只处理 ConnectionError 和 TimeoutError，其他异常直接抛出

正常情况你会看到三步：Jev 先输出 plan，Claude Code 回显“我将按照推荐计划执行”，然后才开始动文件。如果第一步就报错，说明 Jev 调用有问题，先去查~/.jev/logs/下的日志；如果第二步就没有计划直接写代码，说明 slash command 没加载成功，检查命令文件有没有放在正确的目录。

还可以用jev logs查看最近的决策记录。这条命令会列出所有过去任务的输入、输出候选方案、最终推荐方案和耗时。我习惯在刚配完的时候跑一下，确认 Jev 真的参与了决策，而不是 Agent 在自说自话。

3. 把 Jev 装到 Codex 上的另一种姿势

Claude Code 装完，Codex 那边就简单多了。但 Codex 的配置方式和 Claude Code 不一样，最大的差异在于配置文件格式：Claude Code 用 JSON，Codex 用 TOML。别小看这个差异，填错一个字段就够你折腾半小时。

3.1 Codex 的配置方式差异

Codex 的全局配置在~/.codex/config.toml。默认情况下它走 OpenAI 的模型服务，要接入 Jev，有两种思路。

第一种思路是把 Jev 当作一个独立的决策工具，让 Codex 在收到复杂任务时先调用一个本地脚本。这种做法的好处是不动 Codex 本身的模型配置，风险最低。

第二种思路是把 Jev 的本地服务注册成 Codex 的一个 model provider，让 Codex 在处理某些任务时直接把规划请求发给 Jev。这种做法更彻底，但需要 Jev 以服务模式运行，并且要处理协议兼容问题。

我推荐先走第一种，跑通以后再去折腾第二种。原因很简单：第一种改动面小，出问题容易回滚；第二种万一配错，可能导致 Codex 完全无法启动。

3.2 Jev 接入 Codex 的步骤

先写一个最小的调用脚本。Jev 提供本地服务模式，启动后暴露一个 OpenAI 兼容的/v1/chat/completions接口。先启动服务：

jev serve --port 8477

启动以后，写一个jev_codex.py：

#!/usr/bin/env python3 import json import subprocess import sys task = " ".join(sys.argv[1:]) result = subprocess.run( ["jev", "plan", "--input", task, "--json"], capture_output=True, text=True, check=True, ) plan = json.loads(result.stdout) print(json.dumps(plan, ensure_ascii=False, indent=2))

这个脚本本质上是把jev plan的输出透传给 Codex。然后在AGENTS.md里加规则：

## 复杂任务处理流程 当任务涉及多个文件、多个步骤，或存在多种实现方案时，先执行： `python /path/to/jev_codex.py "<任务描述>"` 阅读输出中的 recommended_plan，然后严格按照计划实施。

Codex 会自动读取AGENTS.md，规则优先级很高。实测下来，加这段规则后 Codex 在遇到重构类任务时，会先调用脚本拿计划，再动手。

如果你要试第二种思路，config.toml 里大致这样配：

model = "jev-planner" model_provider = "jev" [model_providers.jev] name = "Jev Planner" base_url = "http://127.0.0.1:8477/v1" wire_api = "chat" env_key = "JEV_API_KEY"

注意base_url结尾的/v1不能漏。Codex 会在后面拼具体的路径，漏了会导致 404。另外env_key要指向一个真实存在于环境变量里的 key，比如启动 Codex 之前先export JEV_API_KEY=xxx。

3.3 同时管理 Claude Code 和 Codex 的 Jev 配置

如果你两个工具都在用，最怕的就是配置漂移：Claude Code 里的 Jev 是一个 profile，Codex 里是另一个，两边规则还不一样。Jev 本身支持统一配置，在~/.jev/config.json里设默认 profile：

{ "default_profile": "coding-agent", "profiles": { "coding-agent": { "provider": "jev-official", "model": "jev-prod", "strategy": "conservative", "output_schema": "plan-v2" } } }

strategy字段我解释一下。它控制 Jev 的决策风格：conservative偏向改动最小、风险最低的方案；balanced会在改动量和长期维护性之间取折中；aggressive倾向于做更彻底的重构。团队项目我建议统一用conservative，个人项目可以按心情换。

两端共用一套配置后，Claude Code 用/jev，Codex 用jev_codex.py，底层走的都是同一个 profile，决策风格、输出格式完全一致。排查问题的时候也方便，直接看 Jev 的日志就行。

4. 让 Coding Agent “拿主意”的三个核心机制

配置都做完了，你可能会好奇 Jev 内部到底怎么“拿主意”的。我拆开讲一下核心机制，方便你后续调整参数。

4.1 意图识别：把“要我做什么”翻译成“我要做什么”

第一步是意图识别。人类说话的省略程度非常高，你说“给接口加个鉴权”，Agent 如果不追问，它根本不知道是加 Token 校验、加签名、加白名单还是加 OAuth。Jev 做的事情，是把这种模糊表述转成结构化意图。

举个例子。任务：“给订单查询接口加缓存”。Jev 会先识别出几个关键维度：

• 场景是读多写少，写入后缓存要失效。
• 查询接口的响应数据量不大，适合用本地缓存。
• 一致性要求：下单后必须能看到最新数据，所以不能只用 TTL，还要主动失效。
• 范围：只缓存订单查询接口，不碰订单创建接口。

这些信息会被 Jev 写进constraints字段，Agent 拿到以后就不会写出“整个订单模块全缓存”的跑偏代码。

4.2 任务拆解与方案排序：不再一根筋

识别完意图，Jev 会生成候选方案并排序。同样是“订单查询接口加缓存”，它会列出至少三套方案：

排序的依据不是“哪个代码写得快”，而是综合了改动范围、风险等级、未来可维护性。Jev 会在recommended_plan里给出推荐方案，并写明理由。这个理由很重要，Agent 后面如果遇到问题，可以回溯到决策层重新选择，而不是自己硬着头皮改。

4.3 风险判断与回退：拿主意也要能收得住

“拿主意”不等于“什么都敢干”。Jev 会把任务里的高风险操作标记出来，比如删除文件、迁移数据库、改动公共接口、修改鉴权逻辑。凡是风险等级为 high 的操作，recommended_plan里都会有一个requires_confirmation字段。Agent 执行到这一步会停下来，把风险输出给用户确认。

我遇到过最典型的情况是，让 Agent“优化一下数据库查询”，它直接把一个公共的 DAO 方法签名改了，结果所有调用方全部编译失败。装上 Jev 之后，这类操作会被识别为高风险，Agent 在动手前会问一句“改这个公共接口会影响 12 个调用方，是否继续？”这就把失控概率降下来了。

4.4 与主模型的分工边界

最后要强调分工。Jev 永远不直接写实现代码，它只输出计划。写代码这件事，严格交给 Claude Code 或 Codex 的主模型。

这样分有几个好处。第一，主模型的上下文窗口不被“该怎么做”的讨论占用，全部留给“具体怎么实现”。第二，Jev 的计划是独立存储的，随时可以复盘，出了问题能查到是哪一步决策导致的。第三，主模型可以专注于自己最擅长的事情，而不是一边规划一边写码，结果两边都做不好。

我自己试过把规划功能直接写进 Claude Code 的系统提示词里，让它“先思考再回答”，效果远不如独立跑 Jev。原因就是主模型没有专门针对规划做过优化，你塞给它一种新的思维模式，它反而会乱了节奏。

5. 常见问题与排查技巧实录

配置过程中一定会遇到问题。我把实际操作中踩过的坑整理成速查表，按出现频率从高到低排。

5.1 Jev 生效了但 Agent 不听

这是最让人崩溃的情况：Jev 已经输出了计划，计划写得也没问题，但 Agent 看完以后还是按自己的思路写代码。根本原因通常是规则文件里的指令力度不够。Claude Code 看到“建议参考”这种词，默认当成可选项；看到“必须”“禁止”“严格”这种词，才会当成硬约束。

解决方法是把规则改成不可协商的语气。在 Claude Code 的CLAUDE.md里可以写：

当收到任务时，如果 Jev 计划存在，你的所有文件修改必须落在 recommended_plan.affected_files 列表内。列表之外的文件一律禁止修改。

如果还不管用，再加一道保险：用PreToolUse钩子拦截修改操作，比对目标文件是否在计划列表里。不在列表里就让命令直接失败。这样就把规则从“建议”升级到了“物理强制”。

5.2 Codex 报 endpoint 错误怎么办

如果你在 Codex 里配了 Jev 的 model provider，可能会看到类似cc switch local proxy failed while handling codex endpoint /responses的报错。这个报错看起来像是网络问题，实际上很多时候是协议不匹配。

Codex 新版默认走/responses端点，而 Jev 本地服务默认暴露的是/v1/chat/completions。两边各说各话，自然握手失败。解决办法是在 Jev 启动服务时指定 wire 格式：

jev serve --port 8477 --wire-format responses

如果你用的 Jev 版本不支持这个参数，更稳妥的做法是让 Codex 走本地脚本方式，也就是上面写的jev_codex.py，绕开 model provider 配置。

5.3 响应太慢、Token 消耗翻倍

装了 Jev 以后，每次任务多一次模型调用，Token 消耗上升是正常的。但如果你发现涨得离谱，先查这几个地方：

第一，确认~/.jev/config.json里cache是true。不开缓存的情况下，每次一模一样的任务 Jev 都会重新规划，纯属浪费。第二，检查jev plan是不是带了--deep之类的深度规划参数。深度模式会生成更多候选方案，只在复杂重构时开。第三，看max_candidates设置。默认是 3，如果你调成了 5，每次多出两个方案的 Token 成本会很快累积。

5.4 多模型切换后 Jev 失效

Claude Code 支持切换不同的底层模型，比如从 Sonnet 切到 Opus。每次切换以后，你会发现 Jev 的输出没以前那么“听话”了。原因不是 Jev 出了问题，而是不同主模型对于规则文件的理解力度不一样。

解决方法是把 Jev 的规则文件独立出来，在主配置里引用，而不是每个模型各写一份。Claude Code 可以@import公共规则文件，Codex 的AGENTS.md也可以拆出子文件。总之别让规则跟模型绑定，切换模型以后重新验证一次/jev流程即可。

下面是几个典型问题的速查：

6. 我自己用下来的几点体会

调试 Jev 的那个晚上，我反复遇到一个诡异的状况：Jev 明明已经给出了正确决策，Claude Code 却还是执行了第二套方案。后来查了半天才发现，是 slash command 的规则只对交互式会话生效，一旦任务被工具链里的其他 hook 接管，规则就失效了。最后我把校验逻辑做成了一个独立脚本，挂在PreToolUse钩子里，强制比对本次要修改的文件是否在计划列表内，问题才算根治。

这件事给我的体会是，Jev 这类决策层最大的价值不是让 Agent 变聪明，而是让 Agent 不乱来。它把“做之前先想清楚”这个过程，从依赖模型的随机涌现变成了可配置、可审计、可复用的规则。你会发现 Coding Agent 从“能写代码”变成了“知道为什么写这段代码”，这个转变比多写几百行代码有价值得多。

Jev 的决策层思路还能继续扩展，比如把团队代码规范写成策略模板，让 Agent 在规划阶段就自动避开团队禁止的写法；或者把 Jev 接入 CI 机器人，让它在代码评审阶段输出风险点。我自己目前比较推荐的做法是：先在一个小项目里让 Jev 只做“方案选择”，别放开执行权，跑通机制以后，再逐步把它接进 Claude Code 和 Codex 的主流程。别指望第一版就完美，决策 profile 需要跟着你项目的实际规范反复调，这才是它真正发挥价值的地方。