Pi Agent 源码级教程
F10

上线前 —— 信任、可写、环境三条边界

2,499 字 · 含 2 行代码 · 约 17 分钟

Part F 讲了九章「怎么配」。最后一章反过来问一句: 这套东西跑起来之后,它到底能碰到什么?

Pi 的立场写在 security.md:3 第一句——把模型生成的命令和代码当作不可信。 这不是免责声明,是设计前提:它不会在每次工具调用前问你。

三个问题:

  1. 项目信任挡住了什么?没挡住什么?
  2. 那些 PI_* 环境变量里,哪些会改变安全行为?
  3. 无人值守跑一夜,该改哪几处?

一、信任边界:它挡的是「自动加载」,不是「动手」

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)

动作面

  • [ ] 默认工具集是四个还是更多?开 grep find ls 会不会改变提示词里的行为指导(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 保持默认),跑:

powershell
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:

powershell
$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 把所有旋钮都放在文件里,代价是你得知道每个旋钮在哪。 默认值基本够用,一旦要定制,就回到源码找那个 ?? "默认值"—— 这本书每一章末尾的源码索引,就是为了这个。