Pi Jev Router

English · 研究与 Bifrost 对比 · 设计与边界 · 验证记录

为 Pi Coding Agent 开发的任务边界路由扩展。Jev 判断任务档位、上下文是否充分和潜在后果；程序根据你声明的模型能力、Pi 当前可用模型、上下文容量、价格估算和故障状态决定是否换模型。

重点解决连续编程会话中的三个问题：“继续”不应被当成新任务降档；相似措辞不等于相同任务；便宜模型接手长上下文未必更便宜。

默认 shadow，只展示建议；默认关闭 Jev 网络调用。自动模式需要显式开启。本项目不自动重放失败任务，不负责派生子 Agent，也不压缩或删除对话历史。

相比直接逐轮分类，多了什么

能力	实现
任务边界	首次任务及 /route new 才考虑重新分类；续接保持当前模型
明确的上下文	可用 /route brief 提供任务摘要；不暗中上传历史或工具输出
可放弃判断	unknown、低 confidence、上下文不足时保留合格的当前模型
独立后果判断	Choice 不直接决定权限；单独 Noul 与显式最低档位共同约束路由
精确缓存	内存哈希覆盖完整请求、问题版本和策略；不做模糊匹配、不落盘提示词
实际可用性	遵守 Pi 可用模型和 --models 范围；使用准确 provider/model，无子串猜测
能力筛选	工具支持声明、推理能力、当前/历史图片、上下文与输出空间
换模成本	使用价格和最近观察到的缓存读取比例估算，未知价格不冒充免费
防止来回切换	任务内保持、换模次数上限、降档等待、手动选模自动 pin
故障恢复	持久化熔断、进程间锁、恢复试用租约、迟到结果校验
可解释	preview、explain、doctor、stats；提案与实际模型变更分开记录
验证	单元测试、真实 Pi RPC + 本地 SSE 服务测试、真实 Jev 与离线策略重放

这是针对这些缺口的独立实现，不是 Bifrost 的完整功能替代，也尚未证明它在真实编程任务上更便宜或更准确。具体对比与源码依据。

安装与第一轮使用

要求 Node.js 22.19+，Pi 0.84.2–0.86.x。已在 0.84.2 与 0.86.1 上执行真实宿主测试。新增路由运行代码只依赖 Node 标准库和 Pi 提供的扩展 API。

推荐通过 GitHub 安装到 Pi，再从实际工作的项目目录启动：

pi install git:github.com/win4r/pi-jev-router
pi

已运行的 Pi 会话需要重新启动才能加载新扩展。安装后依次执行 /route init，编辑生成的模型配置，再执行 /route reload 和 /route doctor；具体配置与 Jev 启用方式见下文。

如果需要阅读、修改源码或运行测试：

git clone https://github.com/win4r/pi-jev-router.git
cd pi-jev-router
npm ci --ignore-scripts
npm run typecheck
npm test
npm run test:pi

在你实际工作的项目目录临时加载，替换成源码的实际绝对路径：

pi -e /path/to/pi-jev-router/index.ts

需要持久安装时使用 Pi 的本地包安装：

pi install /path/to/pi-jev-router

不要同时加载本项目和 Bifrost；检测到 /bifrost 时会暂停本项目的自动换模。

在 Pi 中：

/route init

它创建新的 .pi/jev-router.json，不覆盖已有文件、不探测付费模型。初始只列当前模型，放在 frontier，tools 为 false。这是待确认的配置起点，并不代表当前模型已被评为高能力或已验证工具支持。参照 完整配置示例，按自己的模型实测能力分配档位，并确认 tools 字段；未确认工具支持的候选不会接手有工具的任务。

{
  "version": 1,
  "mode": "shadow",
  "models": [
    { "id": "YOUR_PROVIDER/YOUR_FAST_MODEL", "tier": "quick", "tools": true },
    {
      "id": "YOUR_PROVIDER/YOUR_GENERAL_MODEL",
      "tier": "general",
      "tools": true
    },
    {
      "id": "YOUR_PROVIDER/YOUR_STRONG_MODEL",
      "tier": "frontier",
      "tools": true
    }
  ],
  "classifier": { "enabled": false }
}

示例中的模型 ID 是占位符，不是真实模型。以 Pi 的 /model 列表为准，使用完整的 provider/model ID。一个模型只属于一个档位；模型分组是你的策略，不是 Jev 对模型能力的测评。

配置来源：显式 --jev-config PATH 优先；否则读取受信任项目中的 .pi/jev-router.json，再退回 $PI_CODING_AGENT_DIR/jev-router.json（默认 ~/.pi/agent/jev-router.json）。完整替换，不做多层合并。未知字段、重复 ID、非法数值会报错。

修改后执行 /route reload，再用 /route doctor 检查已配置模型是否可用。

启用 Jev

从父进程提供 TYPESAFE_API_KEY。下面使用隐藏输入启动 Pi，Key 不进入命令参数或文件：

python3 - <<'PY'
import getpass, os
os.environ['TYPESAFE_API_KEY'] = getpass.getpass('TypeSafe API key: ')
os.execvp('pi', ['pi'])
PY

此命令适用于前面已经安装的扩展；仅使用源码临时加载时，在参数列表中追加 '-e', '/path/to/pi-jev-router/index.ts'。

然后在 Pi 中：

/route jev on
/route preview 给现有列表增加搜索和分页，并补充组件测试
/route explain

preview 直接展示预览结果，可能调用 Jev，但不切模型、不占用模型恢复租约、不启动执行模型，也不填入分类缓存。explain 展示最近一次实际输入的路由记录，不会被 preview 覆盖。

确认配置符合预期后开启自动模式：

/route auto
/route new
给现有列表增加搜索和分页，并补充组件测试

Jev 固定使用 jev-1.13.0。发送任务原文、可选 briefing、图片存在标记、工具需求、最低档位、新任务标记与上次运行失败标记。不发送历史正文、工具输出、系统提示词、图片内容、模型目录或模型价格。 任务和 briefing 本身若含私人信息仍会发送；凭证模式检查不等于完整脱敏。

常见场景

主会话稳定，独立任务选一次

首次独立任务可以路由；“继续”“按第二种方案改”和同一任务后续输入保持当前模型。另起任务时先 /route new。已恢复的历史会话默认按正在续接的任务处理。不会靠猜测自动认定新任务。

短句依赖前文

/route new
/route brief 当前独立任务是修复队列租约过期和确认并发时的重复处理，需保持幂等性。
/route floor frontier
继续检查这个竞态

briefing 由你或上层程序明确提供，只保留在进程内；new 会清空 briefing、最低档位和单次覆盖。没有 briefing 的含糊续接不调用 Jev。

用户明确选择

/route tier frontier
审查这次鉴权边界变更

单次档位覆盖不调用 Jev，但仍受最低档位、可用性、能力、熔断与换模预算约束。Pi 中手动切模型会自动 pin；/route unpin 恢复路由。pin/off 表示用户接管，绕过自动选择，不构成安全审核。

在子任务启动器中复用

Router 不依赖 Pi，不执行模型调用后的工作。可用类型化 Packet 明确传入独立任务、briefing、能力底线和实际上下文估算，读取 Decision 后由宿主执行。当前项目不包含子 Agent 创建器；不能把主会话历史直接当作独立子任务上下文。

排查路由和故障

/route doctor
/route explain
/route stats
/route cache clear

explain 区分提议的 action、当前模式和 modelChanged，并显示排除原因、激活尝试和分类来源。stats 区分 Jev HTTP 尝试、分类 tokens、执行模型报告的成本与缓存读取 tokens。执行端失败只影响后续请求；包括响应中途断连，本扩展也不会发送自动 continue。

命令速查

命令	作用
/route status	模式、当前模型、pin、任务边界与底线
/route init / reload	创建新配置 / 重新读取
/route shadow / auto / off	建议 / 自动选择 / 关闭路由
/route jev on / off	当前进程启停远程分类
/route new	下一条输入开始新任务，清空上一个任务的 brief、floor、tier
/route brief <text>	提供必要任务上下文，最多 6000 UTF-8 字节
/route floor quick/general/frontier	当前任务的最低档位
/route tier quick/general/frontier	下一次成功提交的输入使用指定档位
/route pin / unpin	保持手动选择 / 恢复路由
/route preview <text>	看提案，不执行
/route explain / doctor / stats	决策 / 配置与可用性 / 计数
/route cache clear	清除当前进程中的精确缓存

模式、Jev 开关、brief、floor 和 pin 的命令调整仅在当前运行实例生效。持久化偏好请编辑 JSON。恢复会话或重启不继承临时 pin、brief 或单次 tier。

实测与限制

首轮 16 个合成案例：13 次真实 Jev 请求、3 个本地规则案例；15/16 符合预设的原始档位/规则标签，输入 9,282 tokens、输出 1,100 tokens。模型误判的单元测试任务被保留当前模型的规则拦住。这不是下游编程任务成功率。

首轮还发现了风险 Noul 中间值造成多余升级的策略问题。修正后对同一组原始判断离线重放，保留了修正前后的记录；没有把重放当成新的 Jev 实测或独立验证。全部验证与边界。

需要明确的限制：

• confidence 反映分布集中程度，不是正确概率；阈值尚未经过生产校准。
• 成本是估算，当前模型缓存比例来自最近一次观察；未来缓存是否命中、跨模型缓存、分段计价和订阅折算均无保证。
• 上下文检查使用 Pi 估算和额外字节余量，不是提供商的精确 tokenizer。/skill 和模板在 input hook 后展开，因此保持原模型；其他扩展之后追加的大段内容仍可能改变实际请求。
• 自动模式无合格模型时不提交当前输入；shadow 模式只提示，执行仍沿用当前模型。它不检查任务代码正确性，也不授予执行权限。
• 只限制路由分类预算与换模次数，不是执行模型的硬性账单上限。估算的输入 tokens 用于准入，失败请求、进程重启、提供商结算可能与计数不同。
• Pi 本身的自动重试独立于本扩展；本扩展不会发起重放。测试用隔离配置关闭了 Pi 自动重试。
• 熔断状态在受信任项目 .pi/jev-router/health.json 持久化，保存模型 ID、失败时间和恢复租约，不含任务。崩溃遗留的锁不会自动抢占；确认没有活跃进程后再清理锁目录。
• 未实测 Windows、所有提供商、长期真实项目流量；无全面“优于 Bifrost”或节省比例承诺。

开发与评估

npm run demo                  # 明确标记的本地模拟，零 API 调用
npm run test:pi               # 真实 Pi + 本机假提供商，零商业模型调用
npm run format:check

# 可选付费评估：要求进程环境已有 TYPESAFE_API_KEY
# 仅发送 examples/evaluation-cases.json 中的合成任务
npm run eval:live -- results/new-live-run

# 不重新调用 Jev，用已有判断验证当前策略
node --experimental-strip-types scripts/replay.ts \
  examples/live-v1.json results/new-replay.json

新输出路径必须不存在。原始任务标签需在运行前确定，不应看到答案后改标签。CI 工作流只运行离线测试与本地 Pi 假提供商测试。

本项目独立编写，设计参考 pi-bifrost 与 TypeSafe intent routing。采用 MIT License，与 Pi、TypeSafe、Bifrost 官方无隶属关系。