DSH plugin 配置怎么演进:新增字段给默认值、改名字要迁移、整行替换的坑与发布前验证
插件发出去之后,配置就不再只属于你。用户可能在 cordis.yml 里写了自己的值,也可能只在 profile 的 patch 里覆盖了一个字段。
每加一个字段、每改一个名字,都要假设「有人正在用旧写法」。
一个具体的 DSH plugin 版本场景
配置演进要从旧版本的实际配置出发,而不是从新设计出发。 假设你的插件 v1.1 的配置长这样:
export interface Config {
greeting: string
maxRetries: number
}
export const Config: Schema<Config> = Schema.object({
greeting: Schema.string().default('Hello'),
maxRetries: Schema.number().default(3),
})
发布三个月,用户数从 3 个涨到 300 个。现在 v1.2 要加三样东西:请求超时、一个开关、以及把 maxRetries 改成更准确的名字 retryLimit。三件事风险完全不同,必须分开处理。
三种 DSH plugin 配置改动,风险不一样
DSH plugin 配置改动要先分类,再动手。 三类改动的兼容成本差一个数量级:
| 改动 | 旧配置会怎样 | 风险 |
|---|---|---|
| 新增字段 + 默认值 | 缺字段,填默认值 | 低 |
| 改默认值 | 旧配置有值则不变 | 中 |
| 改名 / 改语义 / 加 required | 旧键失效或校验失败 | 高 |
新增是安全的,改名是危险的。 前者旧配置照常加载,后者插件能启动但行为会悄悄变化——这比直接报错更难排查。改默认值属于「看情况」: 用户显式写过的值不受影响,没写过的用户会感知到行为变化;如果默认值影响安全或成本,要在版本说明里单独提示。
安全的插件配置改动:新增字段
DSH plugin 新增字段只有一个原则:必须给默认值。 步骤:
- 在接口里加字段,标记为可选或直接给类型;
- 在 schema 里写
.default(...),不要在apply里写config.x ?? 默认值; - 在
apply里直接使用config.x,让类型保持非空; - 用最小配置启动一次,确认字段被填充;
- 用完整配置启动一次,确认显式值优先。
为什么强调默认值写在 schema 里? 因为只有 schema 默认值会在加载时被填充,apply 里的 ?? 是运行期兜底,类型上仍然是可选,调用方拿不到「一定有值」的保证。
不要给新字段加 required()。 一旦必填,所有旧配置在升级后立刻校验失败,插件加载不了。如果这个字段确实不能有默认值,就把它放到下个大版本,并提前公告。
危险的插件配置改动:改名与语义变化
改名的坑在于「没有报错」。 用户旧配置里写的是 maxRetries: 5,你的新代码读 retryLimit,读到的是默认值 3。插件正常启动,重试次数却从 5 变成 3。
推荐的过渡做法是双读:
export interface Config {
retryLimit: number
/** @deprecated use retryLimit */
maxRetries?: number
newSwitch: boolean
}
export const Config: Schema<Config> = Schema.object({
retryLimit: Schema.number(),
maxRetries: Schema.number(),
newSwitch: Schema.boolean().default(false),
})
export function apply(ctx: Context, config: Config) {
const retryLimit = config.retryLimit ?? config.maxRetries ?? 3
// ...
}
要点有三个:
- 新字段不要直接给默认值,否则旧值永远读不到;
- 旧字段保留并标记废弃,但仍参与读取;
- 读取顺序是「新字段 → 旧字段 → 硬兜底」,三者都要显式写出来。语义变化比改名更隐蔽: 同一个字段名,从「毫秒」改成「秒」,用户配置里的
30000会变成 30000 秒;这类改动不能靠双读,只能换字段名,并按破坏性变更处理。
为什么整行替换让 DSH plugin 改名更麻烦
很多配置系统会做深度合并,DSH plugin 不会。 patch 替换的是目标行的整个 config 值,不是逐键合并。
这意味着两件事:
- 用户只写一个字段时,其余字段回落到你的 schema 默认值,而不是继承上一层 patch 的值;
- 你改字段名后,用户那层的旧键不会自动迁移,也不会报「未知字段」错误——大多数情况下它只是被忽略。
所以兼容性不能指望「合并逻辑帮我兜住」。 字段的生命周期要自己管:新增给默认值、改名做双读、删字段等大版本。一个实用做法是把配置变更写进插件文档的升级说明——用户升级前能看到「v1.2 新增 timeoutMs,默认 30000」「v2.0 移除 maxRetries,请改用 retryLimit」,比在启动失败后猜要省事得多。
发布前怎么验 DSH plugin 配置兼容性
DSH plugin 兼容性测试只需要三种配置,但必须三种都跑。 对照执行:
- 旧配置:复制上一版用户最典型的
config,不加任何新字段,启动一次; - 最小配置:只写必填字段,其余省略,启动一次;
- 新配置:全部字段显式写出,启动一次。
每次确认三件事:能启动、--dump-config 里的值符合预期、行为与文档一致。
还要特意测一次「错误配置」。 把数字字段写成字符串,确认加载失败且报错指向该字段;能失败的校验才是校验,静默接受非法值的 schema 等于没有。最后检查默认值是否泄露到日志: 有些字段默认值包含路径或内部地址,升级后出现在启动日志里,属于无意的信息暴露。
配置演进的目标不是「这次不坏」,而是「坏的时候用户能看懂」。报错清晰、版本说明到位、旧字段有过渡期,三件事做到,用户就不会因为一次升级放弃插件。想看 Config 与 schema 的基础写法,读 DSH plugin 配置;想看 id 与整行替换的关系,读 cordis.yml 的 id;想看版本范围怎么声明,读 插件版本兼容。
常见问题
给 DSH plugin 新增配置字段时,只要在 schema 里给默认值就不会让旧配置失败。旧配置缺少该字段时由 schema 填充默认值;但如果新字段用了 required(),旧配置会直接校验失败,升级瞬间所有用户都无法启动。
改 DSH plugin 配置字段名比删字段更危险,因为删字段后旧值被忽略、行为回到默认;改名则旧键无人读取、新键拿到默认值。插件能启动但行为悄悄变了,用户不会看到报错,只会觉得功能不如以前,排查成本更高。
DSH plugin 的用户配置不能靠深度合并兜底,因为 patch 会整行替换目标 config,不做深度合并。用户那层只写了部分字段,你的默认值仍会生效,但字段一旦改名,旧键不会被迁移,等于每次都要用户手动改。
发布前至少要把三种 DSH plugin 配置组合各跑一遍:上一版用户的完整旧配置、只写部分字段的最小配置、以及新版全部字段的配置。三种都能启动且行为符合预期,才算兼容性过关。
相关术语
- schema 默认值
- schema 默认值是写在 Schemastery schema 里的兜底值,配置缺字段时由框架填充,旧配置因此能继续加载。— DeepSeek Harness 开发文档
- 破坏性变更
- 破坏性变更是指会让已有配置或调用方式失效的改动,例如改字段名、改语义、把可选字段改成必填。— DeepSeek Harness 开发文档
- 双读迁移
- 双读迁移是同时读取旧字段与新字段、优先新字段的过渡做法,让用户有时间改配置,再在后续大版本移除旧字段。— DeepSeek Harness 开发文档
- 配置层
- 配置层是叠加在配置树上的 patch 层,按组合包、profile、home、命令行覆盖的顺序应用,后应用的层优先。— DeepSeek Harness CLI 行为参考
来源
- DeepSeek Harness 开发文档:插件配置· deepseek-harness
- DeepSeek Harness CLI 行为参考· deepseek-ai
- deepseek-harness 仓库· deepseek-ai