安全

Pi是本地編碼代理。它以啟動它的使用者帳戶的權限運行，並將該使用者可寫入的檔案視為在同一本地信任邊界內。

專案信任控制 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、主題、系統提示檔案等資源
• 缺少透過專案設定配置的項目包
• 專案本地擴展和專案包管理的擴展

信任下降會跳過受保護的資源。無論項目信任如何，都會載入上下文文件，例如 AGENTS.override.md、AGENTS.md 和 CLAUDE.md，除非禁用上下文載入。在信任解決之前，pi 僅載入 context files、使用者/全域擴充和 CLI -e 擴充。使用者/全域和CLI擴充可以處理project_trust事件；返回是/否決策的第一個擴充擁有該決策。

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

Pi 不包括內建sandbox。內建工具可以使用 pi 進程的權限讀取檔案、寫入檔案、編輯檔案以及執行 shell 命令。 Extensions 是TypeScript 模組，以相同的權限運作。套件安裝、shell 命令、語言伺服器、測試命令和其他開發人員工具的行為與普通本地進程一樣。

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

專案信任只是一個輸入加載防護。它可以防止儲存庫在您批准之前悄悄更改 pi 的設定或擴充。它不會使不受信任的程式碼、不受信任的提示或不受信任的模型輸出變得安全。從儲存庫檔案、註解、文件、context files或建置輸出進行提示注入是預期的本機代理風險，且 pi 無法可靠地阻止。

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

常見模式記錄在 Containerization 中：

• 在容器內運行整個pi進程/sandbox
• 運行主機 pi，同時將內建工具執行路由到 Gondolin 微型虛擬機
• 僅掛載代理應存取的工作區路徑
• 避免掛載主機~/.pi/agent，除非容器應該存取主機會話、設定和憑證
• 通過最低要求的 API keys 或使用短期憑證
• 當任務不需要時限制網路訪問
• 在將結果複製回受信任的系統之前檢查差異和輸出

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

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

預期的本地代理行為、缺乏內建 sandbox、來自不受信任內容的提示注入以及用戶安裝的擴展或技能的行為通常超出安全邊界，除非報告演示了真正的特權邊界繞過或顯示 pi 如何授予本地用戶尚未擁有的訪問權限。