DeepSeek Harness 配置树怎么核对？三种 dump 模式、层来源与覆盖差异对比

DeepSeek Harness 的配置问题，第一步不是改文件，而是把“最终生效的树”导出来看。 官方给了三个互斥的 dump 模式：--dump-default-config 只看组合包基线，--dump-config 叠加 profile、home 与命令行 patch，--dump-config-schema 输出字段 schema。三者都不启动应用，也不执行配置表达式。

DeepSeek Harness：三种 dump 各回答什么问题

选错模式，看到的就不是你以为的那棵树。 对照如下：（来源）

三条命令互斥，不能同时用；也都拒绝应用参数。比如 dsh --profile web --port 8080 --dump-config 不会按你想象的方式工作，因为 --port 属于应用参数，dump 只展示解析应用参数之前的树。

DeepSeek Harness：怎么读 --dump-config 的来源注释

--dump-config 的价值不只是“看值”，而是“看这个值是谁写的”。 输出会用注释标出每行来自哪个文件、被哪些 overlay 改过。读的时候按三层看：（来源）

1. 先找目标行 — 用插件名或字段名搜索。预期：定位到具体 entry。
2. 看来源注释 — 注释会指出是 bundle、profile patch、home patch 还是命令行 patch。预期：知道该去改哪个文件。
3. 看被谁覆盖 — 同一行可能被多个 overlay 改过，最后一个生效。预期：不会改了一个“看起来该生效”的旧层。

一个常见误区是只改 profile 的 cordis.patch.yml，却被 home 级 patch 覆盖。home 级 patch 优先于逐 profile 配置层，命令行 --patch 又排在最后。顺序不清时，dump 是最快的证据。

DeepSeek Harness：schema dump 能回答什么

--dump-config-schema 回答“这个插件支持哪些字段”，不回答“我现在配了什么”。 它能给出：（来源）

1. 字段与类型 — 普通字段内联，共享 Config 用 $ref。预期：知道某个值该写字符串、数字还是数组。
2. 默认值与必填 — 默认值是注释，不执行填值；必填字段会考虑 nullable fallback。预期：知道不写时会发生什么。
3. 角色与限制 — secret、credential-ref、ms 等角色保留在 x-cordis。预期：知道哪些字段涉及凭据或时间单位。
4. 不完整标记 — 回调验证、不支持的正则等会标为 partial。预期：不会把 schema 当成运行时校验的完整替代。

schema 输出是 JSON，适合喂给脚本做字段核对，但不适合直接当“配置模板”复制；它描述的是声明，不是值。

DeepSeek Harness：三种实战用法

dump 不是只有排错时才有用，配置评审、升级对比、插件开发都能用。 三种用法：（来源）

1. 定位覆盖冲突 — 改完不生效时，先 --dump-config 看最终值和来源。预期：确认是哪个层覆盖了你。
2. 核对插件字段 — 写新插件配置前，先 --dump-config-schema 查字段名与默认值。预期：不靠猜字段拼写。
3. 升级前后留基线 — 升级前导出一次 --dump-config，升级后再导一次做 diff。预期：看到默认值、字段或层顺序的变化。

第三种用法尤其适合“升级后行为变了但不知道哪变了”的场景。diff 比逐个项目点开看快得多。

DeepSeek Harness：限制与安全边界

dump 是只读检查工具，不是配置执行器；它也有明确的边界。 四点注意：（来源）

• 不执行插件 — 不会应用插件、执行 transform 或求值 !!js 表达式。预期：dump 成功不代表启动一定成功。
• 可能导入模块 — 收集过程会导入可信模块，可能调用 Config getter 或 lazy builder。预期：不要对不可信插件跑 dump。
• 可能保留句柄 — 导入可能在输出后阻塞或保留进程句柄。预期：自动化调用要设外部超时。
• 输出可能含敏感信息 — 默认值与插件原始错误可能带敏感数据。预期：分享前检查，必要时脱敏。

另外，dump 会初始化缺失的 profile 文件。也就是说，第一次对某个 profile 跑 dump，可能顺带把它的基础文件创建出来；这是正常行为，不是副作用 bug。

DeepSeek Harness：输出太长时怎么缩小范围

dump 输出的是整棵树，直接读很容易迷路；先缩小问题范围，再定位到行。 三种做法：（来源）

1. 按插件名搜索 — 先用 grep 找到目标 entry，再读它前后的注释。预期：只看相关层，不被几百行无关配置淹没。
2. 先用 schema 查字段 — 不知道字段名时，先跑 --dump-config-schema，再回到 --dump-config 搜值。预期：避免用错关键词搜不到。
3. 先对比默认基线 — 怀疑默认值变了，就先 diff --dump-default-config 与 --dump-config。预期：快速区分“模板变了”与“我的 patch 改了”。

如果输出里出现大量重复插件名，先确认是不是同一个组合包被多个层重复插入；这类问题看来源注释比看值更快。

三种常见误用也值得避开：

1. 用 default dump 排查用户配置 — 它本来就不叠加用户 patch，看不到你改的值。
2. 用 schema dump 找当前值 — 它只有字段与默认值注释，没有实际配置。
3. 把 dump 成功当成启动成功 — dump 不应用插件，插件启动失败仍可能发生。

把这三条记成检查习惯，能省掉大量“导出了但看错对象”的时间。

退出码与失败形态

dump 不是“只要能输出就成功”，不同失败会用不同方式表达。 三种情况：

1. 准备、patch 解析或组合失败 — 以非零退出码结束，不输出可用文档。预期：脚本应把非零当失败，不要继续解析 stdout。
2. schema 投影 partial — 保留部分输出并以 1 退出，诊断同时写到 stderr。预期：输出可以参考，但不能当完整 schema。
3. 找不到 patch 目标 — 报告到 stderr，不一定是致命错误。预期：先看 stderr，再决定是否修 patch。

另外，dump 会导入可信模块，可能保留进程句柄；自动化调用要设外部超时，不能假设它会自己退出。

DeepSeek Harness 常见问题

Q：dump 输出里没有我改的字段，是不是没保存？ 先确认改的是哪个 profile、哪个 home，再用 --dump-config 而不是 --dump-default-config。后者本来就不叠加用户 patch。

Q：为什么 schema dump 里有 partial 标记？ 表示某些约束无法完整投影成 JSON Schema，例如回调验证或不支持的正则。运行时仍按原生 Schemastery 校验，schema 只是参考。

Q：dump 能不能用来做 CI 校验？ 可以，但要注意它会导入模块、可能保留句柄，且 schema 输出不是稳定版本化目录；每次升级 DSH 或插件后应重新生成再比对。

一句话收束： 配置排查先分清“基线、有效值、字段声明”三种问题，再选对应的 dump；选错模式，越看越乱。