Multisim MS14 Builder MCP
README.md
# Multisim MS14 Builder MCP
**用 JSON 描述电路,通过 MCP 生成可编辑的 Multisim 图纸、自动连线、核对网表,并导出带真实探针结果的电路图。**
适合数字电路实验、教学演示和实验报告配图。支持直接使用 Python 命令,也可接入支持本地 stdio MCP 的 AI 客户端。
> 需要 Windows + 已安装的 NI Multisim。项目不包含 Multisim 安装程序、许可证或完整元件数据库,也不是 NI 官方产品。
## 案例预览
### 8 线—3 线优先编码器:自动布局与连线
8 个输入开关、74HC148N_4V 和 5 个输出指示器。布局在默认 A 纸内居中,开关标签与接地符号留在图框内。示例的 15 个网络已与规格逐网核对。

### 运行后导出:自动接入电压测量探针
选择“运行后的电路图”后,在普通数字电压指示器输入端添加原生测量探针,读取实际仿真样本,再生成黄色结果框。原输入文件不变,另存带结果的图纸和采样 JSON。

[下载该案例的可编辑图纸](examples/encoder-simulated.ms14) · [查看原始采样数据](examples/encoder-simulated.results.json)
> 指示器旁原有的 `2.5 V` 是器件显示的阈值标注;本次实测电压以黄色结果框及采样 JSON 为准。
### 保留已有原生探针
已有测量探针的电路同样可以重新采样并导出;不会把文件里保存的历史读数当成新结果。

## 功能
| 功能 | 说明 |
| --- | --- |
| JSON → `.ms14` | 从 Multisim 本机元件库替换占位元件,输出可编辑图纸 |
| 自动布局与连线 | 按元件角色布置,9 单位网格正交布线;提供默认 A 纸布局 |
| 网表核对 | 用 Multisim 导出网表,逐个网络比较引脚集合,报告缺失与多余连接 |
| 导出前选择 | MCP 在未指定模式时返回询问,让用户选择原图或运行后图 |
| 原始图 | 不运行仿真,隐藏原生测量探针的历史黄色读数框 |
| 运行后图 | 使用保存的输入开关状态仿真,采样并显示真实电压结果 |
| 探针自动添加 | 为单输入 `PROBE_DIG` 数字电压指示器添加原生电压测量探针 |
| 报告配图 | 整页 PNG,或裁剪留白后放大 3 倍的 PNG |
| Word 插图(可选) | 用 Microsoft Word COM 插入或替换报告里的电路图 |
| MS14/XML 转换 | 纯 Python 编解码与模型文本往返保真 |
## 环境要求
- **Windows 10/11(64 位)**,本机已安装 Multisim,并注册 `MultisimInterface.MultisimApp` COM 接口;当前实测版本为 **Multisim 14.3**。
- **Python 3.9 或更新版本**。核心生成器、网表核对及 MCP 服务只用标准库。
- Windows 自带的 **32 位 PowerShell**:`C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe`。Python 可以是 64 位。
- 裁图需要 **Pillow**;Word 插图另需 **Microsoft Word + pywin32**。
- 元件型号必须存在于本机 Multisim 元件库;其他版本/数据库不保证兼容。
## 下载与安装
### 方式一:下载 ZIP
1. 点击本页 **Code → Download ZIP**,或使用 [main 分支下载链接](https://github.com/lycheegrove111-cmd/multisim-ms14-builder/archive/refs/heads/main.zip)。
2. 解压到固定位置,例如 `C:\MultisimMCP`。不要在 ZIP 内直接运行。
3. 打开 PowerShell,进入解压后的目录:
```powershell
cd C:\MultisimMCP
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```
### 方式二:Git 克隆
```powershell
git clone https://github.com/lycheegrove111-cmd/multisim-ms14-builder.git
cd multisim-ms14-builder
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```
验证 Python 与自动化环境:
```powershell
.\.venv\Scripts\python.exe --version
Test-Path 'Registry::HKEY_CLASSES_ROOT\MultisimInterface.MultisimApp'
Test-Path 'C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe'
.\.venv\Scripts\python.exe -m unittest discover -s . -p 'test*.py' -v
```
两个 `Test-Path` 应返回 `True`。单元测试不启动 Multisim,不能替代本机 COM 连通性或仿真检查。
## 接入 MCP
这是 **stdio MCP 服务**,不是 HTTP 服务,不需要开放端口。把下面配置加入支持本地 MCP 的客户端设置;字段外层结构以客户端要求为准。
```json
{
"mcpServers": {
"multisim": {
"command": "C:\\MultisimMCP\\.venv\\Scripts\\python.exe",
"args": ["C:\\MultisimMCP\\mcp_server.py"]
}
}
}
```
将 `command` 和 `args` 改成你的**绝对路径**,保存后重启 MCP 连接。安装或更新后也需重启服务。路径中包含中文或空格时仍应作为完整参数填写。
可以对 AI 客户端说:
> 使用 Multisim 工具,按 `specs/实验二_1_74LS148测试.json` 生成编码器电路,保存到 out,核对连通性。导出图片前请问我是要原电路图还是运行后的电路图。
> 导出运行后的电路图,显示黄色探针结果框,并给我图纸副本和采样记录。
### MCP 工具列表
| 工具 | 必要参数 / 作用 |
| --- | --- |
| `build_circuit` | `spec`, `output`;生成图纸,可选 `overwrite` |
| `check_connectivity` | `ms14`, `spec`;返回逐网比较结果 |
| `export_netlist` | `ms14`;导出网络与引脚集合 |
| `export_image` | `ms14`, `output`;整页 PNG;明确选择后传 `mode` |
| `export_figure` | 同上;裁剪并放大 3 倍 |
| `list_components` | `ms14`;列出元件 |
| `insert_figure` | `docx`, `png`, `section`;可选 `nth`, `caption`, `anchor` |
| `decode_ms14` | `ms14`, `output`;解码 XML |
| `encode_ms14` | `xml`, `output`;编码 MS14,可选 `overwrite` |
导出模式:`original` / `simulated`。缺少 `mode` 时返回 `needs_user_choice`,**不会生成图片**。客户端应把问题展示给用户,再带选择重新调用;服务本身不会弹出操作系统对话框。
运行后导出的请求示例:
```json
{
"ms14": "C:\\MultisimMCP\\out\\encoder.ms14",
"output": "C:\\MultisimMCP\\out\\encoder-simulated.png",
"mode": "simulated",
"duration": 0.001
}
```
返回 `.png`、`.ms14` 副本和 `.results.json` 的绝对路径。已有结果副本或采样记录时需换新输出名,避免覆盖。调用 Word 插图前务必备份文档。
## 不用 MCP:命令行快速开始
以下命令均在仓库根目录运行。
```powershell
New-Item -ItemType Directory -Force out | Out-Null
# 生成电路(包含自动连线)
.\.venv\Scripts\python.exe build.py "specs/实验二_1_74LS148测试.json" "out/encoder.ms14"
# 逐网核对:必须看到 ok: true,且 missing / extra 均为空
.\.venv\Scripts\python.exe netcheck.py "out/encoder.ms14" "specs/实验二_1_74LS148测试.json"
# 用户选择原图后
.\.venv\Scripts\python.exe figure.py image "out/encoder.ms14" "out/encoder-original.png" --mode original
# 用户选择运行后图后(另一个输出名称)
.\.venv\Scripts\python.exe figure.py image "out/encoder.ms14" "out/encoder-simulated.png" --mode simulated --duration 0.001
```
生成与导出需要调用本机 Multisim,通常需要几十秒。直接运行 `build.py` 会写入指定路径,请使用新的输出名称。
**型号说明:**历史规格文件名包含 `74LS148`,但该示例内容使用的是 `74HC148N_4V`。实际元件以 JSON 的 `lib` 和生成图纸为准,不能据文件名把 HC 与 LS 型号混同。
## 自定义 JSON 电路
`switches` 指定输入开关数,`parts` 指定其他元件;`nets` 可选,提供时自动连线。JSON 不填写坐标。
以下是规格结构片段,完整可运行示例见 [specs](specs/):
```json
{
"switches": 3,
"parts": [
{"name": "U1", "role": "chip", "lib": ["TTL", "74LS", "74LS153N"]},
{"name": "X1", "role": "probe", "lib": ["Indicators", "PROBE", "PROBE_DIG_RED"]}
]
}
```
- `role`:`chip` 主芯片、`gate` 门电路、`probe` 指示器。
- `lib`:Multisim 中的组 / 系列 / 型号,必须与本机元件库一致。
- 开关名为 `S1…Sn`,按键为 `A…Z`;`3` 接 VCC,`1` 接地,`2` 为信号端。
- `nets` 格式如 `"D7": ["S1.2", "U1.D7"]`;一个网络需列出全部连接引脚。
- 数字地引用为 `GND.GND`,电源为 `VCC.VCC`;芯片隐藏电源脚由 Multisim 处理。
- 同一引脚不能出现在多个网络中。省略 `nets` 时只摆放元件,不连线。
## 运行结果如何理解
- 使用 `.ms14` 中保存的输入状态,不会自动遍历开关组合。
- `duration` 默认 `0.001` 秒,范围为 `0 < duration <= 10`,每路采集 100 个样本;仿真运行至采样窗口之后再读取数据。
- 黄色框:`V` 为最后有效样本;`V(p-p)` 为窗口峰峰值;`V(rms)` 为均方根;`V(dc)` 为窗口算术平均值;`t` 为最后样本时刻。
- 这些是当前采样窗口的结果,不是稳态保证、频率分析或完整真值表证明。时序/模拟电路应按需要选择采样窗口。
- 图纸里的结果框是本次运行的快照;重新打开副本后可继续仿真。探针读取失败会报错,不回退为历史读数。
## 项目结构
```text
mcp_server.py MCP stdio 工具入口
build.py / route.py 元件生成、布局与自动布线
ms14.py / msedit.py 文件编解码和 XML 编辑
base_clean.ms14 运行底板(保留模型原文)
msapi.ps1 / check.ps1 Multisim COM 替换与检查
netcheck.py / msreport.ps1 网表核对、原生图片导出
simulation.py / .ps1 实际采样、探针与结果副本
probe_template.xml 原生测量探针结构模板
wire_templates.xml 原生连线结构模板
figure.py 图片裁剪和可选 Word 插图
specs/ 电路规格示例
examples/ 已验证图纸与采样数据
docs/images/ README 案例截图
test_*.py 不依赖运行 Multisim 的回归测试
```
## 限制与常见问题
- **仅 Windows / 本机 Multisim。** 不支持直接在 Linux、macOS 或远程服务器上进行 COM 仿真。
- **沙箱权限:** AI 客户端可能拦截桌面 COM。连接超时或访问被拒绝时,应按客户端提示授权本机执行;无需关闭全局安全设置。
- **型号找不到:** 在 Multisim“放置元件”中确认组三元组。错误型号可能使 COM 替换失败。
- **自动布局不是通用 PCB/原理图编辑器。** 针对教学数字电路;复杂密集电路可能无法布通或无法容纳结果框,此时应调整规格/布局,不要把失败输出当作成品。
- **8 个开关采用单列。** 两列方案在编码器案例中会堵塞路由;单列经实际网表和截图验证。
- 自动探针当前支持单输入 `PROBE_DIG` 电压指示器;不会自动改接电流钳或任意元件测试点。
- 图像为 Multisim 原生栅格导出,默认 A 纸约 960×720。放大不增加原始信息,不是矢量输出。
- 图纸的连通性正确不等于逻辑设计或仿真结果正确。发布示例验证了网络与导出,不代表所有输入组合均经过验证。
- 测试可运行:`python -m unittest discover -s . -p 'test*.py' -v`。当前整理版包含 8 项测试。
## 可选:Word 报告插图
这里是本地操作示例,**不是报告模板下载**。`报告副本.docx` 是占位文件名,需替换为使用者自己的本地文件。本仓库不附带个人报告或 Word/PDF 模板;插图功能只操作指定的本地文档,不会将文档自动上传到 GitHub。
```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements-word.txt
.\.venv\Scripts\python.exe figure.py insert "报告副本.docx" "out/encoder-original.png" --section "(一)" --nth 1 --caption "优先编码器电路"
```
需安装 Microsoft Word;请先备份并关闭待编辑文档。该功能会保存修改,不支持用 WPS 替代 Word COM。
## 许可与来源
保留原项目的 [GNU GPL v3 许可证](LICENSE)。本仓库是在已有 `multisim-ms14-builder` 源码基础上整理的修订版,包括模型文本保真、布局修正和运行结果导出;不将原有实现声称为全新原创。当前收到的源码不含 Git 历史,暂无法核实上游仓库地址。
`ms14.py` 内注明压缩码表来自 zlib 的 `contrib/blast/blast.c`。Multisim 元件、符号及模型由本机 Multisim 提供;软件与相关商标的权利归其权利人,GPL 不授予 Multisim 本身的使用许可。
## 公开仓库与个人文件
仓库公开展示源码、教学电路规格、脱敏案例图纸、截图和采样数据。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues