docs: 强化 AGENTS.md 单位原则——模型单位≠米（取决于文档单位），补充测试警示

- 新增三层单位语义表（模型单位/米/配置项）
- 强调模型单位取决于当前 NW 文档单位（如 Floor2 为英尺，1米=3.281模型单位），禁止假设等于米
- 明确 TotalLength 等长度属性返回米，禁止二次换算
- 新增 §6.4 测试警示：集成测试断言长度必须按文档单位因子换算，涉及单位换算的断言不放单测
- 排查指引新增'长度/尺寸偏差约 3.28 倍'条目（源于本次集成测试单位踩坑）

AGENTS.md

@@ -125,9 +125,32 @@ var rotation = new Rotation3D(qx, qy, qz, qw);
 
 ## 6. 单位原则
 
-内部一律用**模型单位**，UI和外部交互使用**米单位**。米单位变量以 `InMeters` 结尾，模型单位不加后缀。
+### 6.1 三层单位语义（禁止混用）
 
-优先用 `UnitsConverter.GetMetersToUnitsConversionFactor()` / `ConvertToMeters()` / `ConvertFromMeters()`。
+| 场景 | 单位 | 说明 |
+|---|---|---|
+| 模型坐标/包围盒/路径点/几何 | **模型单位** | 取决于当前 NW 文档单位，**绝不等同于米**（如 Floor2 模型是英尺，1米=3.281模型单位） |
+| UI 显示/外部交互/日志长度 | **米** | 通过 `UnitsConverter.ConvertToMeters()` / `ConvertFromMeters()` 在边界转换 |
+| 配置项 | 米 | config.toml 中物体尺寸/安全间隙等均以米存储 |
+
+### 6.2 命名规则
+
+- 米单位变量/字段/参数以 `InMeters` 结尾（如 `objectHeightInMeters`、`safetyMarginInMeters`）
+- 模型单位变量不加后缀
+- 禁止把模型坐标直接当米使用；同一变量内禁止混用两种单位
+
+### 6.3 转换入口
+
+- `UnitsConverter.GetMetersToUnitsConversionFactor(units)` — 当前文档 米→模型单位 因子（英尺=3.281，毫米=1000，米=1）
+- `UnitsConverter.ConvertToMeters(modelUnits)` / `ConvertFromMeters(meters)`
+- 注意：`PathRoute.TotalLength` 等长度属性返回**米**（内部已从模型单位换算），不要再二次换算
+
+### 6.4 测试警示
+
+- 集成测试断言长度/尺寸时，期望值必须按当前文档单位因子换算（服务端应返回因子，如 import-route-file 的 `metersToModelUnits`），**禁止假设模型单位=米**
+- 单元测试进程无 NW 文档，无法做单位换算；涉及单位换算的断言必须放集成测试
+
+典型症状：「预期 12 米实际 3.7 米」（英尺模型）、「虚拟物体尺寸偏大 3.28 倍」。
 
 ---
 
@@ -140,6 +163,7 @@ var rotation = new Rotation3D(qx, qy, qz, qw);
 | 吊装路径不显示 | 渲染链退化段/零长度段 |
 | 路径越走越偏 | 是否把实时 BoundingBox.Center 误当业务跟踪点 |
 | 设为终点后列表空 | UIStateManager 队列消费 |
+| 长度/尺寸偏差约 3.28 倍 | 是否把模型单位(英尺)当米用，未走 UnitsConverter（见 §6 单位原则） |
 
 ---