pi-model-routing

给 pi coding agent 的模型路由包：一份路由规则 skill，加一个强制显式模型的 subagent 执行器。

解决的问题很具体 —— 模型和推理强度应该按任务类型选，而不是一路用同一个；以及子任务必须显式指定模型和强度，不能靠继承或"扮演某个模型"。

能解决什么

• 正式规划、架构决策前先核对当前轮实际运行的模型和强度，不匹配就说明并暂停规划。
• 按任务类型选择模型和强度：规划用最强推理模型，常规实现用通用模型，文书与视觉用专长模型。
• 委派子任务时强制写清目标、上下文、允许写入的绝对路径、验收标准和已有证据。
• 子代理必须显式声明 provider/model:thinking，否则直接拒绝执行。
• 主代理必须独立复核子代理的结果，不接受"已完成"作为证据。
• 可选额度守卫：共享额度池接近耗尽时自动改道到备用模型。

安装

pi install npm:pi-model-routing

本地开发阶段使用绝对路径安装：

pi install "/path/to/pi-model-routing"

Pi 已运行时，安装后执行：

/reload

安装后检查：

bash scripts/check-install.sh

路由规则

包内的 model-routing skill 提供完整规则表。核心映射：

几条容易做错的：

• 路由是能力判断，不是省钱判断。选能稳定完成任务的最低档模型，遇到证据再升级。
• 专长分支不是阶梯。文书任务不会因为提高强度就变成实现任务。
• 弱模型多试几次不等于强模型少试几次。
• 额度或服务故障可以回退，但要说明实际跑的是哪个模型。质量问题不能靠换模型掩盖。

subagent 工具

安装后 Pi 提供 subagent 工具，三种模式：

// 单个
{ "agent": "reviewer", "task": "审查 X 模块的错误处理" }

// 并行
{ "tasks": [{ "agent": "a", "task": "..." }, { "agent": "b", "task": "..." }] }

// 串行，上一步输出注入下一步
{ "chain": [{ "agent": "a", "task": "..." }, { "agent": "b", "task": "参考 {previous} 继续" }] }

关键约束：

• Agent 必须显式声明模型。~/.pi/agent/agents/*.md 的 frontmatter 缺少 model: provider/model:thinking 会被拒绝。
• 子代理不能再次委派，也不能自行 commit / push。
• 默认并发 2，硬上限 4。同一轮里的多次并行调用共享这个额度。
• 项目内 Agent 需要确认。.pi/agents 下的定义由仓库控制，默认弹窗确认后才执行。
• 输出上限 50KB / 2000 行，超出的完整内容写入临时文件并在结果中给出路径。

并发上限用环境变量调整：

PI_MODEL_ROUTING_CONCURRENCY=3

取值必须是 1 到 4 的整数，其他值直接报错。

额度守卫（可选）

默认不启用。只有配置了共享额度池时才介入。

配置文件：~/.pi/agent/model-routing.json

{
  "quota": {
    "endpoint": "http://127.0.0.1:8080/v1/quota",
    "managedModels": ["vendor/team/shared:max"],
    "fallbackModel": "vendor/team/worker:max",
    "cachePath": "~/.config/provider/quotas.json",
    "plan": {
      "provider": "acme",
      "plan": "SHARED",
      "windows": ["5 hours", "Weekly", "Credits"],
      "threshold": 80
    }
  }
}

字段说明：

行为约定：

• 读不到额度就按不足处理，改道到备用模型。不会因为接口故障就放行高额度请求。
• 过期读数视为不足，未来时间戳同样视为无效。
• 额度守卫是失败防护，不是绕过限额的手段，也不会购买额外额度。
• 配置文件缺失、JSON 非法或字段不全时，守卫整体不启用，不影响子代理正常执行。

不包含什么

• 不含任何供应商账号、模型组名、凭据或运行记录。
• 不含实时路由状态面板（/routing），也不含本地安装脚本和回滚快照。
• 不会修改你的全局 settings.json、Agent 定义或指令。

许可

MIT