MATLAB 运行面板 seally-web/dsh-matlab-runner

dsh-matlab-runner

一个 DeepSeek Harness 插件，在右侧边栏放一块 VS Code 风格的 MATLAB 面板：编辑 .m 代码，按 ⌘/Ctrl+Enter，看控制台输出，内联打开图形，多次运行之间保持一个常驻 MATLAB 会话，像 MATLAB 的 add-to-path 列表那样浏览多个文件夹，还能查看和赋值工作区变量。

dsh-matlab-runner 是 UI 插件：宿主端以系统用户权限启动 MATLAB（不走智能体的沙箱），浏览器端给你编辑器 + 运行器 + 工作区查看器。它和基于 MCP 的 MATLAB 插件不同，不是智能体工具的封装——智能体确实会拿到一个 matlab_run 工具，但面板才是产品本身。

一个包里装两半：

| 半边 | 文件 | 做什么 |
| 宿主 | lib/index.js、lib/runner.js | 持有常驻 MATLAB 会话和运行注册表，提供 /matlab/api/，注册 matlab_run 智能体工具。 |
| 浏览器 | lib/client.js | 一个 page 类型的侧边栏标签页（编辑器、行号槽、脚本选择器、Run/Stop/Save、实时控制台、图形预览、设置），外加一张引导卡片和 matlab-runner.open 快捷键。 |

面板

一次真实运行：左边是文件树 + 变量，中间是编辑器，下面是实时控制台，导出的图形以缩略图展示。拖动分隔条可以调整文件树、变量面板和控制台的大小；设置一键可达。*

| 设置 | 窄侧边栏 |
| 设置 | 窄侧边栏 |

两种运行模式

- session（默认）——一个长期存活的 matlab -nodesktop -nosplash 进程，通过 stdin 喂入。首次启动后（约 6–9 秒），一次运行只要 ~10–30 毫秒，提示符在多次运行之间保留你的变量，图形窗口真的会在桌面上打开，同时面板也显示导出的 PNG。脚本还在跑的时候，输出就已经流式进入控制台。
- batch——每次运行都走 matlab -batch，无界面，脚本结束进程就退出（每次调用 15–20 秒，不开窗口）。留给类 CI、跑完不留痕迹的活儿。

侧边栏和智能体工具共用同一个会话，所以模型跑的东西和你敲的东西落在同一个 MATLAB 工作区里。

为什么智能体的 shell 跑不了，这里能跑

MATLAB 启动前需要写 ~/Library/Application Support/MathWorks。沙箱化的 shell（workspace-write）会让 matlab -batch 以退出码 1 结束、控制台一片空白，智能体拥有的 PTY 标签页同样受这个沙箱限制。宿主端从宿主进程用 node:child_process 启动 MATLAB，也就是以系统用户权限运行，不受智能体沙箱模式影响——所以这块面板不用把会话切到 Full access 就能跑 MATLAB。

安装

从 npm 安装（发布后可用）：

dsh plugin --profile web add dsh-matlab-runner

桌面应用的配置档归 Electron 应用所有，请改用随附脚本——它会把载荷复制进配置档，接好依赖和 dsh.profile.bundles 行，写入初始配置，再重新组装插件：

node bin/install-local.sh # or: plugins/dsh-matlab-runner/bin/install-local.sh

官方桌面应用自己管理配置档，所以脚本会把载荷复制到 ~/.dsh/profiles/desktop/node_modules/dsh-matlab-runner，加上依赖和 dsh.profile.bundles 行，写入初始配置，再重新组装插件的 Loader 条目。

说说最后一步：应用会监听 ~/.dsh/profiles/desktop/package.json，所以把 bundle 行删掉再放回去，就会从磁盘重新加载插件——不用重启应用，也不会丢会话。bin/reload-host.sh 做的就是这件事：

plugins/dsh-matlab-runner/bin/reload-host.sh # host half picked up new files

然后刷新页面（⌘/Ctrl+R），浏览器那一半也会更新。只有标签页仍显示旧面板时，才需要完整重启应用。

打开它

右侧边栏 → 添加控件（+）→ MATLAB 运行器 / MATLAB runner 卡片。首次访问后，标签页会留在标签栏里；⌘/Ctrl+Shift+M 可在任意位置打开它（Web 构建：⌘/Ctrl+Shift+Alt+M）。

面板能做什么

- 文件树（⌸ 文件）——在面板里浏览 workdir，按需展开文件夹，点击任意文本文件即可在编辑器中打开（↑ 上一级 向上走，刷新 重新读取）。只有文本扩展名的文件可编辑，其他文件会报告 binary。
- 编辑器带行号栏、MATLAB 语法高亮（关键字、字符串、数字、注释），关闭自动更正，Tab = 两个空格。
- 运行（⌘/Ctrl+Enter）把缓冲区写入 <workdir>/.dsh-matlab-runner/<stem>.m，并在持久会话中运行。
- 脚本选择器——scriptDir 里的每个 .m 文件，加上每个未保存的草稿。选中一个就加载进编辑器。＋ 新建 打开空白缓冲区，并且每个缓冲区都会被记住（按文件路径，外加每个草稿），所以切换文件或标签页绝不会丢掉你敲的代码。
- 多文件夹——文件树标题栏有文件夹选择器和一个 + 按钮。+ 可把任意绝对路径（~ 也行）挂载为额外的树根，就像 MATLAB 的「添加到路径」列表；挂载项会以 extraRoots 持久化在 matlab-runner.json 里，也能在同一行移除。挂载的文件夹可浏览、可编辑，但运行的工作目录仍跟随工作区（相对路径始终锚定在正在运行的脚本上）。
- 变量编辑器——双击变量面板中的任意一行即可打开值；编辑字面量后点 写回工作区 / Write back，会用 evalin('base', '<name> = <literal>;') 赋值，真正替换 MATLAB 变量（面板随后立即刷新）。数值用 mat2str 显示，其他内容通过 evalc('disp(x)') 显示。
- Stop / ■ 中止当前脚本（会话模式下会重启 MATLAB 会话；下次运行会重新启动它）。
- Save 把真正的脚本写入 <scriptDir>/<name>.m。
- 控制台实时流式输出 stdout/stderr，随后显示退出码、耗时和脚本路径。出错时打印 getReport(e,'extended')，行号得以保留。
- Autosave —— 一次干净退出的运行结束后，缓冲区会写回磁盘：已打开的文件写回各自路径，草稿则作为新脚本保存到 scriptDir 下。用 autoSave 设置或 Settings 里的复选框关掉它。
- 拖动分隔条 —— 一条在文件树和编辑器之间（宽度），一条在编辑器和控制台之间（高度）；两者都按浏览器记住。
- Variables（Σ 变量）—— 实时工作区：每个基础工作区变量的名称、类和大小。宿主让 MATLAB 把 whos 以 JSON 写入 .dsh-matlab-runner/vars.json 再读回来，所以列表不会被控制台截断。每次运行后自动刷新。
- Figures —— 运行过程中涉及的图片文件（.png/.jpg/.svg/.gif/.webp）以缩略图显示在控制台下方；点一张就在标签页里打开完整图片。session 模式下 figure 窗口也会在桌面上打开。
- Live scripts（.mlx） —— 在文件树里点 .mlx 会打开只读预览：带标题的文本、着色代码块、文本输出和内嵌图片。解析在本地完成（lib/livemd.js：ZIP + OOXML，不需要 MATLAB）。预览时 Run/Save 禁用；关掉预览才能编辑。
- Settings —— 运行模式、图形预热开关、所有路径、超时、配置位置，以及 Restart session 按钮。

Interface

面板沿用 VS Code / MATLAB 的布局惯例：

| 区域 | 内容 |
| Toolbar | 三组：run（▶ Run / ■ Stop / Save）、files（脚本选择器 + New）、views（文件树 / 变量）。会话徽标和设置齿轮在右侧。 |
| Breadcrumb | 面板当前指向的文件夹，可按段点击，右侧是编辑目标。 |
| Left column | 上方是文件树，下方是 MATLAB 工作区变量（名称 / 值 / 类 / 大小），两者之间有拖动条，靠编辑器一侧有垂直拖动条。 |
| Editor | 行号槽、语法高亮，控制台上方有分隔条 —— 拖动可调整大小。 |
| Console | 标题条、流式输出、图片缩略图，以及带阶段、退出码、耗时和脚本路径的状态栏。 |
| Settings | 三个带标签的分区 —— run、workspace、MATLAB —— 以标签/控件网格排列，附当前检测来源、「follow this workspace」、「pin to this path」、Save 和 Restart session。 |

面板开关（文件树 / 变量）按浏览器记住。node bin/preview-ui.mjs 把两个视图渲染到 /tmp/mrun-.html，方便快速无头查看：

node bin/preview-ui.mjsbash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \
--screenshot=/tmp/panel.png --window-size=980,760 file:///tmp/mrun-panel.html

保存、草稿与缓冲区

| 缓冲区 | 保存会做什么 | 存在哪里 |
| 已打开的文件（从文件树或脚本选择器里选中的） | 原地覆盖该文件，和编辑器的 ⌘S 一样。自动保存（一次干净运行之后）也是同样效果。 | 文件本身 |
| 草稿（＋ new，名字不带路径） | 把副本存到 <scriptDir>/<name>.m，并把缓冲区切换到这个文件。 | <scriptDir>（默认 <workspace>/matlab） |
| 两种缓冲区里未保存的改动 | 存在浏览器的 localStorage 里，键名 dsh.matlab-runner.buffers，所以切换文件或刷新页面都不会丢。 | 浏览器存储 |
| MATLAB 实际执行的脚本 | 草稿从 <workspace>/.dsh-matlab-runner/ 里的临时副本运行；已打开的文件原地运行，所以相对路径按文件所在目录解析。 | 工作区 |

配置

~/.dsh/matlab-runner.json（设置了 $DSH_HOME 时是 $DSH_HOME/matlab-runner.json），首次启动时创建，里面填的是这台机器实际使用的路径： json { "mode": "session", "warmFigures": false, "autoSave": true, "autoDetect": true, "matlabPath": "/path/to/MATLAB/bin/matlab",
"sessionArgs": ["-nodesktop", "-nosplash"],
"extraArgs": ["-nodisplay", "-nosplash"],
"workdir": "~/your-project",
"scriptDir": "~/your-project/matlab",
"timeoutMs": 600000,
"env": {}
}

- mode — session（常驻进程，快，能弹图窗）或 batch（每次运行起一个进程，无界面）。
- warmFigures — 设为 true 会在启动时初始化图形/Java 栈，第一次 figure 从约 13 秒降到约 2 秒；代价是第一次运行要先把这笔开销付掉。
- autoSave — true（默认）：运行成功后把缓冲区写回打开的文件（草稿则存成 scriptDir/<name>.m）。
- autoDetect — true（默认）：workdir 跟随 DSH 会话当前打开的文件夹，scriptDir 变成 <workspace>/matlab，切换项目不用改配置。设为 false 则固定使用下面两个路径。
- matlabPath — 启动器二进制（app bundle 里的 bin/matlab，不是 Contents/MacOS 里那个）。
- sessionArgs — 常驻进程在 matlabPath 之后跟的参数。
- extraArgs — batch 模式下 -batch 之前的参数。
- workdir — 会话的工作目录，也是临时脚本写入的根目录。开启 autoDetect 时这个值是推导出来的*，不是固定的。
- scriptDir — 保存把 .m 文件放到这里，选择器也从这里找（自动模式下是 <workspace>/matlab）。
- timeoutMs — 每次运行的硬性上限；手动版就是「停止」按钮。
- env — 给 MATLAB 的额外环境变量。

除 env 外，其余都能在面板的 Settings 页里改。

脚本在哪个文件夹里运行？

缓冲区对应真实文件时，运行的就是那个文件，所以 MATLAB 的工作目录是文件自己所在的文件夹，readmatrix('data.xlsx') 会从那里解析脚本（与编辑器里的 Run 按钮相同）。草稿仍从 <workspace>/.dsh-matlab-runner/ 下的临时副本运行；MATLAB 找不到相对路径时，控制台会显示基准文件夹：

相对路径以脚本所在目录为基准: /…/W07_quiz（数据文件放这里，或用绝对路径）

用哪个文件夹？

标签页每次调用 API 都会带上所在会话的工作区根目录（?cwd=），所以：

1. 会话文件夹优先——面板始终操作你当前打开的内容。
2. 否则取 ctx.workspaceRegistry 里的第一个文件夹，再不行取宿主进程的 cwd（没有面板在通信时，智能体工具看到的就是这个）。
3. 超过 2 分钟的报告视为过期，因此 matlab_run 绝不会继承你早已关闭的文件夹。
4. autoDetect: false 跳过以上全部，改用 workdir/scriptDir。

设置里会显示检测到的根目录及其来源，还有 跟随当前工作区 和 固定为当前路径 两个按钮。路径被拒时会指出你当前所在的文件夹，例如 path outside the configured roots: /etc · 当前工作区: /tmp（面板 → 设置 → 自动检测 / 使用当前工作区）。

智能体侧

matlab_run({ code | file, name? }) 通过同一套注册表运行一个脚本，返回其控制台文本，模型因此可以反复迭代 MATLAB 代码、读取输出、查看错误（包装器会打印 getReport(e,'extended')）。

测试 sh
node plugins/dsh-matlab-runner/test/host-unit.mjs # names, argv, config dialect, path containment, vars helper
node plugins/dsh-matlab-runner/test/client-smoke.mjs # loader shell + registration order
node plugins/dsh-matlab-runner/test/client-render.mjs # renders the panel body once against stubs
node plugins/dsh-matlab-runner/test/client-tokenize.mjs # highlighter token split (transpose vs string, comments, numbers)
node plugins/dsh-matlab-runner/test/livemd.mjs # .mlx parser, self-contained fixture
node plugins/dsh-matlab-runner/test/host-apply.mjs # the whole apply(): routes, tool, tree, vars, session (~40 s)
node plugins/dsh-matlab-runner/test/session.mjs # real MATLAB: boot, warm reuse, errors, figures, stop (~50 s)
node plugins/dsh-matlab-runner/test/host-run.mjs # real MATLAB batch path (needs an unsandboxed shell)

bin/check.mjs 是实机检查：它通过回环地址（DSH_GUI_URL，默认 http://127.0.0.1:54501）与运行中的应用通信，打印解析后的配置，运行一个脚本，验证下一次运行复用了会话，并通过 artifact 路由取回导出的图窗。通过即证明宿主侧已跑通、MATLAB 可达；只有页面才能证明标签页渲染正常。

MATLAB 测试在沙箱 shell 下会失败，这是设计使然——它们走的是应用所用的同一条 spawn 路径，而这条路径只在沙箱外存在。

限制

- 会话中第一个图窗约耗时 13 秒（Java/桌面初始化），之后约 2 秒。打开 warmFigures 可把这段开销挪到启动时。
- 不要用 MATLAB 内置函数名命名脚本（plot.m、mean.m 等）：run 会先解析脚本，把函数遮蔽掉，于是 plot.m 报错「不支持将脚本 plot 作为函数执行」。
- 每台主机只有一个会话，面板和智能体工具共用；长时间 pause 或死循环会阻塞该会话，直到你点 Stop。
- 变量面板只列出 base-workspace 变量，而且需要会话正在运行（首次运行前会显示「session not started」）。
- Windows 未测试；sessionArgs/extraArgs 和启动器路径需要调整。
- 首次成功运行（或手动 Save）之前，缓冲区只存在 localStorage 里，所以切换标签页、刷新页面都还在，但换浏览器或清空配置档就没了。
- 语法高亮是分词器，不是解析器：它不折叠代码块，% 出现在特殊上下文里仍可能被当成注释。
- .mlx 仅支持预览——面板只渲染 MATLAB 保存的内容，不能编辑或运行实时脚本（那需要 Live Editor 引擎）。从 Word 导入的实时脚本，章节数是启发式估算；块的顺序始终按文档顺序。
- 停止或重启会话时，会先让 MATLAB exit，不会留下 -nodesktop 进程。长时间运行的 -nodesktop MATLAB 会以 MATLAB 的 bundle id 注册到 macOS，导致在 Finder 里双击看起来没反应（无窗口实例接收了激活事件）。解决办法：open -n -a /Applications/MATLAB_R2026a.app，或退出会话；在 VS Code 里把 MATLAB.matlabConnectionTiming 设为 onDemand。
- 文件树以 workdir 为根，不跟随 DSH 工作区切换器，也不显示 git 状态。
- MATLAB 文件名必须以字母开头：生成的辅助文件叫 _vars.m 会报错「文本字符无效」。

License

MIT © 2026 seally-web