MATLAB 智能体 liu13511798974-cloud/dsh-matlab-agentic

MATLAB Agentic for DeepSeek Harness

把 MathWorks 官方的 MATLAB MCP Server（含可选 Simulink 扩展工具）和 MATLAB Agentic Toolkit 技能接入 DeepSeek Harness（DSH），让 DSH 里的 AI 直接启动/退出 MATLAB、编写并运行 MATLAB 代码、跑单元测试、静态检查代码。

- 零侵入：不改 DSH、不改 MATLAB 工具链；会自己拉起独立的 MCP server 进程，与 Claude / Codex / Copilot 等其它 Agent 的配置互不影响。
- 一键安装：一个 PowerShell 脚本完成 二进制下载 → MATLAB 侧 MCP 初始化 → 技能安装 → 预设创建 → 设为默认。
- 基础模式随时可调：安装完成后任何时候都能一条命令切换 MATLAB Agentic 基于哪个 DSH 预设（标准/代码/精简/创造模式）。

工作原理（30 秒版）

MATLAB ──shareMATLABSession()──► matlab-mcp-server.exe（官方 stdio MCP server） ▲ 安装脚本下载 + --setup-matlab 初始化 │ DSH 预设 "MATLAB Agentic" ──@deepseek-ai/dsh-mcp-client 行──┘（DSH 自带通用 MCP 桥） │ 模型可调用工具： mcp__matlab__evaluate_matlab_code / run_matlab_file / run_matlab_test_file / detect_matlab_toolboxes / check_matlab_code （+ 可选 7 个 Simulink 工具）

MATLAB 技能（150+ 个 matlab-* skill）安装在 ~/.agents/skills —— DSH 默认自动扫描该目录。

无需修改 DSH 或 MATLAB Agentic Toolkit 的任何代码：两边都是标准 MCP / 标准技能目录。

一、在新电脑上从零安装

0. 前提

| 依赖 | 要求 |
| 操作系统 | Windows 10/11 |
| MATLAB | R2021a 或更新（官方支持最近 5 年内版本）。Simulink 工具需要安装 Simulink |
| Node.js | ≥ 20（安装 DSH 用） |
| git | 可选；没有时脚本会用 zip 包兜底安装技能 |
| 网络 | 需能访问 GitHub。脚本会自动探测常见本地代理端口（7890/7897/10809…），也可用 -Proxy 手动指定 |
| DSH | 需已能正常对话（模型/账号已配置） |

1. 安装 DeepSeek Harness（若已安装则跳过）

npm install -g @deepseek-ai/dsh
dsh web # 首次运行自动初始化，按终端打印的地址在浏览器打开（本地默认一般是 http://127.0.0.1:3080）

2. 获取本仓库并运行安装脚本

git clone https://github.com/liu13511798974-cloud/dsh-matlab-agentic.git
cd dsh-matlab-agentic
powershell -ExecutionPolicy Bypass -File .\install.ps1

脚本会依次完成（每步都有 [OK] 输出，失败会停在对应步骤并给出原因）：

1. 定位环境 —— 找到 DSH 主目录与自带的四个预设（标准/代码/精简/创造模式）
2. 定位 MATLAB —— PATH 里有 matlab 就直接用；否则自动找 C:\Program Files\MATLAB\R20xx；都找不到就加 -MatlabRoot 指定
3. 下载 MCP 二进制 —— 从 matlab-mcp-server Releases 下载 matlab-mcp-server-windows-x64.exe 到 %USERPROFILE%\.matlab\agentic-toolkits\bin\（已存在则跳过）
4. MATLAB 侧 MCP 初始化 —— 运行 matlab-mcp-server.exe --setup-matlab，向 MATLAB 安装 "MATLAB MCP Server Toolbox"。这是让 MATLAB 能被 MCP 连接的关键一步，约 1–3 分钟
5. 安装技能 —— 克隆 MATLAB Agentic Toolkit，把 skills-catalog 下所有技能链接到 %USERPROFILE%\.agents\skills\（DSH 默认扫描目录；优先符号链接，无权限时自动退化为复制）
6. 创建预设 —— 基于你选的模式复制一份 DSH 预设到 %DSH_HOME%\.agent-presets\matlab\，追加 mcp-matlab 行（路径已自动填写）
7. 设为默认预设 —— 修改 settings.yaml 的 agent-presets.default: matlab（改前自动备份）

3. MATLAB 侧初始化（哪些必要？）

MATLAB 侧共有三种"初始化"，必要性不同：

| 初始化 | 作用 | 什么时候必要 |
| --setup-matlab（脚本第 4 步自动做） | 向 MATLAB 安装 "MATLAB MCP Server Toolbox"（提供 shareMATLABSession 等） | 想共享桌面会话（existing/auto 的共享部分）才需要；纯 new 模式可跳过 |
| shareMATLABSession() | 把当前打开的 MATLAB 注册为共享会话，让 MCP server 连到它 | existing/auto 想用桌面上这个 MATLAB 时需要；每次 MATLAB 启动后执行一次 |
| Simulink 初始化 addpath('<toolkit>\simulink'); satk_initialize | 注册 7 个 Simulink 扩展工具（satk_initialize 内部会自动调用 shareMATLABSession） | 仅使用 Simulink 扩展工具时需要；每次 MATLAB 会话执行一次 |

打开 MATLAB，在命令行窗口执行（不用 Simulink 就只跑第一行）：

shareMATLABSession()

% 仅当启用了 Simulink 扩展工具（-EnableSimulink）时再跑：
addpath(fullfile(getenv("USERPROFILE"), ".matlab", "agentic-toolkits", "simulink"))
satk_initialize

这就是常见教程里 init_codex() / 启动文件做的事（fullfile(getenv("USERPROFILE"), ...) 拼路径 + satk_initialize），DSH 与 Codex 用的是同一套机制，已有的初始化函数无需改动。
想每次 MATLAB 启动自动执行：重跑脚本加 -AddToStartup（自动写入 Documents\MATLAB\startup.m，启用 Simulink 时自动写入 satk 初始化）。选了 new 会话模式则这一步整体可跳过。

4. 验证

关闭当前会话、新开一个 DSH 会话（默认已是 "MATLAB Agentic" 预设），对 AI 说：

MATLAB 版本是什么？装了哪些工具箱？

预期：AI 调用 mcp__matlab__detect_matlab_toolboxes 并报告你的 MATLAB 版本和工具箱列表。再试：

在 MATLAB 里计算 1 到 10 的平方和，并把结果画成柱状图

二、随时调节基础模式（重点）

"MATLAB Agentic" 是基于某个 DSH 预设构建的（标准模式/代码模式/精简模式/创造模式）。这个基础安装后随时可切换，不会锁死，两种方式任选：

方式 A：在 DSH 里直接对话切换（推荐）

安装脚本会做两件事：装一个原生切换工具 matlab_switch_base（dsh plugin add 自动完成）和一个切换技能。之后完全在 DSH 内完成切换——直接说：

把 MATLAB Agentic 的基础模式切到创造模式（cordis）

AI 直接调用 matlab_switch_base 工具完成切换（秒级），并告诉你生效方式。也可以指定会话模式/Simulink："切到 code 模式，会话模式改成 new"。随时可以问它「MATLAB Agentic 当前基于哪个模式？」。

方式 B：命令行切换

安装时选（默认 standard）： .\install.ps1 -Base cordis

安装后随时切换（秒级完成，只重建预设层）： .\install.ps1 -Switch code .\install.ps1 -Switch cordis

| 参数值 | 含义 |
| standard | 标准模式：功能完整的编码 Agent（默认） |
| code | 代码模式 |
| minimal | 精简模式 |
| cordis | 创造模式：额外带运行时自修改工具集（cordis_* 工具与组合编写技能） |

切换后如何生效（DSH 对预设按文件时间戳热挂载新组合）：

1. 关闭已有的 MATLAB Agentic 会话（旧会话仍运行在旧基础上，并占用着 matlab 这个 MCP 连接名）
2. 新开会话即生效，无需重启 DSH
3. 例外：基础为 cordis 时，需要完全退出并重启 DSH（cordis 含进程级单例的自修改工具集，不能与其它 cordis 类预设在同一进程并存）

-Switch 只重建预设层；下载、MATLAB 初始化、技能安装都会跳过（它们与基础模式无关，装一次即可）。

三、完整参数

| 参数 | 取值 | 说明 |
| -Base | standard(默认) / code / minimal / cordis | 以哪个预设为基础构建 MATLAB Agentic |
| -Switch | 开关 | 只重建预设层，用于安装后随时切换基础模式 |
| -SessionMode | auto(默认) / existing / new | MATLAB 会话模式，见下表 |
| -EnableSimulink | 开关 | 同时装 Simulink 技能并注册 Simulink 扩展工具 |
| -MatlabRoot | 路径 | 手动指定 MATLAB 根目录（如 C:\Program Files\MATLAB\R2025b，不含 \bin） |
| -SkipSetupMatlab | 开关 | 跳过 --setup-matlab（MATLAB 侧已初始化过时用） |
| -SkipSkills | 开关 | 跳过技能安装 |
| -SkipDownload | 开关 | 二进制已就位，不重新下载 |
| -Update | 开关 | 强制升级二进制到最新版 |
| -NoDefaultPreset | 开关 | 不修改默认预设，手动在 DSH 界面选择 |
| -SkipSwitchTool | 开关 | 不安装"DSH 内切换工具"插件（只保留脚本/技能切换方式） |
| -Profile | profile 名 | dsh plugin 安装到的 profile（默认 web） |
| -AddToStartup | 开关 | 把 shareMATLABSession() 写入 MATLAB 的 startup.m |
| -Proxy | URL | 手动指定下载代理，如 http://127.0.0.1:7890 |

会话模式怎么选

| 模式 | 行为 | 适合 |
| auto | 优先连共享的 MATLAB 会话；连不上就自动新开一个 | 大多数用户（最省心，默认） |
| existing | 只连共享会话（必须先 shareMATLABSession()） | 想和 Claude/Codex 一样用桌面上的同一个 MATLAB |
| new | 每次都新开独立 MATLAB | 和 Codex 等完全隔离、互不干扰 |

注意：existing/auto 下，若 Codex 与 DSH 同时都在连同一个共享会话，两边会共用那一个 MATLAB（通常没问题；要彻底隔离就选 new）。

四、手动安装（不想用脚本）

1. 下载二进制：打开 <https://github.com/matlab/matlab-mcp-server/releases/latest>，下载 matlab-mcp-server-windows-x64.exe，放到 %USERPROFILE%\.matlab\agentic-toolkits\bin\
2. MATLAB 侧初始化：运行 matlab-mcp-server.exe --setup-matlab（必要时加 --matlab-root=<MATLAB根目录>）
3. 装技能：克隆 <https://github.com/matlab/matlab-agentic-toolkit>，把 skills-catalog\\ 下的技能目录链接/复制到 %USERPROFILE%\.agents\skills\
4. 建预设：把本仓库 preset\ 下的 agent.cordis.yml、preset.yml 放到 %DSH_HOME%\.agent-presets\matlab\，并把 agent.cordis.yml 里的 __REPLACE_WITH_BINARY_PATH__ 换成你的二进制绝对路径（斜杠用 /）
5. 设默认：在 %DSH_HOME%\settings.yaml 里设 agent-presets.default: matlab（或界面选预设）
6. 共享会话：MATLAB 里执行 shareMATLABSession()，然后新开会话验证

五、常见问题

| 问题 | 原因与解决 |
| 工具调用报"连不上 MATLAB" | existing 模式下 MATLAB 未运行或未执行 shareMATLABSession()；执行后再让它重试。auto 模式会自动新开 MATLAB |
| --setup-matlab 失败 | 确认 MATLAB 版本在支持范围内、能正常启动；用 -MatlabRoot 明确指定路径 |
| 新会话里看不到 matlab 技能 | 技能在 ~/.agents/skills；确认脚本第 5 步成功（DSH 下次会话会重新扫描） |
| 切换基础模式后新会话没变化 | 关掉所有旧的 MATLAB Agentic 会话再开新的；cordis 基础需重启 DSH |
| 切换后新会话报 MCP 相关错误 | 旧的 MATLAB Agentic 会话还占着 matlab 连接名，先关掉旧会话 |
| 下载很慢/失败 | 走代理：脚本会自动探测 7897/7890/10809 等本地端口，或 -Proxy 手动指定 |
| 符号链接创建失败 | 无管理员权限/未开开发者模式，脚本已自动退化为复制（更新技能时重跑脚本即可） |
| 和其它 Agent（Claude/Codex）并存 | 完全独立，各拉各的 server 进程、各配各的；只是 existing 模式下会共用同一个共享 MATLAB 会话 |
| 想关掉匿名使用统计 | 在预设的 mcp-matlab 段取消 --disable-telemetry=true 注释（或安装时用 -Switch 重跑后手动加） |

六、接入后的工具

- 内置 5 个：detect_matlab_toolboxes、check_matlab_code、evaluate_matlab_code、run_matlab_file、run_matlab_test_file
- Simulink 扩展 7 个（-EnableSimulink 时）：模型读取/编辑/查询参数/测试等
- 技能 150+ 个：matlab-* 全系列（数据分析、信号处理、RF、天线、深度学习……），DSH 会自动按需加载

七、本仓库文件

| 文件 | 作用 |
| install.ps1 | 一键安装 + 随时切换（唯一需要的文件） |
| preset/ | 手动安装用模板（脚本运行时会用你机器上 DSH 自带的最新预设，模板仅供参考） |
| NOTICE.md | 第三方内容来源与许可说明 |

许可与声明

- 本仓库代码以 MIT 许可发布（见 LICENSE）；preset/agent.cordis.yml 派生自 @deepseek-ai/dsh（MIT）随附的 standard 预设。
- MATLAB MCP Server 二进制不随本仓库分发，安装时从 MathWorks 官方 Releases 下载；其使用须遵守 MathWorks 软件许可协议，且不得多用户共享同一 MCP server（官方要求，详见 matlab-mcp-server README）。
- 本仓库与 MathWorks、DeepSeek 无隶属关系，是社区适配脚本。