安全性

Pi 是一个本地编程助手。它以启动它的用户账户权限运行，并将该用户可写入的文件视为处于同一个本地信任边界内。

项目信任

项目信任控制 Pi 是否加载项目本地的设置、资源、包和扩展。它不是沙盒，也不限制模型在你开始在工作目录中进行操作后可以向工具请求什么。

当 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 资源，如扩展、技能、提示模板、主题和系统提示文件
• 通过项目设置配置的缺失项目包
• 项目本地扩展和项目包管理的扩展

拒绝信任会跳过受保护的资源。AGENTS.md 和 CLAUDE.md 上下文文件无论项目信任状态如何都会被加载（除非禁用了上下文加载）。在信任解析之前，Pi 仅加载上下文文件、用户/全局扩展以及 CLI -e 扩展。用户/全局扩展和 CLI 扩展可以处理 project_trust 事件；第一个返回是/否决策的扩展拥有该决策。

非交互模式（-p、--mode json 和 --mode rpc）不会显示信任提示。在没有适用的保存信任决策的情况下，defaultProjectTrust: "ask" 和 "never" 会忽略此类资源，而 "always" 会信任它们。使用 --approve/-a 或 --no-approve/-na 可以覆盖单次运行的项目信任。

没有内置沙盒

Pi 没有内置沙盒。内置工具可以以 Pi 进程的权限读取文件、写入文件、编辑文件和运行 shell 命令。扩展是 TypeScript 模块，使用相同的权限运行。包安装、shell 命令、语言服务器、测试命令以及其他开发工具都作为普通的本地进程运行。

这是有意为之。Pi 旨在操作本地源代码树、调用项目工具链，并与用户的现有开发环境集成。一个部分的内进程沙盒容易被误解为安全边界，同时仍然依赖于宿主 shell、文件系统、包管理器、凭据和扩展代码。真正的隔离必须来自操作系统或虚拟化/容器边界。

项目信任只是一个输入加载的守护程序。它防止仓库在获得你批准之前静默更改 Pi 的设置或扩展。它并不能使不受信任的代码、不受信任的提示或不受信任的模型输出变得安全。来自仓库文件、注释、文档、上下文文件或构建输出的提示注入是本地代理的预期风险，Pi 无法可靠地防止。

运行不受信任或未监控的工作

对于不受信任的仓库、你不想密切监控的生成代码，或未attended 的自动化，请在受限环境中运行 Pi。使用容器、VM、微 VM、远程沙盒或仅包含任务所需的文件和凭据的策略控制沙盒。

常见模式已在 容器化 中记录：

• 在容器中运行整个 pi 进程
• 在宿主机运行 Pi 的同时将内置工具执行路由到 Gondolin 微 VM
• 仅挂载代理应访问的工作空间路径
• 除非容器需要访问会话、设置和凭证，否则不要挂载宿主机的 ~/.pi/agent
• 传递任务所需的最小 API 密钥或使用短期凭据
• 当任务不需要时限制网络访问
• 将结果复制回可信系统之前审查差异和输出

如果你以读写方式绑定挂载宿主工作空间，从容器或 VM 内部进行的写入仍然可以修改宿主文件。当需要更强保护时，请使用只读挂载或将文件复制进出沙盒。

报告安全问题

要报告安全问题，请遵循仓库的 安全策略。不要为安全敏感的报告公开创建问题。

预期本地代理行为、缺乏内置沙盒、来自不受信任内容的提示注入，以及用户安装的扩展或技能的行为，通常在安全边界之外，除非报告展示了真正的权限边界绕过，或者说明 Pi 授予了本地用户原本没有的访问权限。