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