TROUBLESHOOTING · 按症狀縮小範圍
Pi 故障排查手冊
這不是錯誤程式碼百科，也不從“工作階段（Session）、上下文（Context）、擴充功能（Extension）”這些知識分類開始。先找到你眼前看到的現象，再按同一條路線處理：保留現場 → 檢查最小條件 → 建立乾淨基線 → 每次只恢復一個變數 → 到達停止條件就停。
涉及命令和當前行為的內容核驗於 2026 年 9 月 11 日，本機版本為 Pi 0.80.10。實際輸出不一致時，先以你本機的 pi --help 和 Pi 最新官方文件 為準。
先不要做的事
不要一上來重灌、清空 ~/.pi/agent/、刪除工作階段、執行 pi update --all，或同時停用一批自己記不清的外掛程式。這些動作會改變現場，讓原來的問題更難定位；認證目錄還可能包含私人工作階段與憑據。
先用一分鐘判斷問題在哪一層
| 看到的現象 | 先進入 |
|---|---|
普通終端機提示 command not found，或 Pi 介面根本打不開 | 啟動不了 |
| Pi 能開啟，但模型清單為空、缺少目標模型或請求報認證錯誤 | 模型不出來 |
啟動時出現 .ts、import、工具或命令註冊錯誤 | 擴充功能載入失敗 |
技能（Skill）能看到卻不執行，或 /skill:name 不存在 | 技能沒觸發 |
pi -c、pi -r 找不到原來的任務 | 工作階段找不到 |
| 介面已經開啟，但傳送後長期沒有新內容 | 突然不響應 |
| 上下文接近上限、壓縮失敗或壓縮後忘了關鍵要求 | 上下文爆了 |
| 單獨啟用都正常，一起啟用就報錯或行為改變 | 外掛程式互相衝突 |
| Pi 讀錯目錄、修改越界，或“說完成”但檔案不對 | 檔案和工具結果異常 |
建立最小基線
很多問題都需要先回答一個問題：不用任何專案資源和自動發現資源時，Pi 能不能正常啟動？
在普通終端機執行：
pi --no-approve --no-extensions --no-skills --no-context-files \
--no-prompt-templates --no-themes --verbose這條命令只用於排查。它臨時忽略專案資源、擴充功能、技能、上下文檔案、提示模板和主題，但不是沙箱，也不會修復任何東西。
- 基線也失敗：優先查安裝、Node、終端機、認證或模型服務商（Provider）。
- 基線正常：問題更可能來自專案目錄、工作階段或某個附加資源。
- 恢復一個資源後才失敗：已經把範圍縮小到這個資源或它與當前環境的組合。
1. 為什麼啟動不了？
你看到的現象
- 普通終端機顯示
pi: command not found。 pi有輸出，但在進入互動介面前退出。- 介面卡在啟動階段，錯誤中出現 Node、模組、設定或資源路徑。
先檢查什麼
先區分“系統找不到命令”和“Pi 已經啟動但初始化失敗”。不要把 Pi 編輯區當作普通終端機，也不要根據舊教學隨機改 PATH。
pwd
command -v node
node --version
command -v pi
pi --version
pi --helpWindows 使用者在本書約定的 Git Bash 中執行這些命令。如果 command -v pi 沒有結果，問題還沒進入 Pi 內部；回到安裝並啟動 Pi核對安裝方式和當前官方要求。
怎樣縮小範圍
如果 pi --version 正常，但互動介面打不開，先執行本頁的最小基線。如果仍卡在啟動網路階段，再試一次：
pi --offline --no-approve --no-extensions --no-skills \
--no-context-files --no-prompt-templates --no-themes --verbose--offline 只用於判斷啟動網路操作是否相關。離線能開啟不代表模型服務商呼叫一定正常，也不應直接得出“網路就是唯一原因”。
什麼時候停止
- 錯誤要求提升系統權限、修改系統目錄或執行陌生安裝指令碼。
- 你準備刪除整個設定目錄，只為了“試試看”。
- Node 或 Pi 的來源無法確認，且錯誤涉及被替換的可執行檔案。
保留版本、完整錯誤、終端機型別和 command -v 的路徑，再求助。
2. 為什麼模型不出來？
你看到的現象
/model清單為空，或沒有教學裡提到的型號。- 能選模型，但傳送後出現未登入、無權限、額度不足或模型不可用。
- 模型服務商已經發布新模型，本地目錄還沒出現。
先檢查什麼
先把三個問題分開：目錄裡有沒有這個模型、當前有沒有憑據、使用者帳戶是否真有該模型的呼叫權限。安裝 Pi 本身不會自動獲得模型或額度。
pi --list-models
pi --list-models 關鍵詞
pi update --models前兩條只檢視當前目錄；第三條重新整理模型目錄，不升級 Pi 本體。然後啟動 Pi，在編輯區使用 /login 核對模型服務商、用 /model 重新選擇。
怎樣縮小範圍
| 常見結果 | 更可能的方向 |
|---|---|
--list-models 完全沒有目標模型服務商 | 模型目錄或自定義模型服務商設定 |
清單有模型，但 /model 裡不可用 | 當前模型服務商、範圍過濾或認證狀態 |
| 請求返回 401 / 403 | 憑據、訂閱或使用者帳戶權限；以模型服務商的原始錯誤為準 |
| 請求返回 429 | 額度、速率限制或併發限制；不要立即反覆重試 |
| 請求返回 404 / model not found | 模型 ID、區域、模型服務商或目錄過期 |
| 請求超時或 5xx | 網路、代理或模型服務商服務狀態 |
不同模型服務商的狀態碼含義可能不同，這張表只是定位方向。測試付費模型前先確認費用；不要把 API Key 貼到聊天、截圖、專案檔案或命令引數中。
什麼時候停止
- 登入頁、回撥網域或模型服務商來源不可信。
- 重試正在持續計費，或 429 尚未恢復。
- 需要複製
auth.json、完整 Token 或 API Key 才能繼續求助。
3. 為什麼擴充功能載入失敗？
你看到的現象
- 啟動資訊顯示某個
.ts/.js檔案載入失敗。 - 擴充功能註冊的命令或工具沒有出現。
- 載入後 Pi 能啟動，但呼叫自定義工具時報錯。
先檢查什麼
先保留錯誤中的完整檔案路徑和第一條異常。擴充功能在 Pi 程序中執行程式碼，問題可能來自發現路徑、專案信賴（Project Trust）、import、依賴、版本或執行時邏輯。
pi --no-extensions --verbose
pi --no-extensions -e ./path/to/extension.ts --verbose第一條確認“沒有擴充功能時能否啟動”；第二條關閉自動發現後只顯式載入目標檔案。
怎樣縮小範圍
- 不帶擴充功能正常，顯式載入失敗：問題已經縮小到該檔案、依賴或當前 Pi 相容性。
- 顯式載入正常，自動發現失敗：檢查全域與專案發現位置、設定、包（Package）和專案信賴。
- 啟動正常，只有工具執行失敗：保留該次 Tool Call 輸入與錯誤，問題在執行路徑，不是“沒載入”。
- 只有
/reload後失敗：重新啟動做一次冷載入，區分過載狀態和檔案本身。
用 pi list 檢視登記的包，用 pi config 檢視其中哪些擴充功能被啟用。不要為了排查先執行 pi update --all，更新多個包會同時引入更多變數。
什麼時候停止
- 擴充功能來源不明，或要求憑據、系統權限、刪除檔案與對外傳送。
- 錯誤指向依賴安裝，但你還沒有審查
package.json和安裝指令碼。 - 關閉擴充功能後問題消失，但重新啟用會重複產生越界寫入或危險命令。
4. 為什麼技能沒觸發？
你看到的現象
- 你認為任務應該匹配某個技能，但 Pi 沒有讀取它。
/skill:name不存在。- 技能被讀取了，結果卻沒有按說明執行。
先檢查什麼
先區分“沒有發現”“發現但沒有自動選擇”和“已經載入但執行偏離”。確認真正的入口是 SKILL.md，frontmatter 至少有有效的 name 與非空 description。
test -f ./path/to/skill/SKILL.md
sed -n '1,40p' ./path/to/skill/SKILL.md
pi --no-skills --skill ./path/to/skill/SKILL.md --verbose--no-skills 關閉自動發現，但顯式 --skill 仍然會載入指定路徑。進入 Pi 後使用 /skill:name 可以強制讀取該技能；自動匹配不能保證每次都觸發。
怎樣縮小範圍
/skill:name不存在：檢查路徑、frontmatter、名稱規則和啟動警告。- 命令存在，自動任務沒觸發：
description可能沒有準確描述使用場景，或模型沒有選擇讀取；先用顯式命令驗證，不要直接把描述改成“適用於所有任務”。 - 技能已讀取但找不到指令碼：檢查相對路徑是否以技能目錄為基準、配套檔案是否齊全。
- 出現同名警告：Pi 會保留先發現的同名技能；先確認實際載入來源，再處理碰撞。
什麼時候停止
- 技能引導執行未審查的指令碼、安裝依賴、讀取憑據或存取任務外目錄。
- 為了提高觸發率準備寫一個覆蓋所有任務的寬泛描述。
- 你無法確認當前載入的是哪一個同名技能。
5. 為什麼工作階段找不到？
你看到的現象
pi -c開啟的不是剛才的任務。pi -r或/resume清單裡沒有熟悉的工作階段名。- 專案移動、重新命名或換電腦後，原工作階段不再出現。
先檢查什麼
Pi 的工作階段預設按工作目錄組織。pi -c 是繼續當前專案最近的工作階段，不是全域最近聊天。
pwd
pi -r在選擇器中可用 Ctrl+P 顯示路徑、Ctrl+N 只看命名工作階段。進入候選工作階段後用 /session 核對檔案、ID、訊息數、Token 和成本；發現選錯就退出，不要繼續寫入。
怎樣縮小範圍
- 回到建立工作階段時的原目錄，再執行
pi -r。 - 如果知道工作階段檔案或 ID，使用
pi --session <路徑或ID>精確開啟。 - 如果當時用了
--no-session，這次對話本來就不會儲存。 - 如果當時用了
--session-dir，必須回到相同目錄設定或提供具體工作階段路徑。 - 倉庫被移動或重新命名時，舊工作階段仍可能存在，只是不會自動歸到新路徑下。
什麼時候停止
- 準備直接編輯 JSONL 來“修復”工作階段樹。
- 工作階段包含私人提示、憑據或客戶資料，卻準備整份公開上傳。
- 還沒確認路徑和名稱，就要在選擇器裡批次刪除舊工作階段。
6. 為什麼突然不響應？
你看到的現象
- 傳送後長期沒有文字，但狀態列仍顯示工作中。
- 卡在一次工具呼叫、網路請求或壓縮（Compaction）。
- 介面能操作，只有當前工作階段不再向前。
先檢查什麼
先等當前工具的合理完成時間，再按一次 Esc 停止這一輪。Esc 能中止尚未完成的工作，但不能撤銷已經發生的檔案寫入、命令、釋出或對外傳送。
停止後立即記錄：當前模型、最後一個 Tool Call、最後一條可見錯誤、是否已經有檔案變化，以及這次請求是否可能計費。
怎樣縮小範圍
啟動一個不儲存、沒有工具和附加資源的最小測試：
pi --no-session --no-tools --no-extensions --no-skills \
--no-context-files --verbose只傳送一句短文字，不讓它讀檔案或執行命令。
- 最小請求也不返回：優先檢查認證、網路、代理、模型服務商狀態和額度。
- 最小請求正常，原工作階段不正常：檢查上下文、工作階段歷史或特定模型。
- 沒有工具時正常，一啟用工具就卡：定位最後一個 Tool Call 和外部程序。
- 沒有擴充功能時正常：轉到擴充功能排查或衝突排查。
什麼時候停止
- 相同請求可能計費，卻已經連續重試。
- 最後一個動作涉及部署、刪除、付款或對外傳送，結果狀態未知。
- 外部命令仍可能在後台執行，而你準備重複啟動同一任務。
先獨立檢查真實系統狀態，不要把“介面沒回復”直接等同於“動作沒發生”。
7. 為什麼上下文爆了？
你看到的現象
- 狀態列的上下文佔用接近上限。
- Pi 自動開始壓縮，或
/compact失敗。 - 壓縮後還能繼續，但漏掉早期約束、錯誤原文或檔案狀態。
先檢查什麼
先把不能丟的事實寫入專案內的檢查點：目標、禁止事項、已完成、真實檔案變化、失敗原文和唯一下一步。不要把關鍵狀態只留在準備被壓縮的聊天裡。
在 Pi 中用 /session 檢視當前工作階段資訊；需要壓縮時使用：
/compact壓縮需要模型生成摘要。它會用摘要和近期訊息重建後續上下文，不會撤銷磁碟修改，也不保證逐字保留全部舊細節。
怎樣縮小範圍
- 壓縮前就混入多個無關任務：新增命名工作階段，重新讀取檢查點，通常比連續壓縮更清楚。
- 單次工具輸出特別大：以後改為讀取必要片段，把長日誌儲存到檔案並提取關鍵行。
/compact本身失敗：保留錯誤；檢查當前模型是否可用、請求是否仍能呼叫模型服務商。- 壓縮後漏約束：讓 Pi 重新讀取原需求和檢查點，並逐項複述；不要用新的長解釋繼續覆蓋問題。
什麼時候停止
- 摘要已經丟失安全邊界或禁止動作，而下一步具有副作用。
- 連續壓縮仍無法容納單個超大輸入或工具結果。
- 你無法說明磁碟檔案、工作階段歷史和當前上下文哪一個才是可信來源。
8. 為什麼外掛程式互相衝突？
你看到的現象
- 兩個包單獨啟用正常，一起啟用時啟動失敗。
- 同名命令、工具或技能指向了意外來源。
- 載入新外掛程式後，System Prompt、模型、工具選擇或介面行為發生變化。
先檢查什麼
不要先更新全部外掛程式。先記錄“最後一次正常”的資源組合，再檢視當前登記內容：
pi list
pi --no-approve --no-extensions --no-skills --no-context-files \
--no-prompt-templates --no-themes --verbose如果幹淨基線正常，就從零開始每次只顯式加入一個資源：
pi --no-extensions -e ./one-extension.ts --no-skills --verbose
pi --no-skills --skill ./one-skill/SKILL.md --no-extensions --verbose怎樣縮小範圍
- 固定同一個目錄、Pi 版本、模型和測試任務。
- 先測 A，再測 B，最後測 A+B。
- 記錄每次啟動時真實載入的資源和第一處行為差異。
- A、B 單獨正常而 A+B 失敗，才有“衝突”的證據。
- 確認來源後，可用
pi config暫停包中的某項資源；一次只改一個開關。
同名技能會發生髮現順序與名稱碰撞；擴充功能還可能註冊同名命令、工具或事件處理器。不要只按包名猜能力，應該檢查實際載入的是擴充功能、技能、模板還是主題。
什麼時候停止
- 無法確認兩個資源的來源、版本或實際程式碼。
- 衝突涉及命令攔截、權限控制、憑據、部署或刪除保護。
- 需要透過刪除整個包目錄、全域設定或所有快取來繼續試錯。
9. 為什麼讀錯檔案、改錯目錄或“完成”卻沒有結果？
你看到的現象
- Pi 回答了內容，但目標檔案不存在或沒有變化。
- 修改出現在同名的另一個專案裡。
- Agent 說測試透過，普通終端機復跑卻失敗。
Esc後以為動作已撤銷，實際檔案已經改變。
先檢查什麼
回到真實環境，不問 Agent 自己是否完成：
pwd
git status --short
git diff --check
git diff不是 Git 專案時，直接開啟目標檔案並檢查修改時間、內容和輸出路徑。再回看工作階段中真正發生的 Tool Call，不要只看最後總結。
怎樣縮小範圍
pwd不對：停止當前工作階段，回到正確目錄再建立或恢復任務。- 狀態有範圍外檔案：先保留差異，分清已有變化與本次變化，不做批次恢復。
- Agent 報告透過但沒有命令輸出：由人在普通終端機執行專案規定的檢查。
- 本地檔案正確但線上不對：繼續檢查部署版本、構建目錄、快取和正式 URL；本地透過不是線上透過。
什麼時候停止
- 發現憑據檔案、使用者目錄或任務外倉庫被讀取或修改。
- 釋出、付款、刪除、訊息傳送的最終狀態無法確認。
- 為了恢復準備使用覆蓋整個倉庫或使用者目錄的破壞性命令。
求助前整理一份最小證據包
不要只發“壞了”或一張截掉錯誤的截圖。複製下面模板，只填寫與問題有關的部分：
現象：
期望結果：
作業系統與終端機：
Pi 版本（pi --version）：
Node 版本（node --version）：
當前目錄（pwd，可隱去私人上級路徑）：
實際啟動命令（刪除 Key 和 Token）：
第一條完整錯誤：
最小基線是否能啟動：
只啟用目標資源時的結果：
Provider 與模型名（不要提供憑據）：
Session 名稱或 ID（不要上傳整份私人 Session）：
已經發生的檔案或外部狀態變化：一份好的證據包能讓別人判斷問題屬於安裝、模型服務商、工作階段、上下文還是附加資源，也能避免讓你重複已經失敗且可能產生副作用的動作。
全域停止條件
出現以下任一情況，停止自動重試，先由人確認：
- 憑據、付款、額度或使用者帳戶權限不清楚；
- 刪除、覆蓋、釋出或對外傳送的最終狀態未知；
- 擴充功能或技能來源不明，卻要求執行程式碼或安裝依賴；
- 實際路徑離開任務目錄，或出現無法歸因的檔案變化；
- 相同請求持續計費、持續 429，或外部服務仍在處理；
- 修復方案要求清空認證、工作階段、整個設定目錄或整個倉庫；
- 你沒有辦法儲存當前錯誤、差異和恢復點。