Pi Agent Harness 架构解析：一个轻量可扩展的 Agent 开发底座

1. 概述

Pi 是一个 Agent Harness，由 Mario Zechner（知名游戏开发框架 libGDX 的创建者）开发。它不是一个单一产品，而是一个 Agent 开发底座——同时提供两种用法：

• 轻量编程助手：直接使用 CLI，在项目目录运行 pi，让模型读代码、修改文件、执行命令
• Agent 开发底座：使用底层 SDK、RPC 模式或 TUI 组件，构建自己的 Agent 产品

---

2. 四层软件包架构

Pi 包含四个核心软件包，从底层到顶层逐层组装。

2.1 pi-ai：模型接入层

pi-ai 负责统一接入各种模型。它把 OpenAI、Anthropic、Google、OpenRouter、Ollama 等不同模型接口统一起来，处理以下能力：

• 流式输出
• 工具调用
• 图片输入
• 推理内容
• Token 与费用统计

2.2 pi-agent-core：Agent 循环层

pi-agent-core 负责 Agent 的核心运行循环。流程如下：

模型发起工具调用 → 执行工具 → 校验参数 → 把结果送回模型 → 继续下一轮

直到任务完成，循环结束。这一层不关心模型来源，也不关心终端界面，只负责 Agent 的核心逻辑。

2.3 pi-tui：终端界面层

pi-tui 负责终端界面，使用差分渲染技术——只更新发生变化的内容，减少终端闪烁。同时，这一层的组件是可复用的，开发者可以拿它构建自己的终端应用。

2.4 pi-coding-agent：组装成品层

pi-coding-agent 是前面三个包的组装成品。在项目目录中运行 pi，即可获得一个完整的 Coding Agent，具备读代码、修改文件、执行命令、运行测试的能力。

---

3. 设计哲学

3.1 极简的核心

Pi 默认只给模型四个工具：

工具	功能
read	读取文件
write	创建或重写文件
edit	精确修改文件
bash	执行终端命令

作者认为主流前沿模型已经非常熟悉 Coding Agent 的工作方式，读文件、改代码和运行命令足够覆盖绝大部分编程任务。Pi 最初的系统提示词和工具描述合计不到 1000 Token，模型不需要先读大量产品规则，更多上下文可以留给项目代码和当前任务。

3.2 可扩展的体系

Pi 默认没有内置 MCP、子 Agent、计划模式和待办列表。需要这些能力时，可以安装社区 Package，或者用 TypeScript 写一个扩展。扩展可以注册新工具、命令、快捷键和 Provider，也能改变上下文压缩方式、接管 Bash 执行、增加自定义界面。修改完成后执行 /reload，当前会话即可继续使用。

3.3 模型无关

Pi 支持 15 个以上的模型 Provider 和数百个模型。可以在同一段会话中从 Claude 切换到 GPT，再换成 Gemini，也可以连接 Ollama、llama.cpp 等本地模型。

3.4 会话管理

会话历史采用树状结构。走错方向时，可以回到之前的节点重新开一条分支，原来的尝试仍然保留在同一个会话文件里。长对话接近上下文上限后，Pi 会自动压缩历史，也允许开发者替换自己的压缩策略。

除了交互式终端，Pi 还提供单次执行、JSON 事件流、RPC 和 SDK 四种接入方式。

---

4. 安全边界

Pi 没有内置沙箱，它会继承当前用户的文件、进程、网络和凭证权限，扩展代码也运行在相同权限下。

项目信任机制可以阻止陌生仓库在未经确认时加载本地扩展，但它无法限制模型后续执行的命令。处理陌生代码、无人值守任务或者重要凭证时，官方建议把 Pi 放进容器、虚拟机、微型虚拟机或策略沙箱，并且只挂载任务需要的目录。

---

5. 部署与使用

Pi 是一个本地命令行程序，不需要单独部署数据库或常驻网关。

环境要求：Node.js 22.19.0 或更高版本

安装方式：

# npm 全局安装
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# macOS / Linux 安装脚本
curl -fsSL https://pi.dev/install.sh | sh

基本使用命令：

命令	用途
pi	进入交互式会话
/login	配置模型（支持 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot、API Key）
/model	切换模型
pi -c	继续上次会话
pi -p “任务描述”	单次执行一次性任务

---

6. 总结

Pi 同时提供两种用法：轻量编程助手和 Agent 开发底座。核心设计原则是极简、可扩展、模型无关。它适合愿意掌控工作流的开发者，从一个很小的核心开始，只把自己需要的东西装进去。