Pi 是一套開源、可擴充的 AI Agent 工具組，由軟體開發者 Mario Zechner（GitHub 帳號 badlogic）建立，在程式碼託管平台累積 115,322 顆星標與 14,691 次複製。專案以 TypeScript 撰寫、採 MIT 授權，把多供應商模型 API、Agent 執行迴圈、終端機介面與編碼代理整合進同一個 monorepo，並可透過擴充套件、技能、提示範本與主題自行組裝。最新版本 1.2.0 於 2026 年 10 月 12 日發布，新增 OpenRouter 按金鑰顯示可用模型清單，並為設定檔輸出 JSON Schema 以支援編輯器驗證。本文整理其套件架構、版本更新、安裝方式與生態現況。
Pi 是什麼？
Pi 是一套以 TypeScript 撰寫、採 MIT 授權的開源 AI Agent 工具組，GitHub 星標達 115,322 顆，可透過擴充套件、技能與主題自行組裝。
專案的定位是一副「極簡但可延伸」的代理外殼。官方說明指出，使用者應該依照自己的工作流程改造 Pi，而不是反過來調整習慣去遷就工具，因此擴充套件、技能、提示範本與主題都被設計成可獨立安裝的模組，並可打包成 Pi 套件、透過 npm 或 Git 分享給其他人。
產品形態並不限於互動使用。同一套核心可以互動模式啟動、以列印或 JSON 模式自動化執行、透過 RPC 由其他程式控制，或直接用 TypeScript SDK 嵌入既有應用。Pi 內建了實用預設值，但刻意略過子代理與計畫模式這類較重的功能，讓需要的人自行以套件補上。
Pi 的核心套件與架構如何組成？
Pi 採 monorepo 結構，包含統一的模型 API、代理執行核心、終端機介面函式庫、持久化執行環境與編碼代理 CLI 等多個可獨立使用的套件。
整份程式碼以 monorepo 方式組織，把命令列工具與支撐用的函式庫放在同一個儲存庫內。其中 pi-ai 負責跨供應商的模型呼叫，介接 OpenAI、Anthropic、Google 等服務；pi-agent-core 提供工具呼叫與狀態管理；pi-tui 是一套採用差異渲染的終端機介面函式庫；pi-durable 處理對話、任務與文件的持久化。
另有幾個較少被提及但同樣關鍵的套件。chord 是可熱重載外掛的型別化執行環境，負責契約、複製狀態與 JSON 連結上的遠端呼叫；pi-telemetry 提供與供應商無關的遙測契約、參考轉接器與一致性測試。對於需要把代理接進聊天平台的團隊，官方另有一個獨立的 pi-chat 專案可搭配使用。
Pi 1.2.0 版本更新了哪些功能？
1.2.0 於 2026 年 10 月 12 日發布，新增 OpenRouter 按金鑰模型清單、設定檔 JSON Schema、遠端剪貼簿傳送，並調整擴充套件的啟動事件行為。
這次更新的主軸是把設定與模型選擇變得更透明。當使用者設定 OpenRouter 金鑰後，Pi 只會列出該金鑰實際可用的模型，並一併顯示上下文長度、最大輸出與價格，包含在 models.json 指定的區域端點；清單會被保存下來，離線時仍可查閱。專案同時為 settings.json、models.json、鍵位設定與主題輸出 $schema，讓編輯器能做欄位驗證與自動完成。
版本說明也標示了數項破壞性變更。主題的 schema 網址改為 https://pi.dev/schemas/theme.schema.json，啟動時載入的主題現在與後續重載套用相同的驗證規則。before_agent_start 事件的觸發範圍擴大至由擴充套件主動發起的執行，事件型別變成以 messageType 區分的聯合型別，處理器若只想回應使用者提示，必須自行檢查 event.messageType === "user"。此外，pi mcp list --json 對提供資源的伺服器改為回報 resources: true，不再列出數量。
修正項目集中在穩定性與相容性。Mistral 串流在長思考期間被逾時中斷的問題已修掉，逾時目前只適用於等待回應標頭；列印模式在回應被輸出上限截斷時，過去會靜默以 0 結束，現在會印出部分文字、把警告寫入標準錯誤並以 1 結束。MCP 伺服器回傳非物件結構化內容時的呼叫失敗、Windows 上 auth.json 讀寫的暫時性權限錯誤，以及終端機顏色回覆片段滲入提示輸入等問題，也一併處理。
Pi 如何安裝並開始使用？
官方提供 shell 安裝腳本、npm 全域安裝與 Nix 三條路徑，執行需要 Node.js 22.19 以上版本，安裝後在專案目錄執行 pi 即可開始。
最直接的方式是執行官方安裝腳本，macOS、Linux 與 Windows 各有對應指令，安裝程式會鎖定相依版本，之後可用 pi update 更新。偏好套件管理員的使用者可以改用 npm 全域安裝，但 npm 路徑不會鎖定遞移相依，官方也提醒一般安裝不需要執行相依套件的生命週期腳本。Nix 使用者則可透過 flake 安裝 stable 標記或指定版本標籤，建置過程在離線環境完成。
執行環境需求為 Node.js 22.19 或更新版本。使用者在自己想處理的專案目錄啟動 Pi，於互動介面內執行 /login 連接訂閱或 API 金鑰後即可指派任務。若要在自動化流程中使用，可切換列印或 JSON 模式取得結構化輸出，或透過 RPC 與 SDK 由既有系統控制。
# macOS / Linux
curl -fsSL https://pi.dev/install.sh | sh
# 或使用 npm（不鎖定遞移相依）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 在專案目錄啟動
cd /path/to/project
pi
Pi 的權限邊界與維護模式如何？
Pi 沒有內建權限系統，預設以啟動者的身分執行，需要更強邊界時官方建議改用微虛擬機、Docker 或政策沙箱其中一種容器化模式。
這是一個需要留意的設計取向。官方文件明確指出，Pi 不含限制檔案系統、行程、網路或憑證存取的內建權限系統，預設以啟動它的使用者與行程權限執行完所有工具。對於只在本機個人專案使用的情境，這能換來最低的設定負擔；但若要在共享環境或處理敏感資料，就需要自行加上隔離層。
官方為此提供三種容器化模式。Gondolin 擴充套件把 Pi 與供應商驗證留在主機，只將內建工具與 ! 指令導向本地的 Linux 微虛擬機；純 Docker 模式把整個行程放進本機容器做簡單隔離；OpenShell 則把行程放進受政策控管的沙箱。文件把這三種做法的適用範圍寫得相當清楚，選型前值得先讀過一輪。
Pi 與其他 AI Agent 工具有何差異？
差異在於組合彈性與供應鏈治理：Pi 以核心套件加外掛組裝，直接相依鎖定精確版本，並在安裝時避免執行相依套件的生命週期腳本。
相較於把大量功能預設開啟的代理產品，Pi 把子代理、計畫模式等能力留給社群套件，核心維持精簡。這樣的分工讓使用者能挑選真正需要的功能，代價是初次設定需要較多判斷。開發節奏相當密集，1.0.0 於 2026 年 10 月 1 日發布，1.2.0 於同月 12 日推出，短短兩週內歷經七個版本。
供應鏈治理是另一個被寫進文件的重點。專案把直接的外部相依鎖定在精確版本，設定 npm 在解析時避開當日發布的版本，並以 package-lock.json 作為相依的唯一依據；提交前檢查會擋下未經允許的鎖定檔變更。官方安裝程式改從產生好的安裝鎖定檔安裝，以鎖住遞移相依，並讓本機發布測試與 npm 發布共用同一套打包流程。
出處連結有哪些？
本文資訊整理自 Pi 的 GitHub 儲存庫、README、官方版本說明與 npm 套件頁面，涵蓋套件結構、安裝指引與供應鏈治理說明。
- GitHub 儲存庫：https://github.com/earendil-works/pi
- 官方網站與文件：https://pi.dev
- 版本發布紀錄：https://github.com/earendil-works/pi/releases
- npm 套件：https://www.npmjs.com/package/@earendil-works/pi-coding-agent
總結：Pi 適合什麼團隊？
適合願意自行組裝工具鏈、重視相依治理與容器化邊界的開發團隊；若期待開箱即用的完整功能，則需評估額外設定成本。
Pi 的價值在於把選擇權交回使用者手上。擴充套件、技能、提示範本與主題四種自訂方式覆蓋了多數調整需求，而核心刻意維持精簡，讓工具鏈的形狀由團隊自行決定。115,322 顆星標、6,948 次提交與 291 位具名貢獻者，反映的是一套在短時間內被大量採用的開發者工具，而非依賴單一商業模式支撐的服務。
1.2.0 的內容也說明其維護取向。新功能集中在設定透明度與模型選擇，同期卻一併處理逾時、編碼與 Windows 權限這類容易長期累積的問題，並把相依版本鎖定與安裝腳本治理寫進貢獻規範。對已經在使用編碼代理的團隊而言，這類偏重可預期性與供應鏈安全的更新節奏，比功能堆疊更具參考價值。
