MAINTENANCE PATH · 安裝後生命週期

安裝以後：更新、退出登入與解除安裝

Pi 已經能正常使用以後，你遲早會遇到這些問題：提示有新版本時要不要更新？換一個模型使用者帳戶是不是要重新安裝？解除安裝以後，舊工作階段和 API Key 還在不在？

它們不是同一個動作。更新改變程式版本；退出登入處理 Pi 儲存的認證；解除安裝只移除 pi 命令；本地工作階段、設定和包（Package）由你另外決定是否保留。

準備更新前，可以先到Pi 版本更新記錄輸入當前版本或目標版本，檢查新功能、Breaking Changes、遷移說明和已修復問題。版本檔案用於理解差異，實際更新仍按本頁的恢復點和驗收步驟進行。

先記住最容易誤判的一點

按照 Pi 官方當前說明，解除安裝 Pi 不會自動刪除 ~/.pi/agent/。這個目錄可能包含認證資訊、工作階段、設定和已安裝包。看到 pi: command not found，不能證明憑據和歷史記錄已經從電腦中消失。

本頁同時覆蓋藍皮書當前採用的官方安裝器和 npm 路線。更新 Pi 本體都可以先使用 pi update；解除安裝時必須回到自己原來的安裝方式。Windows 使用者看到“普通終端機”時，仍應開啟 Git Bash。

先判斷自己要完成哪件事

你的目標	應做的動作	不會自動發生的事
使用新版 Pi	pi update	不會順便更新所有包
只重新整理模型目錄	pi update --models	不會升級 Pi 本體
更新已安裝包	先 pi list，審查後用 pi update --extensions	不代表 Pi 本體已經更新
換使用者帳戶或移除 Pi 儲存的憑據	在 Pi 中使用 /logout	不會解除安裝程式或刪除工作階段
暫時不用 Pi，但想保留歷史	用原安裝方式解除安裝 Pi，保留 ~/.pi/agent/	不會自動清理本地資料
不再保留這臺電腦上的 Pi 資料	先退出登入和盤點，再單獨處理資料目錄	不能只靠解除安裝命令

不確定時，先停在“檢視版本和盤點”階段。檢查命令不會替你修改設定。

1. 更新前先留下恢復點

不要在 Pi 正在修改檔案、執行構建或等待模型回覆時更新。先讓當前任務結束，在 Pi 編輯區輸入 /quit，回到普通終端機。

如果當前目錄是 Git 倉庫，先用自己的正常流程確認重要修改已經提交或另有備份。Pi 的更新命令只負責 Pi，不會替你的專案建立恢復點。

記錄當前版本和已安裝包：

pi --version
pi list

把版本號記在臨時筆記中。pi list 展示的是使用者設定和當前專案設定中登記的包；它們可能包含能夠執行程式碼的擴充功能（Extension），所以後面不要未經檢查就全部更新。

再確認 Pi 的本地資料目錄是否存在，但不要列印其中的認證內容：

test -d ~/.pi/agent && echo "FOUND: Pi 本地資料目錄存在"
ls -la ~/.pi/agent

ls 只用於確認檔案和目錄名稱。不要執行 cat ~/.pi/agent/auth.json，不要把 auth.json 的內容放進截圖、聊天、工單或 Git 倉庫。

更新前驗收

• [ ] 當前 Pi 任務已經結束，我已回到普通終端機。
• [ ] 專案中的重要修改已有恢復點。
• [ ] 我記錄了更新前的 pi --version。
• [ ] 我看過 pi list，沒有把陌生包當成 Pi 本體。

2. 只更新 Pi 本體

普通更新使用：

pi update

官方當前說明，pi update 預設只更新 Pi 本體，與 pi update --self 的目標相同。它不會自動把所有已安裝包一起升級。

截至 Pi 1.1.0，更新時還要區分兩種結果：

• npm 全域安裝更新成功後會建議遷移到官方安裝器，因為 npm 路線不固定間接依賴；這條提示本身不是更新失敗。
• 官方安裝器管理的安裝，更新後只保留新版本和本次更新前的版本。它不代替專案備份，也不適用於 npm 等其他安裝方式。

從 1.0.2 或更早版本升級且使用 Azure 時，提供商名稱已從 azure-openai-responses 改為 azure。需要重新 /login，並核對自定義模型和設定中的舊名稱；設定欄位及舊工作階段快取的影響見Pi 1.1.0 更新要點。不用 Azure 時無需處理。

命令結束、普通終端機重新出現輸入行後，檢查：

pi --version

新版本號可能變化，也可能已經是最新版而保持不變。不要只根據“出現了很多下載文字”判斷成功；最終要看更新命令沒有錯誤、pi --version 仍可執行。

然後從獨立練習目錄啟動 Pi，完成一次最小連通測試：

cd ~/Downloads/pi-practice
pi

Windows Git Bash 把目錄換成 ~/pi-practice。進入 Pi 後提交：

只回復“更新後連接正常”。不要讀取、建立、修改檔案，也不要執行命令。

能收到準確回覆，說明當前認證和模型呼叫也能工作。測試失敗時先保留完整錯誤和更新前後的版本號，不要緊接著重灌、清空設定和更換模型服務商（Provider）；一次只排查一個變數。

--force 不是日常更新按鈕

pi update --self --force 會在已經是最新版時仍嘗試重新安裝，適合明確的修復場景，不是普通更新的必經步驟。官方還說明，安裝器管理模式不支援 --force；這種安裝應重新執行對應安裝器進行修復。

3. 分清 Pi、模型目錄和包的更新

Pi 當前提供這些不同範圍：

命令	實際範圍	什麼時候使用
pi update	只更新 Pi	日常升級本體
pi update --self	只更新 Pi	需要明確寫出範圍時
pi update --models	只重新整理模型目錄	模型服務商已支援新模型，但本地選擇器還沒有時
pi update --extensions	更新已安裝包，並核對固定的 Git 引用	已逐項確認包來源和變更時
pi update --all	更新 Pi 和包	已看過 pi list，並準備一起驗收時

包可以包含擴充功能、技能（Skill）、Prompt Template 和主題。其中擴充功能能以當前使用者權限執行程式碼，技能也可能引導模型執行操作。更新第三方包前，先確認來源、當前版本、更新內容和回退辦法。

初學者的預設順序應當是：

1. 先執行 pi update，驗證 Pi 本體。
2. 需要新模型目錄時，單獨執行 pi update --models。
3. 只有確實需要時，檢視 pi list 後逐項處理包。
4. 不把 pi update --all 當成看見更新提示後的第一反應。

4. 換使用者帳戶或退出登入

如果只是要換模型使用者帳戶，不需要解除安裝 Pi。進入 Pi，在底部編輯區輸入：

/logout

按介面選擇要清除的模型服務商憑據。完成後可以用 /login 登入另一個使用者帳戶，再用 /model 選擇可用模型。

Pi 官方說明，使用 /login 儲存的令牌或 API Key 位於 ~/.pi/agent/auth.json，/logout 用於清除憑據。不要直接開啟這個檔案複製或手工刪改某一段 JSON；手工改壞格式會同時影響其他模型服務商。

環境變數是另一條憑據來源

如果你曾在 Shell 設定、系統環境或啟動指令碼中設定 API Key，/logout 不會替你修改那些外部設定。Pi 當前的憑據解析順序包括命令行引數、auth.json、環境變數和自定義模型服務商設定。退出後仍然能呼叫某個模型服務商，不一定是 /logout 失效，也可能是外部環境仍提供了憑據。

不要用 echo $OPENAI_API_KEY 一類命令檢查，這會把真實金鑰列印在螢幕和日誌中。只檢查變數名稱和它來自哪個設定位置；需要撤銷時到對應服務商後台撤銷舊 Key。

如果電腦丟失、使用者帳戶異常或金鑰可能洩露，僅刪除本地檔案不夠。應當在服務商後台撤銷令牌或 API Key，再生成新的憑據。

退出登入驗收

• /logout 已針對正確模型服務商完成。
• 我沒有把 auth.json 或金鑰內容列印出來。
• 如果要換使用者帳戶，重新 /login 後已用一次真實回覆驗證。
• 如果舊憑據可能洩露，我已在服務商後台撤銷，而不只是清理本地檔案。

5. 按原安裝方式解除安裝 Pi，但保留設定和工作階段

先用 /quit 退出 Pi，再回到普通終端機。先根據安裝時的記錄選擇一條解除安裝路線，不確定時不要把兩條命令都執行一遍。

如果透過官方安裝器安裝，重新執行同一個官方入口，並在選單中選擇解除安裝：

curl -fsSL https://pi.dev/install.sh | sh

執行前再次確認網域是 pi.dev。安裝器會檢查當前安裝並提供對應動作；閱讀選單後只選擇解除安裝。

如果透過 npm 全域安裝，使用同一個包管理器解除安裝：

npm uninstall -g @earendil-works/pi-coding-agent

命令結束後檢查 pi 是否仍能被找到：

if command -v pi >/dev/null 2>&1; then
  echo "CHECK: 仍然找到了 pi，請確認安裝方式"
else
  echo "PASS: pi 命令已經移除"
fi

如果仍然找到 pi，不要繼續刪除目錄。先執行 command -v pi，確認它是否來自另一個 Node.js 版本、另一個包管理器或舊安裝位置。

透過任一路線解除安裝後，~/.pi/agent/ 預設仍然保留。以後重新安裝時，原有設定和工作階段通常仍可繼續使用；重新安裝後仍要執行 pi --version，並用 /resume 實際確認需要的工作階段是否存在。

如果 Pi 是透過 pnpm、Yarn 或 Bun 安裝的，應使用同一個包管理器移除。不要為了“解除安裝乾淨”把四種命令全部執行一遍。

6. 決定本地資料保留到什麼程度

解除安裝程式後，再單獨決定這些內容：

位置	可能包含什麼	常見決定
~/.pi/agent/auth.json	OAuth 令牌或 API Key	先用 /logout 處理；不要放入普通備份包
~/.pi/agent/sessions/	按工作目錄儲存的工作階段	需要續寫或留檔時保留
~/.pi/agent/settings.json	預設模型、主題、包等使用者設定	準備重灌時通常保留
~/.pi/agent/npm/、git/	使用者級 Pi 包檔案	不再使用相關包時才處理
~/.pi/agent/models-store.json	模型目錄快取	可重新整理，不等同於認證憑據
專案中的 .pi/	專案設定、資源或本地包	屬於專案範圍，不會因全域解除安裝自動消失

第一次清理時，不提供一條 rm -rf ~/.pi/agent 讓你整目錄刪除。更安全的順序是：

1. 在 Pi 中逐個 /logout，確認不再需要本地儲存的認證。
2. 用 pi list 和 ls -la ~/.pi/agent 盤點名稱，不讀取憑據正文。
3. 單獨備份確實需要的 sessions/ 和設定說明；不要把 auth.json 放進未加密壓縮包、網盤共享或 Git。
4. 使用作業系統的廢紙簍或回收站處理不再需要的 Pi 資料，以便發現誤刪時仍有恢復機會。
5. 最後檢查專案目錄中的 .pi/；全域目錄與專案資源是兩個不同範圍。

如果你的目標只是“恢復到接近新安裝狀態”，也應先把原目錄改名並確認新環境可用，而不是直接永久刪除。這個動作會讓 Pi 暫時看不到舊設定、認證和工作階段；只有在你已經完成盤點和備份時才進行。

7. 完成一次完整生命週期驗收

根據你實際做的動作逐項檢查，不需要為了完成本課真的解除安裝正在使用的 Pi。

• 只更新： 更新前後版本均有記錄，pi --version 可用，並收到一次最小真實回覆。
• 更新包： 先檢查 pi list，更新後重新驗證相關擴充功能、技能或主題，而不是隻看命令成功。
• 退出登入： 正確模型服務商已退出，沒有列印金鑰；換使用者帳戶後完成真實呼叫。
• 只解除安裝程式： command -v pi 不再找到命令，同時明確知道 ~/.pi/agent/ 是否保留。
• 準備清理資料： 已區分認證、工作階段、設定、包和專案 .pi/，先備份或移入回收站，不執行不透明的整目錄刪除命令。

更新、退出登入、解除安裝、刪除資料是四個獨立決定。每完成一個動作，就用與它對應的證據驗收。

繼續第 5 課，完成第一次真實任務 →

本頁依據

• Pi Quickstart：安裝與解除安裝
• Pi 包：更新範圍與包管理
• Pi 模型服務商：登入、退出與憑據位置
• Pi 工作階段（Session）：工作階段儲存位置
• Pi Settings：設定與更新檢查

官方安裝器、登入退出及儲存位置仍保留 2026-09-23 的核驗記錄。2026-10-12 在獨立 npm 字首中實測 pi list、從 1.0.0 更新到 1.1.0、1.1.0 的 npm 遷移提示、pi update --models 和 npm 解除安裝；測試副本已移除，獨立設定目錄仍在，系統原有安裝未改動。託管安裝的舊版本清理與 Azure 改名僅對照固定版本 Changelog核對，未實測託管更新或 Azure 使用者帳戶。實際使用時仍以對應官方文件和本機 pi --help 為準。