跳到主要内容
AI教程

使用 JevHarness 构建快速、任务专用的决策流水线

了解 JevHarness 如何将任务观测转换为结构化、低延迟的决策。本教程涵盖其架构、Claude Code 和 Codex 的安装、已归档的 Pokémon 示例、任务专用 harness 的创建、评估驱动的改进、运行时要求、凭据、追踪记录，以及冻结已验证 harness 的技术。

AI我搜编辑部阅读约 15 分钟
使用 JevHarness 构建快速、任务专用的决策流水线

JevHarness 的功能

JevHarness 可帮助创作型 LLM 为 Jev 创建特定任务的决策框架。该框架将允许的观测结果转换为有用特征，构建结构化的 Jev 问题和标准，并将答案组合成合法的任务动作。

其核心理念是将高成本的策略开发与日常执行分离：

在开发期间进行深度推理。冻结策略。让 Jev 快速做出模糊决策。

在开发期间，LLM 可以修改框架代码、问题、图、状态、标准和记忆。选择并冻结框架后，运行时决策会使用固定逻辑及其 Jev 调用。创作型 LLM 无需再次为每个动作进行完整推理。

因此，JevHarness 适用于这样的任务：代码可以计算可靠事实，但部分决策仍具有上下文依赖性或存在歧义。例如，代码可以确定合法动作并计算数值特征，而 Jev 则判断哪个可用动作最符合特定任务标准。

架构与职责边界

JevHarness 将受信任的任务适配器与决策框架分离。该边界可防止框架修改自身奖励或访问隐藏的任务状态。

  • 任务适配器：负责观测结果、合法动作、副作用和评分。
  • 框架：负责特征构建、Jev 判断和决策逻辑。
  • 环境：执行动作并返回受信任的结果或奖励。
  • 创作型 LLM：在开发期间以及可选的反思过程中创建或修改框架。

经过验证的 PipelineSpec 会通过 PipelineRuntime 执行。选定后，流水线可以与其规格、运行时、评估器和声明的任务资源一同冻结。

主要功能

结构化 Jev 判断

Jev 支持 choice、score 和 noul 答案类型。一个请求可以包含多个具名问题，彼此独立的图节点可以并发执行。

明确的策略表示

策略会保存在代码、计算特征、状态、指令、标准、记忆和控制流中。这样，决策过程变得可检查且可复用，而不是停留在创作对话内部。

完整的执行轨迹

反思可以接收所选回合的完整记录，包括观测结果、决策、节点输入和输出、Jev 问题与答案、记忆以及失败信息。无损去重可减少重复内容。如果反思输入超过配置的字节限制，系统会将其归档并拒绝，而不是静默截断。

可选的基于奖励的改进

可选的 GEPA 集成会从实例前沿中选择父项，在同一训练批次上比较每个父项与提案，并在 Eval 上评估已接受的提案。它会记录实际的祖先关系，包括被拒绝的提案。

可检查的冻结产物

冻结会保留所选框架及其声明的依赖项。包含 Jev 节点的冻结框架在运行时仍需要 Jev。还需注意，托管模型别名并不能保证未来服务商的行为保持不变，因此存储的响应与新发起的调用可提供不同程度的可复现性。

前置条件

根据你想运行的内容选择相应要求：

  • 归档网站：Node.js 和现代浏览器。无需模型凭据、游戏引擎或 Python 沙箱。
  • Python 项目：Python 3.11 或更高版本。
  • 函数式 Python 节点：受支持的 macOS 原生沙箱。如果无法隔离，执行会安全失败。
  • 版本 2 表达式和 Jev 流程：这些功能不会启动函数式 Python 工作进程。
  • 实时 Jev 调用：受支持的服务商账户及相应的 API 密钥。
  • 可选的创作和反思：已配置的 Proposer，使用本地 Claude CLI、OpenAI、Azure 或 Anthropic 端点。

在 Claude Code 中安装技能

最快的 Claude Code 设置方式是将仓库添加为插件市场、安装插件，然后重新加载插件。

/plugin marketplace add https://github.com/TianyuCodings/JevHarness.git
/plugin install jev-harness@jevharness
/reload-plugins

安装插件会下载技能及其参考资料，但不会安装 Python 依赖或配置模型凭据。如果仓库是私有的，GitHub 身份验证必须已经可用，且你的账户必须拥有读取权限。

在 Codex 中安装技能

在提供内置 skill-installer 的 Codex 宿主中，直接请求从仓库安装：

$skill-installer Install the jev-harness skill from https://github.com/TianyuCodings/JevHarness/tree/main/skills/jev-harness

在后续回合中使用该技能。如果 Codex 没有立即发现它，请重新启动会话。

手动安装

你可以为 Claude Code、Codex 或两者手动安装技能。将 /path/to/your-project 替换为现有项目目录。

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
python3 scripts/install-skill.py --target both --scope project --project /path/to/your-project

这会在 .agents/skills/jev-harness/ 创建 Codex 的项目级安装，并在 .claude/skills/jev-harness/ 创建 Claude Code 的项目级安装。使用 --target codex 或 --target claude 可只安装其中一个。

如需在多个项目中使用的用户级安装，请运行：

python3 scripts/install-skill.py --target both --scope user

个人安装位置为 ~/.agents/skills/jev-harness/ 和 ~/.claude/skills/jev-harness/。安装程序不会覆盖已有的其他安装版本。如果未发现该技能，请重启代理会话。

探索已归档的 Pokémon 示例

随附的 Pokémon 示例提供了一次已归档的运行记录、一个选定的 harness、可浏览的演进树、完整的决策记录、被拒绝的提案，以及与 Jev 答案同步的回放重点。浏览此归档不会发起模型请求，也不会开始游戏。

  1. 克隆代码仓库。
  2. 构建网站。
  3. 启动本地预览服务器。
  4. 在现代浏览器中打开网站。
git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
node website/build.mjs
node website/preview.mjs --port 8768

打开 localhost:8768。战斗动画会从官方 Pokémon Showdown 渲染器下载资源。已归档的战斗日志会保留在浏览器中，不会上传到回放服务器。

报告中的 Pokémon 结果显示，经过五轮反思后，Eval 胜率从 25%，即 12 场中的 3 场，提高到 75%，即 12 场中的 9 场。搜索保留了第三轮候选项作为最佳 harness。这一结果是在选择 Eval 数据集上测得的，不应视为对未见过的游戏性能的独立估计。

理解一个基本决策

harness 会编写一个特定于任务的 Jev 请求，其中包含 state、命名的 questions、答案 type，以及用于评判可用操作的 instructions 和 criteria。

在记录的 Pokémon 示例中，harness 计算出 Slowbro 很可能在伤害竞赛中输给 Gastrodon。它提供四个合法选项，包括三个招式和换下场换上 Scizor。操作问题使用 choice 类型，并要求 Jev 严格返回一个列出的操作 ID。

{
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "选择最有可能赢得整场战斗的单个操作，而不只是本回合。",
      "criteria": {
        "switch:2": "换上 Scizor；换人会让对手获得一次免费攻击",
        "move:2": "Psychic；大约需要命中 3 次才能击倒目标",
        "move:3": "Ice Beam；大约需要命中 4 次才能击倒目标",
        "move:4": "Slack Off；预计受到的伤害超过当前 HP"
      }
    }
  }
}

Jev 选择了 switch:2，操作选择概率为 0.72，harness 接受了这一选择。该数值用于比较列出的操作，并不表示玩家有 72% 的概率赢得战斗。

完整的记录请求、答案、时间信息和来源信息可在 Pokémon 第 12 回合的 JSON 记录中查看。

构建你自己的 Harness

你不需要手写所有 Jev 指令和评判标准。调用已安装的技能并描述任务，然后让编码代理收集所需的契约细节。

Claude Code 插件调用

/jev-harness:jev-harness 构建一个将支持工单分配给正确团队的 harness。
先澄清我的输入、合法操作、示例、成功标准和预算。
如果我们有可靠的奖励信号，请加入评估和反思优化。

独立 Claude Code 调用

/jev-harness 构建一个将支持工单分配给正确团队的 harness。
先澄清我的输入、合法操作、示例、成功标准和预算。
如果我们有可靠的奖励信号，请加入评估和反思优化。

Codex 调用

$jev-harness 构建一个将支持工单分配给正确团队的 harness。
先澄清我的输入、合法操作、示例、成功标准和预算。
如果我们有可靠的奖励信号，请加入评估和反思优化。

该技能应先澄清任务，而不是立即生成流水线。你可以预期它会收集以下信息：

  • 允许任务观察到的内容以及隐藏状态的边界。
  • 合法操作以及操作的验证方式。
  • 具有代表性的示例和可用数据。
  • 成功标准、奖励或评估流程。
  • 运行时和隔离要求。
  • 凭据和提供商可用性。
  • 实验预算和优化资源。

契约明确后，代理即可构建并验证 harness。如果存在可靠的反馈，并且你请求进行优化，它可以在冻结所选结果之前，使用轨迹和奖励进行反思。

配置 Jev 凭据

JevHarness 支持两种有文档说明的 Jev 传输配置：

  • Vercel AI Gateway： 创建 JevClient(transport="vercel")，并设置 AI_GATEWAY_API_KEY。
  • 直接使用 TypeSafe： 创建 JevClient(transport="typesafe")，并设置 TYPESAFE_API_KEY。

提供商适配器无法保证你的账户可以使用每个模型或端点。请将凭据存储在环境变量或被忽略的本地 .env 文件中。切勿将凭据放入任务观察结果、追踪记录或冻结的构件中。

评估和改进 Harness

反思是可选的。只有在你拥有可信的奖励或评估方法时才使用它。一个实用的工作流程是：

  1. 定义任务边界。 将隐藏状态、评分、合法动作验证和副作用保留在受信适配器中。
  2. 创建基线测试框架。 在代码中计算可靠特征，并将 Jev 保留用于依赖上下文的判断。
  3. 验证流水线。 确认 PipelineSpec 和运行时满足任务契约。
  4. 收集完整轨迹。 保留观测、节点输入、输出、问题、答案、记忆、失败和奖励。
  5. 提出修订方案。 让编写 LLM 检查证据，并修订代码、提示词、图结构或记忆。
  6. 公平比较。 使用相同的训练批次比较父版本和提案版本。
  7. 评估已接受的提案。 运行完整的 Eval 评估，并保留实际的候选祖先关系，包括被拒绝的提案。
  8. 冻结选定的测试框架。 将胜出的规范绑定到其运行时、评估器和声明的任务资源。

明确区分训练证据和 Eval 选择结果。如果使用 Eval 选择候选方案，应将其报告为选择性能，而不是对未见任务性能的无偏估计。

延迟与并发

在已存档的 Pokémon Eval 运行中，选定的测试框架完成一次完整决策的中位时间为 568 毫秒。单个 Jev 请求的中位耗时为 269 毫秒。初始测试框架的完整决策中位时间为 678 毫秒。

  • 初始测试框架的完整决策： 中位数 678 ms，P95 为 1,495 ms，共 238 次决策。
  • 选定测试框架的完整决策： 中位数 568 ms，P95 为 657 ms，共 113 次决策。
  • 选定测试框架的单个 Jev 请求： 中位数 269 ms，P95 为 348 ms，共 226 个请求。

完整决策时间包括特征计算、并行 Jev 调用和最终动作选择。单个请求时间包括客户端和网络开销。并行调用的耗时彼此重叠，因此不应将它们相加。战斗模拟以及编写或反思时间不包含在这些决策测量中。

这些已存档的观测排除了本地响应缓存命中，但它们并不是与每个运行时决策都由 LLM 完成的方案进行的受控基准测试。

高级技巧

先计算事实，再请求判断

对于合法动作、数值估计、阈值和派生状态等事实，使用确定性代码或表达式。向 Jev 提供聚焦的状态和明确的标准，让它处理剩余的模糊选择。

使动作标准具体明确

使用与任务相关的证据描述每个可用动作。在 Pokémon 测试框架中，标准包括剩余生命值、伤害估计、速度、击倒所需回合数，以及切换时放弃一次免费攻击的代价。

在确实独立的地方使用并行节点

独立的图节点可以并发运行，多个问题也可以共享一次请求。组织图结构以利用这一点，同时不要引入任务并不需要的依赖关系。

正确检查概率

选择概率用于根据请求对所提供的选项进行排序。除非评估器另行确立了这种含义，否则不要将其重新解释为整体任务成功率的校准概率。

保留完整的失败记录

失败可以揭示无效假设、缺失观测和脆弱标准。将失败与成功决策一起保存在轨迹中，使反思能够获得完整证据。

避免静默截断

配置合理的反思字节上限。JevHarness 会归档并拒绝超大的反思输入，而不是截断它们。这能保护证据的完整性，但要求你适当规划实验规模。

区分冻结的逻辑与冻结的提供商行为

冻结测试框架会固定选定的流水线和声明的资源，但托管模型别名可能会随时间变化。当精确的历史检查很重要时，应保留已记录的响应，并将新的提供商调用视为不同的可复现性条件。

使用仓库地图

  • auto_jev/ 包含规范验证、并行运行时、Jev 传输、反思、GEPA、存储和冻结功能。
  • examples/pokemon/ 包含受信战斗适配器、带种子的本地引擎桥接、测试框架和演示代码。
  • examples/pokemon/sample/ 包含选定的测试框架和整理后的网站存档。
  • docs/ 包含任务编写材料、已记录的 Jev 调用、视频和屏幕截图。
  • skills/jev-harness/ 包含用于编写特定任务测试框架的编码代理说明。
  • website/ 包含只读演示和部署适配器。

结论

JevHarness 将由 LLM 开发的策略转化为明确且可检查的运行时逻辑。首先定义严格的任务边界，让该技能构建并验证流水线；如果希望通过反思实现改进，则使用完整轨迹和可信奖励。选定候选方案后，将其冻结，使常规决策能够使用其中的代码和聚焦的 Jev 判断，而无需每次动作都调用编写 LLM。