阶段一 · 架构与核心机制
工具系统 —— 模型的手和眼睛是怎么装上去的
模型只能输出文字,工具是它操作世界的唯一通道。这一章讲三件事:工具怎么被"声明"给模型看、调用怎么被分发执行、以及——当模型想干坏事时,谁拦得住它。最后一节会纠正一个流传很广的误解:Pi 并不在每次工具调用前询问你。
具体回答三个问题:模型凭什么知道能用什么工具?调用为什么会失败?拦截该写在哪一层?
学习目标
- 理解"工具 = 说明书 + 执行器",以及为什么模型只看得到说明书。
- 理解注册表的作用:加一个工具,为什么只需要改一处。
- 分清两类约束:靠提示词"劝"模型的,和根本不问模型意见的。
- 知道 Pi 到底有没有工具级审批、拦截应该写在哪。
- 理解工作目录的真实角色:它是相对路径的基准,不是安全边界。
一、模型怎么知道它能干什么
模型不知道你的文件系统、你的终端、你的业务。它唯一能"知道"的,是你喂给它的工具信息——三样:
名字 —— 这个工具叫什么
说明 —— 干什么、什么时候该用(写得好,模型才不会误用)
参数说明 —— 收哪些参数、什么类型(写得越严格,模型生成的调用越合法)
执行器不在模型的视野里。它是你进程里的真实函数,可以注入、替换、打桩。这正好是可测试性的来源:测试时塞一个假执行器,就能验证"模型要求调用工具时,循环是否正确地调了它"。
二、注册表:加工具只改一处
没有注册表时,加第二个工具要改两个地方:声明列表加一项、执行分发的 switch 加一个分支。加到第三个就开始出错了——总有一处忘改。
注册表把"声明"和"分发"收拢到一处:
registry = ToolRegistry()
registry.add(read_tool) # 一行一个工具
registry.add(write_tool)
# 分发:registry.get(name).execute(...)
它带来一个额外好处:工具绑定在工作目录上。工具不是全局单例,而是"属于某个项目的实例",创建时必须告诉它工作目录。
但这里必须补一句,否则很容易形成错误的安全感:工作目录只是相对路径的解析基准和默认位置,它不是围栏。模型给出绝对路径、给出 ../、或者直接让你跑一条命令,都能越出这个目录。Pi 的官方安全文档写得很直白:工作目录并不阻止命令访问其他路径。真想限制范围,得靠操作系统级隔离——那是另一层的事,见下一节。
三、两类约束:劝,还是拦
约束工具行为的手段分两种,性质完全不同:
| 机制 | 问谁 | 强度 | 例子 |
|---|---|---|---|
| 软约束 | 模型愿不愿意 | 因模型而异 | 参数说明里要求"改文件前先读一遍" |
| 硬闸门 | 不问模型意见 | 与模型无关 | 执行前发现越界,直接拒绝 |
软约束的强度取决于你恰好用了哪个模型:同一条规则,一个模型遵守,另一个可能不遵守。硬闸门不依赖模型,是唯一可以依赖的防线。
Pi 的硬闸门到底在哪
这里要纠正一个流传很广的说法。很多资料(包括本课程的早期版本)会说 Pi 有一套"允许 / 询问 / 拒绝"三档的工具权限,多条规则按优先级裁决。这个机制在 Pi 里并不存在。官方文档的原话是:Pi 不会在每次工具调用前征求同意,它启动后就用你这个系统账号的权限运行。
所以真正的硬闸门只有三处,而且各自管的范围不同:
| 闸门 | 在哪 | 能拦住什么 | 拦不住什么 |
|---|---|---|---|
| 工具调用拦截 | 扩展里的一段钩子,可以对某次调用说"不许执行" | 单次调用,在执行之前 | 扩展本身的 bug、没装扩展 |
| 操作系统隔离 | 沙箱、容器、专用账号 | 越界的文件、网络、进程 | 你主动授权的危险路径 |
| 项目信任 | 决定要不要加载这个目录里的配置和扩展 | 项目级设置、扩展、提示词 | 完全不限制工具能访问什么 |
第三行最容易被误读:项目信任回答的是"要不要加载这个目录里的东西",不是"工具能做什么"。信任一个项目,不等于给它的工具开了绿灯;不信任,也不会让已经启用的工具自动收敛权限。
那"允许 / 询问 / 拒绝"这套设计就没用了吗?有用——它是一种通用的权限模式,你完全可以在自己产品里实现。但要在 Pi 上复现它,正确做法是写一个权限扩展:拿到工具名和参数,必要时弹窗问用户,拒绝就拦下。官方示例里就有一个最小的权限闸门,还有一个版本用工具自带的"只读 / 有破坏性"标注来决定要不要问。
两个容易被忽略的细节:拦截钩子抛异常时按失败关闭处理——宁可拦下,也不"因为扩展坏了所以放行";被拦下的调用不会执行,但会回填一条错误结果,模型能看到"这次被拒了",而不是凭空消失。
四、命令类工具是特权工具
bash 与文件工具不同:一次调用就能执行任意命令、访问整个系统。Pi 给它的防护分两层——工具自己保证的和必须由外部保证的:
- 截断:输出限 2000 行或 50KB,谁先到算谁。截断后的完整输出保存到临时文件,路径放进结果——既不撑爆上下文,又不丢信息。
- 超时:可选超时,防止命令挂死。
- 隔离——这一条不在工具里:Pi 默认既不拦
rm -rf,也不弹确认框。真正的边界是沙箱、容器、专用账号,或者你自己在扩展里判断后拦下。
把"bash 自带权限层"当成事实,是这份课程要纠正的旧说法。
工具执行失败也有统一约定:执行失败就抛异常,由循环统一转成带错误标记的结果,而不是每个工具各自手工拼错误对象。这样"失败"在消息层面只有一种形状,前端和模型都不用猜。
当前 Pi 行为
- 内置工具共八个:读文件、跑命令、Windows 命令、编辑、写入、内容搜索、文件名搜索、列目录。默认启用的四个是读、命令、编辑、写入,其余按需开启。
- 执行结果以一条工具结果消息回填,带调用编号,和发起它的那次调用配对。
- 工具可以声明"我需要独占执行";这一批里只要有一个这样声明,整批就改成串行,否则并行。并发安全因此是工具作者的责任,不是循环的猜测。
- 命令输出截断阈值是 2000 行 / 50KB,完整输出落在临时文件。
- 提示词里的工具清单只列"给了说明文案"的工具;但工具声明是另一条通道——没写说明的工具仍然会被声明、仍然可调用,只是不出现在那几行清单里。
- 不在每次调用前询问用户;拦截只能靠扩展或操作系统隔离。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 工具定义 | 工具执行器 + 参数模式(schema) |
| 独占执行 | executionMode: "sequential" |
| 调用拦截钩子 | tool_call 事件,返回 block |
| 只读 / 破坏性标注 | 工具注解(readOnlyHint 等) |
| 项目信任 | defaultProjectTrust(询问 / 总是 / 从不) |
| 工具工厂 | createCodingTools(cwd) |
源码位置
packages/coding-agent/src/core/tools/:八个内置工具、截断逻辑、路径工具。packages/agent/src/agent-loop.ts:工具批的调度与截断处理。packages/coding-agent/docs/security.md:安全模型的第一手说明,建议先读它再读代码。
失败与边界实验
lab permissions 用同一个策略函数走四条路径:
| 场景 | 输入 | 谁拦下 | 结果 |
|---|---|---|---|
| 命令不在白名单 | rm -rf / |
硬闸门(命令令牌) | 拒绝,执行器没被调用 |
| 相对路径穿越 | ../../etc/passwd |
硬闸门(归一化 + 包含检查) | 拒绝 |
| 符号链接逃逸 | 指向边界外的链接 | 硬闸门(解析真实路径后再判断) | 拒绝 |
| 白名单内的合法读 | ls + 边界内路径 |
— | 执行 |
三条拒绝路径的共同点是:执行器完全没有运行,所以零副作用。这就是"硬闸门"的定义——检查发生在执行之前,而不是靠事后撤销。
python3 -m learn_pi_lab lab permissions
python3 -m unittest tests.test_02_tool_permissions -v
在 Pi 里怎么操作
- 内置工具不用安装;扩展注册新工具的方式见第 06 章。
- 首次进入未信任的项目目录,Pi 会问你信不信任,确认后才加载项目设置与扩展。
- 想给工具加审批,装一个权限扩展;想看当前能访问什么,读安全文档比读代码快。
Python 实验
mini_agent.py 里的工具定义,就是"说明书 + 执行器"的最小形态:
@dataclass(frozen=True)
class AgentTool:
name: str
description: str
parameters: Mapping[str, object] # 参数说明,模型看到的部分
execute_fn: ToolExecutor # 执行器,模型看不到
真正值得逐行读的是 tool_permissions.py,它把"拦截"写成了一个纯函数:判断和执行彻底分开。
def dispatch_if_allowed(request, policy, executor):
decision = evaluate_request(request, policy) # 只看意图
if not decision.allowed:
return DispatchResult(decision=decision, result=None, executed=False)
return DispatchResult(decision=decision, result=executor(decision.request), executed=True)
evaluate_request 内部是三道依次的检查:
token, problem = _command_token(request.command) # ① 拆出裸命令令牌
if token not in policy.allowed_commands: # ② 白名单
return Decision(False, "command_not_allowed", ...)
for requested_path in request.paths: # ③ 路径归一化 + 包含检查
normalized_path, path_problem = _normalized_path(requested_path, policy.root)
三个取舍藏在细节里:
_command_token拒绝一切 shell 语法:命令里有空格分隔之外的管道、重定向、变量替换,直接拒绝。命令必须是单个裸 token——不做字符串解析,就没有注入面。- 路径检查两步走:先拒绝
..这样的父目录分量拦住明显穿越,再解析真实路径后验证它仍在边界内,兜底符号链接与绝对路径。两步缺一不可。 executed=False是一个结构化事实:调用方不需要"事后撤销"任何东西,因为根本没执行。
把它和 Pi 对照,差异正好说明一件事:这个闸门是你写的,不是 Pi 内置的。Pi 提供的是"拦下某次调用"的钩子和操作系统隔离,策略本身留给你——因为每个团队能接受的风险不一样。
Tau 的 tau_agent/tools.py 里,工具字段基本一致,只是执行器是异步的、支持进度回调。
python3 -m learn_pi_lab lab permissions
这一模块的核心代码在核心代码导览 · 工具权限闸门有逐段解读。
验证方式
python3 -m unittest tests.test_02_tool_permissions tests.test_11_projects -v
边界与安全
- 白名单不是沙箱:生产实现还需要操作系统隔离、最小凭据、审计日志、用户确认,以及针对符号链接和竞态条件的防御。
- 不要用字符串拼接生成 shell 命令;命令令牌必须是白名单里的裸命令。
- 工具是隔离边界:执行器抛出的异常应转成结构化错误结果,而不是让循环崩溃。
- 装了扩展不等于安全了:扩展在 Pi 进程里运行,拥有同样的系统权限。
自测三问
- 一个工具没写"一句说明",模型还能调用它吗?为什么?
- 如果一个产品同时在提示词里写"删文件前要确认"、又没装任何拦截扩展,它的安全边界在哪?
- 工作目录为什么不能当围栏用?给出两条能绕开它的路径。
回顾
- 工具 = 说明书 + 执行器:模型只看得到说明书,执行器在你的进程里。
- 注册表:加工具只改一处;工具绑定工作目录,但工作目录不是围栏。
- 两类约束:劝模型的不保险,拦模型的才可靠;Pi 的拦截在扩展和操作系统层,不在内置工具里。
- 命令类工具是特权工具:截断与超时是工具自带的,隔离必须外部提供。
工具执行的结果要填回给模型——这就是下一章的主题:消息与记忆,看对话历史如何组织。