# 安全 > pi 的本地信任模型、项目信任机制、沙箱边界与安全问题报告方式。 --- LLMS 索引： [llms.txt](/llms.txt) --- Pi 是一个本地编码智能体。它以启动它的用户账户的权限运行，并把该用户可写的文件视为处于同一个本地信任边界之内。 ## 项目信任 {#project-trust} 项目信任决定 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` 可以为单次运行覆盖项目信任。 ## 没有内置沙箱 {#no-built-in-sandbox} Pi 不包含内置沙箱。内置工具可以读取文件、写入文件、编辑文件，并以 pi 进程自身的权限运行 shell 命令。扩展是以相同权限运行的 TypeScript 模块。包安装、shell 命令、语言服务器、测试命令和其他开发工具都表现为普通的本地进程。 这是有意为之。Pi 的设计目标是在本地源码树上操作、调用项目工具链，并与用户现有的开发环境集成。一个进程内的部分沙箱很容易被误解为安全边界，但它仍然要依赖宿主机的 shell、文件系统、包管理器、凭据和扩展代码。真正的隔离必须来自操作系统或虚拟化/容器边界。 项目信任只是一道输入加载防线。它可以防止仓库在你批准之前悄悄更改 pi 的设置或扩展。它无法让不受信任的代码、不受信任的提示词或不受信任的模型输出变得安全。来自仓库文件、注释、文档、上下文文件或构建输出的提示词注入，属于本地智能体预期之中且无法避免的风险，pi 无法可靠地防范。 ## 运行不受信任或无人监督的工作 {#running-untrusted-or-unmonitored-work} 对于不受信任的仓库、你不打算密切监督的生成代码，或无人值守的自动化，请在受控环境中运行 pi。使用容器、虚拟机、微虚拟机、远程沙箱或受策略控制的沙箱，并且只提供任务所需的文件和凭据。 常见模式记录在[容器化](/book/pi/containerization/)一章中： - 将整个 `pi` 进程放入容器/沙箱中运行 - 在宿主机上运行 pi，同时把内置工具的执行路由到 Gondolin 微虚拟机 - 只挂载智能体应该访问的工作区路径 - 避免挂载宿主机的 `~/.pi/agent`，除非容器需要访问宿主机的会话、设置和凭据 - 只传入必需的最少 API 密钥，或使用短期凭据 - 在任务不需要网络时限制网络访问 - 在把结果复制回受信任系统之前，先审查 diff 和输出 如果你以读写方式绑定挂载宿主机工作区，容器或虚拟机内部的写入仍然可以修改宿主机文件。当你需要更强的保护、防止意外写入时，请使用只读挂载，或者以复制文件的方式把内容移入和移出沙箱。 ## 报告安全问题 {#reporting-security-issues} 要报告安全问题，请遵循仓库的[安全策略](https://github.com/earendil-works/pi/blob/main/SECURITY.md)。不要为安全敏感的报告创建公开 issue。 预期中的本地智能体行为、缺少内置沙箱、来自不受信任内容的提示词注入，以及用户安装的扩展或技能的行为，通常不在安全边界范围之内，除非报告演示了真实的权限边界绕过，或表明 pi 授予了本地用户原本并不拥有的访问权限。 --- 反链： - [容器化](/book/pi/containerization/)