核心只写2000行，却撑起23k Star——拆解Pi Agent三层架构

你可能因为三种原因点开了这篇文章想找个好用的编码 Agent、想知道 Agent 怎么做的、要做自己的 Agent。这三个问题恰好对应同一个框架的三个身份。一、三个身份一个项目先说清楚 Pi 是什么。它是Mario ZechnerlibGDX 游戏引擎作者GitHub ID: badlogic开发的开源 AI Agent 框架。MIT 协议TypeScript 写的23.7k Star官网 pi.dev。但 Pi 不是一个产品这么简单。它同时是三件事•编码 Agent CLI— 一个终端里的编程助手跟 Claude Code 同赛道•Agent 源码教材— 核心只有 5 个文件约 2000 行读它就能搞懂 Agent 怎么做•SDK 二开底座— 分层设计让你能嵌进自己的应用长出完全不同的产品这三个身份指向同一个项目本身就值得好奇。二、三层架构Pi 的核心设计决策Pi 最重要的架构决策是三层分离设计原则只有一句话分离不稳定的外部世界与稳定的核心循环。┌─────────────────────────────────┐ │ 产品层 (coding-agent) │ │ CLI · 7工具 · Extension · TUI │ ├─────────────────────────────────┤ │ Agent运行时 (agent-core) │ │ Agent Loop · Steering · 状态 │ ├─────────────────────────────────┤ │ LLM通信层 (pi-ai) │ │ 22提供商 · EventStream · 转换 │ └─────────────────────────────────┘每层只知道自己该知道的事•pi-ai只管和模型说话不知道 Agent 是什么•agent-core只管循环和状态不知道工具具体干什么•coding-agent只管编码业务不关心底层通信细节这里有两个关键边界需要记住LLM 边界统一消息进统一事件出和副作用边界模型只能提议工具调用实际执行在本地可被拦截。三、第一层 pi-aiLLM 通信的脏活3.1 为什么要单独分一层用过多家 LLM API 的人都知道这个痛苦• OpenAI 的 tool call ID 可以有 450 字符带管道符Anthropic 限制 64 字符且只允许特定字符• Anthropic 返回加密的 thinking signatureGoogle 有 thought signature格式完全不同• 每家上下文溢出的错误信息都不一样Pi 用一个统一接口抹平这些差异。核心是一个自建的EventStream。3.2 EventStream不跟风任何流框架Pi 没用 RxJS、没用 Node Stream、没用回调自建了一个极简异步可迭代流classimplementspushvoid// 生产者推事件asyncIterator// 消费者 for-await-ofresult// 等最终结果LLM 的流式响应被标准化为11 种细粒度事件text_delta、thinking_delta、toolcall_delta、done 等。最狠的是toolcall_delta——Pi 在流式传输过程中实时解析不完整的 JSON工具参数不用等传完就能读取。3.3 transformMessages最有工程价值的函数当你在不同提供商之间切换模型时对话历史需要转换。这是全项目最脏但最有价值的代码// OpenAI 的 tool call ID: 450 字符带管道符// ↓ transformMessages()// Anthropic 能接受的: 64 字符以内它还处理四件事thinking block 转换加密的只对同模型有效切换时转纯文本、孤立 tool call 修补模型发了调用没返回结果注入合成结果防报错、thought signature 过滤、错误消息清理。这正是框架的价值把脏活集中到一个地方让上层代码保持干净。3.4 ThinkingLevel 统一每家的思考实现不同Pi 用一个枚举统一ThinkingLevel→Anthropicminimal budget:1024 / medium budget:8192 / high budget:16384ThinkingLevel→OpenAIminimal effort:“minimal” / medium effort:“medium” / high effort:“high”ThinkingLevel→Googleminimal LOW / medium MEDIUM / high HIGH上层代码只需要说我要 high 级别思考不关心底层怎么映射。四、第二层 agent-coreAgent 运行时4.1 不只是一个 while 循环大多数 Agent 教程里的循环是这样的while现实中这不够用。用户在 Agent 执行过程中改主意怎么办多工具能并行要不要并行工具执行一半出错怎么恢复Pi 的解决方案是双层循环外层循环 (Follow-up) └── 内层循环 (Steering Tool Execution) ├── 调 LLM → 发射 message events ├── 执行工具 (可并行) ├── 检查 Steering → 可中断剩余工具 └── 注入新指令4.2 Steering用户随时改主意Steering转向是关键创新。工具执行过程中外部可以往队列塞消息// Agent 正在执行一系列工具...steeruser停不要部署。// → 当前工具执行完后跳过剩余工具Follow-up后续处理另一种场景——Agent 说完了但有后续消息要注入。4.3 并行工具执行Pi 默认并行执行工具但做了精心设计•Preflight 串行— 先逐个校验参数、跑钩子可阻止执行•执行并发— 通过校验的工具 Promise.all 并发•结果按原始顺序返回— 不管哪个先完成顺序和 LLM 发出的一致顺序为什么重要因为 LLM 看到的结果顺序会影响它的推理。五、第三层 coding-agent产品层5.1 七个内置工具read— 读文件支持图片自动缩放到 2000x2000bash— 执行命令超时控制、流式输出、退出码追踪edit— 精确编辑find-and-replace不是整文件覆盖write— 写文件创建或覆盖自动建父目录grep— 搜索内容尊重 .gitignore截断到 30KBfind— 搜索文件glob 模式ls— 列目录POSIX 格式5.2 Operations 接口工具与环境解耦这是 Pi 工具设计里最聪明的部分。工具不直接调fs.readFile而是通过接口interfacereadFilestringstringstatstring// 本地执行const// SSH 远程const同一个 read 工具本地跑、SSH 远程跑、容器里跑——零代码改动。5.3 Extension 系统不替你做决定Pi 明确不用 MCP用 TypeScript 原生扩展export default functionregisterTooldeployontool_callasyncregisterCommandstatssetWidgetkeyLine 1扩展有两种能力监听并介入在 Agent 运行任意节点插入逻辑和向核心注册新能力注册工具、命令、快捷键、UI。覆盖了30 生命周期事件session_start、before_agent_start、tool_call、tool_result、compact 等。这意味着子代理、计划模式、权限弹窗——全都可以通过扩展实现核心不需要改一行代码。5.4 会话管理JSONL 树形 无损压缩Pi 用 JSONL 格式存储会话采用树形结构interfacestringstring// 父节点形成树messagecompactionany关键概念leafId 决定模型看到的上下文路径。模型只看到从根到叶子节点的路径。这使得会话支持分支切换不需要复制整个历史。压缩是无损的——完整历史保留在 JSONL 文件中压缩只是创建摘要条目替代旧消息。六、TUI终端渲染的工程细节pi-tui 是独立终端 UI 框架有两个值得关注的技术点。差分渲染三种策略首次全量输出、尺寸变化清屏重绘、增量更新只重绘变化区域。所有更新用CSI 2026 同步输出协议包裹——零闪烁SSH 远程场景下减少网络传输量。IME 支持用自定义 APC 序列精确告诉终端 IME 光标位置中日韩输入法候选窗口能正确定位——大多数终端 TUI 框架不处理这个。七、Pi vs Claude Code两种哲学读完源码最明显的感受是它和 Claude Code 代表两种 Agent 构建哲学理念Pi 最小内核极致可扩展 vs Claude Code 全功能内置扩展Pi TypeScript Extension vs Claude Code Hooks (shell)MCPPi 设计上排除 vs Claude Code 原生支持权限Pi 无内置交给上层vs Claude Code 内置审批计划模式Pi 无可扩展实现vs Claude Code 内置工具后端Pi Operations可插拔 vs Claude Code 固定本地Pi 的哲学是不替你做决定。Claude Code 的哲学是开箱即用。两种都有效取决于你要平台还是要产品。八、OpenClaw架构的实战验证理解 Pi 架构价值的最佳案例是OpenClaw——一个支持 46 个消息渠道WhatsApp、Telegram、Discord 等的多渠道 AI 助手。它不是 fork Pi 然后魔改而是把 Pi 当引擎嵌入• 复用 Pi 的streamSimple()嵌入运行 Agent 循环• 复用SessionManager做会话持久化• 复用codingTools选择性引入工具• 复用 Extension 系统自建上下文修剪扩展同一套 LLM 通信层和 Agent 运行时长出了两个完全不同形态的产品。这就是分层架构的价值证明。九、写在最后Pi 给我们的启示不是怎么做 Agent而是怎么不做什么。核心 5 个文件 2000 行70 扩展示例覆盖远比核心丰富的功能场景。这种结构传递了一个明确信息框架的作者不替开发者决定 Agent 应该怎么工作。如果你要一个开箱即用的产品选 Claude Code。如果你要一个能嵌进自己流程、能改模型、能改工具、能改权限策略的底座Pi 值得一读。核心只做最必要的事。剩下的全部交给扩展。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】