安全地运行 Pi
本页面是 Pi 官方文档 的中文翻译。仅供学习参考。
把模型生成的命令和代码视为不可信。Pi 能以启动它的账号的权限读取、修改和执行文件，并且不会在每次 tool call 之前请求批准。扩展、包安装器、语言服务器和其他子进程都以相同的权限运行，除非有操作系统或虚拟化边界加以限制。
文件、注释、指令、命令输出和模型响应都可能通过 Prompt 注入操纵模型。项目信任控制启动时加载哪些项目资源，但它不会让这些内容或由此产生的操作变得安全。
安全来自限制 Pi 在生成的操作错误或带有敌意时能够访问和影响的文件、凭证、进程和网络服务。盯着转录、使用项目信任、审阅改动都不会构成安全边界。
选择 Pi 的运行方式
不同的运行方式对生成的命令能访问什么设置了不同的限制：
工作文件夹控制资源发现以及工具的默认位置，但它不会阻止命令访问 Pi 进程可用的其他路径。
无论选择哪种方式，都只提供任务所需的文件和服务。尽量把凭证放在环境之外，或使用范围窄、生命周期短的凭证。当命令不需要网络时，限制网络访问。
每种隔离方法的设置说明和局限见在隔离环境中运行 Pi。
理解项目信任
项目信任控制 Pi 是否加载由工作文件夹提供的大部分设置和资源。它能防止某个文件夹在你批准之前静默加载可执行的扩展。
项目信任不是完整的启动边界。Pi 在选择或创建会话时、在确定项目信任之前，就会读取项目的 sessionDir 设置。拒绝信任会阻止其余项目设置和受保护资源加载，但无法撤销那次初始的会话目录查找。
项目信任不限制 tool call 能访问或影响什么。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 可以加载：
- 项目设置
.pi下的扩展、Skill、Prompt 模板、主题和系统提示文件- 通过项目设置配置但缺失的包
- 项目本地和项目包中的扩展
拒绝项目信任会跳过这些受保护资源，除了上面提到的初始 sessionDir 查找。
AGENTS.override.md、AGENTS.md 和 CLAUDE.md 等上下文文件无论项目信任如何都会加载，除非你禁用上下文加载。即使你拒绝项目信任，也要把文件夹中的指令当作不可信输入。
Pi 如何选择信任决策
命令行 --approve 或 --no-approve 覆盖最先生效。当存在受保护资源且没有命令行覆盖时：
- 用户级和命令行扩展可以处理
project_trust事件。第一个返回是或否的扩展拥有该决策。 - 如果没有扩展做出决定，Pi 查找当前目录或某个父目录已保存的决策。最近的决策生效。
- 如果没有适用的已存决策，Pi 遵循全局
defaultProjectTrust设置，默认值为"ask"。
已保存的决策使用规范化目录路径，存放在：
用 /trust 为未来的 Pi 进程保存决策。
没有交互提示时的项目信任
Print、JSON 和 RPC 模式无法显示内置的信任提示。如果没有命令行覆盖、扩展或已存决策适用：
defaultProjectTrust: "always"会加载受保护的项目资源。defaultProjectTrust: "ask"或"never"会跳过它们。
当自动化运行需要明确的一次性决策时，使用 --approve 或 --no-approve。
减少影响并改善恢复
这些做法不能替代隔离，但可以减少暴露面或让恢复更容易：
- 只给 Pi 访问任务所需的文件和服务。
- 在实质性改动之前使用快照、备份或版本控制。
- 加载扩展和包之前先审阅。扩展在 Pi 进程内执行。
- 优先使用范围窄、生命周期短的凭证。
- 把结果应用到另一个系统之前，先审阅 diff 和生成的输出。
- 导出或分享会话之前先审阅。它们可能包含 Prompt、工具参数、命令输出、文件内容和对话期间暴露的凭证。
报告安全问题
请遵循仓库的安全政策。安全敏感的报告不要开公开 issue。
本地 Agent 的预期行为、来自不可信内容的 Prompt 注入、缺少内置沙箱，以及用户安装的扩展或 Skill 的行为，通常都在安全边界之外，除非报告展示了权限边界绕过或本地用户原本不具备的访问能力。
法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。