权限与安全边界
Pi 的设计目标是直接操作本地代码库。理解它的权限模型,比记住任何快捷键都重要。
核心事实
Pi 没有内置操作系统沙箱。它继承启动进程的用户权限:
你的用户账号 │ 相同的文件、进程、网络与凭据权限 ▼Pi 进程 ├── 内置工具:read / write / edit / bash / ... ├── MCP 服务:本地子进程或远程服务 └── 扩展与 Pi 包:普通 TypeScript/JavaScript 代码因此,Pi 能做的事情通常和你在同一个终端中能做的事情相同。
项目信任不是沙箱
| 机制 | 它控制什么 | 它不控制什么 |
|---|---|---|
| 项目信任 | 是否加载 .pi 设置、项目 MCP、扩展、技能、模板、主题和项目包 | 模型调用工具后能读写哪些系统文件 |
| 工具 allowlist | 当前会话向模型暴露哪些 Pi 工具 | 扩展代码或 shell 子进程的系统权限 |
| 容器、VM、微型 VM | 操作系统可见的文件、网络、进程和凭据 | 业务逻辑是否正确 |
信任提示解决的是“这个仓库能否改变 Pi 的启动配置”,不是“Pi 能否修改这个仓库”。记成:信任管加载,不管权限。
AGENTS.override.md、AGENTS.md 和 CLAUDE.md 默认会作为上下文加载,即使项目没有被信任。Pi 还会在信任决策之前读取项目的 sessionDir 设置以确定会话位置。不要把不可信仓库中的指令文件当成安全内容。
推荐的本地工作方式
1. 从干净工作树开始
git status --shortgit switch -c task/my-change已有未提交修改时,先理解它们属于谁、是否可以被覆盖。
2. 第一个请求保持只读
先不要修改文件或执行安装命令。概览项目结构、检查命令和潜在风险。这既验证环境,也让你看到 Pi 对项目的理解是否正确。
3. 明确允许范围
一个好的修改请求应包含:
- 可以修改哪些文件或目录
- 什么结果算完成
- 必须运行哪些验证
- 哪些动作明确禁止
例如:
只修改 docs/ 下的 Markdown,修复相对链接。不要安装依赖或更改配置。完成后运行文档构建并汇报结果。4. 独立检查结果
git status --shortgit diff --checkgit diff --cached --checkgit diffgit diff --cached状态为 ?? 的未跟踪文件要单独检查。再运行项目自己的测试、类型检查和构建。模型说“已完成”不是验证证据。
只选工具时别漏掉 MCP
Pi 1.5 中,--tools read,grep,find,ls 不会自动排除 MCP 工具。若本次不需要内置 MCP,可以使用:
pi --no-mcp --tools read,grep,find,ls--no-mcp 不会禁用替代内置 MCP 的第三方扩展;--no-extensions 禁用自动发现和内置扩展,但显式 -e 仍可加载。全局扩展可能在启动时执行代码,工具过滤也不能限制它们。检查具体配置,并在高风险任务中使用真正的隔离环境。详见 MCP 工具范围。
什么时候必须使用隔离环境
下面任一情况成立时,优先使用容器、虚拟机、微型 VM 或策略沙箱:
- 仓库来源不可信。
- 任务需要运行未知安装脚本或二进制文件。
- Pi 会无人值守运行较长时间。
- 工作目录之外存在高价值凭据或私人文件。
- 任务不需要公网,但宿主机默认可以访问公网。
隔离时遵循最小权限:
- 只挂载任务所需目录。
- 不要默认挂载
~/.pi/agent。 - 只传入必要、最好是短期的凭据。
- 不需要网络时关闭网络。
- 需要保护宿主文件时使用只读挂载或复制进出。
具体模式见 Pi Containerization。
凭据
Pi 可以从 /login 保存的认证、环境变量和 auth.json 读取凭据。建议:
- 不在提示词中粘贴真实密钥。
- 不把密钥写进版本控制。
- 不让不可信扩展访问包含凭据的进程环境。
- 分享或导出会话前检查内容。
- 发现泄露后立即轮换,而不是只删除日志。
第三方扩展、MCP 与 Pi 包
扩展是与 Pi 同进程、同权限运行的代码;本地 MCP 服务是子进程,远程 MCP 服务可能操作其授权账户。Codemode 通过工具间接调用这些服务,并不会撤销已发生的副作用。安装或连接前检查:
- 发布者与仓库来源。
- 安装脚本和依赖。
- 是否读取文件、环境变量或网络。
- 最近维护状态与版本固定方式。
“功能只是一个主题或命令”并不意味着它没有代码执行权限。
在 Vue 或浏览器中集成 Pi
这份文档站使用 Vue 3,但 Pi CLI 本身运行在 Node.js 终端环境。如果你另外构建 Pi Web 客户端:
- 不要把供应商 API Key 放进
VITE_*、客户端.env或浏览器存储。 - 不要把
@earendil-works/pi-coding-agentCLI SDK 直接打进浏览器。 - 浏览器侧可以使用面向 Web 的
pi-ai/pi-agent-core能力,但生产请求应经过你控制的后端代理。 - 后端必须负责认证、模型白名单、限流、审计和供应商密钥保管。
上游的浏览器打包检查证明核心包可以被 bundler 处理,不代表把供应商密钥暴露给浏览器是安全的。
最小安全检查表
- 当前目录正确,工作树状态已确认。
- 仓库与项目本地扩展可信。
- 任务范围、禁止动作和完成标准已写清。
- 高风险凭据没有暴露给任务环境。
- 不可信或无人值守任务运行在隔离环境。
- 修改由
git diff和真实检查命令独立验证。
继续阅读:
- 用配置与扩展选择风险更低的定制机制。
- 在动手前从六个工程工作流复制带范围和验证条件的任务。
- 出现异常时按故障排查收集最小证据。
- 构建 Web Agent 时查看 SDK 与 Vue 最小集成。
- 以 Pi 官方 Security核对上游安全说明。