Pi Coding Agent 完整指南：極簡終端 AI 程式助手入門與實戰工作流

你是不是也遇過這種情況：開了某個 AI 程式助手，它硬要你走「先規劃 → 再開子代理 → 再審查」的流程，結果改一個小 bug 也要等它跑完一整串儀式？

市面上很多 Coding Agent 越來越像「整套 IDE 替代品」，而不是「幫你省時間的夥伴」。如果你想要的是：極簡、快、能嵌進自己習慣的終端工作流，那值得認識 Pi Coding Agent（pi.dev）。

這篇會帶你從「它是什麼」一路走到「怎麼裝、怎麼設定、怎麼跟 Cursor 分工」——讀完你可以決定要不要試，以及該用哪種工作流模式。

什麼是 Pi Coding Agent？

Pi Coding Agent 是跑在終端機（Terminal）裡的 AI 程式開發助手，由 Earendil Inc. 維護。它的設計哲學可以濃縮成一句話：

世界上有很多 Agent 框架，但這一個是你的——工具來適應你，不是你來適應工具。

跟 Devin、重度多代理編排系統不同，Pi 走的是 「極簡核心 + 按需擴充」：

Devin 是 Cognition 推出的自主 AI 軟體工程師（devin.ai）：接到任務後會自行拆解步驟、讀 repo、寫 code、跑測試、開 PR，人類多半只需審核結果。這類「大而全」的 agent 平台內建規劃模式與子代理編排，能獨立完成整個 feature，但工作流往往也由工具決定，而不是開發者自己拼裝。

• 核心只有四個工具：read、write、edit、bash
• 不內建 sub-agent、Plan mode、全專案向量索引
• 能力靠你自己加：AGENTS.md、Skills、Extensions、Pi Packages

白話說：你在專案資料夾打 pi，就能用自然語言叫 AI 讀檔、改 code、跑測試；要不要加 MCP、子代理、網頁搜尋，全由你決定。

四層架構（看懂 Pi 在幹嘛）

把 AI 直接放在終端的好處很實際：不用再「複製錯誤訊息 → 貼到聊天窗 → 複製修復 code 回來」。Linter 報錯、測試失敗，Agent 可以直接讀輸出並迭代修正。

Pi vs Cursor vs Claude Code：該選誰？

Pi 不是 Cursor 的平替，而是不同取捨。下面這張表幫你 30 秒判斷：

依場景選工具

實戰分工（很多人兩邊都裝）：主專案用 Cursor 改 UI、多檔 refactor；Pi 負責終端批次任務、長跑腳本、低成本實驗。同一目錄同一時間只讓一邊寫檔——並行時用 git worktree 隔離。

四種運作模式

Pi 不只有「開 TUI 聊天」：

互動模式裡還有兩個很多人愛用的即時控制：

• Steering（Enter）：Agent 還在跑時，你可以立刻送新指令糾偏；目前工具執行完就切方向，不會傻等整條鏈跑完。
• Follow-up（Alt + Enter）：排程下一則訊息，等當前任務完成後自動接上。

長對話別硬撐——用 /compact 壓縮舊訊息，或 /tree 開分支試另一條路，歷史都留在同一個 session 檔裡。

上下文工程：Pi 真正厲害的地方

AI 回得好不好，八成看上下文怎麼塞。Pi 的策略是：Harness 保持極簡，上下文全部可組合、可版本控制。

1. Context Files（AGENTS.md / SYSTEM.md）

Pi 啟動時會串接多層指令檔：

SYSTEM.md 可完全替換或追加預設 system prompt——適合鎖語言、安全邊界、角色人設。

實戰建議再配一份 APPEND_SYSTEM.md（放 ~/.pi/agent/）：跨專案行為，例如「先讀本地、危險操作先問、不確定就停下來問人」。它的權重通常高於專案 AGENTS.md。

範例（專案根 AGENTS.md）：

# Project Instructions
- 改 code 後跑 `npm run check`。
- 不要動 production 設定檔。
- 不確定時先問我。

2. Skills：按需載入的能力包

Skills 是 Markdown 檔，frontmatter 有 name 和 description。Pi 只在 system prompt 放摘要；Agent 要用 read 才載入全文——避免一次塞爆 context。

手動觸發：/skill:git-workflow。發現路徑：~/.pi/agent/skills/、.pi/skills/、.agents/skills/（專案 skills 需 trust 專案）。

3. Prompt Templates：可重用的 / 指令

帶參數的 Markdown 模板，例如 /review src/auth.ts 展開成完整審查 prompt。支援 $1、$ARGUMENTS 等替換。適合標準化 code review、部署 checklist。

4. Extensions：動態注入 RAG

TypeScript 模組可訂閱 context 事件，在每次 LLM 呼叫前改 message 陣列。社群 pi-local-rag 就是典型：本地 BM25 + 向量混合檢索，按 turn 注入相關 chunks，不動 system prompt，維持 KV-cache 效率。

Project Trust（安全邊界）

專案含 .pi/ 或 .agents/skills/ 時，Pi 會問你是否 trust。未信任前只載入 context files；信任後才載入專案 extensions——避免惡意 repo 配置執行任意程式碼。

為什麼 Pi 刻意不內建 MCP、子代理、Plan mode？

這不是「功能缺失」，是設計選擇：

官方態度很直白：Ask Pi to build it, or install a package.

套件安裝範例：

pi install npm:pi-mcp-adapter    # MCP 生態，~200 token 代理工具
pi install npm:pi-subagents      # scout → planner → worker 鏈
pi install npm:pi-web-access     # 網頁搜尋與抓取

套件選型：不要一開始裝滿排行榜

pi.dev/packages 已有 50+ 社群套件。最佳實務是 Tier 0 起步，痛點出現再加。

pi-mcp-adapter：MCP 但不炸 context

傳統 MCP 可能一個 server 就 10k+ tokens。pi-mcp-adapter 用單一 mcp 代理工具（約 200 token）按需發現與呼叫：

mcp({ search: "screenshot" })
mcp({ describe: "chrome_devtools_take_screenshot" })
mcp({ tool: "chrome_devtools_take_screenshot", args: '{"format": "png"}' })

Server 預設 lazy 啟動（第一次呼叫才連線）。常用工具可設 directTools 升級為一級工具。

pi-subagents：子代理怎麼編排

內建 8 種角色：scout、researcher、planner、worker、reviewer、oracle 等。支援 單一、鏈式（chain）、並行（parallel） 三種模式。

實戰 prompt 範例：

Use scout to map the auth flow, then planner for an implementation plan.
Run parallel reviewers: correctness, tests, and unnecessary complexity.

注意：parallel 模式 token 成本會倍增；裝了套件也不會自動跑 reviewer——要在 prompt 或 AGENTS.md 裡明確要求。

五階段實戰工作流

Pi 沒有「唯一官方流程」，但下面這套在實戰中最穩：

Phase 0  設定層（一次性）
   AGENTS.md + APPEND_SYSTEM.md + 精選 packages
        ↓
Phase 1  任務釐清
   自然語言目標 → 大任務用 create_goal 或 planner
        ↓
Phase 2  探索（唯讀）
   scout / read+grep / web-access
        ↓
Phase 3  實作
   worker 或主 session 小步 edit
        ↓
Phase 4  驗證閉環
   bash 跑 test/lint → reviewer → 修正
        ↓
Phase 5  上下文維護
   /compact、/tree 分支、context-mode（長 session）

三個反模式請避開：

1. 一開始裝滿熱門榜——context 與認知負擔暴增
2. 長專案只靠對話記憶——應寫進 AGENTS.md、goal 檔或 plan.md
3. 沒給驗證條件就「改到好」——一定要指定 test/lint 成功才算完

探索階段原則：計畫寫進檔案（plan.md、context.md），先讀本地，不足再 web，大改前先跟人確認。

安裝與第一次實戰（約 10 分鐘）

前置：Node.js ≥ 22.19.0。

# 方式 A：官方 npm（方便鎖版本）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式 B：macOS / Linux 一鍵腳本
curl -fsSL https://pi.dev/install.sh | sh

確認：

node -v    # ≥ 22.19.0
pi --help

登入模型（憑證存 ~/.pi/agent/auth.json）：

cd /path/to/your-sandbox-project   # 先用可弄髒的 side project
pi
/login

支援 Claude / ChatGPT / Copilot 訂閱 OAuth，或各廠 API Key。CI 可用環境變數，例如 export ANTHROPIC_API_KEY=...。

第一次驗證：

Summarize this repository and tell me how to run its checks.

進階試試：@README.md 附加檔案、!npm run lint 跑 shell、pi -p "Summarize" 非互動模式。

新手常見踩坑

推薦工具與資源

延伸閱讀：Pi Quickstart、Extensibility 文件、Pi Packages 目錄。

結語：回歸極簡，但別回歸低效

Pi Coding Agent 重新定義了「AI 助手該怎麼存在於開發流程裡」——不試圖接管整個 IDE，而是當一個快、可配置、可版本控制的終端夥伴。

三個 takeaway：

1. 極簡核心（四工具）換來 token 效率與完整上下文控制權
2. 能力按需加（Packages / Skills / Extensions），不要一開始裝滿
3. 跟 Cursor 分工：IDE 改 UI、Pi 跑終端批次與實驗——同一 worktree 別兩邊同時寫

若你厭倦了沉重、黑盒、硬塞工作流的 AI 工具，建議先用 sandbox 專案試一輪：到 pi.dev 安裝 → /login → 寫一份 AGENTS.md → 跑一個小任務驗證四工具閉環。覺得順了，再按需加 pi-mcp-adapter 與 pi-subagents。