权限与安全边界

Pi 的设计目标是直接操作本地代码库。理解它的权限模型，比记住任何快捷键都重要。

核心事实

Pi 没有内置操作系统沙箱。它继承启动进程的用户权限：

你的用户账号
    │  相同的文件、进程、网络与凭据权限
    ▼
Pi 进程
    ├── 内置工具：read / write / edit / bash / ...
    └── 扩展与 Pi 包：普通 TypeScript/JavaScript 代码

因此，Pi 能做的事情通常和你在同一个终端中能做的事情相同。

项目信任不是沙箱

机制	它控制什么	它不控制什么
项目信任	是否加载 .pi 设置、项目扩展、技能、模板、主题和项目包	模型调用工具后能读写哪些系统文件
工具 allowlist	当前会话向模型暴露哪些 Pi 工具	扩展代码或 shell 子进程的系统权限
容器、VM、微型 VM	操作系统可见的文件、网络、进程和凭据	业务逻辑是否正确

信任提示解决的是“这个仓库能否改变 Pi 的启动配置”，不是“Pi 能否修改这个仓库”。

AGENTS.md 和 CLAUDE.md 默认会作为上下文加载，即使项目没有被信任。不要把不可信仓库中的指令文件当成安全内容。

推荐的本地工作方式

1. 从干净工作树开始

git status --short
git switch -c task/my-change

已有未提交修改时，先理解它们属于谁、是否可以被覆盖。

2. 第一个请求保持只读

先不要修改文件或执行安装命令。概览项目结构、检查命令和潜在风险。

这既验证环境，也让你看到 Pi 对项目的理解是否正确。

3. 明确允许范围

一个好的修改请求应包含：

• 可以修改哪些文件或目录
• 什么结果算完成
• 必须运行哪些验证
• 哪些动作明确禁止

例如：

只修改 docs/ 下的 Markdown，修复相对链接。
不要安装依赖或更改配置。完成后运行文档构建并汇报结果。

4. 独立检查结果

git status --short
git diff --check
git diff --cached --check
git diff
git diff --cached

状态为 ?? 的未跟踪文件要单独检查。再运行项目自己的测试、类型检查和构建。模型说“已完成”不是验证证据。

什么时候必须使用隔离环境

下面任一情况成立时，优先使用容器、虚拟机、微型 VM 或策略沙箱：

• 仓库来源不可信。
• 任务需要运行未知安装脚本或二进制文件。
• Pi 会无人值守运行较长时间。
• 工作目录之外存在高价值凭据或私人文件。
• 任务不需要公网，但宿主机默认可以访问公网。

隔离时遵循最小权限：

• 只挂载任务所需目录。
• 不要默认挂载 ~/.pi/agent。
• 只传入必要、最好是短期的凭据。
• 不需要网络时关闭网络。
• 需要保护宿主文件时使用只读挂载或复制进出。

具体模式见 Pi Containerization。

凭据

Pi 可以从 /login 保存的认证、环境变量和 auth.json 读取凭据。建议：

• 不在提示词中粘贴真实密钥。
• 不把密钥写进版本控制。
• 不让不可信扩展访问包含凭据的进程环境。
• 分享或导出会话前检查内容。
• 发现泄露后立即轮换，而不是只删除日志。

第三方扩展与 Pi 包

扩展是与 Pi 同进程、同权限运行的代码。安装前检查：

1. 发布者与仓库来源。
2. 安装脚本和依赖。
3. 是否读取文件、环境变量或网络。
4. 最近维护状态与版本固定方式。

“功能只是一个主题或命令”并不意味着它没有代码执行权限。

在 Vue 或浏览器中集成 Pi

这份文档站使用 Vue 3，但 Pi CLI 本身运行在 Node.js 终端环境。如果你另外构建 Pi Web 客户端：

• 不要把供应商 API Key 放进 VITE_*、客户端 .env 或浏览器存储。
• 不要把 @earendil-works/pi-coding-agent CLI SDK 直接打进浏览器。
• 浏览器侧可以使用面向 Web 的 pi-ai / pi-agent-core 能力，但生产请求应经过你控制的后端代理。
• 后端必须负责认证、模型白名单、限流、审计和供应商密钥保管。

上游的浏览器打包检查证明核心包可以被 bundler 处理，不代表把供应商密钥暴露给浏览器是安全的。

最小安全检查表

• [ ] 当前目录正确，工作树状态已确认。
• [ ] 仓库与项目本地扩展可信。
• [ ] 任务范围、禁止动作和完成标准已写清。
• [ ] 高风险凭据没有暴露给任务环境。
• [ ] 不可信或无人值守任务运行在隔离环境。
• [ ] 修改由 git diff 和真实检查命令独立验证。

继续阅读：

• 用配置与扩展选择风险更低的定制机制。
• 在动手前从六个工程工作流复制带范围和验证条件的任务。
• 出现异常时按故障排查收集最小证据。
• 构建 Web Agent 时查看 SDK 与 Vue 最小集成。
• 以 Pi 官方 Security核对上游安全说明。