building-simulink-models

构建模型

所有结构性更改均使用 model_edit——包括 Simulink、System Composer、Simscape 和 Stateflow 图表内部结构

适用场景

• 在模型中添加、连接、删除或替换模块
• 配置模块参数、信号属性或模型设置
• 创建或编辑 Stateflow 图表内部结构（状态、转换、连接点、数据、事件、消息、函数）
• 构建 System Composer 架构模型
• 连接 Simscape 物理连接

不适用场景

• 查询参数值 → 使用 model_query_params
• 将变量引用解析为数值 → 使用 model_resolve_params

库与策略前置条件 — 阻断关卡

首先执行此操作——在进行任何其他工具调用之前评估结果。 不要向用户说明关卡检查；根据结果静默继续。

调用 library.settingsLookup() 检查自定义库配置。它会返回一个包含已解析绝对路径的结构体：

• found — 是否找到了库文件（satk-libraries.json 或旧版 reuse-libraries.json）
• enabled — 是否已配置自定义库
• gatePass — 关卡是否满足（可以继续构建）
• kgIndexPath — library-kg/index.md 的绝对路径
• librariesPath — 库文件的绝对路径
• policyPath — block-policy.json 的绝对路径
• dataRoot — 包含 .satk/ 的目录的绝对路径

解读结果：

• found: false → 未配置自定义库。使用标准 Simulink 模块继续操作。
• gatePass: true, found: true → 阅读 kgIndexPath 以查找模块，然后制定计划并编辑。
• gatePass: false → 调用 setup-custom-libraries 填充知识索引。

显示每项检查及其结果的有效说明，而不是仅陈述关卡通过或失败。

关卡通过之前，不得开始读取、规划或编辑模型。

工作流

0. 确保库与策略前置条件满足： 参见上方的阻断关卡。关卡通过之前不得继续。
1. 查找库模块： 列出计划使用的每种模块类型，搜索 .satk/library-kg/index.md 及相关类别页面，查找匹配的库模块。
2. 先读取： 对目标范围使用 model_read，获取模块 ID 并了解现有拓扑结构。
3. 规划数据流： 对于复杂编辑，先勾勒输入 → 操作 → 输出，再将其映射到步骤 1 和步骤 2 中确定的模块。
4. 编辑： 使用 model_edit，每次操作限定在一个子系统层级内。
5. 验证： 对该范围使用 model_read，确认结构符合预期。
6. 检查连接： 完成某个范围内的所有编辑后，运行 model_check，检查未连接的端口或悬空连线。修复所有严重级别为 error 的问题。

如果 model_edit 返回 status: partial： 立即同时运行 model_read 和 model_check——不要等到所有编辑完成后再运行。

使用 ref 链接操作

使用 ref 为模块命名，并在同一次调用的后续操作中使用 #ref 引用该模块：

[{"op": "add_block", "type": "Gain", "name": "MyGain", "ref": "g1"},
 {"op": "connect", "target": "blk_5.y1 -> #g1.u1"}]

在 SF 范围内，#ref 引用不带端口——不要添加 .y1/.u1 后缀（参见 references/stateflow.md）。

响应中的 created 映射会显示 ref → blk_id（在 SF 范围内为 ref → sf_X）。在后续调用中，请使用返回的 ID——#ref 仅在单次调用中有效。

防护措施

• 切勿根据 model_overview 或 model_read 中显示的名称手动构造模块路径字符串。模块名称可能包含不可见换行符和尾随空格，导致 hilite_system、open_system 和 get_param 失败。应改为根据 blk_X ID 解析路径：

  % blk_42 → use the number after "blk_" as the SID
  blockPath = Simulink.ID.getFullName('<ModelName>:42');
  hilite_system(blockPath)
  open_system(blockPath)
  get_param(blockPath, 'BlockType')
  

• 除非用户明确要求，否则不要调用 Simulink.BlockDiagram.arrangeSystem 或使用 set_param 调整模块位置。model_edit 内置自动布局引擎，会在每次调用后自动运行。
• 始终向 model_edit 传递 layout_mode。在填充空作用域（新模型根节点或新建的子系统）时，使用 "full"，以获得最佳模块排列效果。在已有模块的作用域中添加模块时，使用 "incremental"（保留现有位置）。
• 每次 model_edit 调用只在一个域中运行（Simulink、System Composer 或 Stateflow），具体由作用域决定。要添加 Chart 模块并填充其内容，请分两次调用：第一次使用 SL 作用域添加 Chart 模块，第二次使用 SF 作用域填充内部内容。两次调用之间使用 model_read 查找图表的 sf_X 作用域 ID。
• 使用含义明确的变量名（例如 Kp_SpeedController），不要使用硬编码的数值。请在模型工作区或 .m 初始化脚本中定义变量。
• 不要通过 evaluate_matlab_code 配合 set_param/add_block 绕过 model_edit —— 这会跳过自动布局、撤销跟踪和错误恢复
• 打开尚未打开的模型或创建新模型时，除非用户明确提出其他要求或该模型是库，否则使用 open_system，而不是 load_system。这样用户就能实时看到编辑过程。

命名约定

模块、信号和变量应优先使用适合代码生成的名称：

• 仅使用：a-z、A-Z、0-9、下划线（_）
• 不要以数字开头
• 不要使用开头或结尾的下划线，也不要使用连续下划线
• 名称尽量少于 32 个字符（某些代码生成目标要求如此）

模块类型

在 type 字段中使用模块的显示名称。不要构造或猜测库路径。

• **自定义库模块（来自 satk-libraries.json）：**同时传递 type 和 ReferenceBlock 字段。将 type 设为模块的显示名称，并将 ReferenceBlock 设为库知识图谱（KG）中的完整库路径。

• **工具箱知识库模块（来自 activeToolboxes）：**与自定义库模块的用法完全相同——使用库知识图谱中工具箱类别页面提供的 type 和 ReferenceBlock 字段。

• **内置 Simulink 模块：**直接使用 BlockType：Gain、Sum、Constant、Integrator、SubSystem、Scope

• **库模块（Simscape、Aerospace、DSP、Communications 等）：**使用 Simulink 库浏览器中显示的名称：Voltage Source、Resistor、DC Motor、Solver Configuration、6DOF (Euler Angles)

• **如果 model_edit 返回 INVALID_TYPE：**使用 MATLAB 文档中的完整库路径（例如 ee_lib/Sources/Voltage Source）

[{"op": "add_block", "type": "In", "ReferenceBlock": "customLib_Portsandsubsystems/In", "name": "Voltage", "ref": "v1"},
 {"op": "add_block", "type": "Gain", "ReferenceBlock": "customLib_Mathoperations/Gain", "name": "Kp", "ref": "g1"},
 {"op": "add_block", "type": "Add", "ReferenceBlock": "customLib_Mathoperations/Add", "name": "SumErr", "ref": "s1"},
 {"op": "add_block", "type": "Out", "ReferenceBlock": "customLib_Portsandsubsystems/Out", "name": "Output", "ref": "o1"}]

[{"op": "add_block", "type": "Voltage Source", "name": "V1", "ref": "v1"},
 {"op": "add_block", "type": "Resistor", "name": "R1", "ref": "r1"},
 {"op": "add_block", "type": "Electrical Reference", "name": "Gnd", "ref": "gnd"},
 {"op": "add_block", "type": "Solver Configuration", "name": "Solver", "ref": "sc"}]

审查关卡

完成某个作用域的所有编辑后，请验证：

• model_check 没有严重级别为 error 的问题（端口未连接、线路悬空）
• created 映射中所有 ref 名称都已解析为 blk_id ——后续调用中没有悬空的 #ref 引用
• 布局应用前，Stateflow 图表已通过 lint 检查（使用 checks='["stateflow_lint"]' 调用 model_check）
• 如果任何时候 model_edit 返回了 status: partial，请通过 model_read 确认该作用域在结构上已完整

特定领域规则

处理以下领域时，请先阅读相应的参考文件，再进行编辑：

• Stateflow 图表 -> references/stateflow.md — model_edit 可直接编辑图表内部内容。将范围限定为某个图表（sf_X 或图表 blk_X），并使用相同的操作：使用 add_block 添加 SF 元素，使用无端口的 connect 添加转换，使用 configure 设置属性。参考文件介绍了 SF 专用语法、作用域、LabelString 模式，以及 SL+SF 两步工作流。
• System Composer 架构模型 -> references/system-composer.md — 使用 systemcomposer.createModel 创建模型，然后使用 model_edit。组件使用 type: "SubSystem"，端口使用 Bus Element 块。参考文件介绍了组件创建、端口连线和行为模型生成。
• Simscape 物理模型 -> references/simscape.md — 物理连接使用双向 <-> 语法。参考文件介绍了连接语义、端口模式和初始目标变量。

---

Copyright 2026 The MathWorks, Inc.

---