标签： Node.js

Pi（Pi Agent Harness） 是 libGDX 作者 Mario Zechner（badlogic）团队 earendil-works 开源的极简终端 AI 编程智能体框架：核心只给模型 read / write / edit / bash 四个工具，其余能力全部交给你用 TypeScript 扩展、技能、提示词模板与主题自行拼装。上线不到一年拿下 81,000+ Stars、10,000+ Fork、248 位贡献者，MIT 许可，最新版本 v0.83.0。

一、项目简介

一句话：Pi 是一个「你来定义工作流」的开源终端编程智能体 —— 不预设子智能体、不预设计划模式、不内置 MCP，任何你想要的能力都能用一段 TypeScript 扩展装上去，还能打包成 npm 包分享给别人。

它同时也是一套可复用的智能体开发工具箱，仓库内含四个独立 npm 包：

• @earendil-works/pi-coding-agent —— 交互式编程智能体 CLI（终端里直接用的那个 pi）
• @earendil-works/pi-agent-core —— 智能体运行时，负责工具调用与状态管理
• @earendil-works/pi-ai —— 统一多厂商大模型 API（OpenAI / Anthropic / Google 等）
• @earendil-works/pi-tui —— 带差分渲染的终端 UI 库

也就是说：你既可以把它当 Claude Code / Codex CLI 的替代品直接用，也可以只取其中一层，去写自己的智能体产品。

二、安装要求和过程

环境要求

• Node.js（npm 全局安装方式）或直接用官方安装脚本下载独立二进制
• 操作系统：macOS / Linux / Windows 均支持，另有 Termux（Android）与 tmux 专门文档
• 模型凭据：任一支持的订阅（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）或 API Key

快速安装

# 方式一：npm 全局安装（官方推荐加 --ignore-scripts）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式二：安装脚本（独立二进制）
curl -fsSL https://pi.dev/install.sh | sh

认证与启动

# 用 API Key
export ANTHROPIC_API_KEY=sk-ant-...
pi

# 或复用已有订阅：启动后输入 /login 选择服务商
pi
/login

常用会话参数：

pi -c              # 继续最近一次会话
pi -r              # 浏览并选择历史会话
pi --no-session    # 临时模式，不落盘
pi -p "修复这个测试"  # 一次性打印模式（可配 --mode json）

安装第三方能力包同样一条命令：pi install npm:@foo/pi-tools 或 pi install git:github.com/user/repo@v1。

三、核心功能

1. 四个内置工具 + 无限扩展的极简内核

默认只有 read、write、edit、bash。子智能体、计划模式、权限弹窗、待办列表这些别家标配的功能，Pi 一律不内置，而是让你通过扩展实现或安装现成的 Pi Package。作者的理由很直接：这些机制各家做法不同，硬塞进内核只会限制用户。

2. TypeScript 扩展系统：连 Doom 都能跑

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

扩展可以注册自定义工具（甚至替换内置工具）、自定义命令与快捷键、状态栏 / 页眉 / 页脚 / 浮层 UI、Git 自动提交检查点、SSH 与沙箱执行、权限门禁、自定义压缩策略、MCP 接入……官方示例里甚至有一个「等模型响应时玩 Doom」的扩展。

3. 会话树：分支、回溯、克隆一个文件搞定

会话以 JSONL 树结构存储，每条记录带 id 与 parentId。/tree 可跳回任意历史节点继续对话并在分支间切换，/fork 从某条用户消息派生新会话，/clone 复制当前分支，全部历史保留在同一个文件里。上下文快满时自动压缩（可手动 /compact 并给定压缩指令），压缩是有损的，但原始记录仍在 JSONL 中随时可回看。

4. 30+ 模型服务商，含订阅登录与本地 llama.cpp

订阅方式支持 Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro（Codex）、GitHub Copilot；API Key 方式覆盖 Anthropic、OpenAI、Azure OpenAI、DeepSeek、Google Gemini/Vertex、Amazon Bedrock、Mistral、Groq、Cerebras、xAI、OpenRouter、Vercel AI Gateway、智谱 ZAI Coding Plan（含中国区）、Kimi For Coding、MiniMax、小米 MiMo（含中国区/阿姆斯特丹/新加坡节点）、Hugging Face、Fireworks、Together AI、NVIDIA NIM、Cloudflare 等。还能通过 /login llama.cpp 接入本地 llama.cpp 路由服务器，用 /llama 直接下载和加载本地模型。

5. 四种运行形态：交互 / 打印 / RPC / SDK

除了终端交互，Pi 支持 -p 打印模式与 --mode json 结构化输出、--mode rpc（stdin/stdout 上的 JSONL 协议，方便非 Node 语言集成），以及直接以 SDK 方式嵌入自家应用：

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});
await session.prompt("What files are in the current directory?");

6. 供应链与项目信任双重加固

直接依赖全部锁定精确版本、min-release-age=2 拒绝当天新发布的依赖、发布包内附 npm-shrinkwrap.json、CI 使用 npm ci --ignore-scripts 并定期跑 npm audit signatures。运行侧则有「项目信任」机制：首次进入含项目级配置或 .agents/skills 的目录会先询问，未信任前只加载上下文文件与用户级扩展。

四、典型使用场景

场景 1：把智能体改造成完全贴合自家流程的样子

团队要求「每次改完代码自动跑 lint 并生成 checkpoint 提交」「部署只允许走内部 CLI」「敏感目录禁止写入」。在别的工具里这些要么等官方支持、要么 fork 源码；在 Pi 里就是三个扩展：一个 tool_call 事件钩子做路径门禁，一个注册 deploy 工具，一个在每轮结束时自动 git commit。写完丢进 .pi/extensions/ 全组共享，或打成 npm 包发出去。

场景 2：低成本 / 国产模型 + 本地模型的日常编码

用 /model（Ctrl+L）在 DeepSeek、Kimi For Coding、小米 MiMo、智谱 ZAI、MiniMax 之间随时切换，重活切 Claude / GPT，日常问答切便宜模型或 /llama 加载的本地模型；Ctrl+P 在自己圈定的「常用模型」间循环。底部状态栏实时显示输入/输出/缓存读写 Token、缓存命中率与累计花费，成本一目了然。

场景 3：把编程智能体嵌进自己的产品或 CI

用 pi-agent-core + pi-ai 做后端智能体服务，前端接 --mode rpc 或 SDK；CI 里用 pi -p --mode json 跑「自动修复失败测试」「批量迁移 API」这类任务，输出 JSON 直接被流水线消费。会话以 JSONL 存档，出问题时用 /tree 复盘整条决策链，还能 /export 成 HTML 或 /share 成私密 Gist 给同事看。

五、推荐理由

最近半年冒出来的 Coding Agent 多到看不过来，Pi 的差异化非常清晰：它把「克制」当成了产品特性。README 里那段 Philosophy 值得所有做 Agent 的人读一遍 —— 不做 MCP（写带 README 的 CLI 工具就够了）、不做子智能体（用 tmux 开多个 pi 实例）、不做权限弹窗（进容器）、不做内置待办（「它们会让模型犯迷糊」）。这些取舍未必人人认同，但每一条都给了替代路径，而不是简单的「不支持」。

实际用下来最爽的两点：一是会话树，改坏了直接 /tree 回到三十轮之前换个思路继续，不用新开会话重讲一遍背景；二是扩展的门槛真的低，一个默认导出函数就是一个扩展，热重载 /reload 立刻生效，写工具的体验接近写普通 TypeScript 模块。加上原生支持 Kimi、MiMo、DeepSeek、智谱等国内可用的服务商，中文开发者上手成本很低。

要注意的是：Pi 没有内置权限系统，默认以启动它的用户权限运行，官方明确建议放进容器或沙箱（文档给了 Gondolin 微虚机、Docker、OpenShell 三种方案）；Pi Package 会执行任意代码，安装第三方包前务必看源码。另外仓库对新贡献者的 Issue/PR 默认自动关闭（维护者每天人工复核），提问前先读 CONTRIBUTING.md。

六、下载地址

• GitHub 仓库：https://github.com/earendil-works/pi
• 官方网站：https://pi.dev（含在线演示）
• 官方文档：https://pi.dev/docs/latest
• npm 包：@earendil-works/pi-coding-agent
• 作者博文：Mario Zechner 谈 Pi 的设计
• 聊天/工作流版本：earendil-works/pi-chat

项目数据（截至 2026 年 7 月 31 日）：81,086 Stars · 10,008 Forks · 248 位贡献者 · TypeScript · MIT 许可 · 最新版本 v0.83.0 · 仓库仍在每日更新。