AIDive你的agent是個黑盒子
Claude Code、Codex和Gemini CLI都是別人設計的agent harness——如果你的工作日都待在其中一個裡面,你就得接受那個設計決定。想改變某個行為、加個工具、收緊權限規則?你只能等廠商想發布再說。你不知道system prompt裡寫了什麼,看不到執行工具的迴圈,什麼都改不了,即使這些工具早已成為數千名開發者的主要工作台。
有一個開源專案走了完全相反的路:pi,一個提供零件讓你組裝專屬agent的toolkit,從模型連接器一路到介面都包含在內。它在第一年就拿下9萬2千顆GitHub星星,幾乎每週都發布新版本。這篇文章要談pi到底放了什麼在盒子裡、如何用它的SDK打造自己的agent,以及對現成harness的誠實評價。
harness到底是什麼
harness是圍繞著語言模型的所有機制,讓它變成一個能運作的agent。模型單獨只能做一件事:讀文字、產生文字。它不會讀你的檔案,不會執行任何指令,而且從一個session到下一個什麼都不記得。剩下的一切都是harness——框住模型的system prompt、開放給它的工具、執行工具呼叫並把結果回傳的迴圈,還有你終端機裡的介面。
harness還決定了日常差異的那些細節:context滿了以後歷史怎麼壓縮、工具錯誤怎麼回報給模型、什麼會被記錄下來、什麼不會。Claude Code是個harness。Codex也是。當一個agent讓你驚艷時,大部分功勞屬於那套機制,不是模型本身——把同一個模型裝進兩個不同的harness,你會得到兩個完全不同等級的agent。
Earendil Works打造的pi,把那套機制切成可重複使用的積木。你可以直接用它的coding agent,也可以一塊塊拿積木自己組裝。我們在意的正是第二種選擇。
深入pi toolkit
pi是一個monorepo——一個repo裡裝了五個各自發布的套件——每個套件負責harness的一層:
| 套件 | 功能 |
|---|---|
| pi-ai | 通往OpenAI、Anthropic、Google等模型的統一API:回應串流、帶思考等級的推理區塊、甚至動態偵測每家供應商提供的模型。只改一個參數就能切換實驗室。 |
| pi-agent-core | agent迴圈本身:對話狀態,加上發送訊息、讀取工具呼叫、執行它們、直到任務完成前持續回傳結果的循環。失敗的工具、中途被截斷的回應、同時湧入的呼叫這類棘手情況早就處理好了。 |
| pi-tui | 用差分渲染的終端機渲染函式庫,只重新繪製畫面上有變化的地方。 |
| pi-coding-agent | 用上述積木組出的完整coding agent——證明這套工具包足以做出成品。 |
| pi-telemetry | 讓你接上自己的使用指標,不必依賴某個廠商。 |
agent迴圈正是你從零開始寫很容易寫爛的那部分;把它寫好要花好幾週,而你透過一個import就拿到了。團隊還把同一套配方用在別處:另一個repo pi-chat,把同樣的積木重複用在對話自動化上。
數字證明這套公式行得通:
| 指標 | 數值 |
|---|---|
| GitHub星星 | 92,123 |
| Fork數 | 11,400 |
| Commit數 | 5,700以上 |
| 授權 | MIT |
| 2026年8月頭兩週的發布次數 | 3次(v0.84.2於8月14日推出) |
MIT授權代表你可以無限制地使用、修改、再散布pi,就算放進商業產品也行。pi不只是又一個框架:它是拆成零件的完整harness,而且維護節奏很穩定。
CLI實戰
pi的CLI是你在動任何程式碼之前就拿到的、已經組裝好的coding agent,這也是你會開始的地方。安裝只要一行,而--ignore-scripts旗標不是小事:它阻止你的依賴套件執行自己的安裝腳本,那是npm上最常被濫用的攻擊面之一。啟動pi,用login指令連接你的供應商,你的終端機裡就有了一個coding agent。狀態列會顯示目前的資料夾、session、已用的token,還有即時費用——每個請求發出的當下你就能看到定價,而不是月底才發現帳單有多少。
斜線指令涵蓋日常操作:model用來切換模型,compact在context膨脹時摘要歷史紀錄,export把對話拉出來,settings負責其餘部分。prompts資料夾裡的一個markdown檔,會變成一個只要打名字就能觸發的指令。
pi真正的招牌在於session處理。每段對話都以JSONL存在你的家目錄裡,按專案分類——而歷史紀錄其實是一棵樹,不是一條線。你可以回到對話的任何一個節點,再用fork指令走另一條路,然後用tree在分支間移動。失敗的提示詞現在不再有任何損失:回到前一個節點重試,不會失去原本那條分支。因為一切都存在本機,resume能讓你回到任何過去的session,就算幾週後也一樣。Claude Code和Codex都沒有這種形式的歷史導覽。
預設情況下,模型只拿到四個工具:read、write、edit和bash。比起市面上的agent少了非常多,而這是故意的(後面會再談)。設定也遵循同樣的邏輯:家目錄裡有一個全域設定檔,每個專案有一個會覆蓋它的檔案,還有一套trust系統,在套用第一次打開的資料夾的本機設定前會先詢問。如果你要遷移,pi會自動把你現有的AGENTS.md或CLAUDE.md載入為context,所以既有的指示不必重寫就能直接運作。
我們打造自己的agent
用pi的SDK打造agent,從一個import開始:createAgentSession,給它一個模型runtime和session manager,就會回傳一個可運作的agent。session manager是持久化的選擇——一次性腳本用記憶體,或存到硬碟讓你下次執行還能找回對話。
我們在一個本機專案上試了。我們的腳本問目前資料夾裡有什麼;agent呼叫它的read工具,讀資料夾並回答。這就是完整迴圈,由我們寫出來,大約十行TypeScript。SDK建立的session也擁有和CLI一樣的樹狀結構——每則訊息都連結著它的上一則——所以歷史分支在你自己的程式碼裡也能運作。
custom tools是開始變得有意思的地方。defineTool接受一個名字、一段描述、一個有型別的參數schema和一個execute函式,你的工具在模型眼中就會和read或bash一模一樣。我們寫了一個查詢頻道影片清單的工具,傳進customTools,agent從第一個相關問題開始就自己呼叫它。這基本上和MCP伺服器是同一套機制,只是一切都活在你的檔案裡——不需要獨立的行程,中間也沒有協定。因為參數schema是型別化的,你的編輯器會自動補完參數,agent收到的輸入也早就經過驗證。
你還能控制模型、從完全關閉到最大的思考等級、模型看得到的工具的精確清單,如果想從一張白紙開始,甚至能透過resource loader控制整個system prompt。至於顯示,session.subscribe會把每個事件——串流文字、工具呼叫、錯誤——交給你,你可以把它導向任何地方:終端機、訊息機器人,或是在你的pull request上留言的CI管線。一個下午你就從使用agent變成寫出一個agent,終於知道迴圈的每一輪到底發生了什麼。
不用fork就能擴充
pi的CLI可以透過四種機制客製化,全都放在你專案或家目錄裡的普通資料夾:
- Extensions——註冊工具、斜線指令、快捷鍵或UI元素的TypeScript模組。把檔案丟進extensions資料夾,啟動時就會載入。比如你會在這裡寫一個權限守門員:攔截bash指令的擴充功能,在危險指令執行前要求確認。
- Skills——遵循Agent Skills標準的能力套件,和Anthropic推廣的是同一套標準,所以你現有的skills原封不動就能重複使用。
- Prompts——把可重複使用的提示詞做成純markdown檔。
- Themes——CLI執行中就能熱重載。
而這一切都像任何套件一樣安裝:pi install能接受一個npm套件或git repo,一個指令更新全部。文件把這個理念濃縮成一句話:讓pi配合你的工作流程,而不是反過來,不需要fork或修改內部。
這正好和大型harness相反。Claude Code把sub-agent、plan mode和權限都內建在產品裡,pi則刻意把它們留在外面,讓你當成extension自己做,或從社群安裝。這個賭注很清楚:一個幾乎不變的最小核心,以及所有客製化都留在你那一側,放在你跟著專案一起做版本控制的檔案裡。
真正的限制
pi的透明是用工作量換來的,這個代價分成三部分。
先說guardrail:預設情況下完全沒有內建的權限提示,所以agent可以什麼都不問就執行一個bash指令。官方文件承認這一點,並提出包含Docker在內的三種隔離模式——但在把agent放到一台重要機器上之前把這些準備好,是你自己的責任。
接著是成熟度:這是v0.84,不是1.0,有大約一百個未關閉的issue,還有一些API仍標示為實驗性,像是最近幾週才加入的remote session client。今天能用的東西,下一次發布可能就壞了;這是一個推進如此快速的專案該付出的正常代價。
最後,時間。Claude Code一開箱就給你的每一種便利——plan mode、sub-agent或細緻的權限——在這裡都成了你得自己動手做的專案,或是你得追著跑、祈禱它還會被維護的社群套件。擴充功能生態系才滿一年:你會發現要填的坑比現成套件多得多。就連安裝過程本身都在教你需要多高的警戒心,透過它的--ignore-scripts旗標,而你得在整條鏈路上都維持這個水準。如果你今晚的目標是出貨程式碼,pi會先讓你變慢,之後才會讓你變快——別只憑這支影片就在這週換掉你的主要harness。
pi到底適合誰
pi適合那些用多個agent組成產品、而不只用一個agent的開發者。對他們來說,這大概是目前最好的學習投資:裝上CLI,用SDK寫一個二十行的agent,再給它一個你自己的工具。做到這一步,你對Claude Code的理解會超過大多數使用者。
如果你今天只想要一個生產力助手,繼續用你整合好的harness,等1.0補上guardrail再回來:pi的價值在於理解和控制,不在於立即的舒適。而在這兩者之間還有一條零風險的中間路線——工作上繼續用Claude Code,再把pi當成試驗台,搞懂你主要工具到底藏了什麼。
我們最大的收穫是,harness不再是黑盒子了:零件都攤在桌上,有文件,還是MIT授權。下次某個agent讓你驚艷或惱火的時候,你會清楚知道該看哪個零件。
