本文为社区中文翻译（依据 MIT 协议），阅读英文原文 →。译文可能滞后于上游更新。

安全

项目信任

项目信任控制 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 事件；第一个返回 yes/no 决定的扩展拥有该决定权。

非交互模式（-p、--mode json、--mode rpc）不显示信任询问。没有适用的已保存决定时，defaultProjectTrust: "ask" 和 "never" 会忽略这些资源，"always" 则信任。用 --approve/-a 或 --no-approve/-na 可为单次运行覆盖项目信任。

无内置沙箱

Pi 不带内置沙箱。内置工具可以以 Pi 进程的权限读文件、写文件、改文件和运行 shell 命令。扩展是 TypeScript 模块，以同样的权限运行。软件包安装、shell 命令、语言服务器、测试命令等开发者工具的行为与普通本地进程一致。

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

项目信任只是输入加载的守门员：它防止一个仓库在你批准之前悄悄改动 Pi 的设置或扩展。它不会让不受信任的代码、提示词或模型输出变得安全。来自仓库文件、注释、文档、上下文文件或构建输出的提示词注入，是本地智能体的固有风险，Pi 无法可靠地阻止。

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

面对不受信任的仓库、不打算紧盯的生成代码或无人值守的自动化，请把 Pi 放进受控环境运行。使用容器、虚拟机、微虚拟机、远程沙箱或带策略管控的沙箱，并且只给任务所需的文件和凭据。

常见模式记录在容器化：

• 把整个 pi 进程放进容器/沙箱运行
• 宿主机跑 Pi，同时把内置工具的执行路由进 Gondolin 微虚拟机
• 只挂载智能体需要访问的工作区路径
• 除非容器需要访问宿主的会话、设置和凭据，否则不要挂载宿主的 ~/.pi/agent
• 只传必需的 API Key，或使用短期凭据
• 任务不需要网络时限制网络访问
• 把结果拷回受信系统之前先审查 diff 和输出

如果把宿主工作区以读写方式 bind-mount 进容器/虚拟机，容器内的写入仍然会改到宿主文件。需要更强防护时，使用只读挂载，或在沙箱内外拷贝文件。

报告安全问题

报告安全问题请遵循仓库的安全策略。安全相关的报告不要开公开 issue。

本地智能体的预期行为、缺少内置沙箱、来自不受信任内容的提示词注入、以及用户自行安装的扩展或技能的行为，一般都在安全边界之外——除非报告能证明真实的特权边界绕过，或说明 Pi 授予了本地用户本不具备的访问权。