AIDiveTL;DR
- pi 是採用 MIT 授權的 monorepo，把一套程式碼代理（coding agent）harness 拆成五個獨立套件：模型 API 層、代理迴圈、終端機 UI 函式庫、程式碼代理本體，以及遙測套件。你可以只拿一塊，也可以五塊全用。
- CLI 第一天就是完整的程式碼代理：四個預設工具、可 fork 與 resume 的樹狀工作階段歷史、即時費用計數器，而且會讀取你儲存庫裡現有的 AGENTS.md 或 CLAUDE.md。
- 真正的價值在 SDK：createAgentSession 加上 model runtime 與 session manager，大約十行 TypeScript 就能得到可運作的代理，defineTool 則能新增有型別的自訂工具，不需要額外的程序或協定。
- 這種透明的代價是你要自己做的工作：沒有內建權限提示、隔離由你負責、版本仍在 1.0 之前（v0.84），而且大約有一百個未解決的 issue。
- 日常用的 harness 繼續用，把 pi 當成測試台，看看你的 harness 藏了什麼。只有在你願意自己扛起防護機制時，才在它上面建產品。
來源怎麼說
pi 是一個 monorepo：一個儲存庫裡獨立發佈五個套件，每個負責 harness 的一層 s2。pi-ai 是面向模型供應商（OpenAI、Anthropic、Google 等）的統一 API，用同一個介面處理回應串流、帶有思考等級（thinking level）的推理區塊，以及各供應商提供的模型的動態探索 s2。pi-agent-core 是代理迴圈本身：對話狀態，以及送出訊息、讀取工具呼叫、執行並把結果回傳的循環 s2。pi-tui 是採用差異渲染（differential rendering）的終端機渲染函式庫，只重繪畫面上有變動的部分 s2。pi-coding-agent 把這些元件組裝成你安裝的 CLI，pi-telemetry 則讓你接上自己的使用量指標，不必依賴特定廠商 s3。
採用數據支持這個設計：92 123 顆星、11 400 個 fork、超過 5 700 個 commit，全部採用 MIT 授權，允許使用、修改與再散布，包括放進商業產品 s1。發佈節奏整個夏天都維持著：八月前兩週發了三個版本，v0.84.2 在 14 日發佈 s4。
安裝只要一行指令：npm install -g --ignore-scripts @earendil-works/pi-coding-agent，而 ignore-scripts 旗標很重要：它會阻止相依套件執行安裝腳本，這是 npm 上最常被利用的攻擊面之一 s3。透過 login 指令連上供應商後，底部列會即時顯示目前資料夾、工作階段、已消耗的 token 與費用，所以每個請求在送出時就有價格，而不是等到月底才知道 s3。
工作階段是最有特色的功能。每段對話都以 JSONL 存在你的家目錄，依專案分類，歷史是一棵樹而不是一條線：fork 回到任一點並分出新分支，tree 在分支之間切換，resume 可以重開任何過去的工作階段，幾週後也行，因為一切都存在本機 s3。模型預設只拿到四個工具：read、write、edit 和 bash，和市面上的代理相比非常少，而且是刻意的 s3。設定也遵循同樣的邏輯：家目錄裡一份全域的 settings.json，專案裡一份會覆蓋它的設定，以及一套信任機制，在你第一次開啟某個資料夾時，先詢問才會套用該資料夾的本機設定。CLI 也會把專案的 AGENTS.md 或 CLAUDE.md 載入為上下文，所以現有的指示不用重寫就能使用 s3。
在 SDK 這邊，createAgentSession 接收一個 ModelRuntime 和一個 SessionManager，回傳可運作的代理。SessionManager 決定持久化方式：丟棄式腳本用記憶體，要在多次啟動之間找回對話就用磁碟，而 SDK 建立的工作階段與 CLI 自己的工作階段結構相同 s8。createAgentSession 的選項還能讓你精確選擇要暴露的工具組，想從空白開始時，甚至可以透過 ResourceLoader 換掉整份系統提示 s8。自訂工具透過 defineTool：一個名稱、一段描述、有型別的參數 schema 和一個 execute 函式，再透過 customTools 傳給 createAgentSession。對模型來說，這個工具和 read 或 bash 完全一樣，有型別的 schema 讓你在編輯器裡有自動完成，代理收到的輸入也已經驗證過。這和 MCP 伺服器是同一種機制，只是全部都在你的檔案裡，中間沒有獨立程序或協定 s8。
CLI 本身有四種客製化機制，都放在專案或家目錄的資料夾裡：extensions（TypeScript 模組，用來註冊工具、斜線指令、鍵盤快速鍵或 UI 元素，啟動時從 extensions 資料夾載入）、skills（遵循 Agent Skills 標準的能力套件，由模型呼叫或手動呼叫，所以現有的 skills 可以原樣重用）、prompt templates，以及在 CLI 執行時重新載入的 themes s3。README 用一句話說明了理念：讓 pi 配合你的工作流程，而不是反過來，不必 fork，也不用動內部 s3。大型 harness 把子代理、計畫模式和權限都綁進產品裡，pi 則刻意不內建，讓你寫成 extension 或從社群安裝 s3。
限制由專案自己寫明。沒有內建權限提示：預設情況下，代理可以不經詢問就執行 bash 指令。官方的容器化指南承認這點，並提出三種隔離模式（Docker 是其中之一），但在讓代理在重要的機器上放手執行之前先建好隔離，是你的工作 s5。成熟度是另一項成本：v0.84 而不是 1.0、大約一百個未解決的 issue，以及仍標示為實驗性的 API，例如前幾週新增的遠端工作階段用戶端 s7。同一批元件已經用在另一個產品上：pi-chat 把它們用於對話自動化 s6。
結論：保留、試用或跳過
| pi 的部分 | 判定 | 原因 |
|---|---|---|
| CLI 作為日常 harness 旁的學習測試台 | 保留 | 本機樹狀工作階段、即時費用、四個工具：你能看到整合式 harness 藏起來的每一層 |
| 用來做代理產品的 SDK（createAgentSession + defineTool） | 現在就試 | 十行就有可運作的代理、不需要 MCP 配線的有型別自訂工具、可更換的供應商 |
| CLI 作為唯一的日常助手 | 暫時跳過 | 沒有權限提示、隔離由你負責、1.0 之前的 API 變動 |
| 用 extension 做防護（bash 確認、政策） | 試用 | 這是放權限層的預期位置，並隨你的專案版本控制 |
| Skills 資料夾 | 保留 | 採用 Agent Skills 標準，你現有的 skills 可原樣載入 |
| 實驗性 API（遠端工作階段用戶端） | 跳過 | 標示為實驗性，1.0 之前可能會變 |
週一要做的事
- 用
npm install -g --ignore-scripts @earendil-works/pi-coding-agent安裝 CLI，執行pi，用 login 指令連上供應商，並在一項真實任務中觀察費用列。 - 開啟一個已經有 AGENTS.md 或 CLAUDE.md 的儲存庫，確認 pi 有讀取；用同一個提示，把代理最初的回答和你平常的 harness 比較。
- 跑一段對話，然後從較早的節點
fork，往不同方向前進；列出~/.pi/agent/sessions/看看 JSONL 檔案和它們的專案資料夾。 - 寫一個二十行的
our-agent.ts：import createAgentSession，傳入 ModelRuntime 和記憶體內的 SessionManager，問它目前資料夾裡有什麼，並用npx tsx執行。 - 新增一個 defineTool，從你自己的系統（內部 API、資料庫 view、CSV）讀取某些資料，並透過 customTools 傳入；確認代理在相關問題上不用提示就會呼叫它。
- 在你在意的機器上做任何啟用 bash 的執行之前，從容器化指南的三種隔離模式中挑一種並設定好。
- 起草第一個 extension，攔截 bash 呼叫，並在破壞性指令前要求確認；把它放在專案的 extensions 資料夾並納入版本控制。
- 瀏覽一次未解決的 issue 清單，這樣在你開始建構之前，就知道哪些部分會變動。
延伸閱讀
- 閱讀 SDK 文件，了解 createAgentSession 完整的選項清單：工具組、透過 ResourceLoader 設定系統提示、session manager s8。
- 在發佈任何會在使用者機器上執行 bash 的東西之前，先研究容器化指南中的三種隔離模式 s5。
- 看看 pi-chat，了解同樣五個套件如何重新組合，用於對話自動化而不是寫程式碼 s6。
- 瀏覽 packages 資料夾，單獨讀一讀 pi-agent-core：它是每個整合式 harness 所執行迴圈中最小、最好讀的版本 s2。
- 追蹤 releases 頁面：v0.84.0 到 v0.84.2 在八月的兩週內陸續發佈，所以預期會有影響 extension 的變更說明 s4。
- 把未解決的 issue 當成仍屬實驗性部分的地圖，從遠端工作階段用戶端開始 s7。
- 重用你為其他工具寫好的 skills：pi 的 skills 資料夾遵循 Agent Skills 標準 s3。
來源
- pi: the agent toolkit (repository), Earendil Works. 為什麼值得讀：包含套件清單、星數與 fork 數、MIT 授權的 README。
- pi monorepo packages, Earendil Works. 為什麼值得讀：五個套件並排呈現，最快看出每一層由誰負責。
- pi-coding-agent package README, Earendil Works. 為什麼值得讀：安裝指令、預設工具、工作階段，以及四種擴充機制。
- pi releases, Earendil Works. 為什麼值得讀：v0.84 系列的發佈節奏與變更記錄。
- pi containerization guide (isolation patterns), Earendil Works. 為什麼值得讀：在任何重要環境啟用 bash 之前該套用的三種隔離模式。
- pi-chat: the same bricks applied to conversation automation, Earendil Works. 為什麼值得讀：用同一批套件打造的第二個產品，有助於判斷這些套件的可重用程度。
- pi open issues, Earendil Works. 為什麼值得讀：目前版本中不穩定或實驗性部分的即時清單。
- pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. 為什麼值得讀：createAgentSession、defineTool 和 session manager 的確切選項名稱。
FAQ
pi 現在能取代我每天用的程式碼代理嗎？
不能直接替換。它沒有權限提示，隔離由你負責，版本在 1.0 之前，還有大約一百個未解決的 issue。工作上繼續用你現在的 harness，把 pi 放在旁邊跑。
要給 pi 自訂工具，需要 MCP 嗎？
不需要。defineTool 接收名稱、描述、有型別的參數 schema 和 execute 函式，再透過 customTools 傳給 createAgentSession。它的行為就像內建工具，沒有獨立程序或協定。
我現有的 AGENTS.md、CLAUDE.md 和 skills 能用嗎？
可以。CLI 會自動載入專案裡的 AGENTS.md 或 CLAUDE.md，它的 skills 資料夾遵循 Agent Skills 標準，所以現有的 skills 可原樣載入。
為什麼預設只有四個工具？
read、write、edit 和 bash 就是整個預設組合，遠少於市面上的代理，專案把這當成一個選擇。其他任何東西，都透過 customTools 或 extension 有意識地加入。