Pi Agent 工具包上手：多供应商 LLM 框架怎么装、怎么构建、能拿来干什么
数据截至 2026-07，构建方式与功能以 GitHub 仓库 earendil-works/pi 为准。
Pi 值得看一眼的理由不是”又一个 Agent 框架”，而是它把供应链加固当成了正经功能——依赖全部锁版本、带 shrinkwrap 校验，并且给出了容器化沙箱的落地方案。 在一个大家都在比谁的 Agent 更能自动改代码的时间点上，愿意花力气在”怎么不让它把你的机器搞坏”上的项目并不多。
先说清楚安装这件事：它的编码 Agent CLI 是发布到 npm 的正式包，全局装一条命令就行；同时仓库也保留了完整的源码构建流程和打独立二进制的脚本。这三条路各有各的场景，第二节会分开说。想直接照着走一遍的，可以看本站更细的那篇开源编程 Agent pi 从安装到跑通第一个任务。
一、它其实是三个包
Pi 不是单一工具，而是分了三层，这个拆分方式本身就说明了它的定位：
pi-ai：统一的多供应商 LLM API，覆盖 OpenAI、Anthropic、Google 等。如果你打算把国产模型也接进来，国产大模型 API 价格对比可以帮你先把成本算清楚。pi-agent-core：Agent 运行时，负责工具调用和状态管理。pi-coding-agent：交互式的编码 Agent CLI。
这个分层的实际意义是：你可以只用底下两层来搭自己的 Agent，而不必接受它那个 CLI 的交互设计。对于想自建 Agent 产品的团队，pi-ai + pi-agent-core 这个组合比一整套端到端工具更有价值——你要的是引擎，不是整车。
反过来，如果你只是想要个终端里能用的编码助手，直接装它的 CLI 包就行，底下两层不用管。
二、三种装法，按场景选
一、直接装 CLI（多数人该走这条）。 文档给的是全局安装：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
--ignore-scripts 禁止依赖包在安装时执行自己的脚本，而这正是供应链攻击最常见的入口。文档里特别说明了它不依赖安装脚本，所以加这个参数不影响正常使用。仓库另外提供了 curl 安装器，走的也是全局 npm 这条路，卸载时按你当初用的那个包管理器卸即可。
二、从源码跑（要改它、要读它的人走这条）。 仓库根目录的流程是：
npm install --ignore-scripts
npm run build
./pi-test.sh
同样的 --ignore-scripts 不是随手加的。它禁止依赖包在安装时执行自己的脚本，正是供应链攻击最常见的入口。Pi 把这个参数写进标准流程，和它整体的加固思路是一致的。
三、打独立二进制（内网部署、要可复现构建的走这条）。 仓库给了打包脚本：
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"
--offline-model-data 意味着模型元数据被打进产物，构建出来的二进制不依赖联网去拉配置。对于要部署到内网、或者要保证构建可复现的场景，这一条挺关键。
三、供应链和沙箱：Pi 真正的差异点
这部分是我认为它值得单独写一篇的原因。
依赖锁定 + 随包发布的 shrinkwrap。 常规项目用 package-lock.json 就算完事了，而 lock 文件不会跟着 npm 包发出去，装包的人拿到的传递依赖只是”符合版本范围”，不是”和作者当时那棵树一模一样”。Pi 的做法是：直接外部依赖锁到确切版本，再从根 lock 文件生成一份 shrinkwrap 随 CLI 包一起发布，让 npm 用户拿到的传递依赖也是钉死的。它的检查命令里就带着对这份 shrinkwrap 的校验，CI 用 npm ci --ignore-scripts 安装，另有定时任务跑依赖审计与签名审计。
容器化沙箱。 仓库给出了 Gondolin、Docker、OpenShell 几种沙箱化的模式。这件事的重要性经常被低估——一个能自主执行 shell 命令的 Agent，本质上就是把一个不完全可控的进程放在了你的开发机上。跑在容器里和跑在宿主机上，出事时的代价差一个数量级。
如果你打算让 Agent 无人值守地跑批量任务，先解决沙箱再谈能力，这个顺序不要反。
四、另外两个细节
差分渲染的终端 UI 库。 Pi 自带了一套 TUI 库，用差分渲染而不是整屏重绘。这个在长会话、大量输出滚动的时候差别很明显——整屏重绘会闪、会卡，差分渲染不会。这块代码本身也可以单独拿来用。
自扩展的编码 Agent。 仓库描述里提到 Agent 是 self-extensible 的，也就是它能给自己加工具。这个方向很有意思，但也正是上面沙箱那一条为什么重要——一个能给自己加能力的东西，边界必须由外部来划。
五、和常见 Agent 框架的定位差异
如果你已经在用别的框架，Pi 放在哪个位置上比较容易理解？
和 LangChain 比，Pi 的抽象层薄得多。LangChain 想把从数据加载到链式编排的整条路都包进来，好处是现成组件多，代价是你要接受它的一整套概念。Pi 只做三件事：抽象供应商差异、跑 Agent 循环、提供一个 CLI。想要什么额外能力自己加。对于”我只需要一个稳的 Agent 循环，别的我自己写”的团队，薄反而是优点。
和 AutoGen、CrewAI 比，那两个的重心在多智能体协作的编排范式上——谁跟谁对话、怎么分角色。Pi 的重心明显不在这儿，它更关心单个 Agent 怎么跑得稳、怎么跑得安全。
和端到端的成品编码助手比，Pi 除了那个 CLI，还把底下的引擎单独发成了包。也就是说同一个项目既能当成品用，也能拆开当零件用，这是它和只提供成品的工具在形态上的区别。
所以选型判断可以简化成一句：你是要用 Agent，还是要造 Agent。 只想用，装那个 CLI 就够了；想造，pi-ai 和 pi-agent-core 这两层才是你要看的地方。
六、沙箱方案怎么选
仓库给了 Gondolin、Docker、OpenShell 几种，实际选哪个可以按隔离强度和上手成本来权衡。
Docker 是最稳妥的起点。 大多数团队机器上本来就有，把工作目录挂进去、限制网络出口，一条命令就能起来。缺点是每次启动有开销，而且容器内外的文件权限映射在 Linux 上偶尔要额外调。
更轻的方案适合高频短任务。 如果你的 Agent 是被频繁调起、每次只跑几秒，容器启动开销会变得明显，这时候轻量隔离更合适。
判断隔离够不够，看三条： 它能不能读到工作目录之外的文件（尤其是 ~/.ssh、~/.aws 这类）；它能不能往外发网络请求，能发到哪些地址；它退出之后有没有留下东西。这三条里任何一条你答不上来，就说明当前的隔离还不能让它无人值守。
有个容易被忽略的点：把凭证挂进沙箱等于没有沙箱。 很多人为了让 Agent 能提交代码，直接把 SSH key 挂了进去，那前面所有隔离工作就白做了。正确做法是让 Agent 只产出改动，提交推送这一步留在沙箱外由你执行。
七、要不要现在用
按场景给个判断：
- 想自建 Agent 产品：值得认真看
pi-ai和pi-agent-core，MIT 协议、多供应商抽象已经做好，比从零写省事。想先看全景，走开源编程 Agent pi 是什么那篇。 - 要过安全审查的团队：它在供应链和沙箱上的做法可以直接拿去参考，哪怕最后不用它的代码；隔离方案怎么选见pi 没有内置权限系统。
- 只想要个好用的终端编码助手：直接装 CLI 包即可，不必碰源码构建那条路。
还有一点值得提醒：star 数涨得快不等于生产可用。这类项目早期迭代很密，接口随时可能变。如果你打算把它接进正式链路，锁一个具体的提交或版本号，别直接跟主分支——否则某天一次例行拉取就可能让构建断掉，而你还得花时间去比对到底哪个接口改了。
小结
Pi 是个分三层的 Agent 工具包，MIT 协议，CLI 可以直接从 npm 装，也可以从源码构建或打成独立二进制。它的技术亮点不在”Agent 能力有多强”，而在把供应链加固和沙箱隔离当成一等公民——--ignore-scripts、直接依赖锁死、随包发布的 shrinkwrap、离线模型数据、几种容器化模式，这些都写在了仓库的说明里，可以直接拿去核对。
拿它当引擎自建东西，从 pi-ai 和 pi-agent-core 看起；只想用，装 CLI 就行。
Sources: