tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ed7bc13866
NavisworksTransport/CLAUDE.md

14 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

NavisworksTransport is a Navisworks 2026 plugin for logistics path planning and transportation conflict detection in 3D building models. The plugin supports route optimization, collision detection, and animated object movement along defined paths.

Current Status: Navisworks 2026 exclusive development - no legacy 2017 compatibility required. Leverages 2026-specific features for enhanced animation and A* pathfinding capabilities.

Build Commands

标准编译方式 (Windows)

  • 推荐编译命令: ./compile.bat - 在项目根目录下运行的标准方式
  • 重要说明: 在Windows系统下必须使用 ./ 前缀来运行批处理文件，不要使用 cmd /c compile.bat 或其他复杂方式

Architecture Overview

Dual Plugin Architecture

The system implements multiple Navisworks plugin types working together:

  • MainPlugin.cs: Primary AddInPlugin with ribbon UI and DockPanePlugin integration
  • PathClickToolPlugin.cs: ToolPlugin for 3D mouse interaction and point placement
  • PathPointRenderPlugin.cs: RenderPlugin for 3D visualization overlay

Core Management Layer

  • PathPlanningManager.cs: Central coordinator for route planning with A* pathfinding support
  • LogisticsAnimationManager.cs: Enhanced animation system targeting Navisworks 2026 native components
  • TimeLinerIntegrationManager.cs: Bridge between custom animations and Navisworks TimeLiner
  • CategoryAttributeManager.cs: COM API wrapper for persistent logistics attribute management
  • VisibilityManager.cs: Model layer control and filtering
  • ModelSplitterManager.cs: Model export and layer separation

Data and Coordinate Systems

  • PathPlanningModels.cs: Core data structures with event-driven state management
  • PathDataManager.cs: JSON serialization with migration support
  • CoordinateConverter.cs: 2D map overlay to 3D world coordinate transformation chains
  • GeometryExtractor.cs: Spatial analysis and bounding box calculations
  • FloorDetector.cs: Automatic floor/level detection for multi-story logistics

UI Architecture: WPF + WinForms Hybrid

  • WPF Components: Modern MVVM-based controls in src\UI\WPF\
    • LogisticsControlPanel: Main docked interface
    • ViewModels with INotifyPropertyChanged pattern
    • Separated Views for different functional areas
  • WinForms Dialogs: Legacy property editing interfaces
  • Integration: ElementHost for WPF in Navisworks environment

Key Technical Details

Navisworks API Integration Pattern

  • Dual API Strategy: Native API (Autodesk.Navisworks.Api) for core functionality + COM API (Autodesk.Navisworks.ComApi) for attribute persistence and TimeLiner operations
  • Plugin Architecture: Three distinct plugin types registered in single assembly
  • Event-Driven Design: Global exception handling with GlobalExceptionHandler class
  • Navisworks 2026 Focus: Utilizes 2026-specific API features without backward compatibility constraints

Pathfinding and Animation System

  • A Algorithm*: RoyT.AStar library integration for optimal path calculation
  • Animation Pipeline: Transform-based movement with collision detection integration
  • TimeLiner Bridge: Synchronization between custom path animations and Navisworks timeline
  • Real-time Collision: ClashDetectiveIntegration for dynamic conflict detection during animation

State Management and Persistence

  • Session State: PathEditState enum (None, AddingPoints, EditingPath) with event callbacks
  • Data Serialization: JSON-based persistence with LogisticsAttributeChangedEventArgs for tracking
  • Coordinate Mapping: Multi-layer coordinate system supporting 2D overlay on 3D models

Logistics Classification System

Eight predefined categories with inheritance from parent to child nodes:

  • 门 (Doors), 电梯 (Elevators), 楼梯 (Stairs), 通道 (Channels)
  • 障碍物 (Obstacles), 装卸区 (Loading Zones), 停车区 (Parking), 检查点 (Checkpoints)

Language and Communication

  • 使用中文进行所有交流和代码注释 - Primary language for user interaction and code documentation
  • 代码注释和文档说明使用中文 - All technical documentation in Chinese

Package Management (Legacy Format)

  • Old-style csproj: Uses <Reference Include> with HintPath instead of PackageReference
  • packages.config: Manual NuGet package management (do NOT use dotnet add package)
  • Manual package installation: Download .nupkg files and extract to packages/ directory
  • Path format: packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll

Plugin Registration Patterns

// Multi-plugin registration in single assembly
[Plugin("NavisworksTransport.MainPlugin", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
public class MainPlugin : AddInPlugin { }

[Plugin("NavisworksTransport.PathClickTool", "YourDeveloperID")]  
[ToolPluginAttribute("NavisworksTransport.PathClickTool", "YourDeveloperID")]
public class PathClickToolPlugin : ToolPlugin { }

Development Principles

  • 防御性编程的正确态度:

    • ✅ 应该做：检测异常情况并报错，让问题暴露出来
    • ❌ 不应该做：用默认值掩盖问题，让bug隐藏在系统中

  • 对于"备份方案"和"容错处理":

    • ✅ 正确做法：发现问题时记录错误日志，中断处理流程
    • ❌ 错误做法：遇到异常数据时自动"修复"或使用替代值继续执行

  • 对于"向后兼容性"：

    • 明确拒绝考虑向后兼容性
    • 专注解决当前问题，不为旧版本或边缘情况妥协

  • 核心原则：

    • "让问题快速暴露" > "让程序看起来正常运行"
    • "报错比静默失败好" > "容忍错误数据继续处理"
    • "数据一致性检查" > "宽松的数据验证"
    • "最小化修改" > "复杂全面的逻辑"

Critical API Usage Patterns

  • Always reference Navisworks API documentation: Check doc\navisworks_api\ before implementing any Navisworks functionality
  • COM API for persistence: Use COM API for attribute operations that need to persist across sessions
  • GlobalExceptionHandler: Initialize in MainPlugin constructor for application-wide error handling
  • Thread safety: UI operations must be marshaled to main thread when called from background processes

Navisworks 2026 Development Focus

  • Exclusive 2026 targeting: No backward compatibility required - leverage 2026-specific features freely
  • Legacy artifacts: src\Legacy\ contains reference code from 2017 version but is not actively maintained
  • Modern animation system: Use Navisworks 2026 native animation components instead of manual Transform manipulation
  • Enhanced APIs: Take advantage of improved 2026 APIs for collision detection, animation, and model management

Serena MCP工具配置

  • Token限制策略: 所有serena MCP工具调用必须使用max_answer_chars: 3000参数
  • 适用工具: 包括但不限于：
    • mcp__serena__search_for_pattern
    • mcp__serena__find_symbol
    • mcp__serena__get_symbols_overview
    • mcp__serena__find_referencing_symbols
    • 所有其他支持max_answer_chars参数的serena工具

查询最佳实践

核心原则: 分步定位 + 分段读取，避免一次性获取大量内容

❌ 错误做法
# 错误1: 对大方法使用 include_body=true
mcp__serena__find_symbol(
    name_path="LargeMethod",
    include_body=true,        # ❌ 500行方法 → 20k+ 字符 → 必然失败
    max_answer_chars=3000
)

# 错误2: 使用OR模式的宽泛搜索
mcp__serena__search_for_pattern(
    substring_pattern="时间标签|TimeTag|预估.*时间|总时间",  # ❌ 多个模式 → 178k+ 字符
    output_mode="files_with_matches"
)

# 错误3: 使用通用词搜索
mcp__serena__search_for_pattern(
    substring_pattern="Manager",  # ❌ 匹配太多文件
    output_mode="content"
)

# 错误4: 使用 depth=1 获取所有成员
mcp__serena__find_symbol(
    name_path="LargeViewModel",
    include_body=false,
    depth=1,                  # ❌ 返回所有方法签名 → 5k+ 字符
    max_answer_chars=3000
)
✅ 正确做法

步骤1: 精确定位文件

# 方式A: 搜索精确的类名或方法名（单一关键词）
mcp__serena__search_for_pattern(
    substring_pattern="TimeTagViewModel",  # ✅ 单一精确词，不用OR模式
    paths_include_glob="**/*ViewModel.cs",  # ✅ 限定文件类型
    output_mode="files_with_matches"
)

# 方式B: 符号查找定位（不使用depth）
mcp__serena__find_symbol(
    name_path="TimeTagViewModel",
    include_body=false,  # ✅ 只获取类本身
    depth=0,             # ✅ 不获取成员，避免内容过多
    max_answer_chars=3000
)

步骤2: 搜索关键方法调用

# 找到关键API调用，而不是搜索通用词
mcp__serena__search_for_pattern(
    substring_pattern="CalculateTimeMarkers",  # ✅ 搜索具体API名称
    relative_path="src/UI/WPF/ViewModels/TimeTagViewModel.cs",  # ✅ 限定文件
    output_mode="content",
    context_lines_before=2,
    context_lines_after=2,
    max_answer_chars=3000
)

步骤3: 定位实现类

# 根据步骤2找到的服务类，定位实现文件
mcp__serena__search_for_pattern(
    substring_pattern="TimeMarkerCalculationService",  # ✅ 精确类名
    paths_include_glob="**/*.cs",
    output_mode="files_with_matches"
)

步骤4: 分段读取实现代码

# 使用Read工具分段获取
Read(
    file_path="src/PathPlanning/TimeMarkerCalculationService.cs",
    offset=97,     # 从方法起始行
    limit=80       # 读取关键逻辑部分
)

# 如需继续，读取下一段
Read(
    file_path="...",
    offset=185,    # 继续往下
    limit=20
)
何时可以使用 include_body=true
  • ✅ 小方法（<100行）
  • ✅ 属性定义
  • ✅ 简单类结构
  • ❌ 大型方法（>200行）
  • ❌ 复杂类定义
  • ❌ 带有 depth=1 的大型类
常见错误模式总结
错误模式 为什么失败 正确做法
substring_pattern="A|B|C" OR模式匹配过多 使用单一精确关键词
substring_pattern="总时间" 通用词匹配太广 搜索具体API名称
depth=1 + 大型类 返回所有成员签名 使用 depth=0 或直接搜索方法
include_body=true + 大方法 方法体太长 先定位再用Read分段
不限定文件范围 搜索整个代码库 使用 paths_include_glob 或 relative_path
执行原则总结
  1. 单一精确关键词 > OR模式或通用词
  2. 限定搜索范围: 始终使用 paths_include_glob 或 relative_path
  3. 分步骤获取信息: 定位 → 搜索调用 → 定位实现 → 分段读取
  4. 避免使用depth: 对于大型类，使用 depth=0 或直接搜索方法名
  5. 先定位后读取: 用 output_mode="files_with_matches" 定位，再用 Read 获取
  6. 善用context参数: 搜索时只需少量上下文（2-3行）
  7. 如遇到3k限制，使用更精确的搜索条件重新查询，而非提高限制

API Documentation Search Strategy

CHM文档搜索最佳实践

问题：CHM解压后产生大量HTML文件（数千个），标准搜索工具效果有限

解决策略：

  1. 使用文档结构入口点：

    # 优先访问类成员列表
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm

  2. 精确文件名搜索：

    find . -name "*ClassName*" -o -name "*MethodName*"

  3. 分层搜索方法：

    • 先定位到类级别文档
    • 从类成员列表找到方法链接
    • 利用文档间超链接导航

  4. 搜索模式示例：

    # 搜索特定API
grep -r "SaveFile\|Export.*nwd" --include="*.htm" doc/navisworks_api/

# 查找特定类的所有成员
find . -name "AllMembers_T_Autodesk_Navisworks_Api_Document.htm"

  5. 常用API文档路径：

    • Document类：AllMembers_T_Autodesk_Navisworks_Api_Document.htm
    • TimeLiner：AllMembers_T_Autodesk_Navisworks_Api_Timeliner_*.htm
    • 插件基类：AllMembers_T_Autodesk_Navisworks_Api_Plugins_*.htm

避免的搜索方式：

  • 避免在HTML内容中进行模糊搜索（标签干扰）
  • 不要依赖GUID格式的文件名
  • 避免使用过于宽泛的搜索词

Testing and Deployment

  • Testing environment: Navisworks Manage 2026 exclusively - 2017 support discontinued
  • Plugin deployment: Build output automatically copies to Navisworks 2026 plugin directory
  • Hot reload: Restart Navisworks required after compilation to load new plugin version
  • Debugging: Use LogManager for centralized logging and the built-in log viewer dialog for log analysis
  • 2026 Features: Test advanced animation capabilities, enhanced collision detection, and improved model handling
  • 在编码中，不要用回退或向后兼容的思路和步骤
  • 程序的日志在：C:\ProgramData\Autodesk\Navisworks Manage 2026\NavisworksTransport\logs\debug.log
  • 使用agent完成任务前，一定要先用Plan模式设计好方案和任务清单，并征得我同意。
  • 网格坐标代表的是网格单元的左下角，而不是中心点！

运行路径测试

需要先编译单元测试DLL，然后再编译TestRunner：

● Bash(powershell -Command "& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' NavisworksTransport.UnitTests.csproj /p:Configu…) ⎿ 适用于 .NET Framework MSBuild 版本 17.14.10+8b8e13593

   NavisworksTransport.UnitTests -> C:\Users\Tellme\apps\NavisworksTransport\bin\Debug\NavisworksTransport.UnitTests.dll

● Bash(powershell -Command "& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' AStarTestRunner.csproj /p:Configuration=Debug /…) ⎿ 适用于 .NET Framework MSBuild 版本 17.14.10+8b8e13593

   AStarTestRunner -> C:\Users\Tellme\apps\NavisworksTransport\bin\Debug\AStarTestRunner.exe

● 现在运行新的测试程序：

● Bash("bin\Debug\AStarTestRunner.exe")