跳转至

Pi (pi.dev)

概述

Pi 是一款极简的开源终端编程智能体运行框架（harness），其核心设计理念只有一条：编程智能体只需要四个工具——read、write、edit、bash，以及一段不超过 1,000 个 Token 的系统提示词。其余所有功能均通过类型化的 TypeScript 扩展系统按需启用。

Pi 由 libGDX 的作者 Mario Zechner 创建，以 MIT 许可证发布，源码托管在 earendil-works/pi monorepo 中。它的定位是一个可自由重塑的编程智能体运行框架：商业工具倾向于内置大量功能，而 Pi 只提供极简核心，并将工具、上下文管理、技能、主题和界面等每个维度都设计为可替换的组件。

Pi 的设计直接体现了 智能体 = 模型 + 运行框架 这一等式：四工具核心是运行框架的基础层，扩展系统则让团队能够围绕自身工作流重构运行框架，而无需反过来将工作流迁就工具。

核心架构

四个内置工具

Pi 完整的内置工具集如下：

工具 说明
read 读取工作目录中的文件内容
write 创建新文件
edit 修改已有文件（精准编辑，非整体重写）
bash 执行 Shell 命令

这套四工具核心来自对前沿模型行为的一个观察：模型在无需大量脚手架的情况下，已经具备理解编程智能体任务的能力。不超过 1,000 个 Token 的系统提示词加上四个工具，足以实现出色的编程行为；额外的工具和提示词均为情境性需求，按需启用即可。

刻意的功能留白

Pi 明确省略了其他编程智能体中常见的若干功能。每一处省略都是设计决策，而非缺失：

功能 Pi 的立场 扩展路径
MCP 支持 不内置；CLI 工具通过 README 接入 通过扩展构建 MCP 集成
子智能体 不内置 可通过扩展或第三方 Pi 包实现
权限弹窗 不内置；Pi 倾向于使用容器隔离 通过扩展构建自定义审批流
计划模式 不内置 使用文件记录计划或自定义扩展
待办事项跟踪 不内置 使用文件或自定义扩展
后台 Bash 不内置；推荐使用 tmux 以保障可观测性 —

这一设计哲学避免了功能膨胀——功能过多会导致更重量级工具中的上下文管理能力和可读性下降。用户只构建工作流真正需要的功能，不多一分。

组件包

Pi 是一个包含六个包的 TypeScript monorepo：

包 职责
@mariozechner/pi-ai 统一的多厂商 LLM API（Anthropic、OpenAI、Google、Azure、Bedrock 等）
@mariozechner/pi-agent-core 运行时引擎：工具调用、状态管理、会话生命周期
@mariozechner/pi-coding-agent 交互式编程智能体 CLI——面向用户的主要产品
@mariozechner/pi-tui 支持差量渲染的终端 UI 库
@mariozechner/pi-web-ui 用于 AI 对话界面的 Web 组件
@mariozechner/pi-pods 管理 GPU Pod 上 vLLM 部署的 CLI

Slack 集成组件（pi-mom）将消息委托给编程智能体处理，支持通过 Slack 进行对话式编程工作流。

定制化框架

Pi 的可扩展性模型分为四个层次，可打包为可共享的 Pi 包：

扩展（Extensions）

具备完整系统访问权限的 TypeScript 模块。扩展可以： - 添加自定义工具 - 注册命令和键盘快捷键 - 处理事件并注入 UI 组件 - 在每轮对话前注入消息（前馈上下文） - 过滤消息历史（上下文管理） - 实现 RAG 或自定义检索 - 构建长期记忆 - 添加子智能体生成、权限门控、SSH 执行、MCP 集成或自定义编辑器

扩展覆盖了运行框架的完整能力面——其他工具内置的任何功能，都可以作为 Pi 扩展来实现。

技能（Skills）

遵循 Agent Skills 规范的可复用智能体能力。技能通过 /skill:name 调用——既可由用户手动触发，也可由智能体根据上下文自动触发。技能实现了渐进式信息披露模式：能力定义按需加载，而非在每轮对话中全量注入。

提示词模板（Prompt Templates）

本地存储的可复用 Markdown 提示词，通过 /templatename 语法展开。模板支持 {{ variable }} 插值，可用于参数化工作流。

主题（Themes）

支持热重载的视觉定制功能。内置选项包括 dark 和 light；同时支持自定义主题。

Pi 包（Pi Packages）

将扩展、技能、提示词和主题打包在一起，通过 npm 或 git 分发。安装时支持固定版本号和 HTTPS 来源：

pi install @myorg/pi-package
pi install git+https://github.com/user/pi-package#v1.2.0

多厂商支持

Pi 不绑定特定服务提供商，采用自带密钥（bring-your-own-key）模式。同一套智能体循环可在任意支持的服务商上运行，无需修改代码：

  • 订阅制：Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro、GitHub Copilot
  • API 密钥方式：Anthropic、OpenAI、Azure OpenAI、Google Gemini、Vertex AI、Amazon Bedrock、DeepSeek、Groq、Cerebras、Mistral、xAI、OpenRouter、Vercel AI Gateway、Cloudflare，以及国内市场平台等
  • 本地模型：Ollama 及兼容的本地推理服务器

用户可通过 /model 或 Ctrl+L 在会话中途切换服务商。

会话管理

会话以 JSONL 文件形式存储，采用树形结构，支持原地分支而无需复制文件。会话按工作目录自动保存至 ~/.pi/agent/sessions/。

功能 说明
分支（Branching） /tree 命令导航会话树，可跳转到任意历史节点并从该点继续
派生（Forking） 从任意历史用户消息创建新会话
克隆（Cloning） 将当前活跃分支复制到新的会话文件
压缩（Compaction） 在接近上下文窗口限制时，自动或手动对历史消息进行摘要；可通过扩展完全自定义

上下文与项目集成

Pi 从全局目录（~/.pi/）和项目本地目录（.pi/）中的 AGENTS.md 与 CLAUDE.md 文件加载上下文。项目专属的指令和规范在会话启动时注入——与上下文工程策略中记录的机制一致。

配置文件位于 ~/.pi/agent/settings.json（全局）或 .pi/settings.json（项目范围）。

程序化集成

除交互式使用外，Pi 还支持四种运行模式：

模式 应用场景
交互式（默认） 面向开发者的终端智能体
打印 / JSON 脚本化调用，输出结构化结果
RPC 通过 stdin/stdout 上严格的换行符分隔 JSONL 进行进程集成
SDK 直接在 Node.js 应用中嵌入智能体会话 
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

供应链安全

Pi 采用了在开源智能体工具中并不常见的供应链安全实践：

  • 对所有外部依赖固定精确版本号
  • 锁文件校验与受控生命周期脚本
  • 生成 Shrinkwrap 以确保可复现安装
  • 通过 CI 工作流进行自动化安全审计

与其他编程智能体运行框架的对比

维度 Pi Claude Code Flue OpenCode
核心工具数 4（read、write、edit、bash） 40+ 文件系统 + Shell + grep + glob 6（read、write、edit、bash、browser、search）
系统提示词大小 < 1,000 个 Token ~55,000 个 Token 可配置 ~15,000 个 Token
可扩展性 TypeScript 扩展 + 包 Hooks + MCP TypeScript + 技能 插件
MCP 支持 通过扩展 原生支持 原生支持 原生支持
子智能体 通过扩展 原生支持 通过任务 原生支持
LLM 服务商 15+（自带密钥） 仅限 Claude（Anthropic） 多服务商 75+
后端 无（零 SaaS） Anthropic 云 可选 无
许可证 MIT 专有 Apache-2.0 MIT
主要语言 TypeScript TypeScript TypeScript TypeScript / Rust

最佳实践

挑战 / 场景 描述 解决方案 / 建议
一开始就启用过多扩展 从一开始就违背了 Pi 极简核心的设计理念 从四工具核心出发，仅在实际使用中发现明确缺口时才添加扩展
长会话中的上下文腐化 随着会话历史增长，性能逐渐下降 通过扩展配置上下文压缩；设置明确的会话长度限制
服务商锁定 工作流深度依赖某个模型的特性 在固化 Pi 工作流之前，先针对两个或更多服务商进行测试
缺少 MCP 能力 需要符合协议标准的工具连接能力 将 MCP 集成作为 Pi 扩展来实现；社区已有常见 MCP 服务器的现成包
无内置权限门控 自主操作缺乏人工检查节点 在容器中部署，并为有副作用的工具构建自定义审批扩展
技能可发现性 用户不知道有哪些技能可用 在项目级 AGENTS.md 中维护已安装技能的说明文档及调用语法
包版本漂移 Pi 包被固定在旧版本 定期使用 pi update；固定语义化版本范围而非 latest

参见

参考资料