上线前 —— 信任、可写、环境三条边界
Part F 讲了九章「怎么配」。最后一章反过来问一句: 这套东西跑起来之后,它到底能碰到什么?
Pi 的立场写在 security.md:3 第一句——把模型生成的命令和代码当作不可信。
这不是免责声明,是设计前提:它不会在每次工具调用前问你。
三个问题:
- 项目信任挡住了什么?没挡住什么?
- 那些
PI_*环境变量里,哪些会改变安全行为? - 无人值守跑一夜,该改哪几处?
一、信任边界:它挡的是「自动加载」,不是「动手」
security.md:29 一句话说清了:项目信任控制的是
工作目录提供的大部分设置和资源要不要加载,
目的是防止一个目录在你批准之前就悄悄加载可执行扩展。
它不是一道完整的启动边界,有两个明确的缺口:
- Pi 在决议信任之前就要读项目的
sessionDir设置——因为得先选出会话文件 (security.md:31)。拒绝信任也撤不回这一次目录查找。 - 信任不限制工具调用能访问什么。启动之后,启用的工具用的是 Pi 进程的操作系统权限(
:33)。
1.1 哪些资源会触发信任询问
security.md:39-43 列了六类:
| 资源 | 需要信任 |
|---|---|
.pi/settings.json |
是 |
.pi/mcp.json |
是 |
.pi/extensions / .pi/skills / .pi/prompts / .pi/themes |
是 |
.pi/SYSTEM.md / .pi/APPEND_SYSTEM.md |
是 |
当前目录或祖先目录里的项目 .agents/skills |
是 |
只存在一个空的 .pi 目录 |
否 |
最后一条值得记:建目录不会弹窗,放文件才会。
1.2 决议顺序
security.md:61-65 的顺序是四段,和 F01 那章说的五道卡对得上:
| 顺序 | 依据 |
|---|---|
| 1 | 命令行 --approve / --no-approve |
| 2 | 扩展处理 project_trust 事件,第一个返回 yes/no 的说了算 |
| 3 | ~/.pi/agent/trust.json 里当前目录或其父目录的已存决议,最近的生效 |
| 4 | 全局设置 defaultProjectTrust,默认 "ask" |
1.3 非交互环境下这个弹窗不存在
这一条是上线时最要紧的:Print、JSON、RPC 三种模式没有内置信任弹窗
(security.md:77-82)。前三段都没给出决议时:
defaultProjectTrust |
结果 |
|---|---|
"always" |
加载受保护的项目资源 |
"ask" |
跳过 |
"never" |
跳过 |
也就是说 "ask" 在无 UI 的场景下等于拒绝。要一次性的明确决定,用 --approve。
1.4 上下文文件永远加载
security.md:57:AGENTS.override.md、AGENTS.md、CLAUDE.md
这类上下文文件不受项目信任约束,除非你显式关掉。
这条和 F04 呼应:AGENTS.md 的探索链是「无门槛」的一层。
拒绝信任不能阻止一个仓库往你的提示词里塞指令,只能阻止它塞可执行代码。
二、可写边界:工作目录不是围栏
这是最容易被误解的一条。security.md:19 写得很直接:
The working folder controls resource discovery and the default location for tools, but it does not prevent commands from accessing other paths.
工作目录决定三件事:资源发现、上下文文件、会话分组。它不限制路径访问。
启动 pi 时的 cwd 只是「默认起点」,不是「沙箱根」。
真正能收窄范围的只有系统层隔离。security.md:13-17 分三档:
| 跑法 | 保护到什么 |
|---|---|
| 直接用操作系统用户权限跑 | 只有该用户访问不到的东西受保护 |
| 整个进程放进容器 / 虚拟机 / 沙箱 | 你没暴露进去的宿主文件与进程(通常是最实际的选择) |
| Pi 在宿主,只把内置工具丢进隔离环境 | 只有「通过那些工具做的事」受保护;Pi 自己和其它扩展仍在边界外 |
第三档的细节在 containerization.md:16:用 Gondolin 把内置工具代理进
本地 micro-VM 时,其它扩展的工具仍在宿主上跑,除非它们也做了代理。
2.1 ! 与 !! 也在同一权限下
usage.md:70-76:!cmd 跑命令并把输出带进上下文,!!cmd 跑但不进上下文。
两者都是你的 shell 权限。!! 只是「不给模型看」,不是「更安全」。
三、环境边界:PI_* 全表
环境变量分三类(environment-variables.md:3-7):配置 Pi 进程的、
给子进程打标记的、以及注入到 shell 工具里的会话信息。
3.1 两个进程标记
| 变量 | 值 | 用途 |
|---|---|---|
AI_AGENT |
pi |
通用标记,让工具知道「这是 pi 拉起来的」 |
PI_CODING_AGENT |
true |
Pi 专属标记 |
子进程都继承它们,但通过 SDK 嵌入时不自动设置(:18)。
做 CI 时如果想用这两个标记判断「是不是在 agent 里」,SDK 场景要自己设。
3.2 会话变量:让工具知道自己是谁
bash 和 powershell 工具跑的命令会拿到五个变量(:24-30):
| 变量 | 内容 |
|---|---|
PI_SESSION_ID |
当前会话 ID |
PI_SESSION_FILE |
会话 JSONL 绝对路径(临时会话没有) |
PI_PROVIDER |
当前 provider |
PI_MODEL |
当前模型 ID |
PI_REASONING_LEVEL |
当前推理档位,七档之一 |
两个要点:值在每条命令启动时解析,所以切模型立刻对下一条命令生效;
以及用户手打的 ! / !! 命令拿不到这些变量(:49)——它们只注入给模型调用的工具。
这也是 :34 那句建议的由来:问「现在用哪个模型」,查 PI_MODEL,
别从系统提示词里猜。
3.3 会改变安全与行为的变量
environment-variables.md:79-101 一长串,按上线关注度挑出来:
| 变量 | 影响 |
|---|---|
PI_CODING_AGENT_DIR |
换配置目录,默认 ~/.pi/agent。换它等于换一整套凭据和信任记录 |
PI_CODING_AGENT_SESSION_DIR |
换会话存储,被 --session-dir 覆盖 |
PI_PACKAGE_DIR |
换包目录(Nix / Guix 场景) |
PI_OFFLINE |
关掉自动联网,含模型目录刷新 |
PI_SKIP_VERSION_CHECK |
关掉 pi.dev 的版本查询 |
PI_TELEMETRY |
覆盖安装/更新遥测与 provider 归属头 |
PI_CODEMODE_MAX_WORKERS |
codemode worker 上限,默认 2,每个最多 256 MB |
PI_CACHE_RETENTION=long |
延长 provider 端提示词缓存 |
PI_SHARE_VIEWER_URL / PI_RADIUS_GATEWAY |
覆盖 /share 与 /bug 走的地址 |
后两个值得单独说:它们能改变「你的会话被上传到哪」。共享前先确认这两个地址。
PI_OFFLINE 的判断散落各处,取值只认 1 / true / yes
(package-manager.ts:63-67 就是一个例子),写 TRUE 也行,写 on 不行。
3.4 宿主提供的包裹在 peerDependencies
这条上一章说过,这里补一个安全视角:宿主包里包含 agent 核心与工具实现。
如果允许一个第三方包自带物理副本,你实际运行的可能不是 Pi 的那份代码。
packages.md:114 说 Pi 检测到这种清单会直接给扩展警告,不是风格建议。
四、上线自检表
把前面九章的内容压成一张可勾选的表。按顺序过一遍,基本覆盖了所有会踩的坑。
身份与凭据
- [ ]
.pi/settings.json里的模型走的是哪个端点?是不是我认可的那个(F02) - [ ]
models.json里有没有!command去执行本地程序?确认那是预期的 - [ ]
ANTHROPIC_API_KEY这类变量是用短期窄权限的,不是主账号的长期 key
加载面
- [ ] 项目里的
.pi/extensions和.pi/mcp.json我都读过一遍(security.md:90) - [ ]
AGENTS.md链里没有要求「忽略之前的指令」之类的内容 - [ ] 装了哪些包?
pi list的输出和我的预期一致(F08)
动作面
- [ ] 默认工具集是四个还是更多?开
grepfindls会不会改变提示词里的行为指导(F03) - [ ]
codemode开了吗?如果开了,脚本能调的工具范围符合预期(F07) - [ ] 有没有权限扩展兜底?无人值守时
ctx.hasUI是假,拦截返回什么(F05)
边界
- [ ] 无人值守跑的是交互模式还是
-p/--mode json?后两者没有信任弹窗(F09) - [ ]
--approve还是defaultProjectTrust: "always"?只给这一次还是永久 - [ ] 有没有把
~/.pi/agent挂进容器?那等于把凭据、设置、会话全暴露(containerization.md:23) - [ ] 宿主挂载是读写还是只读
收尾
- [ ] 会话文件会留多久?里面可能有凭据片段(
security.md:93) - [ ]
/share会把会话传到哪?PI_SHARE_VIEWER_URL有没有被改过
五、自己动手验证
实验 1:看 "ask" 在无 UI 下等于拒绝。
在一个带 .pi/settings.json 的项目里(defaultProjectTrust 保持默认),跑:
pi --mode json -p "x" > t.jsonl然后看事件流里有没有项目设置生效的痕迹——比如你在 .pi/settings.json
里设了一个非默认的 defaultTools,看 sections.tools 是否变化。
不加 --approve 时应该没变;加上之后应该变。
实验 2:确认上下文文件不受信任约束。
同一个项目里放一个 AGENTS.md,写一行显眼的标记句(比如「本章标记:ALPHA」)。
不加 --approve 跑一次 --mode json,在系统提示词里搜 ALPHA。
它会出现——这正是 security.md:57 说的那条。
实验 3:看会话变量注入到哪。
在交互模式里让模型跑一句 echo $env:PI_MODEL(走 bash/powershell 工具),
再自己手打 ! echo $env:PI_MODEL。前者有值,后者为空——
environment-variables.md:49 的差别就这么被验证。
改一处试试
把 PI_CODING_AGENT_DIR 指向一个新目录,再跑 pi:
$env:PI_CODING_AGENT_DIR = "$HOME\.pi-agent-test"; pi --list-models你会发现模型列表、凭据、信任记录全都没有了——因为那是另一套配置目录。 这条命令能最快让你理解「配置目录」这一层的分量。
六、工程暗坑
坑一:以为批准了项目信任就安全了。
它只管加载,不管动作。工具仍以你的系统权限跑(security.md:7)。
坑二:以为 cwd 是沙箱根。
它只是资源和会话的默认位置。命令能去任何你有权限的路径。
坑三:defaultProjectTrust: "always" 图省事。
这是把「每次同意」换成「永远同意」,项目里换一个扩展你就看不见了。
自动化场景优先用 --approve,只给这一次。
坑四:!! 当安全手段。
它只是不进上下文。命令照样执行,权限一样。
坑五:容器里挂 ~/.pi/agent。
凭据、设置、扩展、会话一次性全暴露给容器内的任意代码。
只挂工作目录,凭据按需单独传(containerization.md:23)。
坑六:PI_OFFLINE=true 写成别的值。
只认 1 / true / yes,写 on 等于没设。这类布尔解析在源码里散落多处,值得统一。
坑七:SDK 里指望 AI_AGENT 已设。
SDK 嵌入不自动设置进程标记(environment-variables.md:18)。
七、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/coding-agent/src/core/project-trust.ts |
98 | 信任决议的四段顺序 |
packages/coding-agent/docs/security.md |
99 | 三档隔离、受保护资源、静默决议 |
packages/coding-agent/docs/environment-variables.md |
103 | PI_* 全表与三类用途 |
packages/coding-agent/docs/containerization.md |
184 | 四种隔离方式与暴露面 |
packages/coding-agent/docs/usage.md |
95 | ! / !! 的语义 |
packages/coding-agent/src/core/package-manager.ts |
2,907 | PI_OFFLINE 的实际解析 |
八、Part F 收尾
十章的路线是这样的:
| 章 | 回答的问题 |
|---|---|
| F01 | 配置写在哪个文件,谁说了算 |
| F02 | 模型从哪来,凭据从哪读 |
| F03 | 模型能动手做多少事 |
| F04 | 模型怎么知道这个项目的规矩 |
| F05 | 扩展怎么落位、怎么拦和改 |
| F06 | 扩展怎么造工具、状态存哪 |
| F07 | 怎么接别人的工具、怎么写脚本 |
| F08 | 怎么打包给别人装 |
| F09 | 怎么从别的程序里驱动它 |
| F10 | 上线之前该确认什么 |
一句话概括整个 Part F:Pi 把所有旋钮都放在文件里,代价是你得知道每个旋钮在哪。
默认值基本够用,一旦要定制,就回到源码找那个 ?? "默认值"——
这本书每一章末尾的源码索引,就是为了这个。