tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8d10f959b2
NavisworksTransport/AGENTS.md

9.5 KiB
Raw Blame History

AGENTS.md

本文件面向后续会话中的 AI 编码助手。目标不是写一份“大而全”的历史说明，而是让新会话能快速理解：

  • 项目现在在做什么
  • 哪些架构已经稳定
  • 哪些开发原则不能再破坏
  • 遇到问题时优先看哪里

如果本文件与更细的专项文档冲突，优先参考：

  1. doc/working/current-engineering-state.md
  2. doc/design/2026/coordinate-system-canonical-space-design.md
  3. doc/design/2026/NavisworksAPI使用方法.md

1. 项目现状

NavisworksTransport 是一个面向 Autodesk Navisworks Manage 2026 的物流路径规划与动画仿真插件。

当前已经不只是“自动寻路”项目，而是一套同时覆盖以下能力的工程：

  • 物流属性与对象分类
  • 地面路径、吊装路径、Rail 路径编辑与可视化
  • 终端安装仿真
  • 动画播放、起点落位、终点诊断
  • ClashDetective 碰撞检测与恢复
  • 路径、检测记录、批处理相关数据存储

当前重点功能

  • Ground / Hoisting / Rail 三类路径
  • 真实物体与虚拟物体的起点摆放、动画姿态、通行空间
  • YUp / ZUp 两类宿主模型坐标系支持
  • 终端安装仿真中的：
    • 端面三点分析
    • 光轴辅助线
    • 安装面双点确定
    • 安装点与 Rail 法向联动

2. 技术栈与构建

  • 平台：Navisworks Manage 2026
  • 框架：.NET Framework 4.8
  • 语言：C# 7.3
  • 架构：x64
  • UI：WPF + Navisworks DockPane
  • 测试：MSTest

关键脚本

  • compile.bat
  • run-unit-tests.bat
  • deploy-plugin.bat

极重要的执行顺序

构建和部署必须严格按顺序执行：

  1. ./run-unit-tests.bat（需要时）
  2. ./compile.bat
  3. 等待编译完整结束并确认成功
  4. ./deploy-plugin.bat

不要并行执行编译和部署。否则很容易把旧 DLL 部署到插件目录。

插件部署目录

  • C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\

日志目录：

  • C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\logs\debug.log

3. 目录与职责

核心目录

  • src/Core/
    • 插件主入口、路径管理、动画、碰撞、渲染、配置
  • src/UI/WPF/
    • 视图、ViewModel、交互命令
  • src/Utils/
    • 单位、几何、坐标、变换、日志等公共工具
  • src/PathPlanning/
    • 网格、A*、路径几何与优化
  • UnitTests/
    • 数学层、工具层、姿态层的回归测试

当前最关键的文件

  • src/Core/Animation/PathAnimationManager.cs
  • src/Core/VirtualObjectManager.cs
  • src/Core/PathPointRenderPlugin.cs
  • src/UI/WPF/ViewModels/AnimationControlViewModel.cs
  • src/UI/WPF/ViewModels/PathEditingViewModel.cs
  • src/Utils/CoordinateSystem/HostCoordinateAdapter.cs
  • src/Utils/CoordinateSystem/CanonicalPlanarPoseBuilder.cs
  • src/Utils/CoordinateSystem/CanonicalRailPoseBuilder.cs
  • src/Utils/CoordinateSystem/CanonicalTrackedPositionResolver.cs
  • src/Utils/CoordinateSystem/RotatedObjectExtentHelper.cs
  • src/Utils/RailPathPoseHelper.cs
  • src/Utils/ModelItemTransformHelper.cs

4. 当前稳定架构

4.1 坐标系三层语义

以后统一只使用这三种说法：

  • 宿主坐标系

    • Navisworks 文档坐标系
    • YUp 或 ZUp
    • UI 输入输出、日志、拾取结果都按这一层解释

  • 内部坐标系

    • 项目内部统一使用的 Canonical Space
    • 固定 ZUp
    • 纯数学姿态和几何计算优先在这里完成

  • 资产坐标系

    • 只属于插件自带资源
    • 当前主要是：
      • 虚拟物体 unit_cube.nwc
      • 参考杆 unit_cylinder.nwc

禁止再使用“本地坐标系”这种含糊说法。

4.2 真实物体 vs 虚拟物体

这是当前架构里最容易被改坏的地方。

真实物体

  • 没有独立资产坐标系
  • 可以视为直接生活在宿主坐标系里
  • 角度调整对话框里的 X/Y/Z，对真实物体应按宿主坐标系消费

虚拟物体

  • 有明确资产坐标系
  • 当前依赖 unit_cube.nwc 资源
  • 资源必须满足：
    • 几何中心在原点
    • 原点处 BoundingBox.Center == (0,0,0)
  • 如果生产环境里虚拟物体固定偏移，先检查部署的 unit_cube.nwc 是否为最新资源，不要先怀疑代码

4.3 路径姿态链

Ground / Hoisting

  • 走平面姿态链
  • 已禁止偷偷退回旧 yaw 方案
  • 起点、逐帧、终点、通行空间，必须共享同一套尺寸语义

Rail

  • 不能像平面路径那样在宿主空间随意补旋转
  • 必须并入 canonical -> rail pose 链
  • Rail 0° 基线必须稳定，不能被角度修正逻辑污染

4.4 通行空间与物体姿态的关系

通行空间、起点落位、逐帧位置、终点诊断，必须尽量共用同一套尺寸/法线语义。

典型错误信号：

  • 通行空间正确，但物体陷入地面
  • 物体姿态正确，但通行空间轴搞反
  • YUp 下 Y/Z 表现互换

遇到这类问题，优先检查：

  • 是否一条链用了“原始高度”
  • 另一条链用了“旋转后法线尺寸”

4.5 终端安装仿真

当前稳定链路是：

  1. 捕获终点箱体
  2. 分析端面（3点）
  3. 选择安装点（当前已是 2 点确定安装面）
  4. 生成辅助线 / 安装面 / 安装点
  5. 取起点并生成路径

当前 UI 上：

  • 终端安装仿真是独立区块
  • 不再夹在路径编辑中间
  • 安装方式选择只保留一处

5. 开发原则

5.1 不向后兼容

项目只针对 Navisworks 2026。不要写旧版本兼容代码。

5.2 不要随意加 fallback

不要为了“先跑起来”就：

  • 偷偷退回旧 yaw
  • 偷偷用硬编码 Z-up
  • 偷偷在错误时给默认值掩盖问题

如果完整姿态链失败，应优先暴露问题并修根因。

5.3 临时补丁不是正式实现

为定位问题临时加入的：

  • 强制刷新
  • 额外同步
  • 再调一次方法
  • UI 和稀泥补丁

如果最后证明它不是真正根因，修完后必须删掉，不能残留在正式代码里。

5.4 优先复用现有工具

尤其优先看：

  • UnitsConverter
  • GeometryHelper
  • LogManager
  • HostCoordinateAdapter
  • Canonical* 姿态工具
  • ModelItemTransformHelper
  • RailPathPoseHelper

不要在业务层手搓一套新的矩阵、坐标变换或尺寸投影公式。

5.5 测试优先于猜测

对几何/旋转/坐标问题，优先顺序应是：

  1. 看日志
  2. 日志不够就补日志
  3. 先补单元测试
  4. 再改代码

不要在没有锁住语义之前反复试错改实现。

6. 单位原则

所有路径计算、网格计算、包络尺寸、位移偏移，内部一律使用模型单位。

命名规则：

  • 米单位：变量名以 InMeters 结尾
  • 模型单位：变量名不加后缀

不要混用。

优先使用：

  • UnitsConverter.GetMetersToUnitsConversionFactor()
  • UnitsConverter.GetUnitsToMetersConversionFactor()
  • UnitsConverter.ConvertToMeters(...)
  • UnitsConverter.ConvertFromMeters(...)

7. 常见问题的排查入口

7.1 虚拟物体固定偏差

先查：

  1. 部署目录下的 resources\\unit_cube.nwc
  2. 原点处 BoundingBox.Center 是否是 (0,0,0)
  3. 再查起点/归位代码

7.2 真实物体旋转轴不对

先区分：

  • 目标姿态算错
  • 还是 Navisworks 应用姿态错

优先看：

  • [动画姿态入口]
  • [模型增量姿态]

7.3 吊装路径不显示

优先检查渲染链里是否有退化段/零长度段导致整条渲染失败。

7.4 “设为终点直接结束”后列表还是空

优先看 UIStateManager 队列消费是否吃掉了后续 UI 事件，不要先怀疑坐标系。

8. 资源与部署注意事项

8.1 虚拟物体资源

当前部署脚本会部署：

  • resources\\unit_cube.nwc
  • resources\\unit_cylinder.nwc

虚拟物体和参考杆问题，必须同时检查：

  • 仓库里的资源
  • bin\\x64\\Release\\resources
  • 插件部署目录下的 resources

8.2 deploy-plugin.bat 当前规则

  • 走白名单部署
  • 不部署测试 DLL
  • 不部署 Navisworks 自带 API DLL

不要把它改回“复制所有 dll”。

9. 推荐阅读顺序

新会话接手本项目时，推荐顺序：

  1. 本文件 AGENTS.md
  2. doc/working/current-engineering-state.md
  3. doc/design/2026/coordinate-system-canonical-space-design.md
  4. doc/design/2026/NavisworksAPI使用方法.md
  5. 相关专项 skill：
    • .agents/skills/nw-api/SKILL.md
    • .agents/skills/geometry-transform/SKILL.md

10. 当前对子代理和 skill 的约定

仓库中已经有几何/变换专项 skill：

  • .agents/skills/geometry-transform/SKILL.md

它负责沉淀以下内容：

  • 坐标系变换
  • 物体姿态
  • 物体位移与归位
  • 虚拟物体资源定位
  • 通行空间几何
  • Navisworks 变换 API 使用规则

后续凡是几何/旋转/位移问题，优先沿这套 skill 与工具链继续维护，不要重新发明一套术语和流程。

11. 最后的硬约束

  1. 不要混淆宿主坐标系、内部坐标系、资产坐标系
  2. 不要在宿主空间随意补旋转，先判断是否应并入现有姿态链
  3. 不要让虚拟物体和真实物体共享含糊的状态分支
  4. 不要让通行空间和真实物体使用两套不同的尺寸语义
  5. 不要把临时补丁留在正式实现里
  6. 不要绕过测试直接改几何核心逻辑

如果你要改动：

  • PathAnimationManager
  • VirtualObjectManager
  • PathPointRenderPlugin
  • AnimationControlViewModel
  • HostCoordinateAdapter
  • Canonical*PoseBuilder
  • ModelItemTransformHelper

请默认这是高风险改动，先补测试，再动实现。