Pi Jev Router

让 Pi 根据每轮任务需要自动降低思考强度，同时始终尊重用户最初选择的上限。

使用 TypeSafe Jev 做结构化路由判断，通过 Pi 的公开 Provider API 调用真实执行模型。Jev 只选择档位，不执行工具，也不生成任务答案。

• 只降不升：不能超过用户提交任务时选择的思考等级。
• 无需填写模型：默认读取当前模型，生成其支持的 low / medium / high 档位。
• 每轮比较固定的用户基准，而不是上一轮自动档位。
• 无可用的更低档位时，完全跳过 Jev。
• 可配置概率差阈值、超时和文本共享范围。
• 默认关闭，显式启用才发送路由文本；支持脱敏 Debug 日志。

实验性版本。 验证环境为 Pi 0.86.0、Node.js 24。已通过自动化回归和少量真实任务测试，但不是准确率、成本节省或跨版本兼容性的保证。本项目不隶属于 TypeSafe 或 Pi 官方。

安装

需要已安装 Pi，并配置至少一个可用执行模型。扩展会执行本机代码，安装前请审阅源码。

通过 GitHub

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

通过 npm

包名为 @gcoder1991/pi-jev-router，不是第三方同名的 pi-jev-router。以下命令需在该 scoped 包发布到 npm 后使用；若返回 404，请先用 GitHub 安装。

pi install npm:@gcoder1991/pi-jev-router

pi install 会登记到 Pi 用户配置。只想临时试用、不持久安装：

pi -e git:github.com/gcoder1991/pi-jev-router

也可以从源码运行：

git clone https://github.com/gcoder1991/pi-jev-router.git
cd pi-jev-router
npm install
pi -e ./index.ts

不要同时通过多个来源加载同一扩展。

快速开始

先用正常的 Pi 模型配置启动，不要直接选择虚拟入口 jev-router/auto。

export TYPESAFE_API_KEY='YOUR_TYPESAFE_API_KEY'
pi --jev-router

以上针对已经安装的扩展。源码试用时加 -e ./index.ts。

也可以不传 --jev-router，在 Pi 内手动启用：

/jev-router on

启用意味着允许将下文说明的有限文本发给 TypeSafe。不要将真实密钥写入代码、JSON 配置、截图或提交记录。

命令

路由规则

用户提交任务 → 固定本任务的模型和思考等级基准
  → Pi 开始本轮执行请求，已有取消信号和完整本轮上下文
  → 本地过滤候选：必须比用户基准更低，且满足能力/scope约束
  → 没有降档候选：直接用用户基准，不请求 Jev
  → 有降档候选：Jev 对候选和用户基准评分
  → 最佳候选概率 − 用户基准概率 > switchMargin？
      是：使用候选
      否：使用用户基准（即使上一轮降过档，也回到基准）
  → 真实模型响应 → 工具执行 → 下一轮重新判断

默认 switchMargin = 0.15，表示严格超过 15 个百分点，不是相对增长 15%。恰好达到阈值不会降档。Jev 的 confidence 仅记录，不作为切换门槛；概率与 confidence 都不是任务成功率保证。

例如用户初始选择 high：

这里恢复 high 不算越级升档：整个任务始终没有超过用户的初始上限。

等级顺序为 off < minimal < low < medium < high < xhigh < max，仅用于比较思考等级，不是不同模型的能力或价格排名。同等级的其他模型不算降档候选。显式跨模型配置需自行评估成本与兼容性。

默认档位

优先使用模型支持的 low / medium / high；这些等级均不可用时，使用其实际支持的其他非 off 等级。非推理模型仅有 off。

因此默认用户选 low 时，通常没有更低候选，会直接跳过路由；需要 minimal/off 时请显式配置，而且模型必须支持。

提示参考 OpenAI 的通用 reasoning 指南：low 也支持规划、工具、多步执行和常规编码，不被限定为机械操作。medium/high 用于额外推理有明确价值的工作。任务类别有重叠，必须结合实际评测，不能看到“读代码”就强制选 medium。

配置

配置文件只从显式 CLI 路径读取，不自动信任仓库里的 JSON。

创建 config.local.json：

{
  "timeoutMs": 10000,
  "switchMargin": 0.15,
  "shareToolResults": false,
  "maxToolChars": 16000,
  "maxStateChars": 48000
}

pi --jev-router --jev-router-config ./config.local.json

只改超时也可以：{"timeoutMs": 10000}。测试中出现过超过 1.8 秒的 Jev 请求，调试时可放宽到 10 秒；默认值并未因此自动提高。

缺 key、超时、网络/HTTP 错误、非法响应和候选优势不足，都会使用用户本任务初始档位。用户取消则停止请求，不会按失败兜底继续执行。执行供应商自己的错误仍交给 Pi 处理。

修改配置后重启 Pi 最稳妥。/reload 会重新初始化扩展；若使用 Debug，原日志路径已存在时不会覆盖。旧版 minConfidence、minMargin 不再参与决策，请移除。

显式模型档位

通常不需要填写 profiles。需要自定义时，参考 config.example.json，将其中 YOUR_PROVIDER、YOUR_MODEL 替换为 /jev-router models 列出的真实 ID。

{
  "switchMargin": 0.15,
  "profiles": [
    {
      "id": "economical",
      "provider": "YOUR_PROVIDER",
      "model": "YOUR_MODEL",
      "thinking": "low",
      "description": "Efficient reasoning for routine planning, tool use and execution-oriented coding."
    }
  ]
}

若用户基准不在候选列表内，会以唯一的 __user_selected 选项参与评分，不会将其概率假定为零。空的 profiles: [] 或非法配置会保持关闭，不静默回退。自定义描述不会被自动档位提示覆盖。

隐私与实际 API 输入

固定路由端点为 POST https://api.typesafe.ai/v1/systemone。请求包含 model、state、questions.route。

state 包含：

• goal：最近用户目标，约最多 2400 字符，不在 observations 中重复。
• userSelected：本任务固定的用户模型和思考等级。
• current：上一轮实际执行档位，与用户基准分开。
• nextStep：明确标记下一步尚未生成，不伪造下一步计划。
• observations：最多 8 条历史观察，工具调用和结果通过 ID 关联。
• evidenceLimits：共享设置、截断和遗漏说明。
• routingPolicy：降档模式、用户上限和切换阈值。

工具正文默认不发送。开启 shareToolResults 后，共享文本正文，并允许内置 read 的路径、offset、limit 白名单字段。不发送系统提示词、隐藏思考、图片数据、工具 details、shell 命令或任意其他工具参数。

脱敏不是完整 DLP。 用户文本、助手正文和工具结果仍可能包含商业秘密、个人信息或复制的敏感数据。候选描述也会发送。不要在不允许外发的项目启用；过滤字段不等于防提示注入。

正文截断优先保留最新证据，过长文本保留首尾并标记缺失；这不是语义摘要，可能遗漏文件中间逻辑。完整本轮上下文只转发给实际执行模型。

Debug 日志

mkdir -p debug
pi --jev-router --jev-router-config ./config.local.json \
  --jev-router-debug "./debug/run-$(date +%Y%m%d-%H%M%S).jsonl"

只有显式指定路径才记录正文。目录必须已存在，文件必须是新文件，以 0600 创建。不会覆盖已有文件或跟随已有符号链接。日志写入失败会停止记录，不阻塞任务；没有自动轮转。

使用 requestId 关联请求、选择和执行。日志仍含任务正文，不要提交到公开仓库。项目忽略 debug/、*.jsonl、本地配置和环境文件，npm 包另外采用文件白名单。

Pi 集成与限制

使用公开 API：registerProvider、modelRegistry.streamSimple、扩展事件和会话审计。没有修改 Pi 核心。

• Pi 模型栏显示 jev-router/auto；状态栏和 /jev-router status 显示实际执行档位。
• 启用时将入口切换为虚拟 Provider；逐轮只在真实请求入口选择目标，不在 before_agent_start 等待网络。
• 真实 provider/model、usage、thinking 签名和工具 ID 原样返回；Jev usage 单独记审计，不并入主模型统计。
• 支持取消、scope、图片能力和保守上下文窗口过滤；虚拟入口使用配置模型的最小窗口，可能提前压缩。
• 主请求与维护请求通过 options.signal === ctx.signal 区分；这依赖当前 Pi 行为，并非跨版本稳定性保证。升级后先跑测试。
• 默认模型设置不持久修改，但虚拟入口会出现在会话历史。内存中的用户基准/最后执行档位不完整跨重启恢复；从正常真实模型启动最可靠。
• 手动选择优先；排队/steering 消息沿用当前 agent run 的基准，不被当成一次新的手动档位选择。
• 不控制子 Agent，不能撤销已发生的工具副作用。Pi 重试请求时可能重新调用 Jev。
• 第三方 provider 专属 hooks、OAuth、跨供应商上下文迁移需单独测试；认证仍由 Pi 处理，不把虚拟入口凭据转发给真实供应商。
• 每次有效路由多一次 API 请求和等待，跨模型切换可能损失缓存，不能保证端到端省钱或提速。

开发与验证

git clone https://github.com/gcoder1991/pi-jev-router.git
cd pi-jev-router
npm install
npm run check
npm test
npm pack --dry-run

测试使用真实 Pi SDK / agent loop，执行 provider 和 Jev 网络请求为 mock，使用临时目录和内存凭据，不调用付费 API。覆盖取消、手动选择、图片、概率差边界、固定用户基准、只降不升、无低档跳过、文本隐私和 Debug。

开发中另做过少量真实任务验证：常规单文件核查选 low，条件概率题选 medium，异步竞态和约束优化题保留 high。概率答案由精确分数计算核对，优化结果由枚举核对，并发反例及修复由调度脚本核对。这些是有限样本，不是系统性基准或质量保证；原始本地会话日志不公开发布。

参考与许可

• TypeSafe API
• TypeSafe Choice
• TypeSafe Skills
• OpenAI reasoning effort 指南

MIT，见 LICENSE。