Pi Agent 源码级教程
M15

契约与遥测 —— 一份声明,五种解释

11,967 字 · 含 534 行代码 · 约 56 分钟

一个工具定义只有十四行,却要同时满足五个读者:发给模型的 JSON Schema、 TypeScript 里的 ReadToolInput、运行时校验器、给人看的错误信息、 provider 的 strict 方言。

这五个读者手里如果各有一份定义,它们不会同时出错。它们会"大部分时候一致", 然后在某一天对一个具体字段产生分歧。

想象一下这个故障:模型调用 read,传了 { path: "a.ts", offset: "10" }。 类型检查通过(string 也能塞),JSON Schema 发出去也没问题,模型以为合法。 运行时到了校验器那一步——offset 要的是数字,于是判非法。用户看到的是一句 "工具调用失败",真实原因是两份定义对同一个字段的理解不同。

这种 bug 最难查的地方在于:它不发生在编译期,也不发生在单元测试里, 它发生在三个东西各自都对、合起来不对的时候。

让五个读者各写一份,它们不会同时出错。它们会"大部分时候一致", 然后在某一天对一个具体字段产生分歧。

想象一下这个故障:模型调用 read,传了 { path: "a.ts", offset: "10" }。 类型检查通过(string 也能塞进去),发给模型的 JSON Schema 也没拦, 模型以为合法。运行时走到校验器那一步——offset 要的是数字,判非法。 用户看到的是一句"工具调用失败",真实原因是两份定义对同一个字段的理解不同。

难查的地方在于:它不在编译期,也不在单测里,它发生在三个东西各自都对、 合起来不对的时候。

而不一致的代价不是编译报错,是 模型以为合法的值,运行时判非法。 §一 会用一个真实字段把这句话讲实。

这一章拆两个包。它们存在的全部理由,就是让这五个读者读同一份声明:

包 文件 行数 一句话
schema 43 4,565 不用 eval 的 JSON Schema 校验器
telemetry 8 1,572 与厂商无关的遥测契约

一共 51 个文件 / 6,137 行,占全仓不到 3%,而且不产出任何功能。

这两个包没有一行代码会出现在用户体验里。它们买的是另一种东西: 同一个值,在任何一处被解释,结论都一样。这一章的价值不靠功能计数, 靠两个可以自己复跑的数字——1 条已知失败,和一张把"输"列出来的排行榜。

翻 package.json,两个包的 dependencies 都是空的。有依赖的是用它们 的那些包:

使用方 用 schema 干什么
ai 校验模型发回来的工具参数;把 schema 改写成 provider 的 strict 方言
agent Static<S> 给工具注册表定型
durable 工具的入参与 structuredOutput 两头校验
chord contract、snapshot、JSON 列的类型
coding-agent models.json 这类配置文件的形状

读完这一章,你应该能回答四个问题:

  1. 一份声明喂给五个读者,为什么不能各写一份?不一致了会坏在哪一步?
  2. 不用 ajv、不用 zod,自研校验器的三条硬约束是什么?
  3. errors() 为什么只在失败路径上跑,代价是什么?
  4. 同一份 schema,为什么校验器那边把每个关键字都当敌人,遥测那边一行校验都不做?

下面两张表是文件地图。现在不用读——后面哪一节提到某个文件名,回来查就行。

schema/src 的主要文件:

文件 行数 职责
compiler.ts 593 schema → 闭包
coerce.ts 556 把模型给的值掰成 schema 要的值
checks.ts 451 闭包原语:and / declaredObject / guardObject
explain.ts 390 失败时才走的那一遍
annotations.ts 208 unevaluatedProperties 的注解追踪
resolver.ts 203 $ref / $id / $anchor
builders.ts 200 obj() / str() / opt(),兼 TS 类型
validator.ts 93 compile()、Validator、CoercingValidator
typebox-static.ts 76 读 TypeBox 的 '~kind',不 import TypeBox
formats/ 31 文件 / 1,682 date-time / ipv4 / idn-hostname 等 21 种

telemetry/src 全部:

文件 行数 职责
index.ts 465 契约:span / metrics / propagation + 类型推导
memory.ts 463 InMemoryTelemetryContext,测试与本地开发用
metrics.ts 145 createTypedMetrics,指标名与属性类型绑定
render.ts 49 把 span 渲染成文本
noop.ts 37 什么都不做的默认实现
testing/ 3 文件 / 415 适配器一致性测试套件

零、读这章之前,你需要先知道一件事

条件类型就是类型层面的 if:S extends A ? X : Y(能当 A 用就给 X)。 递归类型是在自己里面引用自己,用来"展开"任意深度的结构。

没有它会怎样:把 Static<S> 当成一个固定的对象类型去读,碰到三层嵌套就绕不出来, 最后只能背结论。它其实是一个逐层拆解的规则。

本书哪里用到:§二 三层拆解;附录 B 有可 npx tsx 跑的最小片段。


一、问题:一份 schema,五个读者

一个工具长这样(durable/src/tools/read.ts:34-43):

ts
const readSchema = obj(  {    path: str({ description: "Path to the file to read" }),    offset: opt(num({ description: "Line number to start from" })),    limit: opt(num({ description: "Maximum lines to read" })),  },  { open: true },);export type ReadToolInput = Static<typeof readSchema>;

十四行,做了四件事:

  1. 生成一个普通的 JSON Schema 对象,可以 JSON.stringify 进请求体, 发给模型。
  2. 生成 TypeScript 类型 ReadToolInput,函数体里的 input.path 有类型。
  3. 生成运行时校验器,模型送回来的 arguments 要过这一关。
  4. 失败时生成给人看的错误,这份错误还要能塞进下一轮对话。

再加两件本章会讲的:

  1. provider 的 strict 模式要的另一种写法:所有属性必填、对象封闭。
  2. MCP server 送来的 schema 可能是恶意或残缺的,校验器得扛住。

一件声明,五个读者。如果每个读者各写一份,它们迟早会不一致——而"不一致" 在这里的具体含义是:模型以为合法的值,运行时判非法。用户看到的是 "工具调用失败",实际原因是两个包对 additionalProperties 的默认值理解 不同。

所以这份声明必须只有一处,且这一处必须能被所有读者以同样的语义解释。 这就是 pi-schema 存在的理由。不是"代码复用",是"语义单一来源"。

1.1 为什么不用 ajv、不用 zod

三个硬约束把现成的库排除掉了。

一、不能有 eval。 packages/schema/package.json 的 description 写着:

JSON Schema validation without eval: drafts 2020-12 and 7, compiled into plain closures

ajv 的默认模式是 new Function("schema", "..." )——把 schema 编译成源码 再 eval。这在 Node 里没问题,在 Cloudflare Workers 里会被拒绝,在带 CSP 的 浏览器里也会被拒绝。而 M13 讲的 codemode 沙箱、scripts/browser-smoke-entry.ts 这个浏览器入口,都需要同一套校验能跑。

二、schema 来自不可信来源。 types.ts:4-6 的注释:

Schemas come from tool definitions, MCP servers and other untrusted sources, so compile() reads every keyword defensively instead of trusting a static shape

注意 JsonSchema = boolean | object(types.ts:7)——不是 SchemaObject。 schema 本身可以是 true 或 false,这两个是合法的 JSON Schema;也可以 是一个对象,但里面每个关键字的值都可能是垃圾。编译器不能假设 properties 是对象、required 是数组。

三、必须和 TypeBox 互操作。 工具可能用 pi-schema 的 builder 定义, 也可能是别的包里的 TypeBox schema。typebox-static.ts:1-3:

The static types of TypeBox-built schemas, read from the type shapes TypeBox 1.x declares ('~kind', '~optional', '~readonly', '~unsafe') without importing TypeBox

只读类型形状,不 import。TypeBox 是 400 KB 的包,工具参数的类型推导 不需要把它拉进依赖图。

1.2 证据:8.5 KB,和 2,222 / 2,223

三条约束只解释了"为什么不能用现成的"。还剩一个问题没答:自己写一个, 凭什么说不比现成的差? 仓库里放了两样东西回答它:一份官方测试套件, 一个可以复跑的 bench。

先看一致性。 conformance.test.ts 跑的是官方 JSON-Schema-Test-Suite 的 两个 draft(2020-12 与 7),含 optional 和 format 用例,一共 4,213 条。 其中 9 条被登记成"已知失败":

ts
// schema/test/conformance.test.ts:9-22(节选)const KNOWN_FAILURES = new Set([  // Vocabularies switched off by a custom meta-schema are not supported.  "draft2020-12/vocabulary > schema that uses custom metaschema ...",  // A $ref to a document of another draft uses the compile's draft.  "draft2020-12/optional/cross-draft > refs to historic drafts ...",  // contentMediaType and contentEncoding are annotations.  "draft7/optional/content > validation of string-encoded content ...",]);// 同一文件 :37-38:清单里的条目必须继续失败(known ? it.fails : it)(test.description, () => {

it.fails 比 it.skip 狠在它是反向断言:这 9 条必须继续失败。哪天 哪条悄悄通过了,测试变红,逼你去更新清单——既防退化,也防"偷偷修好了 却没人知道"。

九条的分布能对上 README 里的第二个数字:1 条落在 core,8 条落在 optional(format-assertion ×2、cross-draft ×2、content 编码 ×4)。 README 写的是"通过 2,222 / 2,223 条 core 用例"——1,298 条 draft 2020-12 加 925 条 draft 7 正好 2,223,减掉那 1 条,等于 2,222。两个数字互相验证, 谁都编不了。这也是读 README 的一个笨办法:凡是给了分母的地方,都拿它 和别处的分子对一遍。

再看它输在哪。 README 里留了一张排行榜,敢把输的数字写出来:

项目 pi-schema 对手
扁平对象每次校验 13–80 ns TypeBox 7–15 ns
编译一个 schema 25 µs(运行时) Ajv 生成代码 1.8 ms
build 期产出 0 行 JS Ajv 8.9 KB / schema
3,200 个 schema 的验证器 不生成,无处可导 Ajv 生成版全 import 40 MB 堆
包体积(min+gzip) 8.5 KB Zod 40 KB、TypeBox 400 KB

读法就一句:它比对手慢,但慢在同一个数量级;它不生成代码,所以在严格 CSP 下能跑。 这是全书反复出现的同一个交换——拿一点性能,换一个能部署 的环境。

这是全书反复出现的同一个交换——拿一点性能,换一个能部署的环境。 unevaluatedProperties、unevaluatedItems、dependentSchemas、 dependentRequired、if/then/else、not,以及一切非本地 $ref。 被拒的 schema 整组判失败——draft 2020-12 core 挂 405 / 1,298,draft 7 core 挂 107 / 925。工具 schema 里 not 和 if 都不罕见,这条死角是硬的。

bench 可复跑(约 12 分钟):

bash
cd packages/schema && npm run bench
powershell
cd packages/schema; npm run bench

脚本在 test/bench/:conformance.ts 让每个库跑同一份套件,zod.ts 把 schema 翻译成原生 Zod 再跑。它比的是五项:conformance、速度、setup、 内存、体积;再带上「禁止从字符串生成代码」跑一遍,是看「不许 eval」到底 贵多少。

这些数字是作者自测的,不是第三方评测。 本书引用它,理由不是"权威", 是"你能自己跑一遍"——这也是判断一切 benchmark 的唯一可靠办法:看它给 没给复跑命令,以及敢不敢把输的那一栏列出来。

1.3 决定:三个关键字集合

compiler.ts 的做法是把 schema 编译成一堆闭包。编译期只做一次, 之后每次校验就是几次函数调用。这没什么新鲜的——新鲜的是它对"什么值得 专门化"的判断,看 plain() 怎么分组:

ts
// schema/src/compiler.ts:139-166(节选)private plain(node: SchemaObject, base: string): Check {  const parts: Check[] = [];  const types = node.type === undefined    ? undefined    : Array.isArray(node.type) ? node.type : [node.type];  const single = types?.length === 1 ? types[0] : undefined;  let typeInGroup = false;  ...  const string = this.stringGroup(node, single === "string");  if (string !== undefined) parts.push(string);  const numeric = single === "number" || single === "integer";  const number = this.numberGroup(    node, single === "number" ? 1 : single === "integer" ? 2 : 0);  if (number !== undefined) parts.push(number);  const object = this.objectGroup(node, base, single === "object");  if (object !== undefined) parts.push(object);  const array = this.arrayGroup(node, base, single === "array");  if (array !== undefined) parts.push(array);  typeInGroup = ...;  if (types !== undefined && !typeInGroup) parts.unshift(typeCheck(types));  this.inPlace(node, base, parts);  return and(parts);}

关键词按它们约束的类型分组:minLength / pattern / format 归字符串, minimum / multipleOf 归数字,properties / required 归对象, items / contains 归数组。

一个值只需要判断一次"它是什么类型",然后进对应的那一组。如果分开判断, { type: "string", minLength: 3 } 会先判类型、再判长度,而长度那一步又 要确认一次它是字符串。

typeInGroup 这个标志是"省掉一次类型判断"的记账:如果类型已经在组里 判过了,就不再 unshift(typeCheck(types))。这一行看着琐碎,但它决定了 最常见的 schema({ type: "string", minLength: 1 })编译出来是两个 闭包还是一个。


二、编译:从 schema 到闭包

入口只有一个(validator.ts:14-27):

ts
export function compile<S extends JsonSchema>(  schema: S,  options: CompileOptions = NO_OPTIONS,): Validator<Static<S>> | CoercingValidator<Static<S>> {  const check = compileCheck(schema, options);  return options.coerce === true    ? new CoercingValidator(schema, options, check)    : new Validator(schema, options, check);}

返回的 Validator 有两个东西:一个 check 函数,一个懒建的 errors。

ts
// schema/src/validator.ts:31-41(节选)export class Validator<T = unknown> {  /** Whether `value` is valid. A plain function: it may be passed around   *  without its validator. */  readonly check: (value: unknown) => value is T;

注释值得抄下来:check 是一个普通函数,可以脱离 validator 传走。

它的类型是 value is T,所以 if (validator.check(v)) 之后 v 就变成了 T,不需要断言。这就是"编译产物"和"类型谓词"合并成一件事——schema 编译 出来的闭包,恰好就是 TypeScript 判断 v is T 的那件事。

value is T 这个返回值写法(而不是 boolean)叫类型谓词: 返回 true 的那一分支里,编译器把参数的静态类型自动收窄成 T。 写成 boolean 就丢了这个能力,后面每处都得自己 as T。附录 B §2.4 三行讲完。

2.1 错误只在失败时才算

ts
// schema/src/validator.ts:50-54errors(value: unknown): ValidationError[] {  if (this.check(value)) return [];  this.explainer ??=    new Explainer(compiler(this.schema, this.options), this.schema);  return this.explainer.errors(value);}

两处懒:

  • 先跑 check。值合法就返回 [],永远不构造 Explainer。
  • ??=:一个 validator 只在第一次失败时建解释器,之后复用。

durable/src/harness/tool.ts:793-794 就是这么用的:

ts
if (validator.check(value)) return undefined;const [first] = validator.errors(value);

工具每次返回 structuredOutput 都校验,但绝大多数返回是合法的,所以 98% 的调用只付一个闭包的开销,一次垃圾回收都不需要。

2.2 两次编译:RESTART 哨兵

$dynamicRef 是个奇怪的关键字:它的目标不是编译期决定的,而是在运行时 沿着"动态作用域"往上找。这就要求所有 check 在运行时维护一个作用域栈—— 但如果 schema 里根本没有 $dynamicRef,这个栈就是纯浪费。

解法是先乐观地编一遍(validator.ts:83-93):

ts
function compiler(schema: JsonSchema, options: CompileOptions): Compiler {  const plain = new Compiler(schema, options, false);  try {    plain.root();    return plain;  } catch (error) {    if (error !== RESTART) throw error;    return new Compiler(schema, options, true);  }}

编译过程中一旦遇到"确实需要动态作用域"的书签式 $dynamicRef, bookended() 就 throw RESTART(compiler.ts:228)——一个 Symbol, 不是 Error。外层捕获它,扔掉整个编译器,带 dynamic = true 重来。

注释说得很直白:

Most schemas compile without tracking the dynamic scope; one with a bookended $dynamicRef compiles again with it.

代价是遇到 $dynamicRef 时编译两次;收益是其他所有 schema 的每一条 热路径上都没有那个 scope 数组。用一个必然失败的异常换全局的常量因子, 这是典型的"稀有路径付双倍,常见路径付零"。


三、闭包怎么造出来

check() 是递归的主循环(compiler.ts:98-113):

ts
check(node: unknown, base: string): Check {  if (node === true) return ALWAYS;  if (node === false) return NEVER;  if (!isSchemaObject(node))    throw new Error(`A schema must be an object or a boolean, got ...`);  const cached = this.cache.get(node);  if (cached !== undefined) return cached;  const bare = this.bareType(node);  if (bare !== undefined) return bare;  const slot: { check: Check | undefined } = { check: undefined };  this.cache.set(node, indirect(slot));  const check = this.build(node, this.r.baseFor(node, base));  slot.check = check;  this.cache.set(node, check);  return check;}

四个细节,每个都在解决一个具体问题:

true → ALWAYS,false → NEVER。 两个模块级常量,全包共用一份。

按 schema 对象缓存。 Map<object, Check>。同一个子 schema 对象被引用 两次($ref 到同一个 definitions 项、或者 JS 里复用了同一个对象字面量), 只编译一次。

先放 indirect(slot) 再编译。 这是处理递归的手法。schema 可以是 自引用的(树的节点里有节点);如果直接递归编译,build 遇到自己就栈溢出。 所以先把占位闭包放进缓存,编译完成后再把真正的实现塞进 slot:

ts
// schema/src/checks.ts:95-98export function indirect(slot: { check: Check | undefined }): Check {  return (v) => (slot.check as Check)(v);}

多一层函数调用的代价,换来任意深度的递归都能编译。

bareType() 抄近道(compiler.ts:128-136):

ts
private bareType(node: SchemaObject): Check | undefined {  let type: unknown;  for (const k in node) {    if (k === "type") type = node.type;    else if (!NEUTRAL_KEYWORDS.has(k)) return undefined;  }  if (type === undefined) return ALWAYS;  return typeof type === "string" ? TYPE_CHECKS.get(type) : undefined;}

如果一个 schema 只有 type 和几个中性关键字(title / description / default 这类注解),它的 check 就是 TYPE_CHECKS 里那个共享的 typeof v === "string"——全包只有一个闭包实例。{ type: "string" } 这种最常见的子 schema 零成本。

3.1 对象的专门化:一个三元组数组

对象是工具参数的主力形态,所以 objectCore(compiler.ts:324-355)做了 一件很具体的事:把 properties 摊平成一个三元组数组。

ts
// schema/src/compiler.ts:337-346(节选)// One array per object: key, check, flags// (leaf code, required, key also names an Object.prototype member).const entries: unknown[] = [];for (const k of keys) {  const check = this.check(properties[k], base);  const flags =    (LEAF_CODES.get(check) ?? 0) |    (required.includes(k) ? REQUIRED : 0) |    (k in Object.prototype ? INHERITED : 0);  entries.push(k, check, flags);}

三个字段塞进一个扁平数组而不是 {key, check, required} 对象数组:省内存, 并且减少一次属性访问。

flags 里那三个位各有各的原因:

  • LEAF_CODES:如果这个属性的 check 就是 IS_STRING / IS_NUMBER 这类内置的,就把一个整数码放进去,运行时用 switch 内联执行, 不调用函数(checks.ts:34)。
  • REQUIRED:要求计数时不需要再查 required.includes(k)。
  • INHERITED:k in Object.prototype。这条对应一个真实的安全问题—— { in: str() } 这样的 schema,如果对象是 {}(没有自有属性), "in" in obj 会因为原型链而返回 true。declaredObject 因此用 for...in 遍历值的自有可枚举键,而不是用 schema 的键去查值:
ts
// schema/src/checks.ts:229-243(节选)for (const k in o) {  let i = 0;  while (i < n && entries[i] !== k) i += 3;  if (i === n) {    if (closed) return false;    continue;  }  const x = o[k];  if (x === undefined) continue;  const f = entries[i + 2] as number;  const c = f & CODE;  if (c !== 0 ? !leafOk(c, x) : !(entries[i + 1] as Check)(x)) return false;  if (f & REQUIRED) required++;}return required === requiredCount;

entries[i] !== k 是按步长 3 遍历扁平数组:i += 3 直接跳到下一个 键。注释解释了为什么用 for...in 而不是 Object.keys():

The value's own keys are walked with for...in (whose o[k] V8 reads from the enum cache, unlike a load by a name from a list)

V8 对 for...in 循环里的 o[k] 有枚举缓存,而从字符串列表里取 o[name] 走的是字典查找——慢一个量级。

x === undefined 跳过的行为也写在注释里:值为 undefined 的属性视为 不存在。这让 { path: undefined } 和 {} 在 required 判断上等价。

3.2 分支:and() 按数量专门化

ts
// schema/src/checks.ts:73-93(节选)export function and(parts: readonly Check[]): Check {  switch (parts.length) {    case 0: return ALWAYS;    case 1: return parts[0];    case 2: {      const [a, b] = parts;      return (v) => a(v) && b(v);    }    case 3: {      const [a, b, c] = parts;      return (v) => a(v) && b(v) && c(v);    }    default:      return (v) => {        for (let i = 0; i < parts.length; i++) if (!parts[i](v)) return false;        return true;      };  }}

case 0 和 case 1 不只是优化——它们是结构消解:and([]) 不产生 闭包,and([x]) 直接返回 x。所以一个只写了 { type: "object", properties: {...} } 的 schema,编译结果就是 declaredObject 那一个函数, 中间没有包裹层。

case 2 / case 3 把数组解构成局部变量,让 V8 把 a、b 放进寄存器。 4 个以上退回循环——再多就不值得展开了。

3.3 标签联合:省掉的是指数

anyOf / oneOf 的朴素实现是"每个分支都试一遍"。工具结果里常见的 union([obj({ type: lit("text"), ... }), obj({ type: "image", ... })]) 这样写,每个分支都要跑一遍完整校验。

tagged()(compiler.ts:247-270)找的是另一种形状:所有分支都是对象, 且每个分支在同一个键上有一个互不相同的 const。找到之后,按这个键的 值直接选分支:

ts
// schema/src/compiler.ts:260-268(节选)for (const key of Object.keys(first)) {  const tags = resolved.map((s) => tagOf(s, key));  if (tags.some((t) => t === undefined) || new Set(tags).size !== tags.length)    continue;  return taggedCheck(key, tags, branches.map((s) => this.check(s, base)));}

tagOf(s, key) 从分支里取出 properties[key] 的 const;new Set(tags).size !== tags.length 保证标签互不相同(否则选不出来)。两个条件都满足才用 标签分派,否则退回"每个都试"。

省的不只是一次比较:每个分支里可能还嵌着更多联合,朴素实现是指数的。


四、失败时才解释

check 的返回值只有一个 bit。要知道"哪里错了、错在哪个关键字", 需要第二个解释器。

ts
// schema/src/explain.ts:1-2// Errors of a failed value: a walk over the schema that reports each failing// keyword at the value it failed on. It runs only for values that failed the// check, using the compiler's checks for subschemas.

同一个 schema,两套执行策略:热路径是编译出来的闭包(快、只给 boolean),冷路径是重新遍历 schema(慢、给结构化错误)。冷路径里 遇到子 schema 时仍然调 this.c.check(node, base)(v)——复用了已经编译好 的闭包,所以"遍历"只在必要的层级发生。

错误长这样(types.ts:38-43):

ts
export interface ValidationError {  readonly path: string;    // JSON Pointer, "" for the value itself  readonly keyword: string; // the failing keyword  readonly message: string;}

path 是 JSON Pointer(/edits/0/oldText),因为那是 RFC 6901 规定的 定位方式,任何语言都能解析。但模型看不懂 JSON Pointer,所以 ai/src/utils/validation.ts:21-28 转了一层:

ts
function formatValidationPath(pointer: string): string {  if (pointer === "") return "root";  return pointer    .slice(1)    .split("/")    .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"))    .join(".");}

/edits/0/oldText → edits.0.oldText。~1 → /、~0 → ~ 是 RFC 6901 规定的转义(因为 / 和 ~ 在 pointer 里有特殊含义)。这两行不写, 一个键名里带斜杠的工具就永远报错报不准。

最终送进对话的是这段(validation.ts:64-68):

ts
const errors = result.errors  .map((e) => `  - ${formatValidationPath(e.path)}: ${e.message}`)  .join("\n");const errorMessage =  `Validation failed for tool "${toolCall.name}":\n${errors}\n\n`  + `Received arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`;

三件事值得抄:带上了收到的参数(模型能自己看出"3" vs 3)、 一条错误一行、后缀是 Received arguments 而不是 You sent—— 模型不需要被指责,它需要看到自己发了什么。

4.1 memo:一个必要但不显然的缓存

explain.ts:25-29 的注释是本包最长的一段:

ts
/** * The errors of `$ref` targets for object values, within one errors() call: * a recursive union explains each branch to pick the one to blame, and every * branch would explain the same children again, exponentially in the depth. */private memo:  Map<object, Map<object, { path: string; errors: ValidationError[] }>>;

要报错就得说清"哪个分支应该被责怪"。联合类型的做法是把每个分支都解释 一遍,然后挑错误的那个。如果分支自身递归(树的节点里有节点),同一个 子值会被解释 N 次——指数级。

memo 的键是 (schema 节点, 值对象):同一个节点解释同一个值,只做一次。 errors() 结束时把它清掉(finally { this.memo = undefined; }), 所以它只活在一次调用里,不占常驻内存。

同样的模式在 coerce.ts:39-43 又出现了一次,键也一样。两个解释器各自 踩过同一个坑。


五、类型:Static<S> 是怎么算出来的

前面四节讲的是运行时。同一个 schema 还要回答一个编译期问题: readSchema 的 Static 到底是什么类型。

答案是一层纯类型层面的印记(builders.ts:7-11)。先看结论表,再往下读实现:

输入 S 长什么样 输出 为什么
带 TypeBox 的 ~kind / ~unsafe TypeBoxStatic<S> 别人的 schema 交给别人算
带本库的 STATIC 标注 那个标注 T 自己的 builder,标注就是答案
两者都没有 unknown 手写字面量没有类型可读

一句话记法:外层判哨兵、中层取标注、内层是逃生口。

ts
declare const STATIC: unique symbol;export type Schema<T = unknown> =  { readonly [keyword: string]: unknown } & { readonly [STATIC]?: T };

declare const 表示"这个值只在类型世界里存在"。Schema<T> 是一个交叉 类型:左边是"任意关键字的对象"(所以 obj() 的返回值真的能 JSON.stringify),右边是一个带可选属性的 brand。

STATIC 是 unique symbol,模块外无法构造同名属性。所以只有 str() / num() / obj() 这些 builder 的返回值带得上这个 brand, 手写的对象字面量带不上。

读取 brand 的类型函数(builders.ts:19-25):

ts
export type Static<S> = S extends  { readonly "~kind": unknown } | { readonly "~unsafe": unknown }  ? TypeBoxStatic<S>  : S extends { readonly [STATIC]?: infer T }    ? unknown extends T ? unknown : T    : unknown;

三个分支,顺序有意义:

  1. 先认 TypeBox。'~kind' / '~unsafe' 是 TypeBox 的 brand 名。 为什么必须放在最前面,builders.ts:13-14 的注释解释了:

    TypeBox is tested first and in its own branch: a builder brand's fallback through TypeBoxStatic would leave Static<S> of a generic S (constrained to builder schemas) unresolvable to its constraint's types.

    大意:如果放在后面,泛型 S extends Schema 里的 S 走错分支就会变成 unknown,工具参数全部丢失类型。

  2. 再认自己的 brand。unknown extends T ? unknown : T 是为了处理 "brand 存在但 T 是 unknown"的情况——不能把 unknown 当作真实类型 往上传播,否则 obj({ x: unknown() }) 会得到一个 unknown 类型的对象, 而不是 { x: unknown }。

  3. 都不是就 unknown。手写的 JSON Schema 字面量没有类型信息可读。

obj() 那一步(builders.ts:165-173):

ts
export type StaticObject<P extends Properties> = Simplify<  { -readonly [K in keyof P as P[K] extends Optional ? never : K]:      Static<P[K]> } & {    -readonly [K in keyof P as P[K] extends Optional ? K : never]?:      P[K] extends Optional<infer S> ? Static<S> : never;  }>;

as 子句做键重映射:把 P 的键分成两组,Optional 的进第二组并加 ?,其余进第一组。-readonly 是因为 builder 的返回值用了 readonly (brand 需要),但用户拿到的值是可写的。

Simplify<T> = { [K in keyof T]: T[K] } & {} 是最后一步:把交叉类型 拍平成单个对象类型。不拍平的话,IDE 悬停显示的是 {...} & {...} & {...},用户很难读。

5.1 代价:unknown 是一个诚实但难用的答案

typebox-static.ts:1-3 的注释把范围划得很清楚:

Only the common kinds are mapped; every other kind (Enum, Tuple, Intersect, Cyclic, Ref, ...) is unknown.

'~kind' 是 "Enum" 时,Static<S> 就是 unknown。于是 input.foo 报错 "Object is of type 'unknown'",开发者只能自己断言。

这是故意的取舍:宁可让类型断在自己手里,也不要让 Static 猜错而 在运行时炸。要在类型层面完整复刻 TypeBox 的 Static,就必须 import TypeBox 的整个类型系统——那会把 400 KB 的包拉进每个用工具的地方。


六、引用与不可信输入

resolver.ts 只干一件事:把 $ref 字符串解析成一个 schema 节点 + 一个 base URI。但有三个决定值得单独说。

一、base URI 用一个保证解析不出来的域(resolver.ts:12-13):

ts
/** The base URI of a root schema without `$id`; relative references resolve *  against it. */export const DEFAULT_BASE = "https://json-schema.invalid/root.json";

.invalid 是 RFC 2606 保留的顶级域,永远不会被注册。用一个真实的 域名的风险是:$ref: "foo.json" 这种相对引用万一被真的发出去一次请求, 就是一个 SSRF。用 .invalid 让"意外联网"在 DNS 层失败。

二、索引是懒的(resolver.ts:15-18):

The schema is indexed on the first reference, so a schema without references is never walked for identifiers.

$id 可以出现在 schema 树的任意深度,改变该子树的 base URI。要正确处理 就得遍历整棵树索引所有 $id / $anchor。但绝大多数工具 schema 一个 $ref 都没有——所以 ensureIndexed() 只在第一次 resolve() 时跑。 没有引用的 schema,编译期一次树遍历都不做。

三、$ref 指不到东西时,有两种脾气(resolver.ts:72-81):

ts
resolve(ref: string, base: string): Resolved {  this.ensureIndexed();  if (!this.rejectUnresolved) return this.find(ref, base);  try {    return this.find(ref, base);  } catch {    this.unresolved.add(resolveUri(ref, base));    return { node: false, base };  }}

默认是 "throw":编译期直接抛,因为写 schema 的人应该发现问题。但在 "reject" 模式下,解析不到的 $ref 被编译成 false——只有落在这个 位置的值会失败,其他地方照常校验。

为什么需要第二种?ai/src/utils/validation.ts:13-15 的注释:

ts
// A $ref that names nothing (a dangling definition in an MCP server's schema)// rejects only values at its place, instead of making every call of the tool// fail.const validator = compile(schema, {  formats,  coerce: true,  unresolvedRefs: "reject",});

MCP server 送来的工具 schema 是外部数据。它可能引用了自己没送的 definitions,也可能只是拼错了。用 "throw",整个工具的每一次调用 都在编译期炸掉;用 "reject",只有用到了那个字段的调用会失败,而且 错误信息指向准确的路径。

durable/src/harness/tool.ts:790 用的是同一个选项,守的是另一头: 工具的 structuredOutput。

6.1 两个 draft 的差异藏在两行里

CompileOptions.draft 只接受 "2020-12"(默认)和 "7"。差异散在 各处,但有两处最容易写错:

ts
// schema/src/resolver.ts:53(draft 7 里 $id 是惰性的)if (  this.draft === "7" &&  (typeof node.$ref === "string" || id.startsWith("#"))) {  return base;}

draft 7 规定:一个同时有 $ref 和 $id 的节点,$id 不生效 (因为 $ref 会整个替换掉这个节点)。2020-12 改成了 $ref 与兄弟 关键字并存,$id 也就生效了。不写这一行,draft 7 的 schema 会解析到 错误的 base。

另一处是数组(compiler.ts:360-366):draft 7 用 items 数组 + additionalItems,2020-12 用 prefixItems + items。两个都要支持, 因为在同一个进程里可能同时校验老配置和新工具。


七、coerce:模型的三个坏习惯

模型发回来的工具参数经常是"差一点"的:

  • 该传数字的地方传了 "42"
  • 该传数组的地方传了单个值
  • 可选字段不省略,而是传 null

这三种都在 schema 之外:{ type: "number" } 对 "42" 就是非法。严格 拒绝的结果是模型反复重试同一个错误,因为它不理解自己错在哪。

所以 coercing validator 多一步(coerce.ts:50-55):

ts
coerce(value: unknown): unknown {  const base = this.c.r.rootBase;  const withoutNulls = this.dropOptionalNulls(value, this.schema, base);  return this.coerceTypes(this.convertOnly(withoutNulls), this.schema, base);}

三遍,顺序不能换(coerce.ts:5-13 的注释):

遍 做什么 规则从哪来
1 可选属性上的 null 直接删掉,当作没传 自有规则
2 结构驱动的转换:"3.5" → 3、单值 → 单元素数组、联合取第一个能转的分支 移植 TypeBox 1.3.27 的 Value.Convert(MIT)
3 按 type 做基本类型转换,含类型数组 Ajv 的 coerceTypes

第一遍必须在最前面。如果先做第 2 遍,{ limit: null } 里的 null 可能被转成 0——那"没传"就变成了"传了 0"。

第 2、3 遍分开也有理由。第 2 遍是看结构的:它知道 $ref 指向哪、 anyOf 有几个分支、数组的 items 是什么。第 3 遍是只看 type 的 兜底,处理第 2 遍管不到的形状,比如 type: ["integer", "null"] 这种 类型数组,或者 "" → null。

7.1 两个反无限循环的护栏

coerce 比 check 危险:check 只读,coerce 要构造新值,而构造会递归。

护栏一:重入栈(coerce.ts:29-36 的注释 + :68-75):

ts
private reenter(node: object, base: string, value: unknown): unknown {  const entered = this.entered;  for (let i = 0; i < entered.length; i += 2) {    if (entered[i] === node && Object.is(entered[i + 1], value)) {      this.cuts++;      return value;    }  }

栈里存的是 (schema 节点, 值) 对。同一个节点拿着同一个值二次进入,说明 递归了——原样返回。

注释说只有两个入口会 push:$ref 和"把单值包成数组"。递归的 schema 遇到一个所有分支都不接受的值,会沿着 $ref 无限转下去。第三遍的类型 转换把 5 包成 [5],[5] 又匹配到同一个 schema 的数组分支,再包——只有 这个栈能停住它。

护栏二:memo(:39-43),和 §4.1 的 Explainer.memo 一样:递归 联合的每个分支都转换同一批子值,不记忆就是指数级。

但这里多了个细节(:37-38):

ts
/** How often a re-entry was cut short in this coerce() call; *  results computed across one are not memoized. */private cuts = 0;

经过一次"截断"算出来的结果不能进 memo。因为截断意味着"这个子值 我没真正处理,是原样返回的"——把它当正确答案缓存起来,别的分支拿到 的就是错误的结果。reenter() 在写入前比对 cuts 计数(:78-86), 不一致就跳过缓存。

这一个细节把"加缓存"从 5 行变成了 15 行。缓存和近似结果放在一起, 就是 bug。

7.2 一个可以跑的最小验证

scripts/browser-smoke-entry.ts:10-14:

ts
const schema = obj({ prompt: str() });const args = validateToolArguments(  { name: "prompt", description: "", parameters: schema },  { type: "toolCall", id: "1", name: "prompt", arguments: { prompt: 1 } },);

传进去的是数字 1,str() 要的是字符串。args.prompt 跑完之后是 "1"。这个文件是被 scripts/check-browser-smoke.mjs 打包的浏览器入口, 所以它还顺带证明了一件事:整个校验链在浏览器里能跑——没有 eval, 没有 Node 专有模块。

7.3 出口改写,入口还原

第 1 遍(删掉可选属性上的 null)看起来像个补丁,其实它和 §八 是一对。

provider 的 strict 模式不能表达"可选":它要求 required 列出所有 属性名。所以"可选"只能退化成"可空"——把属性类型改成 anyOf: [原类型, { type: "null" }],并把它加进 required。

模型于是会真的传 limit: null 来表达"我不给这个字段"。

所以:

  • 出口(constrained-sampling.ts)把 optional 改写成 nullable 进请求。
  • 入口(coerce.ts)把 nullable 上的 null 删掉还原成 optional 出 校验,交给工具实现。

两处改写在不同的包里、不同的层,但必须是同一对。少任何一半, "可选参数"在 strict 模式下要么传不上去,要么传上去之后让工具收到一个 假的 null。


八、第五种解释:provider 的 strict 方言

前四种解释都发生在本进程内。第五种出了进程:schema 被打包进请求体, 交给 provider 侧的 structured outputs 编译器,变成一份语法(grammar), 然后在解码时逐 token 剪枝。

这个编译器的能力比 JSON Schema 小得多。它没有回溯,没有补集,没有跨文档 引用——它只能在"已经生成的前缀"上判断"下一个 token 可不可能合法"。

8.1 一份黑名单,十六个关键字

ts
// ai/src/api/constrained-sampling.ts:15-32const UNSUPPORTED_STRICT_SCHEMA_KEYS = [  "$ref", "$defs", "definitions", "allOf", "oneOf",  "patternProperties", "dependentSchemas", "dependencies",  "unevaluatedProperties", "propertyNames", "contains",  "prefixItems", "not", "if", "then", "else",] as const;

按"为什么编译不了"分一下组:

组 关键字 编译器的难处
引用 $ref $defs definitions 请求里必须是一棵有限树,不能有指向别处的边
组合 allOf oneOf not 求交、求补、要求"恰好一个",都需要把分支全部展开
对象 patternProperties dependentSchemas dependencies unevaluatedProperties propertyNames 键名本身要参与约束,而生成键名时约束还不完整
数组 contains prefixItems contains 是存在量化;prefixItems 与 items 要合成两段式语法
条件 if then else 要与已生成的内容做匹配

除了这十六个,还有一批是形状被拒(makeJsonSchemaNodeStrict 里逐个 throw):

ts
// ai/src/api/constrained-sampling.ts:56-58, 85-90, 97-99if (!isJsonSchemaObject(schema)) {  throw new UnsupportedStrictJsonSchemaError(    "boolean schemas are unsupported");}if (Array.isArray(schema.items)) {  // 元组  throw new UnsupportedStrictJsonSchemaError("tuple schemas are unsupported");}if (  schema.additionalProperties !== undefined &&  schema.additionalProperties !== false) {  throw new UnsupportedStrictJsonSchemaError(    "schema-valued or true additionalProperties is unsupported");}

第一行值得停一下:boolean schemas are unsupported。而 §一 引过 JsonSchema = boolean | object(schema/src/types.ts:7)——pi-schema 自己把 true 和 false 当作合法的 JSON Schema。同一份标准,两个子集: 自己实现的那一侧要全,发给 provider 的那一侧要小。

anyOf 还有一条额外限制(:38-47):分支里只要出现对象或数组, 整棵树就被拒("object and array unions are unsupported")。字符串的 联合类型可以,{ type: "object" } 的联合不行。

8.2 全部改写只有三行

通过黑名单之后,真正改动 schema 的代码就这三行:

ts
// ai/src/api/constrained-sampling.ts:116-123for (const [key, property] of Object.entries(properties)) {  makeJsonSchemaNodeStrict(property, isUnsupportedKeyword);  if (!required.has(key) && !schemaAllowsNull(property)) {    properties[key] = { anyOf: [property, { type: "null" }] };  }}schema.required = propertyNames;schema.additionalProperties = false;

required = 所有属性名、additionalProperties = false、可选属性包一层 null。三条合起来的意思是:strict 模式下,模型必须生成一个完整对象, 每个字段都有值,不想要的字段给 null。

为什么不能保留 optional:strict 要求 required 覆盖全部属性名(这是 provider 编译器的硬要求,不是风格问题)。所以"这次不给"只能退化成 "这次给 null"。§7.3 已经讲过这一对——这里是出口那一半。

schemaAllowsNull(:49-54)认五种"已经可空"的写法:type: "null"、 type: [..., "null"]、const: null、enum 含 null、以及 anyOf 里存在可空分支。所以这层包装是幂等的:本来就可空的属性不会被包成 anyOf: [{ anyOf: [...] }, { type: "null" }]。

8.3 为什么必须先 structuredClone

ts
// ai/src/api/constrained-sampling.ts:127-140export function makeStrictJsonSchema(  schema: Tool["parameters"],  isUnsupportedKeyword?: UnsupportedStrictSchemaKeywordCheck,): Record<string, unknown> {  const cloned: unknown = structuredClone(schema);  if (!isJsonSchemaObject(cloned)) {    throw new UnsupportedStrictJsonSchemaError(      "root schema must have type object");  }  makeJsonSchemaNodeStrict(cloned, isUnsupportedKeyword);  ...}

三个理由,缺一个都会出事:

  1. 工具定义是共享的。 同一个 Tool 对象在一次会话里被反复发送, 还在重试时被重新读取。就地改写意味着第一个开启了 strict 的请求会把 后面所有请求的 schema 都改掉。
  2. 改写不可逆。 optional 变成 anyOf[..., null] 之后,没人能区分 "原本就允许 null"和"被 strict 改写出来的 null"——§7.3 里 coerce 的第 1 遍前提正是"这个 null 是我们加的",一旦原件被污染,那个前提 就变成猜测。
  3. 降级要能找到原件。 getJsonSchemaToolParameters(:163-165) 是二选一:strict === true 才克隆改写,否则原样返回同一个对象引用。

8.4 provider 的上限被写成了常量

ts
// ai/src/api/constrained-sampling.ts:148-156/** Claude rejects (on the Anthropic API and on Bedrock) a request whose *  strict tools exceed its limits with one of these messages. *  Observed limits: 20 strict tools, and 16 optional or union-typed *  parameters across all strict tools. */const STRICT_TOOL_LIMIT_ERROR_MESSAGES = [  "The compiled grammar is too large",  "Too many strict tools (",  "Schemas contains too many parameters with union types (",];

三个都不是完整的错误消息,只是片段,匹配用 includes(:159-161)。 因为尾巴上带着具体数字和参数名,是变的;能稳定的只有这几段。

注意第三条的语法错误:Schemas contains。原文如此,改对了就匹配不上。 注释里那句 Observed limits: 20 ... and 16 ... 是观察得来的,不是文档 写的——provider 没有公开这两个数字。

strict: "prefer"(:143-146)是配套的退路:能 strict 就 strict, 撞上这三个错误就降级重发一次。

第八节到这里就有了一个可以直接回答本章验收的结论:一份声明同时喂给 五个读者,它的可移植性等于五个子集的交集。 交集最小的那个读者决定 了工具作者能写什么。


九、遥测 schema:唯一一个不校验的类型

换到第二个包。pi-telemetry 的核心声明是一行:

ts
// telemetry/src/index.ts:175export function defineTelemetrySchema<  const T extends TelemetrySchemaDefinition,>(  schema: T,): T {  return schema;}

const T 让字面量类型不被放宽,然后原样返回。整个 465 行的入口文件, 这个函数不做任何事。

作者把这一点写在了另一个函数的注释里(:448-451):

ts
/** * Bind an explicit parent context to the combined span vocabulary of one or * more schemas. * Schema values are used only for type inference; no runtime schema * validation is performed. */

最硬的证据是参数的名字:

ts
// telemetry/src/index.ts:452-457export function createTypedSpanStarter<	const Schemas extends TelemetrySchemaTuple,>(	telemetryContext: TelemetryContext,	_schemas: Schemas & UniqueTelemetrySchemas<Schemas>,): TypedSpanStarter<Schemas> {	return bindTypedSpanStarter<Schemas>(telemetryContext);}

_schemas 下划线开头。整个函数体没有读它一个字段——bindTypedSpanStarter (:427-446)里也没有任何地方碰 startAttributes / endAttributes / events。

为什么可以不校验:信任边界不同。§1.1 第二条说过,pi-schema 面对的是 MCP server 送来的外部数据,必须防御式读取每个关键字;而遥测的 schema 和 调用它的代码在同一个仓库、同一次编译里。写错的属性名已经是编译错误了 (ExactTelemetryAttributes,:243-244,多余的键被映射成 never)。 运行时再查一遍,只是把编译期能发现的错误推迟到生产环境。

9.1 同一份声明,两条命运

schema 部分完全不落地,metrics 部分落地:

ts
// telemetry/src/metrics.ts:129-145export function createTypedMetrics<const Schemas extends MetricSchemas>(	metrics: TelemetryMetrics,	schemas: Schemas & ...,): TypedTelemetryMetrics<Schemas> {	const definitions = new Map<string, TelemetryMetricDefinition>();	for (const schema of schemas) {		for (const [name, definition] of Object.entries(schema.metrics ?? {})) {			definitions.set(name, definition);		}	}	return {		counter: (name: string) => metrics.counter(name, definitions.get(name)),		...	};}

参数叫 schemas,没有下划线;函数体遍历它们;definitions.get(name) 被当作 InstrumentOptions 直接喂给 adapter。于是 description / unit / boundaries 在运行时真的到达了后端。

理由很实际:description 和 unit 是后端的展示元数据——Prometheus 的 HELP/TYPE、图表 y 轴的单位。adapter 拿不到就只能靠名字猜。而 span 的 description 只对人有用,写进属性纯属浪费字节(§十 会看到这条纪律执行得 多彻底)。

顺带一个类型层面的收紧:

ts
// telemetry/src/metrics.ts:43export type TelemetryMetricAttributeDefinition =	TelemetryStartAttributeDefinition & { cardinality?: "low" };

span 属性可以写 cardinality: "low" | "high"(index.ts:133),指标属性 只能写 "low"。写 "high" 是类型错误,不是文档建议。理由:一个高基数 属性当指标维度,等于给后端造一条时间序列——response.id 一旦进来了, 直方图就变成了记账流水。

指标属性的必填性也推导了(metrics.ts:93-100):只要有一个 required: true 的属性,attributes 参数就从可选变成必填。

9.2 重名是类型错误,不是运行时错误

ts
// telemetry/src/index.ts:396-400type UniqueTelemetrySchemas<Schemas extends TelemetrySchemaTuple> =	[DuplicateTelemetrySpanNames<Schemas>] extends [never]		? unknown		: { readonly "duplicate telemetry span names":			  DuplicateTelemetrySpanNames<Schemas> };

用法是 Schemas & UniqueTelemetrySchemas<Schemas>。两份 schema 有同名 span 时,第二份的类型变成 { "duplicate telemetry span names": "..." }, 与 Schemas 求交得到 never,参数不可传——错误信息就是那个属性名本身, 里面直接写着重复的是哪个 span。

这是用类型系统做 lint:没有运行时检查,没有 Set,没有启动时遍历断言。 createTypedSpanStarter 的整个 465 行里没有一个 if 是为它写的。

DuplicateTelemetrySpanNames(:384-394)是元组递归,带一个 Seen 累加器单向扫过 schemas 数组。metrics 侧是同一个模板,只换了被扫的字段 (metrics.ts:79-87)。


十、只记形状,不记内容

遥测最难的部分不是记录,是不记录。三句真实注释划出了边界:

ts
// durable/src/harness/telemetry.ts:49/** Durable's content-free span, event, and metric vocabulary. *  IDs address durable records, never content. */
ts
// ai/src/telemetry.ts:43description: "A completed content block; content is never recorded.",
ts
// ai/src/telemetry.ts:59errorWhen: "Stop reason is error: provider_error with at most 500  error-message characters. Aborted stays ok.",

10.1 一个内容块的四个数字

ts
// ai/src/telemetry.ts:42-55"pi.ai.block": {  description: "A completed content block; content is never recorded.",  attributes: {    type: { type: "string", values: ["text", "thinking", "tool_call"],            required: true },    index: { type: "number", required: true },    chars: { type: "number", description: "UTF-16 character count.",             required: true },    tool: { type: "string",            description: "Tool name, for tool-call blocks only." },  },},

一段三千 token 的思考,进日志的是 { type: "thinking", index: 1, chars: 8123 } 这样的东西。会话内容、工具参数、模型输出,一个字都没有。

chars 的实现里有一个不显然的地方:

ts
// ai/src/telemetry.ts:162-179if (event.type === "toolcall_delta") {  toolChars.set(event.contentIndex,    (toolChars.get(event.contentIndex) ?? 0) + event.delta.length);} else if (event.type === "text_end" || event.type === "thinking_end") {  span.addEvent("pi.ai.block", {    type: event.type === "text_end" ? "text" : "thinking",    index: event.contentIndex, chars: event.content.length });} else if (event.type === "toolcall_end") {  const chars = toolChars.get(event.contentIndex) ?? 0;  toolChars.delete(event.contentIndex);  span.addEvent("pi.ai.block", {    type: "tool_call", index: event.contentIndex, chars,    tool: event.toolCall.name });}

文本和思考的结束事件带着全文,直接量长度。工具调用的结束事件带的是解析 好的 call,没有原文——只能一边收 toolcall_delta 一边累加。而那个 delete 不是清理卫生,是正确性:同一个 contentIndex 在重试时会复用, 不删就会把两次的长度加在一起。

10.2 高基数进 span,低基数才进指标

同一件事在两个粒度上的两个名字:

事实 span 属性 metric 属性
哪次请求 response.id(high,ai/telemetry.ts:38) 不记
哪个任务 task.id(high,durable/.../telemetry.ts:81) task(注册名,:128)
哪个工具调用 tool.call_id(high,:95) tool.name

理由很物理:span 是一行记录,metric 是一个聚合桶。桶的键只有几十种 取值才叫桶,几万种取值叫索引。§9.1 那条类型收紧只是把这条规律写成了 编译期规则。

10.3 500 字符是一条硬边界

ts
// ai/src/telemetry.ts:192-196if (message.stopReason === "error") {  span.setStatus({    status: "error",    error: { name: "provider_error",             message: ownedSlice(message.errorMessage ?? "", 0, 500) },  });}

用 ownedSlice 而不是 slice:结果不引用原串的底层缓冲区,VM 不会为了 这 500 个字符保住一份可能几 MB 的错误响应(V8 的 sliced string 持有父串 引用)。

500 这个数字在 durable 侧重复了一遍(:113:"a diagnostic capped at 500 characters")。为什么是这么小的数:错误信息进的是错误聚合器,聚合器的 价值来自"同一类错误合成一条"。带上完整栈和上游响应体的消息,每条都是 新的一条,聚合器就退化成日志。

同一行注释里还有半句更含蓄的:Aborted stays ok.。用户按 Ctrl-C 不是 故障。把它记成 error,错误率曲线就变成了用户的打字速度。

10.4 一个声明了但从不读取的字段

TelemetryAttributeMetadata 有 sensitive?: boolean(index.ts:130-134)。 全仓搜一遍:声明一处,读取零处。

这不是遗漏,是取舍。sensitive 是给写 schema 的人留的记号("这个字段 将来可能要脱敏"),真正的保护不靠它,靠词表本身里没有内容——§10.1 的 chars 就是那个策略的产物。一个只能记长度的字段,没有办法泄露它 量过的那段文字。

可以批评它是死代码。但它诚实地留在原地:字段的语义("这个属性敏感") 比它的执行("运行时拦一下")更容易先定下来,而执行需要一个真正会脱敏 的 adapter 才谈得上。


十一、契约与实现分离

两个包都讲完了,最后看接缝:一个契约,两个实现。

TelemetryContext 只有三样东西(index.ts:98-103):metrics?、 propagation?、startSpan。TelemetrySpan 继承它,再加四个写方法 (:105-110)。

span 就是一个 context。这不是洁癖,是让子 span 能直接在父 span 上开: memory.ts 的 startSpan 里,parent 就是 { context, localId, span } (:196-205)。

两个可选能力而不是一个胖接口:metrics 和 propagation 都是 ?。一个 只记 span 的 adapter 不该被迫实现指标;一个只做 trace 透传的网关不该被迫 实现采样。noop.ts 把它们各自做成冻结单例(:8-23)。

NOOP_TELEMETRY_CONTEXT 的类型是 TelemetrySpan(:37),不是 TelemetryContext。因为 span 是 context 的超集——根 context 也要能开 span,一个对象同时扮演两个角色,省掉一层包装。

11.1 两个实现,两种时间观

InMemoryTelemetryContext SqliteTelemetry
何时成形 开始时就 push 一条可变记录,结束时改它 结束时才变成一行
同步/异步 全同步,getSpans() 立刻能读 记录路径不碰 SQL,每秒 flush
队列上限 无 10,000 条,超了计数丢弃,不抛错
失败怎么办 不会失败 写失败即永久停止记录,错误留给 flush
保留期 进程内 7 天,在同一事务里 DELETE
对外暴露 所有 span,带 settled 标志 只有落盘的行

第二行最能说明"契约"是什么。chord/src/telemetry-sqlite/index.ts:335-337:

ts
/** Portable, buffered SQLite recorder. Recording never performs SQL; * flush runs every second. * Only settled spans are stored. Metrics aggregate count/sum/min/max per * ten-second interval. * A write failure permanently stops recording and is reported by flush and * close. */

"记录不做 SQL"。span 可能在模型流式响应的热路径上结束,一次同步 INSERT 就能把首 token 延迟拉长几毫秒。记录只是往数组里 push 十元组 (:205-216),IO 留给每秒一次的 drain。

同一段注释里的另外三条,都是刻意选择:

  • 满了就丢,计数但不抛错(:203、:241-244)。两个计数器 droppedSpans / droppedMeasurements。遥测不能因为缓冲区满了就让 agent 停下来——观测者不改变被观测系统的行为。
  • 写失败即永久停止(:319-326):failed = this.stopped = true, 清空队列,clearInterval,不重试。一块坏掉的磁盘不该让之后每个 span 都付一次失败重试的代价。
  • 只有已结算的 span 会落盘。这条让两个实现的行为能对齐:内存实现 开始时就建档,但 getSpans() 的读者看到的字段与 SQLite 落盘的行一致。

两个实现共享的两条规则,值得单独记:

  1. 结算之后不可改。 内存实现的四个写方法都以 if (recordedSpan.settled) return; 开头(memory.ts:207-227); SQLite 用 record() 包一层(:160-162)。span 结束后的 setStatus 是静默空操作而不是抛错——清理代码里顺手补一个状态是常见写法。
  2. identity 存在 WeakMap 里。 contextCarriers(memory.ts:98)/ identities(index.ts:51),注释:Identity survives settlement without exposing backend IDs on the generic context contract.

第二条是 inject() 在 span 结束后仍然能工作的原因:context 对象还活着, 后端 ID 就查得到。代价是多一张 WeakMap;收益是换后端不用改调用方。

11.2 一条会静默丢数据的路径

ts
// telemetry/src/memory.ts:188if (parent?.span?.settled) return startInertSpan(state, options, callback);

在一个已经结束的 span 里开子 span,子 span 什么都不记。SQLite 侧对应 的是 this.stopped(:144)——同一个 inert 兜底,两个触发条件。

后果:void someAsyncWork() 里开的 span,如果父 span 先结束(比如父 span 只包了"发出请求"而没包"等结果"),整棵子树都不会出现在 trace 里。没有 报错,没有计数。

这是刻意取舍:父 span 在子 span 之前结束,trace 的时间轴就倒过来了(子的 startedMs 大于父的 endedMs),后端要么拒绝要么画出负宽度。宁可丢, 不要错。代价是排查时看不到东西,而且不知道为什么看不到。§十四 有 一个能复现这个行为的实验。

11.3 conformance:把"两个实现"变成"同一份用例"

ts
// telemetry/src/testing/conformance.ts:43-46/** Creates runner-independent cases for the callback telemetry adapter * contract. */export function createTelemetryAdapterConformance(	factory: TelemetryAdapterFixtureFactory,): readonly TelemetryAdapterConformanceCase[] {

返回的是用例数组,不是 describe / it 调用(testing/types.ts:16-21):

ts
/** A runner-independent conformance case that can be registered with any * test framework. */export interface TelemetryAdapterConformanceCase {	readonly group: string;	readonly name: string;	run(): Promise<void>;}

一个包不 import 任何测试框架,就能给所有 adapter 提供同一份检查表。 fixture 是 AsyncDisposable(types.ts:5),每个用例跑完自动收尾 (conformance.ts:21-25:await using fixture = await factory();)。

跑它的是另一个包:

ts
// chord/test/telemetry-sqlite.test.ts:92-95describe("SQLite telemetry span and propagation conformance", () => {  for (const test of createTelemetryAdapterConformance(fixture)    .filter((test) => test.group !== "metrics"))    it(`${test.group}: ${test.name}`, test.run);});

pi-chord 通过公开的 pi-telemetry/testing 子路径拿到用例,把 SQLite 适配器接进去跑。group 是一等字段,所以能按能力过滤——SQLite 适配器的 fixture 不提供 metrics 快照,其余全过。

同一个文件里还有一条直接验证 §11.1 第二行的测试(:98-110):

ts
const transaction = vi.spyOn(f.db, "transaction");const pending = f.telemetry.startSpan({ name: "active" }, (span) => {  span.addEvent("begin");  f.telemetry.metrics.counter("calls").add(1);  return gate.promise;});expect(transaction).not.toHaveBeenCalled();

"记录不做 SQL"这句话被写成了一个断言。

这是"契约与实现分离"的最后一块:契约不只是类型,还有行为。类型保证 签名对,conformance 保证语义对,而两者都不需要 adapter 知道对方的存在。


十二、两条完整链路

前面十一节都是局部。这一节把两条链拼起来,一条走值,一条走日志。

12.1 值:从声明到 handler

text
obj({ path: str(), offset: opt(num()) }, { open: true })  |  |  产出是一个普通的 JS 对象,可以 JSON.stringify:  |  { type: "object", properties: { path, offset }, required: ["path"] }  |  (open: true,所以没有 additionalProperties: false)  |  +-(1)-> 请求体 ------------------------------> provider  |         |  |         +-(5)-> strict 方言:required 补齐全部键  |                  optional 包成 anyOf [原类型, null]  |  +-(2)-> Static<S>  =  { path: string; offset?: number }  |  +-(3)-> compile()  ->  check(value): boolean  |  +-(4)-> errors(v)  ->  Explainer  ->  ValidationError[]

五个读者,五种解释。第(2)个在编译期,其余四个在运行时或进程外。

值的回程:

text
model  |  toolCall.arguments = { prompt: 1 }  vvalidateToolArguments            ai/src/utils/validation.ts:54-69  |  argumentsError 非空就直接抛(JSON 都没解析成功)  |  WeakMap<schema, CoercingValidator>      每个 schema 只编译一次  |  structuredClone(arguments)              工具改参数不改 transcript  vCoercingValidator.parse                          schema/src/validator.ts:73-76  |  +--> coerce(value)                              先掰,再判  |      1 dropOptionalNulls   删掉可选属性上的 null  |      2 convertOnly         结构驱动(TypeBox 的 Value.Convert)  |      3 coerceTypes         按 type 兜底(Ajv 的 coerceTypes)  |      每条路径 copy-on-write,没变就返回同一个引用  |  +--> check(coerced)         |         +-- true  ->  { ok: true, value }   -> handler 拿到 "1"         |         +-- false ->  { ok: false, errors } -> Explainer(memo 防指数)                        |                     [{ path: "/prompt", keyword: "type", ... }]                        |                     formatValidationPath("/prompt") -> "prompt"                        |                     "Validation failed for tool \"prompt\":\n  - prompt: ..."

最后那条错误消息回到对话里,模型看到的是自己原本发的参数 (:66 里 JSON.stringify(toolCall.arguments),不是 coerce 之后的值)。 这是对的:要让它知道错在哪,而不是告诉它"我把它改成了什么"。

keyword 字段在拼消息时被丢掉了(:64 只取 path 和 message)—— message 已经是人话,keyword 是给程序读的。

12.2 旁路:从调用到日志

text
业务代码                                adapter--------                                -------start("pi.ai.request", {provider, model, api})  |  +-- 同步拿到 span 句柄 -------------> 记录开始时间与属性  |  +-- onEvent(第一个 chunk) ----------> addEvent("pi.ai.first_chunk")  |                                     histogram.record(首块耗时)  +-- onEvent(text_end) --------------> addEvent("pi.ai.block",  |                                       { type, index, chars })  +-- onEvent(toolcall_end) ----------> addEvent("pi.ai.block",  |                                       { ..., tool: 工具名 })  +-- onResult(message) ---------------> setAttributes({ usage.*,  |                                       cost.total, response.id })  |                                     counter.add("pi.ai.tokens", ...)  |                                     histogram.record(duration, ...)  +-- finish() ------------------------> span 结算(settled = true)                                            |                    InMemoryTelemetryContext     SqliteTelemetry                        立刻可读                  每秒 flush                                            |                      getSpans() / findTraces() / findMetrics()                                            |                                renderTrace(spans) -> 文本树

两条链在形状上是同一个套路:热路径只记形状,读的时候才解释。 check 是布尔,errors 才构造对象;addEvent 只是往数组里 push, renderTrace 才把树画出来。


十三、工程暗坑

1. strict 改写不可逆,coerce 第 1 遍只能靠猜。

{ limit: number | null } 如果作者的意思是"显式表示不限制",那模型传 limit: null 就是有意义的。但 dropOptionalNulls 一律删——它无法区分 "用户自己写的可空"和"§8.2 那条 anyOf 改写出来的可空"。不要把 null 当作业务值,它在 strict 模式下已被系统征用为"没给"。

2. unresolvedRefs: "reject" 把笔误变成了静默拒绝。

$ref: "#/$defs/paramters" 少一个字母,在 "reject" 模式下编译成 false 节点(resolver.ts:72-81),编译期一声不响。只有那个位置的调用会失败, 其他字段照常工作——生产上看起来像"某个参数永远校验不过"。默认的 "throw" 才会当场报错;ai 和 durable 都选了 "reject",因为它们守的是外部 schema。 自己写 schema 时用默认值。

3. 属性名撞上 Object.prototype 要单独处理。

for (const k in o) 会走到原型链上的可枚举属性。一个名为 toString 或 constructor 的工具参数,for...in 会在没有这个键的值上也走到它。所以 编译期给这类键打 INHERITED 标记(compiler.ts:344),校验时要求 Object.hasOwn(o, k)(checks.ts:264)。

4. chars 数的是 UTF-16 码元,不是字符。

event.content.length 是 JS 字符串长度。一个 emoji 记 2,一个由四个码点 组成的字形族记 8。description 老老实实写了 "UTF-16 character count"—— 如果你要用这个数算 token 或算钱,先换算。

5. 父 span 结算后开的子 span 会静默消失。

memory.ts:188 的 if (parent?.span?.settled) return startInertSpan(...)。 后果见 §11.2:void 掉的异步任务,整棵子树都不进 trace,没有报错, 也没有计数。droppedSpans 只统计队列溢出,不统计这一种。

6. span 结算后的写入是静默空操作。

四个写方法都以 if (recordedSpan.settled) return; 开头(memory.ts:207-227), SQLite 侧用 record() 包一层(:160-162)。所以 finally 里补一句 span.setStatus({ status: "error" })——如果 span 已经结算,这句话什么都不做。 看起来"清理代码写了就生效",实际可能一个字都没记上。

7. SQLite 里 true 和 1 不是一回事,JSON1 会混。

json_extract(attributes, '$.flag') 对 true 返回 1。所以按属性值过滤 不能只比数值,得连类型一起比——store.ts:48-60 用 json_each 拿 entry.type:

sql
EXISTS (SELECT 1 FROM json_each(?) entry        WHERE entry.key = ?          AND entry.type = 'true'      -- 布尔走类型          AND entry.value = 1)         -- 数字走值

注释原话:JSON equality must distinguish boolean true from numeric 1.

8. 指标序列的身份取决于属性键的顺序。

index.ts:230-237 先把属性键 sort() 再 JSON.stringify,用这个字符串 当 series_key。不排序的话 {a,b} 和 {b,a} 是两条序列, ON CONFLICT(interval_ms, series_key) 永远不会合并它们。自己写 adapter 时这一步不能省。

9. contentEncoding / contentMediaType 在 draft 7 是断言,在 2020-12 是注解。

KNOWN_FAILURES 里四条 it.fails 就是因为这个(conformance.test.ts:17-21): 一份按 draft 7 写的 schema 会拒绝非法 base64,用 2020-12 编译就不拒绝了, 而且没有任何提示。跨 draft 的 $ref 同理——引用的文档按当前编译的 draft 解释,不是它自己的 draft(另外两条 it.fails)。


十四、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。下面几条未实跑——写作环境里没装 node_modules,判据是从测试源码读出来的;能跑的前提与命令已给全。

两个包都用 vitest(package.json 的 test 是 vitest --run)。下面 每条命令都要先装依赖;写作环境里没有 node_modules,所以判据是从测试 源码里读出来的,不是我跑出来的输出。

bash
cd packages/schema && npm install && npm test
powershell
cd packages/schema; npm install; npm test

实验 1:官方套件,4,213 条用例

bash
cd packages/schemanpm test -- test/conformance.test.ts

判据:test/fixtures/json-schema-test-suite 下有 144 个文件 / 4,213 条 用例(2020-12 有 80 个文件,draft 7 有 64 个)。每条用例跑两遍:

ts
it(`${test.description} (errors agree with check)`, () => {  const validator = compile(group.schema, options);  const errors = validator.errors(test.data);  expect(errors.length === 0).toBe(validator.check(test.data));});

这条断言是本章最重要的自检:热路径和冷路径必须同谋。errors 与 check 走的是两套完全不同的实现(闭包 vs 遍历 schema),一条不一致 就是 bug。

九条已知失败用 it.fails 登记(conformance.test.ts:9-21):

ts
const known = KNOWN_FAILURES.has(  `${file.name} > ${group.description} > ${test.description}`);(known ? it.fails : it)(test.description, () => { ... });

it.fails 的语义是"这条必须失败"。哪天修好了,它会变成红灯,逼你把 名字从名单里删掉。这比 skip 强得多:skip 是永久的遗忘, it.fails 是一次性的欠条。

实验 2:三遍 coerce 各自独立

bash
cd packages/schemanpm test -- test/coerce.test.ts

判据:describe 的层级就是 §7 那张表—— pass 1: optional nulls(:118)、 pass 2: TypeBox's conversion rules on JSON Schema(:151)、 pass 3: primitive coercion by type(:215)。 还有两节值得单独看:where the passes conflict, the conversion rules win(:258)和 recursive schemas(:280)——后者是 §7.1 那两个 护栏的用例。

实验 3:$ref 的两种脾气

bash
cd packages/schemanpm test -- test/validator.test.ts -t "unresolved references"

判据:validator.test.ts:192 那一节。默认模式下指不到的 $ref 在 compile() 时抛;unresolvedRefs: "reject" 下编译通过,只有落在那个 位置的值失败。

实验 4:同一份一致性用例,两个 adapter

bash
cd packages/telemetry && npm test -- test/conformance.test.tscd packages/chord   && npm test -- test/telemetry-sqlite.test.ts
powershell
cd packages/telemetry; npm test -- test/conformance.test.tscd ../chord; npm test -- test/telemetry-sqlite.test.ts

判据:先看内存实现全过(conformance.test.ts:17 InMemoryTelemetryContext conformance),再看 SQLite 实现跑同一份用例 (chord/test/telemetry-sqlite.test.ts:92-95),只过滤掉 metrics 组。 第二个文件里还有一条断言直接钉住 §11.1 第二行:

ts
expect(transaction).not.toHaveBeenCalled();   // 记录路径不碰 SQL

实验 5:没有 eval

bash
node scripts/check-browser-smoke.mjs

判据:它把 scripts/browser-smoke-entry.ts 打包成浏览器能跑的产物。 那个入口里 { prompt: 1 } 会被校验并转成 "1"(§7.2)。这条能过, 说明整条校验链在浏览器里可用——也就是 §1.1 第一条约束成立。


五句话

如果只记五句:

  1. 一份声明,五个读者。 不是代码复用,是语义单一来源。
  2. 不能有 eval。 同一套校验要能在浏览器、Workers、沙箱里跑。
  3. errors() 只在失败时跑。 成功路径只调一个闭包,热路与冷路必须同谋。
  4. coerce 三遍各自独立。 冲突时转换规则赢,不是后完成的赢。
  5. 防御等级跟着信任边界走。 工具 schema 当敌人看,遥测字段一行不校验。

本章小结

  1. 一份 schema 哺五个读者:编译、校验、类型、解释、遥测。
  2. 成功路径只调一个闭包,errors() 只在失败时跑。
  3. 热路径与冷路径必须同谋,靠同一份用例钉住。
  4. coerce 三遍各自独立;冲突时转换规则赢。
  5. 遥测 schema 一行不校验:防御等级跟着信任边界走。

概念回顾

术语 一句话 在哪
五个读者 编译 / 校验 / 类型 / 解释 / 遥测 §一
闭包 schema 编译成可调用函数 §二、§三
延迟解释 失败时才构造错误信息 §四
三遍 coerce 可选 null / 转换规则 / 原始类型 §七
只记形状 遥测只存形状,不存内容 §十

练习

练习 1(读):§十四 实验 1 里 errors() 与 check() 走两套实现。 如果只改其中一套,哪条用例会先红?→ 回 §2.1、§15.1。

练习 2(改):把 coerce 的 pass 顺序对调(先 primitive 再转换规则)。 预期:where the passes conflict 那节变红;回滚:调回原顺序。

常见误区

  1. 你会以为 schema 只是个类型声明;实际是 它同时哺五个读者; 证据 §一 的图。
  2. 你会以为 $ref 指不到一定编译失败;实际是 reject 模式下编译通过、 只让那个值失败;证据 §十四 实验 3。
  3. 你会以为 遥测也该走校验;实际是 一行不校验,防御跟信任边界走; 证据 §九。

读完自检

四个答案,都在开头那四问里。

自检 一句话答案 不会就去
一份声明喂给五个读者,为什么不能各写一份? 会不一致;不一致 = 模型以为合法、运行时判非法 §一
不用 ajv、不用 zod,三条硬约束是什么? 不能 eval、schema 来自不可信来源、要能读 TypeBox 但不 import §1.1
errors() 为什么只在失败路径上跑? 成功时只调一个闭包;代价是两套实现要永远一致 §2.1、§15.1
同一份 schema,遥测那边为什么一行校验都不做? 防御等级跟信任边界走,不跟类型走 §九、§15.1

十五、收束

15.1 三个可迁移的方法

一、让贵的计算只发生在失败路径上。

check 是一个普通函数,还被声明成类型谓词 value is T(validator.ts:34), 所以它可以脱离 validator 传走。errors() 第一句就是 if (this.check(value)) return [](:51),Explainer 用 ??= 懒建。一次工具调用成功了, 就一个闭包被调用;只有失败时才走第二套实现(遍历 schema、拿 memo、拼路径)。

代价是两套实现要永远保持一致。这个代价是用实验 1 那条 errors agree with check 付掉的——每条用例都跑两遍。贵的东西放到 失败路径,前提是你能写出这个不变式的自动检查。

二、防御等级跟着信任边界走,而不是跟着类型走。

同一个仓库里,pi-schema 把每个关键字都当敌人(boolean | object、 防御式读取、"reject" 兜底),pi-telemetry 的 schema 却一行校验都不做 (_schemas 参数根本没用)。差别不是洁癖程度,是输入来自哪里: 前者收的是 MCP server 送来的 JSON,后者收的是同一个仓库里写死的常量。

给内部常量写运行时校验,是把编译期错误挪到生产环境,还多付一次开销。

三、观测者不改变被观测系统的行为。

SqliteTelemetry 满了就计数丢弃(:203、:241-244),写坏了就永久 停止记录(:319-326),结算后的写入静默变空操作。三条加起来是一个 承诺:instrument 之后,程序的行为和没 instrument 一样。

代价是"看不到东西的时候不知道为什么看不到"(§11.2)。所以要有计数器 ——droppedSpans / droppedMeasurements 就是这个承诺的收据。

15.2 这章的边界

没讲的部分:

  • annotations.ts(208 行):unevaluatedProperties 要靠注解追踪判断 "哪些键已经被前面的子 schema 覆盖过"。全章只提了一次名字。
  • formats/(31 文件 / 1,682 行):21 种 format 的正则与 IDN 处理, 从 TypeBox 1.3.27 移植。本章只用到了"它是可选入口"这个事实。
  • explain.ts 的 390 行:只讲了 memo 和那两条路径。memo 的键是 (节点, 值对象) 二元组,为什么值也要进键,值得单独读。
  • coerce.ts 的逐条转换规则:coerce-typebox.test.ts 有 1,344 行, 全是移植过来的 TypeBox 用例。本章只讲了三个 pass 的分工和两个护栏。
  • constrained-sampling.ts 的后半段(:167-335):grammar 采样 (lark / regex)与流式增量拼接。这是另一条完整的链路,与 strict JSON Schema 并列。
  • memory.ts 的查询侧:findTraces 的游标分页用 JSON.stringify([startedMs, traceId]) 当 cursor(:370、:404), 时间戳相同时靠 traceId 打破平局。

15.3 最后一章

M01 的地图上,这一章是十二个包里最小的两个(51 文件 / 6,137 行,占全仓 不到 3%)。它们也是最不"功能"的两个——没有网络、没有磁盘、没有界面。 但每个别的包都从它们那里 import 了一种说法:什么叫合法, 什么叫可观测。

回头看 M02 那张十二包地图,两个包的箭头几乎指向所有其他包。这不是 依赖倒置的技巧,是"语义单一来源"的必然结果:谁定义了"合法",谁就得 被所有人依赖。

附录回到起点:v0.80 到 v1.4 的迁移对照。那里会看到这两个包是怎么 从别处拆出来的——先有重复,才有抽取。

如果想横着再看一遍,翻附录 D(合龙):一条请求从命令行到屏幕上, 穿过二十五个落点,每一站都标了出处——读不懂哪一站,就回哪一章。

下一章:附录 A(迁移)——从旧版读过来的人看它;新读者可直接跳到附录 D。


本章源码索引

文件 行数 职责
schema/src/compiler.ts 593 schema → 闭包:四条快路、bareType、三元组、RESTART
schema/src/coerce.ts 556 三遍转换、copy-on-write、重入栈与 cuts
schema/src/checks.ts 451 闭包原语:and、declaredObject、tagged、leafOk
schema/src/explain.ts 390 失败时才走的那一遍,memo 防指数
schema/src/annotations.ts 208 unevaluatedProperties 的注解追踪
schema/src/resolver.ts 203 $ref / $id / $anchor,.invalid base
schema/src/builders.ts 200 obj() / str() / opt(),STATIC brand 与 Static<S>
schema/src/validator.ts 93 compile()、Validator、CoercingValidator.parse
schema/src/typebox-static.ts 76 读 TypeBox 的 '~kind',不 import TypeBox
schema/src/formats/ 1,682 21 种 format(可选入口)
schema/test/conformance.test.ts 51 官方套件 4,213 条 + 9 条 it.fails
telemetry/src/index.ts 465 契约 + 类型推导 + createTypedSpanStarter
telemetry/src/memory.ts 463 内存实现与查询侧快照
telemetry/src/metrics.ts 145 createTypedMetrics、cardinality 收紧
telemetry/src/noop.ts 37 冻结单例,四个空方法
telemetry/src/testing/conformance.ts 387 与 runner 无关的一致性用例
ai/src/utils/validation.ts 70 校验入口:WeakMap 缓存、parse、错误文本
ai/src/api/constrained-sampling.ts 335 strict 方言:16 个关键字、optional→null、上限
ai/src/telemetry.ts 211 pi.ai.* 词表与 500 字符边界
durable/src/harness/telemetry.ts 140 pi.durable.* 词表,content-free
chord/src/telemetry-sqlite/index.ts 363 缓冲记录器:每秒 flush、容量丢弃、写坏即停
chord/src/telemetry-sqlite/store.ts 171 JSON1 查询,布尔与 1 的区分