AGENTS.md — AI 工具工作说明

本文件面向 Claude Code / Codex / Cursor / 豆包等 AI 编程工具。接到任何任务前，先读 docs/KNOWLEDGE_BASE.md。方法论框架：ai-collab-dev-playbook-v2.md（五支柱 + 五步启动法，新项目可复用）。接续入口：换人/换机/新会话先读 docs/HANDOFF.md。

项目定位

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

系统一（Web端）：方案生成与优化（FastAPI + Vue3，AI 闭环 / 自适应搜索 / 经验库）
系统二（本地EXE）：仿真执行（Motor-CAD / Maxwell / JMAG 适配器，批量调度）
共享核心层 src/afmcore/：指标 / 拓扑 / 适配器 / 策略 / L0 预筛选的单一事实源

当前状态：P1~P5 全部完成，P6 前端体验优化进行中（P6-M1 已完成，P6-M2/M3 待办）。进度、阻塞点、待办的唯一权威来源：docs/HANDOFF.md 第 3 节。

开始工作前必须阅读

最小必读集（新会话至少读这些）：

docs/HANDOFF.md — 当前进度、阻塞点、待办、接续提示词（含环境恢复步骤）
docs/KNOWLEDGE_BASE.md — 核心知识库（环境事实、参数语义、探测技术、SOP、已踩的坑），重点 §1 环境事实与 §3 参数语义

按需查阅：

README.md — 项目说明、目录结构、快速开始（历史更新见 CHANGELOG.md）
PCB轴向磁通电机自动化仿真系统设计方案介绍.md — 完整设计方案V2.0（架构、接口、算法选型）
docs/P1-P5交付总结与上手指南.md — 新人上手与模块定位
参考案例的知识库：
- axial_mag_pull-master/axial_mag_pull/docs/KNOWLEDGE_BASE.md
- torqrippswap-master/torqrippswap/MOTORCAD_SCAN_KNOWLEDGE_BASE.md
已完结的历史计划/评审文档见 docs/archive/

环境体检（换机/新会话第一条命令）

python scripts/check_machine_paths.py        # 只读核对环境，缺项会给修复建议
python scripts/check_machine_paths.py --fix  # 打印精确修复命令（不自动执行）

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

功能	参考文件	说明
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（含索引表 + 详细记录）
每次对话（含关键决策、技术选择、问题排查）必须记录到 docs/CONVERSATION_LOG.md，格式：## YYYY-MM-DD — 主题 → 用户要求 → 本次完成 → 遗留问题
记录内容包括：测试日期、测试环境、测试目的、测试步骤、测试结果（成功/失败）、关键数据、发现的问题、修复措施
测试输出文件（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 / 报告）

反模式自查（交付前对照，命中即返工）

反模式	对策
不读文档直接开工	先读 HANDOFF/KNOWLEDGE_BASE，先报告理解再动手
验收凭"看起来对"	量化基准 + 独立验证（校验方式≠产出方式）
踩坑不记录	坑立刻追加到 KNOWLEDGE_BASE / AGENTS 铁律
环境假设不检测	换机先跑 check_machine_paths.py
上下文只留在对话里	写 CONVERSATION_LOG 持久化
多处定义同一概念	走 src/afmcore 单一事实源
编造未验证的数值/接口	禁臆测 + 标注"待验证"
阶段完成不更新文档	每 P/M 完成立即更新 README

接续与交接

换人/换机/新会话：先读 docs/HANDOFF.md（进度/阻塞/待办/接续提示词），再跑 python scripts/check_machine_paths.py
阶段末（每 Phase/Milestone）：更新 HANDOFF.md 的「当前进度/阻塞点/待办」+ README「最近更新」
让下一个 AI 会话 10 分钟接上：整段粘贴 HANDOFF.md 第 4 节「接续提示词」

工程规范 — 严格执行

适用于所有代码、测试与交付，优先级高于"完成速度"。任何输出在交付前必须过一遍本节。

1. 禁止臆测

不得编造任何未实际验证的结果、数值、接口行为或"应该能跑"的结论。
若无法运行或测试某段代码/场景，必须明确说明："我无法执行此测试，以下是我的推理/建议"，并给出理由与降级方案，不得冒充已验证。

2. 测试完备

每段交付代码必须附带可运行的测试用例，至少覆盖：
- 正常路径（happy path）
- 边界条件（极值、上下限、最大/最小）
- 异常输入（非法值、缺字段、类型错误）
- 空值/零值场景
测试脚本统一放 scripts/test_*.py，命名与被测模块对应；python scripts/test_*.py 可独立运行，exit 0 = PASS。
无法自动化的场景（如真实 Motor-CAD 求解、真实 AI 调用）必须给出可复现的手动测试步骤，或在 TEST_RECORDS.md 标注"待验证"。

3. 代码规范

遵循语言标准规范（Python 遵循 PEP8；前端遵循项目既有风格）。
关键逻辑必须有注释；复杂函数/类必须有 docstring（函数用途、参数、返回值、异常）。
沿用 ASCII 约束（见"硬性工程约束 §1"），docstring 用英文。

4. 自查清单（交付前逐项确认，回复中标注 ✅/❌）

代码已通读一遍，无语法错误和明显逻辑漏洞
所有测试用例已列出，且能描述预期输入与输出
已考虑边界情况（空值、极值、并发、超时、资源耗尽等）
已考虑错误处理路径（异常捕获、回滚、降级）
如果涉及多模块，已确认接口契约和数据流向
如果无法实际运行测试，已明确告知用户

5. 交付声明

只有完成上述自查并确认无误后，才能说"已完成/已通过"。
否则必须使用"草案待验证"或"需要您协助测试"，并说明缺口。

6. 迭代修正

若用户反馈测试失败，必须：复现问题 → 定位根因 → 修复 → 重新走一遍自查清单 → 再回复。
不得仅口头致歉后跳过复现与修复。

AGENTS.md 11 KB History Raw