安全性

Pi 是一个本地编程 agent。它会以启动它的用户账号权限运行，并把该用户可写的文件视为同一个本地信任边界内的内容。

项目信任

项目信任决定 pi 是否加载项目本地的 settings、资源、Package 和扩展。它不是沙箱，也不会在你开始在某个目录里工作后，限制模型可以要求工具执行什么。

当 pi 从当前工作目录出发，发现以下任意内容时，就会认为该项目含有需要信任的资源：

• .pi/settings.json
• .pi/extensions、.pi/skills、.pi/prompts 或 .pi/themes
• .pi/SYSTEM.md 或 .pi/APPEND_SYSTEM.md
• 当前目录或其祖先目录中的项目 .agents/skills

仅有一个空的 .pi 目录，不算需要信任的项目资源。

当一个交互式会话在某个包含需要信任资源的项目中启动，而且当前目录或父目录没有已保存的决策时，pi 会遵循全局 settings 中的 defaultProjectTrust。默认值是 "ask"，这会在有 UI 时询问是否信任该项目。已保存的决策按规范化目录存储在 ~/.pi/agent/trust.json 中，当前路径或父路径上最近的已保存决策会优先于全局默认值生效。

信任某个项目后，pi 可以加载其中需要信任的项目资源，包括：

• .pi/settings.json
• .pi 资源，例如扩展、Skill、提示词模板、主题和系统提示词文件
• 通过项目 settings 配置但缺失的项目 Package
• 项目本地扩展，以及由项目 Package 管理的扩展

拒绝信任会跳过受保护资源。除非禁用了上下文加载，否则 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 模块。Package 安装、shell 命令、语言服务器、测试命令以及其他开发者工具，都会像普通本地进程一样运行。

这是刻意为之。Pi 的设计目标，就是直接操作本地源码树，调用项目工具链，并接入用户已有的开发环境。如果只做一部分进程内沙箱，很容易被误解成安全边界，但它仍然要依赖宿主 shell、文件系统、Package 管理器、凭证和扩展代码。真正的隔离，必须来自操作系统，或者来自虚拟化/容器边界。

项目信任只是一个输入加载护栏。它能防止仓库在你批准之前，悄悄修改 pi 的 settings 或扩展。它不会让不受信任的代码、不受信任的提示词，或不受信任的模型输出变得安全。来自仓库文件、注释、文档、上下文文件或构建输出的 prompt injection，是本地 agent 的预期风险，pi 无法可靠地防住。

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

对于不受信任的仓库、你不打算密切监控的生成代码，或者无人值守的自动化任务，应把 pi 运行在受隔离的环境中。使用容器、VM、micro-VM、远程沙箱，或者由策略控制的沙箱，并且只给它完成任务所需的文件和凭证。

Containerization 里记录了常见模式：

• 把整个 pi 进程运行在容器/沙箱中
• 在宿主机上运行 pi，同时把内置工具执行路由到 Gondolin micro-VM
• 只挂载 agent 应该访问的 workspace 路径
• 除非容器需要访问宿主机的会话、settings 和凭证，否则不要挂载宿主机 ~/.pi/agent
• 只传入最低限度所需的 API keys，或者使用短期凭证
• 如果任务不需要网络，就限制网络访问
• 在把结果复制回受信任系统之前，先审查 diff 和输出

如果你以读写方式 bind-mount 宿主机 workspace，容器或 VM 内的写入仍然会改到宿主机文件。若你需要更强的防止意外写入保护，就使用只读挂载，或者在进出沙箱时复制文件。

报告安全问题

要报告安全问题，请遵循仓库的 Security Policy。涉及安全敏感内容的报告，不要公开开 issue。

预期的 local-agent 行为、缺少内置沙箱、来自不受信任内容的 prompt injection，以及用户安装的扩展或 Skill 的行为，通常都在安全边界之外，除非报告证明存在真实的权限边界绕过，或者说明 pi 如何授予了本地用户原本没有的访问权限。