AGENTS.md — AI 工具工作说明

本文件面向 Claude Code / Codex / Cursor / 豆包等 AI 编程工具。接到任何任务前，先读 docs/KNOWLEDGE_BASE.md。

项目定位

PCB轴向磁通电机自动化仿真系统 — 双系统解耦架构：

系统一（Web端）：方案生成与优化（Phase 2+）
系统二（本地EXE）：仿真执行（当前Phase 1重点）

当前处于 Phase 1 最小闭环开发：本地GUI方案编辑 → Motor-CAD自动化仿真 → 结果输出 → 经验库积累。

开始工作前必须阅读（按顺序）

docs/KNOWLEDGE_BASE.md — 核心知识库（环境事实、参数语义、探测技术、SOP、已踩的坑）
README.md — 项目说明、目录结构、快速开始
PCB轴向磁通电机自动化仿真系统设计方案介绍.md — 完整设计方案V1.1（架构、接口、算法选型）
参考案例的知识库：
- axial_mag_pull-master/axial_mag_pull/docs/KNOWLEDGE_BASE.md
- torqrippswap-master/torqrippswap/MOTORCAD_SCAN_KNOWLEDGE_BASE.md

参考案例代码（可直接复用/改造）

功能	参考文件	说明
Motor-CAD连接与前台可见	`torqrippswap-master/torqrippswap/solver.py` → `MotorCADSolver.connect()`	`open_new_instance=True` + `set_visible(True)`
参数写入+回读校验	`torqrippswap-master/torqrippswap/solver.py` → `_write_and_verify()`	写入后get_variable回读，不一致抛异常
每点基线重载	`torqrippswap-master/torqrippswap/solver.py` → `run_single_point()`	每点 `load_from_file` 防止污染
结果导出与解析	`torqrippswap-master/torqrippswap/solver.py` → `parse_export()` / `extract_all_metrics()`	分号分隔CSV，中英文字段别名匹配
扫描执行+逐点落盘	`torqrippswap-master/torqrippswap/solver.py` → `run_scan()`	manifest+CSV+log+raw，每点flush
Git preflight	`torqrippswap-master/torqrippswap/solver.py` → `git_preflight()`	运行前检查仓库干净
AFM轴向力3D力图读取	`axial_mag_pull-master/axial_mag_pull/axial_force_final.py`	`get_magnetic_3d_graph_point`，Fr=轴向力
三判据校验	`axial_mag_pull-master/axial_mag_pull/axial_force_final.py`	作用反作用/转矩交叉/解析量级

硬性工程约束（违者返工）

1. 源码字符集

所有 .py 和 .ps1 文件必须只包含 ASCII 字符。中文说明写在 Markdown 文档中，不能写进脚本注释、字符串、窗口标题。中文字段名用 \uXXXX Unicode 转义。

检查命令：

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

2. 运行前必须 Git 提交

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

Git 仓库存在且 HEAD 有效
所有已跟踪文件无未提交修改

GUI 内置 Git preflight，不满足时拒绝启动扫描。

3. Motor-CAD 实例管理

使用 open_new_instance=True 创建独立实例，不要连接已有实例（可能控制错误窗口）
启动后必须 set_visible(True)（/SCRIPTING模式默认隐藏主窗口）
每个扫描点开始前 load_from_file(基线模型)，结束后也重载基线

4. 参数必须回读校验

不能只调用 set_variable。必须：

mc.set_variable(variable, value)
applied = float(mc.get_variable(variable))
if not math.isclose(applied, value, rel_tol=1e-8, abs_tol=1e-7):
    raise RuntimeError(...)

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

5. 结果逐点落盘

每个点完成后立即写 CSV 并 flush，不能等整批完成后一次性保存
失败点记录错误并继续
运行目录结构：output/<timestamp>_<scan_name>/ 含 manifest.json + scan_results.csv + program_log.log + raw/

6. 原始模型只读

原始 .mot 文件不修改
所有操作在 Motor-CAD 内存中进行，或另存时间戳副本
models/ 目录下的模型文件视为只读

7. 生成物不入库

output/、runs/、build/、dist/、*.log、*.spec 不入库
关键数值转录进入库的文档（RESULTS.md / 报告）

环境变量陷阱（AI shell 常踩）

非登录 shell 可能不继承机器级环境变量：

MOTORCAD_ACTIVEX 为空 → pymotorcad 找不到 Motor-CAD
ANSYSLMD_LICENSE_FILE 为空 → Motor-CAD 启动后 ~30s 静默退出

脚本内回退：

import os
if not os.environ.get("MOTORCAD_ACTIVEX"):
    from ansys.motorcad.core import set_motorcad_exe
    candidate = r"D:\Program Files\ANSYS Inc\v261\motorcad\MotorCAD.exe"
    if os.path.exists(candidate):
        set_motorcad_exe(candidate)

不要做的事

不要猜 Motor-CAD 变量名 — 先从 .mot、已有参数表或探测结果确认
不要在主线程运行仿真（GUI会卡死）— 必须用 QThread 子线程
不要修改原始 .mot 文件
不要把生成物提交到 Git
不要在 .py 文件中写中文字符（用 Unicode 转义或放 Markdown）
不要用 open_new_instance=False 连接已有实例

项目纪律（违者返工）

1. 每次阶段/里程碑完成必须更新 README.md

每个 Phase（P1/P2/P3/P4...）或每个 Milestone（M1/M2/M3...）完成后，必须立即更新 README.md，记录：
- 完成的功能点
- 新增的文件/模块
- 关键技术决策
- 已知问题和后续计划
不允许"代码提交了但 README 没更新"的情况
README 更新应与代码提交在同一个 commit 中，或紧随其后

2. 每次测试必须工作留痕

每次实际运行 Motor-CAD 仿真、API 测试、集成测试后，必须记录到 docs/TEST_RECORDS.md
记录内容包括：测试日期、测试环境、测试目的、测试步骤、测试结果（成功/失败）、关键数据、发现的问题、修复措施
测试输出文件（CSV/JSON/log）保留在 output/ 目录中，不入库但在记录中注明路径
失败的测试也要记录，包括失败原因和后续修复

3. Git 提交信息规范

Commit message 格式：type(scope): description
- type: feat/fix/docs/refactor/test/chore/enhance
- scope: 模块名（如 robust_motorcad, frontend, backend, p4-m3）
重大变更在 commit message 中详细说明，不允许只写 "update" 或 "fix bug"

4. 生成物不入库

output/、runs/、build/、dist/、*.log、*.spec、__pycache__/ 不入库
关键数值转录进入库的文档（TEST_RECORDS.md / RESULTS.md / 报告）

AGENTS.md 6.4 KB История Директен файл