安全

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 如何授予本地用户尚未拥有的访问权限。