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 脚本，两条路径均已覆盖。