Simulink AI 建模规范Skill：命名、布局、模块与连线

hyowinner

Simulink AI 建模规范：命名、布局、模块与连线的工程化约束

最近用 AI 或脚本自动生成 Simulink 模型时，一个很常见的问题是：功能能跑，但模型打开后不够工程化，比如块名是 Constant1/Add2，信号线交叉，反馈线贴着模块，数据类型靠继承，验证用 Display/Scope 混在算法子系统里。

下面整理一份面向 AI 建模的 Simulink 规范，目标不是替代项目正式的 MAB/MAAB 检查，而是给 AI 一个更明确的建模约束，让生成出来的模型更接近工程师愿意维护的模型。

一、总体原则

1. 单一职责：每个子系统只表达一个明确功能，不要把输入处理、核心算法、输出处理混在同一层。
2. 显式优先：数据类型、采样时间、初值、常量含义应显式设置，避免大量继承类型导致审查困难。
3. 从左到右：主数据流从左到右，控制信号从左上到右下，反馈环路清晰绕行。
4. 少交叉：连线不穿越模块，不重叠标签，不出现无意义折返。
5. 接口稳定：顶层只暴露真实输入输出，内部调试量不要随意做成 Outport。
6. 可检查：模型生成后应能运行项目选择的 MAB/MAAB 或 Model Advisor 基础检查。

二、模型层级规范

1. 顶层只放接口、主要功能子系统和必要说明，不直接堆放大量算法块。
2. 算法子系统建议命名为 SS_FunctionName，例如 SS_CStaticCntReturn1。
3. 子系统深度通常控制在 2 到 4 层；超过 4 层时要确认是否过度拆分。
4. 可复用算法子系统可设置为 atomic subsystem，并按代码生成需求设置 reusable function。
5. Display、Scope、To Workspace 等验证用块不要混入生产算法子系统，建议放在测试模型或验证脚本里。

三、命名规范

命名要表达角色、含义和数据类型。建议使用英文、数字和下划线，避免空格、中文、特殊符号和自动生成名称。

对象	推荐格式	示例	说明
模型	lower_snake_case	c_static_cnt_return1_mab	短、稳定、能表达模型目的
子系统	SS_FunctionName	SS_CStaticCntReturn1	SS 表示 Subsystem
输入端口	U_SignalName	U_EngineSpeed	U 表示外部输入
输出端口	Y_SignalName	Y_ReturnValue	Y 表示外部输出
常量块	C_Meaning	C_ReturnValue	C 表示 Constant
延迟/状态	D_StateName	D_CntState	D 表示 Delay 或状态记忆
求和块	Sum_Result	Sum_CntNext	说明运算结果
开关块	Sw_Condition	Sw_EnableLimit	说明选择条件
信号线	sig_meaning_type	sig_cnt_next_s32	关键线必须命名

四、数据类型和采样时间规范

1. 常量必须设置数据类型，例如 int32(1)、uint16(0)、true。
2. 状态模块必须设置初值，初值数据类型应和状态数据类型一致，例如 int32(0)。
3. 整数运算应明确溢出策略；需要饱和时显式开启 Saturate on integer overflow。
4. 离散模型统一设置固定步长求解器；块级采样时间只在确有必要时显式设置。
5. 不同采样率之间必须使用 Rate Transition 或明确的接口子系统，避免隐式速率转换。

五、布局规范

1. 主数据流从左到右，控制信号从上到下或左上到右下。
2. 模块之间至少保留 60 到 100 像素，复杂模块保留更大间距。
3. 同一功能链路上的模块水平居中，并列分支纵向对齐。
4. 反馈线从输出端绕到输入端，形成清晰矩形回路，不贴着模块边缘。
5. 信号标签靠近源端或主水平线段，不能压在线、模块或其它文字上。
6. 注释只写模型意图、关键假设和约束，不解释显而易见的块功能。
7. 一屏内模块数量宜控制在 20 个以内；超过时优先拆分子系统。

六、模块使用规范

场景	推荐模块	注意事项
常量输出	Constant	必须设置值、数据类型、采样时间策略
上一拍状态	Unit Delay / Delay	初值显式设置，状态信号命名
加减运算	Add	Inputs 参数要明确，输出类型按需求设置
乘除缩放	Gain / Product	避免在 Gain 中隐藏复杂表达式
条件选择	Switch / Multiport Switch	条件阈值、数据类型和默认分支明确
逻辑判断	Relational Operator / Logical Operator	布尔信号名称要体现 is、has、enable 等含义
类型转换	Data Type Conversion	转换原因应通过名称或注释体现
复杂流程	Stateflow	仅在状态机语义明确时使用
复杂数学	MATLAB Function	仅在基本块表达成本过高时使用，并保证可代码生成

七、连线规范

1. 关键信号必须命名，名称体现物理含义或算法含义，不使用 signal1、tmp、x。
2. 同一信号的分支应从一个清晰分叉点引出，避免链式跨图分叉。
3. 跨越较远距离的信号优先使用 Goto/From 或 Bus，但不得滥用隐藏数据流。
4. 线段尽量水平或垂直，避免斜线、短碎线和贴边走线。
5. 反馈线必须留出足够空间，标签不能和主数据流标签重叠。
6. 禁止未连接端口、悬空线、无名大范围跨越线。

八、给 AI 的建模提示词模板

可以把下面这段作为生成 Simulink 模型时的基础约束：

请根据以下 C/算法描述生成 Simulink 模型。要求：
1）顶层只包含一个算法子系统和真实输入输出端口；
2）使用 MAB/MAAB 风格命名；
3）所有常量、状态和输出显式设置数据类型；
4）主数据流从左到右，反馈线绕行且信号标签不重叠；
5）关键信号命名为 sig_meaning_type；
6）不要在算法子系统内放 Display、Scope、To Workspace；
7）生成后运行仿真断言和 Model Advisor 基础检查，并给出报告路径。

九、AI 建模后自动检查清单

1. 功能等效：仿真输出和源代码/需求一致，关键边界条件已验证。
2. 顶层接口：只包含真实输入输出，不暴露内部调试信号。
3. 命名：模型、子系统、端口、模块、信号均无默认名称。
4. 数据类型：常量、状态、输出和关键运算类型明确。
5. 采样时间：固定步长设置正确，无无意的继承/多速率问题。
6. 布局：左到右、少交叉、标签不重叠、反馈清晰。
7. 模块选择：基本块优先，MATLAB Function/Stateflow 使用有充分理由。
8. 连线：无悬空线、无未连接端口、分支点清晰。
9. Model Advisor：项目要求的 MAB/MAAB 检查无失败，警告有解释或修正。
10. 代码生成：目标为代码生成时，模型可成功生成代码或通过代码生成前检查。

十、一个简单例子：static cnt++ / return 1

对于下面这段 C 代码：

1. 
   
2. static int cnt = 0;
   
3. cnt++;
   
4. return 1;
   

复制代码

推荐建模方式：

1. 使用 D_CntState 的 Unit Delay 表示 static int cnt，初值设置为 int32(0)。
2. 使用 C_CntIncrement 的 Constant 表示增量 int32(1)。
3. 使用 Sum_CntNext 计算 sig_cnt_next_s32 = sig_cnt_current_s32 + sig_cnt_increment_s32。
4. 将 sig_cnt_next_s32 反馈到 D_CntState 输入，形成下一拍状态。
5. 使用 C_ReturnValue 输出 int32(1)，连接到 Y_ReturnValue。
6. 如果原函数接口只返回 1，cnt 不应作为顶层 Outport；验证时用日志或测试框架观察内部信号。

十一、不推荐做法

1. 默认块名 Constant1、Add2：审查者无法快速理解模型，应改为 C_ReturnValue、Sum_CntNext 等。
2. 所有信号不命名：检查和调试困难，关键接口、状态、分支和反馈线必须命名。
3. 布局完全依赖自动路由：容易出现线交叉、标签重叠，应先定坐标，再连线，最后少量自动整理。
4. 算法中混入 Display/Scope：生产模型和验证模型边界不清，应放在测试模型或脚本中。
5. 用 MATLAB Function 包住简单逻辑：可读性和可检查性下降，简单加减、比较、选择、延迟优先用基本块表达。
6. 内部状态暴露为顶层输出：会改变接口语义，应使用信号日志或测试 harness 观察内部状态。

十二、推荐的 Model Advisor 基础检查

不同 MATLAB 版本和项目配置中的检查集名称可能不同。若安装 Simulink Check，可以至少运行以下基础检查作为 AI 建模后的快速门禁：

检查 ID	用途
mathworks.jmaab.db_0043	检查模型字体设置
mathworks.jmaab.db_0097	检查信号标签位置，防止标签重叠或不可读
mathworks.jmaab.db_0112	检查索引模式一致性
mathworks.jmaab.jc_0201	检查子系统名称
mathworks.jmaab.jc_0211	检查端口模块名称

建议把这些检查和项目正式 MAB/MAAB 配置文件结合使用。AI 生成模型后，至少应输出仿真结果、检查通过数量、警告数量、失败数量和报告路径。

总结

AI 建模要真正进入工程工作流，不能只追求“能生成一个能跑的模型”，还要让模型具备可读性、可审查性和可维护性。对 AI 来说，越明确的命名、布局、模块和连线约束，越容易生成接近工程规范的 Simulink 模型。

下载：