tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
pathcurve
NavisworksTransport/AGENTS.md
tian 07f8f5b2bf 修复网格可视化性能问题 
根本原因：新代码在循环中调用了 AddPoint() 方法，该方法每次都会触发 UpdateTotalLength()，导致：
算法复杂度：从 O(n) 变成 O(n² log n)
排序次数：12,480 个点 = 78,000,000 次排序
性能损失：从 76 毫秒 → 12.5 秒（130倍慢）
修复方案：直接使用 Points.Add() 绕过昂贵的 UpdateTotalLength() 调用
2026-01-16 20:35:33 +08:00

5.6 KiB
Raw Permalink Blame History

AGENTS.md

本文件包含在 NavisworksTransport 仓库中工作的代理编码助手所需的构建/测试命令和代码风格指南。

构建命令

主要构建

./compile.bat
  • 使用 Visual Studio 2022 的 MSBuild
  • 构建 Release 配置的 x64 平台
  • 目标框架：.NET Framework 4.8

测试命令

./run-unit-tests.bat
  • 首先构建主项目
  • 构建测试项目（Release/x64）
  • 使用 VSTest 控制台运行单元测试
  • 测试框架：MSTest 3.0.4

手动测试执行

# 仅构建测试项目
MSBuild.exe NavisworksTransport.UnitTests.csproj /p:Configuration=Release /p:Platform=x64

# 运行特定测试（使用 Release 路径匹配构建输出）
VSTest.Console.exe "bin\x64\Release\NavisworksTransport.UnitTests.dll" /Framework:".NETFramework,Version=v4.8" /TestAdapterPath:"packages\MSTest.TestAdapter.3.0.4\build\net462"

项目结构

目标环境

  • 平台: Navisworks 2026 (Windows 10+)
  • 框架: .NET Framework 4.8
  • 语言: C# 7.3
  • 架构: x64

关键目录

  • src/Core/ - 主插件文件和业务逻辑
  • src/Commands/ - 命令模式实现
  • src/PathPlanning/ - A* 算法和网格地图生成
  • src/UI/WPF/ - WPF MVVM UI 组件
  • src/Utils/ - 工具类和助手
  • UnitTests/ - 测试文件

插件架构

  • MainPlugin.cs: AddInPlugin - Ribbon UI + 停靠面板
  • PathClickToolPlugin.cs: ToolPlugin - 3D 鼠标交互
  • PathPointRenderPlugin.cs: RenderPlugin - 3D 可视化

API 使用

  • Native API (Autodesk.Navisworks.Api): 核心功能
  • COM API (Autodesk.Navisworks.ComApi): 属性持久化, TimeLiner
  • 在 MainPlugin 构造函数中初始化 GlobalExceptionHandler

代码风格指南

导入和命名空间

// System 命名空间优先
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

// 第三方库
using RoyT.AStar;

// Navisworks API 命名空间
using Autodesk.Navisworks.ComApi;
using Autodesk.Navisworks.Api;
using Autodesk.Navisworks.Api.Plugins;

// 项目命名空间（按字母顺序）
using NavisworksTransport.Core;
using NavisworksTransport.Utils;
using NavisworksTransport.UI.WPF.ViewModels;

命名约定

  • 类: PascalCase (例如: PathPlanningManager)
  • 方法: PascalCase (例如: GenerateGridMap)
  • 属性: PascalCase (例如: CellSize)
  • 字段: camelCase 带下划线前缀 (例如: _uiStateManager)
  • 常量: PascalCase (例如: MaxHeightDiff)
  • 接口: PascalCase 带 'I' 前缀 (例如: IPathPlanningCommand)
  • 枚举: PascalCase (例如: LogLevel)

单位系统 - 极其重要

所有网格地图和路径规划计算必须使用模型单位，不要用米制单位。

// ✅ 正确：在函数入口转换
public GridMap GenerateFromBIM(BoundingBox3D bounds, double cellSizeMeters, ...)
{
    double factor = UnitsConverter.GetMetersToUnitsConversionFactor(Application.ActiveDocument.Units);
    double cellSizeInModelUnits = cellSizeMeters * factor;
    // 使用模型单位进行所有计算
}

// ❌ 错误：在计算中混用单位
private const double MAX_HEIGHT_DIFF = 0.35; // 米！
if (heightDiff > MAX_HEIGHT_DIFF) // Bug!

错误处理

  • 防御性编程: 检测并报告错误，不要隐藏它们
  • 日志记录: 使用 LogManager 进行所有错误报告
  • 异常: 不要仅仅为了吞噬异常而捕获它们
// ✅ 正确：记录并重新抛出或适当处理
try
{
    var result = SomeOperation();
    return result;
}
catch (Exception ex)
{
    LogManager.Error($"Operation failed: {ex.Message}");
    throw; // 重新抛出或适当处理
}

// ❌ 错误：吞噬异常
try
{
    var result = SomeOperation();
    return result;
}
catch
{
    return null; // 隐藏问题
}

线程安全和UI更新

  • 使用 UIStateManager 进行线程安全的UI更新
  • UI操作必须编组到主线程
  • 使用异步事件触发避免死锁
// ✅ 正确：异步事件触发
private void OnStatusChanged(string status)
{
    Task.Run(() =>
    {
        try
        {
            StatusChanged?.Invoke(this, status);
        }
        catch (Exception ex)
        {
            LogManager.Error($"StatusChanged事件失败: {ex.Message}");
        }
    });
}

包管理

  • 使用旧式 csproj 与 <Reference Include> 和 HintPath
  • packages.config 用于手动包管理
  • 不要 使用 dotnet add package
  • 包路径: packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll

文档和注释

  • 对公共 API 使用 XML 文档
  • 业务逻辑可以使用中文注释
  • 注释重点说明"为什么"而不是"什么"

性能考虑

  • 缓存频繁访问的几何数据
  • 使用空间索引进行碰撞检测
  • 使用 SmartDataBindingOptimizer 优化 UI 更新
  • 最小化跨线程操作

常见错误避免

  1. 单位混淆: 绝不要在计算中混用米制和模型单位
  2. 线程违规: 始终将UI操作编组到主线程
  3. 异常吞噬: 正确记录和处理错误
  4. 内存泄漏: 释放资源并取消事件订阅
  5. API兼容性: 专门针对 Navisworks 2026，不考虑向后兼容

验证

运行命令前，代理应该验证：

  • 构建输出存在: dir bin\x64\Release\NavisworksTransportPlugin.dll
  • 测试程序集存在: dir bin\x64\Release\NavisworksTransport.UnitTests.dll
  • 依赖项在预期的包路径中
  • MSBuild 和 VSTest 在预期位置可用

调试

  • 调试日志位置: "C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\logs\debug.log"
  • 使用 LogManager 进行结构化日志记录
  • 在 Navisworks 2026 环境中测试以进行完整集成测试