用 Pi SDK + Jev 构建自定义 Agent Harness · 干货攻略

• 链接:https://x.com/omarsar0/status/2102762406204076532
• 分类:x-tips
• 来源:X @omarsar0
• 作者:Jay
• 更新:2026-09-29
• 仓库:earendil-works/pi

这是什么

Pi SDK（earendil-works/pi）是 earendil-works 出品的 TypeScript Agent 开发工具包，包含多个可独立使用的包：

Jev（typesafe/jev，当前版本 jev-1.13）是 TypeSafe AI（2026 年 9 月 15 日出道，$40M Seed 轮）发布的首个 System One 模型。与传统 LLM 不同，Jev 不生成文本，而是接收「程序状态 + 类型化问题」，返回带校准概率的决策值（Choice / Noul / Score 三种问题类型），在一次并行计算中完成所有回答。

两者的组合：LLM 负责慢速的读写文件、写答案等生成任务，Jev 负责 Harness 环内的快速判断（路由、门控、验证），让每个步骤都可以做检查而不必担心 LLM 调用成本。

为什么值得关注

传统 Harness 靠 LLM 做中间判断——路由选模型、判断工具调用是否安全、评估答案是否够好——每一步都是一次完整的 LLM 调用，在生产环境里要么被跳过，要么成本爆炸。

Jev 的出现改变了这个等式：一次 Jev 调用的成本约为 GPT-6 Astra 的 1/300（$0.042/MTok input，output 免费），延迟 70-500ms，可以在每个工具调用、每次路由决策、每个答案检查处都跑一次，而不用心疼预算。

@omarsar0 的这篇教程（灵感来源于 LangChain 官方博客的 Building a Harness with Jev）用 Pi SDK 从零构建了一个完整的自定义 Harness，演示了 Gate / Router / Verifier 三段式架构，并提供在线 Playground 可直接改参数跑。

核验过程

官方来源

1. Pi SDK GitHub（earendil-works/pi，MIT License，GitHub 51K+ stars，截至 2026 年 9 月仍在活跃维护）
   核心包列表、@earendil-works/pi-agent-core + @earendil-works/pi-ai 的安装方式、pi.dev 文档站均可在 README 确认。

2. DAIR.AI Academy 教程（academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness）
   完整正文内容（Gate/Router/Verifier 三段式架构、示例场景：trail survey notes 文件夹管理、Setup 命令）均可直接读取。

3. Jev 官方定价（typesafe.ai）
   官网标注：$0.042 / MTok input，output 免费，延迟 70-500ms，context window 32K tokens，版本 jev-1.13。

交叉验证

原帖声称 arxiv ID 2606.30406 对应 SMELT 论文，经核验：该 arxiv ID 实为 MOPD 论文（Multi-Teacher On-Policy Distillation，Xiaomi LLM Core，2026 年 6 月 30 日），与本话题无直接关联，已在文中去除该错误引用。

上手步骤

1. 安装

npm install @earendil-works/pi-agent-core @earendil-works/pi-ai

2. 配置环境变量（OpenRouter 同时支持 LLM 和 Jev）

export OPENROUTER_API_KEY=...

Jev 有独立的端点，需指定精确版本号：

typesafe/jev-1.13

3. 三段式 Jev 决策接入

教程中的 Harness 有三个 Jev 决策点：

Gate（工具门控）

在工具调用执行前问 Jev：这个操作是否安全？

import { createAgent } from "@earendil-works/pi-agent-core";
import { createJevCaller } from "@earendil-works/pi-ai";

const jev = createJevCaller({ model: "typesafe/jev-1.13" });

const agent = createAgent({
  tools: [readFile, writeFile, deleteFile],  // 示例工具集
  beforeToolCall: async (toolCall) => {
    const decision = await jev.ask({
      state: { toolCall },
      questions: [{
        type: "noul",   // yes/no 判断
        prompt: `Is it safe to ${toolCall.name} with args ${JSON.stringify(toolCall.args)}?`,
      }]
    });
    if (decision < 0.5) throw new Error("Tool call blocked by gate");
  },
});

Router（模型路由）

根据请求类型选择不同的 LLM 处理：

const routeDecision = await jev.ask({
  state: { userRequest: input },
  questions: [{
    type: "choice",
    prompt: "Route to coding model, analysis model, or general model?",
    options: ["coding", "analysis", "general"],
  }]
});

Verifier（答案验证）

在 LLM 返回答案后，用 Jev 评估质量：

const qualityCheck = await jev.ask({
  state: { answer, task: input },
  questions: [{
    type: "score",
    prompt: "Rate the quality of this answer for completeness and accuracy (0-1)",
  }]
});
if (qualityCheck < 0.7) { /* 要求重试或降级 */ }

4. 在线 Playground

DAIR.AI Academy 教程提供实时沙箱，可直接改参数跑完整示例：
https://academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness

坑与适用边界

适用场景： - 需要在每个工具调用处做安全检查的自定义 Agent - 高频路由决策（多模型切换），不想用 LLM 每次都跑一遍 - 答案/输出质量验证，且需要带概率的量化评分

不适用场景： - 需要生成文本/代码的对话任务 → 换回 LLM - Jev 的问题类型（Choice/Noul/Score）无法覆盖的开放式判断 → 仍需 LLM - 需要超过 32K context 的判断场景 → Jev 当前上限

价格注意： $0.042/MTok input 是 TypeSafe 官方定价，第三方（如 explainx.ai、eesel.ai）均标注为「vendor-published figure, limited independent verification as of Sep 2026」。在正式生产前建议用小额预算实测一次。

Pi SDK 默认无内置权限隔离：README 明确说明 Pi 以启动进程的 USER 权限运行，需要自行容器化或用 Gondolin 等扩展做沙箱隔离。

SemIf 替代方案：教程外，另有 SemIf（Qwen3.5-4B based，logit 级直接读）可选，延迟 1.02s vs Jev 的 70-500ms。SemIf 无需微调但更慢，适合对延迟不敏感的场景。

一句话结论

用 TypeScript 写 Harness 的团队现在可以用 Pi SDK + Jev 把路由、门控、验证这些高频小决策全部自动化——每次调用成本从 LLM 的几美元降到几分钱，每个步骤都能检查，而不必因为预算跳过。