stgsharp/StgSharp.UserInterface/Generator/IncrementalGeneratorFramework.md

增量生成器框架说明

本文档说明当前 Generator 文件夹里这套增量生成器骨架为什么这样拆，以及每一层现在承担什么职责。

这里讲的是“结构设计”，不是“最终 VSS 业务代码怎么生成”。

---

1. 当前结论

当前这套结构不再是“一个字段触发一个小生成器”，而是：

1. 一个统一入口生成器
2. 一个类型级候选识别管线
3. 一个共享中间模型
4. 三个内部分析模块
5. 一个统一发射器
6. 一个诊断层预留点

也就是说，设计目标已经从“节点枚举小功能”升级成“围绕一个状态类型进行多维分析”。

---

2. 当前文件与职责

当前 Generator 文件夹中的核心文件是：

1. PanelStateIncrementalGenerator.cs
2. PanelStateIncrementalGenerator.Pipeline.cs
3. PanelStateIncrementalGenerator.Models.cs
4. PanelStateIncrementalGenerator.Analysis.cs
5. PanelStateIncrementalGenerator.StateSymbols.cs
6. PanelStateIncrementalGenerator.StateChangeBindings.cs
7. PanelStateIncrementalGenerator.StateCommandHandlers.cs
8. PanelStateIncrementalGenerator.Emitter.cs
9. PanelStateIncrementalGenerator.Diagnostics.cs

它们的职责可以概括成下面这张表：

文件	角色	负责什么
PanelStateIncrementalGenerator.cs	入口层	把 Roslyn 的增量管线接起来
PanelStateIncrementalGenerator.Pipeline.cs	候选管线层	识别类型级候选，并收集已知标记成员
PanelStateIncrementalGenerator.Models.cs	中间模型层	定义共享输入、目标、分析结果模型
PanelStateIncrementalGenerator.Analysis.cs	协调层	驱动三个内部分析模块并汇总输出
PanelStateIncrementalGenerator.StateSymbols.cs	分析模块 1	分析状态符号相关成员
PanelStateIncrementalGenerator.StateChangeBindings.cs	分析模块 2	分析状态变化绑定相关成员
PanelStateIncrementalGenerator.StateCommandHandlers.cs	分析模块 3	基于前两部分结果派生状态变化命令处理结果
PanelStateIncrementalGenerator.Emitter.cs	发射层	把分析结果输出成 .g.cs
PanelStateIncrementalGenerator.Diagnostics.cs	诊断层	预留统一诊断定义位置

一句话总结现在的结构：

一个入口识别类型声明，进入统一模型，再在内部拆成三个并列分析部分。

---

3. 入口层

对应文件：

PanelStateIncrementalGenerator.cs

它的职责仍然很单纯：

1. 建立 SyntaxProvider
2. 收集类型级候选
3. 与 Compilation 合并
4. 调用统一分析器
5. 把结果交给发射器

它不应该承担这些事情：

1. 不应该写复杂业务规则
2. 不应该直接拼大段生成代码
3. 不应该依赖某一块具体的状态逻辑

入口层越薄，后面三部分演化时越安全。

---

4. Pipeline 层

对应文件：

PanelStateIncrementalGenerator.Pipeline.cs

这层的重点已经从“字段筛选”切换成“类型筛选”。

4.1 IsCandidate

这一步只做便宜的语法级判断。

当前策略是：

1. 只看 TypeDeclarationSyntax
2. 该类型内部至少存在一个带 Attribute 的字段、属性或方法

这一步允许误报，但必须便宜。

4.2 Transform

这一步开始做语义级确认。

当前逻辑是：

1. 拿到类型符号 INamedTypeSymbol
2. 遍历该类型成员
3. 识别已知 Attribute
4. 收集所有命中的成员
5. 构造一个类型级目标 PanelStateIncrementalGeneratorTypeTarget

这一步的核心意义是：

1. 根输入单位是“类型”
2. 成员只是这个类型上的分析素材
3. 后面的三部分都共享同一份素材，而不是各自重新扫一遍类型

---

5. Models 层

对应文件：

PanelStateIncrementalGenerator.Models.cs

中间模型的作用，是把 Roslyn 的语义对象整理成稳定的数据结构，供后面多个模块共享。

当前关键模型包括：

1. PanelStateIncrementalGeneratorMarkedMember
2. PanelStateIncrementalGeneratorTypeTarget
3. PanelStateIncrementalGeneratorInput
4. PanelStateIncrementalGeneratorTypeAnalysis
5. PanelStateIncrementalGeneratorOutput

以及三个内部分析结果：

1. PanelStateSymbolPartAnalysis
2. StateChangeBindingPartAnalysis
3. StateChangeCommandHandlerPartAnalysis

其中第三个结果不再对应一个额外的用户声明 attribute，而是前两部分分析完成后自动推导出来的调度结果。

这意味着现在共享的不是某个模块实例里的私有字段，而是显式模型。

这点很重要，因为源生成器里真正稳定的共享方式就是：

1. 共享模型
2. 共享编译上下文
3. 共享归一化后的分析结果

而不是模块之间互相暴露运行时对象。

---

6. Analysis 层

对应文件：

1. PanelStateIncrementalGenerator.Analysis.cs
2. PanelStateIncrementalGenerator.StateSymbols.cs
3. PanelStateIncrementalGenerator.StateChangeBindings.cs
4. PanelStateIncrementalGenerator.StateCommandHandlers.cs

这一层是当前结构里最关键的变化。

以前如果只做一个节点枚举生成器，那么 Pipeline 之后可以直接进 Emitter。

但现在不行，因为你已经明确有三块并列需求：

1. StateSymbols
2. StateChangeBindings
3. StateChangeCommandHandlers

所以中间必须有一个统一分析层。

它负责：

1. 对每个类型目标进行统一调度
2. 先调用前两个显式分析模块
3. 再基于前两部分结果运行第三个派生调度阶段
4. 把三个分析结果装配成一个类型级总分析结果
5. 保证最终发射器看到的是完整上下文

这就是“一入口，三部分”的真正落点。

---

7. Emitter 层

对应文件：

PanelStateIncrementalGenerator.Emitter.cs

发射器当前还是一个骨架，但它已经不再只是输出“发现了哪些字段”，而是输出：

1. 发现了哪些类型
2. 每个类型在三部分里各命中了多少成员

这类 manifest 的作用不是业务交付，而是结构校验：

1. 证明统一入口已经接通
2. 证明类型级分析结果已经被汇总
3. 证明发射器能看到三部分的完整结果

等后面要真正生成 enum、binding 路由、handler 路由时，这个文件会自然长大。

---

8. Diagnostics 层

对应文件：

PanelStateIncrementalGenerator.Diagnostics.cs

当前它依然很薄，这是正常的。

它的存在价值是为后续统一诊断留一个稳定出口，例如：

1. 标记位置不合法
2. 同一类型内声明冲突
3. 某个 handler 签名不符合规则
4. 某个 binding 指向不存在的状态路径
5. 同一路由被重复生成

真正重要的不是现在有没有很多诊断，而是不要等逻辑长大后再到处散着写诊断定义。

---

9. 为什么必须是“一入口三部分”

如果把这三块拆成三个彼此独立的生成器，会立刻遇到两个问题：

1. 元数据重复扫描
2. 诊断信息无法自然共享

更严重的是，多个生成器之间并不适合靠实例成员互相通信。

因此更合理的结构是：

1. 一个根入口
2. 一个共享模型
3. 三个内部分析部分
4. 一个统一发射出口

这就是现在这套结构背后的核心原则。

---

10. 当前阶段的定位

现在这套代码还只是“结构骨架”，不是“业务生成完成版”。

它已经完成的事情是：

1. 根入口已经统一
2. 输入粒度已经切到类型级
3. 三部分内部分析已经独立成模块
4. 发射器已经能看到完整汇总结果

还没有完成的事情是：

1. 真实的状态符号生成
2. 真实的状态变化绑定生成
3. 真实的基于前两部分推导出的状态命令路由生成
4. 真实的统一诊断规则

也就是说，当前目标不是“把功能做完”，而是先把以后不会推翻的结构搭稳。

但从工程实现看，它其实是几件不同的事情：

1. Roslyn 入口接线
2. 低成本筛候选
3. 高成本做语义确认
4. 把结果整理成稳定模型
5. 输出代码
6. 在不合法时报诊断

如果这几件事全写在一个文件里，短期看更短，长期一定更难改。

所以你可以把这套拆分理解成：

它不是为了“显得标准”，而是为了让后面真正加业务逻辑时，不需要每次都从一坨 Roslyn 接线代码里翻东西。

---

9. 一个更直观的心智模型

你可以把当前框架理解成一条流水线：

1. 入口层：把流水线接起来
2. Pipeline：把矿石挑出来
3. Models：把矿石做成标准坯料
4. Emitter：把坯料加工成成品代码
5. Diagnostics：发现废品时给出报错

如果写成一句更短的话：

1. 找目标
2. 抽模型
3. 发代码
4. 报问题

---

10. 你后面最可能怎么继续扩展

如果按你现在的 VSS 方向继续，这套框架下一步通常会往下面长：

第一步：把 Target 变得更像“节点描述”

例如不只是保存字段名，还保存：

1. 节点名
2. 所属 PanelState
3. 路径前缀
4. 可生成成员集合

第二步：在 Emitter 中真正生成 enum

例如：

1. 每个 PanelState 对应一个 xxxNode enum
2. enum 成员由被标记字段自动生成

第三步：继续生成路由代码

例如：

1. string path -> enum
2. enum -> setter/handler

第四步：再接入受控状态写入与分布式 observer hook

例如：

1. pre-change handler 调用点
2. set property
3. 由源生成器织入的轻量 post-change observer hook
4. 局部状态广播或内部同步

这里的 observer hook 只负责很薄的一层内部广播，不负责 view 重绘或业务执行。 在 VSS 中，这两部分分别由 command/result 同步链路与 service 逻辑承担。

---

11. 对你当前项目的最简理解

如果你觉得这套骨架有点“过工程化”，可以先只记住下面这五句话：

1. IncrementalGenerator 文件只是总入口，不负责细活。
2. Pipeline 文件负责找出哪些代码需要生成。
3. Models 文件负责把识别结果整理成稳定的数据结构。
4. Emitter 文件负责把这些数据真正输出成 .g.cs。
5. Diagnostics 文件负责以后统一放错误和警告定义。

你后面要改业务逻辑，主要会集中在 Pipeline、Models、Emitter 这三层。

---

12. 最后一句话

当前这套框架不是“生成器已经很复杂了”，而是“先把复杂度分栏放好”。

你后面真正写逻辑时，应该优先记住这个原则：

1. Pipeline 决定“找谁”
2. Models 决定“怎么表示它”
3. Emitter 决定“怎么生成它”

只要这三个边界不乱，后面的业务逻辑就算加很多，也还会比较稳。