Tool 是类型化的环境动作

#你将得到什么

到第 05 章为止，模型已经可以生成完整的 ToolCall。但这个调用仍是一项不可信的 提议：工具名可能不存在，参数可能缺字段或类型错误，工具本身也可能抛出异常。 TypeScript 无法约束模型在运行时发来的 JSON。

本章处理一个新问题：怎样把不可信调用变成一条可信、完整的环境观察。

你将实现三个连续边界：

1. validator 把 unknown 参数收窄成工具需要的类型；
2. ToolRegistry 决定本次运行允许哪些工具；
3. executeToolCall() 负责查找、验证、执行和结果归一化。

完成后，成功、未知工具、参数错误和工具异常都会返回 ToolResultMessage。每条结果 都保留原调用的 id 和 name。上层不需要用一个分支处理成功，再用三个异常通道处理 失败。

本章只修改：

packages/pi-course/src/tool.ts

重新练习时，运行：

npm run practice -w @pi/course -- 06 <新目录>

练习目录会保留第 05 章源码，注入第 06 章测试，并放入一份只用于学习的代码骨架。 骨架已经声明 Schema、Tool、ToolRegistry 和 executor 的公共签名，主要的 未实现入口都带有 Lab 编号。验证、注册、执行和错误归一化仍要由你完成。

如果想从头再来，请创建另一个练习目录。隔离目录没有 Git 历史，不要修改注入测试， 也不要在里面运行恢复 commit 的命令。

本章不变量是：

执行器每收到一个完整的 tool call，都必须返回一个 ToolResultMessage。结果沿用 原调用的 toolCallId 和 toolName；失败只改变内容、details 与 isError。

#先建立全景

模型只负责提出调用。程序拥有信任边界：

ToolCall
  id / name / arguments: unknown
             │
             ▼
      ToolRegistry.get(name)
             │
      ┌──────┴──────┐
    未找到          找到 Tool
      │               │
      │        schema.parse(arguments)
      │               │
      │        ┌──────┴──────┐
      │      验证失败       typed input
      │        │              │
      │        │        tool.execute()
      │        │              │
      └────────┴──────┬───────┘
                     ▼
             ToolResultMessage

三个组件各自回答一个问题：

Tool 把模型可见的描述和程序可执行的函数放在同一个契约中：

export interface Tool<P, D = unknown> {
  name: string;
  description: string;
  schema: Schema<P>;
  execute(
    parameters: P,
    context: ToolContext,
  ): Promise<ToolOutput<D>>;
}

schema 同时提供两种能力。parse() 在运行时把 unknown 收窄成 P； jsonSchema 告诉 provider 允许生成哪些字段。两者必须描述同一组参数。否则，模型 以为可以生成的参数会被执行器拒绝，或者执行器接受了模型并不知道该怎样生成的参数。

#第一步：让 validator 同时携带行为和描述

脚手架已经给出这个类型：

export type Validator<T> = ((value: unknown) => T) & {
  jsonSchema?: Record<string, unknown>;
  optional?: boolean;
};

Validator<T> 要完成两件事：作为函数验证输入，同时用对象属性保存元数据。 Object.assign() 可以把函数和元数据合成同一个值：

export const stringValue: Validator<string> = Object.assign(
  (value: unknown) => {
    if (typeof value !== "string") throw new Error("必须是 string");
    return value;
  },
  { jsonSchema: { type: "string" } },
);

optionalString 收到 undefined 时直接返回 undefined，其他值复用 stringValue()。它的元数据还要带 optional: true。optionalPositiveInteger 使用相同结构，只接受大于等于 1 的整数。

objectSchema(shape) 也要完成两件事。

先从 shape 生成 provider 看见的 JSON Schema：

properties           每个 validator 的 jsonSchema
required             没有 optional 标记的 key
additionalProperties false

再实现 parse(value)：

1. 拒绝 null、数组和其他非对象值；
2. 只遍历 shape 中声明的 key；
3. 把输入对应字段交给各自 validator；
4. 返回一个新对象。

因为只遍历 shape，输入中的额外字段不会进入结果。这里的“清洗”指构造新对象， 不表示修改传入对象。

代码骨架已经写好下面这段映射类型（mapped type）：

{
  [TKey in keyof TShape]: ReturnType<TShape[TKey]>;
}

它把每个 validator 的返回类型映射到同名字段。你只需实现运行时逻辑，不必重新设计 这段泛型。

npm run build -w @pi/course
node --test --test-name-pattern="validator" \
  packages/pi-course/dist/test/06-*.test.js

#第二步：让每次运行显式持有动作空间

ToolRegistry 使用自己的 Map<string, Tool> 保存工具。不要把它放到模块级全局变量； 不同产品入口可以授权不同工具，测试也需要创建互不影响的 Registry。

四个方法的职责很窄：

register(tool)  重名时抛错，否则保存
get(name)       返回工具或 undefined
list()          按注册顺序返回工具数组
definitions()   只导出 name、description、schema

definitions() 的结果会交给第 05 章的 provider adapter。execute 是本地函数， 不能序列化到网络请求中。工具没有 jsonSchema 时，可以使用 { type: "object" } 作为最小描述；本章的 objectSchema() 会提供更精确的定义。

npm run build -w @pi/course
node --test --test-name-pattern="Registry" \
  packages/pi-course/dist/test/06-*.test.js

#第三步：让每种预期结果都带着原调用返回

executeToolCall() 的顺序不能交换：

1. registry.get(call.name)
2. tool.schema.parse(call.arguments)
3. tool.execute(typedInput, { ...context, callId: call.id })
4. 把 ToolOutput 变成 ToolResultMessage

名称不存在时，不调用 schema。验证失败时，不调用 execute。成功时，原样保留 工具返回的 content、details 和 isError；工具没有提供 isError 时使用 false。

可以先写一个 failedResult(call, error)，让三类可预见的失败使用同一种消息结构：

{
  "role": "toolResult",
  "toolCallId": "i",
  "toolName": "echo",
  "content": [
    {"type": "text", "text": "Tool echo failed: 必须是 string"}
  ],
  "details": {"error": "必须是 string"},
  "isError": true
}

执行器只把 error.message 放入结果，不包含 stack。它无法自动识别任意字符串中的 绝对路径或密钥。因此，工具实现仍要避免把秘密写进异常消息，产品层以后还要加入 专门的脱敏策略。

ToolContext 还包含 signal 和进度回调 reportProgress：

{
  ...context,
  callId: call.id,
}

执行器负责原样传递它们。signal 能否及时停止动作，取决于工具是否主动检查并响应。 本章的测试只证明取消信号会到达工具；执行器无法强制一个忽略 signal 的工具停下。

details 供日志或 UI 使用；content 会进入下一轮模型上下文。即使 UI 不读取 details，模型看到的 content 也不应改变。

npm run build -w @pi/course
node --test --test-name-pattern="执行器" \
  packages/pi-course/dist/test/06-*.test.js
node --test packages/pi-course/dist/test/06-*.test.js

#故意把它弄坏

临时把 schema 验证移到 execute() 之后：

错误顺序：lookup → execute(raw arguments) → parse

当 echo 收到 { value: 1 } 时，副作用计数会从 1 变成 2。测试会先在 executionCount 上失败，之后才会比较错误结果。

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/06-*.test.js

#可选迁移练习

#小结

validator 负责验证参数，Registry 保存本次运行允许使用的工具，executor 按固定顺序 把调用变成结果。即使工具名不存在、参数不合法或动作抛错，调用仍会得到完整、配对 的 ToolResultMessage。

第 07 章不再处理这些局部错误。它只负责把模型消息、工具调用和工具结果按正确顺序 写回同一条反馈回路。