多文件合并成一个输出类时，真正难的不是读文件

第二案例看上去最显眼的变化，是开始读 AdditionalFiles。

但真正把实现难度拉高的，并不是“文件能不能读到”，而是：

多个输入文件怎么合法地并到同一个输出类里。

为什么读取本身反而没那么难

只要管道已经建立起来，单文件读取这件事通常还比较直接：

• 读文本
• 解析 JSON
• 提取条目
• 读取文件级元数据和项目级默认值

这条链路会出错，但它大多还是单文件局部问题。

多文件合并为什么风险更高

因为一旦进入合并阶段，问题类型就从“这个文件对不对”变成了“这组文件 together 对不对”。

这时候你要开始同时处理：

• 哪些文件属于同一个输出组
• 同一个输出组里是否出现重复条目
• 不同文件对同一输出组的可见性是否冲突
• 文件名约定、显式类名和默认类名会不会把不该并到一起的文件并到一起

这已经不是读取逻辑，而是输出契约设计。

合并阶段为什么更像架构问题

因为这里决定的，是最终“一个输出类型”的身份边界。

只要分组键定义不稳，下面这些现象都会出现：

• 原本应该分开的类被错误合并
• 原本应该合并的文件被拆散
• 某次配置改动后突然多出或少出一个生成类

这类问题在业务代码里看起来往往特别诡异，因为消费方只会看到生成结果变了，却很难第一时间定位到是哪个输入组合导致的。

第二案例里最重要的合并心智模型

单文件创建和多文件合并必须是两段逻辑：

• Create
  • 解释单个文件
• Merge
  • 决定最终输出组

只有这样，你排错时才能把问题稳定分层：

• 如果某个文件内容本身不对，先看创建阶段
• 如果输出组数量、类名或冲突行为不对，再看合并阶段

为什么诊断在这里尤其重要

多文件合并不是能不能生成的问题，而是“为什么这次没法合法生成”的问题。

例如：

• 重复条目
• 可见性冲突
• 不同文件对同一输出组的解释不一致

如果这时没有明确诊断，调用方看到的只会是“生成结果不对”。

所以第二案例里，诊断已经不再只是补充信息，而是在替这套合并契约做可观测性。

一句话结论

第二案例真正把生成器推进到工程阶段的，不是读到了更多文件，而是开始为“多输入怎样合成一个稳定输出”负责。