Pi:分层的 agent harness monorepo

一句话定位

Pi Agent Harness(原 badlogic/pi-mono,现迁到 earendil-works/pi)是一个 monorepo,自我描述是「自扩展的编码 agent 之家」。星标超过十万八千,MIT 协议,TypeScript。它不是一个单一 CLI,而是一套分层的包:harness、agent 运行时、统一 LLM API 各自独立可用。

三个核心包:@earendil-works/pi-coding-agent 是交互式编码 agent CLI;@earendil-works/pi-agent-core 是带工具调用与状态管理的 agent 运行时;@earendil-works/pi-ai 是统一多 provider 的 LLM API(OpenAI、Anthropic、Google 等)。另有四个支撑包:chord(独立的应用组合运行时,管服务、复制状态、RPC 与插件)、pi-telemetry(厂商中立的遥测契约、参考适配器、一致性测试与类型化 schema)、pi-durable(持久化的会话、任务与文档运行时)、pi-tui(带差分渲染的终端 UI 库)。

为什么它的分层值得看

多数 agent 项目把 LLM 接入、agent 循环、TUI 揉在一起,你要么整套用,要么不用。Pi 把它们切成可以单独取用的层:pi-ai 可以被任何需要统一多 provider 接口的应用拿走,即使它跟 agent 毫无关系;pi-tui 的差分渲染是终端 UI 的通用能力;chord 干脆是一个通用应用组合运行时。这种切分让「harness」这个词落到具体职责上——哪一层持有会话状态、哪一层负责工具调用、哪一层负责渲染,是分开的。

pi-telemetry 的存在尤其说明它的取向:遥测契约、参考适配器、一致性测试、类型化 schema 四件套齐全。这意味着 Pi 把「可观测」当作与「可运行」同级的一等目标,而不是事后补的日志。对一个 harness 来说,失败能不能被定位、成本能不能被归因,取决于遥测是不是一开始就在契约里。

「自扩展」(self extensible)是它给自己的标签,配合 chord 的插件能力,指向的是 agent 能在运行中扩展自己的能力集。这一点与 Hermes 的技能自生长、DeepSeek Harness 的插件挂载是同一问题的三种解法,值得并置比较。

权限与容器化:它诚实地写了自己不做什么

README 里最该被引用的一段是关于权限的坦白:Pi 不包含内置的权限系统来限制文件系统、进程、网络或凭据访问;默认情况下,它以启动它的用户与进程的权限运行。如果你需要更强的边界,请把 Pi 容器化或沙箱化。

它给出三种模式:Gondolin 扩展——把 pi 与 provider 认证留在宿主机,而把内置工具与 ! 命令路由进一个本地 Linux 微 VM;纯 Docker——整个 pi 进程跑在本地容器里做简单隔离;OpenShell——整个 pi 进程跑在策略控制的沙箱里。把「我没有权限系统」写在 README 正文、再给出三条替代路径,是一种负责的做法:它不假装安全,而是把安全的边界与责任划清楚交给部署者。

这条也解释了它在生态里的位置:orca 的 topics 里就带着 pi,说明 orca 把 Pi 当作可编排的 agent 之一。Pi 提供运行时,上层编排工具消费它。

治理与边界

README 顶部有一条治理声明:来自新贡献者的新 issue 与 PR 默认自动关闭,维护者每天审阅被自动关闭的 issue。这是一种高压力的维护策略——它用「默认拒绝」把维护者的注意力保护起来,代价是社区贡献的摩擦变大。读者应当知道这个项目的协作模式偏封闭,长期规划走 RFC(rfc.earendil.com 上的 pi 关键词)。仓库同时有 AGENTS.md,对人与 agent 同样生效。

官网 pi.dev 有 demo,文档在 pi.dev/docs/latest,README 还特意说你也可以直接让 agent 解释它自己。我们没有对 Pi 做过基准或复现测试;星标与它在编排生态里的位置说明它是这条脊柱上必须收录的一层。能力水位这一档记为待复现。