pi 的上下文经济学引擎——dsh-switchman 调度理念的 pi 原生重设计。
管住每一个进入上下文的 token(入口压缩),把工作派到成本最低的执行层(分层执行矩阵),让模型选择只在一个入口发生(sticky 虚拟模型路由)。
状态:M0–M4 完成。设计文档见 DESIGN.md。
| 层 | 能力 |
|---|---|
| [A] 入口压缩 | 超大工具结果进 transcript 前蒸馏(保头尾+省略标记),全文落盘 footer 留路径;expand 工具按行号取任意片段;hard 水位自动收紧阈值 |
| [B] 执行矩阵 | dispatch 工具四模式:gather(内嵌只读步骤编排,过程零入栈)/ judge(泳道模型单发裁决)/ run(隔离子进程 subagent)/ parallel(≤8 任务并行);每次派发入台账(防重复派发 + 压缩保真);子智能体工作可视:每个 run agent 写人类可读日志;tmux 内在当前窗口左右分屏——pi 主格居左,右列最多 2 格上下均分直播,超出的后台排队,格子空出即 respawn 无缝接位,全部收工自动恢复主格全屏;非 tmux 用 /switchman-agents [n] 列表/钻取 |
| [C] sticky 路由 | switchman/auto 虚拟模型:continuation/retry 粘滞保缓存;user 边界双决策器(本地决策模型 + 内置规则打底)判泳道;缓存窗口 + 置信度双闸决定换/留;图像闸门:请求带图(read 工具的图像结果或 API 附件)而当前模型不读图时,优先于一切粘滞强制改道 vision 泳道;图像中继:大上下文(≥ router.visionRelayThresholdTokens,默认 50k,0 关闭)时不冷切,由 vision 泳道小请求描述图片注入对话(用户附件在 before_agent_start 拦截,read 工具结果在 tool_result 拦截替换),当前模型缓存无损,失败自动回落整回合切换;死回合接续:pi 在响应出错后的阈值压缩只压不接(Case 3 无 retry),turn_end 检测到「errored assistant + 尾部压缩」死回合时自动发 [SWITCHMAN:CONTINUE] 接续 |
| [D] 能力知识层 | 候选集活目录现查;锚点 > 名字/价格启发式推断 > 目录顺序;泳道未配置自动排序 |
| [E] 水位 | 每档双形态阈值:百分比(0–100)或绝对 token(如 tokens: 80000),两者同配时按实际窗口换算取小者生效;soft→引导派发 / hard→压缩收紧 / force→提示 pi 自动压缩(单压缩者原则;台账经 session_before_compact 快照、session_compact 后确定性还原);死回合(stopReason=error)自动接续 |
| [F] TUI 配置 | /switchman-config:泳道×有序模型表(↑↓调序)、决策模型选择、即存即生效;JSON 文件永远可手改 |
| [G] 注释规范注入 | 初始 prompt 要求模型写注释(代码/文档)时用 dsh 式三段括号形式 [YYYY-MM-DD]-[改动与理由]-[对齐关系];独立协议段(字节稳定,开关切换不扰动主段缓存前缀);"annotate": false 关闭 |
出厂 agents:scout(侦查)/ reviewer(独立复审)/ tester(测试分诊)/ worker(通用实现)。
内置 skills(随包安装自动发现,/skill:<name> 显式调用):git-commit-message(只产出提交文案,不碰 git 写操作)/ db-query(MySQL/Redis 只读核查,自带加固过的查询脚本)/ requirement-docs(带证据链的需求/设计/计划文档)。输出语言遵循 switchman.json 的 skills.language(default + 按类别 commit/docs/db 覆盖,项目层覆盖全局层),当场指令的语言优先级最高;机器标记与协议文本保持英文稳定。首次在未配置的 TUI 项目里启动会一次性询问三个语言问题(默认产出 / 提交信息 / 生成文档):从常用语言列表选择,末项"其他"可手动输入;答完写入项目 .pi/switchman.json,Esc 跳过则跟随对话语言且本会话不再问。
方式一:pi 包(推荐,一条命令)
pi install git:github.com/mrzturn/pi-switchman出厂 agents(scout/reviewer/tester/worker)已编译为内置兜底——未放置任何 agent 文件时自动可用;放入 ~/.pi/agent/agents/*.md 可覆盖。升级:pi update --extensions。
方式二:开发安装(本仓库 clone 后)
# 试运行
pi --extension ./src/index.ts
# 安装为用户扩展(含出厂 agents 文件版,覆盖内置)
ln -s "$(pwd)/src" ~/.pi/agent/extensions/pi-switchman
mkdir -p ~/.pi/agent/agents
for f in agents/*.md; do ln -s "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f"); done
# 技能随包安装自动发现;开发安装需在 ~/.pi/agent/settings.json 声明:
# "skills": ["<本仓库绝对路径>/skills"]非 npm 包:宿主依赖(pi-ai / pi-agent-core / pi-coding-agent)由 pi 提供,
peerDependencies: "*",无需npm install。
# 路由:/model 里选 switchman/auto;配置:/switchman-config;状态:/switchman-status;子智能体日志:/switchman-agents配置(全部可省,开箱即用;TUI 只是 JSON 的编辑器):
本地决策模型:两种配置部路——
- TUI:
/switchman-config→ decision 行 →── add local endpoint (provider + model)…,填 provider 名、systemone 端点 URL、模型 id(可选 API key),确认即保存并立即注册(无需重启); - 手改 JSON:如上例的
router.decisionEndpoint,扩展启动时自动注册为 typesafe-system-one classifier,decisionModel会同步指向它。 端点挂掉自动落回内置规则链,路由永不断;也可不用本地端点,直接在 models.json 注册任意 classifier 后在 TUI 选择。
bun add -d @earendil-works/pi-coding-agent @earendil-works/pi-ai # 仅测试需要
npm test # node --test,48 个用例零运行时依赖(peerDependencies "*",由 pi 宿主提供);node_modules/ 仅开发用。
MIT