dsh-matlab-workbench 0.0.0-stage → 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH-MATLAB-Workbench contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,57 @@
+# DSH-MATLAB-Workbench
+
+[简体中文](README.md) · [Installation](#installation) · [Real PID demo](#real-pid-sweep-demo)
+
+An independent **DSH Desktop** community plugin (`v0.1.0-beta.2`) for MATLAB experiments. The Agent executes code through the **official MathWorks MATLAB MCP Server**; Workbench prepares session-owned experiments, verifies MATLAB-generated PNG/CSV/numeric metrics, attaches images to the conversation, and displays PID sweep comparisons. It does not bundle MATLAB, replace the official MCP server, or estimate precise metrics from image pixels.
+
+**Beyond a generic MCP bridge:** unique immutable experiment IDs; PNG CRC and SHA-256 integrity checks; MATLAB-sourced metrics; explicit Agent `read_image` attachments; PID gain validation; progress, error and uncertain-outcome states; individual plots and overlays.
+
+**Beta v0.1.0-beta.2 evidence:** On October 25, 2026, one real DSH Desktop 0.2.1-rc.2 session used official MATLAB MCP v0.15.0 with MATLAB R2025b, generated 3 runs / 4 PNGs, verified CSV and metrics, displayed the comparison tabs and supported Agent analysis. **A fresh-user installation of the portable connection example below has not yet been verified.** Historical M1 acceptance remains **FAIL** due to unresolved lifecycle issues; see [known limitations](docs/known-limitations.md).
+
+## Requirements
+
+- Windows x64 and DSH Desktop. Tested: 0.2.1-rc.2. The manifest also allows 0.2.1-rc.3, whose real Desktop installation has **not** been tested.
+- An independently licensed, installed MATLAB. Tested: **R2025b**. Consult [MathWorks](https://github.com/matlab/matlab-mcp-server) for the MCP server's wider MATLAB version support. This example uses base MATLAB `ode45`, with no Control System Toolbox.
+- The separately installed [official MATLAB MCP Server](https://github.com/matlab/matlab-mcp-server/releases) (tested **v0.15.0**). Neither its binary nor MATLAB or a license is distributed with this plugin.
+- A DSH Agent that exposes `evaluate_matlab_code`, `run_matlab_file`, and the host's `read_image` attachment tool.
+
+## Installation
+
+1. In an environment with the DSH CLI installed and the target profile initialized, run `npx @deepseek-ai/dsh plugin --profile desktop add dsh-matlab-workbench@beta`. This installs the package selected by the npm `beta` dist-tag. Replace `desktop` if your DSH Desktop uses a different profile name. A local source directory remains useful for development, but is not evidence of the published-package install.
+2. Install the official Windows binary named `matlab-mcp-server-windows-x64.exe` from its v0.15.0 release; put its directory and MATLAB's `bin` directory on the PATH seen by Desktop. Test from the same Windows environment with `matlab-mcp-server-windows-x64.exe --version` and `matlab -batch "disp(version)"`. Restart Desktop normally **only after saving your active session** if PATH changes need to be picked up.
+3. **If there is no existing MATLAB MCP connection:** in Desktop **Settings → Plugins**, use the local-directory installer for `integration/matlab-mcp-gate`. This editable, public [connection example](integration/matlab-mcp-gate/cordis.patch.yml) registers **one** `matlab` stdio server using the official executable on PATH, in `new/nodesktop` mode. It contains no private or machine-specific paths. **Skip this step if a `matlab` server is already registered.** To customize binary paths/flags, copy the example into your own configuration directory and edit that copy; do not patch DSH core.
+4. Activate the installed bundle through the DSH Desktop profile/plugin workflow. Bundle installation or updates may require a normal Desktop restart; save active sessions first and do not register a second `matlab` MCP connection. This Beta has not yet passed a fresh Desktop installation test.
+5. Confirm the Agent sees `evaluate_matlab_code`, `run_matlab_file`, `dsh_matlab_prepare_sweep` and `dsh_matlab_collect_sweep`; check for **PID Input**, **MATLAB Figures**, and **PID Experiments** tabs. Use a session workspace with local write access. On startup failure, inspect the server executable/PATH and existing `matlab` registrations before changing configuration. Avoid automatically retrying MATLAB writes.
+
+The one-machine M3 test used a private Gate wiring configuration, but **users do not depend on that setup**. The public connection example uses the same DSH MCP client settings format; **it has not yet passed a clean-machine installation test**. This plugin does not edit the Desktop profile, MATLAB `startup.m`, or unrelated plugins automatically.
+
+## Real PID sweep demo
+
+In **PID Input**, enter one `Kp,Ki,Kd` set per line, validate, and send the generated Agent message in the **same Desktop session**:
+
+```text
+1,0.5,0.2
+3,1,0.5
+2,0.8,0.9
+```
+
+The Agent runs `dsh_matlab_prepare_sweep`, executes the returned `setupCode` and `executeCode` with the **official** `evaluate_matlab_code`, confirms the completion marker, calls `dsh_matlab_collect_sweep` to verify all CSV/metrics/plots and the overlay, then calls `read_image` for **every** returned PNG. Preparation is not execution. Unverified/incomplete sweeps must not appear as completed comparisons.
+
+Actual MATLAB R2025b metrics from the October 25, 2026, real Desktop demonstration, for a 12-second simulation window:
+
+| Kp, Ki, Kd | IAE ↓ | ISE | 2% settling | Overshoot |
+| --- | ---: | ---: | ---: | ---: |
+| 1, 0.5, 0.2 | 1.9249665 | 0.6647999 | Undetermined in window | 0% |
+| 3, 1, 0.5 | **0.9647213** | 0.2703758 | 9.10 s | 0% |
+| 2, 0.8, 0.9 | 1.2256675 | 0.4373808 | 8.71 s | 0% |
+
+Controller 2 has the lowest window IAE; controller 3 settles sooner. The fixed example plant is `y''+2ζωy'+ω²y=ω²u` (ζ=0.48, ω=3 rad/s), integrated with base MATLAB `ode45`. These are not hardware results or universal tuning recommendations. Session outputs are stored in `.dsh-matlab/`; do not publish the entire private session workspace.
+
+## Development, feedback, limits
+
+Run `npm run check` for syntax and `npm test` for Node regression tests using synthetic, non-private fixtures. `npm run test:matlab:m2` is an optional **standalone MATLAB** integration test (MATLAB on PATH or `MATLAB_EXE`) and is **not** a Desktop MCP acceptance test. Node 24 is the tested development environment; the plugin uses no third-party runtime npm packages.
+
+Please file issues through the project's GitHub **Issues** page with sanitized reproduction steps and DSH/MATLAB/MCP version numbers, never tokens or private session logs. Suggested GitHub topics: `dsh-plugin`, `deepseek-harness`, `matlab`, `pid`, `simulation`. This is an **unofficial community project** unaffiliated with and not endorsed by DSH/DeepSeek or MathWorks. MATLAB® is a MathWorks trademark; users need their own MATLAB authorization and must follow its license. Project code: [MIT](LICENSE).
+
+**Known limitations:** the historical M1 disable/tab lifecycle failure remains unresolved; `link:` uninstallation can leave a junction; cancelling or timing out a MATLAB MCP request does not prove execution stopped. See [known limitations and evidence scope](docs/known-limitations.md). Only one Windows/DSH/MATLAB combination has been verified. `nodesktop` does not guarantee that all MATLAB graphics commands avoid windows.
+

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# DSH-MATLAB-Workbench
+
+[English](README.en.md) · [安装 / Installation](#安装) · [真实 PID Demo](#真实-pid-实验-demo)
+
+面向 **DSH Desktop** 的 MATLAB 工程实验工作台（社区插件，`v0.1.0-beta.2`）。Agent 通过 **MathWorks 官方 MATLAB MCP Server** 执行 MATLAB；本插件在同一 DSH 会话中准备实验、核验 MATLAB 产出的 PNG/CSV/数值指标、显示实验曲线和 PID 参数扫描对比。它不内置 MATLAB、不代替官方 MCP，也不会把图片中的像素当成精确指标。
+
+**与通用 MATLAB MCP 桥接的区别：** 每次实验使用独立且不可覆盖的 ID；对图像做 PNG/CRC/SHA-256 校验，核对 CSV 和 MATLAB 指标来源；通过 `read_image` 让 Agent 真正获取图片附件；Desktop 有参数输入、运行/核验/加载/失败状态、单组曲线和叠加对比。Agent 仍需明确执行和检查每一步。
+
+**Beta 状态（v0.1.0-beta.2）：** 真实 DSH Desktop（0.2.1-rc.2）→ 官方 MATLAB MCP（v0.15.0）→ MATLAB R2025b → 3 组 PID / 4 张 PNG / CSV / 指标 → Desktop 展示及 Agent 分析，已于 2026-10-25 在一台开发机完成。**下面面向新用户的独立安装流程尚未在全新环境验收**，不能据此保证所有 DSH/MATLAB 组合可用。历史 M1 正式验收为 **FAIL**；[已知限制](docs/known-limitations.md)。
+
+## 前置条件
+
+- Windows x64、DSH Desktop；已验证版本为 DSH Desktop 0.2.1-rc.2（`package.json` 声明兼容 0.2.1-rc.2/rc.3，但 rc.3 尚未实机验证）。
+- 有效的 MATLAB 授权与可执行的 MATLAB；实测为 **R2025b**。官方 MCP Server 支持的 MATLAB 版本范围请以 [MathWorks 文档](https://github.com/matlab/matlab-mcp-server) 为准。此仓库的示例只验证 R2025b；不需要 Control System Toolbox。
+- 单独安装 [官方 MATLAB MCP Server](https://github.com/matlab/matlab-mcp-server/releases)（实测 **v0.15.0**）。它和 MATLAB 本体及许可证均**不随插件分发**。
+- Agent 必须能调用 `evaluate_matlab_code` / `run_matlab_file`，并支持 DSH 的 `read_image` 图片附件。
+
+## 安装
+
+1. 在已安装 DSH CLI 且已初始化目标 profile 的环境运行 `npx @deepseek-ai/dsh plugin --profile desktop add dsh-matlab-workbench@beta`。此命令从 npm 安装 Beta dist-tag 指向的包；如你的 DSH Desktop 使用其他 profile 名称，请把 `desktop` 替换为该名称。源码目录安装仍可用于开发，不是本次发布的安装验收证据。
+2. 在 Windows 安装官方 MATLAB MCP Server v0.15.0 的 `matlab-mcp-server-windows-x64.exe`。将其所在目录与 MATLAB 的 `bin` 目录加入当前 Desktop 可见的 `PATH`。可先从同一 Windows 环境检查 `matlab-mcp-server-windows-x64.exe --version` 和 `matlab -batch "disp(version)"`。PATH 改动可能要重新启动 Desktop 才能生效；**保存当前会话后**再正常重启。
+3. **只有 Desktop 尚未连接 MATLAB MCP 时**，在 Desktop **设置 → 插件**的本地目录安装入口选取 `integration/matlab-mcp-gate`。这是开源的可编辑**连接示例**，使用 PATH 上的官方 MCP，可查看 [连接配置](integration/matlab-mcp-gate/cordis.patch.yml)，默认 `new/nodesktop`；它不含私有文件路径。已有一个 `matlab` server 的用户**跳过此步**，避免重复注册。需要定制参数时，先复制该示例到自己的配置目录后修改（例如绝对程序路径），不要改 DSH 核心。
+4. 安装后按 DSH Desktop 的 profile/插件管理流程激活该 bundle。Bundle 安装或更新可能需要正常重启 Desktop；先保存会话，且不要重复添加 `matlab` MCP 连接。此 Beta 尚未完成全新 Desktop 环境验收。
+5. 确认当前 Agent 的可用工具中出现 `evaluate_matlab_code`、`run_matlab_file`、`dsh_matlab_prepare_sweep`、`dsh_matlab_collect_sweep`，以及 Workbench 的「PID 参数准备」「MATLAB 图像」「PID 实验对比」页签。在有写入权限的本地工作区开启会话。若有 MCP 启动错误，检查二进制和 MATLAB 的 PATH、Windows 进程环境及是否重复注册；不要盲目重复安装或重试有写入的 MATLAB 调用。
+
+**注意：** 本机测试曾使用独立的私有 Gate 接线与本地 `link:`；这不是新用户的安装依赖。上面的可移植连接示例是按相同 DSH MCP Client 配置格式提供，**尚未在一台全新 Desktop 做独立安装验收**。本项目不自动修改 Desktop profile、MATLAB `startup.m` 或其他插件。
+
+## 真实 PID 实验 Demo
+
+打开「PID 参数准备」，每行输入一组 `Kp,Ki,Kd`，然后单击「检查并生成 Agent 指令」，把生成的消息发到**同一会话**：
+
+```text
+1,0.5,0.2
+3,1,0.5
+2,0.8,0.9
+```
+
+Agent 调 `dsh_matlab_prepare_sweep` 得到 `setupCode`、`executeCode`、`sweepId`；经**官方** `evaluate_matlab_code` 执行代码，检查完成标记；再调 `dsh_matlab_collect_sweep` 验证 3 组 CSV/指标/PNG 和叠加图；最后对返回的**每张** PNG 调 `read_image`。Desktop 页面随后按会话展示曲线与对比指标。准备阶段不会执行 MATLAB；未核验完整产物不能视为成功。
+
+以下是 2026-10-25 **真实 MATLAB R2025b 运行**产生的 12 秒窗口示例指标（不是 AI 看图估算）：
+
+| Kp, Ki, Kd | IAE ↓ | ISE | 2% 调节时间 | 超调 |
+| --- | ---: | ---: | ---: | ---: |
+| 1, 0.5, 0.2 | 1.9249665 | 0.6647999 | 窗口内未确定 | 0% |
+| 3, 1, 0.5 | **0.9647213** | 0.2703758 | 9.10 s | 0% |
+| 2, 0.8, 0.9 | 1.2256675 | 0.4373808 | 8.71 s | 0% |
+
+组 2 在本次窗口内 IAE 最低，组 3 调节更快。示例使用 MATLAB `ode45`，对象 `y''+2ζωy'+ω²y=ω²u`（ζ=0.48，ω=3 rad/s），并非通用 PID 自动整定；结果不代表真实硬件性能。结果文件位于会话工作区的 `.dsh-matlab/`，请勿上传包含个人会话数据的整个工作区。
+
+## 开发、反馈与限制
+
+`npm run check` 执行源码语法检查，`npm test` 执行不依赖私有验收图的 Node 测试；`npm run test:matlab:m2` 是可选的独立 MATLAB 测试（本机 MATLAB 需在 PATH，可设 `MATLAB_EXE`），**无法替代 Desktop MCP 端到端验收**。Node 24 是开发测试基线，插件运行本身没有第三方 npm 依赖。
+
+问题反馈请使用本项目 GitHub 仓库的 **Issues**，注明 DSH Desktop / MATLAB / MCP 版本、所见步骤及脱敏错误，不上传会话、令牌或私有日志。仓库建议 Topics：`dsh-plugin`、`deepseek-harness`、`matlab`、`pid`、`simulation`。社区项目，**非 DeepSeek/DSH 或 MathWorks 官方产品，不获其背书**。MATLAB® 属于 MathWorks；使用者须自行遵守 MATLAB 授权条款。本项目源码采用 [MIT](LICENSE)。
+
+**已知限制：** M1 历史生命周期/停用页签残留未明确根因，部分目录链接卸载后可能遗留 junction；取消或超时并不证明 MATLAB 已停止，不能自动重跑同一有写入任务。见 [限制与验收事实](docs/known-limitations.md)。测试中仅验证一套本机组合；`nodesktop` 不保证所有 MATLAB 图形操作都无窗口。
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: dsh-matlab-workbench
+      name: dsh-matlab-workbench
+      config: {}

package/core/figures.mjs

@@ -0,0 +1,127 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { crc32 } from 'node:zlib';
+
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+function pngDimensions(bytes) {
+  if(bytes.length<33||!bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])))throw Error('Invalid PNG signature');
+  let offset=8,first=true,idatBytes=0,ended=false,width=0,height=0;
+  while(offset<bytes.length) {
+    if(bytes.length-offset<12)throw Error('Truncated PNG chunk');
+    const length=bytes.readUInt32BE(offset),end=offset+12+length;
+    if(end>bytes.length)throw Error('Truncated PNG data');
+    const type=bytes.toString('ascii',offset+4,offset+8);
+    if(!/^[A-Za-z]{4}$/.test(type)||crc32(bytes.subarray(offset+4,end-4))!==bytes.readUInt32BE(end-4))throw Error('Invalid PNG chunk CRC');
+    if(first) {
+      if(type!=='IHDR'||length!==13)throw Error('Invalid PNG IHDR');
+      width=bytes.readUInt32BE(offset+8);height=bytes.readUInt32BE(offset+12);first=false;
+    } else if(type==='IHDR')throw Error('Duplicate PNG IHDR');
+    if(type==='IDAT')idatBytes+=length;
+    if(type==='IEND') { if(length!==0||end!==bytes.length)throw Error('Invalid PNG end');ended=true; }
+    offset=end;
+  }
+  if(!ended||!idatBytes||!width||!height||width*height>40_000_000)throw Error('Incomplete PNG or invalid dimensions');
+  return {width,height};
+}
+export function matlabLiteral(value) {
+  if (typeof value !== 'string' || /[\x00-\x1f]/.test(value)) throw Error('Invalid MATLAB string');
+  return `'${value.replaceAll("'", "''")}'`;
+}
+export function requireId(id) { if (!UUID.test(id)) throw Error('Invalid UUID'); return id; }
+export async function checkedDirectory(dir) {
+  if (!path.isAbsolute(dir) || /^(\\\\[?.]\\|\\\\)/.test(dir)) throw Error('An absolute local path is required');
+  const absolute=path.resolve(dir);
+  let current=path.parse(absolute).root;
+  for (const part of absolute.slice(current.length).split(path.sep).filter(Boolean)) {
+    current=path.join(current,part);
+    const stat=await fs.lstat(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw Error('Directory links/reparse paths are not accepted');
+  }
+  const real=await fs.realpath(absolute);
+  if (path.relative(absolute,real)!=='') throw Error('Physical directory differs from requested directory');
+  return real;
+}
+async function childDirectory(parent,name,create=false) {
+  await checkedDirectory(parent);
+  const dir=path.join(parent,name);
+  if(create) { try { await fs.mkdir(dir); } catch(e) { if(e.code!=='EEXIST')throw e; } }
+  return checkedDirectory(dir);
+}
+async function runDirectory(workspace,runId) {
+  requireId(runId);
+  const root=await childDirectory(await checkedDirectory(workspace),'.dsh-matlab');
+  return childDirectory(await childDirectory(root,'runs'),runId);
+}
+async function fileBytes(dir,name,cap) {
+  await checkedDirectory(dir);
+  const file=path.join(dir,name),stat=await fs.lstat(file);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.size>cap)throw Error(`Invalid or oversized artifact: ${name}`);
+  const handle=await fs.open(file,'r');
+  try {
+    const opened=await handle.stat();
+    if(opened.size!==stat.size||opened.ino!==stat.ino)throw Error('Artifact changed while opening');
+    const bytes=await handle.readFile();
+    if(bytes.length>cap)throw Error('Artifact exceeds limit');
+    return bytes;
+  } finally { await handle.close(); }
+}
+const json = async (dir,name) => JSON.parse((await fileBytes(dir,name,1024*1024)).toString('utf8'));
+export async function prepareRun(workspace,helperDir,provenance={}) {
+  const base=await checkedDirectory(workspace);
+  const root=await childDirectory(base,'.dsh-matlab',true);
+  const runs=await childDirectory(root,'runs',true);
+  const runId=randomUUID(),imageId=randomUUID();
+  const runDir=await childDirectory(runs,runId,true);
+  const helper=await checkedDirectory(helperDir);
+  const prepared={schemaVersion:1,status:'prepared',runId,imageId,runDir,createdUtc:new Date().toISOString(),provenance};
+  await fs.writeFile(path.join(runDir,'prepared.json'),JSON.stringify(prepared,null,2),{flag:'wx'});
+  return {...prepared,setupCode:`addpath(${matlabLiteral(helper)});`,exportCode:`dsh_m1_save_figure(fig, ${matlabLiteral(runDir)}, ${matlabLiteral(imageId)}, 'Simulation result');`,next:'Execute MATLAB through the official MCP; preparation is not execution. Then collect and call read_image.'};
+}
+export async function collectFigure(workspace,runId) {
+  const dir=await runDirectory(workspace,runId);
+  const prepared=await json(dir,'prepared.json');
+  requireId(prepared.imageId);
+  if(prepared.schemaVersion!==1||prepared.runId!==runId||prepared.runDir!==dir)throw Error('Invalid preparation record');
+  const metadata=await json(dir,'figure.json');
+  const name=prepared.imageId+'.png';
+  if(metadata.schemaVersion!==1||metadata.imageId!==prepared.imageId||metadata.file!==name||typeof metadata.title!=='string'||metadata.title.length>200)throw Error('Figure metadata does not match preparation');
+  const bytes=await fileBytes(dir,name,16*1024*1024);
+  const {width,height}=pngDimensions(bytes);
+  let metrics=null,data=null;
+  try { metrics=await json(dir,'metrics.json'); } catch(e) { if(e.code!=='ENOENT')throw e; }
+  if(metrics!==null) {
+    if(metrics.source!=='MATLAB'||typeof metrics.method!=='string'||!Number.isFinite(metrics.sampleInterval_s)||!Number.isFinite(metrics.window_s))throw Error('Missing MATLAB metric provenance');
+    const samples=await fileBytes(dir,'samples.csv',16*1024*1024);
+    data={file:path.join(dir,'samples.csv'),sha256:hash(samples),bytes:samples.length};
+  }
+  const artifact={schemaVersion:1,status:'artifact_ready',runId,imageId:prepared.imageId,path:path.join(dir,name),sha256:hash(bytes),bytes:bytes.length,width,height,title:metadata.title,exportedUtc:metadata.exportedUtc,metrics,data,provenance:prepared.provenance};
+  const destination=path.join(dir,'artifact.json');
+  try { const prior=await json(dir,'artifact.json'); if(JSON.stringify(prior)!==JSON.stringify(artifact))throw Error('Collected artifact changed; create a new run'); }
+  catch(e) { if(e.code!=='ENOENT')throw e; const temporary=path.join(dir,randomUUID()+'.tmp'); await fs.writeFile(temporary,JSON.stringify(artifact,null,2),{flag:'wx'}); await fs.rename(temporary,destination); }
+  return artifact;
+}
+export async function collectStandaloneFigure(workspace,runId) {
+  const dir=await runDirectory(workspace,runId);
+  const prepared=await json(dir,'prepared.json');
+  if(prepared.provenance?.sweepId)throw Error('PID runs must be indexed through dsh_matlab_collect_sweep after the whole sweep completes');
+  return collectFigure(workspace,runId);
+}
+export async function listFigures(workspace,{includeSweeps=true}={}) {
+  const root=path.join(await checkedDirectory(workspace),'.dsh-matlab','runs');
+  try { await checkedDirectory(root); } catch(e) { if(e.code==='ENOENT')return []; throw e; }
+  const entries=await fs.readdir(root,{withFileTypes:true}),figures=[];
+  for(const entry of entries) {
+    if(!UUID.test(entry.name))continue;
+    if(entry.isSymbolicLink())throw Error('Unexpected run link');
+    if(!entry.isDirectory())continue;
+    try {
+      await fs.access(path.join(root,entry.name,'artifact.json'));
+      if(!includeSweeps&&(await json(path.join(root,entry.name),'prepared.json')).provenance?.sweepId)continue;
+      figures.push(await collectFigure(workspace,entry.name));
+    }
+    catch(e) { if(e.code!=='ENOENT')throw e; }
+  }
+  return figures;
+}

package/core/sweeps.mjs

@@ -0,0 +1,96 @@
+import {promises as fs} from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {checkedDirectory, prepareRun, collectFigure, matlabLiteral, requireId} from './figures.mjs';
+
+const maxRuns=12;
+function validateParameters(parameters) {
+  if(!Array.isArray(parameters)||parameters.length<2||parameters.length>maxRuns)throw Error('PID sweep requires 2–12 parameter sets');
+  const seen=new Set();
+  return parameters.map((row,index)=>{
+    if(!row||typeof row!=='object'||Array.isArray(row)||Object.keys(row).sort().join(',')!=='kd,ki,kp')throw Error(`Invalid PID row ${index+1}`);
+    for(const name of ['kp','ki','kd'])if(typeof row[name]!=='number'||!Number.isFinite(row[name])||row[name]<0||row[name]>100)throw Error(`Invalid ${name} in PID row ${index+1}: use a finite number from 0 to 100`);
+    // The sample plant has a stable closed loop iff this Routh condition holds for ki>0.
+    const a2=2*0.48*3+9*row.kd,a1=9*(1+row.kp),a0=9*row.ki;
+    if(row.ki>0&&a2*a1<=a0)throw Error(`Unstable PID row ${index+1} for the documented sample plant`);
+    const key=JSON.stringify([row.kp,row.ki,row.kd]);
+    if(seen.has(key))throw Error(`Duplicate PID row ${index+1}: each experiment must use different gains`);
+    seen.add(key);
+    return {kp:row.kp,ki:row.ki,kd:row.kd};
+  });
+}
+async function child(parent,name,create=false) {
+  const root=await checkedDirectory(parent),target=path.join(root,name);
+  if(create) { try {await fs.mkdir(target);}catch(e){if(e.code!=='EEXIST')throw e;} }
+  return checkedDirectory(target);
+}
+async function sweepsRoot(workspace,create=false) {
+  const root=await child(await checkedDirectory(workspace),'.dsh-matlab',create);
+  return child(root,'sweeps',create);
+}
+async function sweepDir(workspace,sweepId) {return child(await sweepsRoot(workspace),requireId(sweepId));}
+async function readRecord(dir,name) {
+  const target=path.join(await checkedDirectory(dir),name),stat=await fs.lstat(target);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.size>128*1024)throw Error(`Invalid sweep record: ${name}`);
+  return JSON.parse(await fs.readFile(target,'utf8'));
+}
+export async function prepareSweep(workspace,helperDir,parameters) {
+  const rows=validateParameters(parameters);
+  const base=await checkedDirectory(workspace),helper=await checkedDirectory(helperDir);
+  const root=await sweepsRoot(base,true),sweepId=randomUUID(),dir=await child(root,sweepId,true);
+  const items=[];
+  for(const [index,params] of rows.entries()) {
+    const run=await prepareRun(base,helper,{kind:'pid_sweep',sweepId,index,parameters:params});
+    items.push({index,parameters:params,runId:run.runId,imageId:run.imageId,runDir:run.runDir});
+  }
+  const comparison=await prepareRun(base,helper,{kind:'pid_comparison',sweepId});
+  const record={schemaVersion:2,kind:'pid_sweep',status:'prepared',sweepId,sweepDir:dir,createdUtc:new Date().toISOString(),plant:{model:'y_second_order_pid',zeta:0.48,wn_rad_s:3,reference:1,sampleInterval_s:0.01,window_s:12},items,comparison:{runId:comparison.runId,imageId:comparison.imageId,runDir:comparison.runDir}};
+  await fs.writeFile(path.join(dir,'sweep.json'),JSON.stringify(record,null,2),{flag:'wx'});
+  return {...record,setupCode:`addpath(${matlabLiteral(helper)});`,executeCode:`dsh_m2_pid_sweep(${matlabLiteral(dir)});`,next:'Run setupCode and executeCode through the official MATLAB MCP. After the success marker, call dsh_matlab_collect_sweep; then read_image for each returned PNG, especially the comparison overlay.'};
+}
+async function loadSweep(workspace,sweepId) {
+  const dir=await sweepDir(workspace,sweepId),record=await readRecord(dir,'sweep.json');
+  if(record.schemaVersion!==2||record.kind!=='pid_sweep'||record.sweepId!==sweepId||record.sweepDir!==dir||record.status!=='prepared')throw Error('Invalid sweep manifest');
+  const parameters=validateParameters(record.items?.map(x=>x.parameters));
+  if(!Array.isArray(record.items)||!record.comparison||record.items.length!==parameters.length)throw Error('Invalid sweep items');
+  const ids=new Set();
+  for(const [index,item] of record.items.entries()) {
+    requireId(item.runId);requireId(item.imageId);
+    if(item.index!==index||ids.has(item.runId)||path.dirname(item.runDir)!==path.join(await checkedDirectory(workspace),'.dsh-matlab','runs')||path.basename(item.runDir)!==item.runId)throw Error('Invalid sweep run path');
+    ids.add(item.runId);
+  }
+  requireId(record.comparison.runId);requireId(record.comparison.imageId);
+  if(ids.has(record.comparison.runId)||record.comparison.runDir!==path.join(await checkedDirectory(workspace),'.dsh-matlab','runs',record.comparison.runId))throw Error('Invalid comparison run');
+  return record;
+}
+export async function collectSweep(workspace,sweepId) {
+  const manifest=await loadSweep(workspace,requireId(sweepId));
+  let completion;
+  try {completion=await readRecord(manifest.sweepDir,'completed.json');} catch(e){if(e.code==='ENOENT')throw Error('Sweep is incomplete: no MATLAB completion record');throw e;}
+  if(completion.schemaVersion!==2||completion.sweepId!==sweepId||completion.runCount!==manifest.items.length||typeof completion.completedUtc!=='string')throw Error('Invalid MATLAB completion record');
+  const figures=[];
+  for(const item of manifest.items) {
+    const figure=await collectFigure(workspace,item.runId);
+    const m=figure.metrics;
+    if(figure.imageId!==item.imageId||figure.provenance?.kind!=='pid_sweep'||figure.provenance.sweepId!==sweepId||figure.provenance.index!==item.index||JSON.stringify(figure.provenance.parameters)!==JSON.stringify(item.parameters)||m?.source!=='MATLAB'||m?.schemaVersion!==2||m?.kind!=='pid_step_response'||JSON.stringify(m.pid)!==JSON.stringify(item.parameters)||m.sampleInterval_s!==0.01||m.window_s!==12||!['within_recorded_window','not_determined_in_window'].includes(m.settlingStatus)||!['integratedAbsoluteError','integratedSquaredError','maxAbsoluteControl','overshoot_percent','analyticSteadyStateError'].every(key=>Number.isFinite(m[key])&&m[key]>=0)||!figure.data)throw Error('Sweep artifact or MATLAB metrics mismatch');
+    figures.push(figure);
+  }
+  const comparison=await collectFigure(workspace,manifest.comparison.runId);
+  if(comparison.imageId!==manifest.comparison.imageId||comparison.provenance?.kind!=='pid_comparison'||comparison.provenance.sweepId!==sweepId)throw Error('Comparison artifact mismatch');
+  figures.push(comparison);
+  return {kind:'dsh-matlab-figures',sweepId,figures,comparisonMetric:'integratedAbsoluteError',note:'IAE is integrated over the fixed 12 s window. Lower is better for this example; verify settling and control effort separately.'};
+}
+export async function listSweeps(workspace) {
+  let root;
+  try {root=await sweepsRoot(workspace);}catch(e){if(e.code==='ENOENT')return [];throw e;}
+  const entries=await fs.readdir(root,{withFileTypes:true}),results=[];
+  for(const entry of entries) {
+    if(!requireIdIfValid(entry.name))continue;
+    if(entry.isSymbolicLink())throw Error('Unexpected sweep link');
+    if(!entry.isDirectory())continue;
+    try {results.push(await collectSweep(workspace,entry.name));}
+    catch(e){if(e.message==='Sweep is incomplete: no MATLAB completion record')continue;throw e;}
+  }
+  return results;
+}
+function requireIdIfValid(value) {try{requireId(value);return true;}catch{return false;}}

package/dsh/client/index.js

@@ -0,0 +1,122 @@
+window.__ModuleLoader__.load({
+  id:'dsh-matlab-workbench',
+  factory(require) {
+    const React=require('react'),h=React.createElement;
+    const dictionaries={
+      zh:{figures:{tab:'MATLAB 图像',empty:'尚无已收集图像。请先运行 MATLAB，再调用 dsh_matlab_collect。',pending:'等待 Agent 调用 read_image',loading:'正在载入图像…',failed:'图像载入失败',source:'MATLAB 数值结果',expand:'放大 / 收起',boundary:'图像用于定性观察；精确数值来自 MATLAB 数据计算。'},compare:{tab:'PID 实验对比',empty:'尚无已完成并收集的 PID 扫描。',boundary:'指标由 MATLAB ode45 数据计算。按 12 秒窗口内 IAE 比较，不能代替稳定性、控制量和实际对象的验证。',overlay:'MATLAB 曲线叠加图',run:'组别',gain:'PID 参数 (Kp / Ki / Kd)',iae:'IAE ↓',ise:'ISE',overshoot:'超调 %',settling:'2% 调节时间 (s)',effort:'最大控制量',best:'本组最低 IAE',unknown:'未确定',curves:'单组实验曲线',status:'当前状态',preparing:'正在准备参数…',prepared:'已准备：请由 Agent 使用官方 MATLAB MCP 执行',running:'MATLAB MCP 正在执行…',awaiting:'MCP 返回了完成标记，等待产物核验',verifying:'正在校验全部 MATLAB 产物…',loading:'已核验指标，等待 read_image 附件',complete:'全部指标及图像已就绪',failed:'校验失败；检查 MATLAB 运行日志，勿自动重试',uncertain:'MCP 状态不确定；确认执行是否结束后再操作',none:'等待 Agent 准备扫描',images:'图像附件'},setup:{tab:'PID 参数准备',guide:'每行一组 Kp, Ki, Kd，用英文逗号分隔。2–12 组；各值在 0–100 内。这里仅校验并生成消息，不运行 MATLAB。',label:'PID 参数（每行 Kp,Ki,Kd）',validate:'检查并生成 Agent 指令',ready:'将以下指令复制到当前会话发送给 Agent',instruction:'请使用 dsh_matlab_prepare_sweep 准备以下参数，通过官方 MATLAB MCP 执行 setupCode 和 executeCode；核验完成标记后调用 dsh_matlab_collect_sweep，再用 read_image 读取全部 PNG。不可根据图像猜测精确指标，执行失败时不要自动重试。参数：',error:'参数有误',rowCount:'请输入 2–12 组 PID 参数',format:'第 {row} 行：请按 Kp,Ki,Kd 输入三个数字',range:'第 {row} 行：各参数必须是 0–100 的有限数值',unstable:'第 {row} 行：参数使示例对象闭环不稳定',duplicate:'第 {row} 行：与前面的参数组重复'}},
+      en:{figures:{tab:'MATLAB Figures',empty:'No collected figures. Run MATLAB, then call dsh_matlab_collect.',pending:'Waiting for the Agent to call read_image',loading:'Loading image…',failed:'Image load failed',source:'MATLAB numerical results',expand:'Expand / collapse',boundary:'Images support qualitative observations; precise metrics come from MATLAB data calculations.'},compare:{tab:'PID Experiments',empty:'No completed and collected PID sweeps in this session.',boundary:'Metrics come from MATLAB ode45 samples. Compare IAE over 12 seconds alongside stability, control effort and real plant checks.',overlay:'MATLAB overlay',run:'Run',gain:'PID gains (Kp / Ki / Kd)',iae:'IAE ↓',ise:'ISE',overshoot:'Overshoot %',settling:'2% settling time (s)',effort:'Max control',best:'Lowest IAE in sweep',unknown:'Undetermined',curves:'Individual response curves',status:'Status',preparing:'Preparing PID parameters…',prepared:'Prepared: ask the Agent to execute via official MATLAB MCP',running:'Executing in MATLAB MCP…',awaiting:'MCP returned completion marker; verify all artifacts',verifying:'Verifying all MATLAB artifacts…',loading:'Metrics verified; awaiting read_image attachments',complete:'Metrics and images ready',failed:'Verification failed; inspect MATLAB log and do not retry automatically',uncertain:'Unknown MCP outcome; confirm execution stopped before proceeding',none:'Ask Agent to prepare a sweep',images:'Image attachments'},setup:{tab:'PID Input',guide:'One Kp, Ki, Kd set per line, comma-separated. 2–12 rows; values between 0 and 100. This only validates and drafts an Agent message. MATLAB is not executed here.',label:'PID parameters (Kp,Ki,Kd per line)',validate:'Validate and build Agent message',ready:'Copy this instruction into the current session for the Agent',instruction:'Use dsh_matlab_prepare_sweep for these parameters, run setupCode and executeCode via official MATLAB MCP, verify the completion marker, call dsh_matlab_collect_sweep, then read_image for all PNGs. Never guess precise metrics from images or automatically retry failed writes. Parameters: ',error:'Invalid PID parameters',rowCount:'Enter 2–12 PID parameter rows',format:'Row {row}: enter three numeric values as Kp,Ki,Kd',range:'Row {row}: values must be finite and between 0 and 100',unstable:'Row {row}: gains are unstable for the sample plant',duplicate:'Row {row}: duplicate gain set'}}
+    };
+    function FigureImage({figure,sessionId,loadAttachment,t}) {
+      const [state,setState]=React.useState({key:null,url:null,error:null});
+      const attachmentId=figure.attachment?.attachmentId;
+      const key=JSON.stringify([sessionId,attachmentId]);
+      React.useEffect(()=>{
+        let active=true;
+        setState({key,url:null,error:null});
+        if(attachmentId) loadAttachment({sessionId,attachmentId}).then(result=>{
+          if(!active)return;
+          if(!result.ok)throw Error(result.error?.message||'Attachment unavailable');
+          const value=result.value;
+          if(!/^image\/(png|jpeg|webp|gif)$/.test(value.attachment.mediaType))throw Error('Unsupported image type');
+          setState({key,url:`data:${value.attachment.mediaType};base64,${value.data}`,error:null});
+        }).catch(error=>{if(active)setState({key,url:null,error:String(error.message)});});
+        return ()=>{active=false;};
+      },[sessionId,attachmentId,loadAttachment]);
+      if(!attachmentId)return h('p',{role:'status'},t('figures.pending'));
+      if(state.key!==key)return h('p',{role:'status'},t('figures.loading'));
+      if(state.error)return h('p',{role:'alert'},`${t('figures.failed')}: ${state.error}`);
+      if(!state.url)return h('p',{role:'status'},t('figures.loading'));
+      return h('details',{open:true},h('summary',null,t('figures.expand')),h('img',{src:state.url,alt:figure.title,style:{display:'block',maxWidth:'100%',height:'auto'}}));
+    }
+    function validateRows(input,t) {
+      const fail=(reason,index)=>{throw Error(t('setup.'+reason).replace('{row}',String(index+1)));};
+      const lines=input.split(/\r?\n/).map(line=>line.trim()).filter(Boolean);
+      if(lines.length<2||lines.length>12)fail('rowCount',0);
+      const seen=new Set();
+      return lines.map((line,index)=>{
+        const fields=line.split(',').map(value=>value.trim());
+        if(fields.length!==3||fields.some(v=>!v||!/^\+?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(v)))fail('format',index);
+        const [kp,ki,kd]=fields.map(Number);
+        if([kp,ki,kd].some(value=>!Number.isFinite(value)||value<0||value>100))fail('range',index);
+        if(ki>0&&(2*0.48*3+9*kd)*9*(1+kp)<=9*ki)fail('unstable',index);
+        const key=JSON.stringify([kp,ki,kd]);
+        if(seen.has(key))fail('duplicate',index);
+        seen.add(key);
+        return {kp,ki,kd};
+      });
+    }
+    function SetupView({t}) {
+      const [draft,setDraft]=React.useState('1,0.5,0.2\n3,1,0.5\n2,0.8,0.9');
+      const [result,setResult]=React.useState(null);
+      const check=()=>{try{setResult({parameters:validateRows(draft,t)});}catch(error){setResult({error:error.message});}};
+      return h('section',{'aria-label':t('setup.tab'),style:{padding:20,overflow:'auto',height:'100%',color:'var(--dsw-alias-text-primary)'}},
+        h('h2',null,t('setup.tab')),h('p',null,t('setup.guide')),
+        h('label',{htmlFor:'dsh-pid-input'},t('setup.label')),
+        h('textarea',{id:'dsh-pid-input',rows:7,value:draft,onChange:event=>{setDraft(event.target.value);setResult(null);},style:{display:'block',width:'100%',maxWidth:620,margin:'12px 0',fontFamily:'monospace'}}),
+        h('button',{type:'button',onClick:check},t('setup.validate')),
+        result?.error?h('p',{role:'alert'},`${t('setup.error')}: ${result.error}`):null,
+        result?.parameters?h('div',{role:'status'},h('p',null,t('setup.ready')),h('pre',{style:{whiteSpace:'pre-wrap',overflowWrap:'anywhere',userSelect:'text',padding:12,border:'1px solid var(--dsw-alias-border-base)'}},t('setup.instruction')+JSON.stringify({parameters:result.parameters}))):null);
+    }
+    return {inject:['slots','locale','remote','remote.session'],apply(ctx) {
+      const flat=Object.fromEntries(Object.entries(dictionaries).map(([language,dict])=>[language,Object.fromEntries(Object.entries(dict).flatMap(([group,entries])=>Object.entries(entries).map(([key,value])=>[group+'.'+key,value])))]));
+      ctx.effect(()=>ctx.locale.register('matlabWorkbench',flat));
+      const t=ctx.locale.bind('matlabWorkbench');
+      // Keep one function per plugin lifetime, independent of service proxy identity.
+      // Desktop 0.2.1 accepts exactly one argument; it exposes no per-read abort.
+      const loadAttachment=request=>ctx.remote.session.attachment(request);
+      function FigureView(props) {
+        const snapshot=props.useProjection('matlabFigures');
+        const figures=snapshot?.figures||[];
+        return h('section',{'aria-label':t('figures.tab'),'data-dsh-matlab-figure-view':'active',style:{padding:20,overflow:'auto',height:'100%',color:'var(--dsw-alias-text-primary)',background:'var(--dsw-alias-bg-base)'}},
+          h('h2',null,t('figures.tab')),h('p',null,t('figures.boundary')),
+          figures.length?figures.map(figure=>h('article',{key:figure.imageId,style:{border:'1px solid var(--dsw-alias-border-base)',borderRadius:8,padding:16,marginBottom:16}},
+            h('h3',null,figure.title),h('div',null,figure.imageId),
+            h(FigureImage,{figure,sessionId:props.sessionId,loadAttachment,t}),
+            h('p',{style:{overflowWrap:'anywhere'}},`${figure.width} × ${figure.height} · SHA-256 ${figure.sha256}`),
+            figure.metrics?h('details',null,h('summary',null,t('figures.source')),h('pre',{style:{whiteSpace:'pre-wrap'}},JSON.stringify(figure.metrics,null,2))):null
+          )):h('p',null,t('figures.empty')));
+      }
+      const numeric=value=>typeof value==='number'&&Number.isFinite(value)?value.toFixed(3):t('compare.unknown');
+      function ComparisonView(props) {
+        const snapshot=props.useProjection('matlabFigures'),figures=snapshot?.figures||[],sweeps=snapshot?.sweeps||{};
+        const groups=new Map();
+        for(const figure of figures) {
+          const provenance=figure.provenance;
+          if(!provenance?.sweepId||!['pid_sweep','pid_comparison'].includes(provenance.kind))continue;
+          if(!groups.has(provenance.sweepId))groups.set(provenance.sweepId,{rows:[],overlay:null});
+          const group=groups.get(provenance.sweepId);
+          if(provenance.kind==='pid_comparison')group.overlay=figure;
+          else if(figure.metrics?.source==='MATLAB'&&figure.metrics.kind==='pid_step_response')group.rows.push(figure);
+        }
+        for(const sweepId of Object.keys(sweeps))if(!groups.has(sweepId))groups.set(sweepId,{rows:[],overlay:null});
+        const complete=[...groups];
+        return h('section',{'aria-label':t('compare.tab'),style:{padding:20,overflow:'auto',height:'100%',color:'var(--dsw-alias-text-primary)',background:'var(--dsw-alias-bg-base)'}},
+          h('h2',null,t('compare.tab')),h('p',null,t('compare.boundary')),
+          snapshot?.activity?h('p',{role:snapshot.activity.error?'alert':'status'},snapshot.activity.error||t('compare.preparing')):null,
+          complete.length?complete.map(([sweepId,group])=>{
+            const current=sweeps[sweepId],phase=current?.phase||'complete';
+            const status={prepared:'prepared',running:'running','awaiting-collection':'awaiting',verifying:'verifying',loading:'loading',complete:'complete','verify-failed':'failed','image-failed':'failed',unknown:'uncertain'}[phase]||'none';
+            const rows=group.rows.slice().sort((a,b)=>a.provenance.index-b.provenance.index);
+            const valid=rows.filter(f=>Number.isFinite(f.metrics.integratedAbsoluteError));
+            const best=valid.length?valid.reduce((a,b)=>a.metrics.integratedAbsoluteError<=b.metrics.integratedAbsoluteError?a:b):null;
+            const headers=['run','gain','iae','ise','overshoot','settling','effort'].map(name=>h('th',{key:name,scope:'col',style:{padding:8,textAlign:'left'}},t('compare.'+name)));
+            return h('article',{key:sweepId,style:{border:'1px solid var(--dsw-alias-border-base)',padding:16,borderRadius:8,marginBottom:18}},
+              h('h3',null,`Sweep ${sweepId}`),
+              h('p',{role:phase==='verify-failed'||phase==='image-failed'||phase==='unknown'?'alert':'status'},`${t('compare.status')}: ${t('compare.'+status)}${current?.imagesLoaded!==undefined?' · '+t('compare.images')+': '+current.imagesLoaded+'/'+current.imageCount:''}${current?.error?' · '+current.error:''}`),
+              rows.length>=2&&group.overlay?h('div',{style:{overflowX:'auto'}},h('table',{style:{width:'100%',borderCollapse:'collapse'}},
+                h('thead',null,h('tr',null,...headers)),
+                h('tbody',null,...rows.map(figure=>{
+                  const m=figure.metrics,p=figure.provenance.parameters;
+                  const values=[`${figure.provenance.index+1}${best?.imageId===figure.imageId?' ★':''}`,`${numeric(p.kp)} / ${numeric(p.ki)} / ${numeric(p.kd)}`,numeric(m.integratedAbsoluteError),numeric(m.integratedSquaredError),numeric(m.overshoot_percent),m.settlingStatus==='within_recorded_window'?numeric(m.sampledSettlingTime_s):t('compare.unknown'),numeric(m.maxAbsoluteControl)];
+                  return h('tr',{key:figure.imageId,title:best?.imageId===figure.imageId?t('compare.best'):''},...values.map((value,index)=>h('td',{key:index,style:{padding:8,borderTop:'1px solid var(--dsw-alias-border-base)'}},value)));
+                })))):null,
+              group.overlay?h('div',null,h('h4',null,t('compare.overlay')),h(FigureImage,{figure:group.overlay,sessionId:props.sessionId,loadAttachment,t})):null,
+              rows.length?h('details',null,h('summary',null,t('compare.curves')),...rows.map(row=>h('div',{key:row.imageId},h('h4',null,`${t('compare.run')} ${row.provenance.index+1}`),h(FigureImage,{figure:row,sessionId:props.sessionId,loadAttachment,t})))):null);
+          }):h('p',null,t('compare.empty')));
+      }
+      ctx.slots.inject('conversation.view',()=>ctx.slots.register({name:'conversation.view',id:'matlab-pid-setup',order:29,label:()=>t('setup.tab')},props=>SetupView({...props,t})));
+      ctx.slots.inject('conversation.view',()=>ctx.slots.register({name:'conversation.view',id:'matlab-figures',order:30,label:()=>t('figures.tab')},FigureView));
+      ctx.slots.inject('conversation.view',()=>ctx.slots.register({name:'conversation.view',id:'matlab-pid-comparison',order:31,label:()=>t('compare.tab')},ComparisonView));
+    }};
+  }
+});

package/dsh/host/index.mjs

@@ -0,0 +1,54 @@
+import {fileURLToPath} from 'node:url';
+import {prepareRun,collectStandaloneFigure,listFigures,requireId} from '../../core/figures.mjs';
+import {prepareSweep,collectSweep,listSweeps} from '../../core/sweeps.mjs';
+import {emptyState,foldFigures,stateSchema} from './projection.mjs';
+
+export const inject=['tools','systemPrompt','sessionProjections','workingDirectory'];
+const helperDir=fileURLToPath(new URL('../../matlab/',import.meta.url));
+const output={schema:{type:'object',additionalProperties:true},render:(_args,value)=>[{type:'text',text:JSON.stringify(value)}]};
+export function apply(ctx) {
+  const disposers=[];
+  const workspace=async exec=>{
+    exec.signal.throwIfAborted();
+    if(!exec.agent)throw Error('A session-owned Agent invocation is required');
+    const cwd=await ctx.workingDirectory.ensure(exec.agent,exec.signal);
+    exec.signal.throwIfAborted();
+    return cwd;
+  };
+  const register=(name,description,properties,required,execute)=>{
+    disposers.push(ctx.tools.register({name,description,parameters:{type:'object',properties,required,additionalProperties:false},output,
+      async execute(args,exec){
+        if(!args||typeof args!=='object'||Array.isArray(args)||Object.keys(args).some(k=>!Object.hasOwn(properties,k)))throw Error('Invalid arguments');
+        for(const key of required)if(!(key==='parameters'?Array.isArray(args[key]):typeof args[key]==='string'))throw Error(`${key} is required`);
+        return execute(args,exec);
+      }
+    }));
+  };
+  try {
+    disposers.push(ctx.sessionProjections.register({key:'matlabFigures',stateSchema,init:emptyState,apply:foldFigures,stateVersion:1,wire:{viewSchema:stateSchema,view:state=>state}}));
+    register('dsh_matlab_prepare','Prepare a unique workspace run and safe MATLAB helper code. Does not execute MATLAB or save an image.',{},[],async (_args,exec)=>prepareRun(await workspace(exec),helperDir,{execution:'unknown',scriptHash:'unknown'}));
+    register('dsh_matlab_collect','Verify one completed MATLAB export and index it. Returns a PNG path; call read_image to provide actual visual input. Does not claim simulation success.',{runId:{type:'string'}},['runId'],async (args,exec)=>{
+      requireId(args.runId); const figure=await collectStandaloneFigure(await workspace(exec),args.runId);
+      exec.signal.throwIfAborted();
+      return {kind:'dsh-matlab-figures',figures:[figure],next:`Call read_image with file_path=${figure.path}. Precise metrics are MATLAB-computed; never replace them with visual estimates.`};
+    });
+    register('dsh_matlab_list_figures','Revalidate standalone M1 figure artifacts; use list_sweeps for complete M2 scans.',{},[],async (_args,exec)=>({kind:'dsh-matlab-figures',figures:await listFigures(await workspace(exec),{includeSweeps:false})}));
+    register('dsh_matlab_prepare_sweep','Prepare 2–12 PID gain combinations for the fixed documented second-order MATLAB sample plant. Does not run MATLAB.',{
+      parameters:{type:'array',minItems:2,maxItems:12,items:{type:'object',properties:{kp:{type:'number'},ki:{type:'number'},kd:{type:'number'}},required:['kp','ki','kd'],additionalProperties:false}}
+    },['parameters'],async (args,exec)=>prepareSweep(await workspace(exec),helperDir,args.parameters));
+    register('dsh_matlab_collect_sweep','Verify an entire completed MATLAB PID sweep: all per-run CSV, metrics, PNG and overlay. Incomplete sweeps fail without indexing.',{
+      sweepId:{type:'string'}
+    },['sweepId'],async (args,exec)=>{
+      requireId(args.sweepId);const result=await collectSweep(await workspace(exec),args.sweepId);
+      exec.signal.throwIfAborted();
+      return {...result,next:'Call read_image once for EACH returned figure path, especially the overlay; the Desktop comparison tab will display numerical metrics from MATLAB and the overlay after the attachment arrives.'};
+    });
+    register('dsh_matlab_list_sweeps','Revalidate and list only completed, whole PID sweeps with verified artifacts.',{},[],async (_args,exec)=>{
+      const groups=await listSweeps(await workspace(exec));return {kind:'dsh-matlab-figures',figures:groups.flatMap(group=>group.figures),sweeps:groups.map(group=>group.sweepId)};
+    });
+    disposers.push(ctx.systemPrompt.section({name:'dsh-matlab-workbench',order:9050,text:
+      'For MATLAB figures: dsh_matlab_prepare prepares unique absolute paths and helper code; it does not execute. Execute with the official MATLAB MCP. Pass an explicit figure handle to dsh_m1_save_figure, then dsh_matlab_collect and read_image on its exact path. For M2 PID sweeps, call dsh_matlab_prepare_sweep with an array of {kp,ki,kd}; execute its setupCode and executeCode through the official MATLAB MCP, check DSH_M2_SWEEP_SUCCEEDED, then call dsh_matlab_collect_sweep and read_image for every returned path. Use only verified completed sweeps in comparison. The example is a fixed second-order plant, with derivative on measurement, 12 second window and ode45. Compare MATLAB computed IAE (lower over this window), settling status, and control effort, without treating a ranking as universally optimal. The MATLAB Figures tab displays only collected artifacts referenced by this session. A displayed figure is not evidence the model has seen it. Describe image observations separately from numerical results. Missing, failed, timed-out or cancelled execution is not success; cancellation does not prove MATLAB has stopped. Do not retry writes automatically.'}));
+    ctx.logger?.info?.('DSH_M1_HOST_APPLY');
+  } catch(error) { for(const dispose of disposers.reverse())dispose(); throw error; }
+  return ()=>{for(const dispose of disposers.reverse())dispose();ctx.logger?.info?.('DSH_M1_HOST_DISPOSE');};
+}

package/dsh/host/projection.mjs

@@ -0,0 +1,100 @@
+// DSH event adapter: pure replay fold; no filesystem reads or custom events.
+const keyPath=value=>String(value).replaceAll('\\','/').toLowerCase();
+const matlabExecution=name=>/matlab.*(evaluate_matlab_code|run_matlab_file)/i.test(name);
+const textResult=message=>message?.content?.filter(c=>c.type==='text').map(c=>c.text).join('\n')||'';
+const matlabSucceeded=message=>!message?.isError&&/(?:^|\r?\n)\s*DSH_M2_SWEEP_SUCCEEDED\s*(?:\r?\n|$)/.test(textResult(message))&&!/(?:^|\r?\n)\s*(?:Error using|Error:|Exception:|Failed:)/i.test(textResult(message));
+const sweepForFigure=figure=>figure?.provenance?.sweepId;
+export const emptyState=()=>({calls:{},figures:[],images:{},sweeps:{},activity:null,activeSweepId:null});
+export const stateSchema={parse(value){
+  if(!value||typeof value!=='object'||!Array.isArray(value.figures)||!value.calls||!value.images)throw Error('Invalid MATLAB projection state');
+  return value;
+}};
+function updateSweep(next,id,patch) {
+  if(!id)return;
+  next.sweeps={...(next.sweeps||{}),[id]:{...(next.sweeps?.[id]||{}),...patch}};
+}
+function refreshImages(next,id) {
+  if(!id||!next.sweeps?.[id])return;
+  const figures=next.figures.filter(f=>sweepForFigure(f)===id),expected=next.sweeps[id].imageCount;
+  if(!expected||figures.length!==expected)return;
+  const available=figures.filter(f=>f.attachment?.attachmentId).length;
+  updateSweep(next,id,{phase:available===expected?'complete':'loading',imagesLoaded:available});
+}
+export function foldFigures(state,event) {
+  if(event.type==='tool/call') {
+    const {callId,name,arguments:raw}=event.data;
+    if(!['dsh_matlab_prepare_sweep','dsh_matlab_collect','dsh_matlab_list_figures','dsh_matlab_collect_sweep','dsh_matlab_list_sweeps','read_image'].includes(name)&&!matlabExecution(name))return state;
+    let args;try {args=typeof raw==='string'?JSON.parse(raw):raw;}catch {args={};}
+    const next={...state,calls:{...state.calls,[callId]:{name,args}},sweeps:state.sweeps||{}};
+    if(name==='dsh_matlab_prepare_sweep')next.activity={phase:'preparing'};
+    if(name==='dsh_matlab_collect_sweep')updateSweep(next,args?.sweepId,{phase:'verifying',error:null});
+    if(matlabExecution(name)) {
+      const id=state.activeSweepId,sweep=id&&state.sweeps?.[id];
+      if(sweep?.sweepDir&&JSON.stringify(args).includes(sweep.sweepDir)&&['prepared','running','awaiting-collection','unknown'].includes(sweep.phase)){
+        next.calls[callId].sweepId=id;
+        updateSweep(next,id,{phase:'running',error:null});
+      }
+    }
+    return next;
+  }
+  if(event.type!=='tool/result')return state;
+  const message=event.data.message,callId=message?.toolCallId,call=state.calls[callId];
+  if(!call)return state;
+  const calls={...state.calls}; delete calls[callId];
+  const next={...state,calls,sweeps:state.sweeps||{}};
+  if(call.name==='dsh_matlab_prepare_sweep') {
+    if(message.isError){next.activity={phase:'error',error:textResult(message).slice(0,300)||'Preparation failed'};return next;}
+    let data;try{data=JSON.parse(textResult(message));}catch{}
+    if(data?.status==='prepared'&&data?.kind==='pid_sweep'&&typeof data.sweepId==='string'){
+      next.activeSweepId=data.sweepId;
+      updateSweep(next,data.sweepId,{phase:'prepared',runCount:data.items?.length||0,sweepDir:data.sweepDir});
+      next.activity=null;
+    }else next.activity={phase:'error',error:'Invalid preparation response'};
+    return next;
+  }
+  if(call.sweepId) {
+    // MCP may return MATLAB errors as ordinary text even when isError=false.
+    updateSweep(next,call.sweepId,{phase:matlabSucceeded(message)?'awaiting-collection':'unknown',error:matlabSucceeded(message)?null:textResult(message).slice(0,300)||'MATLAB MCP completion not confirmed'});
+    return next;
+  }
+  if(call.name==='dsh_matlab_collect_sweep'&&message.isError){updateSweep(next,call.args?.sweepId,{phase:'verify-failed',error:textResult(message).slice(0,300)||'Artifact verification failed'});return next;}
+  if(message.isError&&call.name!=='read_image')return next;
+  if(call.name==='read_image') {
+    const attachment=message.content?.find(c=>c.type==='image')?.attachment;
+    const target=state.figures.find(f=>keyPath(f.path)===keyPath(call.args?.file_path));
+    if(message.isError||!attachment?.attachmentId||typeof call.args?.file_path!=='string'){
+      if(target&&sweepForFigure(target))updateSweep(next,sweepForFigure(target),{phase:'image-failed',error:textResult(message).slice(0,300)||'read_image returned no image attachment'});
+      return next;
+    }
+    const key=keyPath(call.args.file_path);
+    next.images={...state.images,[key]:attachment};
+    next.figures=state.figures.map(f=>keyPath(f.path)===key?{...f,attachment}:f);
+    for(const figure of next.figures)if(keyPath(figure.path)===key)refreshImages(next,sweepForFigure(figure));
+    return next;
+  }
+  let payload; try { payload=JSON.parse(textResult(message)); } catch {}
+  if(payload?.kind!=='dsh-matlab-figures'||!Array.isArray(payload.figures)){
+    if(call.name==='dsh_matlab_collect_sweep')updateSweep(next,call.args?.sweepId,{phase:'verify-failed',error:textResult(message).slice(0,300)||'Invalid sweep collection response'});
+    return next;
+  }
+  if(call.name==='dsh_matlab_collect_sweep'&&payload.sweepId!==call.args?.sweepId){
+    updateSweep(next,call.args?.sweepId,{phase:'verify-failed',error:'Sweep ID mismatch in collection response'});
+    return next;
+  }
+  const figures=new Map(state.figures.map(f=>[f.imageId,f]));
+  for(const figure of payload.figures) {
+    if(figure?.schemaVersion!==1||typeof figure.imageId!=='string'||typeof figure.path!=='string')continue;
+    const attachment=state.images[keyPath(figure.path)];
+    figures.set(figure.imageId,{...figure,...attachment?{attachment}:{}});
+  }
+  next.figures=[...figures.values()];
+  if(call.name==='dsh_matlab_collect_sweep'&&payload.sweepId){
+    updateSweep(next,payload.sweepId,{phase:'loading',imageCount:payload.figures.length,error:null});
+    refreshImages(next,payload.sweepId);
+  }
+  if(call.name==='dsh_matlab_list_sweeps')for(const id of payload.sweeps||[]){
+    updateSweep(next,id,{phase:'loading',imageCount:next.figures.filter(f=>sweepForFigure(f)===id).length,error:null});
+    refreshImages(next,id);
+  }
+  return next;
+}

package/examples/dsh_m1_step_response.m

@@ -0,0 +1,31 @@
+function dsh_m1_step_response(runDir,imageId)
+% One control-system experiment; base MATLAB ODE solver, no optional toolbox.
+zeta=0.48; wn=3; dt=0.002; duration=12;
+tRequested=(0:dt:duration)';
+options=odeset('RelTol',1e-9,'AbsTol',1e-11);
+[t,x]=ode45(@(~,x)[x(2);wn^2*(1-x(1))-2*zeta*wn*x(2)],tRequested,[0;0],options);
+y=x(:,1); [peak,k]=max(y); last=find(abs(y-1)>0.02,1,'last');
+A=[0 1;-wn^2 -2*zeta*wn]; B=[0;wn^2];
+equilibrium=-(A\B); steadyStateError=1-equilibrium(1);
+settling=[]; settlingStatus='not_determined';
+if isempty(last), settling=t(1); settlingStatus='within_recorded_window';
+elseif last<numel(t), settling=t(last+1); settlingStatus='within_recorded_window'; end
+metrics=struct('source','MATLAB','method','ode45 samples: max(y), last out-of-2%-band sample plus one', ...
+    'matlab',version,'solver','ode45','relativeTolerance',1e-9,'absoluteTolerance',1e-11, ...
+    'zeta',zeta,'wn_rad_s',wn,'sampleInterval_s',dt,'window_s',duration,'reference',1, ...
+    'knownFinalValue',1,'settlingBandFraction',0.02,'peak',peak,'peakTime_s',t(k), ...
+    'overshoot_percent',100*(peak-1),'sampledSettlingTime_s',settling,'settlingStatus',settlingStatus, ...
+    'finalSampleError',1-y(end),'analyticSteadyStateError',steadyStateError, ...
+    'steadyStateMethod','MATLAB solves x_eq = -(A\B), error = reference - x_eq(1) for stable A');
+writematrix([t,y],fullfile(runDir,'samples.csv'));
+fid=fopen(fullfile(runDir,'metrics.json'),'w','n','UTF-8'); assert(fid>=0);
+closer=onCleanup(@()fclose(fid)); fwrite(fid,jsonencode(metrics),'char'); clear closer;
+fig=figure('Visible','off');
+plot(t,y,'LineWidth',1.7); hold on; yline(1,'--'); yline(0.98,':'); yline(1.02,':');
+grid on; xlabel('Time (s)'); ylabel('Output'); title('M1: numerical unit-step response');
+% Random visual control is deliberately omitted from stdout and metadata.
+tokens={'ORBIT','MAPLE','COMET','RIVER','CEDAR','LANTERN'};
+text(6,0.45,['Visual control: ' tokens{randi(numel(tokens))}],'FontSize',13);
+dsh_m1_save_figure(fig,runDir,imageId,'Unit-step response / ODE45'); close(fig);
+disp('DSH_M1_EXPERIMENT_SUCCEEDED'); disp(jsonencode(metrics));
+end

package/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect x="4" y="4" width="56" height="56" rx="12" fill="#16334a"/><path d="M13 46h38M16 48V17M17 44c5 0 5-24 12-24s5 16 11 16 5-8 10-8" fill="none" stroke="#68d6ed" stroke-width="3"/></svg>

package/integration/matlab-mcp-gate/cordis.patch.yml

@@ -0,0 +1,18 @@
+# Optional connection example for users without an existing DSH MATLAB MCP server.
+# Install the official Windows executable on PATH using the name below.
+# MATLAB must also be discoverable on PATH. Do not add this if matlab already exists.
+- insert:
+    - id: dsh-matlab-mcp-connection-example
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: matlab
+        transport: stdio
+        command: 'matlab-mcp-server-windows-x64.exe'
+        args:
+          - '--matlab-session-mode=new'
+          - '--matlab-display-mode=nodesktop'
+          - '--disable-telemetry=true'
+        toolCallTimeoutMs: 600000
+        failOnStartupError: false
+        env:
+          WINDIR: !!js process.env.WINDIR

package/integration/matlab-mcp-gate/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "dsh-matlab-mcp-connection-example",
+  "version": "0.1.0-beta.1",
+  "private": true,
+  "type": "module",
+  "description": "Optional portable DSH connection to the independently installed official MATLAB MCP server",
+  "dsh": {"bundle": {"patch": "./cordis.patch.yml"}},
+  "files": ["cordis.patch.yml", "package.json"]
+}

package/locale/en.json

@@ -0,0 +1 @@
+{"meta":{"title":"MATLAB Figure Workbench","description":"Save and verify MATLAB figures, browse them in FigureView, and retain MATLAB-computed metrics."},"figures":{"tab":"MATLAB Figures","empty":"No collected figures. Run MATLAB, then call dsh_matlab_collect.","pending":"Waiting for the Agent to call read_image","loading":"Loading image…","failed":"Image load failed","source":"MATLAB numerical results","expand":"Expand / collapse","boundary":"Images support qualitative observations; precise metrics come from MATLAB data calculations."}}

package/locale/zh.json

@@ -0,0 +1 @@
+{"meta":{"title":"MATLAB 图像工作台","description":"保存和核验 MATLAB 图像，在 FigureView 浏览结果；精确指标由 MATLAB 计算。"},"figures":{"tab":"MATLAB 图像","empty":"尚无已收集图像。请先运行 MATLAB，再调用 dsh_matlab_collect。","pending":"等待 Agent 调用 read_image","loading":"正在载入图像…","failed":"图像载入失败","source":"MATLAB 数值结果","expand":"放大 / 收起","boundary":"图像用于定性观察；精确数值来自 MATLAB 数据计算。"}}

package/matlab/dsh_m1_save_figure.m

@@ -0,0 +1,32 @@
+function metadata = dsh_m1_save_figure(fig, runDir, imageId, titleText)
+% Explicit figure handle, absolute run path, unique ID; commit metadata last.
+arguments
+    fig (1,1) matlab.ui.Figure
+    runDir (1,1) string
+    imageId (1,1) string
+    titleText (1,1) string = "Simulation result"
+end
+assert(strlength(titleText)<=200,'DSHM1:Title','Title too long');
+assert(~isempty(regexp(char(runDir),'^([A-Za-z]:[\\/]|/[^/])','once')), ...
+    'DSHM1:AbsolutePath','An absolute local run directory is required');
+assert(isempty(regexp(char(runDir),'[\x00-\x1f]','once')), 'DSHM1:Path','Invalid path');
+assert(~isempty(regexp(char(imageId),'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$','once')), ...
+    'DSHM1:Id','Invalid image UUID');
+record=jsondecode(fileread(fullfile(runDir,'prepared.json')));
+assert(record.schemaVersion==1 && string(record.imageId)==imageId && string(record.runDir)==runDir, ...
+    'DSHM1:Preparation','Run does not match Host preparation');
+png=fullfile(runDir,imageId+'.png'); partial=fullfile(runDir,imageId+'.partial.png');
+manifest=fullfile(runDir,'figure.json'); temporary=fullfile(runDir,imageId+'.partial.json');
+assert(~isfile(png)&&~isfile(partial)&&~isfile(manifest)&&~isfile(temporary), ...
+    'DSHM1:Exists','Refusing to overwrite an existing figure or partial export');
+assert(~isempty(fig.Children),'DSHM1:Empty','Cannot export an empty figure');
+exportgraphics(fig,partial,'Resolution',150);
+[ok,msg]=movefile(partial,png); assert(ok,'DSHM1:Commit','%s',msg);
+utc=datetime('now','TimeZone','UTC','Format',"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
+metadata=struct('schemaVersion',1,'imageId',char(imageId),'file',char(imageId+'.png'), ...
+    'title',char(titleText),'exportedUtc',char(utc));
+fid=fopen(temporary,'w','n','UTF-8'); assert(fid>=0,'DSHM1:Metadata','Cannot create figure metadata');
+closer=onCleanup(@()fclose(fid));
+fwrite(fid,unicode2native(jsonencode(metadata),'UTF-8'),'uint8'); clear closer;
+[ok,msg]=movefile(temporary,manifest); assert(ok,'DSHM1:Commit','%s',msg);
+end

package/matlab/dsh_m2_pid_sweep.m

@@ -0,0 +1,142 @@
+function summary = dsh_m2_pid_sweep(sweepDir)
+% Run each prepared PID experiment once. Only commit completion after all
+% MATLAB CSV, numerical metrics and figure exports have succeeded.
+arguments
+    sweepDir (1,1) string
+end
+assert(isfolder(sweepDir),'DSHM2:Directory','Sweep directory is missing');
+manifestPath=fullfile(sweepDir,'sweep.json');
+assert(isfile(manifestPath),'DSHM2:Manifest','Host manifest is missing');
+manifest=jsondecode(fileread(manifestPath));
+assert(manifest.schemaVersion==2 && strcmp(manifest.kind,'pid_sweep') && ...
+    strcmp(manifest.status,'prepared') && string(manifest.sweepDir)==sweepDir, ...
+    'DSHM2:Manifest','Unexpected sweep manifest');
+assert(numel(manifest.items)>=2 && numel(manifest.items)<=12,'DSHM2:Count','Invalid run count');
+assert(~isfile(fullfile(sweepDir,'completed.json')),'DSHM2:Exists','Sweep was already completed');
+assert(isfield(manifest,'comparison'),'DSHM2:Manifest','Comparison run missing');
+plant=manifest.plant;
+assert(plant.zeta==0.48 && plant.wn_rad_s==3 && plant.reference==1 && ...
+    plant.sampleInterval_s==0.01 && plant.window_s==12, ...
+    'DSHM2:Plant','Unsupported plant definition');
+for index=1:numel(manifest.items)
+    item=manifest.items(index);
+    assert(item.index==index-1,'DSHM2:Manifest','Run index mismatch');
+    checkRun(item.runDir,item.runId,item.imageId,manifest.sweepId);
+    gains=item.parameters;
+    assert(all(isfinite([gains.kp gains.ki gains.kd])) && ...
+        all([gains.kp gains.ki gains.kd]>=0) && all([gains.kp gains.ki gains.kd]<=100), ...
+        'DSHM2:Gains','Invalid PID gains');
+    a2=2*plant.zeta*plant.wn_rad_s+plant.wn_rad_s^2*gains.kd;
+    a1=plant.wn_rad_s^2*(1+gains.kp);
+    a0=plant.wn_rad_s^2*gains.ki;
+    assert(gains.ki==0 || a2*a1>a0,'DSHM2:Unstable','Unstable closed loop');
+    assert(~isfile(fullfile(item.runDir,'metrics.json')) && ...
+        ~isfile(fullfile(item.runDir,'samples.csv')) && ...
+        ~isfile(fullfile(item.runDir,'figure.json')), ...
+        'DSHM2:Exists','Refusing to overwrite existing experiment');
+end
+checkRun(manifest.comparison.runDir,manifest.comparison.runId, ...
+    manifest.comparison.imageId,manifest.sweepId);
+assert(~isfile(fullfile(manifest.comparison.runDir,'figure.json')), ...
+    'DSHM2:Exists','Comparison figure already exists');
+
+stepTime=(0:plant.sampleInterval_s:plant.window_s)';
+trajectories=zeros(numel(stepTime),numel(manifest.items));
+labels=cell(numel(manifest.items),1);
+opts=odeset('RelTol',1e-9,'AbsTol',1e-11);
+for index=1:numel(manifest.items)
+    item=manifest.items(index); g=item.parameters;
+    % Plant: y'' + 2*zeta*wn*y' + wn^2*y = wn^2*u.
+    % PID derivative acts on the measured output to avoid setpoint kick.
+    [t,x]=ode45(@(~,x)pidODE(x,g,plant),stepTime,[0;0;0],opts);
+    y=x(:,1); v=x(:,2); integralError=x(:,3);
+    u=g.kp*(plant.reference-y)+g.ki*integralError-g.kd*v;
+    assert(all(isfinite([y;u])) && max(abs([y;u]))<1e6, ...
+        'DSHM2:Diverged','Simulation output diverged');
+    errorSignal=plant.reference-y;
+    [peak,peakIndex]=max(y);
+    lastOutside=find(abs(errorSignal)>0.02*abs(plant.reference),1,'last');
+    settle=[];settleStatus='not_determined_in_window';
+    if isempty(lastOutside)
+        settle=t(1);settleStatus='within_recorded_window';
+    elseif lastOutside<numel(t)
+        settle=t(lastOutside+1);settleStatus='within_recorded_window';
+    end
+    if g.ki>0
+        analyticFinal=plant.reference;
+    else
+        analyticFinal=plant.reference*g.kp/(1+g.kp);
+    end
+    metrics=struct('schemaVersion',2,'kind','pid_step_response', ...
+        'source','MATLAB','method','ode45 sampled trajectory; MATLAB trapz and last outside reference 2 percent band', ...
+        'matlab',version,'solver','ode45','relativeTolerance',1e-9, ...
+        'absoluteTolerance',1e-11,'sampleInterval_s',plant.sampleInterval_s, ...
+        'window_s',plant.window_s,'reference',plant.reference, ...
+        'settlingBandFraction',0.02,'plant',plant,'pid',g, ...
+        'derivativeMethod','derivative on measurement; no setpoint kick', ...
+        'peak',peak,'peakTime_s',t(peakIndex), ...
+        'overshoot_percent',max(0,100*(peak-plant.reference)/abs(plant.reference)), ...
+        'sampledSettlingTime_s',settle,'settlingStatus',settleStatus, ...
+        'integratedAbsoluteError',trapz(t,abs(errorSignal)), ...
+        'integratedSquaredError',trapz(t,errorSignal.^2), ...
+        'maxAbsoluteControl',max(abs(u)), ...
+        'finalSampleError',errorSignal(end), ...
+        'analyticSteadyStateError',plant.reference-analyticFinal, ...
+        'steadyStateMethod','Stable closed-loop final-value theorem: Ki>0 => zero reference error; Ki=0 => 1/(1+Kp)');
+    writematrix([t y u],fullfile(item.runDir,'samples.csv'));
+    writeNewJson(fullfile(item.runDir,'metrics.json'),metrics);
+    fig=figure('Visible','off'); cleaner=onCleanup(@()close(fig));
+    plot(t,y,'LineWidth',1.5);hold on;
+    yline(plant.reference,'--');yline(plant.reference*0.98,':');yline(plant.reference*1.02,':');
+    grid on;xlabel('Time (s)');ylabel('Output y');
+    title(sprintf('PID %d: Kp=%.3g Ki=%.3g Kd=%.3g',index,g.kp,g.ki,g.kd));
+    dsh_m1_save_figure(fig,string(item.runDir),string(item.imageId), ...
+        "PID step response " + index);
+    clear cleaner;
+    trajectories(:,index)=y;
+    labels{index}=sprintf('%d: P=%.3g I=%.3g D=%.3g',index,g.kp,g.ki,g.kd);
+end
+
+fig=figure('Visible','off');cleaner=onCleanup(@()close(fig));
+plot(stepTime,trajectories,'LineWidth',1.5);hold on;
+yline(plant.reference,'--k','Reference');grid on;
+xlabel('Time (s)');ylabel('Output y');title('M2 PID parameter sweep comparison');
+legend(labels,'Location','best');
+dsh_m1_save_figure(fig,string(manifest.comparison.runDir), ...
+    string(manifest.comparison.imageId),'PID sweep overlay comparison');
+clear cleaner;
+utc=datetime('now','TimeZone','UTC','Format',"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
+summary=struct('schemaVersion',2,'sweepId',manifest.sweepId, ...
+    'runCount',numel(manifest.items),'completedUtc',char(utc));
+writeNewJson(fullfile(sweepDir,'completed.json'),summary);
+disp('DSH_M2_SWEEP_SUCCEEDED');disp(jsonencode(summary));
+end
+
+function dx=pidODE(x,g,plant)
+e=plant.reference-x(1);
+u=g.kp*e+g.ki*x(3)-g.kd*x(2);
+dx=[x(2);plant.wn_rad_s^2*(u-x(1))-2*plant.zeta*plant.wn_rad_s*x(2);e];
+end
+
+function checkRun(runDir,runId,imageId,sweepId)
+assert(isfolder(runDir),'DSHM2:Run','Run directory missing');
+prepared=jsondecode(fileread(fullfile(runDir,'prepared.json')));
+assert(prepared.schemaVersion==1 && string(prepared.runId)==string(runId) && ...
+    string(prepared.runDir)==string(runDir) && ...
+    string(prepared.imageId)==string(imageId) && ...
+    strcmp(prepared.provenance.sweepId,sweepId), ...
+    'DSHM2:Run','Run preparation mismatch');
+end
+
+function writeNewJson(target,value)
+assert(~isfile(target),'DSHM2:Exists','Refusing to replace an existing record');
+temporary=string(tempname(fileparts(target)))+".partial.json";
+fid=fopen(temporary,'w','n','UTF-8');
+assert(fid>=0,'DSHM2:Write','Unable to create record');
+closer=onCleanup(@()fclose(fid));
+fwrite(fid,unicode2native(jsonencode(value),'UTF-8'),'uint8');
+clear closer;
+assert(~isfile(target),'DSHM2:Exists','Refusing to replace an existing record');
+[ok,msg]=movefile(temporary,target);
+assert(ok,'DSHM2:Commit','%s',msg);
+end

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "dsh-matlab-workbench",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "type": "module",
+  "description": "DSH Desktop MATLAB experiment workbench: MCP figures, PID sweeps, verified metrics and comparisons",
+  "license": "MIT",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "matlab",
+    "matlab-mcp-server",
+    "pid",
+    "simulation",
+    "engineering"
+  ],
+  "engines": {
+    "node": ">=24",
+    "dsh": "0.2.1-rc.2 || 0.2.1-rc.3"
+  },
+  "exports": {
+    ".": "./dsh/host/index.mjs",
+    "./client": "./dsh/client/index.js",
+    "./package.json": "./package.json",
+    "./icon": "./icon.svg",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "core",
+    "dsh",
+    "matlab/dsh_m1_save_figure.m",
+    "matlab/dsh_m2_pid_sweep.m",
+    "examples",
+    "integration",
+    "locale",
+    "icon.svg",
+    "cordis.patch.yml",
+    "LICENSE",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "test:matlab:m2": "node probes/m2/run-matlab-validation.mjs",
+    "check": "node --check core/figures.mjs && node --check core/sweeps.mjs && node --check dsh/host/index.mjs && node --check dsh/host/projection.mjs && node --check dsh/client/index.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": false,
+      "inject": []
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lemonxiny55/dsh-matlab-workbench.git"
+  },
+  "homepage": "https://github.com/lemonxiny55/dsh-matlab-workbench#readme",
+  "bugs": {
+    "url": "https://github.com/lemonxiny55/dsh-matlab-workbench/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}