Pi Agent 擴充生態全攻略：Extension 要怎麼寫？社群如何把 Claude Code 功能一個一個補回來？

從 Claude Code 到 Pi：擴充生態為什麼重要？

2025 年 8 月，Mario Zechner 寫了一支名為 cchistory 的小工具，用來追蹤 Claude Code 每次更新的 system prompt 變更。他發現一件耐人尋味的事：system prompt 的長度持續膨脹，從數千 token 一路漲到上萬 token，但模型本身早被強化學習訓練到知道 coding agent 該怎麼做事。與其讓 harness 喋喋不休地提醒模型，不如把控制權還給模型。這個觀察讓他離開 Claude Code，動手打造自己的 agent，也就是後來的 Pi。

四個工具與極簡 prompt 的設計取捨

Pi 的核心設計非常極端。它的 system prompt 只有幾百個 token，工具就四個：read、write、edit、bash。沒有 MCP、沒有權限系統、沒有 sub-agents、沒有 plan mode。這種作法在 2026 年的 AI coding agent 圈幾乎是逆向而行，多數競品都在往整合式、batteries-included 的方向前進，Pi 卻選擇把功能砍到不能再砍。

Mario 的理由很直接：frontier model 已經被訓練到知道怎麼做軟體工程，多餘的提示詞反而綁手綁腳。2026 年 7 月，Anthropic 為了 Claude 5 世代模型刪掉超過 80% 的 Claude Code system prompt，等於官方自己往 Pi 的方向靠攏，這讓 Pi 的極簡路線獲得某種程度的認證。

對照 Claude Code：整合式系統的內建功能

Claude Code 走的是完全不同的路線。它內建 plan mode，讓模型先提出計畫再動手；內建 sub-agents，讓主要 agent 可以呼叫子代理平行處理任務；內建精細的權限控管，可以在執行指令前詢問使用者；也內建 MCP 支援，可以直接連接外部工具。這些功能對日常開發來說相當實用，尤其是專案規模變大之後，plan mode 與 sub-agents 幾乎成為標準配備。

第三方評測也顯示兩者的差異。Composio 在 2026 年 8 月 10 日發布的實測報告中，以自家 tool use eval 進行 100 小時的測試，Pi 在 30 個任務中通過 20 個，每個成功任務的成本是 0.028 美元；Claude Code 通過 16 個，每個成功任務的成本是 0.195 美元。前者成本不到後者的七分之一，但同篇報告也坦言，Claude Code 仍是多數開發者的 daily driver，Pi 更適合想要自訂工作流、使用本地模型或對成本敏感的使用者。

缺了什麼，社群就補什麼

Pi 的 README 寫得非常誠實：不內建權限系統，預設以啟動者的權限執行所有指令，需要隔離就自己 containerize。這意味著 plan mode、sub-agents、權限控管這些 Claude Code 內建的功能，在 Pi 的世界裡全部缺席。但有意思的地方在這裡，Pi 社群沒有抱怨，而是直接動手補。

擴充（extension）是 TypeScript 檔，跑在與 agent loop 同一個 process 裡，寫法門檻很低。再加上 Pi 可以讀自己的原始碼和官方文件，所以當使用者發現缺某個功能時，可以直接問 Pi 自己寫擴充。這種「缺什麼就長什麼」的機制，讓擴充生態快速累積。社群裡的開發者陸續寫出 plan mode 的模擬、sub-agents 的調度、權限確認的介面，把 Claude Code 的內建功能一個一個用擴充補回來。

IndyDevDan 對 Pi 的評價是「Claude Code 是 starter pack，Pi 是 endgame」。這句話在社群廣為流傳，它點出一個事實：擴充生態讓 Pi 可以無限成長，而且成長的方向由使用者自己決定，不是由維護者單方面主導。

為什麼社群自然走向寫擴充這條路？

這不是偶然，而是 Pi 設計哲學的自然結果。核心極簡，所以擴充成為唯一的功能擴展路徑；原始碼開放，所以任何人都能理解內部運作；擴充與 agent 同 process，所以寫起來沒有複雜的跨程式通訊。這四件事疊在一起，讓寫擴充變成 Pi 使用者遇到功能缺口時的第一反應。

另一個關鍵因素是透明度。Yage.ai 在 2026 年 5 月 18 日的比較中提到，Pi 最大的差異在於過程完全透明，Claude Code 的子代理你看得到結果，但看不到過程。這對想要深入理解 agent 行為的開發者來說很有吸引力。當你能看到每一步的決策，你自然會想要插手調整，而擴充就是調整的介面。

擴充生態的風險與台灣企業的落地考量

不過，擴充生態也有代價。最大的風險在於安全，Pi 沒有內建權限系統，擴充等於擁有完整的系統存取權，一旦裝到來路不明的擴充，等同把整台機器交給對方。台灣企業在導入時，必須把 containerization 當作必要條件，而不是選配。Gondolin、Plain Docker、OpenShell 這三種模式提供了隔離的起點，但實際部署時仍需要技術人員針對公司內部流程做設定。

另外，擴充的品質參差不齊，官方也不保證 API 穩定性。社群寫的擴充可能因為 Pi 核心程式碼的更新而失效，維護者 Mario Zechner 對 PR 的審查態度又比較嚴格，新進貢獻者的 PR 可能直接被自動關閉。對公司行號來說，如果要把擴充導入正式流程，建議鎖定版本並建立內部的測試機制。

回到根本問題：一個 frontier model 到底需要多少 harness？Pi 的答案是極少，其餘交給社群擴充。從 Claude Code 的整合式路線到 Pi 的極簡哲學，再到擴充生態的蓬勃發展，這條路徑說明了 AI agent 的樣貌還沒有定論。對台灣的中小企業而言，這反而是好消息，因為你不必被單一廠商的訂閱制綁住，可以選擇開源 MIT 授權的極簡 harness，搭配多家 LLM API，再依照自身需求撰寫擴充。這種組合在成本與彈性之間，提供了整合式產品難以比擬的空間。

Extension 的運作原理：一個 TypeScript 檔案如何融入 agent loop？

前幾章談過 Pi 的極簡哲學、安裝方式與競品比較，這章要鑽進擴充生態的底層，看看一支 TypeScript 檔案到底怎麼進到 agent loop 裡。把 Pi 的擴充想像成一般的外掛程式，很容易得到錯誤的印象，以為它跑在獨立沙盒，透過某種通訊協定與主程式互動。實際的運作方式更為直接：擴充本質上就是一個 TypeScript 檔案，與 agent loop 跑在同一個 process，共用同一份記憶體空間，可以直接呼叫 Pi 自己的 API。這項設計決定了擴充的寫作門檻、執行效能，也解釋了它與 MCP、sub-agent 之間的根本差異。

要理解擴充怎麼融入 agent loop，得先回顧 Pi 的 agent loop 樣貌。Pi 的系統提示詞不到一千個 token，工具只有 read、write、edit、bash 四個。循環的運作方式是先讀取 system prompt，讓模型判斷下一步要做什麼，模型決定呼叫哪一個工具，工具執行完畢後把結果回傳給模型，如此反覆直到任務完成。擴充就在「工具被呼叫」的那一刻插入，它不改變其他 loop 的邏輯，只是在工具清單中多註冊幾個條目。

載入流程：從目錄掃描到工具註冊

擴充的生命週期從 Pi 啟動時開始。Pi 依照

實戰教學：從零寫一個「執行前確認」的權限擴充

Pi 的擴充機制是它與其他 coding agent 最不同的地方，它不像 Claude Code 或 Codex 那樣內建完整的權限管理，而是把決定權交還給使用者。github.com/earendil-works/pi 的 README 明言，Pi 預設以啟動者的權限執行，沒有內建的權限系統，需要隔離就自己 containerize。這聽起來像是缺點，但換個角度想，這代表我們可以完全掌控工具的行為。這篇教學會帶你從零建立一個最實用的擴充：在 Pi 執行 bash 指令之前，先停下來問使用者一句「真的要執行嗎？」。

為什麼選 bash 當範例？因為 bash 是四個工具之中風險最高的一個。read 只是看檔案，write 和 edit 只影響工作目錄的內容，bash 卻能執行任何指令，包括刪檔、安裝套件、連上遠端伺服器。實務上我們最常遇到的情境，就是模型在自動化過程中突然想做一個我們沒有預期到的高風險操作。與其事後懊悔，不如在事前攔截。這個擴充會針對 bash 工具包上一層確認機制，使用者可以選擇允許、拒絕，或直接中斷整個任務。

擴充的基本結構：一個 TypeScript 檔案就搞定

Pi 的擴充是一支 TypeScript 檔案，跑在 agent loop 的同一個 process 裡。這代表擴充可以直接讀取 Pi 的內部狀態，不需要另外開一個服務或寫 IPC 溝通。以 Pi coding agent 的架構來說，擴充透過註冊工具的方式加入 loop，工具註冊完成之後，模型就有機會呼叫它。我們要做的「執行前確認」不只是註冊一個新工具，而是攔截既有的 bash 工具，這需要走 Pi 提供的 hook 機制。Pi 的文件在 pi.dev/docs/latest，擴充開發者可參考官方說明，不過實際上讀原始碼更直接，Pi 的原始碼完全開放，作者 Mario Zechner 自己也說，缺功能就自己看原始碼補。

先建立專案資料夾。假設我們的工作目錄叫做 pi-confirm，裡面放一個 src 資料夾和一個 package.json。Pi 的套件是 @earendil-works/pi-agent-core，擴充需要匯入它的型別。如果你已經用 npm 安裝過 pi-coding-agent，這支套件會一起被帶進來。TypeScript 的設定沒有什麼特別要求，只要 target 設為 ES2022 以上，module 設為 NodeNext 就能動。擴充本身不需要編譯成獨立的 bundle，Pi 會用 tsx 直接載入 TypeScript 原始碼，這樣開發時的 feedback loop 很短，改完存檔就能重跑。

// src/confirm-bash.ts
import { defineExtension } from '@earendil-works/pi-agent-core'

export default defineExtension({
  name: 'confirm-bash'，
  hooks: {
    beforeToolCall: async (call， context) => {
      // 攔截邏輯
    }
  }
})

逐步撰寫：攔截 bash 工具的前置檢查

上述程式碼是擴充的骨架。defineExtension 接受一個物件，裡面可以定義擴充的名稱、要註冊的工具，以及各種 hook。beforeToolCall 這個 hook 會在工具被呼叫前觸發，我們可以在這裡檢查工具名稱，如果是 bash，就丟出確認訊息給使用者。Pi 的互動介面會把確認訊息顯示在終端機上，等待使用者輸入 y 或 n。如果使用者選擇 n，我們就丟出一個錯誤，讓模型的這次工具呼叫失敗，模型看到錯誤訊息之後，通常會改採其他方式，或直接回報任務無法繼續。

這裡有一個實作細節要注意：Pi 的 bash 工具在非互動模式或背景執行時，不一定有終端機可以問問題。為了避免擴充在無頭環境卡死，我們可以檢查 context 裡有沒有提供 interact 方法。如果有就詢問，沒有就放行。這說起來簡單，但正是這種防呆設計，讓擴充在 CI 環境也能正常運作，不會因為等待輸入而逾時。另外，我們還可以把允許清單寫在環境變數裡，例如使用者設定 PI_ALLOW_COMMANDS 為 “npm test”，這些指令就直接放行，不必每次詢問。

const ALLOW_PATTERN = process.env.PI_ALLOW_COMMANDS?.split('，').map(s => s.trim()) ?? []

if (call.tool === 'bash') {
  const command = call.input.command
  const match = ALLOW_PATTERN.some(pattern => command.includes(pattern))
  if (!match && context.interact) {
    const answer = await context.interact(`允許執行嗎？n${command}n[y/N] `)
    if (answer.toLowerCase() !== 'y') {
      throw new Error('使用者拒絕執行此指令')
    }
  }
}

註冊擴充與本地測試

擴充寫好之後，要讓 Pi 知道它的存在。Pi 的設定檔是 pi.config.ts，通常放在專案根目錄。我們在設定檔裡引入擴充檔案的相對路徑，Pi 啟動時就會掃描並載入。根據我們在 2026-08-24 查證的 GitHub 頁面（github.com/earendil-works/pi），Pi 的擴充機制一直保持穩定，官方文件建議使用相對路徑，避免不同機器上的絕對路徑造成載入失敗。設定檔的內容大致如下。

import { defineConfig } from '@earendil-works/pi-coding-agent'

export default defineConfig({
  extensions: [
    './src/confirm-bash.ts'
  ]
})

測試的方式很直接：開一個新的專案資料夾，隨便叫 Pi 執行一個無關緊要的 bash 指令，例如 echo hello，觀察終端機有沒有跳出確認訊息。第一次跑建議用一個無害的指令，不要拿 rm -rf 來測試，萬一擴充沒生效就糟了。確認擴充有攔截之後，再試著輸入 n，看看 Pi 是否會回報失敗給模型。接著試試看設定環境變數 PI_ALLOW_COMMANDS，確認白名單的放行邏輯正常。這三個測試都過關，擴充就算完成。

比較進階的測試方式是寫一個最小的 agent loop，直接在 Node.js 裡驅動 Pi 的 agent runtime，然後呼叫 bash 工具。這需要比較多 boilerplate，但好處是可以寫成自動化測試，未來改動擴充時不怕回歸。實務上我們會先用手動測試確認行為，再決定要不要投入寫自動測試。介面工具的 hook 邏輯通常變動不大，一旦穩定之後，自動測試的成本就值得了。

進階變化：把白名單機制帶進工作流程

執行前確認只是一個起點，同樣的模式可以延伸出更多保護機制。例如我們可以針對不同專案設定不同的允許指令，像是資料分析專案允許 pip install，但不允許 curl 下載任意檔案。或者我們可以記錄所有被拒絕的指令，事後輸出成一份報告，幫助開發者了解模型常常想做哪些危險操作，進而調整 system prompt 或專案指引。這個擴充的寫法，也可以套用到 read、write、edit 三個工具，例如限制 write 只能寫在特定子目錄。

要特別提醒的是，擴充的確認機制不是安全邊界，它比較像是一個快速煞車。真正要隔離高風險操作，還是要回到 Pi 官方建議的 containerize 路線，例如搭配 Gondolin 擴充或 Plain Docker。擴充能攔截的是模型呼叫工具的意圖，但如果模型找到其他方式繞過工具，或者 bash 指令本身透過 shell 語法躲過字串比對，白名單就可能破功。所以這個擴充適合當作日常開發的防呆，不適合當作維運環境的唯一防線。

替代方案有限公司觀點

我們在協助台灣企業導入 AI Agent 的過程中，最常被問到的問題就是「模型亂執行指令怎麼辦」。多數客戶的第一反應是找一個內建權限管理的商用產品，但我們的經驗是，與其把信任交給一個黑盒子，不如自己掌握攔截邏輯。Pi 的擴充機制讓這件事變得很簡單，一支 TypeScript 檔案就能做到企業最在意的執行前確認。這對台灣的中小企業特別有意義，因為 SME 的 IT 人力有限，通常沒有餘裕把整套容器化基礎設施建起來，輕量級的擴充攔截是成本最低的起手式。我們建議導入時先從 bash 確認開始，跑一個月之後檢視被拒絕的指令清單，再逐步收緊白名單，之後再評估是否需要更完整的 sandbox 方案。這樣的做法可以讓企業在享受 Pi 低成本、多供應商靈活性的同時，也兼顧內部稽核的基本要求。

補齊功能的思維模式：從 Claude Code 功能清單到 Pi Extension 的對照分析

多數開發者第一次接觸 Pi 時，都會冒出同一個疑問：少了 plan mode、沒有 sub-agents、也不支援 MCP，這種極簡工具真的能接手日常工作嗎？這個問題背後藏著一個更根本的誤解，我們習慣把 Claude Code 的介面當成 agent 的本質，卻忘記那些功能只是 Anthropic 用 TypeScript 堆出來的產品設計。Pi 的擴充機制同樣是 TypeScript 檔案，跑在 agent loop 的同一個 process 裡，換句話說，Claude Code 做得到的每一件事，理論上都存在於 Pi 的實作可能性之中。差別只在於你有沒有能力描繪那張功能對照表。

我們在協助客戶搬遷工作流程時，習慣把這個過程拆成三個步驟。第一步是盤點，打開 Claude Code 的功能選單，把 plan mode、sub-agents、MCP 連接器、Slash 指令、自動完成、權限控管全部列成一張清單。第二步是分類，標註每一項功能背後的本質是流程控制、工具擴充、還是安全機制。第三步才是對照，針對每個類別找出 Pi 擴充系統裡對應的掛載點。這套方法論不挑工具，換成 Codex 或 Hermes 也適用，它要訓練的是一種拆解產品表層、直視底層機制的能力。

plan mode 的實作：攔截工具呼叫，建立兩段式執行流程

Claude Code 的 plan mode 讓模型先產出完整計畫，經使用者確認後才動手。Pi 沒有這個內建模式，但你可以在 extension 的 tool 層做一個薄薄的 wrapper，把 read、write、edit、bash 四個工具全部包起來。設計上只需要一個狀態變數，當 mode 是 planning 時，wrapper 攔截所有工具呼叫，只回傳模擬結果，例如 bash 工具改成回傳「此指令將在鎖定後執行」，write 工具改成輸出預期的寫入內容。當使用者切換到執行模式，wrapper 放行真實呼叫，同時保留一份完整的工具呼叫日誌，讓你事後核對模型有沒有按照計畫走。

這個實作方向比表面上看起來更靈活。Claude Code 的 plan mode 是固定的產品功能，行為細節由官方決定，你只能接受。但 Pi 的 wrapper 可以加入企業自己的規則，例如在計畫階段就檢查 write 路徑是否落在白名單目錄，或對 bash 指令做靜態掃描，偵測到 rm -rf 或 curl 下載腳本就直接標記為高風險。我們實際測試過，用不到一百行程式碼就能完成基本版本，背後的關鍵是攔截邏輯與 agent loop 的生命週期綁在一起，擴充並不影響模型本身的推理能力。

sub-agents 的替代方案：包裝子程序，讓工具呼叫產生平行執行

Claude Code 的 sub-agents 讓你指派多個子代理平行處理不同任務，Pi 沒有這個抽象層，linux 行程本身就可以扮演這個角色。最單純的實作是寫一支 extension，在 bash 工具裡包裝一個「背景任務管理器」，每次需要 sub-agent 時，就用 nohup 啟動另一個獨立的 Pi 實例，餵給它一個包含任務描述的檔案路徑，完成後把結果寫入指定的輸出檔。主 agent 輪詢檔案是否出現，再讀取內容併入自己的 context。這種做法的好處是每個子任務都是獨立的 process，記憶體隔離、崩潰互不影響，也方便平行擴充。

進階一點的做法是寫一支 TypeScript 的 task dispatcher，建立一個任務佇列，把大任務切成小塊丟給多個 process 處理，然後彙整結果。Yage.ai 在 2026 年 5 月的比較報告中特別點出，Claude Code 的子代理你看得到結果、看不到過程，Pi 的做法反而讓每個子程序的指令與輸出都留在終端紀錄裡，稽核成本更低。對台灣的軟體團隊來說，這種透明性在交付客戶時是加分項，你可以直接出示子代理做了哪些事，而不是泛泛而談「AI 跑完了」。

MCP 支援的轉譯：把外部服務接線的工作還給程式碼

MCP 是 Claude Code 連接外部工具的主流協定，Pi 的極簡路線刻意不內建，但這不表示你只能用四個內建工具。別忘了 Pi 的擴充本身就是一段 TypeScript 程式碼，你可以直接引入 MCP 的 client SDK，在 extension 裡建立連線，再把 MCP 工具註冊成 Pi 的工具。過程大概分四步：安裝 MCP SDK、設定 server 的 endpoint 與認證、呼叫 listTools 取得工具清單、逐一包成 Pi 的 tool 介面。坊間已經有社群實作把 GitHub MCP server、檔案系統 MCP、資料庫 MCP 接進 Pi，這些範例散落在 GitHub 上，搜尋 pi extension mcp 就能找到。

如果你的需求只是連一兩個外部 API，老實說不需要引入 MCP 的重量級架構。直接在 extension 裡用 fetch 呼叫 REST endpoint 更輕、更好除錯，也更容易讓台灣的資安團隊審查，因為整段程式碼都在你的 repo 裡。MCP 真正的價值在於標準化，如果你有一整批既有工具是用 MCP 寫的，引入 SDK 是合理的，這部分就是標準的 TypeScript 開發工作，門檻不高。

其他功能的補齊優先序：從權限管控與自動完成開始

我們建議企業導入時，把補齊功能的優先順序列成一張表，第一優先永遠是權限管控。Pi 官方在 README 明言不內建權限系統，預設以啟動者權限執行，需要隔離就自行 containerize。但如前一章所述，一支 TypeScript 攔截器就能做到執行前確認、路徑白名單、指令黑名單，這是風險最高、也最該先補的一塊。第二優先才是 plan mode，因為多數 SME 的 IT 人力有限，需要一個機制讓非技術主管也能審核 AI 的動作。第三優先才是 sub-agents 與 MCP，這些屬於生產力增強，沒有並不會出事。

自動完成與 Slash 指令這類 UX 功能，反而不急著補。Claude Code 的便利有一部分來自它的整合式介面，但 Pi 的使用者多半是從終端機出發的開發者，本來就習慣簡潔的工作環境。如果你真的需要快速指令，例如 /review 或 /test，寫一個 extension 偵測使用者輸入的斜線指令，展開成對應的 prompt 模板即可，這大概是所有擴充裡最簡單的一種。

功能對照表：一頁看懂遷移藍圖

這張對照表可以直接當成內部遷移評估的檢查清單。用 Composio 在 2026 年 8 月 10 日公布的評測數據來看，Pi 在 tool use 測試中拿下 20 分，每個成功案例成本僅 0.028 美元，Claude Code 是 16 分、成本 0.195 美元，來源：Composio 實測報告。補齊功能並不會動搖 Pi 的成本優勢，因為擴充跑在同一個 process，沒有額外的 API 呼叫，模型費率維持不變。

最終還是要回到你自己的使用情境來驗證。挑三個你每個禮拜都會用 Claude Code 處理的任務，先在 Pi 上逐一手動執行，把卡住的地方記下來，再針對那些瓶頸寫擴充。不要一開始就想複製全套功能，那是產品部門的思維，不是 agent builder 的思維，後者的原則是讓最小可行擴充解決最大的痛點。Pi 的原始碼與文件都是開放的，擴充寫完之後，可以參考 官方 repository 的 extension 範例，或到 pi.dev 文件查詢 API 規格，社群在 Reddit 討論串也累積了不少實作筆記，這些都是現成的參考資源。

台灣企業導入視角：開源擴充生態如何降低 SME 的 AI Agent 入門門檻

台灣的中小型企業，尤其是接案公司與新創團隊，在評估 AI Agent 導入時，往往卡在一個現實問題：團隊裡沒有專門的 AI 工程師，甚至連 DevOps 人力都吃緊。市場上的 coding agent 產品，像是 Claude Code 或 OpenAI Codex，雖然號稱開箱即用，但訂閱費用、平台綁定，以及黑箱化的決策流程，對預算敏感的 SME 來說都是隱形成本。開源專案 Pi Agent 在 2026 年 8 月 24 日於 GitHub 上已累積 95，超過 98,294 顆星（earendil-works/pi），以 MIT 授權釋出，主打極簡的 agent loop，對台灣企業來說，它的擴充生態正好補上商業產品不願意談的缺口：權限控管與操作流程。

權限控管缺口：擴充生態是解法，但不是免錢的午餐

Pi 的官方 README 開宗明義表示，它不內建權限系統，預設以啟動者的身分執行所有指令。這對技術底子厚實的開發者來說是彈性，對缺乏技術編制的 SME 卻是一顆未爆彈。好在 Pi 的架構把擴充寫成 TypeScript 檔案，並且跑在 agent loop 的同一個 process 裡，意思是任何缺的功能，團隊可以自己動手補。例如想限制 agent 只能寫入特定資料夾，或要求在執行 bash 之前先經過審核，這些都可以透過自行開發的擴充達成。

但前提是，團隊內必須有人看得懂 TypeScript。Pi 的擴充不是填寫設定檔那麼簡單，它需要理解 agent 的事件週期，以及如何攔截工具呼叫。這個技術門檻，決定了「開源省下來的成本」是否真的划算。如果公司連一個能改 TypeScript 的工程師都請不起，那 Pi 的擴充生態反而會成為另一道學習曲線。

台灣接案公司與新創的成本實算：pay-per-token 比較划算嗎

以台灣常見的三到十人接案公司為例，每個月實際跑 coding agent 的次數，可能只有幾十次到上百次。Composio 在 2026 年 8 月 10 日公布的實測數據顯示，在自家 tool use 評測中，Pi 通過 20 項中的 30 項，每個成功任務的成本是 0.028 美元；對照組的 Claude Code 通過 16 項，每個成功任務的成本是 0.195 美元（來源）。這代表使用量低的小公司，走 pay-per-token 模式，每個月的 API 費用可能壓在幾美元到幾十美元之間，而訂閱制方案每個月的基本開銷就是 20 美元起跳，甚至有高達 200 美元的高階方案。

下面這個表格，粗略比較了兩種計費模式在小型團隊情境下的差異：

不過要提醒的是，訂閱制的 20 美元通常還包含其他協作功能，不能單純用單一任務成本來定勝負。比較合理的評估方式是，把自家團隊過去三個月的實際任務量抓出來，分別用兩種計費模式試算，再決定要走哪條路。

containerization 不是選配，是導入 Pi 的必要條件

Pi 原始設計的安全模型，是「先假設 agent 值得信任，再用外部機制隔離」。官方文件列出的隔離方式有三種：Gondolin 擴充、Plain Docker、OpenShell。對台灣 SME 來說，這不是技術炫技，而是基本的資安衛生。如果沒有 containerization，agent 一旦被 prompt injection 誘導，可能會讀取公司內部檔案、修改程式碼，甚至觸發部署流程。台灣的接案公司手上往往是客戶的原始碼與資料庫憑證，這類風險的損失遠高於導入成本的節省。

好消息是，這三種隔離模式都屬於擴充生態的一環，可以跟前面提到的權限控管一起設計。例如用 Plain Docker 跑 agent，同時用自訂擴充限制網路存取，或者要求特定指令必須經過人工確認。這個組合，正是開源專案對 SME 最實際的價值，商業產品把這些功能封裝在訂閱方案裡，開源社群則把決定權交還給使用者。

回到團隊能力的問題。一家公司如果連 Docker 都不熟，貿然導入 Pi 只會把維運負擔轉嫁給現有員工。我們會建議，先把「誰負責寫擴充」「誰負責看 container log」「agent 出錯時誰來止血」這三個問題想清楚，再開始安裝。

替代方案有限公司的觀點

我們在協助台灣客戶導入 AI Agent 的過程中，最常被問到的問題是：到底要選開源工具還是商業產品？我們的答案是，先別急著選工具，先把自家的工作流程畫出來。

以 Pi 為例，它確實把 AI Agent 的入門門檻大幅降低，npm 一鍵安裝、MIT 授權、多供應商 API 支援，這些特性讓小型團隊可以用極低的成本開始實驗。但「可以用」跟「用得好」之間，隔著一道名為維運的深淵。台灣 SME 真正缺少的不是工具，而是懂得把工具放進既有流程的人。我們的做法是，在導入前期先協助客戶盤點權限需求，設計 containerization 策略，再由客戶自家的工程師接手擴充的長期維護。這樣一來，開源省下來的錢，才能真的留在公司裡，而不是轉變成另一筆隱形的技術債。

Pi 這個專案讓我們看到，coding agent 的戰場已經從「誰的功能最多」轉向「誰的架構最透明」。對預算有限、又不想被單一廠商綁死的台灣團隊來說，這是一條值得認真評估的路。唯一的條件是，請確保團隊裡至少有一個人，願意把 TypeScript 當成基本配備。

替代方案有限公司觀點：我們如何用 Hermes 與 Pi 擴充生態回答客戶的選擇題

過去這一年，台灣企業對 AI Agent 的詢問度明顯升溫，但多數客戶走進我們辦公室時，問的第一句話往往不是「這套工具能做什麼」，而是「我到底該用哪一個 agent」。老實說，這道選擇題沒有標準答案，而我們自己的做法，是同時把腳踩在兩個生態裡：一邊用 Hermes 當作日常的持久助理，一邊把 Pi 當作 coding 任務的極簡 harness。這不是騎牆，而是我們在輔導客戶導入後，逐漸收斂出來的工作哲學。

自家的工具組合：Hermes 當秘書，Pi 當工匠

先說我們怎麼分工。Hermes 之於我們，比較像一個跨頻道的持久助理，它記得專案的來龍去脈，會出現在 Slack、Discord 或任何我們習慣的溝通介面裡，該追蹤的排程、該提醒的事項，它會主動丟出來。Pi 則完全不一樣，它活在終端機裡，只有 read、write、edit、bash 四個工具，system prompt 不到 1，000 個 token，卻能承接我們最繁重的程式碼任務。我們內部的習慣是，凡是需要連續好幾個小時盯著程式碼的工作，就交給 Pi；凡是需要記得「上禮拜客戶說的那個需求後來怎麼了」的瑣事，就交給 Hermes。

會有這樣的分工，並不是我們一開始就規劃好的。起初團隊裡也有人主張全部押注在單一工具上，但實際跑了一季之後，我們發現兩者的定位根本是互補的。Hermes 強在跨頻道的記憶與排程，Pi 則專注在 coding harness 的極致輕量。把兩者硬湊在一起比較，就像拿螺絲起子去量錘子的重量，意義有限。

面對客戶的選擇題，我們怎麼拆

客戶來問「該用哪個 agent」時，我們不會急著推產品，而是先請對方回答三個問題：任務類型、預算結構、技術能力。這三個維度幾乎決定了九成以上的答案。

如果客戶要處理的是明確的程式碼任務，例如把一段 Python 腳本改寫成 API、幫內部工具補測試、或是在既有專案裡加功能，而且團隊中有人敢碰終端機，我們通常會建議先試 Pi。原因很實際，Pi 是 MIT 授權，沒有每月訂閱的進入門檻，Pay-as-you-token 的成本結構對用量不高的 SME 來說，常常比月費制便宜一大截。根據第三方 Composio 在 2026-08-10 發布的實測，以自家 tool use eval 跑 100 小時，Pi 通過 20/30 個任務、每個成功成本約 0.028 美元，Claude Code 則為 16/30、每個成功成本 0.195 美元（來源）。這個成本差距，對預算敏感的台灣中小企業來說，是很有感的數字。

但如果客戶要的不是寫程式，而是「有一個東西幫我記得所有事情，並且在我開會前把資料整理好」，那我們會明確說，這不是 Pi 的戰場。Pi 沒有聊天頻道整合、沒有排程、沒有跨 session 的記憶設計，硬要拿它來做這些事，等於要它做它不曾被設計來做的事。這種需求，Hermes 那一類的持久助理反而更合適。我們在 2026-07-10 的 MCPlato 五 agent 比較報告中看到同樣的結論，Pi 被定位為最小終端 harness，Hermes 則被歸類為持久助理，兩者各自有清楚的適用場景（來源）。

技術能力的差異，決定導入路徑的長短

第三個問題是技術能力，這往往是最殘酷的篩選器。Pi 的極簡建立在一個前提上，使用者有能力自己補齊缺的東西。它的擴充是 TypeScript 檔案，跑在與 agent 相同的 process 裡，想要加 plan mode、加 sub-agent、加 MCP，都得自己動手或依賴社群套件。我們遇到不少客戶，聽完 Pi 的省錢故事之後興致勃勃，結果發現團隊裡沒人有把握維護 TypeScript 擴充，還是回頭選整合度高的方案。

我們的立場是，與其讓客戶裝了一套之後放著長灰塵，不如在導入前就誠實盤點。如果團隊裡連一個能把 TypeScript 當基本配備的人都沒有，Pi 再便宜都是災難；反之，如果團隊有技術底子，Pi 的開放性會是極大的優勢，因為它不會綁死你，你想接 OpenAI、Anthropic、Google 或是本地模型，它都允許。

誠實面對 Pi 的短板：權限是客戶自己該扛的責任

做顧問的不能只講好處，風險不講清楚，出事就是我們的責任。Pi 的 README 開宗明義就寫了，它不內建權限系統，預設以啟動者的權限執行所有指令。白話文來說，就是如果你用 root 啟動它，它就有 root 的權力，這在台灣企業的資安環境裡，是很多人都會皺眉頭的事。我們的標準作法是，在導入前先陪客戶盤點主機上的權限邊界，設計 containerization 策略，再用 Gondolin、Plain Docker 或 OpenShell 這幾種模式把 agent 關在隔離環境裡跑。

這個過程絕對不是「裝完就能用」那麼輕鬆，但我們會跟客戶說清楚，這份功夫換來的是自由。你不需要為了用某個 agent 而被迫接受一整包你根本用不到的產品，一切都可以客製。

給台灣市場的落地建議：不要盲選，先小規模驗證

如果要用一句話總結我們的建議，那就是「先別急著全面導入」。我們輔導客戶的 SOP，是先挑一個兩週內可完成的內部專案，把 Pi 或 Hermes 放進去跑，建立一個可量化的評估基準，例如完成任務數、每成功任務成本、需要人工介入的次數。時間到了之後，讓實際使用的人來投票，而不是讓主管拍板。

這套流程聽起來樸素，但我們看過太多失敗案例，都是因為企業一開始就選了「聽起來比較厲害」的方案，結果導入三個月後發現團隊根本沒在用。工具的好壞，永遠是相對於使用者習慣而存在的。

我們認為，台灣的 SME 在 AI Agent 這波浪潮中，最大的優勢就是沒有歷史包袱，可以跳過西方企業那種綁定單一廠商的基礎設施，直接從開源生態裡挑適合自己的零件。而 Pi 與 Hermes 這兩個看似路線不同的專案，正好代表了兩種截然不同的思考方式：一個把「少」做到極致，一個把「記憶」做到極致。對我們來說，它們不是二選一的敵人，而是工具箱裡各司其職的夥伴。客戶帶著選擇題來，我們的工作不是替他們選邊站，而是陪他們把題目拆開，找出最適合當下處境的解方。

這是我們公司在 2026 年最重要的體悟：AI Agent 的導入，不該是信仰問題，而是工程決策。把任務類型、預算結構、技術能力攤開來談，答案自然會浮現。我們作為顧問的價值，不是比客戶更懂某套工具，而是比客戶更早看過足夠多的失敗與成功案例，能在關鍵時刻說出那句「這個需求不該用這個工具」。

結論：動手寫你的第一個 Pi Extension，成為擴充生態的一份子

這六天我們從 Pi 的起源、極簡哲學、安裝實測，一路談到與 Claude Code、Codex 的對決，以及台灣企業導入的權衡。如果你從第一天跟著看到這裡，應該已經發現一件事情：Pi 從頭到尾不是一個「裝好就拿去用」的工具，它是一塊畫布，等著你親手在上面畫出屬於自己的工作流。它的作者 Mario Zechner 在 2025 年 8 月動手寫 Pi 的時候，起因是不滿 Claude Code 的複雜與封閉；一年後，這份不滿長成了近九萬六千顆星的開源專案。而這股動能的下一步，不在維護者手上，而是在每一個願意打開編輯器的人手上。

擴充生態的核心價值：讓工具長成你的形狀

Pi 的官方定位是「AI agent toolkit」，三個套件各自獨立：pi-coding-agent 提供 CLI、pi-agent-core 負責 agent runtime、pi-ai 統一超過二十家供應商的 LLM API。它的預設功能刻意做得很小，只有 read、write、edit、bash 四個工具，system prompt 不到一千個 token。這個設計引來兩種反應，一種人覺得「什麼都沒有」，另一種人卻看見無限可能。後者會在 Pi 的擴充生態裡找到歸屬，因為 Pi 的擴充是用 TypeScript 寫成的檔案，而且在 agent loop 的同一個 process 裡執行。意思是，你寫的每一行程式碼都擁有完整的控制權，沒有黑盒子中介層，沒有隱藏的權限閘門。

社群早就把這個特性玩出各種花樣。有人把 Claude Code 的 plan mode 用擴充補回來，有人加上 sub-agents 的能力，也有人為了自己的團隊打造專屬的 MCP 整合。IndyDevDan 在 2026 年的一篇評論中說了一句名言：「Claude Code 是 starter pack，Pi 是 endgame。」這句話精準點出擴充生態的位置，Claude Code 給你的是一整套打包好的體驗，Pi 給你的是一把可以無限擴張的鑰匙。你不用再等官方實作某個功能，不用在 issue tracker 裡許願，自己動手，十分鐘就能把想法變成工具。

動手寫第一個 extension，比你想的還簡單

寫 Pi 擴充的門檻並不高。你只需要熟悉一點 TypeScript，其餘的都可以靠 Pi 自己補完，因為 Pi 可以讀取自己的原始碼和官方文件。最實際的起手式是這樣：先安裝 @earendil-works/pi-coding-agent，接著打開 pi.dev/docs/latest 找一份現成的範例，複製到本地端，然後動手改。你甚至可以直接對 Pi 說：「請讀取原始碼裡的 extension API，解釋它怎麼運作，然後幫我寫一個能列出目前工作目錄檔案的擴充。」Pi 會帶著你走過整個過程，就像一個有耐心的同事。

具體可以從三件小事開始嘗試：

• 讀原始碼，Pi 的程式碼就在 GitHub 上的 earendil-works/pi，擴充相關的目錄與型別定義都寫得很清楚，直接當作參考手冊。
• 從現有擴充改起，GitHub 上已經有社群貢獻的各式 extension，找到最接近你需求的那一個，改掉幾行參數就能變成自己的版本。
• 請 Pi 自己解釋 API，這是最符合 Pi 精神的做法，把問題丟回給它，讓它讀文件、寫範例、陪你 debug。

當你完成第一個擴充，你會發現整個思考角度改變了，你不再只是一個工具的使用者，你變成生態的參與者。那種「我可以改裝我的 coding agent」的踏實感，是任何訂閱制產品都無法給你的。

成本與品質，第三方實測給的答案

也許有人會擔心，自己動手組裝是不是代表品質打折。Composio 在 2026 年 8 月 10 日公布的實測結果提供了參考（來源連結）：在自家 tool use eval 上，Pi 以二十個成功案例通過三十項測試，每個成功案例的平均成本是 0.028 美元；Claude Code 通過十六項，每個成功案例成本高達 0.195 美元。Pi 在成本上幾乎是七分之一，成功率也更高，這還是在沒有大量訂製擴充的條件下達成的數字。換句話說，擴充生態不是靠犧牲效能換來的，它是把原本就開放的能力，進一步交還給使用者。

當然，擴充的靈活也伴隨責任。Pi 的 README 明確表示不內建權限系統，預設以啟動者的權限執行。當你寫擴充時，等於是在 agent 的心臟地帶放進自己的程式碼，務必留意安全邊界。如果你要讓 Pi 執行高風險操作，請先做好 containerization，Gondolin、Plain Docker、OpenShell 都是官方建議的方向。這是每一位 Pi 擴充作者都該放在心裡的紀律。

資源、下一步與我們的聯絡信箱

寫作這篇文章的同時，我們整理了最實用的資源清單，方便你直接取用：

• 官方網站與文件：pi.dev 與 pi.dev/docs/latest
• 原始碼與 issue 討論：github.com/earendil-works/pi，目前超過九萬五千顆星，每日持續更新
• 第三方評測與對比：Composio 的 Pi vs Claude Code 實測、MCPlato 在 2026 年 7 月的五款 agent 比較、Yage.ai 的透明度分析

如果你在安裝、寫擴充或導入的過程中遇到任何問題，歡迎寫信到 [email protected]。我們是替代方案有限公司，團隊成員自己就是 Pi 與 Hermes 的實際使用者，也協助台灣企業評估與導入 AI Agent。你的問題，很可能就是我們下一個研究主題的起點。

Pi 告訴我們的事情很單純：工具的最終形態，應該由使用者決定，而不是由廠商決定。花二十分鐘寫下你的第一個擴充，你就能體會那種自由。這一步走出去，你就不再是旁觀者，而是擴充生態的一份子。動手吧，你的第一個 extension 正在等你。

📩 有任何問題或需要協助，歡迎聯絡我們：[email protected]