第 7 章 插件配置与热重载：让插件可被使用者定制
写死的插件没人愿意用。这一章让你的插件接受 cordis.yml 里的配置，并理解 dsh 的热重载机制。
7.1 定义 Config：类型 + Schema
导出 Config 类型和同名的 Schemastery schema，默认值直接写在 schema 里：
代码块
Plain Text
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
export const name = 'my-plugin'
export interface Config {
greeting: string
maxRetries: number
verbose?: boolean
}
export const Config: Schema
greeting: Schema.string().default('Hello'),
maxRetries: Schema.number().default(3),
verbose: Schema.boolean().default(false),
})
export function apply(ctx: Context, config: Config) {
console.log(config.greeting) // 用户传的值，或 schema 默认值
}
要点：不要导出普通对象作为 Config，它不满足 Cordis 要求的 Standard Schema 接口，框架会校验失败。
7.2 在 patch 里传配置
在 scratch-plugin/cordis.yml 的插件行里加 config：
代码块
Plain Text
- insert:
- id: hello
name: './src/my-plugin.ts'
config:
greeting: 'Hi there'
maxRetries: 5
插件加载时，Cordis 通过导出的 schema 校验配置，缺的字段自动填默认值。
7.3 严格校验
需要强约束的场景，用 Schema 表达约束本身：
代码块
Plain Text
export const Config = Schema.object({
apiKey: Schema.string().required(),
timeout: Schema.number().default(30000),
mode: Schema.union(['fast', 'accurate']).default('fast'),
})
配置不合法时插件会加载失败并给出明确错误，而不是静默用错误值跑——这正是框架喜欢的"响亮失败"。
7.4 设计原则：没有硬编码的可调参数
dsh 的约定：凡是不同部署可能需要不同值的参数，都必须定义为配置字段。
代码块
Plain Text
// 错误：硬编码超时
const TIMEOUT = 30000
// 正确：可配置，默认 30000
export interface Config {
timeoutMs: number
}
检验标准一句话：能不能在 cordis.yml 里改这个值，而不需要改代码？ 能，就对了。
7.5 热重载（HMR）
改 cordis.yml 里某个插件的 config 后，框架会卸载旧实例、加载新实例，不需要重启 dsh。
由于所有注册都是 effect（可逆副作用），替换后不会残留旧实例的注册。开发插件时，这就是你最快的调试循环：改配置 → 自动重载 → 看效果。
7.6 本章小结
•
Config 类型 + Schemastery schema 是插件的标准配置接口；
•
默认值写进 schema，patch 里传 config 覆盖；
•
可调参数一律做成配置字段，杜绝硬编码；
•
配置变更触发插件热重载，无需重启。
下一章：把插件打包成可安装的 bundle，发给别人用。