让 AI Agent 直接操作 Simulink：Simulink Agentic Toolkit MCP 配置踩坑全记录

本文记录了将 Simulink Agentic Toolkit 的 MCP 服务接入 AI Agent（Hermes Agent），实现 AI 直接调用 MATLAB/Simulink 的完整过程。包括环境配置、函数注册修复、踩坑排查，以及用一个三相逆变器仿真实例验证效果。

一、什么是 Simulink Agentic Toolkit

Simulink Agentic Toolkit 是 MATLAB 官方提供的 MCP（Model Context Protocol）工具包，让 AI Agent 可以通过标准化协议直接调用 MATLAB/Simulink 的功能：

• 模型读取（model_overview、model_read）
• 参数查询（model_query_params、model_resolve_params）
• 模型编辑（model_edit、model_check）
• 代码执行（evaluate_matlab_code、run_matlab_file）

工作原理：

AI Agent  ←→  MCP 协议  ←→  matlab-mcp-server.exe  ←→  MATLAB 引擎

AI Agent 发送 JSON-RPC 请求，MCP 服务器翻译成 MATLAB 命令执行，返回结果。

二、环境准备

2.1 工具清单

工具	版本	用途
MATLAB	R2024b	仿真引擎
Simulink Agentic Toolkit	0.2.0 (R2026a)	MCP 工具包
matlab-mcp-server.exe	-	MCP 服务器
Hermes Agent	-	AI 编程助手（MCP 客户端）

2.2 安装 Simulink Agentic Toolkit

% MATLAB 命令窗口
cd('E:\matlab-toolkits\simulink')
satk_initialize

安装后的目录结构：

E:\matlab-toolkits\simulink\
├── tools\
│   ├── tools.json              % MCP 工具定义（函数名映射）
│   └── common\
│       ├── +sage\              % 命名空间函数（.p 加密文件）
│       │   ├── graph_read.p
│       │   ├── graph_query.p
│       │   └── graph_get_params.p
│       └── +sage\+internal\    % 内部依赖
├── satk_initialize.p           % 初始化脚本
└── bin\
    └── matlab-mcp-server.exe   % MCP 服务器

2.3 配置 AI Agent 的 MCP 连接

在 Hermes Agent 的配置文件中添加 MATLAB MCP 服务器：

# ~/.hermes/config.yaml
mcp_servers:
  matlab:
    command: "E:\\matlab-toolkits\\bin\\matlab-mcp-server.exe"
    args:
      - "--extension-file"
      - "C:\\Users\\xxx\\.matlab\\agentic-toolkits\\simulink\\tools\\tools.json"

⚠️ 关键注意：matlab-mcp-server.exe 是 Windows 程序，--extension-file 参数必须用 Windows 路径格式（C:\Users\...），不能用 WSL 路径（/mnt/c/...）。这个坑花了很久才定位到。

配置完成后重启 Agent，看到类似以下输出说明连接成功：

MCP server 'matlab' connected
14 MCP tools available: model_overview, model_read, model_query_params, ...

三、踩坑：函数注册完全失效

3.1 现象

MCP 连接成功，14 个工具都列出来了，但调用任何一个都报错：

错误: 未定义函数 'model_overview'

3.2 排查过程

第一步：检查 tools.json 的函数映射

{
    "name": "model_overview",
    "function": "model_overview",
    "signature": "model_overview(model, scope, detail)"
}

MCP 服务器会调用 model_overview 函数，但 MATLAB 中找不到这个函数。

第二步：查找实际函数位置

>> which sage.graph_read
E:\matlab-toolkits\simulink\tools\common\+sage\graph_read.p  % static method

实际函数在 sage 命名空间下，不在顶层。

第三步：尝试直接调用命名空间函数

>> sage.graph_read('Inverter3Phase', 'root', 0)
错误: 无法解析名称 'sage.internal.utils.SystemComposerUtils.getSystemComposerInfoFromPath'

函数内部依赖缺失！

第四步：检查内部依赖

>> dir('E:\matlab-toolkits\simulink\tools\common\+sage\+internal\')
+adapter    +cache    +expr    +graph    SAGEContainerCategory.p    SubgraphSource.p

>> dir('E:\matlab-toolkits\simulink\tools\common\+sage\+internal\+utils\')
未找到  ← 这就是问题！

+utils 目录完全缺失，导致 SystemComposerUtils、StateflowUtils 等类找不到。

3.3 根因分析

层级	问题
tools.json	映射 model_overview → model_overview，但顶层函数不存在
sage.graph_read	存在（.p 文件），但内部依赖 +utils 目录缺失
satk_initialize	有 autolayout 警告，没有正确注册顶层函数
版本兼容	Toolkit 是 R2026a，MATLAB 是 R2024b，内部 API 不兼容

核心问题：R2024b 的 MATLAB + R2026a 的 toolkit 版本不兼容，+utils 目录缺失导致内部函数链断裂。

3.4 解决方案

分两步修复：

第一步：创建缺失的 stub 文件

utilsDir = 'E:\matlab-toolkits\simulink\tools\common\+sage\+internal\+utils';
mkdir(utilsDir);

% SystemComposerUtils - 提供空的结构体返回值
fid = fopen(fullfile(utilsDir, 'SystemComposerUtils.m'), 'w');
fprintf(fid, [...
    'classdef SystemComposerUtils\n' ...
    '    methods(Static)\n' ...
    '        function result = getSystemComposerInfoFromPath(varargin)\n' ...
    '            result = struct();\n' ...
    '            result.isSystemComposer = false;\n' ...
    '        end\n' ...
    '    end\n' ...
    'end\n']);
fclose(fid);

% StateflowUtils - 返回 false
fid = fopen(fullfile(utilsDir, 'StateflowUtils.m'), 'w');
fprintf(fid, [...
    'classdef StateflowUtils\n' ...
    '    methods(Static)\n' ...
    '        function result = isSFSID(varargin)\n' ...
    '            result = false;\n' ...
    '        end\n' ...
    '    end\n' ...
    'end\n']);
fclose(fid);

第二步：创建原生 API 包装函数

既然 sage.graph_read 内部还有各种问题，不如直接用原生 Simulink API（get_param、find_system）重写顶层函数：

% E:\matlab-toolkits\simulink\tools\common\model_overview.m
function result = model_overview(model, scope, detail)
    % ⚠️ MCP 传参可能是 string 类型，必须转换
    if isstring(model), model = char(model); end
    if isstring(scope), scope = char(scope); end
    if isstring(detail), detail = char(detail); end
    
    if endsWith(model, '.slx')
        model = model(1:end-4);
    end
    
    if ~bdIsLoaded(model)
        load_system(model);
    end
    
    if nargin < 2 || isempty(scope) || strcmp(scope, 'root')
        scope = model;
    end
    
    blocks = find_system(scope, 'SearchDepth', 1, 'Type', 'block');
    result = struct();
    result.model = model;
    result.scope = scope;
    result.blocks = {};
    for i = 1:length(blocks)
        blk = struct();
        blk.name = blocks{i};
        blk.type = get_param(blocks{i}, 'BlockType');
        result.blocks{end+1} = blk;
    end
    result.block_count = length(result.blocks);
end

同样创建 model_read.m、model_query_params.m、model_resolve_params.m。

⚠️ 关键踩坑：string 类型处理

MCP 服务器传给 MATLAB 函数的参数可能是 string 类型（而非 char），这会导致很多内置函数报错。每个包装函数开头都必须加：

if isstring(model), model = char(model); end

验证：

>> which model_overview
E:\matlab-toolkits\simulink\tools\common\model_overview.m

>> model_overview('Inverter3Phase.slx', 'root', 'tree')
ans = 
    model: 'Inverter3Phase'
    block_count: 30

MCP 工具调用也恢复正常。

四、验证：用 AI Agent 搭建三相逆变器仿真

MCP 配置好后，用一个实际测试案例验证 AI Agent 能否完整操作 Simulink。

4.1 测试目标

让 AI Agent 自动搭建一个三相逆变器 Simulink 模型（不用 Universal Bridge），运行仿真并在 Scope 中显示波形。

4.2 AI Agent 的操作流程

通过 MCP 工具，AI Agent 执行了以下操作：

1. evaluate_matlab_code：检查可用的模块库

% 查找 Ideal Switch 模块
add_block('powerlib/Power Electronics/Ideal Switch', 'test/SW1');

2. run_matlab_file：运行 build_model.m 构建完整模型
3. model_overview：验证模型结构（30+ 个模块）
4. evaluate_matlab_code：运行仿真

sim('Inverter3Phase');
open_system('Inverter3Phase/Scope');

4.3 遇到的问题

问题	原因	解决方案
From Workspace 变量丢失	工作区变量被清除	改用 Sine Wave + MATLAB Function
IGBT 不导通	R2024b powerlib 兼容性问题	改用 Ideal Switch
电压测量极性反	LConn1/LConn2 极性与直觉相反	交换连接
boolean 类型不兼容	比较器输出 boolean，开关需要 double	加 Data Type Conversion
Scope 不显示	LayoutDimensions 默认 [1,1]	设为 [4,1]

4.4 最终效果

AI Agent 成功搭建了完整的三相逆变器仿真模型，Scope 显示四组正确波形：

1. 三相调制波（正弦波，120° 相移）
2. 六路 PWM 脉冲信号
3. 桥臂输出电压 uab（PWM 波形）
4. 滤波后输出电压（三相正弦波）

五、踩坑总结

MCP 配置相关

坑	现象	解决方案
tools.json 函数映射失效	model_overview 未定义	创建原生 API 包装函数
sage 内部依赖缺失	SystemComposerUtils 找不到	创建 stub .m 文件
string 类型传参	包装函数参数错误	每个函数开头加 if isstring(x), x = char(x); end
extension-file 路径格式	MCP 服务器启动失败	用 Windows 路径（C:\...），不用 WSL 路径

Simulink 搭建相关

坑	现象	解决方案
From Workspace 变量丢失	仿真报错	用原生 Simulink 源模块
powerlib IGBT 不导通	输出恒为 0	用 Ideal Switch 替代
电压测量极性	输出电压为负	LConn1=GND侧, LConn2=AC侧
boolean 不兼容	开关不响应	加 Data Type Conversion
Scope 布局	只显示 1 个图	设置 LayoutDimensions

六、经验总结

1. 版本兼容性是最大的坑：R2024b + R2026a toolkit 的组合需要手动修复。如果 toolkit 和 MATLAB 版本匹配，大部分问题不会出现。

2. stub + 包装是通用解法：当 .p 加密文件的内部函数链断裂时，创建 stub 文件（提供最小返回值）+ 原生 API 包装函数是最稳的方案。

3. MCP 传参格式要注意：MCP 服务器传给 MATLAB 的参数可能是 string 而非 char，每个包装函数都要处理。

4. 最简电路测试是王道：遇到 Simulink 模块行为异常时，不要在复杂模型里猜，先用最简电路（DC → 开关 → R → GND）隔离问题。

5. AI Agent + MCP 的价值：AI 可以快速迭代代码（改一行、跑一次、看结果），比手动拖拽 Simulink 模块效率高很多。但 AI 对 Simulink 底层行为的理解可能不准确，需要实测验证。

---

本文基于 MATLAB R2024b + Simulink Agentic Toolkit 0.2.0，不同版本的行为可能有差异。