安全

Pi 是本機程式開發 Agent。它以啟動它的使用者帳戶權限執行，並將該使用者可寫的檔案視為處於同一個本機信任邊界內。

專案信任控制 pi 是否載入專案本機設定、資源、包和擴充。它不是 sandbox，並且它不限制模型在你開始在目錄中工作後可以要求工具執行的操作。

當 Pi 從目前工作目錄中找到以下任何資源時，就認為專案具有需要信任的資源：

• .pi/settings.json
• .pi/extensions、.pi/skills、.pi/prompts 或 .pi/themes
• .pi/SYSTEM.md 或 .pi/APPEND_SYSTEM.md
• 目前目錄或祖先目錄中的專案 .agents/skills

裸露的 .pi 目錄不算作需要信任的專案資源。

當互動式工作階段在專案中啟動且資源需要信任並且目前目錄或父目錄沒有儲存決策時，pi 遵循全域設定中的 defaultProjectTrust。預設值為 "ask"，詢問當 UI 可用時是否信任該專案。儲存的決策按規範目錄儲存在 ~/.pi/agent/trust.json 中，目前或父路徑上最接近的儲存決策在全域預設值之前應用。

信任專案允許 pi 載入需要信任的專案資源，包括：

• .pi/settings.json
• .pi 擴充、技能、Prompt Templates、主題、system prompt 檔案等資源
• 缺少透過專案設定設定的專案套件
• 專案本機擴充和專案套件管理的擴充

拒絕信任會跳過受保護資源。無論專案信任狀態如何，context files（如 AGENTS.override.md、AGENTS.md 和 CLAUDE.md）都會載入，除非停用了上下文載入。在信任解析前，pi 只載入 context files、使用者/全域擴充和 CLI -e 擴充。使用者/全域和 CLI 擴充可以處理 project_trust 事件；第一個傳回 yes/no 決策的擴充擁有該決策。

非互動模式（-p、--mode json 和 --mode rpc）不顯示信任提示。如果沒有適用的已儲存信任決策，defaultProjectTrust: "ask" 和 "never" 會忽略此類資源，而 "always" 則信任它們。使用 --approve/-a 或 --no-approve/-na 覆寫單次執行的專案信任。

Pi 不包含內建 sandbox。內建工具可以使用 pi 程序的權限讀取檔案、寫入檔案、編輯檔案以及執行 Shell 指令。擴充是 TypeScript 模組，也以相同權限執行。套件安裝、Shell 指令、語言伺服器、測試指令和其他開發工具的行為與普通本機程序一樣。

這是故意的。 Pi 旨在操作本機原始碼樹，呼叫專案工具鏈，並與使用者現有的開發環境整合。部分程序內 sandbox 很容易被誤解為安全邊界，同時仍然依賴主機 shell、檔案系統、套件管理工具、憑證和擴充程式碼。真正的隔離需要來自作業系統或虛擬化/容器邊界。

專案信任只是輸入載入防護。它可以防止 repository在批准前悄悄更改 pi 的設定或擴充。它不會讓不受信任的程式碼、不受信任的 Prompt 或不受信任的模型輸出變得安全。來自 repository 檔案、注釋、檔案、context files 或建置輸出的 Prompt injection 是預期的本機 Agent 風險，pi 無法可靠阻止。

對於不受信任的儲存庫、你不打算密切監視的產生程式碼或無人值守的自動化，請在封閉的環境中執行 pi。使用容器、虛擬機、微型虛擬機、遠端 sandbox 或策略控制的 sandbox，僅使用任務所需的檔案和憑證。

常見模式記錄在 Containerization 中：

• 在容器內執行整個 pi 程序/sandbox
• 執行主機 pi，同時將內建工具執行路由至 Gondolin 微型虛擬機
• 僅掛載代理應存取的工作區路徑
• 避免掛載主機 ~/.pi/agent，除非容器應該存取主機工作階段、設定和憑證
• 只提供最低必要的 API Keys，或使用短期憑證
• 當任務不需要時限制網路存取
• 在將結果複製回受信任的系統之前檢查diff和輸出

如果你以讀/寫方式綁定掛載主機工作區，則來自容器或虛擬機內部的寫入仍然可以修改主機檔案。當你需要更強的保護以防止意外寫入時，請使用唯讀掛載或將檔案複製到 sandbox，或從 sandbox 複製出來。

要報告安全問題，請關注儲存庫Security Policy。不要針對安全敏感報告提出公開問題。

預期的本機 Agent 行為、缺少內建 sandbox、來自不受信任內容的 Prompt injection，以及使用者安裝的擴充或 Skills 的行為，通常不屬於安全邊界問題，除非報告展示了真實的權限邊界繞過，或說明 pi 如何授予本機使用者原本沒有的存取權限。