实现篇第4章 给手装上工具——Tools ​

本章导读: 你会写
src/tools.ts的 read、write、bash 三个工具,还有workspacePath路径边界和truncateHead输出截断。这一步要立的规矩:四道闸门(schema、运行时校验、截断、realpath)控制模型能碰什么,但都不是 OS 级隔离。
循环能跑了,但小A发现一件事:模型说要“读文件”,它真的读了;可它说要“写文件”的时候,竟然能往工作区外面写。小A吓出一身冷汗,赶紧去找老Z。
“我是不是该给工具加权限?”他问。
“加,但先想清楚加在哪。”老Z说,“src/tools.ts 的 createWorkspaceTools() 返回 read、write、bash。每个 ToolSpec 都有 properties、required 与 additionalProperties: false;执行前 stringField() 再做运行时检查,因为模型输入仍不可信。”
小A抢着总结:“懂了,schema 管参数长什么样,运行时再兜一道。”
“兜一道没错。不过这套检查做的是路径边界,OS 沙箱它做不了:检查与实际打开之间仍有 TOCTOU 窗口,bash 仍能使用进程本身拥有的权限。schema 和运行时检查是两道门,缺一不可。”
小A把“两道门”记下来,又问:“那 createWorkspaceTools() 返回的三个工具,谁给它们定义边界?”
“边界不在工具内部,挂在 createWorkspaceTools(workspaceRoot) 的根参数上。”老Z说,“workspacePath 的所有检查都相对 rootReal 展开:realpath(root) 先求一次根的真实路径,之后 candidate 都以它为基准比较。根在构造时就定死了,模型每次调用都改不动它,手里只有相对工作区的路径。‘根从构造来、路径从请求来’的分工,是路径边界成立的先决条件。”
工具声明和运行时是两道门 ​
小A:“那这两道门分别干什么?”
老Z打开 tools.ts:
spec: {
name: "write",
inputSchema: schema(["path", "content"], {
path: { type: "string" }, content: { type: "string" },
}),
}“schema 用于告诉模型期望形状;additionalProperties: false 是向 Provider 表达的约束,不是本地 JSON 验证器。”
小A追问:“Provider 不是会按 schema 校验模型输出吗?为什么还要再查一遍?”
“因为 schema 在这里有两个角色,不能混。”老Z说,“第一个角色是‘告诉模型该怎么调’,它出现在发给 Provider 的 input_schema 里,模型据此生成参数。第二个角色是‘Provider 替我们挡住坏参数’,但这件事契约里没保证:Provider 可能某天改了行为,模型可能输出绕过 schema 的 JSON。我们控制不了 Provider,但能控制自己的执行器。所以 stringField() 是兜底,不管谁给的 input,到了执行这一步都重新验一遍。这叫纵深防御:schema 照常信任,安全却不能只押在它一道关卡上。”
小A注意到返回值:“那 stringField 为什么返回 undefined,而不是抛错?”
“因为工具失败的处理方式是‘变成消息’,不是‘中断循环’。”老Z说,“write 的执行器返回 { content: "invalid write input: ...", isError: true },loop 把它记成 tool message 交给下一轮。模型读到‘path must be a string’,自己决定要不要修正。抛错是剥夺模型的修正机会,返回 isError 是给它反馈。这两条路在 agent.ts 里分得很清楚:isError 走‘记录并继续’,抛异常走‘记录失败并 rethrow’。”
小A:“那 undefined 和空字符串有区别吗?stringField 会不会把空字符串当合法值?”
“会,而且这是有意的。”老Z说,“stringField 只判断‘是不是 string 类型’,不判断‘是不是非空’。空字符串是合法的 content,你要写一个空文件,content 就该是空串。真正的失败信号是 undefined:字段缺失、类型不对、或者 input 根本不是对象。‘类型对但内容空’和‘形状不对’是两回事,stringField 只拦后者。如果你想让空字符串也被拒,那是业务规则,应该写在执行器里,而不是塞进这个通用函数。”
小A:“三个工具都复用同一套 stringField,错误信息会不会写得太笼统?”
“看执行器的措辞就知道了。”老Z说,“read 说 invalid read input: path must be a string,write 说 invalid write input: path and content must be strings,bash 说 invalid bash input: command must be a string,工具名在前,规则在后。模型读到这条消息,能同时知道‘哪个工具’‘哪个字段’‘什么规则’,修正才有依据。这是给模型的反馈,反馈的信息密度直接决定它下一轮能不能改对。”
从声明到执行的正常路径 ​
老Z接着走了一遍完整流程:“以 write 为例,模型先看到 ToolSpec 的名字、描述和 schema;若它返回 { path, content },stringField() 逐字段取得字符串。两个字段任一不是字符串,工具直接返回 isError: true 的结果,Agent 可将它交还下一轮。字段形状通过后才进入文件系统。”
function stringField(input: unknown, field: string): string | undefined {
const value = asObject(input)?.[field];
return typeof value === "string" ? value : undefined;
}“asObject 先排除 null、数组和基本类型;可选访问意味着缺字段得到 undefined;最后只接受 string。”老Z说,“这里没有把 JSON schema 当作运行时验证器,这正是模型调用边界所需要的重复检查。”
小A把 asObject 的三个排除挨个问了一遍:“为什么 null 要排除?数组为什么也不行?”
“null 的 typeof 是 "object",但访问它的字段会直接炸;数组的 typeof 也是 "object",可它没有你要的具名字段。”老Z说,“asObject 的职责是回答一个精确的问题:‘这个值能安全地当对象读字段吗?’只有非 null、非数组、对象类型的值才答‘能’。这三个检查不是防御性装饰,是 input: unknown 这个类型本身要求的安全降级,从 unknown 到 Record,每一步都要显式证明。”
路径决策序列 ​
小A:“那路径越界怎么防?symlink 能骗过吗?”
“workspacePath() 先 realpath(root),再解析候选路径。”老Z敲出一段:
const requested = resolve(rootReal, candidate);
if (creating) {
try { await lstat(requested); }
catch (error) { checked = await nearestExistingAncestor(dirname(requested)); }
}
const checkedReal = await realpath(checked);
if (!isInside(rootReal, checkedReal)) throw new Error("path escapes workspace");“第一行只做词法解析,尚未证明对象位于 workspace。目标已存在时 lstat 让后续 realpath 看见 symlink 最终位置;目标不存在时,最近祖先是唯一可解析的 filesystem 对象。最后才比较 canonical path。真实代码只在 ENOENT 时向上寻找祖先,权限错误会传播,不会伪装成‘文件不存在’。”
小A盯着 creating 参数问:“为什么写文件要单独走一条路?”
“因为写一个不存在的文件,realpath 会失败,它只能解析已存在的路径。”老Z说,“所以 workspacePath 在 creating 时先 lstat:目标已存在,正常解析;不存在,就向上找最近存在的祖先,检查它是不是在工作区内。你看 nearestExistingAncestor:”
// examples/mini-agent/src/tools.ts,节选
async function nearestExistingAncestor(path: string): Promise<string> {
let current = path;
while (true) {
try {
await lstat(current);
return current;
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
const parent = dirname(current);
if (parent === current) throw new Error("no existing ancestor");
current = parent;
}
}
}“它一路向上 dirname,直到找到存在的目录。注意 if (parent === current):到了文件系统根还找不到,才抛错,否则会死循环。而 isInside 用 relative 判断,还处理了 Windows 的路径分隔符:”
// examples/mini-agent/src/tools.ts,节选
function isInside(root: string, path: string): boolean {
const value = relative(root, path);
return (
value === "" ||
(!value.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
value !== ".." &&
!isAbsolute(value))
);
}“relative(root, path) 的结果,如果以 .. 开头或本身是 ..,说明 path 在 root 之外,/work-other/x 这种相似前缀就是这么被拒的。”
小A看完全段:“这些检查放到真实场景里,都长什么样?”
老Z把五个典型场景画成一张表,小A逐行看:
| 场景 | 检查对象 | 结果 |
|---|---|---|
src/a.ts 已存在 |
目标 realpath | root 内才可读写 |
nested/a.ts 不存在 |
最近存在父目录 | root 内才允许 mkdir |
escape/x 是目录 symlink |
symlink 最终目录 | 外部即拒绝 |
write-link 是文件 symlink |
目标最终文件 | 外部即拒绝 |
/work-other/x 相似前缀 |
relative/isAbsolute | 拒绝 |
“为什么这个 root 上的 symlink 检查对 bash 不生效?”小A问,“bash 工具不是也调用 workspacePath 吗?”
“bash 调用的是 workspacePath(workspaceRoot, ".", false),候选路径是 ".",也就是工作区根自己。”老Z说,“所以 bash 只把 cwd 固定到真实的工作区根,命令本身执行的路径它不检查。cd /etc && cat shadow 能跑通,因为那是 shell 在 cwd 之外的自由行动。路径边界保护的是 read、write 两个文件工具,不是 bash 的命令内容。bash 的边界是 timeout、maxBuffer 和调用层的审批,三者没有一个能算路径隔离。”
小A不放心:“那测试跑绿了,能证明这套检查绝对安全吗?它到底拦住了什么,只是 symlink 吗?”
“不能,测试证明的是它拦住了哪些,证明不了竞争条件不存在。”老Z说,“它拦住三类常见错误,测试文件里也都有对应用例:直白的越界,path: "/etc/passwd",relative 一算就发现不在 root 内;相似前缀,/work-other/x,relative 结果以 .. 开头被拒;静态 symlink,escape 指向工作区外,realpath 解析后比较发现不在 root 内。另外,测试还覆盖截断、嵌套 write 以及 symlink 读写逃逸。拦不住的是第四类 TOCTOU:检查完到 writeFile 之间,外部进程把目录换成 symlink。这是 race,应用层没有原子操作能消除它,只有 OS 级 sandbox 能。”
小A:“那为什么不直接上 OS sandbox?”
“因为那不在这一层。”老Z说,“OS sandbox 是容器或权限降级,独立工程,要单独运行环境。这一章的产物是一个库,它没法假设自己运行在容器里。路径边界是应用层这一侧的上限;再往上的保障,得靠前面说的容器或权限降级。”
小A把 symlink 的场景在纸上画了一遍,又问:“如果工作区里已经有一个指向外部的 symlink,模型用 read 读它,报错信息是什么?”
“realpath 解析出外部路径,isInside 返回 false,抛 path escapes workspace。”老Z说,“这个错误会被 read 的 catch 收走,经 failure(cause) 变成 isError: true 的结果,模型读到的是‘path escapes workspace’,不是 Node 的原始 stack。边界违反和命令失败走同一条返回通道,模型不需要区分‘路径太坏’和‘文件不存在’,它只需要知道‘这个动作没做成,换个方式’。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。