schema 生成 协议

它是什么

schema 生成是指从一份声明式 spec 算出 JSON Schema，而不是手抄，从根上消除「schema 与实现互相漂移」：第 06 章手写 tools 数组时，参数的真实定义写在实现里、schema 描述手抄在数组里——同一份契约有两份拷贝，改一处忘一处，模型按旧契约调用、线上偶发炸。这种 bug 不在测试里出现（测试只覆盖你记得更新的路径），是工具系统里最阴险的一类故障。

为什么 TS 要绕路

Python 生态能直接读函数类型注解和 docstring 生成 schema（如 smolagents 的 @tool），因为 Python 的类型是运行时对象；TS 的类型在编译后被擦除，运行时拿不到。引入类型编译器或运行时类型库（zod/typebox）代价又高，所以本章用一份运行时可见的参数声明（name / type / description / required）作为唯一契约来源，注册时由十行小生成器算出 schema：

function generateSchemaFromSpec(spec) {
  const properties = {};
  const required = [];
  for (const p of spec.parameters) {
    properties[p.name] = { type: p.type, description: p.description };
    if (p.required !== false) required.push(p.name);
  }
  return { type: 'object', properties, required };
}

小结

spec 写一次，schema 是算出来的，不存在「忘改」这个操作——漂移问题从根上消失。等工具系统复杂到需要嵌套对象、联合类型、跨工具复用类型时，再评估 zod/typebox 也不迟（第 08 章）。