产品与定位
Pi（全称 Pi Agent Harness）由 Mario Zechner（@badlogic / @mariozechner）创建，是一个刻意保持极简的终端编码 Agent 框架。它的设计取向与主流 Agent 相反：不预置一堆功能，而是只提供稳定的内核（统一 LLM API、Agent 循环、TUI、编码 Agent CLI），其余能力全部交给 TypeScript 扩展自行拼装。
这个取向决定了它的适用人群：愿意动手写扩展、希望完全掌控 Agent 行为的开发者，会得到极高的自由度；只想开箱即用的人则会觉得缺东西。
仓库地址注意：项目原地址为
github.com/badlogic/pi-mono，现已迁移并更名为github.com/earendil-works/pi（npm 包同步为@earendil-works/pi-coding-agent）。旧的badlogic/pi-mono链接会重定向，但引用时应使用新地址。
功能速览
| 功能 | 说明 |
|---|---|
| 树状会话 | 会话以树存储，可回到任意历史节点继续，所有分支保存在同一文件 |
| 四种运行模式 | 交互式 TUI、打印模式（pi -p、--mode json）、RPC（stdin/stdout JSON）、TypeScript SDK |
| 多供应商 | 15+ 供应商、数百模型，支持 API Key 或 OAuth，/model 与 Ctrl+P 切换 |
| 自定义供应商 | 通过 models.json 声明任意 OpenAI 兼容 / 兼容端点 |
| 扩展体系 | extensions、skills、prompt templates、themes 均为 TypeScript |
| Pi Packages | 支持 pi install npm:@foo/pi-tools、git:github.com/...，/reload 热重载 |
| 上下文工程 | AGENTS.md 启动加载、SYSTEM.md 替换系统提示、自动 compaction、skills 渐进披露 |
| 会话分享 | /export 导出 HTML、/share 上传 GitHub Gist 生成可读链接 |
常用命令
| 命令 | 作用 |
|---|---|
pi | 启动交互式 TUI |
pi -p "问题" | 单次提问并退出 |
/model | 切换模型 |
/tree | 跳转到会话树中的任意历史节点 |
/export / /share | 导出或分享当前会话 |
调用与兼容性
# npm 安装（需要 Node.js ≥ 22.19.0）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# macOS / Linux 安装脚本
curl -fsSL https://pi.dev/install.sh | sh版本与更新注意
- 当前版本 v0.87.0（2026-09-21 发布），MIT 许可，仓库约 108,499 stars（截至 2026-09-22）。
- 官方明确不内置以下能力，需要靠扩展或第三方 Pi Package 补齐：MCP、sub-agents、权限确认弹窗、plan mode、todo 列表、后台 bash。选型时这是最关键的一条。
- Pi 官方不提供权限/沙箱系统：默认以启动它的用户权限运行，需要更强隔离请自行容器化（官方文档给出 Gondolin 微虚拟机、Docker、OpenShell 三种模式）。
- 迭代节奏很快，v0.87.0 引入了若干 breaking changes（如移除
shouldStopAfterTurn、SessionManager成为 provider 上下文的唯一权威），扩展作者升级前务必读 changelog。 - 供应链策略较严：直接依赖锁定精确版本、
package-lock.json为唯一事实源、发布包附带npm-shrinkwrap.json。 - 社区有大量 fork（曾出现
pt-act/pi-mono、radicor/pi-mono等镜像），引用时只认earendil-works/pi。
选型建议
- 想完全掌控 Agent 行为、愿意写 TypeScript 扩展 → Pi 的抽象层次最干净。
- 需要树状会话、频繁回溯和分支探索的复杂任务 → 树状会话是 Pi 的差异化能力。
- 需要开箱即用的 MCP / 子代理 / plan mode → 直接选 OpenCode 或 Oh My Pi，后者正是基于 Pi 补齐这些能力的派生版本。
- 对企业合规要求高、需要内置权限管控 → Pi 需要额外自行加固，不如 Claude Code、Copilot CLI 省心。