7  安全模型

7.1 概述

Pi 是一个本地编程代理。它以启动它的用户账户权限运行，并将该用户可写的文件视为同一个本地信任边界内的内容。

Pi 的安全设计基于三个核心原则：

  1. 项目信任机制：控制项目本地设置的加载
  2. 无内置沙箱：有意为之的设计决策
  3. 外部隔离：通过容器/VM 实现真正的安全边界

7.2 项目信任机制详解

7.2.1 什么是项目信任

项目信任控制 Pi 是否加载项目本地的设置、资源、包和扩展。它不是沙箱，不会限制模型在开始工作后能要求工具做什么。

7.2.2 触发信任提示的资源

当 Pi 在当前工作目录中发现以下任一资源时，会认为该项目有需要信任的资源：

  • .pi/settings.json
  • .pi/extensions、.pi/skills、.pi/prompts 或 .pi/themes
  • .pi/SYSTEM.md 或 .pi/APPEND_SYSTEM.md
  • 当前目录或祖先目录中的项目 .agents/skills
Note

一个空的 .pi 目录不会触发信任提示。只有包含上述特定资源时才会。

7.2.3 信任决策流程

当一个交互式会话在有需要信任资源的项目中启动，且当前目录或父目录没有已保存的决策时：

  1. Pi 遵循全局设置中的 defaultProjectTrust
  2. 默认值为 "ask"，在有 UI 时询问用户
  3. 保存的决策按规范目录路径存储在 ~/.pi/agent/trust.json 中
  4. 当前路径或父路径上最近的保存决策优先于全局默认值

7.2.4 信任后加载的资源

信任一个项目后，Pi 会加载：

  • .pi/settings.json
  • .pi 资源（扩展、技能、提示词模板、主题和系统提示词文件）
  • 通过项目设置配置的缺失项目包
  • 项目本地扩展和项目包管理的扩展

7.2.5 拒绝信任时的行为

拒绝信任会跳过受保护的资源。但以下内容无论信任与否都会加载：

  • AGENTS.md 和 CLAUDE.md 上下文文件（除非显式禁用上下文加载）
Warning

在信任解决之前，Pi 只加载上下文文件、用户/全局扩展和 CLI -e 扩展。用户/全局和 CLI 扩展可以处理 project_trust 事件；第一个返回 yes/no 决策的扩展拥有该决策权。

7.2.6 非交互模式的行为

非交互模式（-p、--mode json 和 --mode rpc）不显示信任提示。在没有适用的已保存信任决策时：

  • defaultProjectTrust: "ask" 和 "never"：忽略这些项目资源
  • defaultProjectTrust: "always"：信任这些项目资源

使用 --approve/-a 或 --no-approve/-na 为单次运行覆盖项目信任。

pi config 和包命令使用相同的项目信任流程，但 pi update 从不提示。

7.3 无内置沙箱

7.3.1 设计决策

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

Warning

这是有意为之的设计决策。Pi 被设计为在本地源代码树上操作、调用项目工具链，并与用户现有的开发环境集成。

7.3.2 为什么没有沙箱

一个部分进程内沙箱很容易被误解为安全边界，但实际上仍然依赖于宿主 Shell、文件系统、包管理器、凭证和扩展代码。真正的隔离需要来自操作系统或虚拟化/容器边界。

项目信任只是一个输入加载守卫——它防止仓库在获得批准前静默更改 Pi 的设置或扩展。它不能使不可信代码、不可信提示或不可信模型输出变得安全。

7.3.3 Prompt 注入风险

来自仓库文件、注释、文档、上下文文件或构建输出的 Prompt 注入是预期的本地代理风险，Pi 无法可靠地防止这种情况。

Warning

从不可信来源克隆仓库后，在信任该项目之前，务必检查其 .pi/ 目录和 AGENTS.md 文件中的内容。

7.4 运行不可信代码的最佳实践

对于不可信仓库、你不打算密切监控的生成代码，或无人值守的自动化，应该在受控环境中运行 Pi。

7.4.1 推荐做法

做法 说明
✅ 使用容器/沙箱 在容器/VM/微VM/远程沙箱/策略控制沙箱中运行整个 Pi 进程
✅ 限制工作空间 只挂载 Agent 应该访问的工作空间路径
✅ 避免挂载凭证目录 不要挂载宿主机的 ~/.pi/agent，除非容器需要访问宿主会话和凭证
✅ 最小化 API Key 只传递必需的 API Key 或使用短期凭证
✅ 限制网络 当任务不需要网络时禁用网络访问
✅ 审查输出 在将结果复制回可信系统前审查 diff 和输出

7.4.2 常见的容器化模式

Pi 文档中记录了三种容器化方案（详见下章）：

  1. 将整个 Pi 进程放入容器/沙箱
  2. 在宿主机上运行 Pi，通过 Gondolin 微VM 路由内置工具执行
  3. 使用 OpenShell 策略控制沙箱
Warning

如果你以读写方式绑定挂载宿主工作空间，容器或 VM 中的写入仍可以修改宿主文件。在需要防止意外写入时，使用只读挂载或将文件复制进出沙箱。

7.5 安全报告流程

要报告安全问题，请遵循仓库的安全策略。

Warning

不要为安全敏感的报告创建公开 Issue。

7.5.1 不在安全范围内的情况

以下情况通常不在安全边界内：

  • 预期的本地代理行为
  • 缺乏内置沙箱
  • 来自不可信内容的 Prompt 注入
  • 用户安装的扩展或技能的行为

除非报告证明了一个真正的权限边界绕过，或者展示了 Pi 如何授予本地用户已有的访问权限之外的访问权限，否则上述情况被视为预期行为而非安全漏洞。

7.6 安全检查清单

在开始使用 Pi 处理敏感项目前，建议完成以下检查：