【2026 最新】PI-Desktop 教學：安全匯入 Claude Code／Codex Session，Agent、Plan、Goal 怎麼選？

你可能已經在 Claude Code 或 Codex 累積了一長串對話：需求怎麼拆、哪個指令失敗、最後改了哪些檔案，全都散在終端機裡。PI-Desktop 教學最吸引人的承諾，是把這些 Session 放進一個本機 Agent 桌面，讓專案、對話、Review 與模型切換集中在同一個視窗。

但「能匯入」不等於「可以放心搬家」。截至 2026 年 9 月 11 日，v0.14.6 專案 README 仍標示 Early Preview；macOS 的一般 tagged release 預設未簽署，而 Session 匯入器會直接讀取你家目錄裡的 Claude Code／Codex 紀錄。真正安全的第一步，不是把全部歷史搬進去，而是先確認 repo、驗證下載檔，再用完全沒有秘密的測試 Session 做一次可回滾演練。

這篇專為第一次碰本機 coding agent 的讀者寫。你不需要先懂 Electron、JSONL 或 Rust；跟著做完後，會知道匯入保留了什麼、Agent／Plan／Goal 差在哪、哪些權限真的被擋住，以及如何用 VM 或專用測試帳號完成可驗證回滾。

PI-Desktop 教學先說結論：匯入是副本，不是接手原 Agent

• 先認 repo：本文只談 vastsa/PI-Desktop；不要只看專案名稱或搜尋結果，也不要從「PI」推論其他專案或品牌的背書關係。
• 匯入＝一次性轉換副本：v0.14.6 把可辨識的 user、assistant 與 tool 紀錄轉成 PI-Desktop Session；同一來源重匯會被跳過，不會同步後續變更，也不是原 Claude Code／Codex runtime 的完整快照。
• 模式≠權限：Plan 先核准計畫，Goal 先核准成果與驗收條件；兩者都不能取代 Write、Edit、Bash 與外掛權限判斷。
• macOS 要先停看聽：AlphaLab 下載並核對的 v0.14.6 Apple Silicon ZIP 雜湊吻合 GitHub API，但其 App 是 ad-hoc 簽章，Gatekeeper 評估未通過。本篇不教你繞過系統保護。
• 正式資料先不要進場：先在隔離帳號或虛擬機建立一筆假資料 Session；直到匯入、拒絕權限、刪除與還原都可預期，再考慮日常 repo。

記住這條公式：安全搬家＝可信來源 × 可丟測試資料 × 最小權限 × 可驗證回滾。四項像門鎖的四個轉輪，任何一項是零，整扇門就不該打開。

PI-Desktop 是什麼？先把「桌面」與「模型」分開

本文核對的產品，是由 GitHub 帳號 vastsa 維護的開源 local-first coding-agent 工作台。它把專案、Session、檔案檢視、差異 Review、模型設定、Skills、MCP、Subagents 與 Plugins 放在桌面介面；真正回答問題的模型，仍來自你設定的 Anthropic、OpenAI、本機模型或相容 API。

同名專案不只一個，所以本文把身分鎖在 owner vastsa、repo PI-Desktop、tag v0.14.6 與該 release 資產；這個識別範圍不替它認證與其他 Pi 專案、Anthropic、OpenAI 或 Pi Network 的組織關係。

白話比喻是：Claude／GPT 像廚師，PI-Desktop 像有砧板、刀具、採購單與出餐關卡的廚房。廚房可以把工作流程整理得更清楚，卻不會自動讓食材可信，也不會替你決定哪些刀可以交出去。若你還分不清 Model 與 Harness，可先讀 AI Agent Harness 是什麼。

專案所說的 local-first 也不是「完全離線」：對話與設定在本機，但使用遠端模型時，必要上下文會直接送往你設定的 provider。這個邊界在v0.14.6 README寫得很清楚，所以本文把「匯入歷史」與「之後送模型」分成兩個不同風險。

PI-Desktop 教學 Step 1：先驗證 repo、Release 與 checksum

痛點：同名專案多，GitHub Release 也可能同時有 DMG、ZIP、blockmap 與不同架構。解法：把 owner、tag、檔名與 digest 一起鎖住。以下是本文在 2026 年 9 月 11 日核對的 macOS Apple Silicon 範例；版本更新時，三個值要一起換，不能只改檔名。

下列方式需要先安裝並登入 GitHub CLI；先跑 gh --version 與 gh auth status，任一失敗就先停下，不要把搜尋到的同名下載站當替代來源。

REPO="vastsa/PI-Desktop"
TAG="v0.14.6"
ASSET="PI-Desktop-0.14.6-arm64-mac.zip"

gh release download "$TAG" --repo "$REPO" --pattern "$ASSET"
gh api "repos/$REPO/releases/tags/$TAG" \
  --jq ".assets[] | select(.name==\"$ASSET\") | .digest"
shasum -a 256 "$ASSET"

這次 GitHub API 回傳 sha256:d1e03824fce489fb9e74dcc6c5ccdd783ef1bfe549d8b5d39d6124fcaf44a290，本機 shasum 得到相同 64 碼。這只證明下載位元組與該 GitHub 資產一致，不證明程式安全，也不補上作者簽章。

接著只解壓縮做靜態簽章檢查，不啟動 App：

UNPACK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pi-desktop-unpack.XXXXXX")"
ditto -x -k "$ASSET" "$UNPACK_DIR"
codesign -dv --verbose=4 "$UNPACK_DIR/PI-Desktop.app"
spctl --assess --type execute -vv "$UNPACK_DIR/PI-Desktop.app"

AlphaLab 保留的 v0.14.6 檢查結果是 Signature=adhoc、沒有 TeamIdentifier；spctl --assess 非零結束，回報 code has no resources but signature indicates they must be present。這和專案macOS 說明所寫「tagged-release 預設未簽署」一致。repo 另附開啟 helper，但若你的目標是安全評估，合理分支是等待簽署／公證 build，或在可丟棄的虛擬機從已審閱 source 建置；自行建置也不等於替託管資產補上 provenance，不要把移除 quarantine 當成驗證。

Step 2：先造一筆「沒有秘密」的 Claude Code／Codex Session

PI-Desktop v0.14.6 的 Claude 匯入器固定掃描 ~/.claude/projects/*/*.jsonl，Codex 匯入器則只往 ~/.codex/sessions 找 JSONL；它不跟隨 Claude 的 CLAUDE_CONFIG_DIR 或 Codex 的 CODEX_HOME 改址，也不涵蓋預設目錄外的封存或其他格式。這代表「我只選一筆」是匯入 UI 的篩選，不是把同一預設目錄裡的其他歷史對 App 隱形；掃描清單沒出現某筆，也不能反推原工具沒有那段歷史。

若用遠端模型建立測試 Session，「沒有秘密」不能只靠 prompt 保證：請用專門測試、可撤銷的身分，先建立對話並完成一次原生 resume 驗收，再撤銷／登出，之後才啟動 PI-Desktop；不要登入主帳號，也不要留下仍有效的正式 API key。Codex 的本機 --oss 路線可不經遠端模型；若無法隔離 credential，就停在靜態下載與簽章檢查。

在隔離環境建立最小 repo，內容只放假資料：

mkdir -p "$HOME/pi-desktop-lab"
cd "$HOME/pi-desktop-lab"
git init
printf "alpha\nbeta\n" > sample.txt
git add sample.txt
git -c user.name="PI Lab" -c user.email="pi-lab@example.invalid" \
  commit -m "add disposable sample"

然後在 Claude Code 或 Codex 開一個新 Session，只送這段：

只讀取 sample.txt，回覆行數與識別字串 PI-IMPORT-TEST-2026；不要建立、修改或刪除任何檔案。除本次模型 API 對話外，不要透過 Browser、Bash、MCP 或其他工具發出網路請求。

收到任何超出讀取範圍的工具要求就拒絕，結束後再用原工具確認能原生續接：Claude Code 可用 claude --resume，而且 resume 接受 Session ID、名稱或絕對 JSONL 路徑；Codex 可用 codex resume。Claude 的 /export產生供人閱讀的純文字；原生續接則以 Session 紀錄為準。完成這次 resume 後，撤銷遠端測試憑證，記下所選來源 JSONL 的絕對路徑，執行 shasum -a 256 "/absolute/path/to/session.jsonl" 保存基準值，之後才進 PI-Desktop。

PI-Desktop 教學 Step 3：掃描後只匯入一筆

進入 Settings → Import（簡中介面為「设置 → 导入」），在上方的 Session 匯入卡按 Scan；不要操作下方另一張 Model configuration 匯入卡，後者會另外掃描 provider 設定，並可能複製 API key。Session 候選清單會顯示來源、標題、訊息數與日期，而且 v0.14.6 掃描後預設未勾選任何項目；找出含有 PI-IMPORT-TEST-2026 的測試對話，只勾這一筆。

如果候選清單是空的，先回頭檢查上述預設路徑與檔案副檔名；v0.14.6 總掃描器會把單一來源的 importer error 收斂成空結果，未必留下能直接定位原因的提示，所以「零候選」也可能是路徑、格式或解析失敗。匯入後先維持 VM／OS 層斷網再打開對話，因為專案安全規格明載 assistant Markdown 裡的遠端圖片、音訊或影片可在 render 時自動抓取。

這一步最容易被「搬家」兩個字誤導。從 v0.14.6 的 Claude importer 與 Codex importer可確認：它讀取來源紀錄、轉換支援的 message／tool 內容，再以 import-<source>-<externalId> 建立新的 PI Session。這個 deterministic ID 也讓同一來源重匯成為 skipped／no-op；原 Session 後來新增的內容不會合併或刷新。匯入後預設模式是 Agent、providerId 為空；Claude 來源中可辨識的模型名稱可能被寫進 modelId，Codex 匯入的 modelId 則為空，兩者都沒有自動恢復可執行的 provider／model 配對。

驗收時逐項看：使用者訊息是否完整、assistant 回覆順序是否正確、tool call 與結果是否能辨識、專案路徑是否仍存在。不要用「對話打得開」推論思考區塊、子 Agent、附件、壓縮摘要、MCP 狀態或中斷中的工具都已完整保留；Claude 文件明說 transcript entry 是會隨版本改變的內部格式，而 PI 的 Codex parser 只轉換它列出的 message、function call 與 output 類型。尤其 v0.14.6 的 Codex importer 沒有錯誤狀態對映，匯入的 function output 一律標成 success，因此不能把綠色狀態當成原任務成功的稽核證據。

Agent、Plan、Goal 怎麼選？先看你要批准什麼

Agent是直接開始工作；Plan先研究，再把不可變的實作計畫交給你批准；Goal先鎖定成果與驗收條件，路線交給 Agent 決定。最簡單的選法是：小改動用 Agent、路線敏感用 Plan、結果明確但過程可彈性用 Goal。

關鍵陷阱是把 Plan／Goal 當成完整唯讀。依 v0.14.6 的工具權限規格，兩種 contract mode 在批准前會硬擋 Write／Edit，但 Bash 仍依全域權限模式處理：Ask／Accept edits 會詢問，Auto 可能直接放行。這裡的 BrowserPreview 只是本機 HTML 預覽，不是一般網頁瀏覽器；Bash 子程序則以目前 OS 使用者權限執行，沒有 OS filesystem sandbox。Ask 是執行前的決策閘門，不是放行後的 containment，所以「Write 被擋」不等於 repo 不會變。

Step 4（選做）：逐項拒絕檔案、Shell、網路與外掛

只驗收匯入的讀者可以停在 Step 3：PI 不需要 provider，測試 VM 繼續斷網。要讓 Agent 真的產生 Write／Bash 權限卡，則必須另接同一隔離環境裡的本機模型，或使用可撤銷的遠端測試 provider；後者會把 prompt 與必要上下文送出，不能再稱為離線測試。無法接受這個邊界，就跳過 Step 4。

Agent／Plan 可先把 composer 左下權限模式設為「每次詢問／Ask」。Goal 在 v0.14.6 的 composer permission chip 會固定顯示 Auto 並停用；批准 Goal 時，才從 approval bar 選 Ask／Accept edits／Auto，因此要在那裡明確選 Ask。接著在同一個假 repo 做四個觀察；每次都記下工具名稱、參數預覽、理由與 workspace，再按 Deny。

1. 檔案：要求「建立 write-probe.txt」，在 Write／Edit 卡片按拒絕；回到外部終端執行 git status --short，應看不到新檔。
2. Shell：要求「用 Bash 執行 pwd」，即使這個指令本身只讀，也按拒絕，確認 UI 明確顯示 denied，而不是默默成功。v0.14.6 permission card 的逾時為 120 秒，逾時也應走拒絕。
3. 網路：v0.14.6 文件把模型請求、一般 Browser、Bash 發出的網路與 plugin 的 net.fetch 分成不同通道；公開 permission matrix 列出的不是一個跨通道「Network」總開關。若用 VM 內本機模型，維持 OS 層出站封鎖；若用遠端測試 provider，就只在接受其資料邊界時短暫開通，結束後立即撤銷測試憑證。
4. 外掛：本次練習完全不要安裝 Marketplace Plugin、MCP 或 pi extension。專案自己的程式碼稽核指出，Plugin main code 是目前 OS 使用者權限下的 Node 程式，可透過 Node built-ins 繞過 PI host API 的檔案／網路權限；manifest 只描述宣告能力，不能證明實際行為被框住，套件雜湊也不是 publisher signature。

最後把同一個「不改檔」要求分別開成三個新 Session：Agent 觀察工具卡；Plan 確認 Write／Edit 被硬擋，但 Read／Glob／Grep／本機 BrowserPreview 與 Bash 仍在可用集合，遇到任何 Bash 卡都按拒絕，再確認只留下 plan artifact；Goal 則把「git status --short 無變更」寫進 acceptance criteria，批准時在 approval bar 選 Ask。不要拿匯入後那一筆對話直接做三模式比較，因為 importer 先以 Agent 建立副本；三個乾淨 Session 比較才不會混入舊狀態。

Step 5：封存 host data、刪除 Session 與 VM 級回滾

PI-Desktop 的 durable host data 預設放在 ~/.pi-desktop/，也可由 PI_DESKTOP_DATA_DIR 改址；內容包含 SQLite index、sessions/*.jsonl、attachments、logs、plugins、review snapshots 與 secrets。v0.14.6 沒有提供受支援的整機 backup／restore 或 Session export 流程；以下只是依預設路徑與儲存規格推導的 host-data snapshot，不是受支援的還原契約。先撤銷選做權限測試用的遠端憑證、完全退出 App；只有在 home 所在測試磁碟已加密且不會同步雲端時才執行，否則直接使用 VM snapshot。

umask 077
BACKUP_DIR="$HOME/pi-desktop-lab-backup"
mkdir -p "$BACKUP_DIR"
chmod 700 "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/pi-desktop-host-data-v0.14.6.tgz" \
  -C "$HOME" .pi-desktop
shasum -a 256 "$BACKUP_DIR/pi-desktop-host-data-v0.14.6.tgz"

這裡有一個不能略過的版本風險：v0.14.6 README 把 API credentials 描述成存於 OS keychain，但同一 tag 的資料規格與實際 secrets.rs顯示，出貨中的 backend 是 AES-256-GCM 檔案，machine key 就放在同一個 secrets/ 目錄。拿到整包資料的人也拿到解密材料；shasum 只驗完整性，不提供機密性。兩份第一方說明互相衝突時，本篇採較保守、且與程式碼一致的做法：不輸入正式 API key，封存檔只留在加密且不同步雲端的測試磁碟，並視同敏感明文保護。

如果只是暫時不想看到測試 Session，先用 Archive；若確定要清掉匯入副本，再打開側邊欄 Session 選單選 Delete。v0.14.6 的刪除是沒有確認視窗的 immediate hard delete，會移除該 Session 的資料庫紀錄、transcript、revision、inflight checkpoint、scratch 與 review snapshot；但共用 logs、其他 Session 與 App 資料是分開的，所以它不是整個 App 的抹除鍵。刪除後重新計算先前記錄的來源 JSONL 雜湊；若還要測 native resume，請只重新驗證那個已隔離的測試身分。

若要撤回 host data 測試，先退出 PI-Desktop，建立一個不會碰撞的新隔離路徑，確認它不存在後才移動資料目錄；再從 Finder 把 App 移到垃圾桶：

QUARANTINE="$HOME/pi-desktop-lab-backup/pi-desktop-quarantine-$(date +%Y%m%d-%H%M%S)"
if [ -e "$QUARANTINE" ]; then
  printf 'stop: destination exists: %s\n' "$QUARANTINE" >&2
else
  mv "$HOME/.pi-desktop" "$QUARANTINE"
  printf 'quarantine: %s\n' "$QUARANTINE"
fi

重新開啟時若產生全新的空資料目錄，表示 durable host data 邊界如預期。手動回復只應在同一個 PI-Desktop 版本、App 完全停止時進行：先移開新目錄，再把剛才印出的 quarantine 路徑改回 .pi-desktop；不要假設舊資料可安全降版。這仍不保證清掉 Electron 另存的視窗、瀏覽器或快取狀態。要完成整次隔離測試的可驗證回滾，虛擬機直接還原快照；專用 OS 測試帳號則在確認封存不再需要後刪除帳號。

什麼時候才適合搬進日常 repo？

符合以下條件再小範圍採用：下載來源與 digest 可重現；macOS 使用通過簽署／公證的 build，或你能審閱並自行建置；小型假 Session 的訊息與 tool 紀錄符合預期，再以另一筆去敏感、大小接近日常工作的副本驗收。這一步不是形式檢查：issue #211記錄過 v0.14.6 在 Windows 處理一筆 7,407 則訊息、約 82 MB transcript 的極端個案時，重試出現 130 秒逾時與 UI／host 狀態分歧；它不代表一般 Session 都會失敗，卻提醒你別只拿小檔案推論日常負載。接著確認 Ask 模式下每張權限卡都能看懂；刪除與 VM 還原都演練成功；provider credential 的實際儲存方式也已重新核對。

反過來，只要你必須立刻開 Auto、要裝來源不明的 Plugin、repo 含正式憑證／客戶資料，或公司要求可稽核的簽章供應鏈，就先停在隔離環境。v0.14.6 README 的 Project status把 macOS release qualification、installer rollback、session recovery、plugin sandbox 與 publisher verification 明列為 current priorities；Early Preview 最適合用來評估工作流，不適合靠期待補齊控制。

PI-Desktop 常見問題 FAQ

1. 匯入後能無縫接著跑原本任務嗎？

不應這樣理解。v0.14.6 建立的是一次性轉換 Session；來源模型名稱可能被辨識，但可執行的 provider／model 配對、原 Agent process、sandbox 與權限決策不會由舊文字紀錄自動恢復，同來源重匯也只會跳過，不會同步更新。先把它當可搜尋的對話快照。

2. 匯入副本如何跟原 Session 分辨？

看新的 PI Session ID 與資料目錄。v0.14.6 會讀取來源 JSONL，再以 import-<source>-<externalId> 寫進 PI 自己的資料區；刪除 PI 副本後，以匯入前後的來源 JSONL SHA-256 比對是否一致，需再續接時才重新驗證測試身分。

3. Plan 模式就是唯讀嗎？

不是。批准前 Write／Edit 會被擋，但 Bash 仍由 Ask／Accept edits／Auto 決定；Auto 下 shell 可能改檔。

4. 只看匯入結果，需要先填 API key 嗎？

不用先填。掃描與轉換本機紀錄本身不需要模型回答；先離線檢查歷史、標題與工具紀錄，再決定是否配置 provider。

5. checksum 一致就可以放心開啟嗎？

不行。它只回答「檔案是否等於 GitHub 上那個資產」，沒有回答作者身分、簽章、程式行為或依賴是否安全。

6. macOS 顯示 damaged，可以直接跑 repo 內的 helper 嗎？

安全評估時不要急著跑。v0.14.6 helper只檢查 Applications 內兩個路徑與 bundle ID、移除 com.apple.quarantine，再開啟 App；它不會加入 Developer ID 簽章或公證。先等待專案提供可驗證的簽署／公證資產，或在可丟棄環境完成 source review。

7. 我把 Session 刪掉，敏感資料就全沒了嗎？

不能把它當完整抹除。單一 Session delete 處理該對話的資料庫紀錄與相關檔案，但 App 還有共用 logs、plugins、其他 host data 與可能的 Electron 狀態；完整撤回要還原測試 VM，或移除專用 OS 測試帳號。

8. Claude Code、Codex 自己也有匯入或續接功能嗎？

有原生續接，而且 Codex 另有 OpenAI 文件化的 migration／App Server 路線。Claude 提供 resume 與可讀文字 export；Codex 提供 resume，而 /import是把 Claude Code／Cursor 的近 30 日 chat 匯進 Codex，最多 50 筆，且執行中、remote 或 App Server 連線時不可用。OpenAI 也公開供第三方整合的 App Server；這些都不代表 PI-Desktop v0.14.6 已採用相同路線。

給新手的 7 個重點

• 只認 vastsa/PI-Desktop，版本、檔名與 digest 一起核對。
• macOS 簽章不過就停，不把移除 quarantine 當安裝驗證。
• 在沒有舊資料的帳號或 VM 造一筆假 Session。
• 只掃描上方 Session 卡，維持預設未選狀態，再勾識別字串一筆。
• 把 importer 當一次性格式轉換，不當同步或 runtime 搬家。
• Agent／Plan／Goal 先限制工具集合與批准關卡；Ask／Accept edits／Auto 再決定被允許工具是否詢問。
• 在碰正式 repo 前，先演練 host-data snapshot、Deny、Delete 與 VM Restore。