5. 配置

组合文档中的每个配置项都可以携带 config 块；插件声明一个配置类型，在运行 Apply 前完成反序列化与校验。 错误配置导致加载失败并给出准确错误：插件绝不会在配置不完整时启动。

可配置插件

dsh 用 Schemastery schema；C# 版用 DataAnnotations 配置类 （src/Cordis.Loader/PluginCatalog.cs，与仓库既定选型一致）：

using System.ComponentModel.DataAnnotations;

public sealed class GreetConfig
{
    public string Greeting { get; set; } = "Hello";

    [Required, MinLength(1)]
    public string[] Targets { get; set; } = ["world"];
}

在 catalog 上注册时声明配置类型；YAML 的 config 映射先反序列化为 GreetConfig、 再经 Validator.ValidateObject(..., validateAllProperties: true) 校验，通过后工厂才会运行：

var catalog = new PluginCatalog();
catalog.Register<GreetConfig>("greet", config => Plugin.From(c =>
{
    foreach (var target in config.Targets)
        Console.WriteLine($"{config.Greeting}, {target}!");
}));

未提供的属性保留 C# 默认值：Apply 始终收到完整且经过验证的配置。

代码内挂载也可以传配置：实现 IConfigurablePlugin 的插件会在 apply 前收到 ctx.Plugin(plugin, config) 的 config 对象；委托版快捷方式是 Plugin.From<TConfig>((c, config) => ...)（src/Cordis/Plugin.cs）。

明确报错

向它传入无效内容（例如 targets 写成字符串）：catalog 的 Create 在反序列化或校验阶段抛出， 错误信息指明插件名与失败原因——对应 dsh 的 ValidationError 行为：fiber 失败、组合挂载明确报错。 同理，配置通过校验但引用的资源不可用（路径不存在、名称无法解析）时，插件应当在能解析该引用时立即拒绝， 而不是带着半可用状态启动。

计算得到的配置值

有意偏离：dsh loader 支持 !!js 标签在加载时求值表达式；Tether 不做 !!js （组合文档不允许执行代码），改用环境变量替换（src/Cordis.Loader/EnvSubstitution.cs）

• stable-id 有序 patch。按平台或环境门控一行的需求，用 patch 层覆盖 disabled 字段表达。 详见 YAML 组合与加载。

下一章：组合与 HMR：把 YAML 文档视为应用。