3  Pi 概览

3.1 Pi 是什么

Pi 是一个极简的终端编程助手（terminal coding harness）。它运行在你的终端中，利用大语言模型（LLM）来理解你的代码库、执行编程任务、修改文件和运行命令。

与传统的 IDE 插件或 Web 聊天界面不同，Pi 从一开始就为终端工作流而设计。它不是一个带 AI 功能的编辑器，而是一个以 AI 为核心、围绕终端环境构建的编程代理（agent）。

Pi 的核心设计哲学是：保持内核极小，通过扩展机制实现功能增强。

3.2 设计理念

3.2.1 极简内核

Pi 的内核刻意保持精简。它只内置了四个核心工具，不包含任何臃肿的内置功能：

内置工具 功能
read 读取文件内容
write 创建或覆盖文件
edit 精确修补文件
bash 执行 Shell 命令

这四个工具覆盖了编程代理最本质的需求：读取代码、修改代码、执行命令。其他所有高级功能——比如 MCP 协议支持、子代理（sub-agents）、权限弹窗、计划模式、待办事项列表、后台 bash——Pi 都刻意没有内置。

Note

这不是功能缺失，而是有意为之的设计决策。Pi 认为这些工作流特定的行为应该通过扩展、技能（Skills）或包（Packages）来实现，而不是塞进核心内核中。

3.2.2 扩展机制

Pi 通过以下机制实现功能扩展：

  • TypeScript 扩展（Extensions）：用于添加工具、命令、事件处理器和自定义 UI
  • 技能（Skills）：可复用的按需能力模块
  • 提示词模板（Prompt Templates）：可复用的提示词，通过斜杠命令展开
  • 主题（Themes）：内置和自定义终端主题
  • Pi 包（Packages）：打包和分享扩展、技能、提示词及主题

这种设计使得 Pi 可以适应各种工作流：从简单的代码助手到复杂的自动化代理，都可以通过组合不同的扩展来实现。

Tip

如果你熟悉 Emacs 的设计哲学，会发现 Pi 与之有异曲同工之妙——最小化核心，最大化可扩展性。

3.3 核心特性

3.3.1 四个内置工具

Pi 默认为模型提供四个工具。此外，还有一些额外的内置只读工具（grep、find、ls）可通过工具选项启用：

# 启用所有内置工具（默认）
pi

# 仅启用只读工具（审查模式）
pi --tools read,grep,find,ls

# 禁用特定工具
pi --exclude-tools ask_question

3.3.2 上下文文件

Pi 在启动时自动加载上下文文件，为模型提供项目指令：

  • ~/.pi/agent/AGENTS.md：全局指令
  • AGENTS.md 或 CLAUDE.md：从父目录到当前目录逐级加载

3.3.3 会话管理

Pi 自动保存会话，支持会话分支、恢复和压缩：

pi -c                  # 继续最近的会话
pi -r                  # 浏览历史会话
pi --name "my task"    # 为会话命名

3.3.4 多模型支持

Pi 支持 30+ 个模型提供商，包括订阅制和 API Key 制。你可以随时切换模型，或通过 Ctrl+P 在多个模型间循环切换。

3.4 与 Claude Code / Cursor 的区别

Pi 与其他 AI 编程工具在设计理念上有显著差异：

维度 Pi Claude Code Cursor
运行环境 终端原生 终端 IDE
内核设计 极简（4个工具） 较丰富 IDE 集成
扩展机制 TypeScript 扩展 + 包 有限 插件系统
模型支持 30+ 提供商 Anthropic 为主 多模型
会话管理 树形分支 + 压缩 线性 线性
MCP 支持 通过扩展 内置 内置
子代理 通过扩展 内置 无
权限弹窗 项目信任机制 内置 IDE 权限
开源协议 MIT 专有 专有
Note

Pi 的定位不是替代 Claude Code 或 Cursor，而是提供一种更 Unix 化的终端编程代理方案——小内核、可组合、可脚本化。

3.5 安装方式

3.5.1 通过 npm 安装（推荐）

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

--ignore-scripts 参数禁用安装过程中的依赖生命周期脚本。Pi 在正常 npm 安装时不需要安装脚本。

3.5.2 通过 curl 安装（Linux/macOS）

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

curl 安装器底层也使用 npm 进行全局安装，因此卸载方式与 npm 安装相同。

3.5.3 卸载

# npm 安装或 curl 安装的卸载方式
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm
pnpm remove -g @earendil-works/pi-coding-agent

# Yarn
yarn global remove @earendil-works/pi-coding-agent

# Bun
bun uninstall -g @earendil-works/pi-coding-agent

卸载 Pi 不会删除设置、凭证、会话和已安装的 Pi 包，这些文件保留在 ~/.pi/agent/ 目录中。

3.6 首次运行

安装完成后，在项目目录中启动 Pi：

cd /path/to/project
pi

首次运行时，你需要进行身份认证：

  • 方式一：在 Pi 中运行 /login，选择订阅提供商（如 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 等）
  • 方式二：设置 API Key 环境变量（如 export ANTHROPIC_API_KEY=sk-ant-...）

认证完成后，直接输入你的需求并按 Enter 即可开始使用。

3.7 适用场景

Pi 特别适合以下场景：

  1. 终端重度用户：习惯在终端中完成大部分开发工作的程序员
  2. 脚本化工作流：需要将 AI 编程能力集成到 Shell 脚本或自动化流程中
  3. 多模型需求：需要在多个模型提供商之间灵活切换
  4. 可扩展性需求：希望通过自定义扩展来定制 AI 编程行为
  5. 开源爱好者：偏好开源工具和可审计的代码
Tip

想要了解 Pi 的完整设计理念，可以阅读作者的博客文章。