pi-tier-scheduler

为 Pi 编码代理做分层模型调度——一个虚拟模型,把每个请求路由到 brain/pillar/crowd 三层之一。

English | 简体中文

只选一个虚拟模型 ts/auto,调度器就把每个请求送到适合这项工作的实体模型:强模型负责规划与推理,均衡模型负责实现与调试,高效模型处理轻量任务。路由确定、可解释;手动接管永远只需一条命令;所有回退都有上界。

目录

• 环境要求
• 安装
• 快速上手
• 配置
• 分层与路由
• 命令
• 凭据
• 故障排查
• 开发
• 贡献
• 许可证
• 更新日志

环境要求

• Pi 1.0.4 或更新。这是经过验证的兼容地板:本包基于 Pi 1.0.4 扩展 API 构建并测试,/ts doctor 会报告它验证过的地板版本。
• Node 20 或更新只在从检出目录跑开发检查时才需要;在 Pi 里安装并使用本包,不需要单独配置 Node。

安装

从 npm(推荐)

本包以 pi-tier-scheduler 发布在 npm:

$ pi install npm:pi-tier-scheduler

一条命令包含全部：从 npm registry 解析包、装进 Pi 的包目录、对每个新 Pi 会话注册——pi list 可见，pi remove npm:pi-tier-scheduler 卸载。npm 包页 npmjs.com/package/pi-tier-scheduler 镜像本 README 与版本历史。（裸 npm install pi-tier-scheduler 只是把文件放进项目的 node_modules——Pi 只加载它自己安装过的包。）

从 GitHub

$ pi install git:github.com/MicTx/pi-tier-scheduler@v0.5.1

git: 形式对任何可克隆的 git 远端都成立——公司 Gitea、自建服务或 fork 都行。用 @<tag> 钉版：后续更新只核对检出内容，不会移动钉死的 ref。认证走你 git 克隆该主机时本来就用的那套凭据；本包自身不保存任何密钥。pi remove 接同一个源。

从本地检出安装

本包也可以从本地克隆安装:

$ pi install ./

本地包从解析出的磁盘路径加载——不复制、不发布。装好后 pi list 会显示 pi-tier-scheduler,pi config 可以开关它的资源。在包根目录用同样的源路径卸载:

$ pi remove ./

只想在单个会话里试用、不安装:

$ pi -e ./

pi install ./ 让本包对机器上每个新 Pi 会话可用;pi -e ./ 只在那一次调用里加载。两条命令都不需要凭据:本包不保存密钥、不读取任何密钥材料(见凭据)。

快速上手

从安装到第一个被路由的请求,三步:

1. 在你的项目里启动 Pi,运行 /ts init——引导向导(TUI)会读取 Pi 已知的模型清单,逐层点选,零手输。没有向导可用?直接抄配置里的完整示例。
2. 把 ts/auto 选为会话模型——/model、--model、或设置项,它看起来和别的模型一样。
3. 随便问点什么。/ts status 随后显示哪个实体模型应答、为什么是它。

$ /ts init
$ /ts status
$ /ts use brain
$ /ts auto

后两条是手动逃生口:/ts use brain 把规划类工作钉在你最强的层,/ts auto 交还自动路由。

配置

配置是两份可选的 JSON 文件,都按包名命名:

• 用户级:<agent-dir>/tier-scheduler.json——默认 ~/.pi/agent/tier-scheduler.json。agent 目录跟随 Pi 的 PI_CODING_AGENT_DIR 覆盖。
• 项目级:会话工作目录下的 .pi/tier-scheduler.json。不向上搜索父目录。

多层深合并,优先级为内置默认 < 用户 < 项目。每一层都是部分的:文件只写自己在意的键即可,最小合法文件就是 { "schemaVersion": 1 }。完整示例:

{
  "schemaVersion": 1,
  "tiers": {
    "brain": { "candidates": [{ "provider": "your-provider", "id": "strong-model" }] },
    "pillar": { "candidates": [{ "provider": "your-provider", "id": "balanced-model" }] },
    "crowd": { "candidates": [{ "provider": "your-provider", "id": "fast-model" }] }
  },
  "policy": {
    "defaultBias": "medium",
    "sticky": true
  },
  "retry": {
    "maxAttemptsPerRequest": 3,
    "maxTierSwitches": 2
  }
}

• tiers.<tier>.candidates 是有序的 { "provider", "id" } 列表。这份列表就是你的模型清单:上面的示例 ID 只是示意,由用户自填——内置候选数组为空,在你配置至少一个候选之前,路由无模型可派。
• policy.defaultBias(minimal | low | medium | high | xhigh | max,默认 medium)是会话没有手动选择时施加的思考强度偏置。
• policy.sticky(默认 true)让续接请求尽量留在上一个实体模型上(只要它仍合格),保住提示缓存。
• retry.maxAttemptsPerRequest(默认 3)与 retry.maxTierSwitches(默认 2)约束恢复游走。这是只能收窄、不能放宽的天花板:代码强制硬上限——每请求 5 次尝试、每路由 3 次换层。

校验不过的层会被报告并跳过——其余层照常生效。无法解析的 JSON 会被隔离成 .corrupt-* 副本供你修复;任何内容都不会被静默覆盖。

分层与路由

三层,各说明一个模型是干什么的:

层	偏置	适合的工作
brain	high	规划、架构、硬推理、横切分析
pillar	medium	实现、调试、重构——干活的主力默认层
crowd	low	会话闲聊、轻量或重复执行

把 ts/auto 选为会话模型（/model、--model、或设置项——它看起来和别的模型一样）。每个请求之前,路由器按以下顺序确定性决策:

1. 手动覆盖——/ts use <tier> 永远压过自动路由。
2. 工作阶段——对会话分类:规划 → brain,实现/验证 → pillar,闲聊 → crowd,无法分类 → pillar。
3. 复杂度——高复杂度升一层,低复杂度降一层。
4. 思考偏置——选中的虚拟思考等级(或 policy.defaultBias)朝同一方向轻推。完整 Pi 档位全部开放:minimal/low 倾向 crowd,medium 不动,high/xhigh/max 倾向 brain——更深的档位会传给路由到的模型,并按其能力钳制。
5. 候选选择——该层配置顺序里第一个合格的候选胜出。合格性过滤已配置且已授权的 provider 和任务约束(图像输入、推理要求);请求的思考强度会被钳到实体模型支持的范围内。

每个决策都产出机器可读的理由(work_phase、complexity_adjustment、thinking_bias、manual_override、manual_override_fallback、automatic_fallback、direct);/ts status 显示最近一条。

回退天生有界。一次尝试失败后,失败被分类,下一个备选先从同层挑,再按配置的回退顺序走——绝不无限循环,始终在尝试与换层上限之内。粘性续接时,上一个实体模型只要仍合格就会被保留。ts/auto 永远派发实体模型,绝不派发另一个虚拟模型。基于分类器的路由精化是后续计划,不在本发布内;上面的确定性规则就是交付契约。

命令

一个命令族,注册为 /ts:

命令	可用模式	行为
/ts 或 /ts status	全部	当前选择、最近派发的实体模型、生效中的覆盖、最近路由理由、生效配置摘要(含逐层候选表)
/ts use <tier>	全部	手动覆盖到 brain、pillar 或 crowd;选中 ts/auto 并设置对应偏置
/ts brain · /ts pillar · /ts crowd	全部	/ts use <tier> 的短别名
/ts auto	全部	解除手动覆盖,回到自动路由
/ts init	TUI	引导式首次配置——从已装模型中点选候选
/ts config	全部 / TUI	任何模式都能看生效合并配置;编辑仅限 TUI
/ts doctor	全部	配置合法性、模型可用性、凭据在场情况、路由器状态健康度、兼容地板——对齐的检查表输出

模式行为:/ts init 与 /ts config 的编辑半边要打开交互式 Pi 对话框,因此仅限 TUI;在 RPC、JSON、print 模式下它们回复一条纯文本提示,不做任何变更。status、覆盖、解除、doctor 在所有模式下行为一致,纯文本输出。

凭据

Pi 通过自己的机制解析 provider 凭据(它的认证存储和各 provider 的环境约定)。本包绝不保存、写入、代理或记录凭据——它只问 Pi 某 provider 是否已配置。你平时怎么给 Pi 配密钥就怎么配;调度器不需要任何额外的东西。

故障排查

• doctor 报告凭据缺失——某个已配置候选的 provider 在 Pi 里没有密钥。按 Pi 的方式补上凭据即可;调度器没有独立的密钥库。doctor 永远不打印凭据值。
• no_eligible_physical_model 或状态里某层为空——该层候选缺失、写错名字,或当前全都不可用(provider 未授权、模型不在目录里)。对照 Pi 列出的模型检查 provider/id 拼写,并用 /ts doctor 查看逐 provider 的授权状态。
• 加载时报配置问题——校验不过的层被跳过,并给出指向问题键的 JSON 路径错误;其余层照常生效。修报告的键;只有文件损坏(而非校验不过)才会产生 .corrupt-* 隔离副本。
• JSON 损坏——配置文件无法解析时,原始字节保留为旁边的 .corrupt-* 副本,该文件视为不存在。修复或删除副本;调度器绝不静默丢弃它。
• 路由上上下文溢出——失败分类器会标记它,重试游走在层内优先挑容量更大的兼容候选;上限耗尽时请求以有界错误结束,而不是循环。
• 撞到重试上限(route_limit_exceeded)——有界游走在 maxAttemptsPerRequest 次尝试或 maxTierSwitches 次换层后停下。减少重复候选、给该层加一个健康候选、或在配置里收窄重试值,都会改变游走;想放宽到硬上限(5 / 3)以上是不可能的。
• 命令有响应,对话框不出现——你在 RPC、JSON 或 print 模式。/ts init 与 /ts config 编辑按设计仅限 TUI;其余子命令在所有模式可用。
• Pi 升级后扩展加载失败——兼容地板是 Pi 1.0.4。运行 /ts doctor(它的版本检查会报告地板);在新版宿主上出现漂移时,使用前需要重新验证——本发布验证过的地板见更新日志。

开发

从检出目录:

$ npm install
$ npm run typecheck
$ npm test
$ npm run test:release
$ npm run test:coverage

在检出的包根目录运行。

test:release 先类型检查、再跑全量套件——发布门禁。测试套件确定且密闭:伪造的模型注册表与内存 provider、失败注入语料、配置/路由/命令/模式矩阵。验证不发起真实网络调用、不使用真实凭据。

贡献

欢迎到 MicTx/pi-tier-scheduler 提 issue 与 PR。提交 PR 即表示你同意贡献按本仓库的 PolyForm Noncommercial 1.0.0 条款授权。

许可证

以 PolyForm Noncommercial License 1.0.0 发布。个人、研究、教育及其他非商业用途免费;商业使用需另行取得书面授权。

更新日志

见 CHANGELOG.md:发布历史与每个版本的兼容地板。