安全

Pi 是一个本地编码智能体（agent）。它以启动它的用户账户的权限运行，并将该用户可写的文件视为位于同一本地信任边界（trust boundary）内。

项目信任

项目信任（project trust）控制 pi 是否加载项目本地的设置、资源、包和扩展。它不是一个沙箱（sandbox），也不会限制模型在你在某个目录开始工作后可以要求工具（tool）做什么。

当 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.override.md、AGENTS.md 和 CLAUDE.md）无论项目信任状态如何都会加载，除非上下文加载被禁用。在信任决定确定之前，pi 只加载上下文文件、用户/全局扩展和 CLI -e 扩展。这些扩展可以处理 project_trust 事件，由第一个返回是/否决定的扩展来拍板。

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

无内置沙箱

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

这是有意为之。Pi 的设计目标是在本地源码树上操作、调用项目工具链，并与用户现有的开发环境集成。进程内的部分沙箱很容易被误认为是一种安全边界，而它实际上仍依赖宿主 shell、文件系统、包管理器、凭据（credential）和扩展代码。真正的隔离必须来自操作系统或虚拟化/容器边界。

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

运行不受信任或无人值守的工作

对于不受信任的仓库、你不打算密切监视的生成代码或无人值守的自动化任务，请在受隔离的环境中运行 pi。使用容器、VM、微 VM（micro-VM）、远程沙箱或策略受控的沙箱，并且只提供任务所需的文件和凭据。

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

在容器/沙箱内运行整个 pi 进程
在宿主机上运行 pi，同时将内置工具的执行路由到 Gondolin 微 VM
只挂载智能体应访问的工作区路径
除非容器需要访问宿主的会话、设置和凭据，否则避免挂载宿主的 ~/.pi/agent
只传入所需的最小 API 密钥，或使用短期凭据
当任务不需要网络时限制网络访问
在将结果复制回受信任系统之前，审查 diff 和输出

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

报告安全问题

要报告安全问题，请遵循仓库的安全策略。不要为涉及安全的问题打开公开 issue。

预期的本地智能体行为、缺少内置沙箱、来自不受信任内容的提示词注入，以及用户安装的扩展或技能的行为，通常都不在安全边界之内，除非报告能够证明存在真正的权限边界绕过，或说明 pi 如何授予本地用户原本不具备的访问权限。