给 Agent 加一个工具,只需要加一行

本章导读(你在这)
  ↓
① 先定义可观察结果        ← 本章的验收标准,9 条
  ↓
② 一个完整例子            ← 模型怎么用四个工具走完一次任务
  ↓
③ ToolRegistry            ← 「加一行」到底加在哪
  ↓
④ 文件系统边界 + Zod      ← 依赖方向、同源 schema、描述也是上下文
  ↓
⑤ safePath                ← 本章安全性的核心,两道检查
  ↓
⑥ 四个工具逐个看          ← read / write / edit / glob 各自的取舍
  ↓
⑦ 错误映射 + profile      ← 稳定错误码、P01 与 P02 的差别
  ↓
⑧ 配对与权限边界          ← 多工具单轮的硬规则、本章故意留的缺口
  ↓
⑨ 运行、验证与小结        ← 动手 + 排错表 + 自测题

用户输入:「只使用文件工具:写入 demo/note.txt,内容为 alpha;把第一处 alpha 改成 gamma;读取文件并用 glob 列出 demo/*.txt」

失败也是完整链路的一部分:模型试图读 ../secret.txt,不会抛异常,而是回填 Error [path_escape]: …。模型看到 path_escape 就知道换个路径——工具失败是数据,不是异常。

如果把工具写死在循环里,第二个工具出现就开始堆 if (call.name === "shell") 分支——每加一个工具都要改循环。反例:

// 反例:不要让 Agent Loop 认识具体工具
if (call.name === "shell") return runShell(call.arguments);
if (call.name === "read_file") return readFile(call.arguments);

循环只认识「一次调用返回一个结果」这个抽象协议。注册表负责四件事:

1. 按名称查找工具;
2. 把 OpenAI 返回的 JSON 字符串解析成 object;
3. 用 Zod 严格校验参数;
4. 调用与 schema 绑定在同一个 ToolDefinition 里的 handler。

未知工具、坏 JSON、错误类型、多余字段都会在 handler 执行前变成结构化错误。校验在 prepare(),副作用在 invoke(),顺序不能反——否则先写文件再校验就来不及了。

文件操作是外部边界。feature 不应直接创建 Node 文件系统适配器,否则业务层反向依赖具体实现——大白话:工具 handler 里不要出现 import { readFile } from "node:fs/promises"。

bootstrap
   ├─ 创建 NodeWorkspaceFileSystem
   └─ 注入 features
features ──依赖──> core/WorkspaceFileSystem   (接口)
adapters ──实现──> core/WorkspaceFileSystem

直接 import Node fs 的代价:测「路径越界」要在磁盘上真造一个 junction;测「非法 UTF-8」要造坏字节文件;测试真会写文件、跑完得清理。通过接口注入:替身直接抛领域错误,只在内存里记一笔。测试注入替身,生产注入 Node 适配器,feature 无需知道区别。

z.strictObject 拒绝 schema 外字段。约束都是实际契约:path/old_text/pattern 不能为空;limit 必须是大于 0 的整数(true、"2"、0、-1 都非法);content 和 new_text 允许空串(清空/删除是有效操作)。

effect 在第 2 章只是结构化元数据,第 3 章会用它参与权限决策。

工具 description 和参数描述不是文档,而是模型选工具时实际读到的上下文。在请求结构上,工具定义位于 API 顶层 tools 字段,与 system 共同构成每轮不变的静态前缀。

「模型不需要猜测」四条检查:做什么 / 什么时候用 / 返回什么 / 失败怎么办。例:edit_file 描述要求「先读取文件,不接收行号」,模型就不会凭记忆拼旧文本。

公开契约是「工作区相对路径」,运行时不猜测不修复危险输入。直接拒绝:../secret.txt、nested/../secret.txt、C:\secret.txt、/etc/passwd、NUL.txt、nested/CON.log、file:stream、trailing.。

第一关 词法检查(不访问磁盘):拒绝空值、NUL、绝对路径、盘符、..、Windows 保留组件(CON/NUL/COMx/LPTx)、冒号(ADS)、尾随点。

第二关 解析已存在父路径:若 workspace/escape 是指向工作区外的 junction/符号链接,escape/secret.txt 文本看似在内、真实路径却在外——只解析已存在的父路径(因为 write_file 允许创建还不存在的文件)重新拼出真实路径,不在 root 内就立即失败。

read_file:严格 UTF-8 解码,非法字节返回 invalid_utf8(不悄悄替换 �,因为 � 一旦进入上下文模型就看到了错误的文件内容)。执行顺序每步都是先否决再前进:校验 limit → safePath → 读字节 → 严格解码 → 按 limit 截断。limit 截断时尾部标注 ... (N more lines),避免模型猜内容是否被截。

write_file:自动建父目录(mkdir recursive),返回 bytes.byteLength 而非字符串长度。你好 的 length=2,但 UTF-8 实际 6 字节——结果与磁盘一致。

edit_file:不接受行号——行号随每次编辑整体偏移,模型很容易拿旧行号改错位(删掉第 2 行后,原第 4 行变成第 3 行)。要求旧文本+新文本,只替换第一处精确匹配,找不到不写回文件(所以重试是安全的)。读入整段只替换匹配片段,未改部分的 CRLF 不会被顺带改成 LF。

✅ read_file → 拿到精确片段 → edit_file
❌ 凭记忆/猜测拼 old_text → text_not_found

glob:返回 / 风格稳定排序的相对路径,无匹配返回 (no matches)(而不是空串——空串和「工具坏了」没法区分)。模式本身也必须相对;通配符前的固定前缀先过 safePath,遍历不进符号链接目录,每个匹配结果再查真实路径。三道防线,因为 glob 要遍历一整片目录树,检查点从一个变成成百上千个。

Node 适配器先把 ENOENT、EISDIR 等系统错误翻译成 core 定义的领域错误。handler 在工具边界把这些预期失败转成稳定错误码,不把本机绝对路径或堆栈泄漏给模型。

第 1 章和第 2 章的智能体,代码上只差一个工具集合。P02 构建是「先复用,再追加」:

export const P01 = Object.freeze({
  chapter: 1,
  capabilities: new CapabilitySet(["loop", "powershell"]),
});
export const P02 = Object.freeze({
  chapter: 2,
  capabilities: new CapabilitySet(["loop", "powershell", "tool_registry", "files"]),
});
// createChapterTwoTools 第一行就调用 createChapterOneTools(…),
// 所以 P02 一定包含 P01 的全部行为——这是结构保证。

工具从 1 个变成 5 个,模型可能在一轮里同时请求好几个工具。当前实现按顺序执行,结果历史必须严格配对:

assistant(tool_calls: write-1, read-1)
tool(tool_call_id: write-1, 写入结果)
tool(tool_call_id: read-1, 读取结果)

不能漏掉失败调用的结果,也不能在两个 tool 结果之间插入新的 user / assistant 消息。违反配对直接崩:

本章有一个刻意的不对称:

shell "Remove-Item note.txt"    → 弹审批,不敲 y 就不执行
write_file "note.txt" "..."     → 直接执行,你什么都看不到

两者都能改文件,但只有一个要审批。因为第 2 章还没有权限系统,只有一个硬编码的「shell 需要审批」;effect: "write" 这个标签已经贴上了,但没有任何代码去读它。

Set-Location 'F:\笔记\Agent实操\code'
npm run test:ch02

 Test Files  8 passed (8)
      Tests  47 passed (47)

比第 1 章多了 2 个文件、17 个测试——新增的正是文件工具和路径边界。不需要 API Key,不发网络请求。

npm run ch02 -- --prompt '只使用文件工具:写入 demo/note.txt,内容为 alpha;把第一处 alpha 改成 gamma;读取文件并用 glob 列出 demo/*.txt'

npm run agent-tutorial -- run --chapter 2 --prompt '读取 package.json,并列出 chapters/ch02/src/**/*.ts'

这条只用 read_file 和 glob,不产生任何文件改动,适合反复跑着观察。你在哪个目录敲命令,Agent 的工作区边界就在哪里——在 code/ 里跑,safePath 守的就是 code/。

npm run typecheck
npm test
npm run lint
npm run format:check
npm run build

这些测试不需要 API Key,也不访问网络。真实 OpenAI 运行只是额外验证,不替代离线契约测试。

第 1 章那张表仍然适用(配置、参数、审批相关)。下面是本章新增、和文件工具有关的情况:

1. 模型传 {"path":"note.txt","limit":"10"},会发生什么?为什么不自动转成数字?
2. nested/../secret.txt 化简后在工作区内,为什么还是拒绝?
3. 工作区里有个指向外部的 junction,第一关和第二关分别是什么结论?
4. write_file 写入 你好,返回的数字是 2 还是 6?为什么?
5. edit_file 的 old_text 在文件里出现 3 次,会改几处?
6. handler 的 catch 最后为什么要 throw error 而不是返回兜底错误码?