AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

带 Schema 校验的 Tool Registry ​

一个 agent 连校验都做不了的 tool，本质上就不能安全调用。先把 registry 和 schema checker 做出来，再谈工具本身。

类型： Build 语言： Python 前置要求： 第 13 阶段第 01-07 课、第 14 阶段第 01 课 预计时间： ~90 分钟

学习目标 ​

  • 维护一份带类型的注册表：tool name -> schema -> handler，让 dispatcher 只问一次、之后就能信。
  • 实现一个 JSON Schema 2020-12 子集，覆盖 90% 工具调用真正会用到的关键字。
  • 返回精确到 json-pointer 形状的错误路径，让模型一轮往返就能自修。
  • 默认拒绝重复注册，除非显式 override；静默覆盖就是线上 tool catalog 漂移的起点。
  • 保持 validator 纯净（无 I/O、无时间、无全局），这样 replay log 时能重跑。
figure
cf-registry-validate

为什么 registry 要先于 tool ​

2026 年的 coding agent，注册进系统的 tool 往往比模型一次上下文窗口装得下的还多。一个稍像样的 harness 会注册 200 个 tool，而单个 turn 真正暴露给模型的只有 10-40 个。registry 就是三件事的真值源：

  • 到底有哪些 tool
  • 它们的参数长什么样
  • 最终该调用哪个 handler

这三件事钉住之后，harness 的其他层就不用再猜。我们要避免的，就是“handler 已经发出去了但没有 schema”，或者“schema 发出去了但没人验证”。这两种都很常见，也都会把下一层（第 23 课的 dispatcher）变成猜谜游戏，最后唯一的失败模式就是 handler 自己炸出一条栈。

Tool Record 长什么样 ​

text
ToolRecord
  name        : str          (唯一；小写字母数字和下划线段，以点分隔，如 snake_case.segment.case)
  description : str          (单行，展示给模型)
  schema      : dict         (JSON Schema 2020-12 子集)
  handler     : Callable     (同步或异步，返回 Any)
  idempotent  : bool         (dispatcher 用它决定是否可重试)
  timeout_ms  : int          (覆盖 dispatcher 默认超时)

validator 只碰 schema，完全不碰 handler。这是故意的。schema 是数据，handler 是代码。把两者缠到一起，你迟早会把校验逻辑偷塞进 handler，而这正是我们要掐死的 bug。

JSON Schema 2020-12 子集 ​

完整的 2020-12 规范像一篇论文。我们只拿 8 个关键字：

text
type           string / number / integer / boolean / object / array / null
properties     property 名 -> schema 的映射
required       必填字段名列表
enum           允许的原始值列表
minLength      整数，仅作用于字符串
maxLength      整数，仅作用于字符串
pattern        兼容 ECMA-262 的正则，仅作用于字符串
items          作用于数组每个元素的 schema

这已经够覆盖真实工具 API 的大多数需求。我们故意不加 oneOf、anyOf、allOf、$ref、条件分支，因为一旦上这些，validator 就会膨胀成一个带循环引用的树遍历器。这里要建的是 registry，不是再造一个 JSON Schema 引擎。

Json Pointer 错误路径 ​

校验失败时，validator 返回一组错误。每个错误都要带一条指向输入内部位置的 json pointer。pointer 就是一个以 / 开头、后面跟属性名或数组下标的路径。

text
{"a": {"b": [1, 2, "x"]}}
                    ^
                    /a/b/2

模型读这类错误路径，比读自然语言更快。如果 schema 要求 args.user.email 是字符串，而模型传了整数，错误最好直接给 /user/email 和 expected_type: string。这样模型下一轮就能自己修，不用你再写一段废话解释。

注册与 override ​

register(name, schema, handler, **opts) 默认拒绝重复注册。调用方必须显式传 override=True 才能替换。这不是洁癖，是运维卫生。代码库里两个不同模块悄悄注册了同一个 tool name，这种 bug 在线上能耗你一周。

registry 暴露 3 个读接口：

  • get(name)：返回 record，否则抛错
  • validate(name, args)：返回 Ok 或错误列表
  • names()：按注册顺序返回 tool name

Validator 是什么，不是什么 ​

它是一个递归的 schema 树单次遍历器，而且必须是纯函数。它不调用 handler，不做类型强转（字符串 "42" 不会通过 number schema），也不会偷偷截断输入。

它不是安全边界。一个恶意 handler 就算通过校验，也一样能乱来。第 23 课的 dispatcher 会继续加 timeout 和 sandbox。registry 管的是“形状”，不是“后果”。

形状 ​

mermaid
flowchart TD
    code[你的代码]
    reg[ToolRegistry<br/>name<br/>schema<br/>handler<br/>timeout]
    out[Ok 或错误列表]
    code -->|注册 name, schema, handler| reg
    reg -->|校验 args| out

怎么读代码 ​

code/main.py 里定义了 ToolRegistry、ToolRecord、ValidationError，以及 8 个 validator 函数。validator 按 schema["type"] 分发；如果 schema 只有 enum，就走无类型 enum 校验。每个类型校验器要么返回空列表，要么返回一组 ValidationError。顶层 walker 在递归时负责拼接错误，并在下钻时把路径段前缀补上。

code/tests/test_registry.py 覆盖了注册、override、校验成功、带路径的校验失败，以及 8 个关键字的全部分支。

往前走 ​

一旦这节落地，后面最想补的两个扩展通常是：

  • 针对本地 definitions block 的 $ref 解析
  • additionalProperties: false 这种严格形状限制

这两个都不大，也都很常见。但为了让文件保持在“一遍能读完”的尺度里，这节课先不带它们。下一课（22）会把这个 registry 暴露到 JSON-RPC stdio transport 上；再下一课（23）会把两者包进带 timeout 和 retry 的 dispatcher。