Schemastery 类型驱动 Schema 验证器全解析:从 DSL 到 DeepSeek Harness 配置体系
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
从源码看:
union依次尝试每个成员 schema,全部失败时汇总错误抛出(见 vendor/schemastery/src/index.ts);intersect对每个成员做严格校验并merge合并对象输出,因此{ a: '' }会补上b: 0的默认值(见 vendor/schemastery/src/index.ts);transform先校验inner,再调用callback转换结果;preserve为 true 时只转换输出而不再回写(见 vendor/schemastery/src/index.ts)。
实例方法: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 在本仓库并非孤立工具,而是配置体系的基石之一。几个可直接深入源码验证的落地点:
- 设置注册:
settings子系统通过ctx.settings.register(namespace, Schema, ...)注册命名空间配置 schema,并在测试中对重复注册、同名冲突等行为做了断言(见 packages/settings/settings/tests/settings.spec.ts)。 - 客户端配置声明:client 侧大量插件用
Schema.object/Schema.dict/Schema.union声明自己的设置项,例如 packages/client/ui-chat/src/chat-settings.ts、packages/client/ui-conversation/src/submission-settings.ts、packages/client/ui-settings/src/client/schema.ts 等,声明出的 schema 同时驱动校验与设置界面渲染。 - 网关与控制器:
api/gateway、api/session-controller、api/settings-controller、acp等包的依赖清单中均包含@deepseek-ai/schemastery,说明从请求参数校验到设置接口的类型约束都复用同一套 schema 体系。
值得注意的是,本仓库对 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 配置体系"从声明到界面、从宿主到客户端"的完整链路。