Simulink模型差分工具需求与解决方案modelDiff

hyowinner

基于 MathWorks 官方文档、公开开源示例、论文资料和工程实践中反复出现的问题做的归纳。Simulink 模型差分这件事，核心不是把 SLX 文件当普通文本比较，而是让工程师能快速看懂“模型行为到底改了什么”。

一、为什么 Simulink 模型差分工具会有明确需求

随着 MBD 流程进入团队协作、供应商交付、基线评审、软件配置管理和 CI 流水线，Simulink 模型已经不再是个人电脑里的单个文件。一个模型变更通常会影响模块结构、信号连接、Mask 参数、配置集、数据字典、Stateflow 逻辑、库链接、模型引用以及测试结果。因此，模型差分工具至少要服务以下场景：

1. 代码评审/模型评审
需要在提交前或 Pull Request 中说明哪些模块、信号线、状态机、参数、注释发生了变化，而不是只告诉评审人“某个 .slx 文件变了”。

2. 基线追溯
当模型仿真结果发生变化时，需要定位变化是从哪个提交、哪个模块、哪个参数或哪根信号线开始引入的。

3. 供应商交付验收
甲方往往只关心“交付模型相对基线改了什么”，并希望拿到可离线查看的报告，而不是被要求必须打开完整 MATLAB/Simulink 环境。

4. 安全关键系统审查

汽车、航空、轨交、电力电子等场景里，模型变更需要有证据链。差分结果要能关联需求、测试、接口、数据类型和配置参数。

5. 多人协同开发
多个工程师同时改一个模型时，需要识别冲突、判断能否自动合并，并能把差异按子系统、Chart、接口、信号通路分层展示。

6. CI 自动化
团队希望在 GitHub/GitLab/Jenkins 等流水线中自动生成模型差分报告，并把 HTML/DOCX/PDF 报告作为构建产物附到评审流程里。

二、MathWorks 自带比较器已经解决了什么

MathWorks 的 Comparison Tool/visdiff/slxmlcomp 已经提供了比较 Simulink 模型的正式能力，包括：

- 对两个磁盘模型或同一模型不同版本进行比较；
- 支持 SLX、MDL、数据字典等文件类型；
- 在报告中显示插入、删除、修改项；
- 可在 Simulink Editor 中高亮变化；
- 可导出 HTML、Word、PDF、PDF/A 等报告；
- 可通过 visdiff 或 slxmlcomp.compare 生成比较对象；
- 可配置 Git/SVN/Perforce 等外部源代码管理工具使用 MATLAB diff/merge；
- 支持包含 Stateflow 的模型比较与合并；
- 支持在 GitHub Actions 中自动生成模型比较报告。

也就是说，官方工具已经证明了“模型差分”是刚需，并且差分结果必须具备可审查、可导出、可集成源代码管理流程的能力。

三、当前内置比较器在工程落地中的常见痛点

1. 普通 Git 文本差分看不懂 SLX
SLX 在配置管理中通常按二进制文件处理，普通 Git diff 只能看到文件整体变化，无法直接告诉工程师哪个模块、哪根线、哪个参数发生了语义变化。MathWorks 官方集成 Git 时也建议对 .slx 配置专用 diff/merge 工具。

2. 评审人依赖 MATLAB/Simulink 环境
内置比较器很适合建模工程师在 MATLAB 里使用，但并不是所有评审人、项目经理、客户、供应商都装有相同版本和许可证。CI 示例也要求 runner 上安装 MATLAB 和 Simulink，这会增加部署成本。

3. 大模型报告仍然偏“树形差异”，工程师想看图
模型工程师习惯看图形拓扑。树形报告可以定位对象，但对复杂模型，评审人更希望看到类似 Simulink 画布的两侧视图：base 模型一张图，变更后模型一张图，模块、端口、信号线、注释和配置差异直接着色。

4. 层级模型需要更自然的导航
真实工程模型通常有多层子系统、Model Reference、Library Link、Variant Subsystem、Stateflow Chart。差分工具需要同一时间只展示一个层级，并允许双击进入子系统或 Chart；如果左右模型层级不一致，应明确提示哪一侧不存在对应层级。

5. 信号线差异容易看不清
Simulink 工程师更关心“源模块端口到目标模块端口”的连接变化，而不是内部 SID。对于有分支的信号线，还要区分 trunk 和 branch，否则删除一条支路可能被误判为删除整条主干。

6. 非功能性变化容易产生噪声
布局、字体、颜色、标签位置、自动布线等变化可能不影响仿真行为。MathWorks 比较器默认会隐藏部分非功能性变化，并提供过滤功能；但团队实际落地时，往往还需要按公司建模规范定制过滤策略，例如“只看接口和行为变化”“忽略纯排版变化”“只看 Mask 参数变化”。

7. 模型引用和库链接的比较边界要小心
官方文档说明，Comparison Tool 对当前选择的模型执行比较，报告不包含 referenced models 或 linked libraries 的变化。对于工程项目，这意味着顶层模型、引用模型、库、数据字典要有统一的批量扫描和汇总机制，否则容易漏掉跨文件影响。

8. 路径和重名模型可能带来干扰
官方文档也提到同名模型、MATLAB path、模型引用接口缓存等因素可能影响比较结果。工程化工具需要在比较前做路径隔离、依赖扫描和环境记录，否则不同机器上生成的报告可能不一致。

9. Stateflow 不是普通子系统
Chart 内部有 State、Transition、Junction、entry/during/exit action、truth table 等元素。一个合格的差分工具不能只把 Chart 当成一个普通块，而应按 Stateflow 语义解析和绘制，并保持与 Stateflow 编辑器接近的视觉表达。

10. 合并操作需要工程顺序和人工确认
官方示例中也提醒，包含 Stateflow 的模型合并要注意顺序，例如先合并 block/state/junction，再合并 line/transition。说明模型合并不是简单的文本三方合并，差分工具至少要把风险和依赖关系提示清楚。

四、理想的 Simulink 模型差分工具应该补充什么

1. 离线桌面工具
双击启动，不要求每个评审人都打开 MATLAB。至少支持选择两个 SLX 文件、启动比较、查看图形结果、导出 HTML 报告。

2. 更像 Simulink 的图形视图
模块要有类似 Simulink 的外观、Icon、输入输出端口、Inport/Outport 形状；信号线横平竖直，增删改用清晰颜色标记。

3. 语义对象命名
信号线对象建议显示为“源模块路径:端口号 -> 目标模块路径:端口号”，不要只显示 SID 或内部 XML id。

4. 左右双图对比
第一个模型作为 base，第二个模型作为 compare。base 图保持原状，compare 图叠加增删改着色，摘要列表点击后能联动高亮图中对象。

5. 层级同步浏览
双击任意一侧子系统，两侧同时进入对应层级；若另一侧不存在该层级，显示“当前模型不存在此层次”。

6. Stateflow 专项解析
Chart 内部要按 Stateflow 元素绘制：state、transition、junction、entry/during/exit action、condition/action 等，并尽量复用原始位置和大小。

7. 差异分类更贴近评审
至少分为模块、信号线、注释、Mask、端口、Bus/数据类型、模型配置参数、Stateflow、模型引用、库链接、数据字典、仿真设置等类别。

8. 报告面向交付
HTML 报告应包含差异摘要、可视化截图/矢量图、对象路径、旧值/新值、影响类型、时间和工具版本，便于放入评审包和交付包。

9. CI 和批处理
支持命令行输出报告，能在 Jenkins/GitLab/GitHub Actions 中运行，并能按项目目录批量比较多个模型。

10. 团队规则可配置
允许配置忽略规则，例如忽略布局变化、忽略仿真缓存、忽略生成代码临时参数、只关注接口/行为/配置变化等。

五、结论

MATLAB 自带比较器是 Simulink 模型差分的官方能力基础，适合建模工程师在 MATLAB 环境里审查和合并模型。但从团队协作、交付验收、轻量评审、CI 集成、客户可读报告这些场景看，仍然存在“更轻量、更图形化、更语义化、更适合工程交付”的工具空间。

对国内 MBD 团队来说，真正有价值的模型差分工具，不是替代 Simulink，而是把模型变更从“文件变了”提升到“工程语义变了什么、影响在哪里、证据如何交付”。

Hyowinner校长的modelDiff工具：