Pi Coding Agent 入門：最小核心、樹狀 Session 與 1.0 更新

Pi（@earendil-works/pi-coding-agent）採取與主流 coding agent 不同的設計方向。Claude Code 提供功能完備、開箱即用的操作環境，並內建權限審核；Pi 則以「可自行擴充的最小核心」為定位，讓使用者依需求加入功能。

專案於 2026 年 10 月 1 日正式推出 1.0.0 版本。這次發布延續「維持最小核心」（hold the line）的方向，將經過實戰驗證的 Codemode、原生 MCP 支援、五級工具曝光與全螢幕終端介面（TUI）納入核心，並同步推出實驗性的長時間運作框架 Pi Durable。

對熟悉 AGENTS.md 與 Claude Code 的開發者而言，Pi 原生支援多個模型服務提供者（provider）與本機端點，並提供樹狀對話紀錄（Session）與免編譯的 TypeScript 擴充系統，方便依開發需求調整工作方式。

最小核心與開源承諾：Pi 的來歷與設計理念

Pi 的作者是 Mario Zechner（GitHub: badlogic）——跨平台 Java 遊戲框架 libGDX 與 RoboVM 皆出自他手。專案自 2025 年 8 月起以個人形式持續迭代，並於 2026 年 4 月正式加入由 Armin Ronacher（Flask 與 Sentry 作者）共同創辦的 Earendil Works。

Zechner 在公告文章〈I’ve sold out〉中承諾，專案將永久維持開源與無門檻貢獻：

MIT, forever. Non-negotiable. No CLA, no DCO, no new hoops to jump through.

商標雖歸 Earendil 所有，但架構決策權由創辦團隊共同保留，避免重演開源專案被商業收購後走向封閉的舊路。

 +--------------------------------------------------------+
 | CLI / TUI / Print / JSON / RPC / TypeScript SDK        |
 +--------------------------------------------------------+
 | Extensions & MCP Tools    | QuickJS Codemode (WASM)    |
 +--------------------------------------------------------+
 | pi-agent-core (4 Tools: read, bash, edit, write)       |
 +--------------------------------------------------------+
 | pi-ai (Unified Provider Engine: Anthropic, Local, etc) |
 +--------------------------------------------------------+

三大核心設計哲學

官方 repo 將 Pi 定義為「可自行擴充的 coding agent」（self-extensible coding agent），並採取以下三項設計選擇：

1. 最小核心：Pi 預設僅啟用 read、bash、edit、write 四個基礎工具（另備 powershell、grep、find、ls 可選）。其餘如權限管控、工作計畫（plan mode）、子代理（sub-agents）或外部整合，全部透過一致的擴充 API 實作。
2. 模型中立：核心不綁定特定模型廠商，透過 @earendil-works/pi-ai 統一封裝 API，原生支援訂閱認證、API key、本機 GGUF 模型檔，以及各家相容端點（OpenAI / Anthropic / Google / Meta Muse）。
3. 直接使用本機權限：所有工具預設都以目前作業系統的使用者權限執行，Pi 本身不內建沙盒。若需要隔離，官方建議由使用者自行搭配微虛擬機器（如 Linux 輕量隔離環境 Gondolin）、容器（Docker）或沙盒政策引擎（如 OpenShell）。

五種執行模式與環境設定

Pi 要求 Node.js 22.19 以上環境，可透過官方腳本或 npm 全域安裝：

# macOS / Linux 一鍵安裝腳本
curl -fsSL https://pi.dev/install.sh | sh

# 或透過 npm 全域安裝（加上 --ignore-scripts，略過安裝腳本）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

安裝完成後可執行 pi --version 驗證。

五種執行模式

Pi 支援終端機互動，也能嵌入其他程式，共提供五種執行模式：

1. 互動 TUI 模式：終端機直接輸入 pi，是日常開發的預設介面。1.0 起預設改為全螢幕終端機介面。
2. Print 模式：pi --print "任務"，完成任務後輸出結果並結束執行，支援管線輸入（如 git diff | pi --print "Review this change"）。
3. JSON 模式：pi --mode json "..." > events.jsonl，輸出完整結構化事件流，方便後續分析與審計。
4. RPC 模式：透過 stdin 讀取 JSONL 指令，並由 stdout 回傳事件，讓外部程式、IDE 或自建工具鏈持續控制 Pi。
5. TypeScript SDK：將 Pi runtime 直接嵌入 Node.js/TypeScript 應用程式。

兩層式設定階層

Pi 的設定分為使用者層與專案層：

• 使用者層（~/.pi/agent/）：存放全域偏好 settings.json、登入憑證 auth.json、自訂端點 models.json、全域 mcp.json，以及 extensions/、skills/、prompts/、themes/ 四大資源目錄。
• 專案層（工作目錄下的 .pi/）：採用與使用者層相同的目錄結構，但登入憑證 auth.json 與自訂端點 models.json 僅存在於使用者層。專案層的可執行程式碼（如自訂 extensions/）需在取得「專案信任」（互動模式以 /trust 保存決定，或啟動時帶 -a 旗標）後才會載入；若要拒絕專案層設定則可帶 -na（no-approve）。純文字規範檔（如 AGENTS.md）則以唯讀方式載入，不受專案信任設定限制。

接上模型與本機端點

在互動模式下執行 /login，可選擇 provider，以訂閱登入或輸入 API key（1.0 支援 ChatGPT 訂閱登入與 Earendil Radius 服務）；使用 /model 即可切換模型。模型字串格式為 provider/model:thinking，思考等級從 off 到 max 有多種選擇，可透過 /thinking 即時調整，按下 Ctrl+S 存為啟動預設值。

若要連線至本機模型（如 Ollama 或 vLLM），可使用內建 llama.cpp router 自動尋找 GGUF 檔案，也可在 ~/.pi/agent/models.json 中設定相容端點：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

apiKey 欄位支援以 $ENV_VAR 讀取環境變數，也支援以 !command 在發送請求時執行命令，動態取得欄位值。

常用指令與 Session 樹工作流

日常操作可分為輸入前綴、任務進行中的訊息處理，以及 Session 分支管理。

常用輸入前綴與快捷鍵

在互動模式下，可使用以下三種輸入前綴：

• @file：模糊搜尋檔案，並將內容加入模型的上下文（context）。
• !cmd：執行終端機指令並將輸出送入對話。
• !!cmd：僅在本機終端機執行指令，不將輸出送入 context，避免加入不需要的對話內容。

任務執行期間，也能透過快捷鍵調整後續工作：

• Enter（調整方向，Steering）：在 agent 執行長任務時輸入訊息，訊息會在目前的 assistant 回合結束後插入，調整後續工作的方向。
• Alt+Enter（排隊 Follow-up）：將任務排入佇列，待目前所有工作完整結束後依序執行；若按下 Escape 中止，排隊訊息會退回編輯器而非遺失。
• Ctrl+O 與 Ctrl+T：隨時展開或收合工具輸出與模型的思考內容（Thinking）。

在命令列中，可透過 pi -c（--continue）快速接續上一次的對話進度。

樹狀 Session 分支管理

與傳統工具的線性對話不同，Pi 的 Session 本質上是一棵以 JSONL 儲存的樹狀結構（存於 ~/.pi/agent/sessions/），每個節點皆帶有 ID 與 parent 指標：

 (Msg A) ---> (Msg B) ---> (Msg C) [Main Branch]
                \
                 +-------> (Msg D) [Experimental Branch]

透過 /tree 指令，開發者可在同一個 session 檔案內走訪不同分支：選取過去的 user 訊息，修改後送出便會建立另一條對話分支；選取 assistant 回覆，則從該節點之後繼續。離開分支時可生成摘要，帶往接下來的路徑，原始紀錄仍留在檔案裡。

三個分流指令解決的問題各不相同：

例如查修 API 延遲時，先請 Pi 分析資料庫查詢；發現線索不足，再用 /tree 回到初始問題，改查外部 HTTP 呼叫。模型接收的是目前分支的歷史，其他分支只在你選擇帶入摘要時提供相關脈絡，避免兩條診斷路線的細節混在一起。

把指令串成一次日常工作

進入專案後啟動 pi，用 @ 引入相關檔案，再交代任務；需要自己看測試結果時，用 !! 執行指令，避免整份輸出佔用 context。想試另一種解法時用 /tree 分流，決定保留哪條路線後，再繼續修改與驗證。

工作一段時間後，使用 /compact 保留 API 設計決策與尚未排除的故障線索，精簡歷史。壓縮會加入摘要並保留近期訊息，原始 session 紀錄仍在。收工前用 /name 命名、/session 看 token 用量與成本；隔天 pi -c 接續目前目錄最近一次的 session，想找其他紀錄則用 pi -r 開啟選擇器。

需要交付紀錄時，/export 可匯出 HTML 或 JSONL，/share 則會上傳並產生檢視連結。這些紀錄可能包含工具參數、指令輸出與檔案內容，分享前應先檢查是否含憑證或內部資料。

擴充生態與工具控制

Pi 提供不同程度的客製化方式，開發者可依需求選擇足以完成工作的最簡單機制：

進階使用時，Pi 也支援自訂終端機 UI 元件（Terminal UI）、自訂模型服務提供者（Custom provider），以及可跨專案分發的套件（Pi package）。

用套件安裝與管理擴充

Pi package 可以把 extensions、skills、prompts 與 themes 一起分發。它是普通的 npm 套件或目錄，使用約定目錄名稱，或在 package.json 的 pi 欄位宣告資源位置。

以下使用官方文件的示意套件名稱，實際操作時請換成要安裝的來源：

# npm 指定版本，或 Git 指定 tag
pi install npm:@example/[email protected]
pi install git:github.com/example/pi-tools@v1

# 也能載入本機目錄，方便開發自己的擴充
pi install ./local-package

# 只在這次啟動試用，不寫入設定
pi -e npm:@example/pi-tools

預設安裝宣告寫入使用者層 settings.json；加 --local 則寫入專案的 .pi/settings.json，並受專案信任設定控制。指定版本的 npm 套件，以及指定 tag 或 commit 的 Git 來源，都會固定在該版本，更新套件時不會自動改用其他版本。

日常管理可用 pi list 查看、pi config 開關資源、pi remove <source> 移除宣告，或 pi update --extensions 同步套件安裝狀態。手動修改設定或資源後，回到互動模式執行 /reload。即使只用 -e 試用，extension 程式碼仍會執行，應先審視來源。

也不必整包照單全收。例如只想載入某套件的 extensions，可以在既有 packages 清單中使用物件形式：

{
  "source": "npm:@example/[email protected]",
  "skills": [],
  "prompts": [],
  "themes": []
}

省略 extensions 表示載入套件允許的所有擴充；空陣列表示不載入該類資源。這讓「安裝哪個套件」與「啟用哪些能力」成為兩個可分別決定的選擇。

免編譯的 TypeScript Extension 與五級工具曝光

Pi 的 Extensions 採用 jiti 即時載入，開發者可直接撰寫 TypeScript 而無需先執行 build 步驟。一個最基本的 Extension 結構如下：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Show a greeting notification",
    handler: async (name, ctx) => {
      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
    },
  });
}

Extension 註冊工具時可設定 exposure（五級曝光），決定工具提供給模型或腳本的方式，並控制工具定義佔用的 context：

• direct：始終直接宣告給模型。
• model-only：對模型可見，但對沙盒環境隱藏。
• codemode：僅供 Codemode 腳本呼叫，不在模型 prompt 中列出工具定義。
• deferred：延遲載入，只有 Tool Search 找到該工具時，才將定義載入 context。
• hidden：僅供內部程式或擴充流程呼叫。

Codemode、工具搜尋與 MCP 如何配合

過去 Pi 曾主張不需要 MCP，但官方在〈“You Said No MCP!”〉中說明了轉向理由：工具需要可搜尋的描述與結構化結果，才能由程式有效組合；同時，核心必須知道工具要直接提供給模型、延遲載入，還是只在 Codemode 中使用。第三方 MCP 外掛取得的工具描述與設定資料（metadata）不足以完整支援這些安排。

三者的分工可以用「彙整最近一週的已合併 PR」來理解。這是使用情境示例，實際工具名稱與參數取決於連線的 MCP server：

1. 搜尋工具：模型用 tool_search 找出未直接宣告的查詢工具；Codemode 腳本也可用 searchTools() 與 describeTool() 取得工具描述與參數定義。
2. 編排呼叫：先取得 PR 清單，再對獨立的 PR 查詢平行抓取細節；有相依性的呼叫仍須依序執行。
3. 整理結果：JavaScript 篩掉不需要的欄位、彙整作者與改動類型，最後只把摘要交回模型撰寫週報。

MCP 提供外部工具介面，工具搜尋負責找到所需能力，Codemode 則負責呼叫順序與結果處理。五級曝光因此有了實際用途：大量低頻工具可以延遲提供，供腳本處理資料的工具也能避免逐一佔用模型的工具清單。

依 Codemode 文件，腳本在 QuickJS 沙盒執行，沒有 Node API、直接檔案存取或網路能力，對外操作須經工具完成。這個沙盒限制的是腳本本身，被呼叫工具的權限仍取決於它的執行環境；呼叫 bash 寫檔，也不會因腳本失敗而自動撤銷。

若尚未使用 MCP，可在 settings.json 啟用批次編排：

{
  "defaultTools": ["+codemode"]
}

MCP 連線則由 pi mcp add 設定，pi mcp list 檢查；互動模式的 /mcp 可查看連線、登入與工具曝光設定。從 session 外修改伺服器設定後，執行 /reload 重新載入。MCP 工具預設透過 Codemode 提供；若只使用本機的四個基礎工具，可依需求自行啟用 Codemode。

1.0 的意義：成熟核心與實驗框架

正式版收錄了哪些能力

0.99.0 release notes 已列出內建 Codemode、Tool Search、MCP 與 Virtual models。1.0 延續這條路線，將 TUI 改為預設全螢幕，並強化既有功能的穩定性；讀公告時應區分「正式版收錄哪些能力」與「發布當天才新增哪些能力」。

例如 1.0.0 的官方測量，是在預設工具加 Codemode 的條件下，將一次 GPT-5.6 請求的 prompt 從約 5,300 tokens 降至 3,300。約 40% 的縮減來自工具描述瘦身與文件按需載入，這個數字不代表所有工作任務的總成本都能降低四成。

另一項值得關注的能力是 Virtual models：使用者選擇一個虛擬模型後，extension 會依任務、成本或對話狀態，為每次請求選擇實際使用的模型與思考等級（thinking level）。

官方發布示範以 Claude 規劃、GPT 實作，交由 Jev 判斷切換時機；/session 可分別檢視各模型的成本。這是可自行設計的路由機制，安裝 Pi 並不會自動得到這套分工。

官方對 1.0 的承諾是：經過使用者回饋與改進，成為個人與企業可以信賴的軟體。不過，本次核對公告與 v1.0.0 README，未找到明確的 API 棄用期限或相容性政策。撰寫 extension 的團隊仍應固定版本、檢查 release notes 並驗證升級；版本號本身不足以取代這些工作。

Pi Durable 解決另一種運作需求

Pi Durable 是同日推出的框架。當 agent 需要從不同介面接收多人訊息、長時間執行，或在行程意外終止後恢復任務時，就需要超出單人終端機工作流程的設計。

Durable 將模型呼叫與工具執行視為任務（task），逐步保存執行進度（checkpoint）；行程重啟後，再從已保存的進度恢復。

內建儲存後端為 memory、SQLite 與 JSONL，後兩者的程式碼不依賴 Node API，可經轉接在 Bun 或 Cloudflare Durable Object 中使用。工具執行環境也能與負責協調 agent 運作的框架（harness）分開，讓對話管理與實際執行位於不同機器。

與既有工作流銜接：Claude Code 對照、升級與選型

原生支援 AGENTS.md

Pi 原生以 AGENTS.md 為主要指示檔，也會讀取 CLAUDE.md。以唯讀方式讀取 AGENTS.md 不需要專案信任，工作目錄及其父目錄的規則會自動逐層繼承。此外，Pi 亦支援專屬的 SYSTEM.md（整份替換系統提示）與 APPEND_SYSTEM.md（追加提示），方便進一步調整提示詞。

Pi 與 Claude Code 核心面向對照

既有使用者升級至 1.0 的注意事項

升級至 1.0.0 時，開發者需留意以下三大面向的調整：

1. 互動介面預設全螢幕：TUI 預設改為 fullscreen 模式。若偏好保留終端機原生的捲動紀錄（scrollback），請於設定中加入 tuiMode: "regular"。
2. CLI 參數嚴格檢查：--provider 不帶 --model 不再默默忽略，而是會直接回報錯誤退出，需同步檢查自訂腳本與 CI 設定。
3. 語法與 API 遷移：
   • Codemode 腳本中探測工具由 typeof tools.name 改為 "name" in tools。
   • MCP OAuth 憑證改按 server 名稱與 URL 分開儲存。
   • Extension API 中 shouldStopAfterTurn 已移除，改用 finishTurn 回傳 { action: "end" }。

給開發者的五步上手與選型判準

1. 第一天基礎操作：完成 /login 接上慣用模型，記住 @ 引用檔案、! 執行指令、pi -c 接續上次對話與 Escape 中止，先完成一項熟悉的開發任務。
2. 掌握 Session 樹：使用 /tree，針對同一個重構問題建立分支，嘗試並比較不同解法。
3. 按需設定擴充與 Codemode：先使用 pi list 檢視現有資源；需要批次編排工具呼叫時，再於 settings.json 中啟用 "+codemode"。
4. 設定安全隔離：在處理不可信任或外來程式庫時，依官方安全指引限制可存取的檔案、憑證與網路，必要時讓整個 Pi 在容器或 VM 內執行。-na 可拒絕專案層資源載入，但不限制工具的 OS 權限，不能替代隔離。
5. 選型與共存決策：若需要使用非 Anthropic 模型、透過樹狀 Session 比較除錯路線，或建置基於 RPC/SDK 的自動化工具鏈，可考慮 Pi，但要預留時間自行組合並維護模型、擴充與隔離設定；若需要預設沙盒防護與開箱即用的權限審核，可考慮 Claude Code。兩者也能在規範完備的 AGENTS.md repo 中搭配使用。