契约与遥测 —— 一份声明,五种解释
一个工具定义只有十四行,却要同时满足五个读者:发给模型的 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 这类配置文件的形状 |
读完这一章,你应该能回答四个问题:
- 一份声明喂给五个读者,为什么不能各写一份?不一致了会坏在哪一步?
- 不用
ajv、不用zod,自研校验器的三条硬约束是什么? errors()为什么只在失败路径上跑,代价是什么?- 同一份 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):
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>;十四行,做了四件事:
- 生成一个普通的 JSON Schema 对象,可以
JSON.stringify进请求体, 发给模型。 - 生成 TypeScript 类型
ReadToolInput,函数体里的input.path有类型。 - 生成运行时校验器,模型送回来的
arguments要过这一关。 - 失败时生成给人看的错误,这份错误还要能塞进下一轮对话。
再加两件本章会讲的:
- provider 的 strict 模式要的另一种写法:所有属性必填、对象封闭。
- 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 条被登记成"已知失败":
// 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 分钟):
cd packages/schema && npm run benchcd packages/schema; npm run bench脚本在 test/bench/:conformance.ts 让每个库跑同一份套件,zod.ts 把
schema 翻译成原生 Zod 再跑。它比的是五项:conformance、速度、setup、
内存、体积;再带上「禁止从字符串生成代码」跑一遍,是看「不许 eval」到底
贵多少。
这些数字是作者自测的,不是第三方评测。 本书引用它,理由不是"权威", 是"你能自己跑一遍"——这也是判断一切 benchmark 的唯一可靠办法:看它给 没给复跑命令,以及敢不敢把输的那一栏列出来。
1.3 决定:三个关键字集合
compiler.ts 的做法是把 schema 编译成一堆闭包。编译期只做一次,
之后每次校验就是几次函数调用。这没什么新鲜的——新鲜的是它对"什么值得
专门化"的判断,看 plain() 怎么分组:
// 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):
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。
// 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 错误只在失败时才算
// 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 就是这么用的:
if (validator.check(value)) return undefined;const [first] = validator.errors(value);工具每次返回 structuredOutput 都校验,但绝大多数返回是合法的,所以
98% 的调用只付一个闭包的开销,一次垃圾回收都不需要。
2.2 两次编译:RESTART 哨兵
$dynamicRef 是个奇怪的关键字:它的目标不是编译期决定的,而是在运行时
沿着"动态作用域"往上找。这就要求所有 check 在运行时维护一个作用域栈——
但如果 schema 里根本没有 $dynamicRef,这个栈就是纯浪费。
解法是先乐观地编一遍(validator.ts:83-93):
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):
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:
// 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):
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 摊平成一个三元组数组。
// 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 的键去查值:
// 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() 按数量专门化
// 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。找到之后,按这个键的
值直接选分支:
// 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。要知道"哪里错了、错在哪个关键字",
需要第二个解释器。
// 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):
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 转了一层:
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):
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 的注释是本包最长的一段:
/** * 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 |
手写字面量没有类型可读 |
一句话记法:外层判哨兵、中层取标注、内层是逃生口。
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):
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;三个分支,顺序有意义:
-
先认 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 genericS(constrained to builder schemas) unresolvable to its constraint's types.大意:如果放在后面,泛型
S extends Schema里的S走错分支就会变成unknown,工具参数全部丢失类型。 -
再认自己的 brand。
unknown extends T ? unknown : T是为了处理 "brand 存在但 T 是unknown"的情况——不能把unknown当作真实类型 往上传播,否则obj({ x: unknown() })会得到一个unknown类型的对象, 而不是{ x: unknown }。 -
都不是就
unknown。手写的 JSON Schema 字面量没有类型信息可读。
obj() 那一步(builders.ts:165-173):
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):
/** 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):
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 的注释:
// 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"。差异散在
各处,但有两处最容易写错:
// 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):
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):
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):
/** 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:
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 一份黑名单,十六个关键字
// 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):
// 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 的代码就这三行:
// 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
// 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); ...}三个理由,缺一个都会出事:
- 工具定义是共享的。 同一个
Tool对象在一次会话里被反复发送, 还在重试时被重新读取。就地改写意味着第一个开启了 strict 的请求会把 后面所有请求的 schema 都改掉。 - 改写不可逆。 optional 变成
anyOf[..., null]之后,没人能区分 "原本就允许 null"和"被 strict 改写出来的 null"——§7.3 里 coerce 的第 1 遍前提正是"这个 null 是我们加的",一旦原件被污染,那个前提 就变成猜测。 - 降级要能找到原件。
getJsonSchemaToolParameters(:163-165) 是二选一:strict === true才克隆改写,否则原样返回同一个对象引用。
8.4 provider 的上限被写成了常量
// 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 的核心声明是一行:
// telemetry/src/index.ts:175export function defineTelemetrySchema< const T extends TelemetrySchemaDefinition,>( schema: T,): T { return schema;}const T 让字面量类型不被放宽,然后原样返回。整个 465 行的入口文件,
这个函数不做任何事。
作者把这一点写在了另一个函数的注释里(:448-451):
/** * 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. */最硬的证据是参数的名字:
// 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 部分落地:
// 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 只对人有用,写进属性纯属浪费字节(§十 会看到这条纪律执行得
多彻底)。
顺带一个类型层面的收紧:
// 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 重名是类型错误,不是运行时错误
// 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)。
十、只记形状,不记内容
遥测最难的部分不是记录,是不记录。三句真实注释划出了边界:
// durable/src/harness/telemetry.ts:49/** Durable's content-free span, event, and metric vocabulary. * IDs address durable records, never content. */// ai/src/telemetry.ts:43description: "A completed content block; content is never recorded.",// ai/src/telemetry.ts:59errorWhen: "Stop reason is error: provider_error with at most 500 error-message characters. Aborted stays ok.",10.1 一个内容块的四个数字
// 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 的实现里有一个不显然的地方:
// 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 字符是一条硬边界
// 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:
/** 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 落盘的行一致。
两个实现共享的两条规则,值得单独记:
- 结算之后不可改。 内存实现的四个写方法都以
if (recordedSpan.settled) return;开头(memory.ts:207-227); SQLite 用record()包一层(:160-162)。span 结束后的setStatus是静默空操作而不是抛错——清理代码里顺手补一个状态是常见写法。 - 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 一条会静默丢数据的路径
// 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:把"两个实现"变成"同一份用例"
// 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):
/** 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();)。
跑它的是另一个包:
// 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):
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
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)个在编译期,其余四个在运行时或进程外。
值的回程:
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 旁路:从调用到日志
业务代码 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:
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,所以判据是从测试
源码里读出来的,不是我跑出来的输出。
cd packages/schema && npm install && npm testcd packages/schema; npm install; npm test实验 1:官方套件,4,213 条用例
cd packages/schemanpm test -- test/conformance.test.ts判据:test/fixtures/json-schema-test-suite 下有 144 个文件 / 4,213 条
用例(2020-12 有 80 个文件,draft 7 有 64 个)。每条用例跑两遍:
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):
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 各自独立
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 的两种脾气
cd packages/schemanpm test -- test/validator.test.ts -t "unresolved references"判据:validator.test.ts:192 那一节。默认模式下指不到的 $ref 在
compile() 时抛;unresolvedRefs: "reject" 下编译通过,只有落在那个
位置的值失败。
实验 4:同一份一致性用例,两个 adapter
cd packages/telemetry && npm test -- test/conformance.test.tscd packages/chord && npm test -- test/telemetry-sqlite.test.tscd 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 第二行:
expect(transaction).not.toHaveBeenCalled(); // 记录路径不碰 SQL实验 5:没有 eval
node scripts/check-browser-smoke.mjs判据:它把 scripts/browser-smoke-entry.ts 打包成浏览器能跑的产物。
那个入口里 { prompt: 1 } 会被校验并转成 "1"(§7.2)。这条能过,
说明整条校验链在浏览器里可用——也就是 §1.1 第一条约束成立。
五句话
如果只记五句:
- 一份声明,五个读者。 不是代码复用,是语义单一来源。
- 不能有
eval。 同一套校验要能在浏览器、Workers、沙箱里跑。 errors()只在失败时跑。 成功路径只调一个闭包,热路与冷路必须同谋。- coerce 三遍各自独立。 冲突时转换规则赢,不是后完成的赢。
- 防御等级跟着信任边界走。 工具 schema 当敌人看,遥测字段一行不校验。
本章小结
- 一份 schema 哺五个读者:编译、校验、类型、解释、遥测。
- 成功路径只调一个闭包,
errors()只在失败时跑。 - 热路径与冷路径必须同谋,靠同一份用例钉住。
- coerce 三遍各自独立;冲突时转换规则赢。
- 遥测 schema 一行不校验:防御等级跟着信任边界走。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 五个读者 | 编译 / 校验 / 类型 / 解释 / 遥测 | §一 |
| 闭包 | schema 编译成可调用函数 | §二、§三 |
| 延迟解释 | 失败时才构造错误信息 | §四 |
| 三遍 coerce | 可选 null / 转换规则 / 原始类型 | §七 |
| 只记形状 | 遥测只存形状,不存内容 | §十 |
练习
练习 1(读):§十四 实验 1 里 errors() 与 check() 走两套实现。
如果只改其中一套,哪条用例会先红?→ 回 §2.1、§15.1。
练习 2(改):把 coerce 的 pass 顺序对调(先 primitive 再转换规则)。
预期:where the passes conflict 那节变红;回滚:调回原顺序。
常见误区
- 你会以为 schema 只是个类型声明;实际是 它同时哺五个读者; 证据 §一 的图。
- 你会以为
$ref指不到一定编译失败;实际是reject模式下编译通过、 只让那个值失败;证据 §十四 实验 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 的区分 |