Pi Agent Harness：把 AI 編碼代理拆成可組裝、可重跑的工程工具鏈

AI 編碼工具正在從「幫我補一段程式」走向「替我完成一個可驗證的工程任務」。但功能越多，工作流也越容易被單一產品綁死：模型、工具、上下文、工作階段、權限與自訂指令全部揉在同一個介面裡，換一個模型或部署方式就得重新適應。Pi Agent Harness 提供了另一種方向：保留一個最小的終端代理核心，再用 TypeScript extensions、skills、prompt templates、themes 與 packages 組合出自己的工作方式。

我認為 Pi 值得研究的地方，不只是它是一個 coding agent CLI，而是它把「代理產品」拆成幾個可以被替換、測試與重複執行的工程層。這種拆分讓同一套 agent runtime 可以透過互動模式使用，也可以進入 print、JSON、RPC 或 SDK 流程；團隊可以先用 CLI 驗證工作流，之後再把相同能力嵌入自己的服務。

先講結論：Pi 解決的是工作流鎖定，而不是模型能力不足

Pi 的官方定位是 minimal terminal coding harness。它預設提供 read、write、edit、bash 等工具，讓模型能讀取專案、修改檔案並執行命令；同時不把 sub agents、plan mode、MCP 或複雜的權限提示視為核心必備功能，而是留給 extensions、skills、外部套件或你自己的工程流程處理。

這個選擇有兩個直接結果。第一，核心相對容易理解，使用者不需要先學一整套企業級控制台才能跑第一個任務。第二，團隊不必接受工具作者預設的協作抽象，可以自行決定要不要加入子代理、檢查清單、MCP、審批流程或沙箱。換句話說，Pi 把代理的「最小執行迴圈」固定下來，把代理的「產品形狀」交還給使用者。

這不代表 Pi 適合所有人。如果你期待開箱即用的多代理編排、完整的計畫模式、細緻的權限 UI 或內建 MCP 生態，Pi 的刻意克制反而會變成額外工作。但對想把 AI agent 放進既有工程流程的人來說，這種取捨很有價值。

架構拆解：從統一模型介面到可嵌入的 Agent runtime

Pi 專案不是只有一個 CLI。官方 monorepo 將能力拆成幾個彼此相關但用途不同的套件：

@earendil-works/pi-coding-agent：互動式 coding agent CLI，負責終端介面、命令列模式、工作階段與資源載入。
@earendil-works/pi-agent-core：具有工具呼叫、狀態管理與事件串流的 agent runtime。
@earendil-works/pi-ai：統一多供應商 LLM API，讓上層程式不必把每個 provider 的請求格式寫死。
@earendil-works/pi-tui：終端 UI 元件與差異渲染能力。

這種拆分讓使用者可以依照需求選擇抽象層。如果只是想在終端裡完成程式碼修改，直接安裝 coding agent 即可。如果要做自己的 agent service，可以直接使用 agent-core；如果只需要多模型串接，則可研究 pi-ai 的 provider 與 model 介面。

agent-core 的基本模型是「狀態加事件」。Agent 會保存 system prompt、目前模型、工具與訊息，呼叫 prompt 後依序產生 agent start、turn start、訊息更新、工具執行與 agent end 等事件。這裡的重要性在於，UI 不必輪詢一個最後才出現的完整答案，而是可以在事件流中更新畫面、記錄工具執行、建立自己的審計軌跡或在特定事件後中止流程。

官方文件也明確區分 AgentMessage 與模型真正理解的 LLM message。前者可以包含 UI 或應用程式自訂的訊息型別；在送給模型前，再透過 transformContext 與 convertToLlm 修剪、注入或轉換上下文。這使得上下文治理不必硬編碼在每個 provider 裡，而能成為 runtime 的可插拔步驟。

工具執行同樣不是黑盒。Agent 支援平行或循序模式，也提供 beforeToolCall、afterToolCall 與 shouldStopAfterTurn 等鉤子。團隊可以在工具真正執行前做參數檢查，在結果回傳前補上審計資訊，或在完成一個回合後判斷是否應該先壓縮上下文，而不是繼續呼叫模型。

四種執行模式，讓同一個代理從終端走向服務

Pi coding agent 支援四種主要模式：互動模式、print 或 JSON 模式、RPC 模式，以及 SDK 嵌入模式。

互動模式適合人與代理一起工作。你可以在終端輸入問題，讓模型讀取檔案、修改程式與執行測試，並用 /model、/session、/tree、/compact 等命令管理模型與上下文。

Print 或 JSON 模式適合腳本與 CI。當一個任務可以由固定輸入觸發，例如「檢查這次變更是否有遺漏測試」，就不必啟動完整 TUI，而是把 prompt、檔案參照與結果接到既有管線。

RPC 模式適合由其他程序控制 agent。外部服務可以把 Pi 當成一個可通訊的工作程序，自己負責佇列、權限、觀察性與使用者介面。

SDK 模式則適合把 agent runtime 放進應用程式。官方的 createAgentSession 範例展示了如何建立記憶體內工作階段、送出 prompt，並以程式方式取得執行結果。這條路徑的價值是：你可以先用同一個 coding agent 驗證提示與工具，再逐步把它收斂成產品內的受控能力。

實際上手：先用 CLI 完成第一個可驗證任務

1. 安裝 coding agent

官方快速開始使用 npm 全域安裝，並建議以 --ignore-scripts 避免安裝階段執行相依套件的 lifecycle scripts：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

也可以使用官方安裝器：

curl -fsSL https://pi.dev/install.sh | sh

這裡的 curl 安裝方式應只在你已經檢查腳本來源、執行環境與供應鏈風險後使用；若團隊需要可重現建置，優先採用已鎖定版本的 npm 安裝與內部套件快取。

2. 登入模型供應商

可以透過環境變數提供 API key，也可以進入 Pi 後使用 /login 選擇現有訂閱或供應商。以下示例只展示變數名稱，不把任何憑證寫進腳本：

export ANTHROPIC_API_KEY="在本機安全地設定"
pi

如果使用訂閱登入：

/login

接著選擇 provider 與 model。Pi 會維護可使用工具的模型目錄；需要立即刷新模型資料時，可執行：

pi update --models

3. 讓代理完成一個小任務

先不要從大型重構開始。進入一個有測試的專案，要求 Pi 完成可觀察、可回退的小任務：

cd /path/to/project
pi "找出最近變更中缺少測試的函式，先列出檔案與理由，不要修改任何檔案"

第一個任務的驗收標準應該是：它讀了哪些檔案、提出哪些風險、是否能指出下一步，而不是回答看起來是否流暢。確認只讀檢查符合預期後，再執行一個明確允許修改的任務：

pi -p "請為目前缺少測試的函式補上最小測試，執行相關測試，最後列出修改檔案與測試結果"

若要限制工具，可以只允許讀取與搜尋：

pi --tools read,grep,find,ls -p "檢查這個專案的設定與測試覆蓋缺口"

也可以用 --exclude-tools 或 --no-tools 逐步收緊能力。這種由命令列明確指定工具集合的方式，比只在 prompt 裡寫「不要修改檔案」更容易被腳本、審查與 CI 重現。

擴充模型：skills、extensions、prompt templates 與 packages

Pi 的可組裝性主要來自四種資源。

Skills 適合描述可重複的知識與工作流程，例如如何執行資料庫遷移、如何檢查某種框架的安全設定，或如何按照團隊規範產生測試。它們可以放在全域或專案目錄，並透過 /skill:name 使用。

Prompt templates 適合把高頻任務整理成具名入口，例如 /review、/release-check 或 /debug-api。這比把一大段提示複製到聊天視窗更容易版本控制。

Extensions 是 TypeScript 模組，可以註冊自訂工具、命令、鍵盤快捷鍵、事件處理器與 UI。若你要接入公司內部部署系統、建立審批對話框、攔截工具呼叫或註冊自訂 provider，extension 通常比修改 Pi 核心更合適。

Pi Packages 則是分享與部署這些資源的單位，可以從 npm 或 git 安裝：

pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3
pi install git:github.com/user/repo@v1
pi list
pi config

專案級安裝可使用 -l，把資源放進 .pi 目錄；全域資源則放在 ~/.pi/agent。這讓同一套工作流可以先在單一專案試用，再打包給團隊。

但擴充能力也帶來一個不能省略的安全邊界：官方文件指出 Pi packages 與 extensions 具有完整系統存取權，skills 也可能指示模型執行任意動作。安裝第三方套件前，應檢查原始碼、鎖定版本、限制網路與檔案權限，並把敏感憑證放在代理不需要讀取的位置。不要把「可擴充」誤解成「可信任」。

工作階段與上下文：把可重跑性放在第一線

Pi 的 sessions 以 JSONL 檔案保存，內部使用樹狀結構，每個項目都有 id 與 parentId。這使得 /tree 可以在同一個工作階段裡切換分支，而不是複製一堆互相失去關聯的聊天記錄。

常用命令包括：

/session
/resume
/tree
/fork
/clone
/compact
/export

我特別推薦把 session 管理納入工程流程。每次 agent 任務開始時，先用固定名稱建立工作階段；任務結束時輸出摘要、修改檔案、測試結果與未完成項目。若結果不理想，可以從樹狀歷史回到修改前的節點，而不是重新猜測當時的上下文。

上下文壓縮也應被視為一種工程行為，而不是單純的聊天功能。Pi 支援手動或自動 compact，但壓縮是有損的；完整歷史仍留在 JSONL，必要時可以透過 /tree 回看。對長時間執行的 agent，最好在壓縮前先寫入一份短而結構化的工作狀態，例如目前目標、已驗證事實、失敗嘗試與下一步，降低摘要遺漏關鍵決策的風險。

權限與沙箱：預設能力很強，邊界必須由你建立

Pi 預設以啟動它的使用者權限執行，沒有內建的檔案、程序、網路或憑證限制。這對本機個人開發很直接，但對 CI、共享工作站或處理敏感程式庫的代理來說，不能只依賴 prompt 約束。

官方 containerization 文件提供三種思路。第一種是 Gondolin extension：Pi 留在主機上，但把內建工具與 ! 命令路由到本機 Linux micro VM。第二種是 Plain Docker：把整個 Pi 程序放入容器，以簡單的檔案掛載共享工作目錄。第三種是 OpenShell：把整個 Pi 放進具有檔案、程序、網路、憑證與推理控制的 policy-controlled sandbox。

Docker 的最小示例可以是：

FROM node:24-bookworm-slim
RUN apt-get update \\
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \\
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
WORKDIR /workspace
ENTRYPOINT ["pi"]

執行時把程式碼目錄掛載到 /workspace，再用獨立 volume 保存代理設定與 sessions。不要直接掛載主機的 ~/.pi/agent，除非你確定要讓容器讀取主機的登入狀態與歷史工作階段。

這裡的核心原則是分離「模型認為自己應該做什麼」與「程序實際被允許做什麼」。前者由 system prompt、skills 與 extensions 處理，後者則應由容器、micro VM、檔案系統、網路政策與憑證注入機制處理。

Pi 與常見 agent 抽象的差異

Pi、子代理、skills、代理團隊與工作流程不是同一層。

Pi 是執行迴圈與工作階段的 harness。它處理模型、訊息、工具、事件與 session，但不替你決定完整產品流程。

Skill 是可載入的知識與操作規範，通常描述「如何做一種任務」。它不一定會建立新的代理程序。

子代理是另一個代理執行個體，適合把任務切成互相隔離的探索或實作工作。Pi 不把子代理列為內建功能，使用者可以透過 tmux、extension 或第三方 package 自行建立。

代理團隊是更高層的協作模型，包含角色分工、共享狀態、彙整與衝突處理。它需要比單一 agent 更多治理與觀察性。

工作流程則是把整個協調邏輯寫成可重跑的程式碼：輸入是什麼、何時啟動哪個代理、怎麼驗證輸出、失敗如何回退，都應該有明確規則。Pi 的價值在於提供一個足夠小、可以被這些上層抽象包住的執行核心。

什麼團隊適合先試 Pi

我會優先推薦以下幾種團隊試用：

已經有成熟 CLI、測試與 code review 流程，想把 agent 接進現有工程，而不是另建一個封閉平台。
需要在不同模型供應商之間切換，希望模型介面與 coding workflow 不要一起綁死。
想把 skills、prompt templates 與 extensions 放入版本控制，建立團隊共用的 agent 套件。
需要把同一個代理從互動終端逐步嵌入 CI、RPC 服務或內部工具。
願意自己處理權限、沙箱、供應鏈與觀察性，而不是期待工具替你做完所有治理。

相反地，如果你的首要需求是立即使用一個完整的多代理工作台，或團隊沒有能力審查第三方 extension 與套件，Pi 的最小核心可能會讓導入成本變高。它不是「零決策」產品，而是把決策權交給工程團隊。

我的導入建議：先限制範圍，再逐步組裝

第一階段只做唯讀任務：列出變更、搜尋漏洞模式、整理測試缺口。使用 --tools read,grep,find,ls，把輸出寫入 session 與 CI artifact。

第二階段開放寫入，但要求代理先提出計畫、只修改指定目錄，並在結束時執行固定測試。用 extension 或 wrapper 記錄工具呼叫與修改檔案。

第三階段才加入自訂 skills、packages 與模型路由。每個套件都鎖定版本，建立最小權限執行環境，並為失敗任務準備人工接管路徑。

第四階段把穩定流程搬到 RPC 或 SDK。這時才值得投資佇列、重試、成本統計、事件儲存與多租戶隔離。不要一開始就把互動 demo 直接包成無人值守的自動部署系統。

結語：最小核心，反而讓代理更像工程系統

Pi Agent Harness 的重點不是再提供一個會寫程式的聊天介面，而是示範一種更可控的 agent 工程分層：pi-ai 負責模型供應商，pi-agent-core 負責狀態與事件，coding agent 負責 CLI 與工作階段，extensions、skills 與 packages 負責工作流差異，容器或 micro VM 負責真正的安全邊界。

當這些責任被拆開，團隊才有機會針對每一層做測試、替換與審查。你可以先用終端完成一個小任務，再把相同 runtime 放到 RPC 或 SDK；可以先用唯讀工具觀察模型，再逐步開放修改權；也可以在不 fork 核心的前提下，加入自己的 provider、工具與治理邏輯。

如果你正在尋找的是一個功能最多的 AI coding 平台，Pi 未必是最短路徑。但如果你想把 agent 變成既有工程系統的一部分，而不是再增加一個孤立的聊天視窗，那麼它的最小主義值得實際跑起來研究。

參考資料