sjscy05/matlab-modelsim-vivado-plugin

mmv-dspic — MATLAB + ModelSim + Vivado 数字通信 IC 设计全流程插件

一个 DeepSeek Harness 插件，为 Agent 提供 MATLAB（算法建模/参考仿真）→ ModelSim（RTL 编译/仿真）→ Vivado（综合/实现/比特流） 的完整数字通信 IC 设计工具链，全部通过本地已安装的 EDA 工具执行。

工具一览

| 工具 | 作用 |
| --- | --- |
| mmv_check_env | 探测 MATLAB / ModelSim / Vivado 是否可用并读取版本信息 |
| mmv_project_init | 初始化设计工作区（matlab/ rtl/ sim/ scripts/ reports/ + 模板） |
| mmv_matlab_run | 以 matlab -batch 运行 .m 脚本或内联表达式，捕获输出与退出码 |
| mmv_modelsim_compile | 用 vlog/vcom 把 Verilog/SystemVerilog/VHDL 源码编译进 work 库（vlib 自动建库） |
| mmv_modelsim_simulate | 用 vsim -c 以 do-file 或内联命令运行批处理仿真，可录制波形 |
| mmv_vivado_run | 以 vivado -mode batch -notrace 运行任意 Tcl 脚本 |
| mmv_vivado_flow | 一键生成并运行 综合 → 实现 → 比特流 的标准 Tcl 流程 |

所有运行类工具返回统一的规范结果：exitCode（超时被杀时为 null）、timedOut、durationMs、stdout、stderr、truncated（输出超过 maxOutputChars 上限时截断并标记）。非零退出码是正常领域结果而非工具错误，Agent 需检查 exitCode 判断成败。

安装与加载

本插件运行在 DeepSeek Harness 生态内（依赖 @deepseek-ai/dsh-tools 等 workspace 包），推荐把它作为可放入 checkouts 的文件夹使用：克隆/复制本仓库到你的 deepseek-harness checkout 根目录（保留文件夹名 matlab-modelsim-vivado-plugin，这样 tsconfig/vitest 对 ../tsconfig.base.json 的相对引用成立；放在其他位置时请相应调整）。

方式一：Web 覆盖层（开发用，已验证）

从 deepseek-harness checkout 根目录运行
cordis.yml 中的 name 需为绝对路径，Windows 上必须写成 file:///... 的 URL 形式
（裸的 D:/ 路径会被当成 d: 协议）——迁移机器后请修改该行
pnpm dsh web --patch ./matlab-modelsim-vivado-plugin/cordis.yml

打开 http://127.0.0.1:3080。启动日志出现 [mmv-dspic] plugin loaded (...) 即加载成功；Agent 立即可调用 7 个 mmv_ 工具。若已有 GUI 实例在运行，需先停掉旧实例再以此命令重启。

方式二：组合包安装（bundle，官方格式）

先构建 lib/（在 checkout 根目录执行）
node node_modules/typescript/bin/tsc -b matlab-modelsim-vivado-plugin/tsconfig.build.json

安装进 profile（本仓库声明了 dsh.bundle manifest，会自动追加到 dsh.profile.bundles）
pnpm dsh plugin --profile web add ./matlab-modelsim-vivado-plugin
pnpm dsh web   # 或 dsh --profile web 启动

验证层已生效：pnpm dsh --profile web --dump-config 应出现 # == mmv-dspic 层。源码模式（pnpm dsh，tsx 解析）下 @deepseek-ai/ 依赖经由 checkout 的 tsconfig paths 解析；dsh plugin add 用 link: 协议链接本目录，不会自动安装其 npm 依赖，因此必须在 deepseek-harness checkout 内构建并使用。从纯 npm/git 独立安装（脱离 checkout）暂不支持，需要先发布到 npm 再由 pnpm 解析依赖。

方式三：临时 profile 验证

pnpm dsh plugin --profile mmv-test add ./matlab-modelsim-vivado-plugin
pnpm dsh --profile mmv-test --dump-config   # 检查 # == mmv-dspic 层
验证后删除：Remove-Item $env:USERPROFILE\.dsh\profiles\mmv-test -Recurse

配置

cordis.yml 中 mmv-dspic 条目的 config：

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| matlabPath | matlab | MATLAB 可执行文件（PATH 名或绝对路径） |
| modelsimPath | vsim | ModelSim 引用：PATH 名、vsim 绝对路径或 bin 目录；vlog/vcom/vlib 由它推导 |
| vivadoPath | vivado | Vivado 可执行文件；Windows 上解析到 .bat/.cmd 时经 cmd 调用 |
| workdir | '' | 工具运行的默认工作目录；空表示 Harness 进程目录 |
| timeoutMs | 600000 | 每次运行的默认超时（毫秒），单次调用可用 timeoutMs 参数覆盖 |
| maxOutputChars | 40000 | stdout/stderr 单流截断上限（字符） |

推荐流程（数字通信 IC 设计）

1. mmv_check_env — 确认三个工具链可用。
2. mmv_project_init — 建立工作区；matlab/ 放算法模型，rtl/ 放可综合 RTL，sim/ 放 testbench 与 do-file。
3. mmv_matlab_run — 在 MATLAB 中完成算法建模（滤波器系数、调制映射、BER/EVN 曲线、定点化参考数据）。
4. mmv_modelsim_compile + mmv_modelsim_simulate — 编译 RTL 与 testbench，批处理仿真并与 MATLAB 参考数据交叉比对；recordWaves: true 生成 WLF 波形。
5. mmv_vivado_flow — 仿真通过后综合/实现/生成比特流，产出 synth.dcp、impl.dcp、utilization/timing 报告与 .bit 文件（默认输出到 vivado_out/）。
6. mmv_vivado_run — 需要自定义 Tcl 步骤（报告分析、DCP 检查等）时使用。

开发与验证

类型检查（project references 构建，依赖已构建的 lib/types）
node node_modules/typescript/bin/tsc -b matlab-modelsim-vivado-plugin/tsconfig.json

单元测试（真实 ToolRuntime + 真实子进程，EDA 工具用假可执行文件替身）
node node_modules/vitest/vitest.mjs run --config matlab-modelsim-vivado-plugin/vitest.config.ts

测试覆盖：插件导出形态（Loader 兼容）、7 个工具注册与 HMR 卸载、进程运行器的超时/中止/截断/缺失可执行文件契约、参数校验（含 exactly-one 约束）、以及通过真实 spawn 的假 vlib/vlog/vsim/vivado 验证完整调用链。

设计说明与限制

- 进程由插件直接 spawn（不经过 dsh-shell/dsh-subprocess 服务），因此不走 Harness 的 shell 审批/沙箱策略；这也是该插件定位为本地开发插件的取舍。
- 运行类工具未接入 ctx.jobs 后台任务机制：MATLAB/Vivado 长任务在前台执行，由 timeoutMs 兜底。需要后台化时可参考 dsh-tool-bash 的 producer 模式扩展。
- mmv_vivado_flow 生成的 Tcl 假定 read_verilog/read_vhdl/read_xdc 直接读文件列表；不含 IP 核、synth_design 之外的策略选项，复杂工程请用 mmv_vivado_run 跑手写 Tcl。
- 未提供波形查看、报告解析等后处理工具；Agent 直接阅读工具返回的日志与报告文本。
- 插件不在 deepseek-harness 的 packages/ 下，不参与其 coverage/文档门禁与 invariant 注册。
- lib/ 为构建产物，不入库（.gitignore）；使用方式二的用户需先构建。
- 测试中的 fake 工具链替身仅在 Windows 上生成 .cmd、其他平台生成 sh 脚本，两条路径均已覆盖。