dsh-matlab-mcp —— 让 Agent 真正动手操作 MATLAB 与 Simulink

dsh-matlab-mcp

让 DeepSeek Harness（DSH）的 Agent 直接动手操作 MATLAB 与 Simulink 的插件：执行 MATLAB 代码、运行 .m 脚本与单元测试、做代码静态检查、读写/查询/检查/仿真 Simulink 模型 —— 全部通过 MathWorks 官方 MATLAB MCP Server 完成，并注入 MATLAB / Simulink Agentic Toolkit 的专家技能。

这不是"在 MATLAB 里塞一个 AI"，而是反过来：MATLAB 作为 MCP 服务器被 DSH 调用。DSH 侧只做三件事：挂载官方 MCP 服务器、一键供给官方制品、把官方技能注册进技能目录。

你 ──自然语言──▶ DSH Agent
                   ├─ 工具  mcp__matlab__<tool>  ──stdio MCP──▶ MATLAB MCP Server(官方 exe) ──▶ MATLAB / Simulink
                   ├─ 技能  matlab-* / simulink-*  ── 来自两个官方 Agentic Toolkit
                   └─ 系统提示词注入（调用规范、超时、图窗导出、Simulink 工具优先级）

特性

能力	说明
执行 MATLAB 代码	`mcp__matlab__evaluate_matlab_code`：给一段代码 + 工作目录，返回命令窗口输出
运行脚本 / 测试	`run_matlab_file`、`run_matlab_test_file`（MATLAB 单元测试框架）
静态检查	`check_matlab_code`：不执行代码，报出风格/潜在错误/弃用函数/性能问题
工具箱探测	`detect_matlab_toolboxes`：列出已安装产品与版本
Simulink 模型操作	`model_overview`、`model_read`、`model_query_params`、`model_resolve_params`、`model_edit`、`model_read_diagnostics`、`model_check`、`model_scan`、`model_test`
专家技能	按组注册 MathWorks Agentic Toolkit 技能（调试、代码评审、Live Script、建模仿真最佳实践…），用标准 `skill` 工具按需加载
打开 MATLAB 按钮	聊天主界面标题栏有一个「打开 MATLAB」按钮，点一下弹出 MATLAB 桌面窗口；`auto`/`existing` 模式下打开的是共享会话，你可以直接在窗口里看 Agent 干活
一键安装	设置卡「一键安装 / 修复」：自动下载官方二进制、MATLAB 端工具箱、两个技能仓，并注册 Simulink 工具包路径。全程不需要你手动打开 MATLAB
零手动	默认 `sessionMode=new`：插件自己启动 MATLAB（桌面可见），你只需要用自然语言下命令
网络兜底	直连 GitHub 失败时可选用镜像（默认关闭，开启后仅在直连失败时启用，并校验 PE/ZIP 魔数）
进程卫生	插件卸载时按父子进程归属关闭它自己启动的 MATLAB，绝不动你手动打开的那个
中英双语 UI	设置卡与文档均中英对齐

架构与上游

本插件不重造 MCP 桥，全部使用 MathWorks 官方制品：

上游	作用	本插件的角色
`matlab/matlab-mcp-server`（官方 Go 二进制）	MCP 服务器本体，被 DSH 的 `@deepseek-ai/dsh-mcp-client` 以 stdio 方式挂载	下载、校验、缓存、构建启动参数与环境变量
`MATLABMCPServerToolbox.mltbx`（同上 release）	提供 `shareMATLABSession()`，用于接管已有 MATLAB 会话	下载并调用 `matlab -batch` 自动安装
`matlab/matlab-agentic-toolkit`	24 组 MATLAB 技能	同步到本地缓存，注册为 DSH 技能
`matlab/simulink-agentic-toolkit`	11 组 Simulink 技能 + 9 个 MCP 扩展工具（`tools/tools.json`）	同步、注册技能、`addpath`+`savepath` 注册工具函数路径、把 `tools.json` 作为 `--extension-file` 传给 MCP 服务器

为什么需要一个 DSH 插件？ 因为 DSH 的官方 MCP 客户端 @deepseek-ai/dsh-mcp-client 只桥接 tools（官方文档："This package bridges tools only; MCP resources and prompts are unsupported"）。所以：工具走 MCP，领域知识（官方 MCP resources + Agentic Toolkit 技能）改由 DSH 的技能系统注入 —— 这正是本插件的价值。

环境要求

项目	要求	本机实测
MATLAB	R2021a 或更高（Simulink 工具需 R2023a+，`model_test` 需 Simulink Test）	R2025b（25.2.0.2998904），含 Simulink / Stateflow / Simulink Test 等 110 个产品
DSH	0.1.5 及以上（插件按 0.1.5 / 0.2 两代设置接缝自适应）	0.2.0 系列
Node.js	`^22.19.0
网络	首次安装需访问 GitHub；受限网络可开启镜像开关	直连不稳，镜像可用

安装

从 npm 安装（最省事）

cd "$env:DSH_HOME\profiles\<你的 profile>"
pnpm add dsh-matlab-mcp
# 再把 "dsh-matlab-mcp" 加进该 profile package.json 的 dsh.profile.bundles，重启 DeepSeek Harness
# 然后 设置 → MATLAB / Simulink MCP → 点「一键安装 / 修复」

插件行不用手写：包内自带 cordis.patch.yml（dsh.bundle.patch），DSH 组合时会自动插入。dependencies 为空、bundle 自包含 —— 安装无需构建，也无需任何编译工具链。

从 git clone 安装（可离线 / 想改代码时用）

git clone https://github.com/MCviseron/dsh-matlab-mcp.git D:\dsh-matlab-mcp
node D:\dsh-matlab-mcp\scripts\install.mjs     # 加 --dry-run 可先预演

不需要 pnpm install，也不需要构建：仓库自带 lib/，且宿主 bundle 把所有运行时依赖（@deepseek-ai/dsh-mcp-client 等）都打进去了，只依赖 Node 内置模块。安装器只做接线：

在 %DSH_HOME% 建 matlab-mcp-plugin 联接指向仓库（同盘路径，规避 pnpm 跨盘 link:D:/... 生成无效联接的问题）；
给每个存在的 profile 写 dependencies / dsh.profile.bundles / cordis.patch.yml；
直接建立（或修复）node_modules 里的联接 —— 有 pnpm 时顺带跑一次 pnpm install，没有 pnpm 也能装；顺带修复其它本地插件失效的 link: 联接；
打印后续步骤。

跑完重启 DeepSeek Harness，再做下面「一键安装运行时」。

兼容性说明：lib/ 随仓库提交，CI（.github/workflows/check.yml）会在每次 push 时重新构建并校验 lib/ 与 src/ 一致、且 bundle 里不再有 @deepseek-ai/* 外部 import —— 所以「提交构建产物」不会变成悄悄过期的坑。

手动接线（不用脚本）

不想用脚本就手工接线（同样不需要构建，仓库自带 lib/）：

# 1) 在 DSH 主目录建一个指向本仓库的联接
cmd /c mklink /J "$env:DSH_HOME\matlab-mcp-plugin" "D:\Program\DSH-Plugin-Class\dsh-matlab-mcp"

# 2) 在 profile 的 package.json 里加依赖与 bundle
#    "dependencies": { "dsh-matlab-mcp": "link:C:/Users/<你>/.dsh/matlab-mcp-plugin" }
#    "dsh.profile.bundles": [ ..., "dsh-matlab-mcp" ]

# 3) 在 profile 的 cordis.patch.yml 里加一行（见下）
# 4) 建立联接（有 pnpm 时用 pnpm install；没有 pnpm 就直接 mklink）
cd "$env:DSH_HOME\profiles\web"; pnpm install
# 若发现某些插件的 node_modules 联接失效（指向 C:\...\profiles\<p>\D:\...），用 mklink /J 逐个修复

cordis.patch.yml 追加：

- id: matlab-mcp
  name: dsh-matlab-mcp
  config:
    enabled: true
    sessionMode: new
    displayMode: desktop
    simulinkTools: true
    toolCallTimeoutMs: 600000
    allowMirrorDownload: false

然后重启 DeepSeek Harness（新增 bundle 需要重新读取插件清单）。

一键安装运行时（在 DSH 设置里）

打开 设置 → MATLAB / Simulink MCP，点 「一键安装 / 修复」。它会：

下载 matlab-mcp-server-<平台> 到 $DSH_HOME/matlab-mcp/bin/（校验 PE 魔数 + --version）；
下载 MATLABMCPServerToolbox.mltbx 并用 matlab -batch 自动安装（拿到 shareMATLABSession）；
git clone（失败则 zip 兜底）两个 Agentic Toolkit 到 $DSH_HOME/matlab-mcp/toolkits/；
addpath(genpath(<simulink-toolkit>/tools)) + savepath，让 9 个 Simulink 工具函数在每个 MATLAB 会话里可见；
重新挂载 MCP 客户端 —— 工具以 mcp__matlab__* 出现在会话里。

若直连 GitHub 失败，会返回 MIRROR_DISABLED 错误并提示你打开「允许镜像下载」，不会静默走第三方。

制品获取（镜像 / 本地目录）

插件默认直连 GitHub；国内网络可配置镜像或本地制品目录（两者都可选，默认关闭）：

allowMirrorDownload: true
downloadMirror: "https://你的镜像/{path},https://gh-proxy.com/{url}"   # {path} 换主机式 / {url} 前缀式，逗号分隔按序回退
localAssetsDir: "D:\matlab-mirror"                                   # 命中即直接复制、零网络请求（优先级：本地 → 镜像 → 直连）

服务器侧的部署工具不在插件里：自建静态镜像、nginx 反代配置生成、备案与端口注意事项，见 deploy/。那份工具与插件运行无关，npm 包也不包含它（files 字段里没有 deploy/）。

配置项

字段	默认	说明
`enabled`	`true`	关闭则卸载 MCP 客户端，不再注册 `mcp__matlab__*`
`announceToAgent`	`true`	把 MATLAB 使用规范注入系统提示词
`matlabRoot`	`""`	留空 = 自动探测最新安装（本机探测到 `D:\MATLAB\2025b`）
`sessionMode`	`new`	`new` 自启 / `auto` 优先接管已共享会话 / `existing` 只连已共享会话
`displayMode`	`desktop`	`desktop` 显示 MATLAB 桌面；`nodesktop` 不显示（更快）
`initialWorkingFolder`	`""`	留空 = `$DSH_HOME/matlab-mcp/workspace`
`simulinkTools`	`true`	挂载 9 个 Simulink 工具，并在安装时注册工具包路径
`skillsEnabled`	`true`	把两个 Agentic Toolkit 的技能注册进技能目录
`skillGroups`	`""`	逗号分隔的技能组；留空 = 默认组；`none` = 全部关闭
`toolCallTimeoutMs`	`600000`	单次工具调用超时（10 分钟）；上限 30 分钟
`allowMirrorDownload`	`false`	默认关闭；直连失败时才用镜像下载官方制品
`localAssetsDir`	`""`	本地制品目录（`mirror-assets.mjs` 产出的那种布局）。命中即直接复制、零网络请求；优先级本地 → 镜像 → 直连
`downloadMirror`	`https://gh-proxy.com/{url},https://gh.llkk.cc/{url},https://ghproxy.net/{url}`	镜像列表（逗号分隔，按顺序回退）。模板：`{url}` 前缀式、`{path}` 换主机式，老的纯前缀写法仍兼容。开启开关后镜像优先、直连兜底
`telemetry`	`false`	关闭时传 `--disable-telemetry=true` 给 MCP 服务器
`shutdownMatlabOnUnload`	`true`	插件卸载时关闭由本插件启动的 MATLAB（按父子进程归属判定）

工具清单

完整参数与返回说明见 docs/tools.md。会话中看到的名字带 mcp__matlab__ 前缀。

内置 5 个：detect_matlab_toolboxes、check_matlab_code、evaluate_matlab_code、run_matlab_file、run_matlab_test_file

Simulink 扩展 9 个（来自 Simulink Agentic Toolkit 的 tools/tools.json）：model_overview、model_read、model_query_params、model_resolve_params、model_edit、model_read_diagnostics、model_check、model_scan、model_test

技能注入

技能来自两个官方仓的 skills-catalog/<group>/<skill>/SKILL.md，通过 ctx.skills.registerProvider 注册为 DSH 技能，用标准 skill 工具按需加载（不占用常驻上下文）。默认组（32 个技能）：

组	技能数	内容
`matlab-core`	6	调试、代码评审、Live Script、文档查询、产品安装/列举
`matlab-programming`	1	带参数校验的健壮函数
`matlab-software-development`	11	测试、性能/内存优化、文档、工具箱打包、工程与构建计划
`matlab-data-import-and-analysis`	4	表格/时间表/大数据方案、凭证安全
`model-based-design-core`	11	建模、仿真、需求草稿、模型清理、缺陷报告
`simulink-simulation`	3	仿真输入、SDI 运行、批量仿真

skillGroups 填其它组名即可启用（例如 matlab-app-building、ai-and-statistics、verification-validation-and-test…）。技能内容是 MathWorks 官方原文，本插件不修改。

使用示例

安装完成后，直接用自然语言即可，例如：

「用 MATLAB 算一下这个矩阵的特征值，并把结果写成 csv 放到当前工程」
「画一张阻尼比 0.1~1.0 的阶跃响应对比图，导出 PNG 给我看」
「在 Simulink 里建一个 PID 控制二阶系统的模型，跑 10 秒仿真，给我超调量和稳态误差」
「检查我工程里所有 .m 文件的代码规范问题」

Agent 会自动：先 detect_matlab_toolboxes 探测 → 需要时加载对应技能 → 用 evaluate_matlab_code/run_matlab_file 执行 → 需要看图就先 exportgraphics 导出 PNG 再自己看 → Simulink 场景优先用 model_* 工具。

排障

现象	原因与处理
错误码 `MIRROR_DISABLED`	直连 GitHub 失败且镜像未开启。设置里打开「允许镜像下载」后重试
启动日志：`matlab-mcp (dsh-matlab-mcp): failed to import`	插件入口加载失败。① 你的仓库副本是 0.2.x 或更早（那时 `lib/` 不进仓库）→ `git pull` 到 0.3.0+（自带 `lib/`）；② profile 里的 `node_modules` 联接失效（见下一条）；③ 自己改过 `src/` 却没重新 `pnpm build`。跑 `node scripts/install.mjs` 可一次处理接线问题
启动日志：多个插件同时 `failed to activate` / `failed to import`	profile 的 `node_modules` 里 `link:` 联接坏了（pnpm 对 `link:D:/...` 跨盘路径会生成无效联接，指向 `C:\...\profiles\<p>\D:\...`）。用 `mklink /J <profile>\node_modules\<插件名> <真实目录>` 逐个修复，或直接重跑 `node scripts/install.mjs`（它会统一修复）
客户端直接崩溃并生成 `crash-*-host.log`，里面有 `spawn ...matlab-mcp-server-windows-x64.exe ENOENT`	`ENOENT` 不代表文件不存在 —— libuv 在 `cwd` 不存在时也报这个错。0.4.0 起插件会自动创建工作目录并在挂载前预检二进制；若你还在 0.3.x：升级，或先手工 `mkdir "%USERPROFILE%\.dsh\matlab-mcp\workspace"` 再重试。这也是 DSH 侧 `dsh-mcp-client` 未捕获 spawn 错误导致宿主退出的健壮性缺陷
插件突然不加载 / 工具消失（重启后才出现）	先查 profile `package.json` 的 `dsh.profile.bundles` 里还有没有这个插件名。DSH 插件管理器的「卸载」会在 pnpm 步骤失败之前先删掉 bundle 记录与依赖，于是插件静默消失、而错误只留在 `.plugin-manager\logs\operation-*\pnpm.log`。补回 `bundles` 里那一项（位置无所谓）+ 恢复依赖后 `pnpm install` 即可
卸载/安装插件时报 `ERR_PNPM_UNEXPECTED_STORE`（…linked from …store\v10 … pnpm now wants …store\v11）	profile 的 `node_modules` 是全局 pnpm 10.x 装的（`node_modules\.modules.yaml` 记着 `storeDir`），而 DSH 运行时自带 pnpm 11.x（store 格式 v11）→ 两者对 store 版本要求打架。二选一：① 临时——在 profile 目录用与树匹配的 pnpm 操作（`pnpm store path` 会正好指向 `.modules.yaml` 里那个 store）；② 彻底——用运行时 pnpm 把整棵树重链到 v11： `cd %USERPROFILE%\.dsh\profiles\desktop` `node "%USERPROFILE%\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.mjs" install --no-frozen-lockfile --config.confirmModulesPurge=false` （无 TTY 时 pnpm 会因「要清空 `node_modules`」而中止，必须给 `confirmModulesPurge=false`；`CI=true` 会顺带打开 `--frozen-lockfile`，所以要么别设 CI，要么显式 `--no-frozen-lockfile`。整棵树重链后，该 profile 里请只用运行时 pnpm 或 DSH 界面，否则全局 pnpm 10 会反向报同一个错）
安装极慢或卡在下载	点设置卡「镜像测速」，再点「把最快的排到最前」。镜像存活期常常只有几小时（实测 `ghproxy.net` 数小时内从可用掉到 0.03 MB/s），默认列表会过期
`not-provisioned` / 没有 `mcp__matlab__*` 工具	还没安装运行时。点设置卡「一键安装 / 修复」
首次调用很慢（20–45 秒）	MATLAB 冷启动，属正常；之后再调用是秒级
工具调用超时	调大 `toolCallTimeoutMs`，或把长任务改成写脚本 + 轮询结果文件
Simulink 工具报找不到函数	一键安装的第 4 步没跑（`simulinkTools` 关闭时不会注册路径）；开启后重跑安装
你手动打开的 MATLAB 被关掉了	不应该发生：只关闭父进程链上属于本插件 MCP 服务器的 MATLAB。若出现请提 issue
想看日志	MCP 服务器日志在 `$DSH_HOME/matlab-mcp/logs/`；设置卡「刷新状态」显示二进制版本、MATLAB 路径、工具箱/技能仓是否就位

卸载

设置卡关闭 enabled（立刻卸载 MCP 客户端、注销技能与工具）；
从 profile 的 package.json（dependencies + dsh.profile.bundles）与 cordis.patch.yml 移除 dsh-matlab-mcp 行，pnpm install，重启 DSH；
删除 $DSH_HOME\matlab-mcp（缓存，约 70 MB，含二进制、工具包、技能仓）；
如需彻底清理 MATLAB 侧：在 MATLAB 里 matlab.addons.toolbox.uninstallToolbox(...) 卸载 MATLAB MCP Server Toolbox，并用 rmpath 去掉 Simulink 工具包路径（savepath）。

验收

逐项验收清单与原始证据（命令输出、工具返回、截图）见 docs/acceptance-2026-10-14.md。

#	验收项	通过标准
A	静态质量	`pnpm typecheck && pnpm test && pnpm build` 全绿；插件加载无报错
B	桥连通	`mcp__matlab__detect_matlab_toolboxes` 返回 R2025b + Simulink
C	执行代码	自然语言算 `sum(1:10)`=55；画图导出 PNG 并视觉复核
D	Simulink 仿真	脚本建模型 + `sim()` 取仿真结果，全程无人工点击
E	Simulink 工具	`model_overview`/`model_read`/`model_scan` 返回结构化结果
F	技能注入	技能出现在目录、`skill()` 可加载、行为符合技能指引
G	零手动	删缓存后一键安装即可复现 B–F
H	稳定性	安装幂等、卸载无残留、无孤儿 MATLAB 进程
I	文档	本 README、`docs/tools.md`、CHANGELOG、验收记录、可复跑验证脚本 `scripts/`

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # 5 个纯逻辑测试套件（配置解包/下载策略/路径探测/启动参数/技能解析）
pnpm build       # esbuild → lib/index.js（宿主）+ lib/client.js（浏览器设置卡）
pnpm check       # 三者串跑

源码结构：

文件	职责
`src/index.ts`	宿主半边：配置 schema、挂载 MCP 客户端、系统提示词段、技能提供者注册、设置接缝适配
`src/provision.ts`	一键供给：二进制/工具箱/技能仓下载与安装、Simulink 路径注册、`runSetup`
`src/download.ts`	下载策略（直连→镜像、镜像默认关闭）、原子写入、魔数校验
`src/paths.ts`	缓存布局、平台制品名、MATLAB 安装探测与选择
`src/server-args.ts`	MCP 服务器启动参数与子进程环境（Windows `windir`/`PATH` 显式传递）
`src/selftest.ts`	最小 MCP stdio 客户端（设置卡「测试连接 / 深度自检」用）
`src/skills-catalog.ts` + `src/skills-provider.ts`	技能发现/解析/过滤 + DSH `SkillProvider`
`src/matlab-processes.ts`	按父子进程归属回收本插件启动的 MATLAB
`src/routes.ts`	宿主 HTTP 路由：status/setup/test/reconnect/diagnostics + 设置桥
`src/client/*`	浏览器半边：设置卡、文案（中/英）、设置命名空间读写

版本与变更

语义化版本；每次发布打 tag（v0.1.0）。
变更记录见 CHANGELOG.md（Keep a Changelog 格式）。
与 DSH 的兼容性：设置接缝、ctx.inject(['tools']) 挂载、volatile 配置解包均按 0.1.5 / 0.2 两代自适应，详见 CHANGELOG。

许可证与商标

本插件代码：Apache-2.0（见 LICENSE）。
不随仓库分发任何 MathWorks 制品：二进制、.mltbx、技能文本都在安装时从 MathWorks 官方 GitHub 下载，且不修改其内容。上游许可见各自仓库（matlab-agentic-toolkit / simulink-agentic-toolkit 为 MathWorks 许可，限制用于配合 MathWorks 产品；matlab-mcp-server 见其 LICENSE.md）。
MATLAB、Simulink、MathWorks 是 The MathWorks, Inc. 的商标。本项目与 MathWorks 无隶属或背书关系。

dsh-matlab-mcp —— 让 Agent 真正动手操作 MATLAB 与 Simulink

dsh-matlab-mcp

中文 | English

这不是"在 MATLAB 里塞一个 AI"，而是反过来：MATLAB 作为 MCP 服务器被 DSH 调用。DSH 侧只做三件事：挂载官方 MCP 服务器、一键供给官方制品、把官方技能注册进技能目录。

你 ──自然语言──▶ DSH Agent
                   ├─ 工具  mcp__matlab__<tool>  ──stdio MCP──▶ MATLAB MCP Server(官方 exe) ──▶ MATLAB / Simulink
                   ├─ 技能  matlab-* / simulink-*  ── 来自两个官方 Agentic Toolkit
                   └─ 系统提示词注入（调用规范、超时、图窗导出、Simulink 工具优先级）

特性

能力	说明
执行 MATLAB 代码	`mcp__matlab__evaluate_matlab_code`：给一段代码 + 工作目录，返回命令窗口输出
运行脚本 / 测试	`run_matlab_file`、`run_matlab_test_file`（MATLAB 单元测试框架）
静态检查	`check_matlab_code`：不执行代码，报出风格/潜在错误/弃用函数/性能问题
工具箱探测	`detect_matlab_toolboxes`：列出已安装产品与版本
Simulink 模型操作	`model_overview`、`model_read`、`model_query_params`、`model_resolve_params`、`model_edit`、`model_read_diagnostics`、`model_check`、`model_scan`、`model_test`
专家技能	按组注册 MathWorks Agentic Toolkit 技能（调试、代码评审、Live Script、建模仿真最佳实践…），用标准 `skill` 工具按需加载
打开 MATLAB 按钮	聊天主界面标题栏有一个「打开 MATLAB」按钮，点一下弹出 MATLAB 桌面窗口；`auto`/`existing` 模式下打开的是共享会话，你可以直接在窗口里看 Agent 干活
一键安装	设置卡「一键安装 / 修复」：自动下载官方二进制、MATLAB 端工具箱、两个技能仓，并注册 Simulink 工具包路径。全程不需要你手动打开 MATLAB
零手动	默认 `sessionMode=new`：插件自己启动 MATLAB（桌面可见），你只需要用自然语言下命令
网络兜底	直连 GitHub 失败时可选用镜像（默认关闭，开启后仅在直连失败时启用，并校验 PE/ZIP 魔数）
进程卫生	插件卸载时按父子进程归属关闭它自己启动的 MATLAB，绝不动你手动打开的那个
中英双语 UI	设置卡与文档均中英对齐

架构与上游

本插件不重造 MCP 桥，全部使用 MathWorks 官方制品：

上游	作用	本插件的角色
`matlab/matlab-mcp-server`（官方 Go 二进制）	MCP 服务器本体，被 DSH 的 `@deepseek-ai/dsh-mcp-client` 以 stdio 方式挂载	下载、校验、缓存、构建启动参数与环境变量
`MATLABMCPServerToolbox.mltbx`（同上 release）	提供 `shareMATLABSession()`，用于接管已有 MATLAB 会话	下载并调用 `matlab -batch` 自动安装
`matlab/matlab-agentic-toolkit`	24 组 MATLAB 技能	同步到本地缓存，注册为 DSH 技能
`matlab/simulink-agentic-toolkit`	11 组 Simulink 技能 + 9 个 MCP 扩展工具（`tools/tools.json`）	同步、注册技能、`addpath`+`savepath` 注册工具函数路径、把 `tools.json` 作为 `--extension-file` 传给 MCP 服务器

环境要求

项目	要求	本机实测
MATLAB	R2021a 或更高（Simulink 工具需 R2023a+，`model_test` 需 Simulink Test）	R2025b（25.2.0.2998904），含 Simulink / Stateflow / Simulink Test 等 110 个产品
DSH	0.1.5 及以上（插件按 0.1.5 / 0.2 两代设置接缝自适应）	0.2.0 系列
Node.js	`^22.19.0
网络	首次安装需访问 GitHub；受限网络可开启镜像开关	直连不稳，镜像可用

安装

从 npm 安装（最省事）

cd "$env:DSH_HOME\profiles\<你的 profile>"
pnpm add dsh-matlab-mcp
# 再把 "dsh-matlab-mcp" 加进该 profile package.json 的 dsh.profile.bundles，重启 DeepSeek Harness
# 然后 设置 → MATLAB / Simulink MCP → 点「一键安装 / 修复」

从 git clone 安装（可离线 / 想改代码时用）

git clone https://github.com/MCviseron/dsh-matlab-mcp.git D:\dsh-matlab-mcp
node D:\dsh-matlab-mcp\scripts\install.mjs     # 加 --dry-run 可先预演

在 %DSH_HOME% 建 matlab-mcp-plugin 联接指向仓库（同盘路径，规避 pnpm 跨盘 link:D:/... 生成无效联接的问题）；
给每个存在的 profile 写 dependencies / dsh.profile.bundles / cordis.patch.yml；
直接建立（或修复）node_modules 里的联接 —— 有 pnpm 时顺带跑一次 pnpm install，没有 pnpm 也能装；顺带修复其它本地插件失效的 link: 联接；
打印后续步骤。

跑完重启 DeepSeek Harness，再做下面「一键安装运行时」。

兼容性说明：lib/ 随仓库提交，CI（.github/workflows/check.yml）会在每次 push 时重新构建并校验 lib/ 与 src/ 一致、且 bundle 里不再有 @deepseek-ai/* 外部 import —— 所以「提交构建产物」不会变成悄悄过期的坑。

手动接线（不用脚本）

不想用脚本就手工接线（同样不需要构建，仓库自带 lib/）：

# 1) 在 DSH 主目录建一个指向本仓库的联接
cmd /c mklink /J "$env:DSH_HOME\matlab-mcp-plugin" "D:\Program\DSH-Plugin-Class\dsh-matlab-mcp"

# 2) 在 profile 的 package.json 里加依赖与 bundle
#    "dependencies": { "dsh-matlab-mcp": "link:C:/Users/<你>/.dsh/matlab-mcp-plugin" }
#    "dsh.profile.bundles": [ ..., "dsh-matlab-mcp" ]

# 3) 在 profile 的 cordis.patch.yml 里加一行（见下）
# 4) 建立联接（有 pnpm 时用 pnpm install；没有 pnpm 就直接 mklink）
cd "$env:DSH_HOME\profiles\web"; pnpm install
# 若发现某些插件的 node_modules 联接失效（指向 C:\...\profiles\<p>\D:\...），用 mklink /J 逐个修复

cordis.patch.yml 追加：

- id: matlab-mcp
  name: dsh-matlab-mcp
  config:
    enabled: true
    sessionMode: new
    displayMode: desktop
    simulinkTools: true
    toolCallTimeoutMs: 600000
    allowMirrorDownload: false

然后重启 DeepSeek Harness（新增 bundle 需要重新读取插件清单）。

一键安装运行时（在 DSH 设置里）

打开 设置 → MATLAB / Simulink MCP，点 「一键安装 / 修复」。它会：

下载 matlab-mcp-server-<平台> 到 $DSH_HOME/matlab-mcp/bin/（校验 PE 魔数 + --version）；
下载 MATLABMCPServerToolbox.mltbx 并用 matlab -batch 自动安装（拿到 shareMATLABSession）；
git clone（失败则 zip 兜底）两个 Agentic Toolkit 到 $DSH_HOME/matlab-mcp/toolkits/；
addpath(genpath(<simulink-toolkit>/tools)) + savepath，让 9 个 Simulink 工具函数在每个 MATLAB 会话里可见；
重新挂载 MCP 客户端 —— 工具以 mcp__matlab__* 出现在会话里。

若直连 GitHub 失败，会返回 MIRROR_DISABLED 错误并提示你打开「允许镜像下载」，不会静默走第三方。

制品获取（镜像 / 本地目录）

插件默认直连 GitHub；国内网络可配置镜像或本地制品目录（两者都可选，默认关闭）：

allowMirrorDownload: true
downloadMirror: "https://你的镜像/{path},https://gh-proxy.com/{url}"   # {path} 换主机式 / {url} 前缀式，逗号分隔按序回退
localAssetsDir: "D:\matlab-mirror"                                   # 命中即直接复制、零网络请求（优先级：本地 → 镜像 → 直连）

配置项

字段	默认	说明
`enabled`	`true`	关闭则卸载 MCP 客户端，不再注册 `mcp__matlab__*`
`announceToAgent`	`true`	把 MATLAB 使用规范注入系统提示词
`matlabRoot`	`""`	留空 = 自动探测最新安装（本机探测到 `D:\MATLAB\2025b`）
`sessionMode`	`new`	`new` 自启 / `auto` 优先接管已共享会话 / `existing` 只连已共享会话
`displayMode`	`desktop`	`desktop` 显示 MATLAB 桌面；`nodesktop` 不显示（更快）
`initialWorkingFolder`	`""`	留空 = `$DSH_HOME/matlab-mcp/workspace`
`simulinkTools`	`true`	挂载 9 个 Simulink 工具，并在安装时注册工具包路径
`skillsEnabled`	`true`	把两个 Agentic Toolkit 的技能注册进技能目录
`skillGroups`	`""`	逗号分隔的技能组；留空 = 默认组；`none` = 全部关闭
`toolCallTimeoutMs`	`600000`	单次工具调用超时（10 分钟）；上限 30 分钟
`allowMirrorDownload`	`false`	默认关闭；直连失败时才用镜像下载官方制品
`localAssetsDir`	`""`	本地制品目录（`mirror-assets.mjs` 产出的那种布局）。命中即直接复制、零网络请求；优先级本地 → 镜像 → 直连
`downloadMirror`	`https://gh-proxy.com/{url},https://gh.llkk.cc/{url},https://ghproxy.net/{url}`	镜像列表（逗号分隔，按顺序回退）。模板：`{url}` 前缀式、`{path}` 换主机式，老的纯前缀写法仍兼容。开启开关后镜像优先、直连兜底
`telemetry`	`false`	关闭时传 `--disable-telemetry=true` 给 MCP 服务器
`shutdownMatlabOnUnload`	`true`	插件卸载时关闭由本插件启动的 MATLAB（按父子进程归属判定）

工具清单

完整参数与返回说明见 docs/tools.md。会话中看到的名字带 mcp__matlab__ 前缀。

内置 5 个：detect_matlab_toolboxes、check_matlab_code、evaluate_matlab_code、run_matlab_file、run_matlab_test_file

技能注入

组	技能数	内容
`matlab-core`	6	调试、代码评审、Live Script、文档查询、产品安装/列举
`matlab-programming`	1	带参数校验的健壮函数
`matlab-software-development`	11	测试、性能/内存优化、文档、工具箱打包、工程与构建计划
`matlab-data-import-and-analysis`	4	表格/时间表/大数据方案、凭证安全
`model-based-design-core`	11	建模、仿真、需求草稿、模型清理、缺陷报告
`simulink-simulation`	3	仿真输入、SDI 运行、批量仿真

使用示例

安装完成后，直接用自然语言即可，例如：

「用 MATLAB 算一下这个矩阵的特征值，并把结果写成 csv 放到当前工程」
「画一张阻尼比 0.1~1.0 的阶跃响应对比图，导出 PNG 给我看」
「在 Simulink 里建一个 PID 控制二阶系统的模型，跑 10 秒仿真，给我超调量和稳态误差」
「检查我工程里所有 .m 文件的代码规范问题」

排障

现象	原因与处理
错误码 `MIRROR_DISABLED`	直连 GitHub 失败且镜像未开启。设置里打开「允许镜像下载」后重试
启动日志：`matlab-mcp (dsh-matlab-mcp): failed to import`	插件入口加载失败。① 你的仓库副本是 0.2.x 或更早（那时 `lib/` 不进仓库）→ `git pull` 到 0.3.0+（自带 `lib/`）；② profile 里的 `node_modules` 联接失效（见下一条）；③ 自己改过 `src/` 却没重新 `pnpm build`。跑 `node scripts/install.mjs` 可一次处理接线问题
启动日志：多个插件同时 `failed to activate` / `failed to import`	profile 的 `node_modules` 里 `link:` 联接坏了（pnpm 对 `link:D:/...` 跨盘路径会生成无效联接，指向 `C:\...\profiles\<p>\D:\...`）。用 `mklink /J <profile>\node_modules\<插件名> <真实目录>` 逐个修复，或直接重跑 `node scripts/install.mjs`（它会统一修复）
客户端直接崩溃并生成 `crash-*-host.log`，里面有 `spawn ...matlab-mcp-server-windows-x64.exe ENOENT`	`ENOENT` 不代表文件不存在 —— libuv 在 `cwd` 不存在时也报这个错。0.4.0 起插件会自动创建工作目录并在挂载前预检二进制；若你还在 0.3.x：升级，或先手工 `mkdir "%USERPROFILE%\.dsh\matlab-mcp\workspace"` 再重试。这也是 DSH 侧 `dsh-mcp-client` 未捕获 spawn 错误导致宿主退出的健壮性缺陷
插件突然不加载 / 工具消失（重启后才出现）	先查 profile `package.json` 的 `dsh.profile.bundles` 里还有没有这个插件名。DSH 插件管理器的「卸载」会在 pnpm 步骤失败之前先删掉 bundle 记录与依赖，于是插件静默消失、而错误只留在 `.plugin-manager\logs\operation-*\pnpm.log`。补回 `bundles` 里那一项（位置无所谓）+ 恢复依赖后 `pnpm install` 即可
卸载/安装插件时报 `ERR_PNPM_UNEXPECTED_STORE`（…linked from …store\v10 … pnpm now wants …store\v11）	profile 的 `node_modules` 是全局 pnpm 10.x 装的（`node_modules\.modules.yaml` 记着 `storeDir`），而 DSH 运行时自带 pnpm 11.x（store 格式 v11）→ 两者对 store 版本要求打架。二选一：① 临时——在 profile 目录用与树匹配的 pnpm 操作（`pnpm store path` 会正好指向 `.modules.yaml` 里那个 store）；② 彻底——用运行时 pnpm 把整棵树重链到 v11： `cd %USERPROFILE%\.dsh\profiles\desktop` `node "%USERPROFILE%\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.mjs" install --no-frozen-lockfile --config.confirmModulesPurge=false` （无 TTY 时 pnpm 会因「要清空 `node_modules`」而中止，必须给 `confirmModulesPurge=false`；`CI=true` 会顺带打开 `--frozen-lockfile`，所以要么别设 CI，要么显式 `--no-frozen-lockfile`。整棵树重链后，该 profile 里请只用运行时 pnpm 或 DSH 界面，否则全局 pnpm 10 会反向报同一个错）
安装极慢或卡在下载	点设置卡「镜像测速」，再点「把最快的排到最前」。镜像存活期常常只有几小时（实测 `ghproxy.net` 数小时内从可用掉到 0.03 MB/s），默认列表会过期
`not-provisioned` / 没有 `mcp__matlab__*` 工具	还没安装运行时。点设置卡「一键安装 / 修复」
首次调用很慢（20–45 秒）	MATLAB 冷启动，属正常；之后再调用是秒级
工具调用超时	调大 `toolCallTimeoutMs`，或把长任务改成写脚本 + 轮询结果文件
Simulink 工具报找不到函数	一键安装的第 4 步没跑（`simulinkTools` 关闭时不会注册路径）；开启后重跑安装
你手动打开的 MATLAB 被关掉了	不应该发生：只关闭父进程链上属于本插件 MCP 服务器的 MATLAB。若出现请提 issue
想看日志	MCP 服务器日志在 `$DSH_HOME/matlab-mcp/logs/`；设置卡「刷新状态」显示二进制版本、MATLAB 路径、工具箱/技能仓是否就位

卸载

设置卡关闭 enabled（立刻卸载 MCP 客户端、注销技能与工具）；
从 profile 的 package.json（dependencies + dsh.profile.bundles）与 cordis.patch.yml 移除 dsh-matlab-mcp 行，pnpm install，重启 DSH；
删除 $DSH_HOME\matlab-mcp（缓存，约 70 MB，含二进制、工具包、技能仓）；
如需彻底清理 MATLAB 侧：在 MATLAB 里 matlab.addons.toolbox.uninstallToolbox(...) 卸载 MATLAB MCP Server Toolbox，并用 rmpath 去掉 Simulink 工具包路径（savepath）。

验收

逐项验收清单与原始证据（命令输出、工具返回、截图）见 docs/acceptance-2026-10-14.md。

#	验收项	通过标准
A	静态质量	`pnpm typecheck && pnpm test && pnpm build` 全绿；插件加载无报错
B	桥连通	`mcp__matlab__detect_matlab_toolboxes` 返回 R2025b + Simulink
C	执行代码	自然语言算 `sum(1:10)`=55；画图导出 PNG 并视觉复核
D	Simulink 仿真	脚本建模型 + `sim()` 取仿真结果，全程无人工点击
E	Simulink 工具	`model_overview`/`model_read`/`model_scan` 返回结构化结果
F	技能注入	技能出现在目录、`skill()` 可加载、行为符合技能指引
G	零手动	删缓存后一键安装即可复现 B–F
H	稳定性	安装幂等、卸载无残留、无孤儿 MATLAB 进程
I	文档	本 README、`docs/tools.md`、CHANGELOG、验收记录、可复跑验证脚本 `scripts/`

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # 5 个纯逻辑测试套件（配置解包/下载策略/路径探测/启动参数/技能解析）
pnpm build       # esbuild → lib/index.js（宿主）+ lib/client.js（浏览器设置卡）
pnpm check       # 三者串跑

源码结构：

文件	职责
`src/index.ts`	宿主半边：配置 schema、挂载 MCP 客户端、系统提示词段、技能提供者注册、设置接缝适配
`src/provision.ts`	一键供给：二进制/工具箱/技能仓下载与安装、Simulink 路径注册、`runSetup`
`src/download.ts`	下载策略（直连→镜像、镜像默认关闭）、原子写入、魔数校验
`src/paths.ts`	缓存布局、平台制品名、MATLAB 安装探测与选择
`src/server-args.ts`	MCP 服务器启动参数与子进程环境（Windows `windir`/`PATH` 显式传递）
`src/selftest.ts`	最小 MCP stdio 客户端（设置卡「测试连接 / 深度自检」用）
`src/skills-catalog.ts` + `src/skills-provider.ts`	技能发现/解析/过滤 + DSH `SkillProvider`
`src/matlab-processes.ts`	按父子进程归属回收本插件启动的 MATLAB
`src/routes.ts`	宿主 HTTP 路由：status/setup/test/reconnect/diagnostics + 设置桥
`src/client/*`	浏览器半边：设置卡、文案（中/英）、设置命名空间读写

版本与变更

语义化版本；每次发布打 tag（v0.1.0）。
变更记录见 CHANGELOG.md（Keep a Changelog 格式）。
与 DSH 的兼容性：设置接缝、ctx.inject(['tools']) 挂载、volatile 配置解包均按 0.1.5 / 0.2 两代自适应，详见 CHANGELOG。

许可证与商标

本插件代码：Apache-2.0（见 LICENSE）。
不随仓库分发任何 MathWorks 制品：二进制、.mltbx、技能文本都在安装时从 MathWorks 官方 GitHub 下载，且不修改其内容。上游许可见各自仓库（matlab-agentic-toolkit / simulink-agentic-toolkit 为 MathWorks 许可，限制用于配合 MathWorks 产品；matlab-mcp-server 见其 LICENSE.md）。
MATLAB、Simulink、MathWorks 是 The MathWorks, Inc. 的商标。本项目与 MathWorks 无隶属或背书关系。

MCviseron/dsh-matlab-mcp

dsh-matlab-mcp

目录

特性

架构与上游

环境要求

安装

从 npm 安装（最省事）

从 git clone 安装（可离线 / 想改代码时用）

手动接线（不用脚本）

一键安装运行时（在 DSH 设置里）

制品获取（镜像 / 本地目录）

配置项

工具清单

技能注入

使用示例

排障

卸载

验收

开发

版本与变更

许可证与商标

Community comments

MCviseron/dsh-matlab-mcp

dsh-matlab-mcp

目录

特性

架构与上游

环境要求

安装

从 npm 安装（最省事）

从 git clone 安装（可离线 / 想改代码时用）

手动接线（不用脚本）

一键安装运行时（在 DSH 设置里）

制品获取（镜像 / 本地目录）

配置项

工具清单

技能注入

使用示例

排障

卸载

验收

开发

版本与变更

许可证与商标

Community comments