Pi Agent Harness 架構(gòu)解析一個輕量可擴(kuò)展的 Agent 開發(fā)底座1. 概述Pi 是一個 Agent Harness由 Mario Zechner知名游戲開發(fā)框架 libGDX 的創(chuàng)建者開發(fā)。它不是一個單一產(chǎn)品而是一個 Agent 開發(fā)底座——同時提供兩種用法輕量編程助手直接使用 CLI在項目目錄運(yùn)行 pi讓模型讀代碼、修改文件、執(zhí)行命令A(yù)gent 開發(fā)底座使用底層 SDK、RPC 模式或 TUI 組件構(gòu)建自己的 Agent 產(chǎn)品2. 四層軟件包架構(gòu)Pi 包含四個核心軟件包從底層到頂層逐層組裝。2.1 pi-ai模型接入層pi-ai 負(fù)責(zé)統(tǒng)一接入各種模型。它把 OpenAI、Anthropic、Google、OpenRouter、Ollama 等不同模型接口統(tǒng)一起來處理以下能力流式輸出工具調(diào)用圖片輸入推理內(nèi)容Token 與費(fèi)用統(tǒng)計2.2 pi-agent-coreAgent 循環(huán)層pi-agent-core 負(fù)責(zé) Agent 的核心運(yùn)行循環(huán)。流程如下模型發(fā)起工具調(diào)用 → 執(zhí)行工具 → 校驗參數(shù) → 把結(jié)果送回模型 → 繼續(xù)下一輪直到任務(wù)完成循環(huán)結(jié)束。這一層不關(guān)心模型來源也不關(guān)心終端界面只負(fù)責(zé) Agent 的核心邏輯。2.3 pi-tui終端界面層pi-tui 負(fù)責(zé)終端界面使用差分渲染技術(shù)——只更新發(fā)生變化的內(nèi)容減少終端閃爍。同時這一層的組件是可復(fù)用的開發(fā)者可以拿它構(gòu)建自己的終端應(yīng)用。2.4 pi-coding-agent組裝成品層pi-coding-agent 是前面三個包的組裝成品。在項目目錄中運(yùn)行 pi即可獲得一個完整的 Coding Agent具備讀代碼、修改文件、執(zhí)行命令、運(yùn)行測試的能力。3. 設(shè)計哲學(xué)3.1 極簡的核心Pi 默認(rèn)只給模型四個工具工具功能read讀取文件write創(chuàng)建或重寫文件edit精確修改文件bash執(zhí)行終端命令作者認(rèn)為主流前沿模型已經(jīng)非常熟悉 Coding Agent 的工作方式讀文件、改代碼和運(yùn)行命令足夠覆蓋絕大部分編程任務(wù)。Pi 最初的系統(tǒng)提示詞和工具描述合計不到 1000 Token模型不需要先讀大量產(chǎn)品規(guī)則更多上下文可以留給項目代碼和當(dāng)前任務(wù)。3.2 可擴(kuò)展的體系Pi 默認(rèn)沒有內(nèi)置 MCP、子 Agent、計劃模式和待辦列表。需要這些能力時可以安裝社區(qū) Package或者用 TypeScript 寫一個擴(kuò)展。擴(kuò)展可以注冊新工具、命令、快捷鍵和 Provider也能改變上下文壓縮方式、接管 Bash 執(zhí)行、增加自定義界面。修改完成后執(zhí)行 /reload當(dāng)前會話即可繼續(xù)使用。3.3 模型無關(guān)Pi 支持 15 個以上的模型 Provider 和數(shù)百個模型。可以在同一段會話中從 Claude 切換到 GPT再換成 Gemini也可以連接 Ollama、llama.cpp 等本地模型。3.4 會話管理會話歷史采用樹狀結(jié)構(gòu)。走錯方向時可以回到之前的節(jié)點(diǎn)重新開一條分支原來的嘗試仍然保留在同一個會話文件里。長對話接近上下文上限后Pi 會自動壓縮歷史也允許開發(fā)者替換自己的壓縮策略。除了交互式終端Pi 還提供單次執(zhí)行、JSON 事件流、RPC 和 SDK 四種接入方式。4. 安全邊界Pi 沒有內(nèi)置沙箱它會繼承當(dāng)前用戶的文件、進(jìn)程、網(wǎng)絡(luò)和憑證權(quán)限擴(kuò)展代碼也運(yùn)行在相同權(quán)限下。項目信任機(jī)制可以阻止陌生倉庫在未經(jīng)確認(rèn)時加載本地擴(kuò)展但它無法限制模型后續(xù)執(zhí)行的命令。處理陌生代碼、無人值守任務(wù)或者重要憑證時官方建議把 Pi 放進(jìn)容器、虛擬機(jī)、微型虛擬機(jī)或策略沙箱并且只掛載任務(wù)需要的目錄。5. 部署與使用Pi 是一個本地命令行程序不需要單獨(dú)部署數(shù)據(jù)庫或常駐網(wǎng)關(guān)。環(huán)境要求Node.js 22.19.0 或更高版本安裝方式# npm 全局安裝npminstall-g--ignore-scripts earendil-works/pi-coding-agent# macOS / Linux 安裝腳本curl-fsSLhttps://pi.dev/install.sh|sh基本使用命令命令用途pi進(jìn)入交互式會話/login配置模型支持 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot、API Key/model切換模型pi -c繼續(xù)上次會話pi -p “任務(wù)描述”單次執(zhí)行一次性任務(wù)6. 總結(jié)Pi 同時提供兩種用法輕量編程助手和 Agent 開發(fā)底座。核心設(shè)計原則是極簡、可擴(kuò)展、模型無關(guān)。它適合愿意掌控工作流的開發(fā)者從一個很小的核心開始只把自己需要的東西裝進(jìn)去。