你可能因為三種原因點開了這篇文章想找個好用的編碼 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%免費】