阶段一 · 架构与核心机制

工具系统 —— 模型的手和眼睛是怎么装上去的

模型只能输出文字,工具是它操作世界的唯一通道。这一章讲三件事:工具怎么被"声明"给模型看、调用怎么被分发执行、以及——当模型想干坏事时,谁拦得住它。最后一节会纠正一个流传很广的误解: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 给它的防护分两层——工具自己保证的和必须由外部保证的:

  1. 截断:输出限 2000 行或 50KB,谁先到算谁。截断后的完整输出保存到临时文件,路径放进结果——既不撑爆上下文,又不丢信息。
  2. 超时:可选超时,防止命令挂死。
  3. 隔离——这一条不在工具里: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 的拦截在扩展和操作系统层,不在内置工具里。
  • 命令类工具是特权工具:截断与超时是工具自带的,隔离必须外部提供。

工具执行的结果要填回给模型——这就是下一章的主题:消息与记忆,看对话历史如何组织。