#安全

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

#项目信任

项目信任控制 Pi 是否加载项目本地设置、资源、包和扩展。它不是一个沙箱，也不会限制模型在你开始在某目录中工作后可以要求工具执行的操作。

当 Pi 从当前工作目录发现以下任何内容时，就认为该项目具有信任输入：

• 当前目录中的 .pi/
• 当前目录或祖先目录中的 .agents/skills

当交互式会话在具有 .pi 或 .agents/skills 中配置的项目中启动，且当前目录或父目录没有保存的决策时，Pi 会遵循全局设置中的 defaultProjectTrust。默认值为 "ask"，在有 UI 可用时询问是否信任该项目。保存的决策按规范化目录存储在 ~/.pi/agent/trust.json 中，在应用全局默认之前，当前路径或父路径上最近的保存决策会先生效。

信任项目后，Pi 可以加载受信任门控的项目输入，包括：

• .pi/settings.json
• .pi 资源，如扩展、Skill、Prompt 模板、主题和系统 Prompt 文件
• 通过项目设置配置的缺失项目包
• 项目本地扩展和项目包管理的扩展

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

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

#无内置沙箱

Pi 不包含内置沙箱。内置工具可以读写文件、编辑文件，并以 Pi 进程的权限运行 shell 命令。扩展是以相同权限运行的 TypeScript 模块。包安装、shell 命令、语言服务器、测试命令和其他开发者工具的行为与普通本地进程相同。

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

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

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

对于不受信任的仓库、不打算密切监控的生成代码或无人值守的自动化，请在受限环境中运行 Pi。使用容器、VM、micro-VM、远程沙箱或策略控制的沙箱，且仅授予任务所需的文件和凭据。

常见模式在 容器化 中有文档说明：

• 在 OpenShell 或 Docker 中运行整个 pi 进程
• 在主机上运行 pi，同时将内置工具执行路由到 Gondolin micro-VM
• 仅挂载 Agent 应访问的工作区路径
• 避免挂载主机的 ~/.pi/agent，除非容器应访问主机的会话、设置和凭据
• 传入所需的最小 API Key 集或使用短期凭据
• 在任务不需要时限制网络访问
• 在将结果复制回受信任系统之前审查差异和输出

如果以读写方式 bind-mount 主机工作区，容器或 VM 内部的写入仍然可以修改主机文件。当需要更强保护以防止意外写入时，请使用只读挂载或将文件复制进/出沙箱。

#报告安全问题

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

预期的本地 agent 行为、缺乏内置沙箱、来自不受信任内容的 Prompt 注入以及用户安装的扩展或 Skill 的行为通常不在安全边界之内，除非该报告证明存在真正的权限边界绕过，或证明 Pi 授予了本地用户原本并不具备的访问权限。