dsh-matlab-bridge

Readme

[README.md](https://github.com/user-attachments/files/31134724/README.md)
<div align="center">

**🌐 Language / 语言：** [**English**](#english) · [**简体中文**](#chinese)

</div>

---

<a id="english"></a>
## 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):

```powershell
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:

```matlab
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:

```powershell
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`:

```yaml
- 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)**

```bash
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

---

<a id="chinese"></a>
## 简体中文

### 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 安装目录（示例路径按实际调整）：

```powershell
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 命令窗口启动守护进程：

```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：

```powershell
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` 末尾追加：

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

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

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

```bash
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