CLI Pi 可自由定制的极简终端AI编码智能体

用终端里的 AI 编码工具，最怕的不是它不会写代码，而是它把工作流替你定死了。想要个子代理，它没有；不想要计划模式，它偏要塞一个；想接进自己的 CI，发现输出格式根本不给你控制。更麻烦的是模型绑定——今天用这家，明天想换，整套工具链推倒重来。earendil-works 团队的 Pi 走了另一条路：官方给自己的定位是「极简、可扩展、由你说了算的 agent 框架」（minimal, extensible agent harness that you can make your own）。它默认连子代理和计划模式都不带，你需要什么就装什么扩展，把适配工具的主动权交回开发者手里。这种「骨架优先」的思路，在动辄全家桶的终端智能体市场里反而成了一股清流。

Pi 不是一个单打独斗的命令行程序，而是一套完整的 monorepo。核心是交互式编码智能体 CLI，外围拆出了统一多供应商 LLM API、智能体运行时、终端 UI 库、插件热重载框架、持久化对话运行时和遥测契约七个包。这意味着你既可以直接用它写代码，也可以只取其中某个包，给自己的产品搭一套 agent 基础设施。项目采用 MIT 协议，TypeScript 编写，当前版本 v1.4.0，最近一次更新在 2026 年 10 月 24 日，GitHub 星数已超过 11.7 万，是近期终端智能体方向关注度最高的新项目之一。

项目基本信息

一、项目介绍

Pi 的本体是 @earendil-works/pi-coding-agent，一个跑在终端里的编码智能体。你在项目目录里启动它，用自然语言描述任务，它读取仓库文件、调用工具、给出可审查的改动。但 Pi 真正区别于 Claude Code、Codex CLI 等同类的，是它的「可拆性」。整个仓库由七个包组成：pi-ai 提供统一的多供应商 LLM API，OpenAI、Anthropic、Google 等主流供应商一套接口打通；pi-agent-core 是带工具调用和状态管理的智能体运行时；pi-tui 是自研的差分渲染终端 UI 库；chord 是可热重载插件的宿主运行时；pi-durable 负责持久化的对话、任务与文档；再加上遥测契约和 CLI 本体。

在形态上，Pi 支持四种用法：交互式使用、print 或 JSON 模式的脚本自动化、通过 RPC 被其他程序远程控制、以及直接用 TypeScript SDK 把 agent 嵌进自己的应用。官方文档明确提到，OpenClaw 这类产品就是基于 Pi 做的真实集成。对个人开发者，它是终端助手；对团队，它是一块可以复用的 agent 基础设施。

二、核心优势

第一，定制自由度是同类里少见的。扩展（extensions）、技能（skills）、提示词模板、主题都可以自己写，打成 Pi package 后通过 npm 或 git 分发。官方默认故意砍掉子代理和计划模式，把「要不要」的决定权还给用户。

第二，统一 LLM API 屏蔽了供应商差异。pi-ai 把 OpenAI、Anthropic、Google 等接口收拢到一套类型安全 API 下，换模型、做多模型 fallback 不用改业务代码。这对怕被单一厂商锁死的团队很有吸引力。

第三，供应链安全是被当作一等大事来做的。项目把 npm 依赖变更视为代码变更来审查：直接依赖全部锁精确版本，.npmrc 设置 save-exact=true 和 min-release-age=2（拒绝安装当天发布的新版本，防范投毒），CI 定期跑 npm audit 及签名校验，安装脚本只从锁文件生成的 install-lock 安装。在一堆「curl 一把梭」的安装脚本里，这份严谨相当少见。

第四，形态全覆盖。交互模式给人用，print/JSON 模式给脚本用，RPC 给程序用，SDK 给产品集成用。同一个智能体内核，四种接入方式。

第五，官方坦承没有内置权限系统，并给出三条容器化路线（Gondolin 微虚拟机、纯 Docker、OpenShell 沙箱）。这种「不装安全」的诚实，比声称自己安全更值得信任。

三、适用场景

想把终端 agent 嵌进自有研发流程的团队：用 SDK 或 RPC 把 Pi 包进内部工具，比从零调各家模型 API 省事。需要在 CI 里做自动化修复的工程场景：print/JSON 模式输出结构化结果，方便流水线消费。二次开发 agent 产品的创业者：七个包可以按需取用，不用背上一整个全家桶。对依赖安全敏感的企业：精确锁版本加最小发布龄策略，能挡住大部分供应链投毒。个人极客：喜欢「我的工具我定制」的人，会在 Pi 的扩展体系里找到乐趣。

四、安装教程

macOS 或 Linux 推荐官方安装脚本，它会锁定全部依赖，之后用 pi update 自我更新：

curl -fsSL https://pi.dev/install.sh | sh

Windows 使用 PowerShell：

powershell -c "irm https://pi.dev/install.ps1 | iex"

也可以用 npm 直接安装（注意：npm 途径不锁定传递依赖，官方脚本才会）：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Nix 用户一条命令跑最新稳定版：

nix run github:earendil-works/pi/stable

常见报错：其一，Node 版本低于 22.19 会直接启动失败，官方安装器会尝试自动装 Node，npm 途径需自行升级。其二，用 npm 装完后发现依赖版本和官方脚本装的不一致，这是设计差异——脚本从 install-lock 安装并锁定传递依赖，npm 包不锁定。其三，在服务器上通过 SSH 使用时如遇权限报错，优先考虑按官方文档用容器模式运行，而不是放宽目录权限。

五、使用示例

安装完成后进入项目目录，直接输入 pi 启动：

cd /path/to/project
pi

首次使用在 Pi 界面内执行 /login，连接你的订阅或 API key，然后用自然语言下达任务，比如「把这个模块里的回调重构为 async/await，并补上单元测试」。Pi 会先读取相关文件，再给出文件改动，每一步都有日志，确认后落盘。日常更新用 pi update 一条命令搞定。

除了交互模式，Pi 还支持 print 与 JSON 两种非交互模式，官方 CLI 文档里给出了完整参数，适合写进脚本或 CI：同一个任务既可以有人在环里逐步确认，也可以无头跑完后拿结构化结果做后续处理。配合 Git 使用时，所有改动都是标准文件差异，git diff 审查、git checkout . 撤销，回滚成本为零。

六、常见问题

问：Pi 没有内置权限系统，跑在生产机器上安全吗？答：官方明确不提供文件系统、进程、网络的细粒度限制，默认以启动用户的权限运行。需要边界就用容器化：Gondolin 扩展把工具调用路由进本地 Linux 微虚拟机，或用 Docker 跑整个进程，或用 OpenShell 策略沙箱。

问：为什么官方脚本和 npm 装的依赖不一样？答：脚本从锁文件生成的 install-lock 安装并锁定传递依赖，npm 包按常规语义解析，这是两种策略的差异，按对供应链的要求选择即可。

问：Nix 构建为什么强调离线？答：Nix 构建过程不联网，捆绑的模型目录来自固定修订版，运行时会再从 pi.dev 叠加更新的目录数据。需要手动刷新时执行 npm run update:model-catalog-pin。

问：想提交issue 为什么被自动关闭？答：项目默认自动关闭新贡献者的 issue 和 PR，维护者每天复审，这是为了控制噪音，正常讨论走 Discord。

七、总结

Pi 的价值不在功能多，而在「把控制权还给开发者」。统一 LLM API、可插拔的扩展体系、四种运行形态和一套认真的供应链安全实践，让它既能当个人终端助手，也能当企业 agent 基础设施的地基。如果你受够了被工具的工作流绑架，或者正打算自建 agent 平台，Pi 是这个方向最值得研究的开源项目之一。当然它也有门槛：极简意味着很多能力要自己装，对想要开箱即用全家桶的用户，现成的大型 CLI 可能更合适。