外观
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.override.md、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 无法可靠地阻止。
运行不可信或无人监督的工作
对于不可信的仓库、你不打算密切监督的生成代码，或无人值守的自动化任务，请在受控环境中运行 pi。使用容器、VM、微型虚拟机、远程沙箱或策略控制的沙箱，并仅提供任务所需的文件和凭据。
常见做法记录在容器化中：
- 在容器/沙箱内运行整个
pi进程 - 在宿主机上运行 pi，同时将内置工具执行路由到 Gondolin 微型虚拟机
- 仅挂载智能体应访问的工作区路径
- 除非容器需要访问宿主机会话、设置和凭据，否则不要挂载宿主机的
~/.pi/agent - 传入所需的最少 API 密钥，或使用短期凭据
- 在任务不需要时限制网络访问
- 在将结果复制回可信系统之前，检查 diff 和输出
如果你以读写方式绑定挂载宿主机工作区，容器或 VM 内部的写入仍可能修改宿主机文件。当需要更强地防护非预期写入时，请使用只读挂载，或将文件复制进、复制出沙箱。
报告安全问题
要报告安全问题，请遵循仓库的安全策略。不要为安全敏感的报告开启公开 issue。
本地智能体的预期行为、缺少内置沙箱、来自不可信内容的提示词注入，以及用户安装的扩展或技能的行为，通常不在安全边界之内，除非报告展示了对真实权限边界的绕过，或说明了 pi 如何授予了本地用户原本并不拥有的访问权限。