DeepSeek Harness 插件配置系统实战:Schemastery Schema 校验、失败即停与 `!!js` 动态配置(Cordis 教程第 5 章)
DeepSeek Harness 插件配置系统实战:Schemastery Schema 校验、失败即停与 !!js 动态配置(Cordis 教程第 5 章)
Cordis 是 DeepSeek Harness 底层的插件框架,所有能力(工具、LLM 适配器、文件访问、Agent 循环本身)都以插件形式挂载到共享 Context 上。本文是 Cordis 教程 的第 5 章,聚焦插件配置:每个 cordis.yml 条目都可以携带 config 块,插件用 Schema 在 apply 执行之前完成校验,非法配置会以精确错误终止加载,插件绝不会"带着残缺配置"启动。读完本文,你将掌握:用 Schemastery 声明可配置插件、在 YAML 中传入配置并利用默认值、让错误配置"响亮失败"(Fail loud)、以及用 !!js 标签在加载时计算配置值,并理解这些行为背后的加载器源码实现。
配置进入插件的路径:cordis.yml 的 config 块
Cordis 教程的每一章都在仓库的 tmp/cordis-tutorial 临时目录中运行同一个单文件启动器(tmp/ 已被 gitignore,写入内容不会触碰版本控制):
mkdir -p tmp/cordis-tutorial
cd tmp/cordis-tutorial
node --import tsx ../../vendor/cordis/bin.js
这个启动器(vendor/cordis/bin.js)只做了三件事:创建根 Context、挂载 Loader 插件、让 Loader 加载当前目录下的 ./cordis.yml:
const ctx = new Context()
ctx.baseUrl = pathToFileURL(process.cwd()).href + '/'
await ctx.plugin(Loader)
await ctx.loader.create({
name: '@deepseek-ai/cordis-plugin-include',
config: { path: './cordis.yml' },
})
--import tsx 标志让 Node 无需构建即可直接运行配置指向的 TypeScript 文件。"有哪些插件、如何配置"全部来自这份 YAML——其中每个条目的 config 块就是该插件收到的配置对象。加载器在调用插件 apply(ctx, config) 之前,会先用插件声明的 Schema 对 config 做校验;校验通过后才执行 apply,失败则加载失败并给出精确错误。
编写一个可配置插件:类型与运行时 Schema 同名导出
在 tmp/cordis-tutorial 下创建 config-demo.ts:
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
export const name = 'config-demo'
export interface Config {
greeting: string
targets: string[]
}
export const Config: Schema<Config> = Schema.object({
greeting: Schema.string().default('Hello'),
targets: Schema.array(String).default(['world']),
})
export function apply(ctx: Context, config: Config) {
for (const target of config.targets) {
console.log(`${config.greeting}, ${target}!`)
}
}
同名导出的双重身份
文件同时导出了 interface Config(TypeScript 类型)和 const Config(运行时 Schema)。二者同名并非巧合,而是一套刻意设计:使用者(其他插件、类型检查器)拿到的是类型,Cordis 拿到的是校验器。Schema<Config> 是泛型标注,声明"这个 Schema 校验的是哪个对象结构"。
本仓库使用 Schemastery),但 Cordis 本身并不绑定它——Cordis 接受任何实现了 Standard Schema 规范的校验器。这意味着:如果只是导出一个普通对象作为 Config(而非 Schema 实例),Cordis 无法对其做运行时校验,配置将不可用。
Schema 工厂的关键方法
从 vendor/schemastery/src/index.ts 的静态工厂可以看出 Schemastery 的建模能力:Schema.object() 定义对象结构,Schema.string() / Schema.number() / Schema.boolean() 定义基础类型,Schema.array(...) 定义数组,此外还有 Schema.any()、Schema.never()、Schema.const() 等。实例方法负责附加约束与默认值,其中 .default(value) 会在字段缺失时回填默认值——这正是示例中 greeting 与 targets 的兜底来源。
用 YAML 配置插件:默认值自动补齐
给 cordis.yml 写入配置:
- name: './config-demo.ts'
config:
targets: ['alpha', 'beta']
运行启动器,输出:
Hello, alpha!
Hello, beta!
greeting 在 YAML 中被省略,Schema 的默认值 'Hello' 自动补齐。apply 收到的永远是完整、已校验的配置——这是 Cordis 配置体系的核心保证:插件作者无需在 apply 内部做"字段是否存在"的防御性检查。
失败即停(Fail loud):精确报错与 fiber FAILED
现在喂给它一份非法配置:
- name: './config-demo.ts'
config:
targets: 'not-an-array'
加载器打印的错误精确到字段与期望类型:
ValidationError: invalid config:
- $.targets expected array but got not-an-array (at targets)
错误的语义拆解:$.targets 是 JSON Pointer 风格的字段定位;expected array but got not-an-array 说明期望类型与实际值;(at targets) 再次点明出错字段。插件永远不会"半配置"地启动——校验失败发生在 apply 执行之前。
源码视角:fiber 如何进入 FAILED
在 vendor/loader/src/config/entry.ts 的 _start 方法中可以看到加载器启动插件的完整逻辑:先 _patchContext([]) 建立插件上下文,随后 ctx.registry.plugin(plugin, this.options.config, ...) 以当前条目的 config 创建 fiber 并 await fiber.await();一旦 apply 抛出 ValidationError,_start 捕获异常并 _dispose(fiber) 回滚,错误向上传播:
private async _start(plugin: any) {
let fiber: Fiber | undefined
try {
await this._patchContext([])
this.loader.showLog(this, 'apply')
fiber = this.fiber = this.ctx.registry.plugin(plugin, this.options.config, this.getOuterStack)
await fiber.await()
} catch (error) {
await this._dispose(fiber)
throw error
}
}
对应到本教程的启动器行为:插件的 fiber 进入 FAILED 状态,launcher 打印错误后以状态码 1 退出。Entry.init / Entry._await 会把失败包装为 failed to apply loader entry <id> (<name>): ... 形式的错误(见 vendor/loader/src/config/entry.ts),保证失败信息可定位到具体条目。
插件侧的主动再校验
Schema 只能校验"形状合法",无法校验"引用的资源真实存在"。教程给出的工程准则:当配置在 Schema 上合法、但点名了不可用的资源或 Provider 时,插件应当在能解析该引用的最早时机主动拒绝。例如配置中的模型名、文件路径、Provider 标识不存在时,在 apply 内尽早抛出带上下文信息的错误,让失败发生在最接近问题源头的位置,而不是等到运行时才爆炸。
计算型配置值:!!js 标签
本仓库使用的加载器支持 !!js YAML 标签,用于"必须在加载时计算"的配置值:
- name: './config-demo.ts'
config:
greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
运行后,若环境变量 DEMO_GREETING 存在则使用其值,否则回退到 'Hello'。这使得配置可以引用环境变量、平台信息等运行时事实,而无需手写第二份配置。
!!js 的合法使用位置
!!js 只允许出现在两处:
- 条目的
config内部——针对该插件上下文求值; - 条目的
disabled字段——本仓库的扩展:每次挂载决策时都针对加载器上下文求值。
其他元数据(name、id、inject、group 等)保持静态,其中出现表达式会被当作普通的 truthy 数据,不会被执行。关于加载器配置的完整说明见 Cordis Primer 的 Loader Configuration 章节。
源码视角:从 YAML 标签到求值
!!js 的实现横跨三层,都在 vendored 源码中可以印证:
1. YAML 解析层——vendor/include/src/index.ts:cordis-plugin-include 注册了一个自定义 YAML 类型 tag:yaml.org,2002:js,把 !!js 标量解析为序列化表达式节点 { __jsExpr: data },并通过 entryListSchema = yaml.JSON_SCHEMA.extend(JsExpr) 导出这一"条目列表 YAML 方言"——离线配置工具(如 dsh --dump-config)解析打印的正是同一套方言,保证 dump 结果与真实启动行为永不分叉。
2. 表达式求值层——vendor/loader/src/config/utils.ts:evaluate 用 new Function('ctx', 'expr', 'with (ctx) { return eval(expr) }') 构造求值器,表达式在 loader 上下文的 with 作用域内执行;interpolate 递归遍历配置对象,把每个 __jsExpr 节点替换为求值结果,数组与对象逐层深入;isJsExpr 通过 '__jsExpr' in value 识别序列化节点。
3. 条目状态层——vendor/loader/src/config/entry.ts:disabledOf 判断条目的禁用状态时,若 disabled 是 !!js 表达式则调用 evaluate 求值并 Boolean() 化,且原始节点保留在 options 中以便回写:
private disabledOf(options: EntryOptions): boolean {
return isJsExpr(options.disabled)
? Boolean(this.evaluate(options.disabled.__jsExpr))
: Boolean(options.disabled)
}
EntryOptions 的结构(vendor/loader/src/config/entry.ts)明确了每个条目的全部字段:id(条目树内的稳定标识)、name(模块说明符)、config(传给插件的配置)、group(是否嵌套组)、disabled(是否禁用本条及其后代)、inject(依赖的服务)。
求值时机:插件上下文 vs 加载器上下文
求值上下文的差异是理解 !!js 的关键,Cordis Primer 给出了精确定义:
config内的表达式:在声明的 injections 激活之后、针对该插件上下文(即ctx.serviceName)求值——所以表达式可以引用已注入的服务;disabled内的表达式:在每次挂载决策时针对加载器上下文求值——所以一个条目可以依据平台或环境自我门控;- Include 会把嵌套行的表达式保留到目标激活时才解析,因为 loader 的
internal/config插值对作为"条目与补丁列表"的树载体配置保持字面量处理,嵌套行config里的表达式归属该行自己的 fiber(见 vendor/include/src/index.ts 的注释)。
实战示例:按环境门控插件
利用 disabled 的动态求值,可以让某一行只在特定平台或环境变量下启用,其他环境静默跳过:
- name: './config-demo.ts'
config:
targets: ['ci']
disabled: !!js process.platform === 'win32'
当检测到 Windows 平台时,该条目在每次挂载决策时被判定为禁用,其 plugin 与后代都不会执行。
一次配置加载的完整调用链
把上面的散点串起来,一条 cordis.yml 配置从文件到 apply 的完整路径是:
- 读取:
Include服务按ctx.baseUrl解析配置路径,支持.yaml/.yml/.json,文件不存在且有initial时自动创建(vendor/include/src/index.ts); - 解析:YAML 内容用
entryListSchema(含!!js方言)解析为EntryOptions[],顶层必须是数组,否则抛ConfigFileError; - 补丁:
applyEntryPatches以不修改原数据、结果彻底分离的方式应用补丁列表(热重载时才能正确回退已变更的补丁),id唯一索引、insert支持组内插入、name校验防止误伤(vendor/include/src/index.ts); - 建树:条目数组转换为
EntryTree,每个Entry延展出自己的子Context; - 求值:
disabled表达式在挂载决策时按加载器上下文求值,config表达式在 injections 激活后按插件上下文求值; - 启动:
_start用求值后的config创建 fiber,Schema 校验失败则 fiber 进入 FAILED、_dispose回滚、launcher 以退出码 1 结束。
小结与延伸
本章的三个核心结论值得作为插件开发的设计准则:
apply永远收到完整、已校验的配置——缺省字段由 Schema 默认值补齐,坏配置在入口处就被拦截;- 让失败响亮且精确——Schema 报错会带字段路径与期望类型;Schema 之外的"资源可用性"校验要在能解析引用的最早时机主动抛出;
!!js是受控的求值后门——仅限config与disabled两处,分别对插件上下文与加载器上下文求值,让配置可以响应环境而不失静态可读性。
下一篇 Composition and HMR(第 6 章) 将把 cordis.yml 当作应用本身来对待:配置文件的插件树组合、热重载,以及如何诊断一个"永远不加载"的插件。更完整的配置模型与全部字段定义,可继续阅读 Cordis Primer;想直接为 Harness 本体(由 cordis.yml 加载、通过 Web UI 驱动)编写插件,可从 你的第一个 Harness 插件 开始。