一、它是什么
earendil-works/pi（项目名 Pi Agent Harness）是一个用 TypeScript 写的 AI agent 工具包，MIT 许可证，仓库创建于 2025-08-09，截至 2026-08-06 已积累 84648 star、10479 fork（star 实时变动，文中数字为当日快照），本周登上 GitHub 周榜第 10 名（周增长 4896）。
它不是一个单一的 CLI，而是一个 monorepo，把"做 agent"需要的几层能力拆成了五个可独立使用的 npm 包：
| 包名 | 职责 |
|---|---|
@earendil-works/pi-ai | 统一多 provider LLM API（OpenAI、Anthropic、Google 等） |
@earendil-works/pi-agent-core | agent 运行时，带 tool calling 与状态管理 |
@earendil-works/pi-coding-agent | 交互式编程 agent CLI |
@earendil-works/pi-tui | 终端 UI 库，差量渲染 |
@earendil-works/pi-telemetry | 厂商中立 telemetry 契约、参考适配器、一致性测试与类型化 schema |
官方一句话定位是 "AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI"，对应的就是上面五个包。项目主页在 pi.dev，文档在 pi.dev/docs/latest，Slack/chat 自动化在另一个仓库 earendil-works/pi-chat。
README 里反复出现的一个词是 "self extensible"（自扩展）——coding agent 本身被设计成可被扩展的 harness，而不是一个能力封闭的产品。
二、解决什么痛点
如果你自己拼过一个 LLM agent，大概率踩过这几块：
- 多 provider 适配碎。OpenAI、Anthropic、Google 三家的 API 形态、流式协议、tool calling schema 都不一样，每换一家就要重写一遍调用层。
pi-ai把这层统一掉，上层 agent 代码不因换模型而动。 - agent 运行时造轮子。tool calling 的循环、状态机、中断恢复、上下文管理，每次重写都容易出 bug。
pi-agent-core把这套运行时抽出来，带 tool calling 和 state management。 - TUI 自己写很痛。终端差量渲染、长输出滚动、流式 token 显示，手写费时。
pi-tui给了一套差量渲染的 TUI 库。 - telemetry 被厂商绑死。可观测性数据格式跟厂商 SDK 走，换 provider 就丢埋点。
pi-telemetry走厂商中立契约，带参考适配器和一致性测试。 - 编程 agent 要从零写。
pi-coding-agent直接给一个交互式 CLI，且可自扩展。 - 权限边界没人管。很多 agent 工具默认全权限跑，Pi 的 README 明确说"不内置权限系统"，转而给出三种容器化模式——这是个被认真对待的痛点，而不是被藏起来。
三、核心功能
1. 五个包，按需取用
Pi 的 monorepo 结构意味着你不必整体接入。只想要统一 LLM API？装 pi-ai。只想要 agent 运行时？装 pi-agent-core。想做自己的终端 agent UI？拿 pi-tui。这种"工具包"姿态和那些"一整个产品"的 agent 工具区别明显。
2. 自扩展的 coding agent
pi-coding-agent 是一个交互式编程 agent CLI，README 强调它是 "self extensible"。这意味着 agent 的工具集、行为不是封闭的，可以被扩展（具体扩展机制在 pi.dev/docs，README 未展开）。定位是 harness（外壳/框架），不是固定产品。
3. 权限与容器化（重点）
README 用了一整节讲这个，且开门见山：
Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it.
翻译过来就是：Pi 默认继承启动它的用户和进程的全部权限，不拦文件、进程、网络、凭证。要更强边界，就自己容器化或沙箱化。README 给了三种模式，文档链接在 packages/coding-agent/docs/containerization.md：
| 模式 | 做法 | 适用 |
|---|---|---|
| Gondolin extension | pi 和 provider 鉴权留在宿主，内置工具和 ! 命令路由进本地 Linux micro-VM | 想保留宿主便利又隔离工具执行 |
| Plain Docker | 整个 pi 进程跑在本地容器 | 简单隔离 |
| OpenShell | 整个 pi 进程跑在策略控制的沙箱 | 需要细粒度策略 |
这块对生产部署很关键——选 Pi 等于默认接受"权限要自己管"，但项目把方案写清楚了，不让你自己摸索。
4. 供应链加固（README 着墨最重的部分）
这是 Pi 区别于多数同类项目的地方，README 列了一长串措施，原样摘要点：
- 直接外部依赖精确 pin 版本，内部 workspace 包才用范围版本。
.npmrc设了save-exact=true和min-release-age=2——后者会挡掉发布不到 2 天的新依赖，规避当天投毒。package-lock.json是依赖真相源；pre-commit 默认拒绝 lockfile 提交，除非设了PI_ALLOW_LOCKFILE_CHANGE=1。- 发布的 CLI 包带
npm-shrinkwrap.json（从根 lockfile 生成），给 npm 用户 pin 传递依赖。 - Release smoke test 用
npm run release:local，在仓库外做隔离的 npm 和 Bun 安装再打 tag。 - CI 用
npm ci --ignore-scripts，外加定时 GitHub workflow 跑npm audit --omit=dev和npm audit signatures。 - shrinkwrap 生成对依赖的生命周期脚本有显式 allowlist，新生命周期脚本依赖会 fail check 直到人工 review。
对重视供应链的团队，这是一份相当完整的实践清单，甚至可以拿来对照自查自己的项目。
5. 共享 OSS coding agent sessions
README 末尾呼吁用户把用 Pi（或其他 coding agent）做开源工作时的 session 数据分享出来，理由是：公开的 OSS session 数据能帮改进 coding agent，比玩具 benchmark 更真实。发布工具是 badlogic/pi-share-hf，发布到 Hugging Face，作者自己持续发布 pi-mono 的 session 到 badlogicgames/pi-mono。如果你介意 session 被用作训练数据，这是要留意的口径。
四、三分钟上手
先说清楚：Pi 的 README 主要面向贡献者，终端用户的安装/使用细节在 pi.dev/docs。下面这些命令都是 README 里可直接抄的。
从源码跑（贡献者方式）
npm install --ignore-scripts # 不跑生命周期脚本，安装全部依赖
npm run build # 刷新模型数据，然后构建所有包
npm run build:offline # 用现有模型数据离线重建，无需联网
npm run check # lint + format + 类型检查
./test.sh # 跑测试（无 API key 时跳过依赖 LLM 的测试）
./pi-test.sh # 从源码运行 pi，可在任意目录执行--ignore-scripts 出现多次不是偶然——Pi 默认不信任依赖的生命周期脚本，这是上文供应链加固的一部分。
构建独立二进制（从 release 源码）
GitHub release 会带版本化的源码包，含 SHA256SUMS。解压后跑官方构建脚本：
VERSION="<release-version>"
tar -xzf "pi-${VERSION}-source.tar.gz"
cd "pi-${VERSION}"
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"--offline-model-data 用 release 自带的 provider 模型数据快照，不再去刷活体 provider catalog。脚本仍会装依赖、构建 monorepo、编译 Bun 可执行文件并布置运行时资产。包维护者若自己提供依赖，可加 --skip-install --skip-deps。
npm 包
@earendil-works/pi-coding-agent 已发 npm（README 有版本 badge），具体安装命令以 pi.dev/docs 为准。配置 provider 鉴权时，API key 形如 sk-xxx，按各 provider 的环境变量约定设置即可，README 未展开。
五、适合谁 + 踩坑
适合谁
- 想要可自扩展编程 agent 的开发者：
pi-coding-agent是 harness 而非封闭产品，能往里加东西。 - 需要统一多 provider LLM API 的团队：
pi-ai一层适配 OpenAI/Anthropic/Google，换模型不动上层。 - 不想在 agent 运行时上造轮子的人：
pi-agent-core把 tool calling 循环和状态管理做成了可复用包。 - TypeScript 生态团队：全 TS，类型化 schema、类型检查是构建流水线一部分。
- 重视供应链安全的团队：Pi 的依赖加固清单可直接当模板。
踩坑
- 没有内置权限系统。最大的坑。默认继承宿主用户/进程权限，意味着 agent 能读你私钥、能
rm -rf、能联网。生产环境务必按 README 三种容器化模式之一隔离。 - 新贡献者的 issue/PR 会被自动关闭。README 原话："New issues and PRs from new contributors are auto-closed by default." 这不是被无视，维护者每天会 review 自动关闭的 issue，但你第一次提 PR 看到被秒关别慌，是流程。
- README 不面向终端用户。安装、配置、用法细节在 pi.dev/docs，README 是给改源码的人看的。照 README 跑
npm run build之前，先确认自己是不是真要走贡献者路径。 min-release-age=2会挡新依赖。fork 后想加一个刚发布的新包，可能被 npmrc 规则挡住，要意识到这是项目有意的安全策略。- 带生命周期脚本的新依赖会 fail check。扩展依赖时，如果新依赖带 install 脚本且不在 allowlist，
npm run check会挂，需要走 review。 - session 数据默认可被分享。如果你用 Pi 做闭源/敏感项目，留意
pi-share-hf这条路是给 OSS session 用的，别把敏感 session 推到 Hugging Face。
六、和竞品比
coding agent CLI 这个赛道现在很挤，能和 Pi 放一起看的有 Claude Code、Aider、Cline、Cursor CLI 等。下表只陈述 Pi 这边 README 能核实的事实，不编造竞品数字，竞品一栏只点大众已知的定位方向，具体能力请各自查官方为准。
| 维度 | Pi Agent Harness（可核实） | 竞品（大众定位，不展开数据） |
|---|---|---|
| 形态 | monorepo，5 个包可单独用 | 多为单一 CLI/插件 |
| 语言 | TypeScript | 各异 |
| LLM provider | pi-ai 统一多家 | 多数绑 1-2 家或自带路由 |
| agent 运行时 | pi-agent-core 独立可复用 | 多数耦合在产品里 |
| TUI | pi-tui 差量渲染库独立 | 多为内置不可拆 |
| telemetry | pi-telemetry 厂商中立契约 | 多绑厂商 SDK |
| 权限 | 不内置，给 3 种容器化模式 | 各家策略不一 |
| 供应链 | 精确 pin + min-release-age + shrinkwrap + audit | 程度不一 |
| 自扩展 | coding agent 是 harness | 多为产品形态 |
| 许可证 | MIT | 各异 |
一句话差异化：Pi 把"做 agent"拆成了可单独取用的工具包，且把权限和供应链这两件多数同类不挑明的事挑明了写进 README。代价是终端用户文档不在 README 里，上手要绕到 pi.dev/docs；收益是你要自己拼 agent 时，几乎每一层都有现成包可用。
参考来源
- earendil-works/pi 仓库 README：https://github.com/earendil-works/pi
- 项目主页 pi.dev：https://pi.dev
- 文档：https://pi.dev/docs/latest
- npm 包 @earendil-works/pi-coding-agent：https://www.npmjs.com/package/@earendil-works/pi-coding-agent
- Pi RFC：https://rfc.earendil.com/keyword/pi/
- 容器化文档：
packages/coding-agent/docs/containerization.md（仓库内） - Session 分享工具：https://github.com/badlogic/pi-share-hf
- 作者 pi-mono session 数据集：https://huggingface.co/datasets/badlogicgames/pi-mono