一、什么是 Pi
Pi 是由 Earendil Inc. 开发并维护的开源、终端优先的编码智能体脚手架(Agent Harness),官方网站为 pi.dev。它的口号是:
"There are many agent harnesses, but this one is yours."(世上有许多智能体脚手架,但这一款属于你。)
核心理念:Pi 是极简的智能体脚手架——"让 Pi 适应你的工作流,而不是让你的工作流去迁就 Pi"(Adapt Pi to your workflows, not the other way around)。与那些"内置一切功能"的封闭智能体不同,Pi 刻意保持核心小巧,通过扩展(Extensions)、技能(Skills)、提示词模板(Prompt Templates)、主题(Themes) 四大机制无限扩展能力,并可打包成 Pi Packages 通过 npm 或 git 分享给社区。
Pi 默认开箱即用,但刻意不内置子代理(sub-agents)和计划模式(plan mode)等重功能——你可以直接要求 Pi 为你构建这些功能,或者安装一个符合你习惯的第三方包。
二、技术架构
Pi 是一个 Monorepo,包含多个独立 npm 包:
包 | 作用 |
|---|---|
@earendil-works/pi-coding-agent | 交互式编码智能体 CLI(核心产品) |
@earendil-works/pi-agent-core | 智能体运行时:工具调用与状态管理 |
@earendil-works/pi-ai | 统一多提供商 LLM API(OpenAI、Anthropic、Google 等) |
@earendil-works/pi-tui | 差分渲染终端 UI 库 |
@earendil-works/pi-telemetry | 供应商中立的遥测契约与适配器 |
模型默认拥有四个核心工具:read(读文件)、write(写文件)、edit(打补丁)、bash(执行 Shell 命令),另有 grep、find、ls 等只读工具。
三、核心特色
1. 极简核心,随时自我改造
Pi 不是"密封产品"。缺命令、工具、提供商、工作流或 UI 调整?直接让 Pi 现场构建,然后 /reload 继续使用——它会在运行中改造自己,这体现了"原语而非功能"(Primitives, not features)的设计哲学:其他工具内置的功能,在 Pi 里都可以自己拼装。官方提供 50+ 示例扩展,涵盖子代理、计划模式、权限门(permission gates)、路径保护、SSH 执行、沙箱、MCP 集成、自定义编辑器、状态栏等。
2. 15+ 提供商、数百模型,会话中随时切换
支持 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi For Coding、MiniMax、NVIDIA、OpenRouter、Ollama 等,可用 API Key 或 OAuth 认证。会话中可用 /model 或 Ctrl+L 切换模型,Ctrl+P 在收藏模型间循环;还可通过 models.json 或扩展添加自定义提供商。
3. 树状、可分享的会话历史
会话以树结构存储,所有分支保存在单个文件中。/tree 可回退到任意历史节点并从此处继续,/fork 从历史消息派生新会话,/clone 克隆当前分支。/export 导出 HTML/JSONL,/share 上传为私有 GitHub gist 并生成可渲染的分享链接。
4. 真正的"上下文工程"
Pi 的极简系统提示词 + 高度可扩展性,让你精确掌控进入上下文窗口的内容:
AGENTS.md:启动时从 ~/.pi/agent/、父目录与当前目录加载项目指令;
SYSTEM.md:按项目替换或追加默认系统提示词;
压缩(Compaction):接近上下文上限时自动摘要旧消息,可通过扩展完全自定义(如按主题压缩、代码感知摘要、使用不同摘要模型);
技能(Skills):按需加载的能力包,渐进式披露且不破坏提示缓存;
提示词模板:Markdown 格式的可复用提示词,输入 /名称 即可展开;
动态上下文:扩展可在每轮前注入消息、过滤历史、实现 RAG 或长期记忆。
5. 运行中转向与跟进
智能体工作时可随时提交消息:Enter 发送转向消息(当前工具执行完后交付,并中断其余工具调用);Alt+Enter 发送跟进消息(等待智能体完成全部工作后交付)。
6. 四种运行模式
模式 | 用途 |
|---|---|
交互式(Interactive) | 完整的 TUI 体验 |
打印/JSON(Print/JSON) | pi -p "query" 适合脚本;--mode json 输出结构化事件流 |
RPC | 基于 stdin/stdout 的 JSON 协议,供非 Node 程序集成 |
SDK | 将 Pi 嵌入自己的 Node.js 应用(OpenClaw 即真实案例) |
7. 默认没有的东西,就是它的哲学
Pi 明确不内置 MCP、子代理、权限弹窗、计划模式、待办清单与后台 bash——需要时要么用扩展/包构建,要么借助外部工具(tmux、容器等)。比如要并行子代理?用 tmux 派生多个 Pi 实例,或安装对应扩展;要沙箱?用 Gondolin、Docker 或 OpenShell 容器化运行。
四、安装与上手
# 方式一:一键脚本(Linux / macOS)
curl -fsSL https://pi.dev/install.sh | sh
# 方式二:PowerShell(Windows)
powershell -c "irm https://pi.dev/install.ps1 | iex"
# 方式三:npm / pnpm / bun
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
安装后输入 pi 即可开始对话;订阅型提供商用 /login 认证,或用 API Key(如 ANTHROPIC_API_KEY)。支持 Windows、Termux(Android)、tmux 等平台。
五、与 Prime Agent 的关系
值得注意:同样开源的 Prime Agent(Prime Intellect 的自改进 RLM 智能体)其 TUI 正是基于 Pi 构建的,二者同属"极简可扩展 Harness"这一设计潮流,但定位不同——Prime Agent 面向长时程自主任务与"模型—脚手架共同学习",而 Pi 更强调"极简核心 + 高度定制 + 融入个人工作流"。
六、基于 Pi 构建的 Agent
Pi 作为可嵌入、可扩展的极简 Harness,已被多个项目用作底层运行时或改造基础,形成了一定规模的"Pi 生态":
Prime Agent(Prime Intellect)——自改进 RLM 编码智能体,其 TUI 正是基于 Pi 构建的(详见上文第五章及 Prime Agent 文档)。Pi 提供终端界面,Prime Agent 在其上实现 RLM 递归子代理与 Continual Harness 自改进机制。
OpenClaw ——开源 AI 助手与消息网关。它是 pi.dev 官方点名的 Pi SDK 真实集成案例:不通过子进程或 RPC,而是直接 createAgentSession() 把 Pi 的 AgentSession 嵌入自身架构,接入 Discord/Telegram/Slack/WhatsApp 等渠道;可注入自定义工具(消息、沙箱、渠道动作)、按渠道定制系统提示词,并复用 Pi 的树状会话、压缩与多账户认证轮换能力。
agent-pi(ruizrica/agent-pi)——把 Pi 改造成多智能体编排平台的扩展套件:43 个扩展、11 个主题、20+ 技能,提供 NORMAL / PLAN / SPEC / PIPELINE / TEAM / CHAIN 六种运行模式,支持团队分发、顺序链、并行流水线,并内置安全加固(破坏性命令拦截、提示注入检测、防数据外泄)与浏览器端计划审查/回滚界面。
pi-agent(pascal-de-ladurantaye/pi-agent)——个人工作流定制包:bash-guard(执行前并行 LLM 安全审查)、goal(Codex /goal 风格自主目标)、session-memory(会话转 Obsidian 知识库)、snapshot(每轮影子 git 快照)等。
其他典型生态包——多数以扩展/包形式增强或改造 Pi:
小结:其中 Prime Agent 与 OpenClaw 是独立的完整智能体产品,其余多为扩展/包形态——这正体现了 Pi"提供原语而非功能、让每个人定制自己的 agent"的生态哲学。
参考来源:pi.dev 官网 | earendil-works/pi (GitHub) | @earendil-works/pi-coding-agent (npm)
