pi-routing-suite

任务感知的推理模式路由,面向 pi(pi-coding-agent)。 移植自 yjh051108/dsh-routing-suite(MIT)。

社区项目,与 earendil-works / DeepSeek 无关。

它做什么

模型在 react↔spec 轴上的行为塌缩为三个稳定区,不是连续谱(上游实测, 21-point × n=2 on DeepSeek V4 Pro):spec [0, 0.15]、不稳定过渡带 [0.2, 0.45]、 react [0.5, 1.0]。"连续模式调优"在模型层是幻觉——量化为三带才是诚实界面。

• 首条消息锚定:会话轨迹在首轮定型。自动模式下,第一条真实用户消息被分类, 首轮 system prompt 注入匹配 persona,工具面按 band 收窄;第二轮起恢复完整能力。
• 三带 + 弱内路由:spec(计划型,只读优先)/ react(执行型,完整工具)/ weak(模型自己按任务分类,persona 按模型特化:pro=spec 句+分类指令, flash=中性+分类+recall/converge/anti-runaway 锚点)。
• near-field 引导(weak 带):固定引导文本,深度自适应(GUIDE_WEAK/GUIDE_DEEP)。
• RL 接口还原(standard):RL 句 + 精简安全指令 + 窄 RL 形状工具面 (bash + read/write/edit)。
• 自优化工具:dev_router_status / dev_router_mode 让模型检查并锁定自己的路由。

安装

作为 pi package(推荐)

# npm(gallery 可发现,推荐)
pi install npm:[email protected]

# 或 git
pi install git:github.com/zhexulong/[email protected]

或直接试运行(不写入配置):

pi -e git:github.com/zhexulong/pi-routing-suite

本地源码

git clone https://github.com/zhexulong/pi-routing-suite.git
cd pi-routing-suite
npm install
npm run check && npm test
pi -e ./extensions/index.ts   # 或复制到 ~/.pi/agent/extensions/

使用

• 自动路由(opt-in):两种开启方式,配一次永久生效:
  • 交互命令:/router-config auto on(写项目 .pi/settings.json,需项目信任)或 /router-config auto on --global(写全局 ~/.pi/agent/settings.json);
  • 或直接编辑 settings.json 加 "pi-routing-suite": { "auto": true }。 开启后每个新会话首条消息自动分类:build 任务 → react persona;fix 任务 → spec persona;模糊任务 → weak 内路由;寒暄/问候不路由(band=none)。 看启动日志 [pi-routing-suite] 首条消息分类=...。
• 手动锁:调用 dev_router_mode 工具,或人类用 /router-mode spec|react|weak|standard|auto。 手动锁持续生效,auto 解锁(解锁后下一条消息重新分类)。
• 状态查看:dev_router_status 工具或 /router-status 命令。

持久化配置(走 pi 原生 settings)

配置存放在 pi 的 settings.json 的 "pi-routing-suite" 键下,与 pi 自身配置同文件、 同写锁,不会被覆盖丢失。优先级(高→低):

1. 环境变量 PI_ROUTER_ENABLED / PI_ROUTER_AUTO(仅显式 0/1)
2. 项目 .pi/settings.json(仅项目信任时读取)
3. 全局 ~/.pi/agent/settings.json
4. 默认:enabled=true,auto=false(自动路由 opt-in)

// settings.json
{
  "pi-routing-suite": {
    "auto": true,
    "enabled": true
  }
}

| 命令 | 作用 | |---|---| | /router-config status | 查看当前生效配置与来源 | | /router-config auto on\|off | 开/关自动路由(写项目 settings) | | /router-config enabled on\|off | 开/关整个扩展(写项目 settings) | | /router-config <key> <val> --global | 同上,写全局 settings |

环境变量

| 变量 | 默认 | 作用 | |---|---|---| | PI_ROUTER_AUTO | off | 1 启用首条消息自动路由(临时覆盖,持久化用 /router-config 或 settings) | | PI_ROUTER_ENABLED | on | 0 完全禁用(无需删文件) | | PI_ROUTER_CRASH_TEST | off | 1 注入 hook 异常,验证 fail-open + 熔断 |

实测记录(2026-08-16,pi 0.84.1 + cpa-oai 渠道)

真实模型实测,验证分类 → 注入 → 行为约束的完整链路:

| 模型 | 任务 | 分类 | 结果 | |---|---|---|---| | deepseek-v4-pro | 写一个 hello world python 脚本 | react | ✓ 完成产出 | | deepseek-v4-pro | 修复…请改注释 | spec | ✓ 只读相关文件、精准小修、无 env 检查 | | deepseek-v4-pro | 梳理项目下一步 | weak | ✓ WEAK_PRO,回答准确 | | deepseek-v4-flash | 看看当前目录结构 | weak | ✓ WEAK_FLASH | | deepseek-v4-flash | 修复一下测试断言 | spec | ✓ |

实测中发现的两个 pi 侧问题(定位过程与修复详见兼容性)。

兼容性

• 开发与测试针对 pi 0.84.x。
• 实测中发现并修复的 pi 侧问题:
  1. spec band 行为漂移(v4pro):仅一句话 persona 时模型跑 env 检查、乱翻 无关文件,450s 无产出 → 新增 SPEC_GUIDE 执行纪律(anti-runaway), 修复后精准小修。此引导为上游 WEAK_FLASH 纪律的 spec 版精简(上游 spec 预设带完整 agent-instructions sections,pi 移植无此机制),追加而非替换 persona。
  2. 中文短指令误判寒暄:"看看当前目录结构"被"短消息无关键词→寒暄"启发式 吞掉 → 移除该启发式,无关键词短句走 weak 内路由。
• 移植语义对齐上游 v0.3.0 / opencode 移植 v0.2.0:三带量化、 首条消息锚定、手动锁、模型特化 weak persona、near-field 引导。
• v4pro / v4f 支持:weak 带按模型特化(非 flash → WEAK_PRO;flash → WEAK_FLASH),persona 文本来自上游在 v4pro/v4f 上实测的最优解(P11/P24), 实测记录见上方章节。
• 与上游的差异(pi 侧适配,非注入文本):
  • spec band 追加 SPEC_GUIDE 执行纪律(见上);
  • 移除"短消息无关键词→寒暄"启发式(见上);
  • pi 无独立 glob/grep 工具 → spec band 工具面为 read + bash;
  • pi 无 str_replace_editor → RL 形状面为 bash + read/write/edit;
  • standard band 采用 追加 RL 句+安全指令(而非整体替换 system), 以保留 pi 的结构性指令;
  • dev_mode_subagent(模式隔离子代理)暂未移植——pi 的子代理系统独立, 后续可映射到 pi-subagents 的 agent persona。

安全

• 每个 hook 均 try/catch,fail-open:异常记录后消息链路照常。
• 连续 3 次异常 → 扩展自禁用并清空状态(恢复:重启 / 修复 / 删除文件)。
• 状态为 per-session Map,会话间不共享模式锁。
• 无网络请求、无遥测。

验证

npm run check          # tsc 类型检查
npm test               # node --test 单元测试(分类器/寒暄/band/模型特化/工具面)
npm run verify:upstream # 上游字节级快照 SHA256 校验

手动检查清单(安装 + 重启后):

• [ ] dev_router_status 报告正常值;/router-status 可用。
• [ ] PI_ROUTER_AUTO=1 时:build 任务("写一个 python 脚本…")→ react persona; fix 任务("重构这个模块…")→ spec persona;模糊任务 → weak persona; 问候("你好")不路由(无注入日志)。
• [ ] /router-mode standard 锁会话:下一条消息按 RL 形状面 + 安全指令处理, 消息后工具面恢复完整。
• [ ] 自动路由会话的第二条消息恢复完整工具集(工具面未收窄)。
• [ ] 崩溃注入:PI_ROUTER_CRASH_TEST=1 发消息——pi 正常运行、异常被记录、 3 次后扩展自禁用。
• [ ] 删除扩展文件后行为与干净安装一致。

目录结构

extensions/index.ts      # pi 扩展(事件 hook + dev_router_* 工具 + /router-* 命令)
src/router-core.ts       # 移植核心:分类器 / personas / band 量化 / 工具面映射(零依赖)
scripts/upstream/        # 上游字节级快照(SHA256 校验,注入字符串唯一事实源)
test/                    # 单元测试(node --test)

Credits

移植自 yjh051108/dsh-routing-suite(MIT)。 结构参考 cuddly-guacamole/opencode-routing-suite (会话状态模型、寒暄检测、熔断与 fail-open 模式)。上游致谢:

• xiaobright/modeltest — Project2 / V4.1b 评测方法
• xiaobright/dsh-anchored-standard — 两阶段锚定机制

特别感谢 LINUX DO 社区——DSH 路由生态的讨论、评测与方法论交流 主要发生在该社区,本项目是这一社区生态在 pi 上的延续。

License

MIT。分类器与 personas 派生自 yjh051108/dsh-routing-suite router-standard 预设;上游版权与 MIT 声明保留于 NOTICE。