配置：让插件拿到带校验和默认值的选项
用 Schemastery 定义 Cordis 插件配置，观察默认值补全、路径化错误和 FAILED Fiber 如何阻止带病启动。
核心结论：配置不是未经检查的对象；schema 在 apply 前运行，补齐默认值，拒绝错误输入，让插件只处理有效配置。
这让插件的行为选择可以留在 cordis.yml 或 profile patch 中，同时保持运行时代码的前置条件明确。
01 / 类型和 schema 要同时存在
一个可配置插件可以这样声明：
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
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 + '!')
}
}Config 接口为 TypeScript 提供静态类型；同名的运行时 schema 负责校验和默认值。普通对象不能替代 schema，因为 Cordis 需要符合 Standard Schema 的运行时验证器。
02 / 配置来自 cordis.yml
- name: './config-demo.ts'
config:
targets: ['alpha', 'beta']没有提供 greeting，所以 schema 把它补成 Hello，apply 接收到的配置始终是完整的：
Hello, alpha!
Hello, beta!
03 / 错误在 apply 之前暴露
把数组误写成字符串：
- name: './config-demo.ts'
config:
targets: 'not-an-array'Loader 会报告带路径的 ValidationError，例如：
ValidationError: invalid config:
- $.targets expected array but got not-an-array (at targets)Fiber 进入 FAILED，启动器以失败状态退出。插件不会先用坏配置执行几步，再在更深处留下模糊错误。
04 / schema 是配置 API 的一部分
schema 同时记录输入类型、默认值和约束。配置字段如果会改变部署行为，就应该成为 schema 字段，而不是散落在插件里的 DEFAULT_* 常量。
本仓库用 Schemastery 定义 schema，Cordis 接受符合 Standard Schema 的验证器。schema 也可以给出 required、union、数组和对象等更精细的约束。
05 / 计算值要限制在明确位置
Loader 支持本仓库扩展的 !!js：
- name: './config-demo.ts'
config:
greeting: !!js process.env.DEMO_GREETING ?? 'Hello'它只在 config 和条目的 disabled 字段内求值。name、id、inject 等元数据保持静态。config 表达式会在依赖服务激活后以插件 Context 求值，disabled 则在每次挂载决策时以 Loader Context 求值；按环境选择组合时，profile overlay 通常比让每个元数据字段都动态化更清晰。
下一步
来源：配置教程、Schemastery、Fiber 实现。
更多文章
Cordis：五个核心概念，读懂一棵插件树
用 Plugin、Context、inject、Events 与 Effect 五个概念，建立 Cordis 运行时的最小心智模型。
waterfall：用 next() 做拦截、包装与短路
沿着一条真实的 Cordis waterfall 链路，理解监听器如何委托下游、包装结果，或在拥有决策权时直接短路。
服务与上下文：Cordis 如何共享能力而不绑定实现
从 Service、Context 与声明合并出发，理解提供者、消费者和作用域如何连接 DeepSeek Harness 的能力。
邮件列表
加入我们的社区
订阅邮件列表，及时获取最新消息和更新