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

如果把工具写死在循环里，每加一个工具都要改循环。用 ToolRegistry 让循环只处理 ToolCall、PreparedToolCall、ToolResult 三种对象。

for (const call of assistant.toolCalls) {
  const prepared = tools.prepare(call);
  const result = prepared.error === undefined
    ? await tools.invoke(prepared, context)
    : prepared.error;
  this.#history.push(toolMessage(result.content, call.id));
}

feature 不直接创建 Node 适配器，只依赖 WorkspaceFileSystem 接口；bootstrap 注入具体实现。测试注入替身、生产注入 Node 适配器。

export interface WorkspaceFileSystem {
  readFile(workspace, relativePath, limit?): Promise<string>;
  writeFile(workspace, relativePath, content): Promise<number>;
  editFile(...): Promise<void>;
  globFiles(...): Promise<readonly string[]>;
}

第一关词法检查（拒绝空值、NUL、绝对路径、盘符、..、Windows 保留组件）；第二关解析磁盘上已存在的父路径，防止 junction / 符号链接越界。

拒绝示例:
  ../secret.txt
  C:\secret.txt
  /etc/passwd
  NUL.txt
  nested/CON.log
  file:stream
  trailing.

不接受行号。indexOf 精确匹配 oldText，替换第一处后原样写回，未修改部分的 CRLF 不会被改成 LF。找不到旧文本时不写回文件。

const index = current.indexOf(oldText);
if (index === -1) throw new TextNotFoundError(...);
const updated = current.slice(0, index) + newText
  + current.slice(index + oldText.length);
await writeFileBytes(target, Buffer.from(updated, "utf8"));

Zod schema 同时用于运行时校验和 OpenAI tool schema 生成：parameters: z.toJSONSchema(definition.inputSchema)。参数上的 .describe() 也会进入 JSON Schema。

const readFileInputSchema = z.strictObject({
  path: z.string().min(1).describe("Workspace-relative path"),
  limit: z.number().int().positive().optional()
    .describe("Optional maximum lines"),
});

抽象契约不好记，先看一遍实际发生的事。模型会自己把任务拆成四步，一步一轮。下面只列每轮的关键字段，第 1 章那套 tool_call_id 配对规则完全不变。

同样一件事，只有 shell 时模型得自己拼一串 PowerShell：

Set-Content -Path .\demo\note.txt -Value 'alpha' -Encoding utf8
(Get-Content .\demo\note.txt -Raw) -replace 'alpha','gamma' |
    Set-Content .\demo\note.txt -Encoding utf8 -NoNewline
Get-Content .\demo\note.txt
Get-ChildItem .\demo\*.txt | Select-Object -ExpandProperty Name

问题不在于「长」，而在于每一处都可能悄悄出错：

模型可能试图访问工作区外的文件。这时不会抛异常打断循环，而是回填一条错误结果：

assistant  tool_calls=[ { id:"call_9", name:"read_file",
                          arguments:'{"path":"../secret.txt"}' } ]
tool       tool_call_id="call_9"
           content="Error [path_escape]: Path escapes workspace: ../secret.txt"

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'

Get-Content .\demo\note.txt
gamma

这条命令会真实创建 code/demo/note.txt。整个过程模型会调用四次工具，对应第 4 节那张表。

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

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

第 3 步只用 read_file 和 glob，不产生任何文件改动，适合反复跑着观察。第 4 步这些测试不需要 API Key，也不会访问网络；真实 OpenAI 运行只是额外验证，不替代离线契约测试。

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

• 加工具的正确姿势是「定义 + 注册」，Agent Loop 一行都不用改。
• 一份 Zod schema 同时供模型阅读和运行时校验，从根上消除「文档和实现不一致」。
• 文件工具的安全性来自 safePath 的两道检查：词法拦明显越界，磁盘解析拦符号链接。

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