Pi Agent Desktop 使用指南

下載安裝

開啟 下載頁面，網站會優先推薦當前系統對應的安裝包。v0.4.1 桌面安裝包已經內建 Pi Coding Agent 1.2.0 與 Herdr v0.8.2，日常使用不需要另外安裝 Pi CLI。

安装于 macOS

1. 根據晶片型別下載 Apple Silicon 或 Intel 版本的 DMG。
2. 開啟 DMG，把 Pi Agent Desktop 拖到“應用程式”資料夾。
3. 從“應用程式”開啟。正式釋出包已經簽名並透過 Apple 公證。

安装于 Windows

1. 下載 Windows x64 未簽名 Beta 安裝程式並執行。
2. 按安裝嚮導完成安裝。
3. 當前安裝包尚未配置程式碼簽名；如果 SmartScreen 顯示“未知釋出者”，確認檔案來自專案的 GitHub Releases後，選擇“更多資訊 → 仍要執行”。

安装于 Linux

1. 下載 Linux x64 AppImage。
2. 在檔案屬性中允許“作為程式執行”，或執行 chmod +x Pi-Agent-Desktop-*.AppImage.
3. 開啟 AppImage。Linux 版本當前使用手動更新。

認識主介面

開始第一條會話

1. 在左側選擇專案目錄。
2. 點選“新建會話”。
3. 確認輸入框下方已經選擇可用模型。
4. 描述你的目標，例如“介紹這個專案”或“幫我查詢登入頁面”。

如果只是聊天或處理臨時任務，也可以選擇一個空目錄。只有在你明確授權工具後，Agent 才能讀取或修改相應專案檔案。

自動命名與回到最新訊息

新會話傳送首條有效訊息後，應用會用當前模型在後臺生成不超過 40 個字元的簡短標題，並實時更新側邊欄。標題生成不會進入會話歷史或阻塞正常回復；模型不可用時會使用訊息開頭作為本地兜底。

• 在“設定 → 通用 → 會話”中關閉或重新開啟“自動命名新會話”。
• 手動設定的名稱始終優先，自動標題不會覆蓋手動重新命名。
• 斜槓命令、空白、單字元和純圖片訊息不會觸發自動命名。
• 向上瀏覽舊訊息後，點選右下角“滾動到底部”按鈕即可回到最新內容並恢復流式輸出自動跟隨。

切換介面語言

開啟設定→通用→介面語言

可以選擇 English、簡體中文或繁體中文。臺灣、香港、澳門及 zh-Hant 系統語言會預設使用繁體中文，並優先保留你已選擇的語言。原生對話方塊、檔案右鍵選單、瀏覽器確認提示、托盤與應用選單都會同步切換。

調整聊天字號、對話寬度與模型回覆寬度

開啟設定→通用→會話

• 聊天字號提供小、標準、大、特大四檔，修改會立即應用，並在重啟後保留。
• 舒適寬度保持 760px；擴充套件寬度會隨視窗自適應，最大為 960px。
• “模型回覆寬度”單獨控制回覆氣泡：舒適寬度保持原有閱讀寬度；“填滿對話列”讓段落、表格和程式碼塊使用當前聊天列的完整空間。
• 模型回覆寬度與外層對話寬度相互獨立；開啟右側面板後，填滿模式會隨可用空間收縮。
• 訊息、過程詳情和輸入框使用統一內容邊界，在寬屏和最小視窗下也能保持對齊。

設定提示快取預熱

“提示快取預熱”提供關閉、“長時間執行工具時”和“空閒時也預熱”三種模式。它可以在長工具呼叫或空閒期間保持模型提示快取活躍，但可能消耗模型用量；該設定與 Pi CLI 共享。若部分執行中的會話未能立即更新，重新開啟這些會話即可。

傳送附件與操作本地檔案連結

• 透過拖放、貼上或輸入框旁的附件按鈕新增圖片或任意檔案；非圖片附件顯示為檔案卡片。
• 大尺寸截圖和 Retina PNG 會在進入草稿前按最長邊 2048 畫素、目標約 512 KiB 自動縮放並轉為 JPEG，常見截圖可以儲存到草稿並在重啟後恢復。
• 支援只傳送附件；Agent 正在流式回覆時，帶附件的訊息也可以加入 Steer / Follow-up 佇列。
• 傳送失敗時，附件和文字會合並回當前草稿，不會覆蓋傳送期間繼續輸入的新內容。
• Markdown 訊息會識別 Windows、POSIX 和 UNC 本地路徑；倉庫內相對路徑在應用內開啟，絕對路徑可在系統檔案管理器中定位。
• 右鍵點選本地檔案連結，可以開啟檔案、選擇預設應用或“開啟方式”、另存為、複製路徑、複製文字內容，或在資料夾中顯示。
• 輸入 @ 引用專案檔案時，應用會按需瀏覽並搜尋最多 300 個候選；在使用者主目錄中預設隱藏 AppData 或 Library ，顯式輸入目錄名稱後仍可訪問。
• 檔案搜尋工具不可用、超時或失敗時，介面會顯示降級狀態並保留當前目錄候選，不會卡住輸入或靜默返回不完整結果。

使用內建瀏覽器

開啟主介面右側→瀏覽器

內建瀏覽器使用真實 Chromium 頁面。你和 Agent 操作同一個頁面，可以保留標籤頁、Profile 與登入狀態，並在需要時隨時接管。

管理瀏覽器許可權

在“設定 → 瀏覽器”中管理全域性預設和具體會話的永久許可權。授權彈窗產生的許可只對當前會話臨時生效；不再需要時，可以隨時撤銷。

高階瀏覽器模式

高階模式提供可信輸入、網路檢查、JavaScript 經驗庫和確認後的寫請求重放，並使用專用 Profile。這個開關只在本次應用啟動期間有效，Agent 工具不會接收或返回 Cookie 值。

使用 Herdr Agent 艦隊

開啟設定→Herdr

Pi Agent Desktop 透過 Herdr v0.8.2 / protocol 20 管理本機 Agent 艦隊。Pi 可以在原主對話中使用 herdr_* 工具；標題欄顯示 Fleet 狀態，右側 Herdr 終端用於觀察、排查和顯式接管。

準備 Herdr 執行時

1. 在 macOS、Linux 或 Windows x64 開啟“設定 → 開發工具”，找到 Herdr。應用已經內建經過完整性校驗的 v0.8.2，可直接安裝、更新、修復或解除安裝私有執行時，無需另行聯網下載。
2. 開啟“設定 → Herdr”並啟用整合，然後選擇 Attach 或 Managed 模式、填寫 Herdr Session 名稱並按需開啟自動連線。
3. Attach 連線由你手動啟動的系統 Herdr，Pi Desktop 不會停止它；Managed 會自動啟動、監控、有限重啟並管理 Pi Desktop 的私有 server。
4. Managed 在禁用 Herdr、切換模式、解除安裝執行時或退出應用時關閉私有 server；它不會接管或終止外部 Herdr。

從主對話管理 Agent

• 24 個 herdr_* 工具覆蓋 Fleet 查詢、workspace / tab / pane 建立與管理、Agent 啟動與提示、等待、按鍵、狀態解釋、程序診斷和輸出等待。
• 標題欄右側按 workspace、tab、pane 和 Agent 層級展示空閒、執行中、已阻塞、已完成或未知狀態；初始頁和啟用會話使用同一列表。
• 可啟動 pi、 claude、 codex、 gemini、 omp、 opencode、 copilot、 kimi、 droid、 grok、 qwen和 agy.
• Managed 模式會在固定 allowlist 目錄中發現常見 Agent CLI，並只把允許的 Agent command 加入 launcher overlay；不會執行登入 shell、讀取 shell profile、聯網安裝或遞迴掃描使用者目錄。
• missing-locally 僅表示 Desktop 未在支援的本機目錄中找到該 CLI。在 Attach 模式下，外部 Herdr Session 回傳的啟動結果仍是準確資訊。
• Pi Session 與 Herdr Session 相互獨立；Herdr prompt 不會寫入 Pi 會話記錄或 compaction 摘要。

觀察與接管終端

• 右側 Herdr 終端支援 ANSI 輸出、自動適配尺寸、只讀觀察、顯式鍵盤接管、輸入限流、斷線恢復和有界緩衝。
• 關閉終端檢視不會關閉 Herdr pane 或 Agent；可以選擇在關閉檢視時釋放終端控制權。
• 關閉 workspace、pane 或 Agent 必須經過本機確認。Herdr v0.8.2 無法只停止 Agent，因此“關閉 Agent”會明確關閉它所在的 pane 及其中程序。
• Windows x64 的終端子程序由原生 Job Object 約束，應用或終端異常退出時會執行有界清理。

執行受管後臺程序

開啟設定→通用→受管後臺程序

受管後臺程序讓 Agent 在應用管理的生命週期內持續執行開發伺服器、watcher、mock API 和其他專案任務，不需要使用 shell &、 nohup或外部終端機。短命令使用工作階段所選的 Shell：Bash，或 Windows 上的 PowerShell。

開始與檢視程序

1. 選擇受信任的專案目錄，在“設定 → 通用”中開啟“啟用受管後臺程序”。此功能預設關閉。
2. 讓 Agent 啟動開發伺服器、watch build 或其他長期任務；Agent 會使用 process_* 工具管理它們。
3. 開啟主介面右側“程序”面板，檢視 owner、狀態、readiness、脫敏日誌、loopback endpoint 與退出原因。
4. 對可用 endpoint 點選“在瀏覽器中開啟”，即可與內建 Browser 聯調；程序能力與 Browser 授權彼此獨立。

控制程序與日誌

• 可以傳送一行 stdin、停止、強制停止、重啟程序，並搜尋、複製或匯出日誌。
• 慢啟動任務使用日誌 cursor 繼續觀察，不會重複讀取全部輸出；日誌使用有界緩衝並自動脫敏常見敏感資訊。
• 每個程序只屬於啟動它的 Agent 會話，其他會話不可見；重啟會生成新的 run ID，過期操作會被拒絕。
• 使用者停止的程序不會被 Agent 自動重新啟動；Host 或應用異常退出時，crash reaper 會有界清理程序樹。

Windows PowerShell 支援

在 Windows 上使用 PowerShell 5.1 或 7 執行 Agent 命令。可選擇新工作階段的預設 Shell，既有工作階段保留原有選擇。

1. 在 Windows 上，開啟「設定 → 一般 → Agent 預設 Shell」，選擇 PowerShell 或 Bash。新工作階段預設使用 PowerShell；此設定僅影響之後建立的工作階段。
2. 優先使用可用的 PowerShell 7，也支援 Windows PowerShell 5.1。可在「開發工具」中指定執行檔；安裝或變更路徑後，請重新整理工具狀態。

請拆分過長的 PowerShell 命令。超過 Windows 長度限制的命令會在執行前明確報錯，不會被無聲截斷後執行。

配置模型

開啟設定→模型

Pi Agent Desktop v0.4.1 內建 Pi Coding Agent 1.2.0，但不提供模型額度。你需要連線已有的模型服務賬號，或填寫模型服務商提供的 API Key。模型設定支援英文、簡體中文和繁體中文。

使用 API Key

1. 開啟“設定 → 模型”，點選“新增服務商”。
2. 選擇你的模型服務商。
3. 如需代理或相容端點，可先填寫 Base URL；留空則使用服務商預設地址。
4. 貼上 API Key，點選“儲存”；應用會同步重新整理 Agent Host 的模型狀態。
5. 選擇要使用的模型；如果介面提供“測試”，可以先測試連線。
6. 關閉設定，在會話輸入框下方選擇剛配置的模型。

Base URL 會覆蓋當前 API Key 服務商的請求地址，並與 API Key 一起在點選頁面底部“儲存”後生效。模型目錄重新整理受到完整超時保護；即使服務初始化或最終目錄整理卡住，也會停止等待並繼續保留快取模型。

管理模型顯示範圍

1. 開啟“設定 → 模型”，選擇一個已經連線的訂閱賬號或 API Key 服務商。
2. 在模型區域檢視已啟用數量；模型較多時，可以按名稱或模型 ID 搜尋。
3. 勾選或取消單個模型，也可以點選“全部啟用”或“全部禁用”批次調整。
4. 等待選擇儲存完成，返回會話後即可在模型選擇器中看到啟用的模型。

選擇會持久化到 Pi 設定併相容已有的思考等級配置，但不會改變當前會話正在使用的模型。應用會阻止儲存沒有任何有效模型的配置，避免模型選擇器不可用。

重新整理模型目錄

1. 在會話輸入框下方開啟模型選擇器。
2. 點選“重新整理模型目錄”，從已配置的 Provider 獲取最新模型。
3. 等待重新整理完成；離線、超時或部分 Provider 失敗時，介面會顯示對應狀態或警告。

會話啟動時優先讀取本地快取的模型目錄，避免每次啟動都發起網路請求。重新整理失敗不會清空已有模型，快取目錄仍可繼續使用。

使用 OAuth 登入

1. 在“新增服務商”中選擇支援 OAuth 的服務商。
2. 點選“登入”，按提示在瀏覽器中完成授權。
3. 回到應用，確認服務商顯示為已連線；登入或退出後模型狀態會自動同步。

自定義相容服務

如果你使用的是相容 OpenAI、Anthropic 或 Google API 的自建服務，可以新增自定義服務商，並填寫 Base URL、API 型別、API Key 和模型資訊。這部分只在普通服務商列表無法滿足需求時使用。

模型設定復原

1. 開啟「設定 → 模型」並修正提示的欄位。其餘無法在介面中編輯的欄位，請手動修改 ~/.pi/agent/models.json。支援行註解與尾端逗號。
2. 重新載入磁碟上的設定，再重新載入工作階段後傳送訊息。復原後檢查已選模型及 Auto 路由。

OpenRouter 根據目前帳號權限更新模型目錄。Desktop 與 Pi CLI 共用 ~/.pi/agent/ 下的快取；切換帳號或離線啟動後，請連線更新，取代過期或來自其他帳號的目錄。

Auto 自動路由

設定快速模型與強大模型，Auto 依思考等級或任務複雜度為每次新提問選擇模型，並顯示實際回答的模型。

1. 開啟「設定 → 模型 → 自動路由」，啟用 Auto，選擇快速模型、強大模型與各自的思考等級。儲存後，在輸入框下方選擇 Auto。
2. 可依思考等級路由，或新增決策模型判斷任務複雜度。決策請求會增加耗時與用量；判斷失敗時，Auto 使用強大模型。
3. 工具接續呼叫沿用已選模型。可在自動重試時嘗試另一個已設定模型，並依實際模型查看用量。
4. 路由設定在新建、重新載入工作階段或重新選擇 Auto 後生效。

MCP 服務管理

透過 stdio 或 Streamable HTTP 連接本機與遠端工具。在設定中匯入設定、透過 OAuth 登入、測試連線並預覽資源。

1. 開啟「設定 → MCP」，選擇「全域」或「目前專案」，然後新增服務或匯入 JSON 設定。
2. 設定 stdio 命令或 Streamable HTTP URL，依需要使用 OAuth 或服務供應商憑證參照，再測試連線。
3. 瀏覽工具、資源和資源範本，在服務詳細資訊中預覽資源內容或重新連線。
4. 專案設定覆寫同名全域設定，擴充功能來源與待套用的變更分開顯示。
5. 儲存 MCP 設定不等於授權工具。請在目前工作階段的工具選單中授權；巢狀呼叫也遵守相同的權限。

圖片生成與決策模型

透過 Codemode 生成圖片、分類內容、進行是非判斷或評分。生成的圖片在重新開啟對話後仍可查看。

1. 在「設定 → 模型」設定可用的圖片或決策模型，然後在工作階段工具選單啟用 Codemode。「完整存取」預設包含 Codemode 與工具搜尋。
2. 讓 Agent 生成圖片或對內容進行分類。支援圖片輸入的決策模型也能判斷螢幕截圖。這些模型提供輔助能力，不在聊天主模型選單中選取。
3. OpenAI 決策介面需要 API Key，ChatGPT 訂閱登入不提供此能力。透過 API Key 新增 TypeSafe / Jev 服務供應商，即可使用 jev-latest。
4. 服務供應商詳細資訊頁可測試圖片和決策模型，測試可能產生費用。呼叫支援取消，並在工作階段歷史中保留輸入、結果、狀態與用量。

工具權限與執行歷史

依工作階段分支檢視直接與巢狀呼叫的執行樹。檢查狀態、耗時、輸入與完整結果，重新開啟或壓縮工作階段後仍可查閱。

1. 工作階段工具選單分別控制模型可見入口、可被巢狀查找的工具與實際執行授權。權限變更會同步至執行階段。
2. 大型結果與暫時輸出會持續儲存，支援分頁讀取。重新開啟或壓縮工作階段後，Agent 可透過 tool_history_get 查詢原始內容。
3. 中斷後保留已完成的子呼叫，未確認的結果標記為中斷或結果未知。復原時不會自動重播操作。

模型進階設定

• 開啟「設定 → 模型 → 模型進階設定」，調整自動上下文壓縮、回覆預留 Token、最近內容保留量與依模型覆寫的參數。
• 設定 Agent 和服務供應商的重試次數、等待時間、請求逾時，以及自動、SSE、WebSocket 或快取 WebSocket 傳輸方式。
• 模型編輯支援依思考等級設定取樣參數、設定圖片與請求輸入限制，以及依模型 ID 覆寫設定。支援的模型可選擇 Max 推理等級。
• 進階設定與 Pi CLI 共用。重新載入現有工作階段後生效；已信任專案的設定可覆寫全域值。儲存時會偵測外部修改，減少設定衝突。

Skills 設定

開啟選擇專案→設定→技能

這裡只介紹設定方法。Skill 的具體能力和使用方式由它自己的說明決定。

1. 先在左側選擇專案，再開啟“設定 → 技能”。
2. 選擇已有 Skill，使用右上角開關設定它是否對模型可見。
3. 需要新增時點選“新增技能”，搜尋名稱，選擇“全域性”或“當前專案”，再點選“安裝”。
4. 只有確實需要自定義說明時才修改內容，並點選“儲存更改”。

Plugins 設定

開啟選擇專案→設定→外掛

外掛頁只需要配置外掛來源、安裝範圍和啟用狀態。

1. 先選擇專案，再開啟“設定 → 外掛”。
2. 點選“新增外掛”，填寫 npm 包、Git 倉庫或本地絕對路徑。
3. 選擇“全域性”或“當前專案”，然後點選“安裝”。
4. 在已安裝列表中啟用、禁用、更新或移除外掛。
5. 設定發生變化後，點選“重新載入會話”使配置生效。

訊息渠道設定

開啟設定→訊息傳遞渠道

先選擇要連線的渠道。飛書 / Lark 推薦使用官方掃碼建立，也可以繼續連線已有自建應用：

附件與對應回合正確關聯。已取消或由擴充功能接管的訊息不再影響後續 Desktop 回合，也不會重複傳送上一輪助理回覆。

飛書 / Lark 掃碼建立機器人

1. 點選“連線飛書 / Lark”，選擇“掃碼建立（推薦）”。
2. 選擇賬號區域：飛書（中國）或 Lark。
3. 點選“生成二維碼”，使用對應客戶端掃碼並完成官方授權。
4. 授權完成後，應用會自動建立機器人、配置所需許可權、儲存憑據、驗證身份並啟動連線。

連線已有飛書 / Lark 應用

在接入方式中選擇“已有應用”，選擇飛書或 Lark，再填寫 App ID 和 App Secret。掃碼流程不會讀取已有應用的 App Secret。

完成賬號設定

1. 儲存賬號資訊，並按需設定預設工作目錄和訪問策略。
2. 啟動賬號，確認狀態顯示為“執行中”。
3. 使用“測試連線”檢查配置；需要與當前會話共享上下文時，再繫結對應訊息對話。

開發工具設定

開啟設定→開發工具

應用會自動掃描所需工具。普通使用只需要處理顯示為“缺少”或“不可用”的專案。

1. 點選“重新掃描”，檢視工具狀態、來源和版本。
2. 已經安裝的工具保持“自動”，檢測不正確時點選“選擇”指定路徑。
3. 缺少工具且應用提供託管版本時，點選“安裝”；檔案損壞時點選“修復”。

Windows 會結合安裝佈局與同目錄 Git 版本識別 Git Bash，因此自定義 Git for Windows 目錄和帶版本號的 PortableGit 目錄也能被正確發現。

優先使用可用的 PowerShell 7，也支援 Windows PowerShell 5.1。可在「開發工具」中指定執行檔；安裝或變更路徑後，請重新整理工具狀態。

管理 Herdr 執行時

macOS、Linux 與 Windows x64 版都隨包提供經過完整性校驗的 Herdr v0.8.2。在“開發工具”中可以檢視內建版本、已安裝版本和私有磁碟佔用，並執行安裝、更新、修復或解除安裝；這些操作從應用內建副本恢復，不會另行下載 Herdr。

Herdr 版本隨 Pi Desktop 更新。解除安裝私有執行時不會刪除 Herdr Session，也不會移除安裝包中的恢復副本。

更新、後臺執行與本地資料

檢查更新

開啟“設定 → 關於”，可以檢查穩定版更新。macOS 與 Windows 支援在應用內下載並安裝；Linux AppImage 當前需要從下載頁面手動獲取新版本。

保持訊息渠道線上

在“設定 → 通用”開啟“關閉視窗時最小化到托盤”。關閉主視窗後訊息渠道會繼續執行；從托盤選單選擇“退出”才會真正停止應用。

本地數據

Desktop 的工具權限與執行紀錄儲存在應用程式資料目錄。完整備份時，除了 ~/.pi/agent/，還需保留其中的 tool-executions 日誌與內容檔案。

• 會話與 Pi 設定預設儲存在本機的 ~/.pi/agent/ 目錄中。
• 已經使用 Pi CLI 的使用者可以直接複用原有會話和配置。
• 模型請求仍會傳送給你所選擇的模型服務商，請同時瞭解該服務商的隱私政策。
• 訊息渠道憑證使用作業系統安全儲存加密儲存，不會在設定頁中重新顯示。

常見問題