Pi - 可自我擴展的程式碼撰寫代理 CLI

1. 專案概覽

Pi 是一個可自我擴展、基於終端機的程式碼撰寫代理框架，建構於 Claude Agent SDK 之上，為開發人員提供互動式 CLI，能在單一統一的執行環境中規劃任務、編輯程式碼、執行工具並支援多個 LLM 供應商。

2. 背景與定位

Pi 的誕生是為了讓開發人員擁有一個可完全掌控並自行擴展的程式碼撰寫代理，而非內建於單一 IDE 或平台中的封閉式單一廠商助理。其核心使命是提供一個輕量級、可組合的「代理載具」：包含管理工具呼叫與狀態的執行環境、終端機 UI 以及模型抽象層，這些皆以獨立套件形式釋出，使團隊能運用與 Pi 本身相同的基礎元件來建構自己的代理。

相較於類似的程式碼撰寫代理專案，Pi 在三個方面展現出差異化優勢：

設計上不受供應商限制 — Pi 並未硬編碼單一 AI 廠商，而是提供統一的 LLM API (pi-ai)，透過單一介面與 OpenAI、Anthropic、Google 及其他供應商互動。
可組合架構 — CLI、代理執行環境、模型層、終端機 UI 和遙測功能均為獨立套件，開發人員可重複使用個別組件，無需採用整個應用程式。
重視供應鏈安全 — 專案鎖定依賴項版本並提供 shrinkwrap 檔案，體現了對此工具（預設以主機層級權限執行）在建構可重現性與可審計性上的刻意關注。

3. 功能分類

🧠 代理執行環境
負責處理工具呼叫迴圈及對話/應用程式狀態的核心套件。

工具調用與結果處理
跨工作階段的狀態持久化
可擴展的工具註冊機制
用途：賦予任何 CLI 或應用程式執行自主程式碼撰寫代理所需的「大腦」。

🌐 多供應商 LLM 層
針對多個大型語言模型 API 的統一抽象層。

支援 OpenAI
支援 Anthropic (Claude)
支援 Google
不受供應商限制的請求/回應型別定義
用途：讓開發人員無需重寫應用程式邏輯即可切換或混合使用模型供應商。

💻 互動式 CLI
旗艦級 pi-coding-agent 終端機應用程式。

在終端機中進行互動式程式碼撰寫工作階段
透過工具進行檔案編輯與命令執行
基於工作階段的工作流程
用途：開發人員日常在真實程式碼庫上使用 Pi 的主要入口。

🎛️ 終端機 UI 函式庫
專用於建構豐富終端機介面的套件 (pi-tui)。

差異化渲染以實現流暢更新
可重複使用的代理輸出 UI 基礎元件
用途：驅動 Pi 自身的 CLI 體驗，亦可重複使用於建構其他基於終端機的代理工具。

📊 遙測框架
供應商中立的遙測合約與型別化結構描述 (pi-telemetry)。

結構化、具型別的事件結構描述
供應商中立設計（不綁定單一分析後端）
用途：讓團隊能在不被供应商鎖定的情況下觀察並改善代理行為。

4. 主要亮點

可自我擴展的載具 — Pi 的設計讓開發人員能夠擴展並重塑代理本身，而不受限於固定的功能集。
多供應商靈活性 — 透過一致統一的 API 介面，在 OpenAI、Anthropic、Google 及其他 LLM 供應商之間切換。
模組化套件設計 — 五個專注的套件（CLI、代理核心、AI 層、遙測、TUI）可獨立採用或組合使用。
終端機優先的使用者體驗 — 採用差異化渲染的終端機 UI，確保互動式工作階段快速且反應靈敏，無需離開命令列。
安全性透明化 — 專案明確聲明未內建檔案系統、處理程序、網路或憑證存取權限系統，改為發佈容器化模式（Gondolin、原生 Docker、OpenShell）供需要隔離環境的團隊使用。
可重現建構 — 鎖定的依賴項與 shrinkwrap 檔案保障了此工具（預設以完整主機權限執行）的供應鏈完整性。

5. 依角色劃分的使用案例

一般開發人員：將 pi-coding-agent CLI 作為日常的結對程式設計助理，直接在終端機中撰寫、編輯及除錯程式碼。
平台/工具工程師：基於 pi-agent-core、pi-ai 和 pi-tui 建構自訂程式碼撰寫代理或內部開發者工具，無需從零開始。
重視安全的團隊：在授予主機層級任務之前，於文件記載的容器化模式（Gondolin、Docker、OpenShell）中執行 Pi，以限制檔案系統、網路及憑證存取。
DevOps/SRE：將供應商中立的 pi-telemetry 結構描述整合至現有的可觀測性管道中，以監控代理的使用情況與可靠性。

6. 快速入門

尋找所需資源 — 請從官方文件網站開始：

https://pi.dev/docs/latest

安裝與執行：

npm install --ignore-scripts
npm run build

若需使用快取的模型資料進行完全離線重建：

npm run build:offline

從原始碼執行 CLI 以進行本機測試：

./pi-test.sh

貢獻：

npm run check   # 檢查語法、格式化及型別驗證
./test.sh        # 執行測試套件

請參閱儲存庫中的 CONTRIBUTING.md 和 AGENTS.md 以獲取貢獻指南。

7. 專案結構

pi/
├── packages/
│   ├── pi-coding-agent/   # 互動式 CLI（主要進入點）
│   ├── pi-agent-core/     # 代理執行環境：工具呼叫與狀態管理
│   ├── pi-ai/             # 統一的多供應商 LLM API
│   ├── pi-telemetry/      # 供應商中立的遙測合約/結構描述
│   └── pi-tui/            # 終端機 UI 函式庫（差異化渲染）
├── CONTRIBUTING.md        # 貢獻指南
├── AGENTS.md              # 代理相關開發筆記
├── test.sh                # 完整測試套件執行器
└── pi-test.sh              # 直接從原始碼執行 CLI

套件的拆分反映了 Pi 的設計理念：CLI 僅是底層代理執行環境、模型層及 UI 工具組的消費者之一，這些底層元件皆可獨立重複使用。

8. 相關生態系統

Claude Agent SDK — Pi 代理載具所基於的底層 SDK。
LLM 供應商 — 透過 pi-ai 抽象層存取的 OpenAI、Anthropic 及 Google API。
容器化工具 — 文件記載 Gondolin、Docker 及 OpenShell 作為安全執行 Pi 的輔助隔離層。
npm 登錄表 — Pi 以 @earendil-works/pi-coding-agent 及相關作用域套件的形式發佈。

9. 授權條款

Pi 依據 MIT 授權條款 發佈。

✅ 可自由使用、複製、修改及散佈，包括用於商業目的
✅ 可自由基於 pi-agent-core、pi-ai 及 pi-tui 建構衍生工具
❌ 不提供任何擔保；作者不對因使用而產生的損害承擔責任
ℹ️ 原始版權聲明與授權條款必須保留在軟體的副本或實質部分中
ℹ️ Pi 預設以主機處理程序權限執行，且未內建存取控制 — 在授予其敏感環境存取權限前，請務必詳閱容器化指南

10. 常見問題

問：Pi 支援哪些 LLM 供應商？
答：透過其 pi-ai 套件，Pi 在單一統一 API 背後支援 OpenAI、Anthropic、Google 及其他供應商。

問：讓 Pi 在我的機器上執行命令安全嗎？
答：Pi 沒有內建權限系統來限制檔案系統、處理程序、網路或憑證存取 — 它預設以主機處理程序權限執行。若需隔離，請使用文件記載的容器化模式（Gondolin、Docker 或 OpenShell）。

問：如何從原始碼安裝並建構 Pi？
答：執行 npm install --ignore-scripts，接著執行 npm run build（或使用 npm run build:offline 進行離線重建），然後使用 ./pi-test.sh 從原始碼執行。

問：我可以只使用 Pi 的部分功能嗎，例如終端機 UI 或代理執行環境？
答：可以。Pi 拆分為多個獨立套件（pi-coding-agent、pi-agent-core、pi-ai、pi-telemetry、pi-tui），因此您可以單獨採用特定組件，無需使用完整的 CLI。

問：我該如何貢獻？
答：在提交變更前，請先執行 npm run check 和 ./test.sh，並遵循儲存庫中 CONTRIBUTING.md 與 AGENTS.md 的指南。

11. 快速連結

儲存庫：https://github.com/earendil-works/pi
官方文件：https://pi.dev/docs/latest
首頁：https://pi.dev
貢獻指南：CONTRIBUTING.md（位於儲存庫中）
社群：專案首頁連結的 Discord 伺服器

12. 總結

Pi 為開發人員提供了一個不受供應商限制、可自我擴展的程式碼撰寫代理，既可作為現成的終端機 CLI 使用，也可作為一組可組合的建構區塊（代理執行環境、模型層、終端機 UI、遙測）來打造自訂代理。它最適合希望掌控自身 AI 程式碼工具，而非依賴封閉式單一廠商助理的開發人員與平台團隊 — 但需明確理解，存取控制與隔離是操作者的責任，並非內建功能。