# 接续指南 · PCB 轴向磁通电机自动化仿真系统

> 面向**换人 / 换机 / 新会话**后继续工作的场景。
> 配套框架：`ai-collab-dev-playbook-v2.md`（方法论）+ `AGENTS.md`（AI 行为准则）。
> 最后更新：2026-09-01

---

## 1. 环境要求

| 软件 | 版本 | 用途 | 必需性 |
|---|---|---|---|
| Motor-CAD | 2026R1 (v261) | 电磁/热/结构仿真求解 | 必需（仿真） |
| Python | ≥ 3.10 | 执行器 / 后端 / 测试 | 必需 |
| ansys-motorcad-core | 0.8.x | pymotorcad 自动化接口 | 必需（仿真） |
| PySide6 / pandas | 最新稳定 | GUI / 数据处理 | 必需 |
| fastapi / uvicorn / pydantic | 最新稳定 | Web 后端 | 必需（Web） |
| Node.js / npm | ≥ 18 | 前端 Vue3 构建 | 必需（Web） |
| Ansys License Manager | FlexNet | 许可证（lmgrd + ansyslmd） | 必需（仿真） |
| Ansys Maxwell + PyAEDT | — | Maxwell 适配器（当前 mock） | 可选（待接入） |
| JMAG + jmagpy | — | JMAG 适配器（当前 mock） | 可选（待接入） |
| scipy/numpy | — | Kriging 代理（当前 IDW 降级） | 可选（待升级） |

---

## 2. 恢复步骤（第一条命令）

```powershell
# 1) 核对环境（只读体检，缺项会给修复建议）
python scripts/check_machine_paths.py

# 2) 验证环境变量（非登录 shell 可能不继承，见 docs/KNOWLEDGE_BASE.md §1）
echo $env:MOTORCAD_ACTIVEX
echo $env:ANSYSLMD_LICENSE_FILE

# 3) 前端依赖（如需构建）
cd web/frontend; npm install

# 4) 后端启动（开发态，两终端）
python -m uvicorn app.main:app --port 8000   # 在 web/backend 下

# 5) 本地执行器（仿真端，enable_mock=true 时无需 Motor-CAD）
python scripts/run_task_executor.py --config executor_config.json
```

---

## 3. 当前进度（2026-09-03）

### 已完成
- **P1**：环境验证 + 单工况仿真 + 参数扫描引擎 + 方案 JSON 接口 + PySide6 GUI + 经验库雏形
- **P2**：Web 端方案系统（FastAPI + Vue3）+ 本地执行器真实仿真全链路打通
- **P3**：AI 驱动智能仿真闭环（策略抽象层 + 自适应编排器 + 批次化 + HTTP 闭环 + 真实烟雾测试）
- **P4**：Web AI 集成 + 双系统闭环 + 批量调度 + Schema 统一 + EXE 打包（`dist/PCB-AFM-Executor.exe`）
- **P5**：平台化增强 M1~M6（前端 build 清零 / EXE 配置化 / adaptive 三视图 / Morris+IDW 策略 / 多工具适配器 / 多物理场 L2 热+结构指标）
- **P6-M1**：Web 前端 UI/UX 全面重构（设计令牌 + 3 公共组件 + B1 信息架构 + B2 PlanDetail 分层）
- **P6-M2**：BC 参数目录单一事实源（`bc_fields.py` 25 字段 + `/api/bc-fields` + `normalize_bc` 统一 key 口径，消除 current_a/rated_ 双轨）
- **P6-M3**：仿真前检查清单（`/api/plans/{id}/preflight` 5 项检查）+ 耗时校准（实测 solve_time_s 均值回写）+ 任务创建自动展开方案参数
- **仿真失败根因修复（2026-09-03，关键）**：MARS 模型变量名经 pymotorcad 实测修正——`RotorOuterDiameter`/`Stator_Lam_Dia`/`Stator_Bore`/`Back_Iron_Thickness`/`PhaseAdvance`（原模板用径向电机命名全错）+ 磁钢材料值 `NdFeB_N42SH`→`N42UH`；详见 KNOWLEDGE_BASE §3.3
- **生产链路全通畅（2026-09-03）**：修复拓扑预检变量集、执行器 dispatch 状态机冲突、适配器 scripts 导入路径；**多点扫描实测通过**（3 点 Airgap：tavg 0.566/0.522/0.468 Nm，趋势符合电磁学）
- **AI 生成链路修复**：Kimi max_tokens 撞顶（2000→配置值）+ topology/strategy 枚举归一化兜底 + 生成摘要对话框 + 扫描变量归一化（SCAN_PARAMETERS 8→13）
- **UI 评审修复**：统计卡字段名 Bug + Dashboard 结果加载（.items）+ BC 空值折叠 + 失败结果错误信息列 + 监控页合并（ExecutionMonitor）+ 批量清理（项目/任务）+ 扫描变量编辑持久化 + 列配置 localStorage
- **PROMPTS_DIR 根因修复（2026-09-03，重大）**：`config.py` 的 `BACKEND_DIR=app/` 导致 `PROMPTS_DIR` 指向不存在的 `app/prompts/`（实际在 `web/backend/prompts/`）→ **真 prompt（generate.txt/analyze.txt）从未加载，一直走兜底**。修复后 AI 变量名遵循度根治、bc_suggestions 生效、验收标准格式规范。新增 `extract.txt`（经验提取）。详见 KNOWLEDGE_BASE §1.2
- **用户四需求（2026-09-03）**：拓扑默认模型自动调用（topology registry `default_model` + 三处回退 + 预检一键修复）+ 全量 25 项 BC 表单与来源标签（用户指定/AI 补充/已修改，bc_meta 追踪）+ 验收标准自动带出 + BC/固定参数默认全展开可编辑保存
- **自适应闭环全链路打通（2026-09-03/04，TEST-045~049）**：修复 6 个集成断层（variables/scan_variables 字段名、start/stop 键名、闭环缺 topology/model_path、**L0 参数名口径**——afmcore/l0 加 MOTORCAD_TO_L0 语义映射、初始批次不消费、report-results 路由缺失、export/import inf 哨兵）+ submit-batch 固定参数合并 + **执行器自动回传闭环**（adaptive_batch 完成自动调 report-results）。端到端实测：8+12 点真实仿真全成功，AI 经验提取 2 轮成功
- **经验提取数据完整性**：report_results 合入输入 params + condense 经 MOTORCAD_TO_L0 翻译（修复"AI 拿不到输入参数无法做敏感性分析"）

### 当前阻塞点
1. **热仿真稳态已打通（2026-09-04 实测）**：`enable_thermal` 修复后 MARS 稳态热跑通（电磁 127.8s + 热 6s）。剩余：MARS 模型 `Ambient_Temperature=125` 异常待修正（致温升/热阻为负）；磁热耦合 `do_magnetic_thermal_calculation` / 瞬态 `do_transient_analysis` 待实测；执行器 enable_thermal 全链路待验证
2. **Maxwell/JMAG 适配器为 mock**：真实接入待目标机环境（Ansys Maxwell + PyAEDT / JMAG + jmagpy）
3. **代理模型为 IDW 降级**：Kriging 待引入 scipy 后同接口替换
4. **中文仓库根 + git 2.52.0.windows.1 子目录命令卡死**：规避 = 先 `cd` 到目标子目录再用相对文件名（见 KNOWLEDGE_BASE §1）

### 待办
- 修正 MARS 模型环境温度 `Ambient_Temperature`（125→25~40°C）后复跑热仿真，验证温升/热阻转正
- 实测磁热耦合 `do_magnetic_thermal_calculation`（电磁+热一次算，用户"一起做省时间"诉求）
- 热仿真接入执行器 enable_thermal 全链路（GUI/扫描点热指标落盘）
- 其他拓扑（DRSS/SDSR）/其他模型的变量名需按 MARS 同样方法实测后登记到 `topology_variable_map`（当前仅 SSSR/MARS 经实测）；DRSS/SDSR 无基础模型文件，待用户提供 .mot 后登记到 topology registry 的 default_model
- 全闭环自动流转的长时端到端观察（信任域收敛）；历史方案（prompt 修复前生成）质量参差，建议关键方案重新生成
- 前端实机走查：AI 生成 → 检查清单 → 启动仿真 → 结果趋势（用户回归）

---

## 4. 给 AI 的接续提示词（整段粘贴）

```text
这是 PCB 轴向磁通电机自动化仿真系统项目。双系统解耦的轴向磁通电机自动化仿真
平台：Web端方案生成（FastAPI+Vue3）+ 本地EXE仿真执行（Motor-CAD），共享核心层
src/afmcore/ 为单一事实源。当前 P6 阶段，P6-M1 已完成前端 UI/UX 重构。

【先做这几件事，做完再动任何东西】
1. 读 docs/HANDOFF.md、docs/KNOWLEDGE_BASE.md、docs/TEST_RECORDS.md、AGENTS.md。
   KNOWLEDGE_BASE 里记录了大量踩过的坑（环境变量陷阱、Git 子目录卡死、
   CurrentDefinition 语义、export_results 兼容性等），请重点看，不要重复踩。
2. 核对环境：python scripts/check_machine_paths.py
3. 确认当前进度与阻塞点（见 HANDOFF.md 第 3 节）。

【工作约定（必须遵守）】
- 每次测试前先 git commit；每次对话记录到 docs/CONVERSATION_LOG.md；
  每次测试记录到 docs/TEST_RECORDS.md（含 TEST 编号索引）。
- 源码（.py/.ps1）只含 ASCII，中文写进 Markdown；脚本用英文注释。
- Motor-CAD 用 open_new_instance=True 独立实例 + set_visible(True)；
  参数写入必须回读校验；每个扫描点结束立即落盘。
- 不要修改 models/ 下原始 .mot；参考目录只读；生成物（output/runs/build/dist/*.log）不入库。
- 仿真禁止跑在主线程（GUI 需 QThread）。

【铁律（血泪教训）】
- 非登录 shell 可能不继承 MOTORCAD_ACTIVEX / ANSYSLMD_LICENSE_FILE → 脚本内回退
- Git 子目录路径命令可能永久挂起 → 先 cd 到子目录再用相对文件名
- 多处定义同一概念会漂移 → 指标/拓扑/Schema 一律走 src/afmcore 单一事实源
- 交付前过自查清单，未验证只能标注"待验证/草案"，禁止编造数值

【当前状态】
- 已完成：P1~P6 全部（含 P6-M2 参数目录单一事实源、P6-M3 检查清单+耗时校准）；
  2026-09-03 仿真失败根因（MARS 变量名/材料名）已实测修复，多点扫描生产链路全通畅；
  2026-09-03/04 PROMPTS_DIR 根因修复（真 prompt 首次生效）+ 自适应闭环全链路打通
  （含执行器自动回传，TEST-045~049 实测）
- 阻塞：热求解/多工具/Kriging 待环境或真实运行
- 待办：DRSS/SDSR 拓扑模型与变量名实测登记；热求解真实验证；闭环长时运行观察；前端实机走查

【接下来做什么】
- <目标1> / <目标2>

先读文档、恢复环境、跑 check_machine_paths.py，然后告诉我你的理解和建议的
下一步，不要直接开始改东西。
```

---

## 5. 文档索引

| 文档 | 内容 |
|---|---|
| README.md | 项目全貌 + 最近更新摘要（历史更新见 CHANGELOG.md） |
| CHANGELOG.md | 全部历史更新记录（按时间倒序） |
| AGENTS.md | AI 行为准则（工程规范 / 铁律 / 反模式） |
| ai-collab-dev-playbook-v2.md | AI 协作方法论框架 V2（新项目可复用） |
| docs/KNOWLEDGE_BASE.md | 环境事实 / 参数语义 / 探测技术 / SOP / 已踩的坑 |
| docs/TEST_RECORDS.md | 测试记录（TEST-001~024，含索引） |
| docs/CONVERSATION_LOG.md | 会话与决策记录 |
| docs/P1-P5交付总结与上手指南.md | 里程碑全盘核对 + 新人上手 |
| docs/PAPER_KNOWLEDGE_BASE.md | 无铁心 PCB-AFPM 论文知识库（38 篇） |
| docs/PLATFORM_DESIGN_V2.md | 平台化升级设计方案 |
| docs/archive/ | 已完结历史计划文档（P3/P4 实施计划等，仅供追溯） |