阶段四 · 新增设计面
工具的第二条通道 —— 脚本化调用与外部工具服务器
上一章讲的是"一次调用一个工具"。但真实工作里,模型经常要连着调几十个工具:读二十个文件只为找一处配置、搜三遍只为确认一个符号。一次一次调用意味着几十次往返,每一次的结果都要进上下文。这一章讲 1.x 的两条新通道:让模型写脚本一次调完,以及让工具从外部来。两者的共同点是——都不动循环。
学习目标
- 理解逐个调用工具在什么规模下开始变得昂贵。
- 理解脚本化调用怎么把 N 次往返压成 1 次,以及它放弃了什么。
- 理解外部工具服务器如何把第三方能力接进工具池,以及命名与暴露方式的含义。
- 分清"沙箱限制"和"权限限制":脚本能调什么,不等于脚本能干什么。
一、问题:工具箱从四个变成四十个
一个编码助手默认有八个内置工具,这就够用一阵子了。但真实项目里,你很快就会接上:代码搜索引擎、内部 API、数据库、浏览器、公司自研的部署工具……几十个工具是常态。
这时"一次调用一个工具"的模式开始露出三个毛病:
- 往返次数多:模型要读五个文件,就是五次调用、五次返回、五次再请求。
- 上下文被中间结果塞满:五次读文件的内容全部进上下文,哪怕模型最后只需要其中一行。
- 模型得自己当编排器:先读哪个、再读哪个、怎么合并,全靠模型一步步决定,步数一多就容易跑偏。
近几个版本给了两条互补的解法:
| 解法 | 解决什么 | 代价 |
|---|---|---|
| 让模型写一段脚本,在沙箱里调工具 | 往返次数、上下文污染 | 沙箱能力受限、调试变难 |
| 让工具从外部服务器来 | 工具供给、复用别人的能力 | 第三方代码、权限与注入风险 |
两条都不改循环——循环仍然只认识"工具调用"这一件事。
二、脚本化调用:把 N 次往返压成 1 次
思路很直接:模型不再"调一个工具、等一个结果",而是写一段程序,程序里连续调用多个工具,最后只把程序的输出交回上下文。
传统方式:模型 → 调工具A → 结果进上下文 → 模型 → 调工具B → 结果进上下文 → …
脚本方式:模型 → 写一段脚本 → 沙箱里连续调 A、B、C → 只把脚本输出进上下文
举个具体场景:找出项目里所有用到 LEGACY_FLAG 的地方,只报文件名和行号。
- 传统方式:搜一次 → 结果几十行进上下文 → 模型再逐个读文件确认 → 每读一个又多一条消息。
- 脚本方式:写一段脚本,循环搜、循环读、只把匹配的行拼成一小段输出 → 上下文里只多一条工具结果。
三个好处很实在:往返少、上下文干净、编排逻辑写在脚本里而不是散在十几轮对话里。
代价也很实在:
- 沙箱里没有文件系统、没有网络、没有定时器。脚本只能通过工具触达外界,想读文件就调读文件工具。
- 出错就停。脚本执行到一半失败,已经执行过的工具调用不会回滚——副作用是真实的。这和"一次调用失败"的性质不同,得让模型知道。
- 调试变难。模型看到的只是最终输出,中间过程看不见。所以脚本运行时会返回"跑了多久、调了哪些工具"这类元信息,帮助定位。
- 需要两个预算:一个超时(防脚本卡死或死循环),一个输出上限(防止脚本的输出把上下文占满)。
三、外部工具服务器:工具从哪来
第二条通道解决的是"工具从哪来"。有些能力不在你的代码里,而是在别人的服务器上:公司的内部平台、第三方的搜索服务、数据库网关。与其为每个能力写一个本地工具,不如按一个统一协议去连它们。
这套协议就是 MCP(Model Context Protocol)。对模型来说,服务器提供的工具和本地工具没有区别,只是在名字上带了个来源前缀:
mcp__<服务器名>__<工具名>
模型看到的就是这个名字。但如果要在脚本里调用,名字里的连字符之类要重写成下划线——所以 mcp__dev-radius__search 在脚本里叫 mcp__dev_radius__search。名字保留来源信息,是为了让你在日志里一眼看出"这个调用是谁提供的"。
服务器工具还有几个设计点:
- 暴露方式可以分级:直接给模型看、只允许脚本调用、延迟到需要时再给、完全隐藏。工具太多时,不是所有工具都该出现在提示词里。
- 带注解:工具会声明"我只读""我可能有破坏性"这类提示。注解不被强制执行,但拦截扩展可以据此决定要不要先问你。
- 来源即信任边界:服务器是第三方代码。它返回的内容会进上下文,可能包含诱导性文字;它拿到的参数可能是你的代码或路径。
四、共同边界:权限跟着工具走
这两条通道最容易被误解的地方,是把"沙箱"当成"安全"。
脚本沙箱限制的是脚本能做什么,不是工具能做什么。 脚本里没有文件系统,但脚本可以调用读文件工具;脚本里没有网络,但脚本可以调用发请求的工具。所以脚本真正的权限,等于"这个会话启用了哪些工具"——和模型直接调用时一模一样。
换句话说:脚本化调用不构成权限提升。它改变的是编排位置(从模型侧移到脚本侧),不是能力边界。
MCP 这边多出两个新的风险面:
- 第三方代码:服务器实现可能有 bug 或恶意行为,它能看到你传给它的参数。
- 内容注入:服务器返回的文本会进上下文,模型可能把它当成指令。
这两条都指向同一个做法:把外部服务器当不可信来源,限制它能拿到什么,别把密钥拼进参数。
当前 Pi 行为
- 脚本化调用默认关闭:可用命令行或配置显式打开(加一个工具名);接入某些外部工具服务器时,也可能由服务器把它打开。启用后模型多一个"写脚本"的工具。
- 脚本在独立的沙箱里跑(QuickJS),没有文件系统、网络与定时器;只能通过工具与"非语言模型"(分类器、图像生成)触达外界。
- 同时最多两个脚本在执行,超出的排队等待,排队超时会失败;可用环境变量提高上限。
- 脚本有输出上限(默认一万 token)和可选的整体超时;输出超过一道硬顶(字符数或输出条数)时脚本直接失败,超时则整个脚本中止。
- 脚本内可以枚举全部工具、按关键词检索工具、查询某个工具的签名,也可以直接调用。
- MCP 有独立的一整套命令:添加、列出、登录、登出;会话内还有斜杠命令查看连接与切换暴露方式。
- 外部工具以
mcp__<服务器>__<工具>命名,暴露方式分四档;工具注解随工具一起提供。 - 两类通道在提示词里的表现不同:脚本化调用是"多了一个工具";MCP 的服务器工具是否出现在提示词里,取决于它的暴露档位——默认档只在脚本里可见。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 脚本化调用工具 | codemode |
| 沙箱运行时 | QuickJS(quickjs-wasi) |
| 外部工具服务器 | MCP,包名 @earendil-works/pi-mcp |
| 命名空间前缀 | mcp__<server>__<tool> |
| 暴露方式 | direct / deferred / codemode / hidden |
| 注解 | readOnlyHint / destructiveHint / idempotentHint / openWorldHint |
| 脚本预算 | 输出上限、timeout_ms;并发上限由 PI_CODEMODE_MAX_WORKERS 控制 |
源码位置
packages/codemode/:脚本沙箱与工具桥接。packages/mcp/src/:协议客户端与认证。packages/coding-agent/docs/codemode.md、docs/mcp.md:两份一手说明。
失败与边界实验
两条通道各有各的典型故障:
| 场景 | 会发生什么 | 为什么会这样 |
|---|---|---|
| 脚本调用一个没启用的工具 | 脚本报错,已执行的调用保留 | 脚本的工具池就是会话启用的工具 |
| 脚本死循环 | 超时后中止(没设超时就会一直跑) | 沙箱没有天然的终止条件,超时必须由调用方给 |
| 脚本输出巨大 | 输出被截断,完整内容落临时文件 | 输出直接进上下文,必须限长 |
| 服务器返回引导性文字 | 模型可能被误导 | 服务器内容是不可信输入 |
| 服务器要求登录 | 连接报"需要登录",等你去授权 | 认证属于服务器,不属于 Pi |
python3 -m learn_pi_lab lab scripted-calls
python3 -m unittest tests.test_15_scripted_calls -v
在 Pi 里怎么操作
pi --tools +codemode # 本次启用脚本化调用
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list # 看已连的服务器
pi mcp login sentry # 需要认证的服务器
会话里用 /mcp 查看连接、切换暴露方式、启用或禁用某个服务器。
Python 实验
scripted_calls.py 用一组"步骤"模拟一段脚本:调用工具、追加文本、结束。它跑的是普通 Python 函数,不是沙箱——但它把设计上最关键的三个约束写清楚了。
runtime = ScriptRuntime(tools={"read": read}, max_output_chars=120)
output = runtime.run((
CallStep("read", {"path": "a.py"}),
CallStep("read", {"path": "b.py"}),
CallStep("read", {"path": "c.py"}),
TextStep("3 files; only the long one matters"),
))
output.calls # ('read', 'read', 'read')
output.context_messages # 1 ← 三次调用,一条消息
三个观察点:
context_messages恒为 1。这是脚本化调用的全部意义:调用次数不再等于上下文条目数。- 失败会带走"已发生的调用"。调用未知工具时抛出的错误里带着
calls——已经跑过的调用不会被撤销,这正是真实副作用的样子。 - 两个预算都在:
max_calls防死循环,max_output_chars防止输出过长;超输出时文本被截断并打标记。注意max_calls是教学模型额外加的——真实沙箱用的是超时,而不是数调用次数。
它还实现了外部工具的命名规则与暴露分级:
mcp_tool_name("dev-radius", "search") # 'mcp__dev-radius__search'
script_identifier("mcp__dev-radius__search") # 'mcp__dev_radius__search'
partition_tools(
("read", "bash", "mcp__db__query", "mcp__db__write"),
{"read": "direct", "bash": "direct", "mcp__db__write": "hidden"},
)
# direct: ("bash", "read") ← 出现在提示词里
# codemode: ("mcp__db__query",) ← 只能脚本调用(默认档)
# hidden: ("mcp__db__write",) ← 只能经由别的工具
两者合起来解释了"为什么同一个工具会有两个名字、三种可见性":名字里的前缀保留来源,暴露档位决定它在哪一层出现。默认档是"只能脚本调用",这正是工具目录很大时提示词不被淹掉的原因。
需要说明这个教学模型没有模拟的三件事:调用之间的数据流(真实脚本能把上一次结果传给下一次)、并行调用、以及 MCP 的连接协议。它证明的是"聚合、预算、命名、暴露"这四件事,不是沙箱本身。
python3 -m learn_pi_lab lab scripted-calls
验证方式
python3 -m unittest tests.test_15_scripted_calls -v
边界与安全
- 沙箱不等于权限:脚本能调用的工具,就是会话启用的工具;想收紧能力,去关工具,而不是只靠沙箱。
- 外部服务器是不可信来源:它返回的文本会进上下文,它拿到的参数可能包含你的代码或路径。
- 脚本的失败不回滚:已经执行过的写操作是真的写过了,重试前要自己确认副作用。
- 别把密钥拼进脚本参数:脚本日志、工具结果、会话记录都可能留下痕迹。
自测三问
- 为什么"脚本化调用"能减少上下文占用,却不能让模型做更多事?
- 一个工具在提示词里看不见,却还能被脚本调用,这是怎么做到的?
- 外部工具服务器带来的两类新风险是什么?各自该怎么防?
回顾
- 两条通道:脚本化调用把多次往返压成一次;外部工具服务器把第三方能力接进工具池。
- 一个目标:都不改循环,只改变"工具从哪来、谁在编排"。
- 不变的边界:脚本的权限等于工具集的权限;服务器内容是不可信输入。
下一章换个角度:如果连"数据存哪、请求给谁"都要可替换,架构上要怎么留口子——状态与路由。