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