# 使用任意 AI 编程工具维护 Motor-CAD 扫描项目

本文面向使用 Claude Code、Codex CLI、Cursor、GitHub Copilot、Kiro、Cline、Continue 或其它
AI 编程工具的开发者。目标是让新的 AI 助手在不了解历史对话的情况下，也能安全维护、构建和运行
本项目。

## 1. 项目用途

本项目使用 Ansys Motor-CAD 的 Python 自动化接口进行参数扫描，并提供 Windows GUI/EXE：

- 设置模型文件；
- 设置参数范围和步长；
- 启动独立、前台可见的 Motor-CAD 实例；
- 实时显示进度和仿真结果；
- 保存带详细时间戳的汇总 CSV、原始结果和程序日志；
- 在每个扫描点重新加载基线模型，避免参数累积污染。

## 2. AI 开始工作前必须阅读

让 AI 按顺序阅读：

1. `MOTORCAD_SCAN_KNOWLEDGE_BASE.md`
2. `README_Central_Mag_Arc扫描.md`
3. `motorcad_scan_gui.py`
4. `scan_central_mag_arc.py`
5. 与任务对应的参数配置 JSON
6. `E:\aitestlocal\claude\motorcadopt\CLAUDE.md`
7. `E:\aitestlocal\claude\motorcadopt\TORQUE_RIPPLE_ANALYSIS.md`

其中 `MOTORCAD_SCAN_KNOWLEDGE_BASE.md` 是本项目的主要知识入口，包含参数映射、求解设置、
运行约束、结果指标和已知 Motor-CAD 陷阱。

## 3. 可直接复制给 AI 的首次提示词

```text
请先完整阅读 MOTORCAD_SCAN_KNOWLEDGE_BASE.md 和 README_AI_TOOLS.md，再检查当前 Git 状态。
这是 Windows 原生 Motor-CAD 自动化项目。所有 .py 和 .ps1 源码必须只含 ASCII 字符。
任何实际 Motor-CAD 求解启动前，必须先有 Git 提交，并确保所有已跟踪文件无未提交修改。
Motor-CAD 必须使用独立、前台可见的实例，不能抢占其它程序正在使用的实例。
不要猜 Motor-CAD 变量名；先从 .mot、已有参数表或探测结果确认，写入后必须回读校验。
每个扫描点开始前重新加载基线模型，每点完成后立即保存 CSV 和日志。
先说明你检查到的事实和计划，再进行修改。
```

## 4. 环境要求

### 4.1 操作系统

- Windows 10 或 Windows 11；
- 已安装与模型兼容的 Ansys Motor-CAD；
- 使用 Windows 原生 Python，不能使用 WSL Python。

### 4.2 Python 依赖

```powershell
python -m pip install ansys-motorcad-core pyinstaller
```

Tkinter 通常随 Windows Python 安装。验证：

```powershell
python -c "import tkinter; import ansys.motorcad.core; print('OK')"
```

### 4.3 Git

本机可能出现仓库所有权保护错误。不要修改全局 Git 配置，使用每条命令的局部配置：

```powershell
git -c safe.directory=E:/aitestlocal/codex/tr status
```

## 5. 硬性工程约束

### 5.1 脚本必须是纯 ASCII

所有 `.py` 和 `.ps1` 文件只能包含 ASCII 字符。中文说明写在 Markdown 文件中。

检查命令：

```powershell
rg -n "[^\x00-\x7F]" --glob '*.py' --glob '*.ps1' .
```

如果命令输出任何行，先修正，再构建或运行。

### 5.2 运行前必须提交 Git

实际启动 Motor-CAD 求解前必须满足：

```powershell
git -c safe.directory=E:/aitestlocal/codex/tr rev-parse --verify HEAD
git -c safe.directory=E:/aitestlocal/codex/tr status --porcelain --untracked-files=no
```

第二条命令必须没有输出。GUI 内置 Git preflight，不满足时应拒绝启动扫描。

### 5.3 不影响其它 Motor-CAD 实例

如果其它程序正在使用 Motor-CAD，不要使用模糊的“连接已有实例”方式。扫描程序应创建独立实例：

```python
mc = pymotorcad.MotorCAD(open_new_instance=True, keep_instance_open=False)
mc.set_visible(True)
```

### 5.4 参数必须验证

不能只调用 `set_variable`。必须回读：

```python
mc.set_variable(variable, value)
applied = mc.get_variable(variable)
```

回读不一致时将该点标记为 `FAILED`，保存错误并继续下一点。

## 6. 当前关键参数

| 用户界面名称 | Motor-CAD 变量 | 说明 |
|---|---|---|
| Central Mag Arc [ED] | `MagnetCentralArc_HalbachRing` | Halbach 中央磁块弧角 |
| Magnet Arc [ED] | `Magnet_Arc_[ED]` | 整体磁铁极弧 |
| Slot Opening | `Slot_Opening` | 槽口宽度 |
| Copper Width | `Copper_Width` | PCB 铜线宽度 |

`Central Mag Arc [ED]` 和 `Magnet Arc [ED]` 不是同一个参数，禁止混用。

## 7. 主要程序和配置

| 文件 | 用途 |
|---|---|
| `motorcad_scan_gui.py` | GUI 主程序 |
| `scan_central_mag_arc.py` | 单参数扫描、结果解析和分析基础代码 |
| `scan_parameters.json` | 二参数扫描配置 |
| `scan_parameters_magnet_arc.json` | Magnet Arc 单参数配置 |
| `build_gui_exe.ps1` | PyInstaller 通用构建脚本 |
| `package_magnet_arc_v2.ps1` | Magnet Arc V2 单参数包生成脚本 |
| `MOTORCAD_SCAN_KNOWLEDGE_BASE.md` | 项目知识库 |

## 8. 构建 EXE

构建前先提交所有已跟踪修改：

```powershell
git -c safe.directory=E:/aitestlocal/codex/tr add -- <files>
git -c safe.directory=E:/aitestlocal/codex/tr commit -m "Describe the change"
```

构建通用 GUI：

```powershell
powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\build_gui_exe.ps1 -AppName MotorCADParameterScanV3
```

生成 Magnet Arc 单参数 V2 包：

```powershell
powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\package_magnet_arc_v2.ps1
```

输出位于：

```text
dist/<AppName>/<AppName>.exe
```

不要覆盖仍在运行的旧版 EXE 目录。需要修改布局或逻辑时使用新的应用名，例如 V4。

## 9. 运行方法

1. 启动对应 EXE；
2. Browse 选择 `.mot` 模型；
3. 检查扫描参数、起点、终点和步长；
4. 检查 Torque points 和 Airgap mesh；
5. 二参数扫描时确认两个水平数量的乘积；
6. 点击 Start；
7. 确认弹窗中的总仿真数和预计耗时；
8. 观察前台 Motor-CAD 和 GUI 进度；
9. 需要停止时使用 `Stop after current point`，不要强制结束当前求解。

## 10. 输出文件

每次运行创建：

```text
runs/YYYYMMDD_HHMMSS_mmm_<scan_name>/
```

主要文件：

- `run_manifest_<timestamp>.json`：完整运行配置和 Git 提交；
- `scan_results_<timestamp>.csv`：汇总结果；
- `program_log_<timestamp>.log`：详细时间戳日志；
- `raw/result_*.csv`：每个扫描点的原始 Motor-CAD 导出结果。

分析问题时，AI 应先读取 manifest 和 log，再读取汇总 CSV，最后只打开相关的 raw 文件。

## 11. 结果指标

程序当前关注：

- Torque Ripple，百分比和 Nm；
- Average torque (virtual work)；
- System Efficiency；
- Back EMF 及 THD；
- Total Losses；
- DC copper loss；
- Magnet loss；
- Stator iron loss；
- Input、Output 和 Electromagnetic Power；
- Shaft speed 和 No-load speed。

Motor-CAD 导出文件使用分号分隔，同一指标可能在多个段落重复或带状态后缀。不要用普通逗号 CSV
解析器直接读取原始结果。

## 12. 修改或增加扫描参数

AI 不得凭记忆猜变量名。推荐流程：

1. 在 `.mot` 文件中搜索 GUI 名称附近的候选变量；
2. 查询 `motorcadopt/results/mot_params_relevant.csv`；
3. 用单点脚本写入并回读；
4. 必要时保存几何截图，确认参数确实改变模型；
5. 将已验证映射加入配置和知识库；
6. 添加范围检查；
7. 用 1–2 点 dry run 或真实单点验证；
8. 提交 Git 后才允许完整扫描。

## 13. 给 AI 的具体任务模板

### 增加单参数扫描

```text
请在不影响现有 EXE 的前提下，增加 <GUI 参数名> 单参数扫描。
先从 .mot 和已验证参数表确认 Motor-CAD 自动化变量名，不要猜。
沿用 V2 三行布局：模型；参数与 Start/Stop/Step；Torque points/Airgap mesh。
所有 .py/.ps1 只能包含 ASCII。写入后回读校验，每点重新加载基线，每点立即保存结果。
修改完成后运行静态检查，提交 Git，再用新的应用名构建 EXE。不要启动完整仿真。
```

### 增加二参数扫描

```text
请将参数 A 和参数 B 做笛卡尔积扫描，总数量必须显示为 NA x NB。
启动前显示组合总数和预计时长并要求确认。
每个点重新加载基线，按依赖顺序写参数并逐个回读。
结果 CSV 必须同时记录 A、B、所有联动值、求解设置和 Git 提交。
保留旧版 EXE，构建新的版本目录。
```

### 分析扫描结果

```text
请先读取最新 runs 目录中的 manifest、log 和 scan_results CSV。
检查失败点、参数写入、Torque points、airgap mesh 和 Git 提交。
按 Torque Ripple 排序，同时施加 Tavg、效率、损耗和转速约束。
快速扫描只用于趋势判断，给出需要用 180 点和收敛网格复算的候选列表。
```

## 14. 提交前检查清单

- [ ] 阅读知识库；
- [ ] 确认真实 Motor-CAD 参数名；
- [ ] 不影响其它 Motor-CAD 实例；
- [ ] `.py`、`.ps1` 纯 ASCII；
- [ ] Python 编译检查通过；
- [ ] JSON 能正常解析；
- [ ] Git diff 无空白错误；
- [ ] 已跟踪修改已提交；
- [ ] EXE 使用新目录构建；
- [ ] GUI 启动测试不自动开始求解；
- [ ] 完整扫描前先做单点验证。