pi-jev-router (win4r)

# Pi Jev Router

[English](README.en.md) · [研究与 Bifrost 对比](docs/research.md) · [设计与边界](docs/design.md) · [验证记录](docs/validation.md)

[](https://github.com/win4r/pi-jev-router/actions/workflows/tests.yml)

为 **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 的完整功能替代，也尚未证明它在真实编程任务上更便宜或更准确。[具体对比与源码依据](docs/research.md)。

## 安装与第一轮使用

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

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

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

已运行的 Pi 会话需要重新启动才能加载新扩展。安装后依次执行 `/route init`，编辑