上位机篇四：标准化插件开发约定

插件化只有加载机制还不够。上位机面对的是现场设备，插件写错不仅会影响页面，还可能影响上传、补偿、诊断和 MES 链路。IIoT.EdgeClient 的插件约定把工序开发拆成几个固定部分：模块入口、业务数据、标准页面、运行任务、Cloud 上传、MES 上传、本地持久化和诊断。

标准化的目标不是减少工序差异。叠片、注液、匀浆的业务字段、PLC 点位、生产节拍和数据上传都不同，差异需要保留。平台要控制的是差异进入系统的位置：工序差异进入插件，平台能力留在宿主。

flowchart TD Entry["IEdgeProcessModule"] --> Builder["IEdgeProcessModuleBuilder"] Builder --> Data["CellData / Snapshot"] Builder --> Views["标准页面注册"] Builder --> Tasks["运行任务工厂"] Builder --> Cloud["CloudUploadChannelBase"] Builder --> Mes["MesScenarioChannelBase"] Builder --> Diagnostics["诊断状态"]

插件入口约定

插件入口类型实现 IEdgeProcessModule。公共基类 EdgeProcessModuleBase<TCellData> 把通用注册流程固定下来，插件重写服务注册和视图注册，把自己的业务能力交给宿主。这样做可以避免插件各自实现一套启动逻辑。

plugin.json 是宿主发现插件的入口。DirectoryModuleCatalog 读取清单，ModulePluginDescriptor 创建模块实例，并检查入口类型是否实现 IEdgeProcessModule。这个检查把“插件能否接入”从运行期异常提前到模块加载阶段。

标准页面约定

这张 IO 页体现的是标准页面约定。页面位置、导航结构和展示框架来自平台；具体点位和工序含义来自匀浆插件。对现场人员来说，切换到不同工序后仍然能在相似位置找到数据、产能、IO、监控、配方、诊断等页面；对开发人员来说，插件只需要补充自己的字段和数据源。

StandardModuleNavigationRegistration 提供标准页面注册方法，包括数据页、产能页、IO 页、监控页、配方页、参数页和硬件配置页。插件通过 builder 注册这些页面，不直接改 Shell 导航。

上传约定：Cloud 和 MES 分开

业务规则要求 Cloud 上传和 MES 上传分开。插件开发约定里也把这点落到了基类上：云端上传优先继承 CloudUploadChannelBase<TCellData, TPayload>，插件保留字段映射和 payload 构建；MES 上传优先继承 MesScenarioChannelBase<TCellData, ...>，复用 MesRequestExecutor，插件保留路径、payload builder 和业务校验。

这不是形式上的拆分。Cloud 上传面向管理中台归档，关系到 DeviceId、产能、日志、生产数据和过站数据；MES 上传面向外部制造执行系统，关系到外部接口接收、心跳、状态和业务上报。两类失败的诊断、重试和本地补偿不能混用。

匀浆的特殊约定

插件约定里对匀浆做了专门说明：匀浆不是多电芯并发过站场景，不使用电芯条码字典，也不把托盘码当作电芯 key。匀浆放行数据是进入本地补发和数据流水线的通道。这个限制让匀浆模型保持贴合工序，不强行套叠片或注液的多电芯模型。

这类工序差异进入插件约定，而不是写进宿主。宿主只关心插件提供什么数据、注册什么任务、暴露什么页面、接入什么上传通道；匀浆内部如何组织放行、实时、配方、设备状态等任务，由匀浆插件自己承担。

约定带来的团队边界

标准化插件开发约定解决的是协作边界。平台负责人维护 Launcher、Shell、Host.Bootstrap、公共契约和标准页面；工序开发人员在插件内实现业务模型、页面数据、PLC 任务和上传映射。新增工序时，评审重点可以集中在插件清单、入口类型、builder 注册、上传链路和本地补偿，而不是重新审一遍宿主。

这套约定让平台可以扩展，也能保持统一。插件数量增加以后，现场入口、Shell 框架、诊断方式和上传语义仍然保持稳定。

插件约定先保证宿主不失控

插件入口只能实现 IEdgeProcessModule，并通过 Configure(IEdgeProcessModuleBuilder builder) 声明能力。模块 ID、工序类型、显示名、服务注册、CellData、运行时任务工厂、上传器、硬件模板、开发样本和 UI 注册都走 builder。这个约定的目的，是让宿主只面对统一合同。

如果插件绕过 builder 直接改宿主注册表或静态全局表，宿主很快会变成工序逻辑集合。当前约定把插件能力收进固定入口，宿主可以做发现、校验、生命周期和诊断，插件只负责自己的工序。

标准页面减少重复，字段语义留在插件

标准数据页、产能页、IO 页、监控页、配方页、参数页和硬件配置页提供通用页面框架。插件可以注册这些标准页面，也可以在必要时提供自己的展示逻辑。关键是业务字段和数据模型留在插件内，共享层只抽通用接口和无业务语义的骨架。

这对匀浆、注液、叠片很关键。不同工序的 CellData 不应该被压成一个万能模型。插件内说明字段含义、数据来源、触发/应答规则和上传目标，宿主只负责把它展示和调度起来。这样后续排查时能从插件内找到业务含义，而不是在共享层寻找被稀释的字段。

开发流程按清单走

新增工序时先建立 IIoT.Edge.Module.<Process> 插件项目，再实现模块入口、业务模型、运行任务、Cloud/MES 上传映射和页面注册。启动入口通过 scripts/edge-runtime.publish.json 和生成的 launcher.profiles.json 维护，不在 Launcher XAML 里手写工序卡片。

这个流程让平台有审核点。代码评审可以检查插件是否只通过接口接入，配置是否有说明，是否误改宿主，是否把 Cloud/MES 链路混在一起。标准化插件开发约定不是文档装饰，而是后续多人协作时控制平台质量的边界。

约定要落到评审检查点

插件开发约定需要变成评审检查点。检查 plugin.json 是否存在，入口是否只实现 IEdgeProcessModule，服务和页面是否通过 builder 注册，业务字段是否留在插件内，Cloud/MES 上传映射是否分开，配置说明是否清楚。这些检查能直接防止插件绕过平台。

标准化不是要求所有工序长得一样，而是要求所有工序用同一套方式接入平台。匀浆、注液、叠片的业务流程可以不同，但启动、模块发现、页面注册、诊断和上传补偿的接入方式应该一致。

后续如果插件需要新增通用能力，也应该先沉淀成宿主接口或共享抽象，再让插件使用。不能因为一个工序急用，就把专属逻辑塞到宿主里。这样平台才能越接越稳，而不是越接越散。