在 DeepSeek Harness 里改完配置并重启,行为却与之前一模一样,这是排查插件问题时常见的困惑。 实际开发中,问题主要集中在四类:
- 以为补丁会逐键深度合并,只在覆盖层写了一两个字段,结果同一条配置行中的其他提供商被整段抹掉;
- 以为「profile 是最后修改的那份」,却忽略了 home 层补丁排在 profile 之后,导致多个 profile 共用的 home 覆盖同时影响所有 profile;
- 把
--patch文件放在仓库里,却在本次启动时根本没传这个参数,于是文件虽然存在于磁盘上,配置却没有生效; - 升级后出现了新的默认值,手写的旧覆盖却没有随之更新,因为整行替换不会自动继承新默认值。
要厘清这些问题,首先要建立这样的心智模型:"配置是一棵从空根长起来的树,每一层补丁替换的是整行,而不是某一个字段"。站内教程版可参考DeepSeek Harness 配置优先级怎么算?。
一、四层配置从哪来、谁覆盖谁?
CLI 参考明确指出,配置从空根开始组合,并按以下顺序依次应用。
| 层 | 作用范围 | 相对优先级 |
|---|---|---|
| Bundle 补丁 | 所列组合包提供的默认配置 | 首先,按 profile manifest 里列出的顺序应用 |
| Profile 补丁 | 所选 profile 自身的 cordis.patch.yml |
位于 bundle 之后 |
| Home 补丁 | $DSH_HOME/cordis.patch.yml,多个 profile 共用 |
位于 profile 之后 |
--patch <path> 覆盖 |
本次调用显式指定的文件 | 最后,按参数出现顺序应用 |
参考总览也将 profile 描述为「一组组合包 + 它自己的用户补丁」,与上表所示顺序一致。
还要注意:bundle 层不是一个 bundle,而是 manifest 里列出的那一串。因此,即使两个 profile 选择了相同的一批包,只要 manifest 中的顺序不同,最终配置树也可能不同。这也是「同一份 profile 名字在两台机器上表现不一样」的一个合理原因。
二、为什么「后者优先」这句话还不够?
「后应用的层优先」容易记,但它只回答了一半问题。要判断最终结果,还要看补丁替换的单位是什么。
官方参考的答案是:补丁会替换目标行的整个 config 值,而不是逐键深度合并(deep merge)。
也就是说,假设较早的层给某一行配了两个提供商 A 和 B:
# 较早层:同一行里有两个提供商
config:
providers:
A: {
... }
B: {
... }
如果后续补丁只打算调整 A,便只写 A:
# 后面层:只写 A
config:
providers:
A: {
...调整后的字段... }
结果不是「A 被改、B 保留」,而是整行 config 被替换为只包含 A 的版本,B 消失了。
这里必须明确一个边界:上面两段是用来说明语义的概念示例,不是可以直接粘贴的配置文件。真实字段结构应以配置目录和插件自身文档为准。
模型指南也在实际模型配置示例中专门提醒:编辑已有覆盖时,要把其他提供商和字段一起保留下来。
那么,「字段消失了」是否就意味着「配置坏了」?不一定。插件配置指南说明加载时会依据插件 schema 验证配置,并填充已声明的默认值。因此,最终生效的字段可能来自三个不同来源:
- 你这次补丁里显式写的;
- 插件 schema 填充的默认值;
- 运行时通过配置表达式从应用参数读到的值(见第五节)。
「schema 填默认值」和「从较早补丁继承字段」是两件完全不同的事。 前者取决于插件 schema 有没有为这个字段声明默认值;后者根本不会发生。排查时把这两者混为一谈,就会得出「我明明保留了它」的错误结论。
三、最容易忽略的一条:home 层排在 profile 层之后
上表中最容易让人意外的是这一行:home 补丁后于 profile 补丁应用。
这会带来两个直接影响:
- 如果两个 profile 里都有同一条目标行,而你在
$DSH_HOME/cordis.patch.yml里改了它,两个 profile 会一起被改——即使它们原本各有专用配置; - 也就是说,「我只改了 A profile」这种说法在 home 层是不成立的,除非你能确认其他 profile 里没有同名行。
因此,选择补丁层时可以按作用范围判断:
- 只对一个 profile 生效 → 写进该 profile 的
cordis.patch.yml; - 确实希望多个 profile 共享的本机偏好 → 才用 home 层,并且事先列出预期受影响的 profile 逐个验证;
- 只对某一次调用生效 → 用
--patch,不要污染共享层。
关于插件本地 checkout 的安装位置与 profile 的关系,可参阅把本地插件 checkout 装进 profile。
四、命令行补丁:文件在磁盘上,不等于这次读了它
--patch <path> 的作用范围最小,也最不容易影响其他调用,但有两个容易出错的地方:
- 顺序就是优先级:多个
--patch按参数出现顺序应用,最后一个对同一行的修改获胜; - 不传就不生效:文件存在于磁盘上,不代表启动器读取了它。包装脚本、
pnpm别名和 CI 启动命令都可能漏传这个参数。
关于命令行参数与 profile 参数的位置关系(哪个属于启动器、哪个属于应用),可参考插件命令里 profile 参数的位置——参数位置错误时,常见表现就是「命令跑了、配置没变」。
还要注意,覆盖层既能针对已有行,也能插入新行。因此,「我的补丁生效了」需要结合具体情况判断:如果补丁插入了一行新配置,而原本要覆盖的行没有匹配到目标,那么目标未匹配并不证明期望的配置已经生效。应查看诊断信息和实际的行标识,才能判断覆盖是否成功。
五、应用参数与热重载:什么时候必须重启?
1. 应用参数能不能覆盖配置,取决于配置怎么写
启动器先处理自身参数,再将应用参数交给应用。部分应用参数会提供可以被配置表达式读取的服务;CLI 参考以 Web 端口为例。
关键在于:只有配置行里保留了那条读取服务的表达式,参数才能覆盖对应值。 如果补丁用字面值替换了整个 config,就可能同时删掉了那条运行时读取。此时,即使参数已经传入且日志没有报错,它仍然不起作用。
结论:不能只用层顺序预测应用参数的结果。 还必须检查该行配置中是否保留了读取表达式。
2. 热重载取决于组合,不取决于「改的是哪一层」
- 随包的
web模板包含实时补丁能力,改配置有机会热生效; headless、sdk、acp模板在启动时应用补丁,没有相应的 HMR 插件就需要重启;- 此外,组合包成员发生变化时,即使普通补丁本身可以热重载,成员变更仍有各自的启动边界。
还要注意:schema 验证通过,仍然可能遇到插件启动失败;也可能出现「某些设置要等下一次请求才影响行为」的情况。具体应以插件自己的契约文档为准。
六、怎么准备并评审一次配置修改?
1. 五步准备流程
- 确定所选 profile 和拥有该设置的插件行,查看配置目录与插件自身文档;
- 检查现有四层(bundle / profile / home / 命令行),先记录「目前是哪一层在提供这一行」;
- 决定作用范围:单 profile 就写 profile,确认要共享才写 home,一次性调用用显式补丁;
- 准备完整的替换配置,把应该继续存在的字段和提供商一并写全,并按已安装插件的 schema 核对必填项与默认值;
- 应用后检查诊断并测试受影响的行为,尽量对比修改前后的同一请求,并为用户管理的配置留一份可恢复的副本。
如果想确认某个字段「默认应该是多少」,可参考怎么找插件配置的默认值,那里给出的查法比凭印象猜测可靠得多。
2. 两遍评审法
第一遍检查作用范围:home 行可能影响多个 profile,profile 补丁只关联所选 profile,命令行覆盖只对传入文件的调用有效。
第二遍检查最终的完整行:将「需要保留的每个提供商和设置」与「拟替换的内容」逐项对照。某个字段消失时,应判断三种可能——schema 提供了合适的默认值 / 该字段直接缺省 / 验证会失败。不要假设较早层会自动补回缺失字段。
团队记录变更时,至少要写清四项:原有作用范围与新作用范围、测试的是哪个 profile、存在哪些补丁文件、测试是否需要重启。 如果改动影响模型请求,完成后应发起一次有代表性的小请求,核对实际选中的提供商和模型。组合成功只证明配置已加载;真实请求才能验证你真正想改的行为。
七、升级之后,为什么旧覆盖会「悄悄失效」?
这是四层模型中需要长期维护的关键环节。
升级后维护补丁时,必须重新检查完整的替换内容,不能假定新默认值会自动进入其中。 原因在于第二节所说的整行替换:新的 bundle 层可能改变某个字段的默认值或结构,而手写的 config 行是完整的字面值,会把新默认值整段盖住。
建议按以下步骤处理:
- 以配置目录和已安装插件的 schema 作为字段与默认值的依据;
- 先对照新版本的要求,逐项检查旧覆盖里还有哪些字段是必要的;
- 再测试依赖该配置的行为。
升级可能改变可用 schema,旧的手写覆盖未必仍适合所有部署。修改配置后如需重启 profile,可参考插件更新后怎么重启 profile完成生效验证。至于「用哪个 profile」这一前置问题,可参阅怎么选 DSH profile。
八、设置看起来被忽略时,按这五步排查
- 先定位提供该行的层:bundle / profile / home /
--patch,记录当前生效的是哪一层。不同机器结果不同时,先比较各层输入,再比较应用现象。 - 核对行标识是否真的匹配:目标未匹配时,补丁可能只是插入了一行新配置,而不是覆盖了你想改的那一行。
- 确认替换单位:怀疑字段丢失时,逐项比对「替换前的完整行」与「替换后的完整行」,不要只看新写的几个键。
- 检查运行时表达式与实际参数:设置可能来自应用参数而非配置文件;此时要看该行是否还保留读取表达式。
- 区分「加载成功」与「行为正确」:schema 验证通过 ≠ 插件启动成功 ≠ 行为符合预期。一次有代表性的请求,比一张配置截图更有说服力。
CLI 提供配置导出模式,可辅助查看组合结果,但需要注意其边界:各模式范围不同,显示的是未求值的树,因此只能帮助追踪来源,不能保证运行时结果。 具体参数和限制以 CLI 参考为准。另外,导出也可能初始化缺失的 profile。检查一个从未使用过的名字时,应考虑这一副作用。
实践中还应遵循一条原则:调试期间一次只改一个因素。 如果同时改动 home 层、profile 和命令行补丁,即使问题恢复,也无法判断究竟是哪一处起了作用。
九、限制与安全边界
- 补丁可以改变控制访问和网络行为的插件与设置:应用陌生覆盖层之前,先检查来源并准备好回滚方式。
- 示例里不要放真实凭据:配置值、插件错误信息都可能含敏感内容,分享配置导出前务必先检查。
- schema 验证通过不代表部署合适:它只说明结构符合要求,不说明每一种有效配置都适合当前部署。
- 配置分层不等于合并所有 YAML 对象:不要把它当成「后写的和先写的自动融合」。
- 设置出现在某个文件里,不能单独证明它已生效:目标未匹配、插件被禁用、运行时表达式、选错 profile 都可能让结果与文件名不一致。
- 修改后要做小范围行为测试:只影响一个 profile 的需求不要随意扩大为 home 级共享覆盖。
- 配置导出是未求值的树:它用于追踪来源,不能替代运行时验证。
十、术语速查
- Bundle:提供配置行与代码的包;同一 profile 可以列出多个,并按 manifest 顺序应用。
- Profile 补丁:与一个 profile 名称对应的覆盖文件(
cordis.patch.yml)。 - Home 补丁:
$DSH_HOME/cordis.patch.yml,在 profile 之后应用的共享本机覆盖层。 - 行:组合后的插件配置树中的一个条目;补丁的作用单位。
- 深合并(deep merge):逐键合并多个对象——DSH 的补丁不是这样工作的,它替换整行
config。 - HMR:热模块替换,仅在组合中挂载了相应插件时可用。
相关阅读
- DeepSeek Harness 配置优先级怎么算?
- 怎么找插件配置的默认值
- 把本地插件 checkout 装进 profile
- 插件命令里 profile 参数的位置
- 插件更新后怎么重启 profile
- 更多 DSH 实践文章
本文依据 DeepSeek Harness 官方 CLI 参考、参考总览、配置目录与插件配置指南整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog