Pi Pocket 安全模型完全清单:它保护什么、不保护什么
Pi Pocket 安全模型完全清单:它保护什么、不保护什么
Pi Pocket 是一个自托管、多人协作、移动端优先的 Pi 编码代理(coding agent)Web 应用。因为它会让 AI 直接在你机器上执行命令、读写文件、访问网络,所以安全模型是新手必须搞懂的核心话题。这篇文章用一张"保护/不保护"清单,帮你 3 分钟看清 Pi Pocket 的权限边界,避免误把共享会话当成沙箱。
先搞懂:为什么 Pi Pocket 需要一套安全模型
Pi Pocket 的核心卖点是"把 Pi 编码代理装进口袋":durable(持久化运行)、multiplayer(多人实时共享同一个会话)、mobile-first(手机优先)。代价是——
- 服务器跑在你的机器上,以你启动它的那个系统用户身份运行。Pi 执行的每条命令、读写的每个文件,权限都等于你自己。
- 任何能"steer(操控)"会话的人,都能让 Pi 调用该会话里的所有工具,包括只被邀请进某一个会话的访客。
- git worktree 只是隔离文件,不是沙箱:Pi 依然能碰到你机器上它能碰到的一切。
官方把这套规则完整写在 SECURITY.md 的"What Pi Pocket protects, and what it does not"一节,给扩展作者看的细则在 docs/extensions/policies/security-model.md。
Pi Pocket 保护了什么
1. 登录与令牌:链接即钥匙,泄露可一键失效
- 邀请链接是一次性的,有效期可选 15 分钟、1 小时、1 天或 1 周;有效期越长,泄露风险窗口越长。
- 邀请码和令牌随机生成、哈希后存储,令牌放在
HttpOnlycookie 里(见 src/server/auth.ts),JS 无法读取。 - cookie 是 host-only 的:
127.0.0.1和localhost在浏览器里是两个不同主机,一个地址的登录不会"串"到另一个。 - 只有 owner 能签发 owner 邀请(固定 15 分钟,直接授予完整控制权);加
--rotate-token启动可让所有旧设备下线、作废旧 owner 邀请。
2. 角色权限:viewer 绝对碰不到 Pi
| 角色 | 能做什么 | 不能做什么 |
|---|---|---|
| Owner | 一切:审批、邀请、装扩展、管令牌 | — |
| Guest(可 steer) | 操控 Pi、批准工具调用 | 改变自己的访问范围 |
| Viewer | 读、发反应、参与旁聊(Pi 看不到) | 让 Pi 做任何事 |
会话旁聊(side chat)是 Pi 看不到的,但注意:guest 发的普通消息会给 Pi,旁聊才是私密通道。
3. Lancet Guard:给危险命令加一道人工审批
Lancet Guard 默认关闭,在 Menu → Extensions 打开。开启后,每次 bash、write、edit 调用都会被规则和分类器检查,"risky"调用会弹出 Allow/Deny 审批卡片(答案跨重启保留)。
几个关键细节:
- 默认任何能 steer 的人(包括发起者本人)都能批准自己引出的危险调用;owner 可打开"Approvals need someone else"(Menu → Extensions),让这类调用必须换人批准。
- 推送通知里的 Allow 只提供给一行显示得下的短命令,长命令必须打开应用审批。
- 0.22.0 起,扩展可以弹"问答卡片"(验证码、key、CAPTCHA):只有 Pi 当前服务的那个人能填,填的内容只给该扩展,不进 Pi 的上下文和记录。
4. 内置浏览器:能上网,但够不到应用本身
内置浏览器在服务器上用 Chromium 运行(而不是你的浏览器),所以页面拿不到应用的 cookie 和 API。它能访问 localhost、内网和互联网,且 Lancet Guard 不检查它——所以如果 guest 不应该碰到你的内网,直接在 Menu → Extensions 里把 Browser 关掉。只有 owner 能从地址栏打开本地文件、查看机器上正在运行的服务。
5. 回复与产物:Pi 说的话默认不可信
- 应用页面不从其他站点加载任何东西,Pi 的回复被清洗:不能包含表单、脚本、样式。
- 回复里的 HTML 块先以"脚本关闭、不加载任何资源"的独立 frame 预览;点 ▶ Run 才进 artifacts 沙箱——有脚本和网络,但没有应用的任何权限。
- 共享的 artifact(
/pub/<token>)是同样的沙箱页,免登录,但令牌就是全部访问权,在结束前要把地址当秘密。 - SVG 一律只当图片渲染,不执行任何东西。
6. 扩展与画廊:装进来之前,先看清它
~/.pi-pocket/extensions/里的 drop-in 扩展以 owner 的完整权限运行在服务进程内,没有沙箱,默认关闭、只有 owner 能开启。- 扩展画廊(Menu → Extensions → Find extensions)只做别人能做的:严格解析索引、只走 https、下载每个条目固定 commit 的文件、逐文件核对 SHA-256、文件名不出目录、装完一律关闭、从不自动更新。
- 官方建议:开启前读一遍源码,或让 Pi 帮你 review。主题类条目会被检查后安装,不能加载外部资源、不能跑代码——但仍能遮挡或改标签(包括审批按钮),只装你信任的。
7. 关联会话(Agent Teams):把 prompt injection 的半径圈住
会话读了恶意网页/文件后,可以把内容"传话"给团队的其它会话。Pi Pocket 的对策是:
- 消息被 fence(防注入围栏)包裹,Pi 被告知"这是请求,不是某人的命令"——这是模型指引,不是硬边界;
- 一个 team 的花费计入起始会话的预算,超支即停;
- 链接不授予任何额外访问权:看不到源会话的人,连"它从哪来"都看不到。
Pi Pocket 不保护什么(重点看这里)
一句话:能 steer = 你的键盘。 下面的每一条都不是缺陷,而是边界。
- worktree 不是沙箱:它只把会话的文件隔开,不限制 Pi 的访问范围。
- spend limit 不拦危险操作:它只在越过限额的那次请求之后才停止运行,不是事前熔断。
- Plan mode 不是边界:它只约束 Pi 的计划行为;你配置成自启的程序照常运行,人的
!shell 命令也照跑。 - Lancet Guard 有盲区:它看不到扩展自己的代码行为(读文件、开进程、发网络请求)、扩展工具内部执行的命令、路由/命令/浏览器模块,以及内置浏览器。
- 模型选择防的是 Pi,不防人:Pi 从不私自挑模型(subagent 只能用会话模型或 owner 在 Providers → Models for subagents 里勾选的清单),但任何能 steer 的人都能改会话模型,而且能跑命令的 Pi 同样能碰到 Pi 自己的登录态。
- 会话级邀请限制的是"看到什么",不是"Pi 能碰到什么":只被邀请进一个会话的人,依然能让 Pi 触达你机器上的文件、Pi Pocket 的配置和令牌。
一张表总结:保护 vs 不保护
| 场景 | ✅ 保护 | ❌ 不保护 |
|---|---|---|
| 登录 | 一次性链接 + 哈希存储 + HttpOnly cookie + --rotate-token 全量失效 |
链接在有效期内泄露(15 分钟~1 周) |
| 他人操控 | 角色隔离,viewer 完全不能操作 Pi | guest(含单会话邀请者)的 steer 权限等同你本人 |
| 命令执行 | Lancet Guard 审批(可要求换人批准) | 扩展代码、内置浏览器、人的 ! 命令 |
| 网页内容 | 回复清洗、artifacts 沙箱、页面拿不到应用 cookie | 内置浏览器可访问你的内网和 localhost |
| 花钱 | 会话/个人 spend limit、team 共享预算 | 限额前的请求、Pi 主动挑选模型的开销 |
| 扩展 | 画廊 SHA-256 校验、装完默认关闭 | drop-in 运行时的完整 owner 权限(无沙箱) |
新手安全清单(照着做就够)
- 只邀请你愿意坐在你键盘旁的人;能给 viewer 就别给 guest。
- 给 guest 的场景关掉 Browser 扩展(Menu → Extensions),内网即安全一堵墙。
- 打开 Lancet Guard,多人协作时再开"Approvals need someone else"。
- 给会话和人设 spend limit,给会开 team 的会话单独设预算。
- 装扩展/画廊条目前先读源码,关闭后它会从应用里完整撤下。
- 令牌怀疑泄露就
--rotate-token重启,所有设备强制重新登录。 - 发现"viewer 能操作 Pi""回复碰到了应用 cookie"这类越权,属于官方明确列出的 bug,应私下通过 Security → Report a vulnerability 报告,不要开公开 issue。
延伸阅读
- 权威安全声明:SECURITY.md
- 扩展作者版安全模型(S1–S8 规则与出处):docs/extensions/policies/security-model.md
- 认证实现(邀请、cookie、旋转):src/server/auth.ts
- Lancet Guard 扩展:src/server/extensions/guard.ts
- 完整功能巡礼:docs/features.md


