# AGENTS.md — AI 工具工作说明

> 本文件面向 Claude Code / Codex / Cursor / 豆包等 AI 编程工具。
> 接到任何任务前，**先读 [docs/KNOWLEDGE_BASE.md](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 节。

## 开始工作前必须阅读

**最小必读集**（新会话至少读这些）：
1. `docs/HANDOFF.md` — 当前进度、阻塞点、待办、接续提示词（含环境恢复步骤）
2. `docs/KNOWLEDGE_BASE.md` — 核心知识库（环境事实、参数语义、探测技术、SOP、已踩的坑），重点 §1 环境事实与 §3 参数语义

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

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

```powershell
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 转义。

检查命令：
```powershell
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`。必须：
```python
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 静默退出

脚本内回退：
```python
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. 迭代修正
- 若用户反馈测试失败，必须：复现问题 → 定位根因 → 修复 → **重新走一遍自查清单** → 再回复。
- 不得仅口头致歉后跳过复现与修复。