tian/NavisworksTransport

Fork 0

tian 378bb6264c add edit tool usage notes to AGENTS.md

2026-05-30 19:17:30 +08:00

5.8 KiB

Raw Blame History

AGENTS.md

面向后续 AI 编码助手。让新会话快速理解项目现状、稳定架构、不可破坏的原则、排查入口。

1. 项目现状

NavisworksTransport — Autodesk Navisworks Manage 2026 物流路径规划与动画仿真插件。

核心能力：物流属性分类 · Ground/Hoisting/Rail 三类路径 · 虚拟/真实物体 · 终端安装仿真 · ClashDetective 碰撞检测 · 路径/检测数据存储。

2. 技术栈与构建

.NET Framework 4.8 · C# 7.3 · x64 · WPF + DockPane · MSTest

构建流水线（必须串行，不可并行）

./compile.bat        # 1. 编译
./deploy-plugin.bat  # 2. 等待编译确认成功后部署

严禁：加 cmd.exe /c 前缀、直接调 MSBuild、拆 PowerShell 逻辑、改 powershell 为 pwsh。

并行边界

允许并行（纯读取）	禁止并行（产出/锁文件）
rg, ls, Get-Content, 读日志	compile, deploy, run-unit-tests, 启动 NW

run-unit-tests → compile → deploy 是单通道流水线，不可拆分并行。

路径

插件部署：C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\
日志：...\plugins\TransportPlugin\logs\debug.log

3. 目录与关键文件

目录	职责
`src/Core/`	插件入口、路径管理、动画、碰撞、渲染、配置
`src/UI/WPF/`	视图、ViewModel
`src/Utils/`	单位、几何、坐标、变换、日志
`src/PathPlanning/`	网格、A*、路径几何
`UnitTests/`	回归测试

高风险区域（改动需先补测试）：src/Core/Animation · src/Utils/CoordinateSystem · src/UI/WPF/ViewModels

4. 核心架构规则

4.1 坐标系三层语义

只用三种说法，禁止「本地坐标系」：

宿主坐标系 — NW 文档坐标系（YUp 或 ZUp），UI/日志/拾取均以此为基准
内部坐标系 (Canonical Space) — 固定 ZUp，纯数学计算在此完成
资产坐标系 — 插件资源专属（unit_cube.nwc, unit_cylinder.nwc）

4.2 命名规则

变量/字段/日志中的方向语义必须带坐标系前缀：

前缀：Host / Canonical / Asset / Local（仅对象自身局部轴）
禁止无前缀的 PositiveX / upAxis / forwardAxis 等

4.3 对象局部轴业务映射

不是第四套坐标系，而是业务解释层：把对象哪根局部轴解释为 forward/up/side。

真实物体：不要依赖 ModelItem.Transform（Revit 导入件多为单位旋转），优先通过 fragment 代表姿态 + Fragment默认Up 解释
虚拟物体：对象局部轴业务映射来自资产轴约定

4.4 Quaternion 固定定义（不可再质疑）

// Rotation3D 参数顺序固定为 x, y, z, w
var rotation = new Rotation3D(qx, qy, qz, qw);
// A=x, B=y, C=z, D=w

禁止写成 new Rotation3D(qw, qx, qy, qz)。姿态问题不要再归因到「四元数顺序可能不对」。

4.5 真实物体 vs 虚拟物体

	真实物体	虚拟物体
坐标系	无独立资产坐标系，生活在宿主坐标系	有资产坐标系
角度调整 X/Y/Z	按宿主坐标系	按资产轴约定
资源要求	—	unit_cube.nwc 几何中心在原点
姿态来源	fragment 代表姿态	资产轴约定

4.6 路径姿态链

Ground/Hoisting：走平面姿态链，已禁止退回旧 yaw。起点/逐帧/终点/通行空间共享同一套尺寸语义。业务跟踪点 = 原始包围盒中心。
Rail：并入 canonical → rail pose 链，不能在宿主空间随意补旋转。Rail 0° 基线不可被角度修正污染。

4.7 通行空间

必须和起点落位/逐帧位置/终点诊断共用同一套尺寸语义。典型症状：「通行空间正确但物体陷入地面」「YUp 下 Y/Z 互换」。

5. 开发原则

彻底禁止 fallback（第一原则）— 新链失败时暴露错误，不许静默退回旧链/yaw/hardcoded Z-up/默认值
不向后兼容 — 只针对 NW 2026
临时补丁必须清理 — 定位问题的临时代码，确认不是根因后必须删除
优先复用现有工具 — UnitsConverter, GeometryHelper, LogManager, HostCoordinateAdapter, Canonical*, ModelItemTransformHelper, RailPathPoseHelper
测试优先于猜测 — 几何/旋转/坐标问题按：看日志 → 补日志 → 补单测 → 改代码

6. 单位原则

内部一律用模型单位，UI和外部交互使用米单位。米单位变量以 InMeters 结尾，模型单位不加后缀。

优先用 UnitsConverter.GetMetersToUnitsConversionFactor() / ConvertToMeters() / ConvertFromMeters()。

7. 排查指引

问题	优先检查
虚拟物体固定偏差	部署目录 unit_cube.nwc → BoundingBox.Center 是否为 (0,0,0) → 起点代码
真实物体旋转轴不对	目标姿态算错 or NW 应用姿态错，看 `[动画姿态入口]` / `[模型增量姿态]`
吊装路径不显示	渲染链退化段/零长度段
路径越走越偏	是否把实时 BoundingBox.Center 误当业务跟踪点
设为终点后列表空	UIStateManager 队列消费

8. 推荐阅读

本文件
doc/working/current-engineering-state.md
doc/design/2026/coordinate-system-canonical-space-design.md
doc/design/2026/NavisworksAPI使用方法.md
.agents/skills/geometry-transform/SKILL.md（几何/变换/姿态/坐标）
.agents/skills/nw-api/SKILL.md

9. 工具使用提示

edit 工具的正确格式

{
  "path": "src/.../File.cs",
  "edits": [
    { "oldText": "原文本（必须完全匹配）", "newText": "新文本" }
  ]
}

path 是顶层字段，不在 edits 数组内
oldText 不能有歧义（匹配多个时提供更多上下文）
多个不重叠的编辑可以放在同一个 edits 数组中

5.8 KiB Raw Blame History Unescape Escape