如果你想在終端機裡使用 AI coding agent，Pi Coding Agent 很容易讓人先盯著「它能不能寫程式」這個問題。但從官方文件來看，Pi 的重點不只是產生程式碼，而是把模型、終端工具、專案脈絡、session 和可選的擴充組在一起。它會在你目前所在的專案目錄工作，也能讀檔、寫檔、修改檔案和執行 shell command，所以第一個要確認的問題其實是：你準備讓它看見什麼，又允許它動手到哪裡？
先講本文的判斷：如果你需要終端機優先的工作方式，想自行切換 provider 和 model，還希望用 AGENTS.md、Extensions、Skills 或 session tree 把工作整理起來，Pi 值得研究。如果你只是想在瀏覽器裡問問題、整理檔案或做研究，ChatGPT、Claude 或 NotebookLM 這類工作區可能更直接。這不是性能排名，而是工作介面的差異。
本文依 Pi 官方文件首頁 以及 2026-09-17 讀到的 Quickstart、Using Pi、Providers、Security、Sessions、Extensions、Skills 和 Packages 文件整理。本文沒有登入 Pi、呼叫任何 provider、安裝第三方 package 或在真實專案執行修改，因此操作命令是官方文件內容，導入順序和驗收清單則是本文建議。你的模型清單、帳號方案、額度、作業系統和實際 UI 仍要自己讀回確認。
文章目錄
Pi Coding Agent 教學先講結論：它是終端工作環境，不是單獨的模型
Pi 官方文件把 Pi 定義成 minimal terminal coding harness。這個說法可以先翻成白話：Pi 是包住模型和工具的終端工作環境，核心刻意維持小，再用 TypeScript Extensions、Skills、Prompt Templates、Themes 和 Pi Packages 擴充。它不是另一個大型語言模型，也不是安裝完就自動擁有固定能力的聊天網站。模型要從 provider 登入或 API key 取得，工具和專案資源則受你的設定與權限影響。
這個定位很重要，因為「模型會不會寫 code」只回答了其中一段。真正跑一個修改專案的任務，至少還會遇到目前工作目錄、哪些檔案已載入、模型能呼叫哪些工具、命令輸出是否進入脈絡、session 是否保存、擴充程式能不能執行，以及最後誰檢查 diff 和測試結果。工具能力一開，責任也跟著一起進來，這筆帳通常不會因為介面很簡單就消失。
你可以先用下面的表格把 Pi 拆開看。左欄是官方文件直接說明的組成，右欄是本文對導入順序的建議，兩者不要混成同一種證據。
| 元件 | 官方文件目前說明 | 本文建議先確認什麼 |
|---|---|---|
| Model／Provider | Pi 可透過 subscription OAuth 或 API key provider 連接模型 | 你的帳號、金鑰、provider 和可見 model 是否真的可用 |
| Agent runtime | Pi 在目前專案目錄接收訊息、組合脈絡並安排工具呼叫 | 目前工作目錄、任務範圍和停損條件 |
| 內建工具 | 預設工具包含 read、write、edit、bash；另有 read-only 工具選項 | 先只讀，確認後才允許寫入或執行命令 |
| Context files | 可以載入 AGENTS.md、CLAUDE.md 與 project resources | 規則是否可讀、是否含秘密、是否和專案實際流程一致 |
| Sessions | 對話會自動保存，可 resume、branch、fork、clone | session 檔案是否要保護，分支任務如何命名 |
| Extensions／Skills | 可加入工具、命令、事件、UI 或可重用能力 | 第三方來源是否可信，是否真的需要增加權限 |
| Trust／Isolation | project trust 控制是否載入專案資源；Pi 預設以使用者權限執行 | trust 不等於 sandbox，必要時另設容器或隔離環境 |
如果你想先理解這層「模型之外還有什麼」，可以先讀網站上的 AI Agent Harness 介紹。Pi 是一個具體產品，Harness 是用來整理執行層責任的上位概念，兩篇文章的問題不一樣。
Pi 的工作構造：模型、工具、脈絡與 Session 各自做什麼
模型和 Provider 負責生成，不負責替你保管工作規則
Pi 把 provider 和 model 拆成可以選擇的設定。你可以用 /model 在互動 session 中切換模型，也能用 /thinking 選擇 thinking level；CLI 也提供 --provider、--model 和 --thinking 等選項。這代表 Pi 的產品價值不只在某一個模型，而在同一個終端工作方式可以接不同的模型來源。
但這裡有一個容易被忽略的邊界：provider 能不能登入、model 是否出現在目錄、帳號方案是否允許、API key 是否有額度，不能只從文件首頁推定。官方 Providers 文件 列出 subscription 與 API key 的設定方式，但它不會替你讀回你現在這台機器的帳號狀態。文章裡不把「文件列出」改寫成「你一定可以用」。
內建工具讓 Pi 可以真的碰檔案與終端機
Pi Quickstart 目前列出的預設工具是 read、write、edit 和 bash。官方文件也說明，Pi 在你啟動的目前工作目錄裡執行，並且可以修改那裡的檔案；grep、find、ls 等額外 read-only 工具則可透過工具選項提供。這和只在網頁輸入文字的聊天流程差很多，因為輸出不只是一段回答，也可能是一個檔案變更或 shell command 結果。
我會把工具分成兩層來看。read 適合做第一輪盤點，先確認目錄和現有規則。write、edit 和 bash 會讓任務跨進修改或執行範圍，應該等你確認過工作目錄、目標檔案和驗收命令再開。這是本文的風險分層建議，不是 Pi 官方宣稱的安全等級。
在互動模式中，官方提供 !command 把 shell command 和輸出送進模型，也提供 !!command 執行命令但不把輸出加入模型脈絡。後者不代表命令變安全，只是減少一段輸出進入 context。若命令本身會修改檔案、刪除資料或碰到秘密，仍要依照同一套人工確認規則處理。
Context 和 Session 決定任務能不能接得起來
Pi 會在啟動時讀取工作規則。官方 Quickstart 與 Using Pi 文件指出，Pi 可以載入全域 ~/.pi/agent/AGENTS.md，也能從目前目錄往上讀取 AGENTS.md 或 CLAUDE.md；同一層有 AGENTS.override.md 時，會取代該目錄的 AGENTS.md 或 CLAUDE.md。改完 context file 後，可以重啟 Pi 或執行 /reload。
這讓 AGENTS.md 很適合放專案慣例，例如先跑哪個檢查、哪些資料夾不要碰、輸出中如何表示 unknown。它不是秘密管理器，也不是權限系統。我會避免把 API key、Cookie、客戶資料或只有某次任務才適用的暫時命令寫進共用規則，這是根據資料暴露風險做的本文建議。
Session 則保存工作歷史。官方 Sessions 文件 說明，session 會自動存到 ~/.pi/agent/sessions/，依工作目錄整理成 JSONL tree。你可以用 pi -c 接續最近一次工作、pi -r 選舊 session，也能在互動模式用 /tree、/fork 和 /clone 走不同分支。這讓任務可以回到某個節點重做，但不代表每一個舊結論都正確，分支仍然要檢查實際檔案。
安裝 Pi Coding Agent 與第一次啟動
目前官方 Quickstart 的安裝方式
截至 2026-09-17，Pi 官方 Quickstart 提供 npm 安裝命令 npm install -g --ignore-scripts @earendil-works/pi-coding-agent。文件解釋 --ignore-scripts 會停用 dependency lifecycle scripts，而 Pi 的一般 npm 安裝不需要 install scripts。macOS 和 Linux 也有 curl -fsSL https://pi.dev/install.sh | sh 的安裝方式。
這裡要留意兩件事。第一，文章不把版本號寫死，因為官方文件標示的是 Latest，安裝時應以當天文件與套件實際輸出為準。第二，我在本次產文流程沒有執行安裝，因此這段是官方命令轉述，不是本機安裝成功證據。若你在 Windows、Termux 或遠端主機操作，請改讀官方對應的平台文件，不要把 macOS／Linux 的命令直接當成所有環境都適用。
如果要解除安裝，官方 Quickstart 要求使用當初的套件管理器，例如 npm 安裝就執行 npm uninstall -g @earendil-works/pi-coding-agent。文件也提醒，解除 Pi 本身不會自動刪除 ~/.pi/agent/ 裡的設定、credentials、sessions 和已安裝 packages。這也是為什麼解除安裝不等於清除資料，若你要交接機器，還要另外盤點這個目錄。
Provider 登入和 API key 是兩條路
啟動 Pi 後可以用 /login 選擇 subscription provider。官方 Quickstart 目前列出的內建 subscription login 包含 ChatGPT Plus／Pro（Codex）、Claude Pro／Max、GitHub Copilot、xAI、OpenRouter 和 Radius；Providers 文件則分開說明 OAuth、API key、環境變數和 auth file。這份清單會隨產品文件變動，讀者仍要在自己的 Pi 介面讀回。
另一條路是啟動前設定 API key，例如 export ANTHROPIC_API_KEY=sk-ant-...，或在 /login 裡選 API-key provider 存到 ~/.pi/agent/auth.json。不要把真正的 key 貼到文章、AGENTS.md、截圖或 issue。官方文件只是在說明存放方式，並不代表把 auth file 分享出去是安全的做法；後一句是本文的基本憑證管理建議。
帳號方案和 API 費用也要分開看。Pi 文件列出可以連接哪些類型的 provider，不能因此推出你的 subscription 包含第三方 harness 使用，或某個 provider 一定不會另外計費。若你在乎支出，請在 provider 本身讀回方案、usage 和 billing 條件，再用小任務測試；本文沒有取得任何帳號或費用資料。
第一次 session 先做只讀任務
官方 Quickstart 的基本流程是進入想讓 Pi 工作的專案目錄，再執行 pi。第一次不要直接下「重構整個專案並順便清理沒用的檔案」這種範圍模糊的指令。先用 Summarize this repository and tell me how to run its checks. 這類只讀任務，觀察它讀了哪些檔案、引用哪些規則、是否能說出測試命令。
我會把第一輪驗收拆成四個問題：
- 它是否在正確的工作目錄？
- 它是否讀到
README.md、AGENTS.md或其他必要的專案說明？ - 它提供的檢查命令是否真的存在於專案？
- 它是否明確說出尚未讀到或無法確認的資料？
確認這四件事後，再讓它處理一個小而可回退的修改。你也可以用 pi @README.md "Summarize this" 把檔案直接提供給初始 prompt，用 pi -p "Summarize this codebase" 做一次性非互動請求，或用 --mode json、--mode rpc 接到其他程序。這些 CLI 行為來自官方文件，是否適合你的 pipeline 則要自己驗收。
Provider、Model 與 Thinking Level 怎麼選
先選工作條件，再選模型名稱
Pi 的 provider 設定影響認證來源和模型目錄，model 設定影響這個 session 實際呼叫哪個模型，thinking level 則是互動設定的一部分。官方 CLI 參考提供 --provider <name>、--model <pattern>、--thinking <level> 和 --list-models [search]。互動模式則可以用 /model、/thinking，並在選擇器中儲存啟動預設。
本文建議的選擇順序是：先確認任務需不需要修改檔案，再確認 provider 的登入或 key，再從目前真的能看到的 model 中選一個，最後才調 thinking level。不要先用一個看起來很強的模型，再回頭處理它是否能寫檔、能否執行命令和誰負擔用量。模型選得再漂亮，工作目錄錯了還是會得到一個很有效率的災難。
| 你要確認的項目 | 可以從哪裡看 | 未確認時的寫法 |
|---|---|---|
| Provider 認證 | /login、環境變數或 auth file | unknown，不要假設已登入 |
| Model 清單 | /model 或 pi --list-models | 以當次讀回為準，不寫固定清單 |
| Thinking level | /thinking 或 CLI 選項 | 記錄任務與設定，不宣稱一定更準 |
| 使用量／費用 | provider 帳號或 billing 頁面 | no_data，不由 Pi 文件推估 |
| 執行權限 | Pi 工具選項、工作目錄與隔離設定 | 先用只讀任務，未確認就不要放大範圍 |
同一個任務要保留可比較的條件
如果你要比較兩個模型，不要一次改 provider、prompt、工具數量和測試資料，然後把結果差異都歸因給模型。先固定專案、任務、輸入資料、驗收條件和允許的工具，再記下 model、thinking level、session、錯誤和人工修改。這是本文的評估建議，不是官方公布的性能測試結果。
網站已有一篇 Claude 與 ChatGPT 比較，比較產品時同樣要把情境和條件寫清楚。這篇 Pi 教學不提供 Pi、Claude、ChatGPT 或 Hermes Agent 的速度、準確率或「誰最好」排名，因為本次沒有同一測試條件，也沒有取得相關性能資料。
Project Instructions、Settings 與 Project Trust
AGENTS.md 是工作規則，不是萬能 Prompt
你可以在 AGENTS.md 寫下專案慣例，例如「修改後執行哪一個 lint」、「不要在本機執行 production migration」、「完成後回報變更檔案和測試結果」。這種規則比每次重新貼一段長 Prompt 穩定，因為 Pi 會在啟動時載入它。但規則仍然是 context，模型可能誤讀、遺漏或遇到互相衝突的要求，所以重要動作仍要用實際 diff 和命令輸出驗收。
Pi 也能用 .pi/SYSTEM.md 或 APPEND_SYSTEM.md 影響 system prompt。這類檔案的影響範圍比一段普通任務訊息大，請先閱讀官方 Using Pi 文件的 System Prompt Files 說明，確認你要的是替換預設 prompt 還是附加內容。本文不建議為了讓 agent 看起來更有個性，就隨便把一堆不可驗收的規則塞進 system prompt。
Global Settings 和 Project Settings 的優先順序
官方 Settings 文件 說明，Pi 使用 JSON settings file，project settings 會覆寫 global settings。全域檔案位於 ~/.pi/agent/settings.json，專案檔案位於目前專案的 .pi/settings.json。互動模式可以用 /settings 處理常見選項，也可以用 /model 和 /thinking 儲存啟動預設。
這種覆寫很方便，也增加了排查成本。你看到的 model、工具、resource 或訊息傳遞方式，可能不是某一個檔案單獨決定的。當行為和預期不同，我會依序記錄目前工作目錄、全域設定、專案設定、載入的 Extensions／Skills、trust 決定和 CLI 參數，再重新啟動或 /reload。不要只改一個檔案就宣布問題已解決。
Project Trust 不等於 Sandbox
這是 Pi 導入時最需要先講清楚的地方。官方 Security 文件 明確說明，project trust 決定 Pi 是否載入專案設定、resources、packages 和 extensions，但它不是 sandbox，也不會限制模型在開始工作後要求工具做什麼。Pi 是 local coding agent，預設以啟動它的使用者權限執行。
互動啟動時，如果目前目錄有 .pi/settings.json、.pi/extensions、.pi/skills、.pi/prompts、.pi/themes、.pi/SYSTEM.md 或 project .agents/skills 等資源，Pi 可能要求你作 trust decision。信任只表示你允許那些專案資源載入，並不是替整個資料夾加上一道作業系統權限牆。如果你需要限制可寫目錄、網路或命令能力，要讀 containerization 方案，不能只按下 trust。
Extensions、Skills、Prompt Templates、Packages 有什麼不同
Pi 的擴充名稱很多，第一次看文件很容易把它們全部當成「插件」。實際上它們的載入方式、能做的事和風險不一樣。
| 類型 | 官方文件目前說明 | 適合處理的問題 | 主要風險 |
|---|---|---|---|
| Extensions | TypeScript module，可訂閱事件、註冊 tool、command、shortcut、flag 和 custom UI | 需要真正接入 runtime 或自訂工具行為 | 可執行任意程式，依 Pi 權限執行 |
| Skills | 可重用、按需要載入的 Agent Skills | 把一套工作方法和參考資源整理成能力 | Skill 內容可以指示模型採取行動，來源不可信時不能直接載入 |
| Prompt Templates | Markdown snippets，透過 /name 展開成完整 prompt | 固定常用任務的輸入規格 | 把過時或不完整的規則重複套用 |
| Pi Packages | 用 npm 或 git 分享 Extensions、Skills、Prompt Templates 和 Themes 的包裝 | 把一套資源安裝到不同環境 | 第三方 package 可能同時帶入多種資源與依賴 |
Extensions 是程式碼，不只是提示文字
官方 Extensions 文件 顯示，Extension 可以使用 ExtensionAPI，監聽 session_start、tool_call 等事件，註冊自訂 tool 和 command，也能建立 UI。文件也直接提醒，Extensions 會以完整系統權限執行，可以執行任意程式，只應安裝信任來源。
所以我會把 Extension 當成要做 code review 的專案依賴，而不是看到別人分享就複製到 ~/.pi/agent/extensions/。先讀它會 import 什麼、註冊哪些 tool、是否攔截命令、是否送資料到遠端、依賴從哪裡安裝，再決定要不要在隔離環境測試。尤其是能改寫 bash、接外部 API 或讀取整個 home directory 的 Extension，不要用「只是自動化一下」輕輕帶過。
Skills 和 Prompt Templates 的責任比較小，但不代表零風險
官方 Skills 文件 把 Skill 說成自包含的能力包，Pi 會掃描 skill location，把名稱和 description 放進可用清單，符合任務時再讀取完整內容。Skills 可放在 ~/.pi/agent/skills/、專案 .pi/skills/、package 的 skills 目錄或 CLI 指定的位置。
Prompt Template 則是 Markdown 片段，檔名會變成 slash command，例如 review.md 可以用 /review。如果你的需求只是固定「讀 staged diff、列出風險、最後附測試命令」，我會先用 Prompt Template。它不需要為了改一段文字就增加一個能執行任意程式的 Extension。
不過 Packages 文件仍提醒，Skills 可以指示模型執行包含 executable 在內的任意行動，package 裡的 Extensions 也有完整系統存取權。這是官方安全警告，不是說所有 Skill 都危險，而是提醒你不能只看名稱和星星數就放行。
Pi Packages 適合分享，也適合被誤裝
官方 Pi Packages 文件 說明，可以用 pi install npm:@foo/bar@1.0.0、git、URL 或本機路徑安裝 package，也能用 pi list、pi config、pi update 管理。Package 可以透過 package.json 的 pi key 或 convention directories 宣告資源。
本文建議第一次導入時先不要同時安裝一大串 package。用內建工具完成一個小任務，確認 session、provider 和驗收流程，再一個一個加入需要的資源。每次只增加一項，出現行為變化時才知道是哪個依賴造成的，這個做法有點慢，但比最後對著十個新 Extension 猜誰碰了設定檔省事。
Sessions、Branch 與 Compaction：長任務不要靠記憶力
Session 會保存，卻不會替你驗證
Pi 會自動保存 session 到 ~/.pi/agent/sessions/。使用 /session 可以查看目前 session file、ID、訊息數、tokens 和 cost；/tree 可以在 session tree 中跳回較早的訊息，/fork 從舊訊息開新 session，/clone 複製目前 active branch。這些功能適合把探索、修正和不同方案分開，卻不能代替 git、測試或人工讀 diff。
Session JSONL 可能包含 prompt、檔案片段、命令輸出和模型回覆。官方文件在這裡說的是保存位置和命令，不是你的組織資料政策。因此本文建議把 session 目錄視為可能含敏感內容的工作資料，交接、備份或使用 /share 前先檢查。沒有做過實際帳號和資料讀回時，不要對 session 是否符合你的公司保存政策下結論。
Compaction 是整理脈絡，不是增加模型記憶
LLM 有 context window 限制。官方 Compaction 文件 說明，Pi 會在對話變長時用 compaction 摘要較早內容、保留近期工作；/tree 切換分支時另有 branch summarization。兩者都會使用結構化摘要，也會累積追蹤檔案操作。
官方文件目前寫出的 auto-compaction 條件是 contextTokens > contextWindow - reserveTokens，預設 reserveTokens 為 16,384 tokens，可在 global 或 project settings 調整。這個數字是產品文件的現行設定說明，不是「每個模型都能記住 16,384 tokens」的意思，更不是長任務不會遺漏資訊的保證。
長任務遇到 compaction 後，我會重新確認三件事：摘要裡列出的檔案狀態和目前磁碟是否一致，模型是否還知道驗收條件，下一步是否應該先讀測試失敗輸出。若重要決定只存在一段很早的對話，請把它整理進專案文件或明確的任務訊息，不要把它留給摘要器猜。
安全與隔離：Pi 預設有權限，請先決定它能動哪裡
正常啟動時，Pi 不是沙盒
官方 Security 文件的說法很直接：Pi 以啟動它的使用者權限執行，該使用者可寫入的檔案都在同一個 local trust boundary。Project trust 只處理是否載入專案資源，不限制 tool execution。這意味著在陌生 repository、帶有可疑 script 的資料夾或包含客戶資料的 home directory 啟動 Pi，都要先停一下。
下面是我會在第一次導入時使用的風險表。它不是 Pi 官方的安全認證表，而是把官方限制轉成可操作的驗收項目。
| 風險情境 | 官方已說明的事實 | 本文的先行動作 |
|---|---|---|
| 陌生或不可信 repository | 專案資源可能需要 trust；trust 不是 sandbox | 先以不信任的只讀方式檢查，或移到隔離環境 |
| 第三方 Extension | Extension 可執行任意程式並使用 Pi 的系統權限 | 先讀 source、依賴、事件 hook 和網路行為 |
| 第三方 Skill／Package | Skill 可以指示模型採取行動；package 可能帶多種 resource | 固定來源和版本，單獨測試，不直接放進共用全域設定 |
| 需要修改檔案 | write、edit、bash 能影響目前工作目錄 | 先做 checkpoint，限制任務檔案，讀 diff 和測試結果 |
| 登入或 API key | credentials 可能存於 ~/.pi/agent/auth.json | 不放進 repo、截圖或 prompt，另查 provider 的 usage 和 billing |
| 長期保存 session | session 存在 ~/.pi/agent/sessions/ | 依組織保存政策處理，不把分享功能當成私密保證 |
需要隔離時，讀 Containerization 文件
Pi 官方 Containerization 文件 說明，Pi 預設以完整權限執行，但可以選擇把整個 Pi process 放進隔離環境，或讓 host 上的 Pi 把 tool execution 路由到隔離環境。文件列出 Gondolin extension、Plain Docker、OpenShell 和 Docker Sandboxes 等模式，隔離的部分、provider key 位置和前置需求各不相同。
這裡不適合直接宣布哪一種「最好」。如果你要的是 host 上保留認證、只把 built-in tools 放進 local micro-VM，官方表格把 Gondolin 列為一種模式；如果你要把整個 Pi 放進容器，Plain Docker 是另一種模式。你還要確認自訂 Extension 是否仍在 host 執行，因為官方文件提醒，host Pi 加上 tool-routing Extension 時，其他沒有自行委派操作的 custom extension 仍可能在 host 跑。
我的導入順序是：先在不含敏感資料的小型專案理解正常流程，接著決定是否需要容器，最後才加入第三方 Extension。不要把 containerization 當成安裝完成後才想起來的補丁，因為 provider key、project mount、custom tool 和網路出口都可能受架構選擇影響。
六步低風險導入流程
下面是一套可以複製到自己的專案規則裡的起步流程。前四步是在確認環境，第五步才交給 Pi 做小範圍修改，第六步把結果讀回。這是本文建議，不是官方唯一工作流程。
- 固定工作目錄。 先在終端執行
pwd、git status或同等的目錄檢查，確認 Pi 將在哪個 repository 工作。若目前目錄不是你要的專案，先停下來，不要靠 prompt 補救。 - 盤點 context 和資源。 找出
AGENTS.md、CLAUDE.md、.pi/settings.json、.pi/extensions、.pi/skills、.pi/prompts和.pi/themes。記下哪些是官方或團隊自己維護，哪些是第三方來源。 - 先做只讀任務。 啟動 Pi 後先要求它摘要 repository、列出測試命令和仍未知的地方。不要一開始就允許大範圍寫檔或執行會改資料的 shell command。
- 確認 provider 和 model。 用
/login、/model、/thinking或對應 CLI 選項確認實際讀回的設定，並把 provider、model、thinking level 和任務名稱記下來。查不到的項目保留unknown。 - 下可回退的小任務。 明確指定目標檔案、不可改的範圍、輸出格式和驗收命令。可以先處理一個測試、文件或小函式，不要把「順便清理」混進同一個請求。
- 讀 diff、跑檢查、決定是否保留。 先看
git diff和新增檔案，再執行既有 lint、test 或 build。若測試失敗、變更超出範圍、出現未解釋的網路請求或模型把 unknown 補成猜測，就先停，不要因為 agent 說完成了就合併。
你可以用這張表記錄每次任務。它的目的不是增加表格，而是讓「成功」有可以回頭看的證據。
| 檢查面 | 通過證據 | 需要停下來的情況 |
|---|---|---|
| 工作目錄 | 路徑和 repository 狀態正確 | 目錄不明、dirty 變更來源不明 |
| 資料範圍 | 讀取檔案和必要 context 有明確清單 | agent 引用未提供或找不到的資料 |
| 權限 | 只開啟完成任務需要的工具和路徑 | 要求額外 home、網路或破壞性命令 |
| 輸出 | diff 只包含目標修改 | 出現無關檔案、設定或格式變更 |
| 品質 | lint／test／build 或人工檢查有輸出 | 測試未跑、結果被摘要取代或失敗原因不明 |
| 可回復性 | 有 git checkpoint、session 名稱或明確備份 | 沒有辦法還原，也說不清誰改了什麼 |
這套流程和 如何實現工作自動化？ 的順序是一致的：先把工作問題和結果定義清楚，再把工具放進去。Pi 的設定很多，但不代表每一個設定都值得今天打開。
Pi Coding Agent 適合誰，什麼情境先不要用
這些需求比較符合 Pi 的設計
如果你的工作本來就發生在終端機，會反覆讀專案檔案、執行檢查、切換模型或需要把任務分成 session branch，Pi 的設計方向是對得上的。你可以從內建工具開始，再視需要加入 Prompt Template、Skill 或 Extension。對希望把 agent 規則放進專案 context、又不想被固定網頁工作區綁住的人，這種可配置性可能比一長串內建按鈕更實用。
如果你需要研究網頁、處理瀏覽器中的檔案或和非工程同事共同編修文件，則要先確認 Pi 是否真的解決你的下一步。網站上的 ChatGPT 介紹 和 Claude 介紹 分別整理了網頁工作區、Projects、研究、檔案和長文等另一類工作方式。這不是說 Pi 做不到，而是本文沒有替那些情境做同一條測試，也沒有取得你實際帳號的功能讀回。
這些情境先不要把 Pi 當成預設答案
第一種是你只想問一次問題，沒有要讓 agent 讀取或修改專案。安裝一個終端 coding harness，再處理 provider、trust、session 和權限，可能比問題本身還重。第二種是你準備把陌生程式碼或第三方 package 直接交給它執行，卻沒有隔離環境、checkpoint 或人工審查。這時候「能做」不是「應該做」。
第三種是你需要可量化比較不同模型，但還沒有固定資料集、任務和驗收標準。Pi 可以提供切換 provider 和 model 的入口，卻不會自動替你設計公平評估。若要做這件事，先建立評估方法，再決定要不要把 Pi 接進去。
Pi Coding Agent FAQ
Pi Coding Agent 是模型嗎？
不是。依 Pi 官方文件，Pi 是 minimal terminal coding harness，負責把模型、provider、工具、context 和 session 組成終端工作流程。模型仍要透過 subscription provider 或 API key provider 取得，實際可用的帳號、模型與額度要在你的環境讀回。
Pi 可以修改我的檔案嗎？
可以。官方 Quickstart 列出 write、edit 和 bash 等能力，也說明 Pi 會在目前工作目錄執行並可修改其中檔案。這不代表每次任務都會修改，也不代表修改一定正確。開始前請先確認目錄，完成後讀 git diff、新增檔案和測試結果。
Project Trust 是不是安全沙盒？
不是。官方 Security 文件明確區分 project trust 和 sandbox。Trust 控制專案設定、資源、packages 和 extensions 是否載入；Pi 仍然以啟動它的使用者權限執行。需要限制可寫目錄、命令或網路時，請另外評估 Containerization 文件列出的隔離模式。
我一定要安裝 Extensions 和 Skills 嗎？
不用。Pi 的核心工具、Prompt Template 或專案 context 已經可以支援不少起步任務。本文建議先用內建能力完成一個只讀任務，再按真正的缺口加入 Extension、Skill 或 Package。你不需要為了讓設定看起來完整而安裝一整套第三方資源。
Skills 和 Extensions 哪一個比較安全？
不能只用名稱判斷。Extensions 是可執行的 TypeScript module，官方提醒它們有完整系統權限。Skills 以可重用能力形式載入，但官方 Packages 文件也提醒 Skill 可以指示模型執行包含 executable 在內的行動。安全性取決於來源、內容、執行環境、權限和你的審查流程，不是取決於標籤。
Pi 的 session 會保存在哪裡？
官方 Sessions 文件指出，session 會自動保存到 ~/.pi/agent/sessions/，依工作目錄整理成 JSONL。你可以用 pi -c、pi -r 或 /resume 繼續工作，也能用 /tree、/fork 和 /clone 管理分支。若內容涉及客戶資料或憑證，請先按照自己的保存政策處理。
Compaction 會讓 Pi 永遠記得整個專案嗎？
不會。Compaction 是在 context 太長時摘要較舊內容並保留近期工作；官方也把 branch summarization 分開說明。摘要仍可能遺漏你沒有寫進明確檔案或任務訊息的條件，所以長任務要用 session、專案文件、git diff 和測試一起回查，不能只相信摘要。
Pi 的 provider 清單代表我現在一定能登入嗎？
不代表。官方 Providers 文件列出支援的認證方式和 provider 類型，但你的帳號、方案、金鑰、地區、額度和當日模型目錄仍可能不同。請把文件證據和帳號讀回分開記錄；本篇沒有替任何特定帳號登入驗證。
結語：先讓第一個任務可回查
Pi Coding Agent 的吸引力不在於把一個聊天視窗搬進終端機，而在於它把模型之外的工作層攤給你設定：provider 可以換，context 可以放進專案，session 可以分支，Extensions 和 Skills 可以按需加入，命令和檔案也真的會在本機發生。這種自由很實用，但它同時要求你自己處理權限、來源、保存和驗收。
如果你今天要試，從一個不含敏感資料的小型專案開始。先跑只讀摘要，再確認 provider 和工作目錄，最後做一個有明確 diff 和測試命令的小修改。做完後把 session、設定和結果記下來，再決定是否需要 package、隔離或更長的自動化流程。先讓第一個任務可回查，通常比一開始就把整個 agent 生態系搬回家更有用。
來源與查證日期
本文查證日期：2026-09-17，Asia/Taipei。以下連結都是 Pi 官方文件或其官方文件導覽頁；功能、provider、模型目錄、方案和介面可能變動，使用前請重新讀回。
- Pi Documentation：產品定位、Quickstart、Using Pi、Providers、Security、Sessions、Compaction 和擴充文件導覽。
- Quickstart：安裝、登入、API key、第一個 session、context file、CLI 與非互動模式。
- Using Pi：互動介面、slash commands、工具、sessions、context files、project trust 和 CLI reference。
- Providers：subscription、API key、auth file、環境變數、cloud providers 和 provider resolution。
- Security：使用者權限、project trust、沒有內建 sandbox 的邊界與安全提醒。
- Containerization：Gondolin、Plain Docker、OpenShell、Docker Sandboxes 與 tool-routing 模式。
- Settings：global／project JSON settings、project trust、model、message、tool 和 session 選項。
- Sessions：session 保存、JSONL、resume、tree、fork、clone 和 share。
- Compaction & Branch Summarization：auto-compaction、branch summary、reserve tokens 與檔案追蹤。
- Extensions：Extension API、工具／命令／事件、資源位置與完整系統權限提醒。
- Skills：Skills 的載入位置、progressive disclosure、project trust 與安全提醒。
- Prompt Templates：Markdown template、slash command、argument hint 和載入位置。
- Pi Packages：npm／git／本機 package 安裝、資源打包、管理命令與第三方資源風險。