Schemastery 类型驱动 Schema 验证器全解析:从 DSL 到 DeepSeek Harness 配置体系

原创2026-09-20 22:55:361,986 阅读
文章标签:人工智能AI AgentAgent 框架DeepSeek

Schemastery 类型驱动 Schema 验证器全解析:从 DSL 到 DeepSeek Harness 配置体系

Schemastery 是 deepseek-harness 仓库内 vendored 的一个"类型驱动"(Type Driven)Schema 验证器,本指南以其 vendor/schemastery/README.md 为核心,系统讲解它的设计理念、全部内置类型与实例方法、简写语法、验证选项、可扩展机制与可序列化能力。读完本文,你将掌握如何用 Schemastery 声明配置结构、编写校验逻辑、自定义 schema 类型,并理解它如何支撑 deepseek-harness 中"一切皆插件"的配置注册体系。

为什么需要 Schemastery:五大核心特性

在 deepseek-harness 中,每个插件(package)都要声明自己的配置项,这些配置既要在宿主端完成运行时校验,又要能序列化到客户端渲染成设置界面。Schemastery 正是为此类场景设计,其 README 明确给出五大特性:

  • 轻量(Lightweight):体积远小于其他校验库。
  • 易用(Easy to use):任意 schema 既可以当作函数直接调用做校验,也可以当作构造函数实例化出默认值。
  • 强大(Powerful):支持 union(联合)、intersect(交叉)与 transform(转换)等高级类型。
  • 可扩展(Extensible):通过 Schema.extend() 注册自定义 schema 类型。
  • 可序列化(Serializable):schema 对象可序列化为 JSON,并在另一环境中重新水合(hydrate)。

从源码实现看,核心的 Schema 同时具备"可调用 + 可构造 + 可迭代元数据"三重身份(见 vendor/schemastery/src/index.ts):Schema 工厂创建出的 schema 本质上是一个函数对象,调用时委托给 Schema.resolve(data, schema, options) 完成校验,同时每个 schema 节点携带 type、inner、list、dict、meta 等结构化描述字段,这正是它能被序列化并在 UI 侧重放的原因。

基本用法:校验器与构造函数二合一

作为校验器使用(JavaScript)

const Schema = require('schemastery')

const validate = Schema.number().default(10)

validate(0)     // 0
validate(null)  // 10
validate('')    // TypeError

注意 .default(10) 之后传入 null 会返回兜底值 10,而传入类型不符的 '' 则抛出 TypeError。这一行为在源码中有精确体现:Schema.resolve 在数据为 nullable 时先检查 meta.required,再读取 meta.default 决定是放行还是克隆兜底值,最后才进入对应类型的 resolver(见 vendor/schemastery/src/index.ts)。

作为构造函数使用(TypeScript)

import Schema from 'schemastery'

interface Config {
  foo: Record<string, string>
  bar: string[]
}

const Config = Schema.object({
  foo: Schema.dict(Schema.string()).default({}),
  bar: Schema.array(Schema.string()).default([]),
})

// config 是 Config 的实例,此时为 { foo: {}, bar: [] }
const config = new Config()

由于 schema 本身可构造,new Config() 直接得到一份合法的默认配置对象。这种"schema 即类型、实例即默认值"的用法,让开发者无需单独编写默认配置对象。

通用类型全览

下表汇总了 README 中定义的全部通用类型工厂,随后逐一给出带运行结果的示例:

工厂方法 含义 未提供值时的默认值
Schema.any() 接受任意类型 undefined
Schema.never() 只接受 nullable undefined
Schema.const(value) 值必须等于给定常量 —
Schema.number() 必须是 number undefined
Schema.string() 必须是 string undefined
Schema.boolean() 必须是 boolean undefined
Schema.is(constructor) 必须是指定构造函数的实例 undefined
Schema.array(inner) 元素均匹配 inner 的数组 []
Schema.dict(inner) 值均匹配 inner 的字典 {}
Schema.tuple(list) 按位置匹配的元组 []
Schema.object(dict) 属性均匹配的普通对象 {}
Schema.union(list) 匹配其中任意一个类型 undefined
Schema.intersect(list) 同时匹配全部类型并合并 —
Schema.transform(inner, callback) 先校验再经回调转换 —

Schema.any() / never() / const()

const validate = Schema.any()
validate()            // undefined
validate(0)           // 0
validate({})          // {}

const validate = Schema.never()
validate()            // undefined
validate(0)           // TypeError
validate({})          // TypeError

const validate = Schema.const(10)
validate(10)          // 10
validate(0)           // TypeError

源码中 const 类型用 deepEqual(data, value) 做相等性判定,而非严格的 ===,因此对对象常量的比较更宽容;never 则无条件抛出 expected nullable but got ... 的校验错误(见 vendor/schemastery/src/index.ts)。

Schema.number() / string() / boolean() / is()

const validate = Schema.number()
validate()            // undefined
validate(1)           // 1
validate('')          // TypeError

const validate = Schema.string()
validate()            // undefined
validate(0)           // TypeError
validate('foo')       // 'foo'

const validate = Schema.boolean()
validate()            // undefined
validate(0)           // TypeError
validate(true)        // true

const validate = Schema.is(RegExp)
validate()            // undefined
validate(/foo/)       // /foo/
validate('foo')       // TypeError

值得留意的是,Schema.is() 的 resolver 做了双层支持:若传入的是构造函数,用 instanceof 判断;若传入的是字符串,则沿原型链查找 constructor.name 与之匹配的对象(见 vendor/schemastery/src/index.ts)。这一设计让 schema 在跨环境(如序列化到 worker 后)依然能完成"按类名"校验。

Schema.array() / dict() / tuple() / object()

const validate = Schema.array(Schema.number())
validate()                  // []
validate(0)                 // TypeError
validate([0, 1])            // [0, 1]
validate([0, '1'])          // TypeError

const validate = Schema.dict(Schema.number())
validate()                  // {}
validate(0)                 // TypeError
validate({ a: 0, b: 1 })    // { a: 0, b: 1 }
validate({ a: 0, b: '1' })  // TypeError

const validate = Schema.tuple([
  Schema.number(),
  Schema.string(),
])
validate()                  // []
validate([0])               // { a: 0 }
validate([0, 1])            // TypeError
validate([0, '1'])          // [0, '1']

const validate = Schema.object({
  a: Schema.number(),
  b: Schema.string(),
})
validate()                  // {}
validate({ a: 0 })          // { a: 0 }
validate({ a: 0, b: 1 })    // TypeError
validate({ a: 0, b: '1' })  // { a: 0, b: '1' }

以上例子的运行结果均出自 README(其中 tuple 示例中 validate(<a href="https://link.gitcode.com/i/7866c4cd69f2a5ee7e049680b9b1b1c2" target="_blank">0]) 的输出为文档原文所载)。实现层面,object/dict 的 resolver 会对每个属性递归调用 property():它把校验错误路径拼接进 options.path(形如 $.foo.bar),并在启用 autofix 时删除非法属性、回填 meta.default(见 [vendor/schemastery/src/index.ts)。dict 还额外支持键 schema(sKey)转换键名。

Schema.union() / intersect() / transform()

const validate = Schema.union([
  Schema.number(),
  Schema.string(),
])
validate()                  // undefined
validate(0)                 // 0
validate('1')               // '1'
validate(true)              // TypeError

const validate = Schema.intersect([
  Schema.object({ a: Schema.string().required() }),
  Schema.object({ b: Schema.number().default(0) }),
])
validate()                  // TypeError
validate({ a: '' })         // { a: '', b: 0 }
validate({ a: '', b: 1 })   // { a: '', b: 1 }
validate({ a: '', b: '2' }) // TypeError

const validate = Schema.transform(Schema.number().default(0), n => n + 1)
validate()                  // 1
validate('0')               // TypeError
validate(10)                // 11

从源码看:

实例方法:default 与 required 互斥

README 特别强调:default 与 required 是互斥的——required 表示不可为 nullable,default 表示 nullable 时的兜底值。

schema.required()

断言值不可为 nullable,传入 null/undefined 时抛出 missing required value。

schema.default(value)

设置 nullable 时的兜底值。源码中兜底值通过 clone(fallback) 克隆后返回,避免调用方修改到共享对象;若 schema 是 intersect 且自身无默认值,会沿第一个成员向上查找默认值(见 vendor/schemastery/src/index.ts)。

schema.description(text)

设置 schema 的描述文本,供文档与表单 UI 使用。源码中的 Meta 类型还支持 description?: string | Dict<string> 的多语言形式(见 vendor/schemastery/src/index.ts),配合 schema.i18n(messages) 方法可注入按 locale 区分的描述。

schema.simplify(value)

把值中等于默认值的部分移除,用于压缩持久化配置的体积:

const Config = Schema.object({
  foo: Schema.string().default(''),
  bar: Schema.number().default(0),
})

Config.simplify({ foo: '', bar: 1 }) // { bar: 1 }

源码中的 simplify 会递归处理 object/dict/array/tuple/intersect/union 各类型,union 分支还会先尝试用 Schema.resolve 匹配到对应成员再化简(见 vendor/schemastery/src/index.ts)。

验证选项(Validation Options)

所有 schema 都可调用,第二个参数接受验证选项(见 README):

const Config = Schema.object({
  foo: Schema.number(),
})

Config({ foo: '1' }, { autofix: true }) // {}
  • autofix:尽可能移除非法的对象属性(如上例,foo 类型不符被删除)。
  • ignore:对指定值与 schema 节点跳过校验,回调签名为 (data, schema) => boolean。
  • path:为嵌套校验错误提供初始路径。

源码中三者都有对应实现:autofix 在 property() 捕获错误后 delete data<a href="https://link.gitcode.com/i/8cf5ff9760f93583f329db9759f73cd2" target="_blank">key];ignore 在 Schema.resolve 入口最先判断;path 由 ValidationError 格式化为 $.a[0].b 形式的错误前缀(见 [vendor/schemastery/src/index.ts、vendor/schemastery/src/index.ts)。

简写语法(Shorthand Syntax)

内层类型支持如下简写,见 README:

简写 等价于
undefined Schema.any()
String Schema.string()
Number Schema.number()
Boolean Schema.boolean()
1(仅原始类型) Schema.const(1)
Date Schema.is(Date)
Schema.array(String)        // Schema.array(Schema.string())
Schema.dict(RegExp)         // Schema.dict(Schema.is(RegExp))
Schema.union([1, 2])        // Schema.union([Schema.const(1), Schema.const(2)])

也可以直接用 Schema.from() 从简写值推断 schema:

Schema.from()               // Schema.any()
Schema.from(Date)           // Schema.is(Date)
Schema.from('foo')          // Schema.const('foo')

从源码看,Schema.from 对字符串/数字/布尔生成 required 的 const schema,对 String/Number/Boolean/Function 分别映射到对应类型,其余构造函数走 Schema.is,无法推断的类型会抛出 cannot infer schema from ...(见 vendor/schemastery/src/index.ts)。

高级示例:组合出实用类型

以下高级示例均摘自 README,展示了用基础类型组合出业务语义类型的方法。

枚举(Enumeration)

const Enum = Schema.union(['red', 'blue'])

Enum('red')                 // 'red'
Enum('blue')                // 'blue'
Enum('green')               // TypeError

转字符串(ToString)

const ToString = Schema.transform(Schema.any(), v => String(v))

ToString('')                // ''
ToString(0)                 // '0'
ToString({})                // '{}'

可列表化(Listable)

const Listable = Schema.union([
  Schema.array(Number),
  Schema.transform(Number, n => [n]),
]).default([])

Listable()                  // []
Listable(0)                 // [0]
Listable([1, 2])            // [1, 2]

单个数字与数组都能通过,这正是"接受单值与多值列表"这类配置项的标准写法。

别名(Alias)

const Config = Schema.dict(Number, Schema.union([
  'foo',
  Schema.transform('bar', () => 'foo'),
]))

Config({ foo: 1 })          // { foo: 1 }
Config({ bar: 2 })          // { foo: 2 }
Config({ bar: '3' })        // TypeError

利用 dict 的键 schema(sKey)+ transform,将 bar 键归一化为 foo 键。

扩展机制:Schema.extend(type, resolve)

自定义 schema 类型通过 Schema.extend(type, resolve) 注册。resolver 接收输入值、schema 节点、验证选项与 strict 标志,返回 [value] 表示接受输入,或 [value, adapted] 表示调用方应将改写后的值回写到源对象(见 README):

Schema.extend('trimmed', (data, schema, options) => {
  if (typeof data !== 'string') {
    throw new Schema.ValidationError(`expected string but got ${data}`, options)
  }
  return [data.trim()]
})

底层机制:所有内置类型的校验逻辑本身就是一组注册在 resolvers 字典中的 resolver(any/never/const/string/number/boolean/bitset/function/is/array/dict/tuple/object/union/intersect/transform/lazy,见 vendor/schemastery/src/index.ts),Schema.resolve 按 schema.type 查表分发,因此 Schema.extend 注册的类型与内置类型完全平权。除了 Schema.ValidationError,自定义 resolver 也可直接返回二元素数组触发回写,例如 bitset 类型就是通过 <a href="https://link.gitcode.com/i/c8d9637a1f50555468b8b04d6fe2a56b" target="_blank">value, keys] 把规范化后的键列表写回源数据(见 [vendor/schemastery/src/index.ts)。

更多内置工厂方法

除 README 覆盖的通用类型外,源码还提供了若干常用便捷类型(见 vendor/schemastery/src/index.ts),在使用 Schemastery 时同样值得了解:

  • Schema.natural():非负整数(step(1).min(0));
  • Schema.percent():0 到 1 之间的数并标记为 slider(step(0.01).min(0).max(1).role('slider'));
  • Schema.date():接受 Date 实例或可解析的日期字符串并转换为 Date;
  • Schema.regExp(flag?):接受 RegExp 实例或正则字符串并编译为 RegExp;
  • Schema.arrayBuffer(encoding?):接受 ArrayBuffer/SharedArrayBuffer/二进制源,也可从 hex/base64 字符串解码;
  • Schema.bitset(bits):接受数值位集或键名数组,归一化为位数值;
  • Schema.function():接受函数;
  • Schema.lazy(callback):延迟构造递归 schema,直到校验或序列化时才展开。

表单元数据与实例方法全集

每个 schema 节点的 meta 承载两类职责:校验约束(如 pattern、max、min、step、required)与 UI 渲染信息(如 role、disabled、collapse、badges、hidden、description、link)。对应的实例方法有 hidden()、loose()(校验失败时返回默认值而非抛错)、role()、link()、comment()、disabled()、collapse()、deprecated()、experimental()、pattern(regexp)、max()、min()、step()、set(key, value)、push(value)、simplify()、i18n()、extra() 等(见 vendor/schemastery/src/index.ts)。toString(inline?) 还能把 schema 渲染成紧凑的类 TypeScript 类型字符串,如 string[]、{ a?: string }。

可序列化性与 Standard Schema 兼容

JSON 序列化与重水合

const schema1 = Schema.object({
  foo: Schema.string(),
  bar: Schema.number(),
})

// 效果与 schema1 相同
const schema2 = new Schema(JSON.parse(JSON.stringify(schema1)))

toJSON 的实现值得展开:它把 schema 图整体导出为 { uid, refs } 结构,refs 以 uid 为键保存每个节点,节点之间通过 uid 相互引用,从而保住共享引用与递归结构;重水合时 new Schema(json) 会先在 refs 上递归重建全部节点,再按 uid 取回入口 schema(见 vendor/schemastery/src/index.ts)。这正是 deepseek-harness 中配置 schema 能被安全地序列化传输、并在宿主与客户端两端重放的关键机制——settings 子系统在其类型定义中明确记载了这一用法:"Serialized schemastery schema envelope (schema.toJSON()); rehydrate with new Schema(json)"(见 packages/settings/settings/src/types.ts)。

Standard Schema ~standard 属性

Schemastery 还对外暴露 Standard Schema 规范的 ~standard 属性(见 README),兼容工具无需依赖 Schemastery 特有 API 即可完成校验。源码实现返回 { version: 1, vendor: 'schemastery', validate },校验成功返回 { value },失败则把 ValidationError 映射为 { issues: <a href="https://link.gitcode.com/i/d81e7bc3989152b6d6ae04b8f6d53407" target="_blank">{ message, path }] }(见 [vendor/schemastery/src/index.ts),依赖的规范类型来自 @standard-schema/spec 包(见 vendor/schemastery/package.json)。

在 deepseek-harness 中的实际落地

Schemastery 在本仓库并非孤立工具,而是配置体系的基石之一。几个可直接深入源码验证的落地点:

值得注意的是,本仓库对 vendored 的 Schemastery 进行了再发布,包名为 @deepseek-ai/schemastery(版本 3.18.1),声明在 vendor/schemastery/package.json 中,工作区内各包通过 workspace: 协议引用它。如果你要阅读其完整类型定义与全部 resolver 实现,vendor/schemastery/src/index.ts 是全库唯一入口文件,类型声明、工厂方法、resolver、格式化器均集中在其中。

小结

Schemastery 用"可调用 + 可构造 + 可序列化 + 可扩展"的单一抽象,把配置声明、运行时校验、默认值生成、UI 元数据与跨环境传输统一到了一起。无论是直接用 Schema.object(...) 声明插件配置,还是用 Schema.extend() 自定义类型、用 toJSON() 跨进程传递 schema,都可以在 deepseek-harness 的源码与测试中找到对应实现作为参考。理解它的设计,也就理解了 deepseek-harness 配置体系"从声明到界面、从宿主到客户端"的完整链路。

登录后查看全文
deepseek-harness