配置分层合并校验工具

当三层配置叠在一起时，谁说了算

在不少工具或服务里，配置并不是一个扁平的键值表，而是分层叠加的：最底层是默认值，保证开箱即用；中间层是系统配置，由管理员按机器或环境设定；最上层是任务配置，随单次调用传入。三层都合理，但一旦合并，就会冒出两个具体问题：

• 冲突：同一项（如 delayMax）在两层里都有值，谁覆盖谁？如果任务值非法，是直接报错还是退回系统值？
• 不可审计：合并后的结果里看不出哪项被自动修复过，排查问题时只能猜测。

它如何合并与校验

config-merge 把整个过程收敛为一个纯函数：

1. 按优先级合并三层配置：任务配置 > 系统配置 > 默认值，高优先级的键覆盖低优先级。
2. 用可注入的 schema 校验：schema 不是内置的，由调用方提供，保证校验规则与业务一致。
3. 自动修复冲突：例如 delayMax 的系统值大于默认值上限时，不是抛异常，而是跳过该来源，降级取下一层的值，保证合并不中断。
4. 写入审计信息：所有自动修复都会记录到 _meta.conflicts，并标记 autoFixed: true，事后可以逐条回溯。
5. 生成指纹与快照：configHash 由配置内容生成，但不含 _meta，因此可以放心用于缓存失效判断；同时支持快照与 diff，方便比对两次合并的差异。

实现上，它是一个 Node ESM 模块，零依赖，仅用内置的 node:crypto，适合被嵌入到任何构建流程或运行时里。

适用边界与注意点

• 适合：明确存在「全局默认 + 用户设置 + 单次任务参数」三层结构的服务或 CLI 工具。
• 不适合：通用配置管理中心。它没有热加载、远程拉取或权限系统，只负责合并与校验。
• 冲突修复规则是内置的：目前只实现了「校验失败则跳过该来源，降级取下一层」，不能自定义修复策略。
• schema 必须自己注入：它不猜测字段类型，调用方需要提供校验规则，否则只做合并不校验。
• _meta 不参与 configHash：这是有意为之，审计信息不会污染缓存指纹。

它如何工作

config-merge 把整个过程收敛为一个纯函数：

1. 按优先级合并三层配置：任务配置 > 系统配置 > 默认值，高优先级的键覆盖低优先级。
2. 用可注入的 schema 校验：schema 不是内置的，由调用方提供，保证校验规则与业务一致。
3. 自动修复冲突：例如 delayMax 的系统值大于默认值上限时，不是抛异常，而是跳过该来源，降级取下一层的值，保证合并不中断。
4. 写入审计信息：所有自动修复都会记录到 _meta.conflicts，并标记 autoFixed: true，事后可以逐条回溯。
5. 生成指纹与快照：configHash 由配置内容生成，但不含 _meta，因此可以放心用于缓存失效判断；同时支持快照与 diff，方便比对两次合并的差异。

实现上，它是一个 Node ESM 模块，零依赖，仅用内置的 node:crypto，适合被嵌入到任何构建流程或运行时里。

适用边界与注意点

• 适合：明确存在「全局默认 + 用户设置 + 单次任务参数」三层结构的服务或 CLI 工具。
• 不适合：通用配置管理中心。它没有热加载、远程拉取或权限系统，只负责合并与校验。
• 冲突修复规则是内置的：目前只实现了「校验失败则跳过该来源，降级取下一层」，不能自定义修复策略。
• schema 必须自己注入：它不猜测字段类型，调用方需要提供校验规则，否则只做合并不校验。
• _meta 不参与 configHash：这是有意为之，审计信息不会污染缓存指纹。