Pi Agent 完整教學：安裝設定、擴充套件與 Session Tree 實戰

by Rain Chu | 9 月 27, 2026 | Agent, AI, 程式開發

Pi Agent 非常適合想自己決定 AI 寫程式流程的人，它把讀檔、寫檔、修改與執行命令放在小巧的核心裡，再透過擴充與模型設定增加能力，真正有用的地方，是你可以在同一段工作裡切換模型，回到先前的對話節點，重新探索另一種方案。

但輕量不代表不用設定，也不保證每次都比較省錢，要先分清楚擴充程式、專案規則、對話紀錄與檔案版本各自負責什麼，後續才不會把對話切回去了，卻以為程式碼也自動還原。

Pi Agent 是什麼？先理解它負責哪一層

Pi Agent是一套以終端機為主的 AI Coding Agent，也常被稱為 Agent Harness。

你可以把 Harness 理解成模型的工作環境，負責把請求、上下文、工具呼叫與執行結果串起來。模型決定下一步，Pi 則讓它能接觸專案檔案與工具。

預設核心工具是 read、write、edit 與 bash。計畫模式、子代理與 MCP 整合不是核心預設配備，可以再用擴充或套件補上。因此，適合的起手式是先用基本能力完成小任務，再增加確實需要的功能。

Pi 也提供不同的接入方式，日常操作用互動終端介面，單次自動化可用 print 或 JSON 輸出，需要其他程式控制時可走 RPC，想嵌入自己的應用則使用 SDK。

RPC 文件與SDK 文件適合留到需要整合時再看。

安裝 Pi Agent：使用目前官方套件名稱

截至 2026 年 9 月 12 日，官方快速入門採用的 npm 套件名稱是 @earendil-works/pi-coding-agent。較舊教學可能使用不同命名，請以官網當下的指令為準。

目前套件設定要求 Node.js 22.19.0 以上，安裝前先確認環境。

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

--ignore-scripts 會停用安裝期間的套件生命週期腳本，官方說明一般 npm 安裝不需要這些腳本。看到版本資訊後，切換到要處理的專案目錄，再啟動 Pi。

cd /path/to/your-project
pi

上面的專案路徑要換成自己的資料夾，第一次練習可使用測試專案，先請它整理目錄、說明啟動方式與現有檢查項目，確認理解正確後再開始改程式。這樣也比較容易看出模型是否能正確使用工具。

模型接入：登入、API Key 與自訂端點分開處理

進入 Pi 後，先用 /login 設定模型服務，再用 /model 選擇模型，服務商文件列有訂閱登入與 API Key 兩種主要方式，可用選項取決於服務商、帳號與目前版本。

常用設定位於 ~/.pi/agent/。auth.json 保存驗證資料，models.json 用來加入自訂模型或端點，settings.json 管理偏好，sessions/ 保存對話。

專案自己的偏好放在 .pi/settings.json，有助於把個人習慣和團隊設定分開。

如果模型服務使用支援的相容 API，可依自訂模型文件填入端點、API 類型與模型 ID。

以下是設定結構範例，網址與模型名稱都是待替換值，不是可直接連線的服務。

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://your-provider.example/v1",
      "api": "openai-completions",
      "apiKey": "$MY_PROVIDER_API_KEY",
      "models": [
        {
          "id": "your-model-id"
        }
      ]
    }
  }
}

將真正的金鑰放進 MY_PROVIDER_API_KEY 環境變數，設定檔保留變數參照即可。修改 models.json 後重新開啟 /model，Pi 會重新讀取。模型沒出現時，依序檢查 JSON 格式、驗證資料、模型 ID 與 API 類型。端點能聊天，也不一定代表工具呼叫完全相容。

Extension、Skill 與 Package 差在哪裡？

Extension 是會執行的擴充程式，通常以 TypeScript 撰寫，可以註冊工具、加入斜線命令、監聽事件、調整終端介面，或改變工具執行方式，例如，替特定命令增加確認流程，就是執行時的能力。

擴充文件提供 API 與範例。

Skill 是可重複使用的工作方法。它把說明與相關資源整理成一個任務單元，適合審稿、部署檢查或特定程式庫的使用流程，Pi 先讓模型知道有哪些技能，需要時再讀取完整內容。，看如何把方法寫成可重用流程，可以延伸閱讀站內的diagram-design 技能教學，再對照Pi 的技能載入規則調整。

Package 是安裝與分享的容器。它可以同時包含 Extension、Skill、提示詞範本與主題，也可以只有其中一種。

Pi Package 文件規定資源可在 package.json 的 pi 欄位宣告，或使用約定目錄。

Extension 和 Package 因此不是二選一的替代品。

安裝前先看套件作者、原始碼與支援版本，pi install 預設寫入個人設定，加上 -l 則用於專案範圍。可以用 pi list 檢查已安裝套件，資源修改後用 /reload 重新載入。

AGENTS.md 怎麼分層？override 只取代同層檔案

Pi 會在啟動時載入全域、父目錄與目前目錄的上下文檔案。全域的 ~/.pi/agent/AGENTS.md 可放常用語言與共通習慣，專案的 AGENTS.md 則放技術選擇、執行方式與驗收條件。

啟動畫面會列出已載入的檔案，可先核對是否符合預期。

依官方使用說明，同一個目錄若有 AGENTS.override.md，Pi 會改讀它，取代該目錄的 AGENTS.md 或 CLAUDE.md。

其他目錄的上下文仍會一起載入。這不能簡化成「有 override 就清空全部規則」，也不宜只靠一句優先級口訣管理互相矛盾的要求。

以賽車遊戲為例，專案規則可以寫得很具體，先限制第一版的範圍，再定義怎樣算完成。

# 專案工作規則

- 使用現有專案的技術，不另換框架
- 第一版先完成操作、碰撞、計時與重新開始
- 相機視角需先確認，再實作渲染方式
- 修改後執行專案既有檢查
- 回報改動、驗證結果與尚未解決的問題

這些是給模型讀取的指示，不是作業系統的權限限制。

若還有跨專案的知識要保存，可參考讓不同 Agent 共用專案知識的方式，避免把所有背景資料塞進每次啟動都載入的檔案。

專案信任不等於沙箱，pi-sandbox 也有適用範圍

Pi 的專案信任機制，決定是否載入專案內的設定、技能、套件與擴充，單純建立空的 .pi 目錄，不一定會出現信任提示，拒絕信任後，受保護的專案資源會略過，但 AGENTS.md 等上下文仍可能載入。

官方安全文件明確說明，這套機制不是沙箱。

Pi 本身會以啟動帳號的權限讀寫檔案與執行命令。若需要執行隔離，應依工作情境選擇容器、虛擬機或作業系統層的沙箱，只在提示詞裡要求「不要碰其他檔案」，不能取代這些限制。

carderne 的 pi-sandbox是一個可選的第三方擴充，為檔案工具加入規則，並透過 sandbox runtime 控制 Bash 的檔案與網路存取。它會在部分被擋下的操作上顯示授權提示。確認作者與套件名稱後，可依其文件安裝。

pi install npm:pi-sandbox

這個套件的 macOS 與 Linux 說明要求環境能找到 rg，設定位置包含全域的 ~/.pi/agent/sandbox.json 與專案的 .pi/sandbox.json。不同同名專案的格式不一定相同，不要混用範例。

Session Tree：保留探索路徑，也要另外保存程式碼

Pi 將對話存成樹狀 JSONL，預設放在 ~/.pi/agent/sessions/，並按工作目錄整理。每筆紀錄透過 ID 與父節點連接，因此可以在同一段對話裡保留不同嘗試。Session 文件對分支與選取行為有完整說明。

pi -c
pi -r
pi --name "racing-game-prototype"

上面三行是不同的啟動方式，依需要擇一。

pi -c 延續最近的對話，pi -r 選擇歷史紀錄，--name 則為啟動的對話設定名稱。進入 Pi 後，也可以用 /session 查看目前紀錄。

/tree 在同一份對話檔案內切換路徑，選取先前的使用者訊息時，原文字會回到編輯區，修改後送出就能展開另一條分支。若想從先前某個問題建立獨立對話，用 /fork，若要複製目前整條使用中的分支，則可用 /clone。

對話樹保存的是討論歷史，不能視為程式碼快照，切回舊節點時，磁碟上的檔案仍可能保留後續修改，要比較兩種實作，應另外使用 Git commit、分支、worktree 或獨立副本保存成果，再確認目前工作目錄和所選對話相符。

切換分支時，Pi 可以摘要離開的路徑，將重要資訊帶到新位置，若是同一需求的改良版，可保留問題與結論。若要獨立比較方案，則要留意摘要是否把原方案的假設帶了過去，長對話也可用 /compact 整理上下文，但摘要會取捨資訊，關鍵規格仍適合寫回專案文件。

用賽車原型練習：先計畫、再審查、最後驗收

一個好練習，是讓 Pi 先規劃俯視賽車原型，再嘗試固定追尾視角。重點不是一次做出完整遊戲，而是讓需求變動時，仍能追溯決策與保留可用版本。

第一步：先把驗收條件講清楚

先要求它列出操作方式、相機位置、碰撞、計時與重新開始等最小功能，暫時不要實作。把「做一個好玩的遊戲」改成可以檢查的條件，例如按鍵方向一致、失敗後能重新開始、相機不因轉彎而失去方向感。

第二步：切換模型審查計畫

用 /model 切到另一個模型，請它檢查計畫中缺少的條件、技術風險與需要確認的選項。這是同一段對話中的模型交接，不是同時啟動多個代理。分工可以是較快的模型整理方案、另一個模型審查關鍵設計，但是否更划算，需要用自己的任務驗證。

第三步：跑起來，檢查可操作性

程式生成後，要實際啟動並檢查操作、碰撞與視角。能開啟頁面，只代表基本流程可執行，不代表遊戲已完成。若俯視版本相機不穩，先保存檔案版本，再用 /tree 回到需求確認點，提出固定追尾視角的新方案。

執行途中想補充方向，可以送出 steering 訊息。想等目前工作完成後再追加任務，則使用 follow-up。預設快捷鍵分別是 Enter 與 Alt+Enter，實際可用 /hotkeys 確認。排隊訊息不是撤銷已執行操作的功能，緊急停止與後續修正仍要分開處理。

Pi 和 Hermes 怎麼選？先看你想完成哪種工作

Pi 適合想掌握本地開發流程、逐步組裝能力，或把 Agent 嵌入自己應用的使用者，Hermes Agent則提供記憶、技能累積、通訊平台接入與排程等較完整的個人助理能力。這是產品方向的差異，不足以直接推論哪一個寫程式一定比較強。

如果需求是從通訊軟體交辦長期工作，可以先看看站內的Hermes 與通訊平台整合，如果主要工作是對著專案反覆改程式，Pi 的對話樹與可擴充介面值得試用，偏好圖形工作台的人，也可比較OpenWork 本地 Agent 工作台的操作方式。

成本方面，不能只比較初始系統提示詞的長度，完整帳單還受模型價格、工具輸出、重試次數、快取與最後是否完成任務影響，Pi 顯示的用量和費用適合追蹤趨勢，自訂模型的價格設定也要正確，結算仍以服務商帳單為準。

常見問題

Pi Agent 是模型嗎？

不是。Pi 是讓模型讀寫檔案、呼叫工具與管理對話的工作環境，需要另外接入可用的模型服務。

Pi Agent 的 Extension 和 Package 有什麼不同？

Extension 是執行時的擴充程式，Package 是安裝與分享資源的容器，可以包含擴充、技能、提示詞與主題。

AGENTS.override.md 會取代所有規則嗎？

不會。它取代同一目錄的 AGENTS.md 或 CLAUDE.md，其他目錄的上下文仍會載入。

Pi 的 /tree 會還原專案檔案嗎？

不能把 /tree 當成檔案還原工具。它切換對話路徑，程式碼版本需要另外用 Git 或其他快照方式保存。

第一次使用，先完成一個能驗收的小任務

先接通一個模型，寫一份精簡的專案規則，請 Pi 完成小修改並說明驗證結果。熟悉之後，再加入真正需要的擴充，練習模型交接與對話分支。當每次嘗試都有清楚的需求、可追溯的討論與獨立保存的檔案版本，這套輕量工具才會成為可靠的開發流程。