Pi – 极简开源的终端编程 Agent，只给模型四个基础工具

Pi 是一款由 earendil works 于 2025 年 8 月开源的终端编程 Agent 运行时，主要用于在项目目录内自主读代码、改文件与执行命令，支持读取、写入、编辑与执行四个基础工具以及 TypeScript 扩展机制，适用于批量代码改造、脚本化重构与把编码 Agent 嵌入自有应用等场景。

Pi 的核心能力

Pi 的设计取向是把默认能力压到最小：模型只看到四个工具和一段不到一千 token 的系统提示词，剩下的空间留给使用者自己补。想先了解这类运行时在 AI 智能体 体系里的位置，可以先看这篇说明。

四个基础工具验证通过编码闭环

模型可用的工具只有读取、写入、编辑与执行命令。读文件、改文件、跑测试这条最短闭环已经够用，其余诉求（搜索、浏览器、数据库）都要显式装成扩展，权限边界因此清楚。

系统提示词不到一千 token

官方把系统提示词控制在不到一千 token 的量级，上下文窗口的绝大部分留给代码与任务本身。任务复杂时空间不会被固定的行为守则吃掉，长会话里退化也更慢。

扩展、技能与提示模板

四类扩展点各自解决一层：扩展加工具与命令，技能提供按需加载的操作说明，提示模板固定常用任务的输入格式，主题改界面。它们可以打包成 Pi 包，经 npm 或 git 分发。

默认不做子智能体与计划模式

官方明确不内置子智能体与计划模式这类重结构能力，需要就自己装包或直接让 Pi 写一个。好处是行为可预测、调试链路短；代价是复杂任务要自己做编排。

四种接入形态

同一个运行时可以交互式使用、进 print 或 JSON 模式做自动化、经 RPC 被外部进程控制，也可以作为 TypeScript SDK 嵌进自有应用。跨形态迁移时任务描述与工具定义不必重写。

Pi 与 Claude Code 的对比

两者都是终端里跑的编程 Agent，分歧在「默认给多少」这件事上：一个把能力压到最小靠扩展长出来，一个把常用能力全内置。

三点分歧。系统提示体量决定上下文留给谁：Pi 压到千 token 以内，长代码库任务里可用空间更多，Claude Code 的提示更重；子智能体与规划是可控与省事的取舍：Pi 默认不给、按需装包，Claude Code 内置编排；模型接入上 Pi 可换供应商，Claude Code 只跑 Claude 系列。要轻量可扩展选 Pi，要开箱即用选 Claude Code。

同样是终端形态的编程智能体，站内的 Step Code（阶跃星辰推出的开源终端编程智能体）走的是模型厂自带客户端的路线，可以和 Pi 这种纯运行时对照看。

Pi 的应用场景与适用人群

能力压到最小之后，它更适合被当成零件用；同为终端路线还可以对照 MiniMax Code CLI：

• 脚本化批量改造：在多个仓库上跑同一套改造任务，用 JSON 模式收集结构化结果。
• 自有产品内嵌编码能力：通过 SDK 或 RPC 把 Agent 接到自家工具里，工具集按业务裁剪。
• 定制工作流：把团队规范写成技能与提示模板，随任务按需加载，不占常驻上下文。
• CI 里的自动修补：在流水线中对失败用例做小范围修复，结果交人工复核。
• 教学与研究：提示词短、工具少，便于观察模型在不同工具配置下的行为差异。

适用人群：适合要自建编码 Agent 的工程团队、需要把编码能力嵌进自有产品的开发者，以及愿意自己写扩展来定义工作流的技术人员；希望开箱即用、不想配扩展的个人，直接用成品客户端更省时间。

Pi 的使用方法

官方给了三条路径：安装脚本最省事，npm 适合已有 Node 工具链的环境，RPC 与 SDK 面向把运行时嵌进别的程序。

安装脚本：一行装好命令行

1. 按 Pi 官网 的说明，在 macOS 或 Linux 上执行安装脚本，Windows 用 PowerShell 的对应命令，安装器会把依赖版本固定住。
2. 进入要处理的项目目录，直接启动 Pi，第一次使用先在会话内完成模型登录或填 API Key。
3. 后续升级用自带的更新命令，不必重跑安装脚本。

npm 安装：接进现有 Node 工具链

1. 确认本机 Node 版本为 22.19 以上，低于该版本要先升级。
2. 全局安装 @earendil-works/pi-coding-agent，注意 npm 方式不固定传递依赖的版本。
3. 启动后在项目目录内下达任务，需要额外能力时再装对应的 Pi 包。

RPC 与 SDK：被别的程序调用

1. 按文档选用 RPC 控制或 TypeScript SDK 两种接入方式，先验证通过官方最小示例。
2. 把工具集收敛到业务需要的最小集合，凭据放在宿主程序侧而不是暴露给模型。
3. 需要结构化输出时走 JSON 模式，便于宿主程序解析而不是从文本里抠结果。

官方示例默认在本机执行命令与写文件，容器或 CI 里要显式挂载工作目录并放行包管理器网络。模型侧可以连订阅也可以填 API Key，团队共用时建议按人分配凭据；扩展与技能从第三方包安装时要先看源码，它们拿到的权限和内置工具是同一档。

Pi Agent Harness 的项目地址

• 项目官网：https://pi.dev/
• GitHub 主仓库：https://github.com/earendil-works/pi

Pi 的价格方案

运行时本身不收费：仓库以 MIT 协议开源，本地运行不产生许可费用，改造与再分发被允许，只需保留版权与许可声明。实际支出来自模型侧——用订阅或在各家模型服务商处按量付费。

官方没有为 Pi 单独设订阅或席位，也没有公布托管版价目；需要托管环境时可选出品方的 Radius 托管服务（AI 网关、产物分享与网页搜索，目前处于 early alpha，按组织额度计费），也可以自己选模型通道与算力。企业内若要统一管理凭据与审计，成本发生在自建的网关与日志侧。

Pi 的常见问题