DeepSeek Harness 插件配置系统实战:Schemastery Schema 校验、失败即停与 `!!js` 动态配置(Cordis 教程第 5 章)

原创2026-09-20 14:56:251,819 阅读
文章标签:人工智能AI AgentAgent 框架DeepSeek

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 只允许出现在两处:

  1. 条目的 config 内部——针对该插件上下文求值;
  2. 条目的 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 的完整路径是:

  1. 读取:Include 服务按 ctx.baseUrl 解析配置路径,支持 .yaml / .yml / .json,文件不存在且有 initial 时自动创建(vendor/include/src/index.ts);
  2. 解析:YAML 内容用 entryListSchema(含 !!js 方言)解析为 EntryOptions[],顶层必须是数组,否则抛 ConfigFileError;
  3. 补丁:applyEntryPatches 以不修改原数据、结果彻底分离的方式应用补丁列表(热重载时才能正确回退已变更的补丁),id 唯一索引、insert 支持组内插入、name 校验防止误伤(vendor/include/src/index.ts);
  4. 建树:条目数组转换为 EntryTree,每个 Entry 延展出自己的子 Context;
  5. 求值:disabled 表达式在挂载决策时按加载器上下文求值,config 表达式在 injections 激活后按插件上下文求值;
  6. 启动:_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 插件 开始。

登录后查看全文
deepseek-harness