MODULE 04 · STEP 11 · 可練習
擴充功能（Extension）的需求與驗收
本課結果
你會顯式載入一個只註冊 /bluebook-check 命令的教學擴充功能，親眼確認它出現、執行並在停用後消失。桌面通知放在本課最後作為進階設計，不把終端機內提示冒充系統通知。
我對擴充功能的理解來自一個很小的煩惱。Pi 跑長任務時，我會切到別的視窗，任務已經停下來卻沒有立即發現。
這個需求適合做第一個擴充功能，因為它有清楚的觸發條件、簡單的系統動作，而且容易驗收。
先把需求說清楚
不要一開始就寫“實現完美的系統通知”。先給第一版定四條邊界：
- 只在 Agent 結束工作、等待新訊息時考慮提醒。
- 終端機正在前臺時不打擾。
- 提醒內容不包含私密任務全文。
- 提醒失敗不得破壞 Pi 本身的工作階段。
這時你已經可以看到擴充功能的輪廓：它要接收 Pi 的事件，判斷狀態，再執行一個系統動作。
理解檔案放在哪裡
Pi 可以載入使用者級或專案級的擴充功能。初學時建議從獨立練習專案開始，只讓這個專案使用它。這樣容易看清來源，出錯時也容易停用。
專案信賴提示不是多餘的障礙。專案級擴充功能會執行程式碼，它能做什麼取決於當前使用者的權限。只有當你知道檔案從哪裡來、大致做什麼，才應信賴該專案。
官方當前的自動發現位置是使用者級 ~/.pi/agent/extensions/ 和專案級 .pi/extensions/。放在這些位置的檔案可以在 Pi 中用 /reload 重新載入；本課使用 -e 顯式路徑做一次性測試，不把教學檔案長期安裝進去。
實作：載入一個最小擴充功能
這次不直接製作桌面通知。先用一個無檔案讀寫、無網路存取的命令驗證完整載入流程，再討論系統通知所需的額外邊界。
1. 下載並讀完程式碼
退出 Pi，在普通終端機進入 pi-practice 後執行：
mkdir -p bluebook-examples
curl -fL https://pi.xiaomovps.com/examples-tw/extension/bluebook-check.ts \
-o bluebook-examples/bluebook-check.ts開啟這個檔案。完整程式碼只有一個匯入、一個預設函式和一個 registerCommand 呼叫；命令執行後只透過 ctx.ui.notify 顯示一條 Pi 介面提示。若你下載到的內容不同，停止，不載入。
2. 只為本次啟動載入它
在普通終端機執行：
pi --no-extensions -e ./bluebook-examples/bluebook-check.ts--no-extensions 會忽略其他自動發現的擴充功能，-e 再顯式加入本課檔案。進入 Pi 編輯區後輸入：
/bluebook-check預期看到“藍皮書擴充功能已載入；本命令沒有讀取或修改檔案。”這條介面提示。它證明命令已註冊且處理函式成功執行；它不證明桌面通知、後台任務或其他擴充功能能力已經可用。
啟動資訊列出了 bluebook-check.ts，中間的中文提示是執行 /bluebook-check 後出現的 Pi 介面回饋。本次使用離線啟動，命令本身沒有模型呼叫、檔案讀寫或網路存取。停用是否成功仍要按下一步重新啟動後檢查。
3. 停用並複核
輸入 /quit 回到普通終端機，再直接執行：
pi --no-extensions此時 /bluebook-check 不應再成為可執行的擴充功能命令。若仍然出現，先核對本次啟動命令是否真的沒有 -e，再檢查專案 .pi/extensions/ 和使用者目錄 ~/.pi/agent/extensions/ 是否另有同名檔案。不要刪除不認識的檔案；只記錄來源並停止。
如果擴充功能語法錯誤，Pi 會顯示載入錯誤。保留完整錯誤和檔案路徑，使用不帶 -e 的命令重新啟動即可繞過本課擴充功能；載入失敗不應成為刪除工作階段或練習材料的理由。
用可觀察結果驗收
真正製作桌面通知時至少要測試三種情況：
| 場景 | 應有結果 |
|---|---|
| 終端機在後台，Agent 真正結束任務 | 出現一次可見提醒 |
| 終端機在前臺，你正在檢視 Pi | 不額外彈出提醒 |
| 仍在執行工具呼叫，或還有排隊訊息 | 不把中間狀態誤判為完成 |
命令會列印出一段控制字元，只能證明命令被呼叫。它不能證明 macOS 桌面上真的出現了通知。最後的證據要包括真實介面觀察，並隱去使用者名稱、路徑和私密內容。
完成基礎載入後，去 CASE 04 的自定義練習改一個命令名和提示文字，再驗證停用；不要只停在下載現成程式碼。
從最小命令走向桌面提醒
實際完成這個小功能時，會經歷一個完整的擴充功能開發迴圈：從真實需求出發，找到事件，寫最小行為，重新載入，復現場景，檢查副作用。
當前官方擴充功能事件中，agent_end 代表一次底層執行結束，之後仍可能自動重試、壓縮重試或處理排隊訊息；用於“任務已經不會自動繼續”的狀態整合時，應優先評估 agent_settled。但“終端機是否在前臺”和“怎樣呼叫 macOS、Windows 或 Linux 的桌面通知”屬於作業系統能力，不是同一個事件就能跨平台解決。
進階案例尚未冒充完成
本課已經完成擴充功能的下載、審查、載入、執行和停用閉環。後台桌面通知仍需分別核驗作業系統通知權限、前臺判斷和真實介面；在沒有真實截圖與復現場景前，不把它標成已驗收。
本課驗收
- 你讀過實際載入的
.ts檔案，能指出它註冊的命令和唯一可見動作。 - 帶
-e啟動時/bluebook-check顯示預期提示。 - 不帶
-e再啟動時，該教學命令不再可用。 - 即使程式碼載入失敗，也能繞過該檔案重新進入 Pi，原工作階段和練習材料沒有被刪除。
本章依據
擴充功能 API 與 agent_settled 事件核驗於 2026-09-09。教學檔案已在本機 Pi 0.80.10 中實際載入，bluebook-check 命令註冊成功，並返回預期介面通知請求。