你可能因為三種原因點開了這篇文章想找個好用的編碼 Agent、想知道 Agent 怎么做的、要做自己的 Agent。這三個問題恰好對應(yīng)同一個框架的三個身份。一、三個身份一個項目先說清楚 Pi 是什么。它是Mario ZechnerlibGDX 游戲引擎作者GitHub ID: badlogic開發(fā)的開源 AI Agent 框架。MIT 協(xié)議TypeScript 寫的23.7k Star官網(wǎng) pi.dev。但 Pi 不是一個產(chǎn)品這么簡單。它同時是三件事?編碼 Agent CLI— 一個終端里的編程助手跟 Claude Code 同賽道?Agent 源碼教材— 核心只有 5 個文件約 2000 行讀它就能搞懂 Agent 怎么做?SDK 二開底座— 分層設(shè)計讓你能嵌進自己的應(yīng)用長出完全不同的產(chǎn)品這三個身份指向同一個項目本身就值得好奇。二、三層架構(gòu)Pi 的核心設(shè)計決策Pi 最重要的架構(gòu)決策是三層分離設(shè)計原則只有一句話分離不穩(wěn)定的外部世界與穩(wěn)定的核心循環(huán)。┌─────────────────────────────────┐ │ 產(chǎn)品層 (coding-agent) │ │ CLI · 7工具 · Extension · TUI │ ├─────────────────────────────────┤ │ Agent運行時 (agent-core) │ │ Agent Loop · Steering · 狀態(tài) │ ├─────────────────────────────────┤ │ LLM通信層 (pi-ai) │ │ 22提供商 · EventStream · 轉(zhuǎn)換 │ └─────────────────────────────────┘每層只知道自己該知道的事?pi-ai只管和模型說話不知道 Agent 是什么?agent-core只管循環(huán)和狀態(tài)不知道工具具體干什么?coding-agent只管編碼業(yè)務(wù)不關(guān)心底層通信細節(jié)這里有兩個關(guān)鍵邊界需要記住LLM 邊界統(tǒng)一消息進統(tǒng)一事件出和副作用邊界模型只能提議工具調(diào)用實際執(zhí)行在本地可被攔截。三、第一層 pi-aiLLM 通信的臟活3.1 為什么要單獨分一層用過多家 LLM API 的人都知道這個痛苦? OpenAI 的 tool call ID 可以有 450 字符帶管道符Anthropic 限制 64 字符且只允許特定字符? Anthropic 返回加密的 thinking signatureGoogle 有 thought signature格式完全不同? 每家上下文溢出的錯誤信息都不一樣Pi 用一個統(tǒng)一接口抹平這些差異。核心是一個自建的EventStream。3.2 EventStream不跟風(fēng)任何流框架Pi 沒用 RxJS、沒用 Node Stream、沒用回調(diào)自建了一個極簡異步可迭代流classimplementspushvoid// 生產(chǎn)者推事件asyncIterator// 消費者 for-await-ofresult// 等最終結(jié)果LLM 的流式響應(yīng)被標準化為11 種細粒度事件text_delta、thinking_delta、toolcall_delta、done 等。最狠的是toolcall_delta——Pi 在流式傳輸過程中實時解析不完整的 JSON工具參數(shù)不用等傳完就能讀取。3.3 transformMessages最有工程價值的函數(shù)當你在不同提供商之間切換模型時對話歷史需要轉(zhuǎn)換。這是全項目最臟但最有價值的代碼// OpenAI 的 tool call ID: 450 字符帶管道符// ↓ transformMessages()// Anthropic 能接受的: 64 字符以內(nèi)它還處理四件事thinking block 轉(zhuǎn)換加密的只對同模型有效切換時轉(zhuǎn)純文本、孤立 tool call 修補模型發(fā)了調(diào)用沒返回結(jié)果注入合成結(jié)果防報錯、thought signature 過濾、錯誤消息清理。這正是框架的價值把臟活集中到一個地方讓上層代碼保持干凈。3.4 ThinkingLevel 統(tǒng)一每家的思考實現(xiàn)不同Pi 用一個枚舉統(tǒng)一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 級別思考不關(guān)心底層怎么映射。四、第二層 agent-coreAgent 運行時4.1 不只是一個 while 循環(huán)大多數(shù) Agent 教程里的循環(huán)是這樣的while現(xiàn)實中這不夠用。用戶在 Agent 執(zhí)行過程中改主意怎么辦多工具能并行要不要并行工具執(zhí)行一半出錯怎么恢復(fù)Pi 的解決方案是雙層循環(huán)外層循環(huán) (Follow-up) └── 內(nèi)層循環(huán) (Steering Tool Execution) ├── 調(diào) LLM → 發(fā)射 message events ├── 執(zhí)行工具 (可并行) ├── 檢查 Steering → 可中斷剩余工具 └── 注入新指令4.2 Steering用戶隨時改主意Steering轉(zhuǎn)向是關(guān)鍵創(chuàng)新。工具執(zhí)行過程中外部可以往隊列塞消息// Agent 正在執(zhí)行一系列工具...steeruser停不要部署。// → 當前工具執(zhí)行完后跳過剩余工具Follow-up后續(xù)處理另一種場景——Agent 說完了但有后續(xù)消息要注入。4.3 并行工具執(zhí)行Pi 默認并行執(zhí)行工具但做了精心設(shè)計?Preflight 串行— 先逐個校驗參數(shù)、跑鉤子可阻止執(zhí)行?執(zhí)行并發(fā)— 通過校驗的工具 Promise.all 并發(fā)?結(jié)果按原始順序返回— 不管哪個先完成順序和 LLM 發(fā)出的一致順序為什么重要因為 LLM 看到的結(jié)果順序會影響它的推理。五、第三層 coding-agent產(chǎn)品層5.1 七個內(nèi)置工具read— 讀文件支持圖片自動縮放到 2000x2000bash— 執(zhí)行命令超時控制、流式輸出、退出碼追蹤edit— 精確編輯find-and-replace不是整文件覆蓋write— 寫文件創(chuàng)建或覆蓋自動建父目錄grep— 搜索內(nèi)容尊重 .gitignore截斷到 30KBfind— 搜索文件glob 模式ls— 列目錄POSIX 格式5.2 Operations 接口工具與環(huán)境解耦這是 Pi 工具設(shè)計里最聰明的部分。工具不直接調(diào)fs.readFile而是通過接口interfacereadFilestringstringstatstring// 本地執(zhí)行const// SSH 遠程const同一個 read 工具本地跑、SSH 遠程跑、容器里跑——零代碼改動。5.3 Extension 系統(tǒng)不替你做決定Pi 明確不用 MCP用 TypeScript 原生擴展export default functionregisterTooldeployontool_callasyncregisterCommandstatssetWidgetkeyLine 1擴展有兩種能力監(jiān)聽并介入在 Agent 運行任意節(jié)點插入邏輯和向核心注冊新能力注冊工具、命令、快捷鍵、UI。覆蓋了30 生命周期事件session_start、before_agent_start、tool_call、tool_result、compact 等。這意味著子代理、計劃模式、權(quán)限彈窗——全都可以通過擴展實現(xiàn)核心不需要改一行代碼。5.4 會話管理JSONL 樹形 無損壓縮Pi 用 JSONL 格式存儲會話采用樹形結(jié)構(gòu)interfacestringstring// 父節(jié)點形成樹messagecompactionany關(guān)鍵概念leafId 決定模型看到的上下文路徑。模型只看到從根到葉子節(jié)點的路徑。這使得會話支持分支切換不需要復(fù)制整個歷史。壓縮是無損的——完整歷史保留在 JSONL 文件中壓縮只是創(chuàng)建摘要條目替代舊消息。六、TUI終端渲染的工程細節(jié)pi-tui 是獨立終端 UI 框架有兩個值得關(guān)注的技術(shù)點。差分渲染三種策略首次全量輸出、尺寸變化清屏重繪、增量更新只重繪變化區(qū)域。所有更新用CSI 2026 同步輸出協(xié)議包裹——零閃爍SSH 遠程場景下減少網(wǎng)絡(luò)傳輸量。IME 支持用自定義 APC 序列精確告訴終端 IME 光標位置中日韓輸入法候選窗口能正確定位——大多數(shù)終端 TUI 框架不處理這個。七、Pi vs Claude Code兩種哲學(xué)讀完源碼最明顯的感受是它和 Claude Code 代表兩種 Agent 構(gòu)建哲學(xué)理念Pi 最小內(nèi)核極致可擴展 vs Claude Code 全功能內(nèi)置擴展Pi TypeScript Extension vs Claude Code Hooks (shell)MCPPi 設(shè)計上排除 vs Claude Code 原生支持權(quán)限Pi 無內(nèi)置交給上層vs Claude Code 內(nèi)置審批計劃模式Pi 無可擴展實現(xiàn)vs Claude Code 內(nèi)置工具后端Pi Operations可插拔 vs Claude Code 固定本地Pi 的哲學(xué)是不替你做決定。Claude Code 的哲學(xué)是開箱即用。兩種都有效取決于你要平臺還是要產(chǎn)品。八、OpenClaw架構(gòu)的實戰(zhàn)驗證理解 Pi 架構(gòu)價值的最佳案例是OpenClaw——一個支持 46 個消息渠道WhatsApp、Telegram、Discord 等的多渠道 AI 助手。它不是 fork Pi 然后魔改而是把 Pi 當引擎嵌入? 復(fù)用 Pi 的streamSimple()嵌入運行 Agent 循環(huán)? 復(fù)用SessionManager做會話持久化? 復(fù)用codingTools選擇性引入工具? 復(fù)用 Extension 系統(tǒng)自建上下文修剪擴展同一套 LLM 通信層和 Agent 運行時長出了兩個完全不同形態(tài)的產(chǎn)品。這就是分層架構(gòu)的價值證明。九、寫在最后Pi 給我們的啟示不是怎么做 Agent而是怎么不做什么。核心 5 個文件 2000 行70 擴展示例覆蓋遠比核心豐富的功能場景。這種結(jié)構(gòu)傳遞了一個明確信息框架的作者不替開發(fā)者決定 Agent 應(yīng)該怎么工作。如果你要一個開箱即用的產(chǎn)品選 Claude Code。如果你要一個能嵌進自己流程、能改模型、能改工具、能改權(quán)限策略的底座Pi 值得一讀。核心只做最必要的事。剩下的全部交給擴展。學(xué)AI大模型的正確順序千萬不要搞錯了2026年AI風(fēng)口已來各行各業(yè)的AI滲透肉眼可見超多公司要么轉(zhuǎn)型做AI相關(guān)產(chǎn)品要么高薪挖AI技術(shù)人才機遇直接擺在眼前有往AI方向發(fā)展或者本身有后端編程基礎(chǔ)的朋友直接沖AI大模型應(yīng)用開發(fā)轉(zhuǎn)崗超合適就算暫時不打算轉(zhuǎn)崗了解大模型、RAG、Prompt、Agent這些熱門概念能上手做簡單項目也絕對是求職加分王給大家整理了超全最新的AI大模型應(yīng)用開發(fā)學(xué)習(xí)清單和資料手把手幫你快速入門學(xué)習(xí)路線:?大模型基礎(chǔ)認知—大模型核心原理、發(fā)展歷程、主流模型GPT、文心一言等特點解析?核心技術(shù)模塊—RAG檢索增強生成、Prompt工程實戰(zhàn)、Agent智能體開發(fā)邏輯?開發(fā)基礎(chǔ)能力—Python進階、API接口調(diào)用、大模型開發(fā)框架LangChain等實操?應(yīng)用場景開發(fā)—智能問答系統(tǒng)、企業(yè)知識庫、AIGC內(nèi)容生成工具、行業(yè)定制化大模型應(yīng)用?項目落地流程—需求拆解、技術(shù)選型、模型調(diào)優(yōu)、測試上線、運維迭代?面試求職沖刺—崗位JD解析、簡歷AI項目包裝、高頻面試題匯總、模擬面經(jīng)以上6大模塊看似清晰好上手實則每個部分都有扎實的核心內(nèi)容需要吃透我把大模型的學(xué)習(xí)全流程已經(jīng)整理好了抓住AI時代風(fēng)口輕松解鎖職業(yè)新可能希望大家都能把握機遇實現(xiàn)薪資/職業(yè)躍遷這份完整版的大模型 AI 學(xué)習(xí)資料已經(jīng)上傳CSDN朋友們?nèi)绻枰梢晕⑿艗呙柘路紺SDN官方認證二維碼免費領(lǐng)取【保證100%免費】