# Motor-CAD 脚本自动化仿真参考资料汇总

> 用途：作为仿真系统编程设计的参考资料
> 整理日期：2026-08-27
> 说明：Motor-CAD 的自动化接口在 2022 年后已从旧的 ActiveX（COM）体系迁移到 **PyMotorCAD**（基于 JSON-RPC 的 Python 接口，属 PyAnsys 生态），因此本资料以 PyMotorCAD 为主、ActiveX 为辅。文中所有链接均来自官方（Ansys / PyAnsys）或公开的社区与组织分享，并标注了来源性质。

---

## 一、官方核心资料（优先阅读）

### 1.1 PyMotorCAD 官方文档站（最重要，一站式入口）

- **PyMotorCAD 官方文档（含版本切换）**
  https://motorcad.docs.pyansys.com/
  - 稳定版（stable）与开发版（dev）及历史版本可在页面右上角切换。
  - 内容结构：Getting Started / User Guide / API Reference（Methods）/ Examples / Contributing。
  - 官方支持邮箱：pyansys.core@ansys.com；Bug 与功能请求走 GitHub Issues；问答走 Ansys Developer 论坛 Discuss 区。

- **PyMotorCAD Cheat Sheet（一页速查表 PDF）**
  https://cheatsheets.docs.pyansys.com/pymotorcad_cheat_sheet.pdf
  - 一页涵盖：启动/退出实例、几何与绕组参数设置、材料赋值、MotorLAB 模型构建、E-Magnetic 性能曲线提取、MATLAB 中调用 PyMotorCAD、ActiveX 旧脚本迁移写法。

- **API 参考（MotorCAD 对象全部方法）**
  https://motorcad.docs.pyansys.com/version/stable/methods/index.html
  - 包括：`MotorCAD` 主对象、`MotorCADCompatibility`（兼容旧 ActiveX 脚本）、几何对象与函数（`geometry` / `geometry_tree` / `geometry_shapes` / `geometry_drawing` / `geometry_fitting`）、工具函数、以及 **`MotorCADError` 错误/异常类型**（错误处理入口，见第三节）。

### 1.2 官方 GitHub 仓库：ansys/pymotorcad

- 仓库地址：https://github.com/ansys/pymotorcad
- PyPI 包：`ansys-motorcad-core`，安装命令：

  ```bash
  python -m pip install -U pip
  python -m pip install ansys-motorcad-core
  ```

- 许可证：MIT（注意：PyMotorCAD 本身开源，但交互控制 Motor-CAD 仍需要合法授权的 Motor-CAD 软件）。
- **examples/ 目录就是一套现成的自动化脚本样例库**，与文档站的 Examples 页一一对应（见 1.4）。
- Issues 页面（https://github.com/ansys/pymotorcad/issues）本身就是一份很好的"故障处理案例库"，可按 bug 标签检索：https://github.com/ansys/pymotorcad/labels/bug
- 发布记录（各版本修复内容，可用于排查版本相关问题）：https://github.com/ansys/pymotorcad/releases

### 1.3 User Guide 关键章节（操作说明）

| 章节 | 链接 | 内容要点 |
|---|---|---|
| User Guide 总览 | https://motorcad.docs.pyansys.com/version/stable/user_guide/index.html | 内部脚本、外部脚本、MATLAB、自适应模板、旧脚本兼容的整体框架 |
| 内部 Scripting 选项卡 | https://motorcad.docs.pyansys.com/version/stable/user_guide/internal_scripting.html | Motor-CAD 内置 Python 解释器 + Scripting 选项卡；`main()`、`thermal_steady` 等类的 initial/main/final 钩子结构；`MessageDisplayState` 弹窗控制 |
| 外部脚本 / 加入自己的 Python | https://motorcad.docs.pyansys.com/version/stable/user_guide/external_scripting.html | 安装模式（user / developer）、tox 测试、开发者贡献流程 |
| MATLAB 脚本 | https://motorcad.docs.pyansys.com/version/stable/user_guide/matlab_scripting.html | 通过 `py.importlib.import_module('ansys.motorcad.core')` 在 MATLAB 里直接用 PyMotorCAD 做完整 E-Magnetic 自动化（含图形数据逐点读取的 try/break 技巧） |
| 自适应模板脚本（Adaptive Templates） | https://motorcad.docs.pyansys.com/version/stable/user_guide/adaptive_templates.html | 自定义几何：Region/Line/Arc 对象、自适应参数、`reset_adaptive_geometry()`、外部 IDE 调试、`draw_objects()` 几何绘图调试、DXF 导入、圆角/槽口修改最佳实践 |
| 旧脚本向后兼容 | https://motorcad.docs.pyansys.com/version/stable/user_guide/backwards_compatibility.html | ActiveX → PyMotorCAD 的迁移规则：函数名改 snake_case；旧 `success` 返回值被**异常机制**取代（失败即抛 `MotorCADError`，必须 try/except）；`MotorCADCompatibility` 对象可最小改动运行旧脚本 |

### 1.4 官方 Examples（可直接运行的自动化脚本样例）

- 示例总入口：https://motorcad.docs.pyansys.com/version/stable/examples/index.html
  - 每个示例都可下载为 `.py` 或 Jupyter Notebook。
- 分类：
  - **Basic examples（基础）**：如 E-magnetic 基础脚本（建模→计算→导出 CSV→读图数据，含 `MotorCADError` 处理示范）https://motorcad.docs.pyansys.com/version/stable/examples/basics/emag_basics.html
  - **Internal scripting（内部脚本）**：
    - 热稳态 https://motorcad.docs.pyansys.com/version/stable/examples/internal_scripting/thermal_steady_state.html
    - 热瞬态（占空比中改冷却流量）https://motorcad.docs.pyansys.com/version/stable/examples/internal_scripting/thermal_transient.html
    - 电磁（计算前参数检查与修正）https://motorcad.docs.pyansys.com/version/stable/examples/internal_scripting/emag.html
    - 机械应力 https://motorcad.docs.pyansys.com/version/stable/examples/internal_scripting/mechanical_stress.html
    - 机械力/NVH https://motorcad.docs.pyansys.com/version/stable/examples/internal_scripting/mechanical_force.html
  - **Adaptive templates library（自适应模板库）**：梯形转子风道、圆弧槽底、转子缺口等 https://motorcad.docs.pyansys.com/version/stable/examples/adaptive_library/TrapezoidalDuct.html
  - **Linking（与其他 Ansys 产品耦合）**：Motor-CAD → Twin Builder 的 ECE 等效电路导出完整流程（JSON 配置驱动 + 错误捕获）https://motorcad.docs.pyansys.com/version/stable/_sources/examples/links/ece_export_for_twinbuilder.rst.txt
  - **Samples 仓库（dev 版）**：应力采样、区域边界峰值应力、Ansys Motion 力导出、SYNC 电机参数扫描等 https://motorcad.docs.pyansys.com/version/dev/samples/index.html

### 1.5 随软件安装的官方教程（本地，不要忽略）

Motor-CAD 安装目录下的 Tutorials 文件夹自带自动化教程 PDF 与示例（CADFEM 技术日上 Ansys 官方推荐的入口）：

- `C:\ANSYS_Motor-CAD\<版本>\Tutorials\ActiveX_Scripting.pdf` —— 通用脚本教程（含 Automation 教程的 section 2.iii，Scripting 选项卡官方文档也指向它）
- `C:\ANSYS_Motor-CAD\<版本>\Tutorials\FEA_Geometry_Scripting` —— FEA 几何脚本
- `C:\ANSYS_Motor-CAD\<版本>\Tutorials\Ansys_Optislang\Advance IPM` —— optiSLang 联合优化
- `C:\ANSYS_Motor-CAD\<版本>\Tutorials\Scripting_Control_In_Duty_Cycle` —— 占空比中的脚本控制
- `TwinBuilder_ECE_Tutorial` —— Twin Builder ECE 模型导出

出处（CADFEM 2021 技术日官方合作演讲）：https://www.cadfem.net/fileadmin/user_upload/05-cadfem-informs/resource-library/2021_siehr_CADFEM_Techday2_scripting_and_parallelization_for_motorcad.pdf
该 PDF 同时给出 ActiveX 三命令核心模式（SetVariable / DoXxxAnalysis / GetVariable）与 MATLAB、VBS 的最小示例，以及用 Blackbox Solver 做参数研究/优化并行化的思路。

### 1.6 Ansys 官方培训课程（Innovation Space）

- **Running Parallel Ansys Motor-CAD Calculations Through Scripting**（并行计算脚本化，基于 2026 R1）
  https://innovationspace.ansys.com/certifications/courses/running-parallel-ansys-motor-cad-calculations-through-scripting/
  - 用 Python multiprocessing 跑多个 Motor-CAD 实例做并行参数研究；MATLAB 则间接通过 Python 调 PyMotorCAD。
- **Induction Motor Design using Ansys Motor-CAD Sensitivity Analysis**（免费课，含 Python 要求）
  https://innovationspace.ansys.com/product/induction-motor-design-using-ansys-motor-cad-sensitivity-analysis/

---

## 二、自动化仿真的关键操作模式（编程设计要点）

以下内容提炼自官方文档，是设计仿真系统时的"骨架代码"模式。

### 2.1 连接方式与生命周期

```python
import ansys.motorcad.core as pymotorcad

# 外部脚本：启动新实例（脚本结束后自动关闭）
mc = pymotorcad.MotorCAD()

# 外部脚本：启动新实例并保持打开（调试时有用）
mc = pymotorcad.MotorCAD(keep_instance_open=True)

# 连接已运行的实例 / 内部脚本环境
mc = pymotorcad.MotorCAD(open_new_instance=False)

# 官方示例推荐的"内外兼容"写法（Adaptive Templates 脚本通用）：
if pymotorcad.is_running_in_internal_scripting():
    mc = pymotorcad.MotorCAD(open_new_instance=False)
else:
    mc = pymotorcad.MotorCAD(keep_instance_open=True)
```

- 通信机制：Motor-CAD 启动 RPC 服务器，PyMotorCAD 通过 `http://localhost:<端口>/jsonrpc` 与之通信，也支持跨机 HTTP 远程连接。
- 无头运行：外部脚本支持 **BlackBox 模式**（不显示 GUI），适合服务器批量仿真。
- 多实例并行：一个外部脚本可同时驱动多个 Motor-CAD 实例（配合 Ansys optiSLang 做优化）。

### 2.2 自动化三件套（所有工作流的最小闭环）

```python
mc.set_variable("Tooth_Width", 6)          # 1. 设参数
mc.do_magnetic_calculation()                # 2. 跑计算（do_steady_state_analysis / do_transient_analysis / do_magnetic_calculation ...）
torque = mc.get_variable("ShaftTorque")     # 3. 取结果
```

配套常用方法：`load_template("e8")` / `load_from_file()` / `save_to_file()` / `save_results()` / `export_results("EMagnetic", path)` / `get_magnetic_graph()` / `get_fea_graph()` / `quit()`。

### 2.3 弹窗与消息控制（批处理必备）

```python
mc.set_variable("MessageDisplayState", 2)   # 消息进独立窗口，禁用弹窗
# ...批量计算...
mc.set_variable("MessageDisplayState", 0)   # 结束后恢复
```

> 官方警告：该设置会禁用关键弹窗（含保存提示、覆盖确认），脚本结束前务必恢复；且它**不能**替代异常处理。

### 2.4 内部脚本钩子结构（Scripting 选项卡 / Run During Analysis）

Motor-CAD 在计算前、每个迭代步、计算后分别调用用户类的 `initial()` / `main()` / `final()`。按求解类型定义类：`thermal_steady`、`thermal_transient`、`emagnetic`、`mechanical_stress`、`mechanical_forces`。典型用途：计算中动态修改边界条件（如热瞬态中按时间关断冷却流量）、计算前参数合法性检查与自动修正、计算后自动保存并退出（`save_and_close()` 模式，见 GitHub issue #741 的官方示例代码：https://github.com/ansys/pymotorcad/issues/741）。

### 2.5 MATLAB 集成

- 旧方式：`mcad = actxserver('MotorCAD.AppAutomation')`（ActiveX/COM）。
- 新方式（官方推荐）：MATLAB 内直接加载 Python 包
  `pymotorcad = py.importlib.import_module('ansys.motorcad.core')`，之后调用与 Python 完全一致；读 FEA 图数据时用 try/catch + break 的循环探测结束点（官方示例见 1.3 MATLAB 章节）。

### 2.6 几何自定义（Adaptive Templates）

- 版本要求：Motor-CAD ≥ 2024 R1 Update（v2024.1.2）且 PyMotorCAD ≥ 0.4.1；Motor-CAD 内置 PyMotorCAD 可通过 Scripting → Settings → PyMotorCAD updates 升级。
- 关键约束：Region 的实体（Line/Arc）必须**逆时针**顺序且闭合，否则几何/FEA 计算会失败（先用 `Region.is_closed()` 检查）；修改几何前先 `mc.reset_adaptive_geometry()`。
- 调试工具：`geometry_drawing.draw_objects()` 可在脚本里画出区域用于可视化调试；建议在外部 IDE（PyCharm/VSCode）+ 断点中开发，而不是 Motor-CAD 内置编辑器。

---

## 三、故障处理与常见问题汇总（错误处理机制 + 真实故障案例）

### 3.1 官方错误处理机制（编程设计时必须实现）

1. **`MotorCADError` 异常类型**：PyMotorCAD 与旧 ActiveX 的本质区别——API 调用失败时**直接抛异常**，不再有静默失败的 `success` 返回值。设计仿真系统时应对所有 Motor-CAD 调用做 try/except：

   ```python
   import ansys.motorcad.core as pymotorcad
   from ansys.motorcad.core import MotorCADError

   try:
       mc.do_magnetic_calculation()
   except pymotorcad.MotorCADError as e:
       print("Calculation failed: " + str(e))

   # 结果导出同样要捕获
   try:
       mc.export_results("EMagnetic", "Export_EMag_Results.csv")
   except pymotorcad.MotorCADError as e:
       print("Results failed to export due to Motor-CAD Error: " + str(e))
   ```

   出处：官方 E-Magnetic 基础示例 https://motorcad.docs.pyansys.com/version/stable/examples/basics/emag_basics.html 与向后兼容章节 https://motorcad.docs.pyansys.com/version/stable/user_guide/backwards_compatibility.html

2. **读图数据的"越界即结束"惯用法**：读取 graph 点到末尾会抛 `MotorCADError`，官方用 while + try/except 循环作为序列结束判断（MotorCAD API 只暴露最近显示的曲线；曲线名称和数据类型在 Motor-CAD 界面 Help → Graph Viewer 里查）。

3. **`MotorCADCompatibility` 对象**：旧 ActiveX 脚本可几乎不改地运行，方便过渡期对照排查问题。

### 3.2 真实故障案例库（论坛 + GitHub Issues，含现象/原因/对策）

| # | 故障现象 | 环境 | 原因与处理 | 来源 |
|---|---|---|---|---|
| 1 | `Failed to connect to Motor-CAD instance: port=58016, Url=http://localhost:58016/jsonrpc`，旧版本脚本突然全部失效 | 同机安装 Motor-CAD 2024.1.3 后又装 2024.2.3.1 | **多版本共存导致自动化注册/端口冲突**。检查 Defaults → Automation 里注册的版本；重装/修复安装使注册版本与实际调用版本一致；换到未混装的机器正常即印证是安装态问题 | Ansys 社区 https://discuss.ansys.com/discussion/4499/python-failed-to-connect-to-motor-cad-instance |
| 2 | `pymotorcad.MotorCAD()` 无法启动新实例 | Windows，Motor-CAD 设置里勾选了 "Hide command Window" | `activex.bat`（`C:\Ansys_Motor-CAD\Shared Files\`）内容格式变化导致 `_find_motor_cad_exe()` 找不到 exe。属已记录的已知 bug，升级 PyMotorCAD 或避免该选项 | GitHub Issue #140 https://github.com/ansys/pymotorcad/issues/140 |
| 3 | MATLAB `actxserver('motorcad.AppAutomation')` 报 "Server Creation Failed" | MATLAB + Motor-CAD（曾经可用，后失效） | ActiveX/COM 注册问题，多与安装/重装相关。对策：重新注册（Motor-CAD 首次安装后需**重启电脑**完成 ActiveX 注册）、检查注册表 ProgID、DCOM 配置与权限；Ansys 员工建议参考 MathWorks 对同类 COM 错误的 8 种修复方案；更根本的办法是迁移到 PyMotorCAD | Ansys 论坛 https://innovationspace.ansys.com/forum/forums/topic/problems-with-motorcad-automation/ ；GitHub Issue #495 https://github.com/ansys/pymotorcad/issues/495 |
| 4 | Python `win32com.client.Dispatch("MotorCAD.AppAutomation")` 报 `pywintypes.com_error: (-2146959355, '服务器运行失败')` | 中文用户，集成到自研软件时失败（单独运行正常） | DCOM 配置/权限/防火墙问题。对策：`dcomcnfg` 中配置 Motor-CAD Application Automation 的安全权限、以管理员运行、检查防火墙、确认 ProgID 拼写与安装路径 | 阿里云开发者社区 https://developer.aliyun.com/ask/551036 |
| 5 | Motor-CAD 报 "Unable to run FE module" | 模型本身无问题（官方复现可算） | 环境/权限问题。对策三步：跑默认模板模型排除模型问题 → **以管理员身份运行 Motor-CAD**（本案例即此解决）→ 确认装在默认目录 `C:\ANSYS_Motor-CAD`，否则重装到默认路径 | Ansys 论坛 https://innovationspace.ansys.com/forum/forums/topic/ansys-motor-cad-unable-to-run-fe-module/ |
| 6 | 自适应模板旋转转子极区域后 FEA 求解器识别不了绕组区域 | Motor-CAD 2025 R1 + PyMotorCAD 0.7 | 旋转后绕组区域被移到 template-other 节点下，区域树关系丢失。属 adaptive geometry 已知问题，跟踪 Issue | GitHub Issue #473 https://github.com/ansys/pymotorcad/issues/473 |
| 7 | 模型求解报几何错误，曾正常 | — | **重复的转子几何区域**（自定义几何/FEA Editor 脚本编辑产生）。删除重复区域即恢复。启示：脚本改几何后要做区域树校验 | Ansys 论坛 https://innovationspace.ansys.com/forum/forums/topic/ansys-motorcad-2/ |
| 8 | 启动时"无法获取许可证" | — | 检查许可证服务器网络连通性（ping）、许可证文件路径与有效期、Ansys License Manager 服务重启、防火墙放行 Ansys 许可端口、许可数量是否占满 | CSDN 文库 https://wenku.csdn.net/answer/7d9nmw0zdbw5 |
| 9 | 旧 ActiveX 示例中 `MagWindingType` 等参数名失效 | PyMotorCAD 示例与版本演进 | 参数名随版本改名（如 `MagWindingType` → `MagneticWindingType`）。设计系统时参数名应做成可配置映射表，勿硬编码 | GitHub Issue #319 https://github.com/ansys/pymotorcad/issues/319 |

### 3.3 从案例中提炼的排障清单（建议写入仿真系统的自检模块）

1. **连接层**：`pymotorcad.MotorCAD()` 失败 → 检查是否同机混装多版本、Automation 注册版本（Defaults → Automation）、端口被占用/防火墙拦截 localhost、是否勾选了 "Hide command Window"。
2. **权限层**：COM/FE 模块类错误 → 管理员身份运行、默认路径 `C:\ANSYS_Motor-CAD` 安装、首次安装后重启完成 ActiveX 注册。
3. **许可层**：拿不到 license → License Manager 服务、端口、文件有效期、并发数。
4. **模型层**：几何类失败 → 区域闭合性与逆时针顺序（`is_closed()`）、重复区域、Adaptive 脚本先 `reset_adaptive_geometry()`。
5. **脚本层**：所有 API 调用包 try/except `MotorCADError`；参数名做版本适配；批处理前关弹窗（`MessageDisplayState=2`）并在 finally 中恢复；结果导出校验文件实际生成。
6. **日志层**：内部脚本用 `mc.show_message()` 写入 Motor-CAD 消息窗口（带时间戳，天然形成运行日志）；外部脚本自行记录每次 set/calc/get 的参数与返回，便于复现。

---

## 四、GitHub 上的 Motor-CAD 自动化项目/工具盘点

> 结论先说：**GitHub 上真正可用、持续维护的 Motor-CAD 自动化项目基本只有 Ansys 官方的 `ansys/pymotorcad`**；没有形成规模的第三方"Motor-CAD 自动化 Skill/框架"。检索 `motor-cad`、`pymotorcad` 两个 topic 均显示"尚无公开仓库使用"，第三方内容以零散示例为主，且搜索中出现的"破解版/激活版"仓库（如 `Alez1704/ansys-motorcad-15-2-2-unlocked-edition`）**为盗版资源，务必避开，不要引入任何工程环境**。

| 项目 | 地址 | 性质 | 说明 |
|---|---|---|---|
| **ansys/pymotorcad** | https://github.com/ansys/pymotorcad | 官方、MIT、持续维护（~30 star，2026 年仍在活跃发版） | 核心库 + `examples/` 完整样例（基础、内部脚本、自适应模板库、Twin Builder/Motion 耦合、参数扫描）。**做仿真系统的首选参考实现**：源码里 `rpc_client_core.py` 展示了实例发现、连接、错误封装；issues/PR 是最好的故障案例库 |
| DeepWiki 对 ansys/pymotorcad 的结构化解读 | https://deepwiki.com/ansys/pymotorcad/5.1-adaptive-templates | 第三方（AI 生成的代码库导读） | 适合快速理解代码架构：几何对象体系、自适应参数、内外脚本执行上下文（`is_running_in_internal_scripting()` 分支） |
| Motor-CAD 热模型导入 Simulink/Simscape 示例 | GitHub 搜索 "motorcad" 可见（mathworks 相关仓库） | 组织分享 | Motor-CAD Thermal → Simulink/Simscape 的模型导入示例，做系统级联合仿真可参考 |
| 零散的 "motorCAD automation" 个人仓库 | GitHub 搜索可得（个位数 star） | 个人分享 | 质量参差，仅作灵感参考 |
| Ansys Innovation Space 并行计算课程配套脚本 | https://innovationspace.ansys.com/certifications/courses/running-parallel-ansys-motor-cad-calculations-through-scripting/ | 官方 | Python multiprocessing 并行驱动多 Motor-CAD 实例的完整示例（任务调度、排队、结果归集） |

如果你的目标是"给仿真系统找一个现成的自动化框架级 Skill"——目前公开生态里没有，可行路线是：**以 `ansys/pymotorcad` 为底座，自行封装一层任务队列 + 异常重试 + 日志的调度层**（并行模式直接参考官方并行课程与 optiSLang 集成方案）。

---

## 五、社区与第三方分享（组织/个人）

- **Ansys 官方社区（两个都要收藏）**
  - Ansys Developer Discussions（PyMotorCAD 官方答疑区）：https://discuss.ansys.com/
  - Ansys Innovation Space 论坛（Motor-CAD 板块）：https://innovationspace.ansys.com/forum/
- **CADFEM（Ansys 渠道合作伙伴，组织分享）**
  - 2021 技术日《Scripting and Parallelization for Motor-CAD》PDF：ActiveX 三命令模式、MATLAB/VBS 最小示例、Blackbox 并行化：https://www.cadfem.net/fileadmin/user_upload/05-cadfem-informs/resource-library/2021_siehr_CADFEM_Techday2_scripting_and_parallelization_for_motorcad.pdf
  - 2023 R1 更新要点（PyMotorCAD 取代 ActiveX 的官方背景说明）：https://www.cadfem.net/fileadmin/user_upload/CADFEM_CH/2023/PUB-CADFEM_Update_2023R1_LF_WBNR-FR.pdf
- **SimuTech Group（Ansys 精英渠道商，组织分享）**：用 Stochos 贝叶斯优化 + PyMotorCAD 做电机设计优化的完整工作流（Evaluator 函数封装模式值得借鉴）：
  https://simutechgroup.com/resources/blog/bayesian-optimization-electric-motor-design-using-stochos-and-motor-cad/
- **Ansys Developer Blog**：PyMotorCAD Cheat Sheet 发布说明：https://developer.ansys.com/blog/pymotorcad-cheat-sheet
- **中文社区排障帖**（个人分享，可作线索、注意甄别）：阿里云开发者社区 DCOM 排障 https://developer.aliyun.com/ask/551036 ；CSDN 文库许可证问题 https://wenku.csdn.net/answer/7d9nmw0zdbw5

---

## 六、给仿真系统编程设计的建议（基于以上资料）

1. **接口选型**：新系统一律基于 PyMotorCAD（JSON-RPC），不要再写 ActiveX；需要兼容存量脚本时用 `MotorCADCompatibility`。
2. **架构参考**：`ansys/pymotorcad` 源码本身是最好的"仿真软件自动化封装"参考——单类 API、异常即错误的语义、内外脚本双上下文判断（`is_running_in_internal_scripting()`）、实例生命周期参数（`open_new_instance` / `keep_instance_open`）。
3. **健壮性设计**：全链路 try/except `MotorCADError` + 重试；弹窗状态用 try/finally 恢复；参数名做版本映射表；每个任务落盘运行日志（时间戳 + 输入参数 + 结果/异常）。
4. **并行与调度**：参考官方并行课程用 Python multiprocessing 驱动多实例；批量任务前确保许可数量（每实例占用 license）并规划 BlackBox 无头模式。
5. **自检模块**：按 3.3 的五层清单（连接/权限/许可/模型/脚本）做启动自检，可显著降低现场排障成本。
6. **合规提醒**：PyMotorCAD 是 MIT 开源，但驱动 Motor-CAD 必须有合法授权；GitHub 上的"激活版/破解版"仓库一律不要碰。