pi 接的不是模型，是一整个 ZCode agent

pi 接的不是模型，是一整个 ZCode agent。zcode-provider 是一个 pi 扩展：把 ZCode 的 agent（zcodex app-server）包装成 pi 里的一个「模型供应商」。你在 pi 的 /model 里选中一个 ZCode 模型，背后接上的不是某个 API 端点，而是一个带着自己会话、自己工具（bash、文件编辑、插件）的完整编码 agent。TypeScript 写的 MIT 小仓库，8 月创建、10 月初仍在更新，目前 2 星 4 fork——工程量远超星数。

一、为什么要这么设计

本站之前写过 pi（earendil-works/pi，11.9 万星）：一个靠多模型编排立足的开源编码 agent。zcode-provider 把这个哲学推到了极端——pi 的 provider 列表里不光有 API 模型，还可以挂一个「agent」。

分工很清晰：pi 是聊天前端，ZCode 在后台保留自己的会话并自己执行工具，回复实时流回 pi——推理、工具调用、工具结果、正文，按 ZCode 产生的原始顺序 inline 交错渲染，不是最后甩一大段。模型列表也不用硬编码：ZCode 配置里的每个 provider/model 都自动变成 pi 的可选项，增删 provider 不用重启 pi。兼容性处理相当细：老版 CLI 只认自己的 settings 文件，ZCode 桌面端把 provider 写在 v2 配置里，扩展在服务启动时把启用的条目合并进去，还会清掉失效变体，防止过期的空 API key 撞坏 app-server 的严格 schema；每次写配置前先备份成带时间戳的 .bak 文件。

二、会话续命与插话

底层是 zcodex app-server 的私有 NDJSON stdio 协议，桥接层实现了会话创建、订阅、发送和事件流的子集，还处理了一个真实的竞态：旧版 app-server 会发出非终态的 prompt_completed 快照，桥不把它当回合结束。

两个体验细节最见功力。一是会话续命：app-server 会把闲置会话逐出内存（闲置 10 分钟、LRU 上限 16 个），桥在每轮开始前先恢复持久化会话；pi 退出后用 --session 恢复对话时，桥按 pi 会话 UUID 记住的映射去 resume 对应的 ZCode 会话——ZCode 的会话记忆、累积上下文、工具状态全都在，跨重启不断档。二是插话模式：ZCode 任务跑到一半时你在 pi 里打字，queue 模式排队等下轮，guide 模式经 ZCode 的 v4 通道在下一个工具/消息边界注入同一轮内，不可导向时自动回退队列，默认跟随 ZCode 自己的交互设置。ZCode 弹 askUserQuestion 提问时，pi 里会出现选项对话框（含多选和自由输入），答完在原会话里继续跑。

三、计费边界与安全开关

Start Plan 的处理写得很老实：Coding Plan 和 Start Plan 在 /model 里分开列出，两者之间没有自动回退；每轮开始前检查余额和模型覆盖，套餐过期或耗尽就直接失败，不会偷偷扣另一个套餐。桥只读共享登录态，绝不把 Start Plan 的 JWT 写进它生成的 provider 配置。单轮默认 30 分钟预算，超时自动中断并续一句 go on，长任务不至于卡死。

安全上要心里有数：这个桥给 pi 的是 ZCode 的全部权力，默认自动「允许」ZCode 的权限提示（这正是它的意义所在），想反悔就设 ZCODE_AUTO_ALLOW=0 改为拒绝；包里不存任何 API key。作者还写了确定性的回归测试——用手写的假 app-server 复现跨三轮的 prompt_completed 竞态，调试用 /zcode-probe 把原始协议行倒进 jsonl。

适合谁：习惯 pi 的交互和编排、又有 ZCode 订阅的人——把 ZCode 当引擎挂在 pi 里统一调度，等于两个工具的优势叠加。2 星的仓库，做的是协议级的细活，值得被更多人看到。