权限、隔离,以及什么让一个智能体值得被构建
收尾的论证:能力不是权限;一道边界必须及时行动,并且位于它所约束之物的触及范围之外;由被检查方选定的值不能充当检查的闸门;以及每个需求属于从指令到宿主遏制这四级台阶中的哪一级。
到这里为止,一切都是机制。工具、扩展、事件、会话、模式、协议。本章讲的,是那个把一组机制变成你愿意让它靠近一个生产仓库的东西的、唯一一个问题,以及那时你能做出哪些论断。
两个论断撑起本章。能力不是权限: Pi 几乎能做启动它的那个账户能做的任何事,而若干个有文档记载的机制关系到它是否应该做某件特定的事。它们中没有一个是沙箱,而它们全都是真实的。而本书里几乎没有任何东西是权限边界,除了操作系统边界。 其余一切都是流程、闸门或约定,而一个流程可以被设计得很好,同时仍然是一个流程。
本章用两项测试挣得第二个论断——一个机制必须通过它们才配被称作一道边界——外加一条关于谁被允许供给一道闸门所依赖的那些事实的原则。
两条规则,以及它们为何指向相反的方向
第 11 章给出了一条关于行为的规则和一条关于放置的规则:
使用能解决这个需求的最弱机制。把决策放进拥有它的最窄那一层,并且只放进一个能在该决策变得不可逆转之前行动的层。
本章补上关于权限的规则:
在仍能阻止那个后果的最低边界上,强制执行一项禁令。
它们看上去像是相互矛盾。第一条说:只在你必须时才往上爬,从一个文本文件开始。第二条说:尽可能往下走,走到操作系统。它们并不矛盾,因为它们回答的是不同的问题。行为规则问的是让智能体做这件事,最便宜的办法是什么? 权限规则问的是如果智能体、模型,以及它上面的代码同时都错了,这件事能在最低的什么地方被强行成立?
用错其中一条,会以一种可识别的方式失败:
| 被误用的规则 | 你最终得到的东西 |
|---|---|
| 把行为规则用在一条禁令上 | “永不部署到生产环境"写在 AGENTS.md 里。最便宜的机制,却拦不住任何东西 |
| 把权限规则用在一条约定上 | 用一个容器来强制执行一套风格指南。强大、昂贵,且没有对准任何东西 |
大多数真实的需求都有这两半,而它们是在不同的级台阶上被满足的。“用我们的测试命令,并且永不推送到发布分支"既是一条约定,也是一条禁令。约定属于文本。禁令属于低处。第 11 章的推演案例 4 正是这个形状,而本章余下部分讲的,就是每一半该去哪儿,以及每一级台阶能诚实地论断什么。
第五部分构建了什么,以及它没构建什么
第 36 到 41 章构建了一个论断检查器(claim checker):一次返回类型化值的模型调用、一个带查找工具的智能体循环、一个无法以散文结束的类型化步骤、一张智能体内核上每个钩子的地图、一条只在便宜的那部分无法决定时才花费昂贵部分的流水线,以及一种测量它多常有效的方式。
它们每一个都是能力。没有一个是权限,而这个论断检查器是安全的,其原因你说得出名字:它唯一的工具 lookup_evidence,读你传进去的一个语料库,别的什么都不做。那是下面那架梯子上第 2 级台阶最强的控制,“不要授予这个能力”,而它之所以是默认,是因为内核不附带任何工具。第 39 章的最后一行说出了其余部分:智能体内核里没有一个钩子能撤销一个效果,而唯一一个能拒绝效果的钩子 beforeToolCall,只能在它发生之前、并且只对着你写下的那张表这么做。
给那个智能体加一个 write_file 工具,那么在它之前的五章里,没有任何一章告诉你它是否应该被允许。那就是本章回答的问题,既针对编码智能体,也针对你在内核之上构建的任何东西。
Pi 拒绝称之为边界的东西
security.md 在第一段陈述了这个立场:
把模型生成的命令和代码当作不可信的。Pi 能以启动它的那个账户的权限读取、更改并执行文件,而它不会在每次工具调用之前都征求批准。
usage.md 从用户那一侧重复了它:“Pi 不会在每次工具调用之前都问。审阅命令和更改过的文件,并对不可信或无人值守的工作使用沙箱。”
然后是那一句从今往后应当支配每一个设计决策的话:
监视转录记录、使用项目信任,以及审阅更改,都不会构成一道安全边界。
它指向安全实际上来自何处:“限制 Pi 能访问和影响的文件、凭据、进程和网络服务,以防一个生成的动作出错或带有敌意。” 安全是环境的一个属性,而不是转录记录的属性。
项目信任是一道启动闸门,不是一个沙箱
这个机制最常被人过度信任。security.md 准确地说明了它的目的——“它防止一个文件夹在你批准它之前静默加载可执行的扩展”——然后把这一节的大部分篇幅花在它买不到什么东西上。第 8 章有完整说明,并且实际运行了它。它的三个结论承载着本章的论证。
- 上下文文件照样加载。 拒绝信任阻止的是可执行的配置,而不是指令,所以一个文件夹仍然能引导模型。第 8 章观察到了它:当项目不被信任时,它的扩展和提示词模板不加载,而它的
AGENTS.md仍然会。这是一个有意的分离,而且是正确的那个,因为一个AGENTS.md不能运行代码,却仍然能引导。它也是为什么指令不是权限的最清晰的例子:你没写过的文本,通过与你写过的文本相同的通道到达。 - 信任对之后的行为什么都没说。 “项目信任不限制工具调用能访问或影响什么。Pi 启动之后,已启用的工具仍然使用 Pi 进程的操作系统权限。”
- 一道启动闸门有一个例外。 项目
sessionDir在信任被解析之前就被读取。
而你无法让项目自己决定它是否被信任。extensions.md 只允许个人的、以及显式的命令行扩展来处理 project_trust,因为那个事件在项目扩展加载之前运行。
梯子:四级台阶
Pi 的各种机制,按当后果正在到来时它们还能改变什么分成四级台阶。这个分类是本书的提议。放在它上面的每一个事实都是有文档记载或已观察的,而放置本身是经过论证的。
4 宿主遏制 操作系统、一个容器或虚拟机、进程一开始拿到的
凭据和网络
3 运行时拦截 在一个效果之前运行并能拒绝它的代码:
beforeToolCall、一个 tool_call 处理器、宿主里的一道闸门
2 智能体策略 智能体被给到的东西:哪些工具存在、它们的 schema、
模式、任何工具自报的风险
1 指令 模型读到的文本:AGENTS.md、系统提示词、
一个技能、一个提示词模板
第 4 级台阶在权限规则所用的意义上是最低的:离后果最近,且最难从上面够到。这些数字的运行方向与"力量"相反。一条指令是最弱的机制,也最便宜,这就是行为规则从那里开始的原因。
第 1 级台阶:指令
一条指令改变模型可能提议什么。它不改变什么能执行。本书中有两样东西在没有模型的情况下展示了这道鸿沟:上面第 8 章的观察,即一个不被信任的文件夹的 AGENTS.md 仍然会加载;以及第 39 章的,即站在一个被提议的调用和它的效果之间的唯一东西是代码。一条说"绝不要调用 forbidden_action“的提示词,并不在 execute() 的路径上。
此处未用真实模型测量。 本书还没有真实模型的证据,所以一个模型在压力下是否会、以及多常无视一条明说的禁令,不是它能告诉你的。这个结构性论点不依赖于答案:即使一个模型从不提议这个调用,这个转变仍然是可执行的。
把指令用在它擅长的事情上,也就是引导、约定和解释。不要把它用在一条必须成立的禁令上。
第 2 级台阶:智能体策略
智能体策略是你在运行之前决定的东西:哪些工具存在,带着哪些 schema。-nbt 和 -nt 剥除得更多,而 --tools 点名一个确切的集合(cli.md)。
准确说出这样一个旗标买到了什么东西,因为"哪些工具存在"是两个并排放着的不同论断,而其中只有一个关乎模型。
它决定什么:模型可以调用什么。 --tools read,grep,find,ls 声明四个工具,并把 bash、edit 和 write 扣住不给模型。模型没有被给到的一项能力无法被调用,无论它怎么决定,而这就是为什么这是智能体之内最强的控制。它是一次真实的削减,值得拥有。
它不决定什么:进程能触及什么。 Pi 是一个以你的身份运行的程序。--tools 配置的是模型的词汇;它不改变 Pi 进程的操作系统权限,也不约束那些没有请求被授予一个工具的代码。任何已经加载的东西——一个扩展、一个被告知要模型去运行的技能打包脚本、你自己的宿主代码——都保有它在那个旗标之前就有的相同访问权。这一级台阶上没有任何东西是遏制。遏制是第 4 级台阶,而这个区分正是本章的主题。
两个后果随之而来,而两者都容易搞错:
- MCP 缺口是第一个论断的一部分,而不是对它的一个告诫。 自 1.0.4 起,
--tools会保留 MCP 工具,除非某个条目以mcp__开头。所以在一台配置了 MCP 服务器的机器上,单用pi --tools read,grep,find,ls并不产生一个四工具智能体——那些服务器的工具仍然注册着,并且在它们的暴露方式上可达。--no-mcp才是让四工具这个论断成立的东西,而它是命令的一部分,而不是它的一个脚注。点名你想要的服务器、丢掉其余的(--tools read,bash,'mcp__radius__*')是选择性的版本。 - 一个更窄的模型词汇并不会收窄一个 shell。
bash能运行账户能运行的任何命令,所以一个包含bash却省掉write的列表并没有移除写入。这一级台阶上的问题从来不是"我省掉了哪些工具”,而是"我留下的那些工具合起来能触及什么”。第 37 章从下面展示了同一件事:内核不附带任何工具,所以论断检查器唯一的触及范围就是你交给它的那一个工具。
这个限制是闭合(closure),而它有一个值得使用的名字:你约束住的是智能体的词汇,不是它的触及范围。如果任何一个被授予的工具能做被扣住的那个工具能做的事,那么被扣住的那个工具从未被扣住。只有第 4 级台阶约束触及范围。
第 3 级台阶:运行时拦截
这是本书中证据最多的一级台阶,因为第 39 章测量了它。一个拦下一次调用的 beforeToolCall 意味着 execute() 运行零次,而那个副作用不存在。一个改写结果的 afterToolCall 太晚了:execute() 已经运行了一次。在编码智能体里,同一个接缝是 tool_call 事件,而第 16 章在它上面运行了一个守卫:在没有 UI 可问的情况下,它拒绝一次强制推送,而那条命令从不运行;一个会抛出的处理器作为一道失效安全(fail-safe)拦住这个工具。
那么它是什么:一道在效果之前行动、并且能说不的闸门。它不可能成为的,是比它看到的那次调用更多的东西。本书的三个观察标出了它的边界。
- 它判定一个表示。 第 11 章的那个守卫最初用一个看着对、却从不在一次普通的
git push上触发的模式匹配git push,因为处理器测试的是序列化后的输入——{"command":"git push origin main"}——在那里git跟在一个引号后面,而不是空白字符后面。它只为复合命令触发。一道作用于命令字符串的闸门是一个流程:它拦住的是它的作者预料到的那些拼写。 - 它判定一个名字。 第 21 章观察到,一个 MCP 工具被命名为
mcp__<server>__<tool>,而一道按名字设键、却忘了前缀的闸门会放它过去。 - 它看不到这次调用之外的东西。 一次被许可的
bash调用就是被许可了。进程随后用它拥有的权限做什么,不是那道闸门的事,这就是为什么一道仔细确认bash的闸门不能替代限制进程能触及什么。
闸门运行在哪里也很重要,而这是本书提出的,不是有文档记载的。一道与智能体同进程的闸门,以它所守卫的那些工具相同的权限运行。如果任何工具能写向闸门读取的某个东西,或者写向下次启动时加载的设置和扩展,那么这道闸门只是建议。更强的放置,是在模型所驱动的那个会话之外,在催生那些工具的进程里。强制执行绝不可被它所约束的东西触及。
第 4 级台阶:宿主遏制
security.md 把 Pi 能如何运行列成表格,而要紧的那一列是什么仍然受到保护:
| Pi 如何运行 | 什么仍然受到保护 |
|---|---|
| 直接运行,带着它那个操作系统用户的权限 | “那个用户无法访问的任何东西。” 一个专用的用户能收窄这一点,但 Pi “仍然与其他用户共享操作系统和网络” |
| 完全在一个容器、虚拟机或沙箱内部 | 你不暴露的宿主文件和进程;“如果你让凭据和网络服务在它内部可用,它们就仍然可访问” |
| 在隔离环境之外,只有它的内置工具在隔离环境内 | 宿主资源受到保护,不会受到通过这些工具执行的动作影响。“Pi 本身和其他扩展仍然在边界之外,所以这是一种更窄的隔离形式” |
containerization.md 补上了让最后一行具体化的那一列,即什么被隔离:
| 方法 | 什么被隔离 | 凭据处理 |
|---|---|---|
| 普通 Docker | Pi、内置工具、! 命令和扩展 |
传进容器的凭据 |
| Docker Sandboxes | Pi、内置工具、! 命令和扩展 |
provider 凭据留在宿主上,由代理替换 |
| OpenShell | Pi、内置工具、! 命令和扩展 |
受策略控制的凭据与推理路由 |
| Gondolin extension | 只有内置工具和 ! 命令 |
存储的 Pi 凭据留在宿主上,但命令继承宿主环境变量 |
最后一行教会其余各行,而它画出来比描述出来更容易看清:
flowchart TB
subgraph W["整个 Pi 进程都在边界内"]
HW["Host"] --> PW["Pi runtime"] --> AW["Agent"]
PW --> EW["Extensions"]
end
subgraph T["只有选中的工具在边界内"]
HT["Host"] --> PT["Pi runtime"] --> ET["Extension tools"]
PT --> VM["Container or VM"] --> BT["Built-in tools"]
end
Gondolin 把 Pi 留在宿主上,把内置工具路由进一个 Linux 微虚拟机,所以"其他扩展工具仍然在宿主上运行,除非它们也把工作委派出去。” 隔离不是二元的。它是一个你把哪些进程放进去、以及你把什么交给它们的问题:同一份文档坦率地说,“一个被隔离的进程仍然能影响你暴露给它的资源。” 它给出了整个进程的配方:一个以 Pi 为入口点的镜像、挂载的工作文件夹,以及一个给容器自己的 /root/.pi/agent 用的命名卷。改为挂载宿主的 ~/.pi/agent 会暴露你的凭据、设置、扩展和会话。Docker Sandboxes 补上了凭据这一维度,而 containerization.md 警告不要犯那个显而易见的错误:“不要在沙箱内部运行 /login,因为那会把一个真实的凭据写进去。”
有文档记载,未运行。 本书没有运行过容器或微虚拟机。它关于这一级台阶的论断是文档的论断,而它补上的唯一一样东西,是为什么这一级台阶是边界的论证:它是唯一一个无论运行了什么都限制后果能是什么的东西,而在它之上的任何东西都无法把它拓宽。
代价是粗糙。一个容器无法把一次好的 git push 和一次坏的分辨开。这就是为什么它是地板,而不是整个设计。
一道边界必须通过两项测试
把四级台阶并排放在一道边界必须做的两件事旁边。
| 级台阶 | 在后果之前行动? | 在它所约束之物的触及范围之外? | 所以它是 |
|---|---|---|---|
| 1 指令 | 否。 它改变被提议什么,而不是什么能运行 | 否。 模型能无视它,而模型读到的内容能与它矛盾 | 影响 |
| 2 智能体策略 | 是,对于一个从未被授予的工具 | 是,如果宿主构建这个列表,但它约束的是词汇,不是触及范围 | 一道关于能被调用什么的边界 |
| 3 运行时拦截 | 是。 第 39 章测量过 | 取决于它运行在哪里。在智能体的进程里,只是部分 | 一道关于它看到的那些调用的边界,当它位于触及范围之外时;否则是一个流程 |
| 4 宿主遏制 | 是:它限制后果能是什么 | 是:里面的进程无法把它拓宽 | 一道权限边界 |
第一项测试是第 1 章和第 39 章的:它能在后果变得不可逆转之前行动吗? 第二项是本章的:它所约束的东西能触及它,或选定它所依赖的那些事实吗? 只有第 4 级台阶无条件地通过两项,这就是本章第二个论断的一张表格化表述。这张表是本书提出的,由上面那些有文档记载和已观察的事实构建。
由被检查方选定的值不能充当检查的闸门
本章中最可迁移的想法,而它不是一个 Pi 能给到你的东西。Pi 只能给你材料。
由被检查方选定的一个值,不能充当那次检查的闸门。
如果一个工具、一个 MCP 服务器、一个包或模型声明了一个关于它自身的属性,而一道闸门依赖那个声明来决定是否检查,那么你本想约束的那一方,就决定了它被监视得多密切。它不必是恶意的。它只需要是错的,或者觉得这道闸门碍事。三个实例,而本书运行过其中两个。
一个工具自报的风险。 第 17 章引入了工具 annotations(readOnlyHint、destructiveHint、openWorldHint),以及 Pi 对一个缺失提示的默认值:“缺失的提示采用 MCP 的默认值:一个工具不是只读的,可能具有破坏性,并能触及一个开放世界。” 那个默认值朝危险的方向解析未知,这是解析它的正确方式。但它对一个不诚实的声明(而不是一个缺席的声明)毫无作用。第 21 章对照着 extensions.md 的批准扩展和一个脚本化的远端,观察到了两者:
{ name: "delete_everything", annotations: { readOnlyHint: true, openWorldHint: false } }, // a lie
assert.equal(liar.isError, false, "declared read-only and not: the gate believed it");
那个完全没有提示的工具在没有 UI 的情况下被拦下。那个自称只读、而实际并非如此的工具通过了,而服务器收到了那次调用。一道以工具自己的声明为键的闸门,被这个工具设了限。
一个由工具在 Pi 自己的类型内部填写的、关于它自身的字段。 AgentTool.replay 在 1.0.4 中被声明为一个效果的"恢复策略,该效果的持久意图存在、但其结果未知","never" 或 "safe":
const writeFile: AgentTool<typeof Params> = {
name: "write_file",
label: "write_file",
description: "write a file",
parameters: Params,
replay: "safe", // a claim by the inspected party
声明中没有任何东西检查 "safe" 对一个写文件的工具是否为真。而对 1.0.4 中 pi-agent-core、pi-coding-agent、pi-mcp 和 pi-codemode 已发布 JavaScript 的一次扫描(作为一次测试运行)发现,没有任何代码读取这个字段。已观察,且对版本敏感: 在这个版本里,它是一个没有读取者的声明,所以它目前什么都不把守。如果一个更晚的版本加上一个读取者,这个测试会失败,而那本章必须被重读。值得说明的是,如果一个宿主真的开始消费它,那会意味着什么。一个靠询问工具"重新运行它是否安全"来决定是否再次运行一个效果的宿主,就是在询问被检查方。
一个由模型提供的值。 一次工具调用的参数由模型选定,而一道闸门应当校验它们。一道闸门绝不能做的,是接受一个断言自身许可的参数:一个 confirmed: true 参数、一个 approved_by 字段、一个它当作充分理由的 reason 字符串。其行为正被检查的那一方,写出了证据。本书提出,此处未运行。
一个声明仍然有什么用
这一切都不会让一个声明变得无用。它让声明变成单向的,而那是一条你可以运用的规则:
一个自报的属性可以被用来请求更多的审视。它绝不能被用来授予更少。
一个自报自己具有破坏性、从而让闸门去问一个人的工具,只能增加摩擦。一个自报自己无害、从而让闸门跳过那个人的工具,是在选择自己的监督。这也是 Pi 的缺失提示默认值所做的事:它把一项声明的缺席当作最坏情形。本书提出,且与 Pi 有文档记载的默认值一致。
所以有两种截然不同的保护,而你两者都需要:
| 防范什么 | 实现为 | |
|---|---|---|
| 把未知解析为危险 | 对自己一无所知的工具 | Pi 对缺失提示的默认值 |
| 在工具控制之外分派风险 | 对自己撒谎的工具 | 你自己的策略,应用在一个你控制的集合上 |
Pi 给你第一种。第二种是你写的许可模型。
你自己分派风险,在一处
你可以建在一个 tool_call 处理器上、或建在它周围的宿主上的形状:
1. 归类 在一张你自己拥有的表里查找这个工具,而不是它自报的那张
2. 评估 套用模式、会话授予的权限,以及任何硬性拒绝
3. 决定 允许 | 确认 | 拒绝,以及在什么范围上
4. 执行 或者返回一个模型能读到的失败
第 1 步是权限所在之处,而从这个形状里推导出两条规则,实现常常把它们搞错。
强制执行绝不可被它所约束的东西触及。 一次智能体能影响的许可检查——通过写一个检查者读取的文件、通过调用一个改变策略的扩展、或者通过被告知自己的模式——不是强制执行。它是建议。
一道闸门,而不是每个集成一个。 一旦你有一条针对 bash 的规则、一条针对第一个 MCP 服务器的规则、以及一条针对第二个的不同规则,你就没有任何规则了。把贡献的工具放进一个命名空间,并在它们全体前面放一个单一的决定点。第 17 章的 namespace 和 exposure 是 Pi 为此给你的杠杆,而第 21 章关于一道忘了 mcp__ 前缀的闸门会放调用通过的观察,就是两个空间的代价看起来的样子。
设计一道人们不会学会挥手放行的闸门
一个确认对话框恰好有两个状态。构建一个在每次写入时都触发、从而训练使用它的人每次都按同一个键的对话框,容易得惊人,而到那时它已经花掉了你的打断,却什么也没买到。Pi 给你 ctx.ui.confirm(prompt, detail) 和不比这更丰富的东西,所以设计是你的。这是设计建议,不是 Pi 的契约。
| 规则 | 它买到什么 |
|---|---|
| 给决定一个范围,而不只是一个判定。 仅此一次、本次会话、永不,是三个问题。 | 一个双按钮对话框只问第一个,而"永不"绝不该是那个容易的选项。把一次授予的作用域限定到一个会话,按工具设键,好让它不活得比它被做出的理由更久 |
| 让无条件的那些情形不花任何提示。 在任何卡片存在之前,就拒绝那些反正会被拒绝的东西。 | 没有什么要关闭,没有什么要下意识接受 |
| 把闸门的作用域限定到真正变化的东西。 在工作区内部读取没意思;触及它外面才有。 | 提示数量最大的一次单一削减 |
| 在卡片里带上上下文。 风险级别、理由、参数、路径。 | 一张没有它们的卡片只能被下意识地回答 |
| 排队,不要堆叠,并在中止时拒绝那个队列。 按请求身份匹配答案,而不是按位置。 | 一个对旧卡片的迟到回答,绝不能解决一个更新的 |
一次确认记录一个人说过一次"是"。能力没有改变,而它仍然是整个进程拥有的那个能力。
什么不是边界,无论它如何伪装
本书提出,而每一条都是一个常见的设计错误,而不是一种 Pi 行为。
一个超时。 一个钩子上的时间预算之所以存在,是为了让一个缓慢的扩展无法拖住智能体。它是一种活性(liveness)机制。受信任的代码仍然能阻塞它运行其上的那个线程,或者迅速把危险的事做完。一个预算让系统跑完;它不让代码变得安全。
一个围在错误东西外面的插件沙箱。 沙箱化一个插件运行时,而受信任的模块却在智能体进程内部运行,这不是隔离智能体。那个已经握有文件和 shell 工具的模块,已经没有什么可遏制的了。
一次重载。 在每次加载时重读一个插件的清单,让开发变得愉快,却丢了一个控制。一个许可集合在你编写一个插件期间可以正当地增长;它绝不能在有人批准它之后还能增长。一次重载可以收窄一个许可集合,绝不能在它拓宽。 许可决定是一个你授予的东西,而任何能编辑你授予之物的东西都是绕过它的一条路。这又是第二项测试:授予必须在它所约束之物的触及范围之外。
把权限放在它能挺过一次运行时更改的地方
@earendil-works/pi-coding-agent 是 Pi 的包名,也是你的扩展导入的那个模块。改问一个关于你自己的系统的问题:
如果你明年换掉这个智能体运行时,你的哪些决定将不得不重新做出?
你在运行时内部编码的任何决定都必须被重新做出。你在它周围那一层编码的任何决定都不必。对于一个扩展作者来说,通过改变对话、或者通过引导一个提示词片段来强制执行一条策略,是经由一个你不拥有的面做出一个安全决定。同一条规则在操作系统或宿主边界上强制执行,能在它下面的运行时更改时存活下来。对于一个宿主来说,同样的逻辑给一次运行时更换定价:在运行时内部做出的每一个权限决定都被重新推导、重新评审;在宿主边界上做出的每一个决定都原封不动。
那是用在决定上、而不是用在层上的可替换性,而第 1 章把两者分开了。一个你能更换的运行时,不是一个遏制任何东西的运行时。第 31 章为界面观察了第一项;本章讲第二项。
运行时之内 人体工学、提示、便利性、呈现
运行时之外 许可、隔离、机密、审计、拒绝
如果一个控制能在两个地方表达,就把它放在外面。里面的那份副本可以保留,为了响应性,只要外面那份副本是那个能独自阻止一个敌意动作的副本。
能力不是权限,作为一项测试重述
给定一个工具或扩展:
- 它能触及什么? 文件、凭据、进程、网络服务。通常是:Pi 进程能触及的一切。
- 谁决定它可以? 项目信任决定了它的代码是否加载。没有什么决定过它的行为是否被许可。
- 谁分派了它的风险,你还是那个工具? 如果风险是工具提供的,你拥有的是一个论断,不是一个控制。
- 什么约束它,而那个东西是否及时行动、且在触及范围之外? 一个你摆放的操作系统边界,或者一道你写下的、工具无法影响的闸门。
- 它能挺过一次重载、或一次运行时更换吗?
第 4 步是每个控制得到它的标签的地方:
| 标签 | 它的意思 |
|---|---|
| 已强制执行 | 一道操作系统或虚拟化边界不问任何人就阻止这个动作。 |
| 已建议 | 一道闸门问一个人,或者检查一张表。它能阻止这次调用;它不能限制进程触及什么。 |
| 已假定 | 一个关于工具、文件夹或模型的论断,而没有任何东西检查它。 |
| 在 Pi 的契约之外 | 提示注入,以及一个被隔离的进程仍然能触及的东西。 |
如果第 4 步里没有任何被强制执行的东西,你拥有的就是建议。
一个需求,三级台阶
拿第 11 章的推演案例 4 来说:不强制推送,并且在动 migrations/ 里的任何东西之前先确认。 按那两条规则放置:
| 需求的一半 | 级台阶 | 它诚实地做什么 |
|---|---|---|
“用 pnpm test:unit;不要运行 npm test” |
1,指令 | 引导。行为规则:产生该行为的最便宜机制 |
“确认 migrations/” |
3,拦截 | 问一个人,如果没有人可问就拦下这次调用,附上一个模型能据以行动的理由。一个作用于一个表示的流程 |
| “不要强制推送” | 3 和 4 | 一个扩展能无条件拒绝它认得的那条命令,而那是第 3 级台阶——但它认得的是一个字符串,所以它是一个流程。第 4 级台阶是远端拒绝这次推送,而它是模式出错时唯一成立的那一半 |
| “智能体永远不能推送到发布分支” | 4,遏制 | 进程不持有任何能推到那里的凭据,或者远端拒绝它。这是如果上面一切都错了仍然成立的那一半 |
较高的级台阶不是多余的。每一级都在减少下面那一级不得不触发的频率,而拦截那一级是解释所在之处:一个拒绝推送的容器说不出任何模型能从中学习的东西,而一道返回理由的闸门能。那是一种设计上的好处,不是安全上的,而这张表对哪个是哪个是诚实的。
把推演案例 4 拆成两行不是吹毛求疵。第 11 章最初展示了一个把每次 git push 都当作一次确认的处理器——它满足"动 migrations 之前先确认",却不满足"不要强制推送",因为第二个会去问一个人,而一个人可以说"行"。禁令和确认是不同的需求,想要不同的代码。同样值得直说的是,修正后的守卫仍然是一个流程:它对着 git push --force 匹配 bash 和 edit 的输入字符串,而一条它没有预料到的拼写抓不到。这就是为什么强制推送那一行也点到了第 4 级台阶。
全书汇成一张表
本书做出的承诺是,你能看着一个需求、说出它需要哪个 Pi 机制。这里是那个映射。级台阶是该需求的强度所需要的那一级;一条约定停留在第 1 级台阶。
| 需求说 | 机制是 | 你依赖的契约 |
|---|---|---|
| “它应该知道我们在这里怎么做” | AGENTS.md / CLAUDE.md,或一个技能 |
加载顺序和作用域;内容是指令,不是代码 |
| “每次都按同样的方式做” | 一个技能 | 已加载的描述;模型按名字调用它 |
| “它需要一个能做 X 的工具” | pi.registerTool() |
给模型的 content、给渲染的 details;为失败而抛出 |
| “不要让它做 X” | pi.on("tool_call") + 一张你自己拥有的风险表,在一道边界之上 |
拦截是一道失效安全;一个声明的提示是一个论断,不是一个控制 |
| “显而易见的那些别来问我” | exposure、作用域,和一个你自己拥有的模式 |
注册不是激活;注解是未经核实的 |
| “做 X 之前先问我” | ctx.ui.confirm() |
需要一个可以询问的 UI;print 和 JSON 没有,所以拒绝而不是假定同意 |
| “只在我要求时”(作为一个人的请求) | 一条显式命令,而不是一次 UI 检查 | ctx.hasUI 说一个 UI 存在,而不是那个人要求过。见下面的注 |
| “把它挡在模型的上下文之外” | pi.appendEntry() |
已持久化,在转录记录里可见,不在上下文里 |
| “它应该在会话之间记得” | 会话文件、SessionManager |
活动分支是到达模型的东西 |
| “当这件事发生时,做那件” | 一个事件处理器 | 顺序是加载和注册顺序;有些事件做转换,有些只通知 |
| “从那里重新开始” | /tree、/fork、fork |
你离开的那个分支不会被删除 |
| “在 CI 里运行它” | --print 或 --mode json |
Print 通过退出码示意失败;JSON 在流中报告它 |
| “结构化的进度” | --mode json、agent_settled |
增量仅供显示;结束事件才是权威的 |
| “把它嵌入一个服务” | createAgentSession() |
SessionManager 是权威的;订阅在替换之后重新绑定 |
| “从另一个进程驱动它” | --mode rpc |
响应意味着已接受;disposition 说一次运行是否开始了 |
| “它绝不碰生产环境” | 一道操作系统边界,外加用于启动的项目信任 | 信任把守的是加载,不是行为 |
| “即使 Pi 变了它也必须仍然安全” | 把许可放在运行时之外 | 唯一一道其放置独立于 Pi 自身代码的边界 |
那些最后几行里有两行带有值得点名的假设,因为它们是表中两个听起来绝对的论断,而两者都依赖某个未言明的东西。
“只有操作系统边界能挺过一次运行时更换。” 这话的意思是,一道操作系统边界不驻留在运行时内部,所以替换掉 Pi 不会移除它。这是一个关于放置的陈述,而它是站得住的。它不是一个关于操作系统边界充分的论断,也不是关于你拥有一道的论断:一个以仓库读写挂载、且环境里有一个凭据的方式启动的容器,是一道恰好允许你给它的东西的操作系统边界。本章里每一个第 4 级台阶的配方都是有文档记载的,此处未运行——没有执行过任何容器、微虚拟机或凭据代理。把它们当作 Pi 有文档记载的选项来读,而不是当作测试过的配置。
“UI 可用不等于同意。” 上面那一行已经把两者分开了,而值得重述每一个是用来做什么的。hasUI 告诉你是否有某个可以询问的东西;它无法告诉你是否有人想要被问。把一个存在的 UI 当作一次请求的代码,会为没有人要求过的东西弹出提示,而一个对一切都弹出提示的守卫,是人们学会盲目批准的守卫——这与根本没有守卫是同一种失败,只是仪式更多。
仍然要你来决定的
本书没有任何东西消除这些。
- 一个工具自报的注解是否为真。 Pi 把一个缺失的提示当作危险的。那是一个安全的默认值,不是一个保证,而第 21 章观察到一个闸门相信了一个假的。
- 某一次特定的确认是否值得为之中断一个人。 一个对一切都弹出提示的闸门,是人们学会盲目批准的闸门。
- 环境实际暴露了哪些文件、凭据和网络目的地。
containerization.md坦率地说,“一个被隔离的进程仍然能影响你暴露给它的资源。” - 模型是否被你没写过的内容引导过。
security.md把提示注入点名为一个来自"文件、注释、指令、命令输出和模型响应"的、活的关切,而没有任何配置旗标能解决它,因为内容是经由模型自己的上下文到达的。 - 一次加载失败时该怎么办。 一条有用的约定:把一个失败的扩展标记为失败,然后跨过它。一个降级了但仍能运行的智能体,胜过一个停下来完整的。
最后一点是整个事业诚实的极限。本书里有文档记载的一切都是机制,而没有一个机制能分辨一个恶意指令和一个有帮助的指令,因为对模型来说它们是同样位置上的同样字节。
你能和不能论断什么
有文档记载: security.md 和 usage.md 里的立场;Pi 的每种运行方式保护什么;隔离方法和每种方法隔离什么(containerization.md);项目信任把守的是启动加载、而非之后的行为;一个缺失的注解采用 MCP 默认值;那些 --tools 旗标(cli.md);以及 AgentTool.replay 的声明。
已观察,在 1.0.4 上,在脚本化的响应和一个脚本化的 MCP 远端之下: 在效果之前的一次拦截意味着 execute() 运行零次,而在它之后的一次改写并非如此(第 39 章);一个守卫拒绝一次强制推送,而一个会抛出的处理器作为一道失效安全拦住(第 16 章);一道忘记前缀的、按名字设键的闸门会放一个 MCP 调用通过,而一个批准闸门相信了一个假的 readOnlyHint(第 21 章);一个不被信任的文件夹的 AGENTS.md 仍然会加载(第 8 章);四个 Pi 包里没有任何已发布代码读 AgentTool.replay(本章的测试,对版本敏感)。
本书提出: 四级台阶,以及那张对照着两项属性测试它的表;权限规则;“由被检查方选定的值不能充当检查的闸门"及其单向推论;第 2 级台阶上的闭合论点;一道闸门相对于它所约束之物的放置;闸门设计规则;那些伪边界;以及那个"一个需求"表的每一行。
未测量: 一个真实模型的任何行为,包括一个模型是否无视一条明说的禁令。本书没有 real_model 证据。未运行: 任何容器、微虚拟机或凭据代理。
延伸阅读
本章中的机制不是在这里发明的,而最接近的、已付诸实践的实例根本不是命令行界面。有两类来源要紧:嵌入一个智能体运行时并发布其规范的桌面应用,以及关于在不可信数据之上使用工具的智能体的已发表研究。附录 A 列出它们,说明每一个实际上是什么的证据,并明确指出哪些是第三方策略、而不是 Pi 自身的语义。它们中没有任何一个是关于 Pi 做什么的权威。
收尾
四十一章之前,前提是一个智能体就是一个模型加一个循环。并非如此。它是一个模型加一个循环,外加一个工作目录,外加一组能触及你给它们的任何东西的进程。
你现在有了能精确表述一个需求的词汇。“它应该小心"不是一个需求。“没有一个人能看到的确认,这个工具就不能运行,并且环境里绝不能含有生产环境的凭据"是一个,而你知道它是一个带有你自己分派的风险的工具、一个 tool_call 处理器,以及一道容器边界——按这个强度顺序——那个注解已知是未经核实的,而那个容器已知是三者中唯一一个称得上是边界的。
所以,本书自第一章起就一直绕着转的那个问题,值得一个直接的回答:什么让一个智能体值得被构建?不是能力,也不是自主。当你能说出它可以触及什么、说出谁授权了那个、并且点出你自己的判断代替一份契约的每一个地方时,一个智能体才值得被构建。那就是让设计可评审的东西,而可评审性是区分一样你能交给别人的东西和一个里面装着模型的脚本的东西。
本书在三个层面上说了一件事。在机制层面:使用能解决问题的那个最弱的。 在放置层面:把决策放进拥有它的最窄那一层,并且只放进一个能在后果变得不可逆转之前行动的层。 在权限层面:在仍能阻止那个后果的最低边界上强制执行一项禁令,并且绝不让一个由你正在约束的那一方选定的值,决定它被监视得多密切。
文本无法强制执行只有代码才能拦截的东西
智能体进程里的代码无法强制执行只有宿主才能遏制的东西
一个被约束方能够触及、或其依据的事实由其提供的边界,只是建议
每一行都是不可逆转条款在起作用,外加第二项测试。一个 AGENTS.md 是文本,而文本无法拦住一次工具调用。一个 tool_call 处理器是代码,而代码无法撤销一次已经发生的写入。智能体自身进程里的一道闸门共享那个进程的权限,而只有操作系统能遏制进程为自己打开的东西。在每一步,答案都不是前一个工具的更好版本,而是一个不同种类的东西,之所以选它,是因为它能及时且在触及范围之外行动。
能力不是权限。机制能力也不是,那是同一个句子换了一个名词,也是本书把最后一章花在两者上的原因。
Pi 把它自身的极限有文档记载得足够仔细,以至于你能在它们之上构建。它没有有文档记载的一切都是你的。
照此构建。