2026 年爆火的 OpenClaw（小龙虾）底层内核就是 Pi‑Agent 。和 Claude Code、Codex CLI "大而全" 思路完全相反，Pi‑Agent 奉行核心极简主义 ：核心运行时仅约 1500 行 TS 代码，系统提示词不足 1000token，仅内置 4 个基础工具，却可以完成复杂工程编码任务。本文从背景、源码分层、Agent 循环、扩展机制、优缺点、横向对比、工程落地、面试考点完整拆解，搞懂 Pi，就能看透现代 Coding Agent 的本质：Agent = LLM + Tools + Loop。
GitHub 仓库：GitHub - badlogic/pi: CLI tool for managing vLLM deployments on GPU pods from Prime Intellect, Vast.ai, DataCrunch, etc. · GitHubCLI tool for managing vLLM deployments on GPU pods from Prime Intellect, Vast.ai, DataCrunch, etc. - badlogic/pihttps://github.com/badlogic/pi‑mono 作者：Mario Zechner（libGDX 游戏引擎之父），现由 Earendil‑Works 维护。
一、什么是 Pi‑Agent？
Pi‑Agent 是MIT 协议开源、模型无关的终端 Coding Agent 运行时（Harness），不是大模型，不是 IDE 插件，是一套智能体调度框架。
通俗理解：
- Claude Code：闭源成品，把模型、工具、计划、子 Agent、MCP、权限全部内置打包好，开箱即用，黑盒，绑定 Claude 系列模型。
- Codex CLI：闭源产品，深度绑定自家 Codex 模型，能力高度封装。
- Pi‑Agent：毛坯式 Agent 内核，核心只保留最本质循环，高级能力全部交给扩展（Extension / Skill）按需装配，支持任意大模型：DeepSeek、OpenAI、Anthropic、Ollama 本地私有化模型全部兼容，代码不会强制上第三方服务器，支持完全本地闭环运行。
核心哲学一句话：
An autonomous agent is just an LLM + tools + a loop. 自主智能体本质就三件事：大模型、工具集、循环调度。多余能力全部外置，不塞进内核。
很多人会混淆：OpenClaw ≠ Pi‑Agent；OpenClaw 是基于 Pi‑Agent 二次封装出来面向终端用户的成品，Pi 才是底层骨架。
Pi 的 4 个内置原生工具（内核仅此 4 个，没有更多）
read：读取文件write：覆盖写入文件edit：增量编辑 / 补丁修改文件bash：执行终端 shell 命令
重点：联网搜索、MCP 协议、子 Agent、计划模式 Plan Mode、权限弹窗，内核完全没有内置，全部靠第三方扩展包按需安装加载，不用就不存在，不污染上下文 token。
二、整体源码分层架构（monorepo 分包设计）
Pi 采用单向依赖 monorepo，4 个 npm 包，职责边界切割极其干净，非常适合学习 Agent 工程化源码。
1. @earendil‑works/pi‑ai｜模型适配层
职责：抹平各家大模型 API 差异。
- 统一 OpenAI / Claude / Ollama / DeepSeek 消息格式、toolCall、流式事件
- 对外输出统一
Message、ToolCall对象 - 上层 Agent 循环完全不用关心后端是哪家模型
价值：换模型只改配置，不用修改 Agent 业务代码。
2. @earendil‑works/pi‑agent‑core｜Agent 核心运行时（灵魂）
这就是 1500 行左右的核心，不含任何 UI、不含编码业务逻辑。 核心模块：
- Agent Loop：主循环调度器
- 消息会话管理：历史、状态、快照 save‑point
- Hook 钩子系统：
before_tool、after_tool、agent_start等事件钩子 - 工具调用生命周期管理：入参校验、执行、结果回传给模型
- 会话持久化、上下文裁剪压缩
所有扩展、Skill 全部通过钩子系统注入，不修改 core 内部源码，实现零侵入扩展。
3. @earendil‑works/pi‑coding‑agent｜编码业务层
基于 core 封装编码 Agent 行为；定义 Skill 加载逻辑，扫描本地 skill 目录，按需注入提示词与工具。 Skill 机制特点：不是常驻系统提示词，用到才加载进上下文，任务结束就释放，极大降低 token 开销blog.palai...。
4. @earendil‑works/pi‑tui｜终端交互层
TUI 终端界面，也就是我们命令行敲pi看到的交互界面，可替换，可以自己写 Web 前端对接 pi‑agent‑core SDK。
启示：这是优秀 Agent 框架的教科书式分层：模型层、循环内核层、业务层、展示层完全解耦。你可以拿掉 tui，把 pi‑core 直接嵌入自己 Web 系统、后台服务。
三、Pi‑Agent 完整 Agent Loop 运行流程（源码级）
Pi 本质就是不断循环的 ReAct 变体，每一轮 Turn 流程如下CSDN博...：
- 输入接收 ：接收用户需求，标准化消息，执行前置钩子
agent_start。 - 上下文组装 Context Assembly
- 基础极简 system prompt（<1000token）
- 会话历史消息
- 当前项目环境信息（工作目录、git 状态）
- 当前生效工具 Schema；按需加载用到的 Skill（不会全部塞进去）
- 上下文自动压缩，防止超窗口
- 调用 LLM，流式接收输出，解析 toolCall 工具调用。
- 工具调用拦截钩子
before_tool：扩展可以在这里拦截、阻断、修改工具调用，比如做权限控制。 - 执行工具：read/write/edit/bash，捕获 stdout、stderr、异常报错。
- 工具结果回写消息队列 ，触发
after_tool钩子。 - 判断任务是否完成：未完成回到步骤 2 继续下一轮循环；完成则终止 Agent。
和传统 LangChain ReAct 最大区别：Pi 把全部生命周期以事件钩子对外暴露，外部可以监听每一步；而 LangChain 很多逻辑黑盒在链内部。
关键设计：Hook 钩子系统
Pi 不硬编码权限、限流、日志，全部靠钩子注入逻辑。 示例：拦截禁止执行 bash 高危命令
typescript
运行
// 在扩展中注册钩子，不需要修改pi‑agent‑core源码
harness.hooks.on("before_tool", async (event) => {
if(event.toolName === "bash" && event.args.cmd.includes("rm -rf /")){
return { block: { reason:"高危命令被拦截" } }
}
})Pi 内核默认没有沙箱、没有命令白名单，默认继承当前操作系统登录用户权限；安全策略交给扩展层，这是它设计上的取舍。
四、两大扩展体系：Skill 与 Extension，很多人搞混
Pi 提供两套扩展，定位完全不一样，这是生态的根基。
1. Skill（技能）：提示词 + 简单工具片段，面向任务增强
- 文件形式：普通 markdown /yaml，不需要编译 TS
- 特点：按需加载，任务需要该技能才注入上下文，任务结束释放，不常驻系统 prompt
- 用途：数据库查询、git 增强、文档解析、测试脚本提示模板
- 加载：放在
~/.pi/skills或者项目目录.pi/skills，/reload热重载，无需重启 pi 进程。
对比 DeepSeek‑Harness 的 SKILL.md：设计思想高度同源，都是轻量配置技能。
2. Extension（扩展）：TS 代码扩展，修改 Agent 运行时本身
- npm 包 / 本地 ts 模块，可注册钩子、新增原生工具、修改循环行为
- 例子：pi‑mcp‑adapter（给 Pi 补上 MCP 协议支持）、pi‑subagents（增加子 Agent 能力）
- 可以修改 Agent 内核行为，拦截循环、新增工具、接入第三方服务。
重要认知：Pi 不是 "没有 MCP、没有子 Agent"；而是内核不内置，需要用户按需安装扩展包，避免默认提示词爆炸。
五、横向硬核对比：Pi‑Agent vs Claude Code vs Codex CLI
表格
| 对比维度 | Pi‑Agent | Claude Code | Codex CLI |
|---|---|---|---|
| 开源协议 | MIT 完全开源 | 闭源 | 闭源 |
| 系统提示词 | ≈800‑1000 token | ≈15000 token | ≈12000 token |
| 内置工具 | 4 个基础工具 | 20 + 全套工具 | 较多内置工具 |
| 模型绑定 | 模型无关，支持本地 Ollama | 仅 Anthropic Claude | 绑定自家 Codex |
| MCP 支持 | 扩展包实现，非内核内置 | 原生内置 MCP | 原生内置 MCP |
| Plan 模式 | 无，靠 Skill / 文件实现 | 内置 Plan Mode | 内置计划模块 |
| Sub‑Agent 子智能体 | 扩展实现 | 内置黑盒子子 Agent | 部分内置 |
| 权限沙箱 | 无内置，靠钩子 / 容器隔离 | 完整权限审批弹窗 | 权限管控 |
| Token 开销 | 极低，同等任务约为 CC 的 30‑40% | 很高，启动开销巨大 | 较高 |
| 部署形态 | SDK 嵌入 / TUI 终端 | IDE 插件 + 终端 | 桌面端 + CLI |
| 适合人群 | 二次开发、私有化部署、学习 Agent 源码 | 开箱即用，不想折腾配置 | 深度编码业务，生态产品用户 |
Pi 不是更强，而是更克制；短提示词带来更快推理速度，更少幻觉，但代价是很多高级特性需要自己装配。
六、Pi‑Agent 核心优势，以及代价（取舍）
✅优势
- 极致轻量化 token 开销：没有上万 token 的预置系统提示，打招呼只消耗千级 token，推理更快，成本更低。
- 模型完全解耦，可跑本地私有化大模型，代码不出内网，适合企业私有仓库安全场景。
- 内核干净透明，1500 行源码，Agent 学习最佳样本，没有黑盒。可以直接把 pi‑agent‑core 作为 SDK 嵌入自己产品。
- 热重载扩展 ：Skill 修改后
/reload立刻生效，不用重启进程。 - 事件全暴露，每一步工具调用、思考过程全部事件抛出，方便做日志、审计、Web 前端封装。
⚠️必须接受的代价（很多人踩坑）
- 开箱即用体验弱：原生没有 MCP、子 Agent、权限弹窗，想要就要装扩展，不是拿到手就全能。
- 默认安全策略宽松 ：直接继承当前用户操作系统权限，会执行
rm等命令；生产使用必须写钩子做命令拦截或者 Docker 沙箱隔离，不能裸跑在主机上。 - 依赖模型本身能力，因为系统提示词很短，弱模型上手效果会变差，强模型（DeepSeek‑V4‑Flash、Claude）才能发挥 Pi 全部威力。
- 没有官方图形 UI，原生只有 TUI 终端，Web 界面需要社区项目如 pi‑web。
七、工程落地：Pi‑Agent 两种使用路线
路线 1：直接终端使用（开发者日常编码）
bash
npm install -g @badlogic/pi
# 在代码仓库目录启动
pi- 适合个人开发者做本地项目重构、bug 修复、写单元测试。
- 搭配 Ollama 可以完全离线本地跑。
路线 2：SDK 二次开发，嵌入自有系统（企业级）
直接引入@earendil‑works/pi‑agent‑core，不使用 TUI 终端，自己封装 Web 界面。
typescript
运行
import { createHarness } from "@earendil‑works/pi‑agent‑core"
// 初始化harness，传入模型适配器
const harness = createHarness({ ai: aiAdapter })
// 监听全部Agent生命周期事件
harness.hooks.on("agent_start", e=>{})
harness.hooks.on("after_tool", e=>{})
// 投递用户任务，驱动Agent循环
await harness.prompt("帮我重构这个项目的登录模块")这就是 OpenClaw、pi‑web 等项目的实现方式：复用 core 内核，自己写上层 UI。
八、高频面试题（Agent 工程师，抛砖引玉）
Q1：Pi‑Agent 核心设计思想是什么？为什么系统提示词做的这么短？
参考答案 Pi 奉行「核心极简，能力外置」。Agent 内核只保留循环、消息、工具调度；业务能力、高级特性全部下沉 Skill 与 Extension 扩展。 短系统提示词好处：降低 token 成本，加快推理速度，减少预设指令带来的干扰。不把全部能力常驻上下文，需要时动态加载 Skill，平衡能力与上下文窗口上限。代价是高级能力需要按需装配，开箱体验弱。
Q2：Pi 没有内置 MCP，如何接入 MCP？内核为什么不直接内置 MCP？
参考答案 通过第三方 Extension 扩展包pi‑mcp‑adapter实现 MCP 支持。 设计者理念：MCP 属于扩展能力，不是 Agent 循环本体；如果塞进内核，无论用户用不用，都会增大系统提示词、增加内核复杂度，遵循 "不用就不引入" 的极简原则。
Q3：Pi 默认直接执行 bash 命令，生产环境如何做安全防护？
参考答案
- 使用
before_tool钩子拦截高危命令，做命令白名单、黑名单。 - 将 Agent 运行在隔离 Docker 容器，文件系统、命令权限做隔离。
- 禁止 root 账号运行 Pi 进程。
- 封装一层审批扩展，高危 bash 命令人工确认之后再放行。
Q4：Pi‑Agent 和 ReAct 框架关系？
参考答案 Pi 本质是 ReAct 范式工程化实现。区别在于传统 ReAct 大多把全部逻辑封装 Chain 内部；Pi 把全部生命周期通过 Hook 事件对外暴露，会话状态做快照 save‑point，扩展不侵入内核源码，适合二次开发与嵌入业务系统。
九、总结与工程启示
- Pi‑Agent 给整个行业最大启示：Coding Agent 的本质并不神秘，就是 LLM + 工具集 + 循环调度，复杂功能不等于塞进内核，能力可以外置装配。
- 它代表 Agent 一条重要分支：毛坯式框架，对比 Claude Code、Codex 这种 "精装成品"。没有绝对好坏，场景决定选型。
- 学习 Agent 工程强烈建议读 pi‑agent‑core 源码，比 LangChain 大量抽象封装更容易看懂 Agent 循环本质。
- 企业私有化落地优先考虑 Pi；追求开箱即用，不想折腾扩展，优先选 Claude Code / Codex。
延伸对比：DeepSeek‑Harness（Cordis 内核）vs Pi‑Agent：Harness 偏向通用多场景 Agent，Profile 多环境、大量内置生态 Skill；Pi 专注 Coding 场景，更加极致轻量化。