为什么 AdditionalFiles 才是第二阶段真正的开始

第一季主线里，我们把重点放在源码输入本身：

• 类型怎么被发现
• Symbol 怎么被提取
• 代码怎么被渲染
• 非法输入怎么被诊断

这条主线必须先站稳，因为它决定了你有没有能力把一个最小闭环跑通。

但只要生成器开始真正进入项目环境，你很快就会发现，输入根本不只有源码。

第二阶段为什么不是“再多读一个文件”

很多人第一次听到 AdditionalFiles，会把它理解成“除了源码之外，再给生成器喂一个 JSON”。这个理解太轻了。

真正的变化是，输入系统被扩成了三层：

• 文件内容本身
• 文件在 MSBuild 里的元数据
• 项目级的默认值和环境配置

一旦进入这三层，生成器就不再只是“从源码拼代码”，而是在解释一套编译期配置系统。

为什么这一步更接近真实工程

真实项目里最常见的诉求，不是“看见一个特性就生成一个方法”，而是：

• 从一组配置文件生成多个输出类
• 允许某些文件做单独覆盖
• 给整个项目设置统一默认命名空间和可见性
• 允许同一个输出类由多个文件共同组成

这些需求都不是靠源码特性能优雅表达的，它们天然更适合 AdditionalFiles + MSBuild 这一层。

这一季真正要建立的心智模型

第二季不是给第一季增加一个输入渠道，而是要把你对生成器的理解升级成下面这句话：

生成器不仅在读代码，它还在读项目配置。

只要你接受这个前提，后面的这些问题才会变得顺理成章：

• 为什么 CompilerVisibleItemMetadata 是必要条件
• 为什么全局默认值会改变输出边界
• 为什么多文件合并比单文件生成更难稳住
• 为什么文件名约定、目录约定和显式启用会形成一套发现契约

第二季最容易踩错的一步

最常见的误区，是把 JSON 内容、文件级元数据和项目级默认值混成一坨。

更稳的拆法应该是：

• JSON 负责业务内容
• 文件级元数据负责单文件覆盖
• 项目级默认值负责整项目兜底

只要这三层职责没有分开，第二案例后面所有行为都会看起来像“神秘优先级”。

一句话结论

AdditionalFiles 真正重要的地方，不是“能读文件”，而是它把生成器正式推进到了编译配置系统这一层。