rencl3 / dsh-matlab-bridge

README.md

---

English

dsh-matlab-bridge

DeepSeek ↔ MATLAB R2025b deep interaction: a file-IPC bridge that lets an AI read, analyze, and modify code open in the MATLAB editor, and create, read, modify, and run Simulink models. No network, COM, or inter-process calls are involved.

Architecture

DSH plugin (Node.js, direct file IPC, no subprocess)
        │  writes task_*.json / reads resp_*.json
        ▼
%USERPROFILE%\.deepseek\{requests, responses}
        ▲
        │  MATLAB daemon polls every 2 seconds
        │
MATLAB: deepseek_daemon.m → deepseek_core.m
        → matlab.desktop.editor API / Simulink API

Components

Path	Description
index.js	DSH host plugin: registers 20 matlab_* tools, direct file IPC
package.json / cordis.patch.yml	Plugin package declaration and bundle layer
matlab/deepseek_core.m	MATLAB core: 20 actions (9 editor + 11 Simulink)
matlab/deepseek_daemon.m	Daemon: polls requests, writes back responses every 2 s
python/deepseek_matlab_bridge.py	Standalone Python bridge (CLI / non-DSH use, optional)
python/deepseek_connect.py	One-shot connectivity check (optional)

Quick start

Step 1: MATLAB side (required)

Copy the two MATLAB files into the MATLAB install directory (adjust the example path):

New-Item -ItemType Directory -Force -Path "D:\Program Files\MATLAB\R2025b\toolbox\local\DeepSeek" | Out-Null
Copy-Item matlab\deepseek_core.m, matlab\deepseek_daemon.m -Destination "D:\Program Files\MATLAB\R2025b\toolbox\local\DeepSeek"

Start the daemon in the MATLAB command window:

rehash toolboxcache
addpath(fullfile(matlabroot, 'toolbox', 'local', 'DeepSeek'))
deepseek_daemon()

You should see [DeepSeek] Daemon started (poll: 2s).

Auto-start on MATLAB launch (optional): add the addpath(...) and deepseek_daemon() lines above to the end of your toolbox\local\startup.m, and MATLAB will start the daemon automatically on every launch.

Step 2: DSH plugin (available to all sessions)

1. Copy package.json, index.js, and cordis.patch.yml from the repo root into the profile's node_modules:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-matlab-bridge" | Out-Null
Copy-Item package.json, index.js, cordis.patch.yml -Destination "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-matlab-bridge"

2. Append to %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml:

- insert:
    - id: dsh-matlab-bridge
      name: dsh-matlab-bridge

3. Restart DeepSeek Harness. Agents in every session can then call the matlab_* tools.

Step 3: Python bridge (optional, non-DSH / CLI use)

py python\deepseek_matlab_bridge.py ping

Tools (20)

Tool	Description
matlab_ping	Connectivity check; returns MATLAB version
matlab_eval	Execute MATLAB code
matlab_get_workspace	List base workspace variables
matlab_get_command_history	Read command history
matlab_get_active_editor	Active editor file + content + cursor
matlab_get_all_editors	All open editors
matlab_get_file_content	Read a file (editor first, then disk)
matlab_replace_text	Replace a text fragment precisely
matlab_open_file	Open a file in the editor
matlab_list_models	List open Simulink models
matlab_get_model_info	Model blocks and lines
matlab_open_model	Open a .slx/.mdl
matlab_close_model	Close a model (no save)
matlab_run_simulation	Run a simulation
matlab_get_block_param	Read a block parameter
matlab_set_block_param	Write a block parameter
matlab_add_block	Add a block
matlab_delete_block	Delete a block
matlab_add_line	Connect two ports
matlab_delete_line	Delete a line

Key constraints

1. Never start a new MATLAB: communicate only via file IPC with an already-running MATLAB; if the daemon is down, ask the user to run deepseek_daemon() rather than launching it.
2. Minimal, precise edits: replace_text should only replace the smallest fragment (one line, one variable name).
3. No GUI operations: never open MATLAB/Simulink GUI windows or tell the user to operate the GUI manually.
4. Read workspace via evalin: to read base-workspace variables, use evalin('base', ...), not eval.

Naming

This project uses deepseek as the concrete implementation (directory %USERPROFILE%\.deepseek\, functions deepseek_core / deepseek_daemon). To adapt it for another AI, replace deepseek → <your-name>, .deepseek → .<your-name>, and DeepSeek → <Your-Name> throughout.

Troubleshooting

Symptom	Fix
Request timeout	Daemon not running; run deepseek_daemon() in MATLAB
Function not recognized	rehash toolboxcache, then addpath again
Stale daemon cache	clear all; rehash toolboxcache, then deepseek_daemon() again

License

MIT

---

简体中文

dsh-matlab-bridge

DeepSeek ↔ MATLAB R2025b 深度交互：通过文件 IPC让 AI 读取、分析、修改 MATLAB 编辑器中的代码，以及创建、读取、修改、运行 Simulink 模型。全程不涉及网络、COM 或进程间调用。

架构

DSH 插件 (Node，直接文件 IPC，无子进程)
        │  写 task_*.json / 读 resp_*.json
        ▼
%USERPROFILE%\.deepseek\{requests, responses}
        ▲
        │  MATLAB daemon 每 2 秒轮询一次
        │
MATLAB：deepseek_daemon.m → deepseek_core.m
        → matlab.desktop.editor API / Simulink API

组件

路径	说明
index.js	DSH host 插件：注册 20 个 matlab_* 工具，直接文件 IPC
package.json / cordis.patch.yml	插件包声明与 bundle 层
matlab/deepseek_core.m	MATLAB 核心：20 个 action（编辑器 9 + Simulink 11）
matlab/deepseek_daemon.m	守护进程：2 秒轮询 requests、写回 responses
python/deepseek_matlab_bridge.py	独立 Python 桥（CLI / 非 DSH 场景，可选）
python/deepseek_connect.py	一键连通性检查（可选）

快速开始

第一步：MATLAB 端（必需）

把 MATLAB 端两个文件复制到 MATLAB 安装目录（示例路径按实际调整）：

New-Item -ItemType Directory -Force -Path "D:\Program Files\MATLAB\R2025b\toolbox\local\DeepSeek" | Out-Null
Copy-Item matlab\deepseek_core.m, matlab\deepseek_daemon.m -Destination "D:\Program Files\MATLAB\R2025b\toolbox\local\DeepSeek"

在 MATLAB 命令窗口启动守护进程：

rehash toolboxcache
addpath(fullfile(matlabroot, 'toolbox', 'local', 'DeepSeek'))
deepseek_daemon()

看到 [DeepSeek] Daemon started (poll: 2s) 即就绪。

开机自启（可选）：把上面 addpath(...) 与 deepseek_daemon() 两行加到你的 toolbox\local\startup.m 末尾，MATLAB 每次启动就会自动拉起守护进程。

第二步：DSH 插件（让所有会话都能用）

1. 把仓库根目录的 package.json、index.js、cordis.patch.yml 复制到 profile 的 node_modules：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-matlab-bridge" | Out-Null
Copy-Item package.json, index.js, cordis.patch.yml -Destination "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-matlab-bridge"

2. 在 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml 末尾追加：

- insert:
    - id: dsh-matlab-bridge
      name: dsh-matlab-bridge

3. 重启 DeepSeek Harness，所有会话的 agent 即可调用 matlab_* 工具。

第三步：Python 桥（可选，非 DSH / CLI 场景）

py python\deepseek_matlab_bridge.py ping

工具清单（20 个）

工具	说明
matlab_ping	连通性测试，返回 MATLAB 版本
matlab_eval	执行 MATLAB 代码
matlab_get_workspace	列出 base 工作区变量
matlab_get_command_history	读取命令历史
matlab_get_active_editor	活动编辑器文件 + 内容 + 光标
matlab_get_all_editors	所有已打开编辑器
matlab_get_file_content	读文件（先编辑器后磁盘）
matlab_replace_text	精确替换文本片段
matlab_open_file	编辑器打开文件
matlab_list_models	列出已打开 Simulink 模型
matlab_get_model_info	模型模块与连线
matlab_open_model	打开 .slx/.mdl
matlab_close_model	关闭模型（不保存）
matlab_run_simulation	运行仿真
matlab_get_block_param	读模块参数
matlab_set_block_param	写模块参数
matlab_add_block	添加模块
matlab_delete_block	删除模块
matlab_add_line	连接端口
matlab_delete_line	删除连线

关键约束

1. 永不启动新 MATLAB：只通过文件 IPC 与已运行的 MATLAB 通信；daemon 未运行时提示用户手动执行 deepseek_daemon()，不做自动拉起。
2. 精确最小化修改：replace_text 只替换最小片段（如一行代码、一个变量名）。
3. 禁止 GUI 操作：严禁打开 MATLAB/Simulink GUI 窗口，或建议用户手动操作 GUI。
4. eval 读工作区：读 base 工作区变量须用 evalin('base', ...) 而非 eval。

命名约定

本项目以 deepseek 为具体实现（目录 %USERPROFILE%\.deepseek\，函数 deepseek_core / deepseek_daemon）。如需换成其他 AI 名字，把代码中的 deepseek → <你的名字>、.deepseek → .<你的名字>、DeepSeek → <你的名字> 即可。

故障排查

现象	处理
请求超时	daemon 未运行，在 MATLAB 中执行 deepseek_daemon()
函数无法识别	rehash toolboxcache 后重新 addpath
daemon 缓存旧版	clear all; rehash toolboxcache 后重新 deepseek_daemon()

License

MIT