Pi

这是什么？适合谁？

Pi（earendil-works/pi）是一个极简、可扩展的终端 AI Agent 工具箱：统一多 Provider LLM API（OpenAI/Anthropic/Google 等）+ Agent 循环 + TUI 交互界面 + 编码 Agent CLI 打成一套可复用底座。它已发布 1.0 正式版，GitHub ★114k+，MIT 开源。官方一句话定位：「Pi is a minimal, extensible agent harness that you can make your own」——让 Pi 适应你的工作流，而不是反过来。

它解决的痛点：自研 Agent 时最耗时的不是 Agent 循环本身，而是模型接入、工具调用、会话上下文管理、终端界面这些重复胶水代码。Pi 把这些全部做成成品，并通过 extensions / skills / prompt 模板 / themes 四类机制让你定制，还能打包成 Pi packages 经 npm 或 git 分享。

适合谁：

• 想要一个开箱即用、又能深度定制的终端编码 Agent 的开发者
• 需要把 AI 编程嵌入 CI/CD 或脚本的团队（print 模式 / JSON 事件流 / RPC 三条自动化路径）
• 想基于成熟 Agent 底座做二次开发的应用作者（TypeScript SDK）
• 重视供应链安全的团队（依赖精确锁定 + min-release-age 防投毒）

不适合：偏好 GUI 的用户；只想「问一句答一句」的轻度对话用户；需要内置 sub-agents/plan mode 且不想自己装包的人（Pi 有意不内置这些）。

使用前提：Node.js 22.19+（安装器可代装）；LLM 订阅或 API Key；熟悉终端。

准备工作

• 设备：macOS / Linux / Windows 均有官方安装器；也支持 Android（文档专页）与 tmux
• 账号：任一 LLM Provider（OpenAI、Anthropic、Google 等，支持订阅或 API Key；也可接本地模型或兼容端点）
• 费用：Pi 本体免费开源；成本只在模型侧（自带 Key 按量计费，或用 ChatGPT/Claude 订阅登录）
• 前置知识：基本终端操作；扩展开发者需 TypeScript 基础
• 替代方案：Aider（git 集成更强）、Claude Code（闭源但内置功能多）、OpenHands（多 Agent 协作）

3 步快速上手

第 1 步：安装

macOS / Linux：

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

Windows（PowerShell）：

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

安装器会锁定全部依赖，之后用 pi update 自更新。也可以走 npm：npm install -g --ignore-scripts @earendil-works/pi-coding-agent（不锁传递依赖）。Nix 用户：nix run github:earendil-works/pi/stable。

第 2 步：连接模型并启动

cd /path/to/project
pi

在 Pi 内部运行 /login 连接订阅或 API Key，然后直接给 Pi 一个任务。它会检视文件、跑命令、编辑内容、推进多步任务。

第 3 步：跑通第一个任务

在项目目录里输入类似「帮我读一下 README 并总结这个项目的架构」，观察 Pi 的工具调用与文件检视过程；满意后可尝试 Esc 中断、会话分支等交互。预期产出：一次完整的 Agent 任务循环 + 可继续的会话。

常见踩坑

踩坑 1：Node 版本不够

• 现象：安装或启动报 Node 相关错误
• 原因：Pi 要求 Node.js 22.19 或更新
• 解决：用官方安装器（可代装 Node），或先升级本机 Node 再 npm -g 安装

踩坑 2：npm 装完少功能/行为异常

• 现象：npm 直装的 Pi 与官方安装器版本表现不一致
• 原因：官方安装器从 install-lock 锁定传递依赖，npm 包不锁
• 解决：优先用 pi.dev 安装脚本；已 npm 安装的可 pi update --self 切到锁定安装

踩坑 3：找不到 sub-agents / plan mode

• 现象：预期功能不存在
• 原因：Pi 有意不内置这些重功能，走「按需装包」路线
• 解决：在 Pi packages 文档 找对应包，或直接让 Pi 自己写一个扩展

踩坑 4：Windows 下终端体验问题

• 现象：TUI 渲染或键位异常
• 原因：Windows 终端差异
• 解决：按官方文档「Run Pi on Windows」专页配置推荐终端；也可用 tmux 方案

踩坑 5：给新贡献者的 PR 被自动关闭

• 现象：首次提 issue/PR 秒关
• 原因：仓库政策——新贡献者内容默认自动关闭，维护者每日复核
• 解决：不必惊慌，等维护者复核即可；详见仓库 CONTRIBUTING.md

踩坑 6：自动化模式选错

• 现象：脚本里拿不到想要的结构化输出
• 原因：print / JSON 事件流 / RPC 三种模式各有适用面
• 解决：一次性任务用 print；要消费结构化事件用 JSON 流；要长驻控制独立进程用 RPC（见文档 Reference 节）

初级用法

• 日常问答改代码：项目目录里直接描述需求，Pi 自动定位文件、编辑、跑测试
• 会话管理：继续或分支历史会话（探索不同方案不丢上下文），见文档「Manage Sessions and Context」
• 换模型：/login 切换订阅/Key；本地模型或兼容端点按「Run Local Models」「Add Custom Providers」配置
• 快速定制：用 prompt 模板固化常用指令；slash 命令列表见文档 Reference

高级玩法

• 让 Pi 改造自己：让 Pi 按你的工作流写一个 extension（如自定义审批流、专属工具），打包成 package 团队共享
• CI 集成：print 模式跑一次性脚本任务，JSON 事件流模式把 Pi 的每步动作接进自己的管线做审计
• RPC 服务化：把 Pi 作为常驻进程，用 RPC 协议从别的应用驱动它——适合自建「AI 后端」
• 虚拟模型路由：按任务类型路由到不同模型（贵模型管难题、便宜模型跑杂活），见「Route with Virtual Models」
• MCP 接入：Connect MCP Servers 一页接通外部工具生态

小技巧

• pi update 更新自身；装了 npm 版的用 pi update --self 迁移到锁定安装
• Nix 用户用 nix profile add github:earendil-works/pi/stable 固定版本，github:earendil-works/pi/v1.0.0 可钉死 tag
• 扩展开发前先读 packages/coding-agent/docs/extensions.md，四类定制机制别混用
• 主题（themes）也能打包分发，团队统一观感零成本
• 官方维护者会公开自己的真实工作会话（Hugging Face 数据集），学提示词与用法的好材料

进阶学习建议

要吃透 Pi，按「用 → 改 → 造」三层推进：

1. 用：跑通 Quickstart 后精读 How Pi Works（工具、上下文、会话、agent loop 的官方心智模型），再过一遍 Reference 节的 CLI / Settings / Environment Variables
2. 改：动手写第一个 extension（入口 packages/coding-agent/docs/extensions.md），再学 skills 与 prompt 模板（同目录 docs/），体会「harness 留白」的设计边界——为什么 sub-agents 不内置而是做成包
3. 造：研究 SDK（packages/coding-agent/docs/sdk.md）与 RPC 协议，把 Pi 嵌进自己的应用；进一步可看 chord（应用组合运行时）与 pi-ai（统一 LLM API）两个子包如何拆分关注点——这是 monorepo 架构的现成教材。真实集成案例可参考 OpenClaw 对 Pi 的接法

FAQ

Q1: Pi 免费吗？ A: Pi 本体 MIT 开源完全免费；你只需为自己连接的模型付费（API Key 按量或订阅登录）。

Q2: 和 Claude Code / Aider 比怎么选？ A: 要开箱即用的重度内置功能选 Claude Code；要强 git 集成选 Aider；要一个开源、可自托管、能按自己工作流深度定制的底座选 Pi。

Q3: 能接本地模型吗？ A: 可以，文档有「Run Local Models」专页，也支持任意兼容端点与自定义 Provider。

Q4: Windows / Android 能用吗？ A: 均有官方支持路径（安装脚本 + 文档专页），Nix 构建（源码）覆盖 ARM64/x86-64。

Q5: 团队怎么共享配置？ A: 把 extensions/skills/themes 打包成 Pi packages，经 npm 或 git 分发，成员 --package 安装即可。

参考链接

• GitHub 仓库 earendil-works/pi
• 官网 pi.dev
• 官方文档
• npm @earendil-works/pi-coding-agent

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。