新增 Navisworks API 开发Skill

2026-02-04 21:50:23 +08:00 · 2026-02-04 21:50:23 +08:00 · a0651d60cd
commit a0651d60cd
parent 0d9eeed89b
4 changed files with 1024 additions and 0 deletions
--- a/.agents/skills/nw-api/SKILL.md
+++ b/.agents/skills/nw-api/SKILL.md
@ -0,0 +1,137 @@
+---
+name: nw-api
+description: Navisworks API 开发助手，用于开发 Navisworks 插件。功能包括：(1) 查看 NET API 文档位置和使用方法，(2) 查看官方 NET API 示例代码，(3) 搜索 Navisworks NET API 使用方法和示例。当用户询问 Navisworks API、插件开发、NET API、C# 开发相关内容时使用此技能。
+---
+
+# Navisworks NET API 开发助手
+
+帮助开发 Autodesk Navisworks 插件的专用技能。主要基于 .NET API，COM API 作为补充参考。
+
+## 本地文档位置
+
+### API 文档（主要）
+
+| 类型 | 路径 | 格式 |
+|------|------|------|
+| NET API | `doc/navisworks_api/NET/documentation/NET API.chm` | CHM 帮助文件 |
+| NET API HTML | `doc/navisworks_api/NET/documentation/NetAPIHtml/` | HTML 文档 |
+
+**HTML 文档入口**: `doc/navisworks_api/NET/documentation/NetAPIHtml/html/index.html`
+
+### API 文档搜索方法
+
+HTML 文档已生成为可搜索的网页形式，可以直接用 Grep 工具搜索：
+
+```bash
+# 搜索 ModelItem 的属性
+Grep -i "ModelItem.*property" doc/navisworks_api/NET/documentation/NetAPIHtml/html/
+
+# 搜索特定方法
+Grep -i "BoundingBox" doc/navisworks_api/NET/documentation/NetAPIHtml/html/
+
+# 搜索类定义
+Grep "class.*ModelItem" doc/navisworks_api/NET/documentation/NetAPIHtml/html/
+```
+
+**文件命名规律**:
+
+- 类型页面: `T_Autodesk_Navisworks_Api_{ClassName}.htm`
+- 属性页面: `P_Autodesk_Navisworks_Api_{ClassName}_{PropertyName}.htm`
+- 方法页面: `M_Autodesk_Navisworks_Api_{ClassName}_{MethodName}.htm`
+- 所有成员: `AllMembers_T_Autodesk_Navisworks_Api_{ClassName}.htm`
+- 属性列表: `Properties_T_Autodesk_Navisworks_Api_{ClassName}.htm`
+- 方法列表: `Methods_T_Autodesk_Navisworks_Api_{ClassName}.htm`
+
+### 官方示例代码（NET API）
+
+| 示例类型 | 路径 |
+|----------|------|
+| 基础插件 | `doc/navisworks_api/NET/examples/Basic Examples/CSharp/` |
+| 插件集合 | `doc/navisworks_api/NET/examples/PlugIns/` |
+| 自动化 | `doc/navisworks_api/NET/examples/Automation/` |
+| 控件集成 | `doc/navisworks_api/NET/examples/Controls/` |
+| 工具插件 | `doc/navisworks_api/NET/examples/Tools/` |
+
+### 项目设计文档
+
+- `doc/design/2026/NavisworksAPI使用方法.md` - API 使用指南
+- `doc/migration/API_Migration_Analysis_2017_to_2026.md` - 版本迁移指南
+- `doc/migration/Navisworks_2026_API_Changes.md` - 2026 API 变更
+
+## COM API 参考（补充）
+
+| 类型 | 路径 |
+|------|------|
+| COM API 文档 | `doc/navisworks_api/COM/documentation/NavisWorksCOM.chm` |
+| COM 示例 | `doc/navisworks_api/COM/examples/` |
+
+## 在线资源
+
+- **Autodesk Platform Services**: <https://aps.autodesk.com/developer/overview/navisworks>
+- **AEC DevBlog**: <https://adndevblog.typepad.com/aec/navisworks/>
+- **ApiDocs (2017-2018)**: <https://apidocs.co/apps/navisworks/>
+
+## 快速参考
+
+### 命名空间
+
+```csharp
+// 核心 API
+using Autodesk.Navisworks.Api;
+using Autodesk.Navisworks.Api.Plugins;
+using Autodesk.Navisworks.Api.Clash;
+using Autodesk.Navisworks.Api.Timeliner;
+
+// COM API（需要时）
+using Autodesk.Navisworks.ComApi;
+using Autodesk.Navisworks.Interop.ComApi;
+```
+
+### 插件类型
+
+| 基类 | 用途 | 示例位置 |
+|------|------|----------|
+| `DockPanePlugin` | 停靠面板插件 | `Basic Examples/CSharp/BasicDockPanePlugin/` |
+| `ToolPlugin` | 鼠标交互工具 | `PlugIns/InputAndRenderHandling/` |
+| `RenderPlugin` | 3D 渲染插件 | `PlugIns/InputAndRenderHandling/` |
+| `AddInPlugin` | 简单命令插件 | `PlugIns/Examiner/` |
+| `EventWatcherPlugin` | 监听文档事件 | `PlugIns/ClashDetective/EventLog/` |
+
+### 关键 API 入口
+
+```csharp
+// 当前文档
+Document doc = Application.ActiveDocument;
+
+// 当前选择
+ModelItemCollection selection = doc.CurrentSelection.SelectedItems;
+
+// 模型遍历
+foreach (ModelItem item in doc.Models.RootItemDescendantsAndSelf) { }
+
+// 搜索
+Search search = new Search();
+search.SearchConditions.Add(SearchCondition.HasCategoryByName(PropertyCategoryNames.Geometry));
+ModelItemCollection results = search.FindAll(doc, false);
+```
+
+## 参考资料
+
+- **常用 API 模式**: 见 `references/api-usage-patterns.md`
+- **插件类型详解**: 见 `references/plugin-types.md`
+- **NET 示例速查**: 见 `references/net-examples-guide.md`
+
+## Web 搜索
+
+如需查找最新的 API 用法或示例，使用 `SearchWeb` 工具搜索：
+
+```
+SearchWeb: "Navisworks .NET API {query} example C#"
+```
+
+常用搜索模板：
+
+- `Navisworks .NET API ModelItem transform example`
+- `Navisworks .NET API plugin DockPane C#`
+- `Navisworks .NET API search condition example`
+- `Navisworks 2026 .NET API changes`
--- a/.agents/skills/nw-api/references/api-usage-patterns.md
+++ b/.agents/skills/nw-api/references/api-usage-patterns.md
@ -0,0 +1,292 @@
+# Navisworks API 常用模式
+
+## 1. 模型遍历
+
+### 遍历所有模型项
+
+```csharp
+// 获取所有模型项
+IEnumerable<ModelItem> allItems = 
+    Application.ActiveDocument.Models.RootItemDescendantsAndSelf;
+
+// 遍历特定模型
+foreach (Model model in document.Models)
+{
+    foreach (ModelItem item in model.RootItem.DescendantsAndSelf)
+    {
+        // 处理每个模型项
+    }
+}
+```
+
+### 获取子节点
+
+```csharp
+// 获取所有后代（不包括自己）
+var childItems = selectedItem.DescendantsAndSelf.Where(x => x != selectedItem);
+
+// 只获取直接子节点
+foreach (ModelItem child in parentItem.Children) { }
+
+// 向上遍历祖先
+var current = selectedItem.Parent;
+while (current != null)
+{
+    current = current.Parent;
+}
+```
+
+## 2. 搜索和查询
+
+### 使用 Search 类
+
+```csharp
+Search search = new Search();
+
+// 添加搜索条件
+search.SearchConditions.Add(
+    SearchCondition.HasCategoryByName(PropertyCategoryNames.Geometry));
+search.SearchConditions.Add(
+    SearchCondition.HasPropertyByName(PropertyCategoryNames.Item, DataPropertyNames.ItemHidden)
+    .EqualValue(VariantData.FromBoolean(false)));
+
+// 设置搜索范围
+search.Selection.SelectAll();
+search.Locations = SearchLocations.DescendantsAndSelf;
+
+// 执行搜索
+ModelItemCollection results = search.FindAll(document, false);
+```
+
+### 使用 LINQ 查询
+
+```csharp
+var results = document.Models.RootItemDescendantsAndSelf
+    .Where(x => x.HasGeometry && !x.IsHidden)
+    .Where(x => x.ClassDisplayName.ToLower().Contains("wall"));
+```
+
+## 3. 选择操作
+
+```csharp
+// 获取当前选择
+var currentSelection = document.CurrentSelection.SelectedItems;
+
+// 清空选择
+document.CurrentSelection.Clear();
+
+// 添加到选择
+document.CurrentSelection.Add(modelItem);
+
+// 复制集合到选择
+document.CurrentSelection.CopyFrom(modelItems);
+```
+
+## 4. 可见性控制
+
+```csharp
+// 隐藏项目
+ModelItemCollection itemsToHide = new ModelItemCollection();
+itemsToHide.Add(modelItem);
+document.Models.SetHidden(itemsToHide, true);
+
+// 显示项目
+document.Models.SetHidden(itemsToHide, false);
+
+// 检查是否隐藏
+if (modelItem.IsHidden) { }
+```
+
+## 5. 文件导出
+
+```csharp
+// 保存 NWD 文件
+document.SaveFile(filePath);
+
+// 使用导出选项
+var exportOptions = new NwdExportOptions();
+exportOptions.ExcludeHiddenItems = true;
+exportOptions.EmbedXrefs = false;
+exportOptions.PreventObjectPropertyExport = false;
+
+document.ExportToNwd(saveFilePath, exportOptions);
+```
+
+## 6. Transform 变换操作
+
+### 核心概念
+
+- `ModelItem.Transform` - 返回设计文件中的原始变换（只读）
+- `OverridePermanentTransform()` - 应用增量变换（累积）
+- `ResetPermanentTransform()` - 清除所有增量变换
+- `ModelItem.BoundingBox()` - 返回当前实际显示的包围盒
+
+### 应用变换
+
+```csharp
+// 获取原始 Transform
+Transform3D originalTransform = modelItem.Transform;
+
+// 应用增量变换
+var doc = Application.ActiveDocument;
+var modelItems = new ModelItemCollection { modelItem };
+doc.Models.OverridePermanentTransform(modelItems, newTransform, false);
+
+// 重置到原始位置
+doc.Models.ResetPermanentTransform(modelItems);
+```
+
+### 绕物体中心旋转（需要补偿）
+
+```csharp
+// 关键：API 的旋转总是绕世界原点(0,0,0)
+// 要实现绕物体中心旋转，需要计算补偿
+
+double deltaYaw = newYaw - currentYaw;
+double cos = Math.Cos(deltaYaw);
+double sin = Math.Sin(deltaYaw);
+
+// 计算绕原点旋转后的位置
+double rotatedX = currentPosition.X * cos - currentPosition.Y * sin;
+double rotatedY = currentPosition.X * sin + currentPosition.Y * cos;
+
+// 计算补偿平移
+var compensatedTranslation = new Vector3D(
+    newPosition.X - rotatedX,
+    newPosition.Y - rotatedY,
+    newPosition.Z - currentPosition.Z
+);
+
+// 组合变换
+var identity = Transform3D.CreateTranslation(new Vector3D(0, 0, 0));
+var components = identity.Factor();
+components.Rotation = new Rotation3D(new UnitVector3D(0, 0, 1), deltaYaw);
+components.Translation = compensatedTranslation;
+
+var incrementalTransform = components.Combine();
+doc.Models.OverridePermanentTransform(modelItems, incrementalTransform, false);
+```
+
+## 7. 属性访问
+
+### NET API 方式
+
+```csharp
+// 查找属性分类
+var category = item.PropertyCategories.FindCategoryByDisplayName("Material");
+
+// 基础属性
+string displayName = item.DisplayName;
+string className = item.ClassName;
+bool hasGeometry = item.HasGeometry;
+bool isHidden = item.IsHidden;
+```
+
+### COM API 方式（当 NET API 不满足需求时使用）
+
+**参考**: `doc/navisworks_api/NET/examples/Basic Examples/CSharp/APICallsCOMPlugin/`
+
+```csharp
+using Autodesk.Navisworks.ComApi;
+using Autodesk.Navisworks.Interop.ComApi;
+
+// 获取 COM 状态
+ComApi.InwOpState10 state = ComApiBridge.State;
+
+// 获取属性节点
+InwOpSelection2 selection = state.CurrentSelection as InwOpSelection2;
+InwGUIPropertyNode2 propertyNode = 
+    state.GetGUIPropertyNode(selection.Paths()[1], true) as InwGUIPropertyNode2;
+
+// 遍历属性分类
+foreach (InwGUIAttribute2 guiAttribute in propertyNode.GUIAttributes())
+{
+    foreach (InwOaProperty property in guiAttribute.Properties())
+    {
+        string name = property.name;
+        string value = property.value;
+    }
+}
+```
+
+### 添加自定义属性（COM API）
+
+```csharp
+InwOaPropertyVec propertyVector = 
+    state.ObjectFactory(nwEObjectType.eObjectType_nwOaPropertyVec);
+
+InwOaProperty property = 
+    state.ObjectFactory(nwEObjectType.eObjectType_nwOaProperty);
+property.name = "CustomProperty1";
+property.UserName = "自定义属性1";
+property.value = value;
+
+propertyVector.Properties().Add(property);
+propertyNode.SetUserDefined(0, categoryName, internalName, propertyVector);
+```
+
+## 8. 线程安全 - 关键
+
+**所有 Navisworks API 调用必须在主 UI 线程中执行**
+
+```csharp
+// ❌ 错误：在后台线程调用
+await Task.Run(() =>
+{
+    var document = Application.ActiveDocument;  // 可能崩溃
+});
+
+// ✅ 正确：使用 Dispatcher.Invoke
+await Task.Run(() =>
+{
+    System.Windows.Application.Current.Dispatcher.Invoke(() =>
+    {
+        var document = Application.ActiveDocument;
+        document.ExportToNwd(path, options);  // 安全执行
+    });
+});
+```
+
+### 检查线程状态
+
+```csharp
+var apartmentState = System.Threading.Thread.CurrentThread.GetApartmentState();
+bool isMainThread = System.Windows.Application.Current.Dispatcher.CheckAccess();
+```
+
+## 9. 碰撞检测 (ClashDetective)
+
+```csharp
+// 获取碰撞测试
+document.ClashTestsData.Tests;
+
+// 创建碰撞选择
+var selectionA = new ClashSelection(modelItemsA, document);
+var selectionB = new ClashSelection(modelItemsB, document);
+
+// 创建碰撞测试
+var clashTest = new ClashTest();
+clashTest.Name = "Test Name";
+clashTest.TestType = ClashTestType.Hard;
+clashTest.SelectionA = selectionA;
+clashTest.SelectionB = selectionB;
+```
+
+## 10. TimeLiner 集成
+
+```csharp
+// 获取 TimeLiner 数据
+var timeliner = document.Timeliner;
+
+// 添加任务
+var task = new TimelinerTask();
+task.Name = "Task Name";
+task.SimulationStatus = SimulationStatus.Active;
+task.StartDate = DateTime.Now;
+task.EndDate = DateTime.Now.AddDays(7);
+
+timeliner.Tasks.Add(task);
+
+// 关联模型项
+task.Selection.CopyFrom(modelItems);
+```
--- a/.agents/skills/nw-api/references/net-examples-guide.md
+++ b/.agents/skills/nw-api/references/net-examples-guide.md
@ -0,0 +1,309 @@
+# Navisworks NET API 示例指南
+
+## 示例代码位置总览
+
+所有示例位于：`doc/navisworks_api/NET/examples/`
+
+## 基础示例 (Basic Examples)
+
+### 1. BasicDockPanePlugin
+
+**路径**: `Basic Examples/CSharp/BasicDockPanePlugin/`
+
+最简单的停靠面板插件示例。
+
+```csharp
+[Plugin("BasicDockPanePlugin.BasicDockPanePlugin", "ADSK",
+   DisplayName = "BasicDockPanePlugin",
+   ToolTip = "Basic Docking Pane Plugin")]
+[DockPanePlugin(100, 300)]
+public class BasicDockPanePlugin : DockPanePlugin
+{
+   public override Control CreateControlPane()
+   {
+      HelloWorldControl control = new HelloWorldControl();
+      control.Dock = DockStyle.Fill;
+      control.CreateControl();
+      return control;
+   }
+
+   public override void DestroyControlPane(Control pane)
+   {
+      pane.Dispose();
+   }
+}
+```
+
+### 2. WPF DockPane
+
+**路径**: `Basic Examples/CSharp/WPF/WpfDockPane/`
+
+使用 WPF 控件的停靠面板插件。
+
+```csharp
+public override Control CreateControlPane()
+{
+    // 使用 ElementHost 托管 WPF 控件
+    ElementHost host = new ElementHost();
+    host.Child = new WPFHelloWorldControl();
+    host.Dock = DockStyle.Fill;
+    host.CreateControl();
+    return host;
+}
+```
+
+### 3. DatabaseDockPane
+
+**路径**: `Basic Examples/CSharp/WPF/DatabaseDockPane/`
+
+展示如何在停靠面板中使用模型数据库。
+
+### 4. BasicPlugIn
+
+**路径**: `Basic Examples/CSharp/BasicPlugIn/`
+
+最简单的 AddIn 插件示例。
+
+### 5. APICallsCOMPlugin
+
+**路径**: `Basic Examples/CSharp/APICallsCOMPlugin/`
+
+展示如何在 NET API 插件中调用 COM API。
+
+### 6. CustomRibbon
+
+**路径**: `Basic Examples/CSharp/CustomRibbon/`
+
+自定义 Ribbon 界面示例，使用 XAML 定义 Ribbon。
+
+## 插件示例 (PlugIns)
+
+### 1. Examiner
+
+**路径**: `PlugIns/Examiner/`
+
+全面的 LINQ 搜索和模型操作示例。
+
+**关键功能**:
+
+- 使用 LINQ 查询模型项
+- 属性搜索和过滤
+- 颜色和透明度覆盖
+- Required/Hidden 状态修改
+- 导出结果到 NWD
+
+**核心代码片段**:
+
+```csharp
+// LINQ 搜索示例
+IEnumerable<ModelItem> result = 
+    Application.ActiveDocument.Models.RootItemDescendantsAndSelf
+    .Where(x => x.HasGeometry)
+    .Where(x => !x.IsHidden)
+    .Where(x => x.DisplayName.Contains(searchName));
+
+// 颜色覆盖
+ModelItemCollection items = new ModelItemCollection();
+items.AddRange(result);
+Application.ActiveDocument.Models.OverridePermanentColor(items, color);
+```
+
+### 2. SearchComparisonPlugIn
+
+**路径**: `PlugIns/SearchComparisonPlugIn/`
+
+对比不同搜索方法的性能。
+
+### 3. InputAndRenderHandling
+
+**路径**: `PlugIns/InputAndRenderHandling/`
+
+ToolPlugin 和 RenderPlugin 的综合示例。
+
+**关键功能**:
+
+- 鼠标输入处理
+- 自定义渲染
+- 3D 拾取
+
+```csharp
+[ToolPlugin("InputAndRenderHandling", "ADSK")]
+[RenderPlugin("InputAndRenderHandling", "ADSK")]
+public class InputAndRenderHandling : ToolPlugin
+{
+    public override bool MouseDown(MouseButton button, int x, int y)
+    {
+        // 处理鼠标点击
+        return true;
+    }
+    
+    public override void Render(View view, RenderContext context)
+    {
+        // 自定义渲染
+    }
+}
+```
+
+### 4. ClashDetective 示例集合
+
+**路径**: `PlugIns/ClashDetective/`
+
+包含多个碰撞检测相关示例：
+
+| 示例 | 说明 |
+|------|------|
+| `ClashGrouper/` | 碰撞结果分组 |
+| `ClashMarkers/` | 碰撞标记显示 |
+| `EventLog/` | 事件日志监听 |
+| `GenerateMatrix/` | 生成碰撞矩阵 |
+| `SimpleUI/` | 简单 UI 界面 |
+
+**碰撞测试基础代码**:
+
+```csharp
+// 创建碰撞测试
+ClashTest clashTest = new ClashTest();
+clashTest.Name = "Test Name";
+clashTest.TestType = ClashTestType.Hard;
+
+// 设置选择
+clashTest.SelectionA = new ClashSelection(itemsA, document);
+clashTest.SelectionB = new ClashSelection(itemsB, document);
+
+// 添加到文档
+document.ClashTestsData.Tests.Add(clashTest);
+```
+
+### 5. Timeliner 示例
+
+**路径**: `PlugIns/Timeliner/`
+
+TimeLiner 集成示例，展示 4D 模拟功能。
+
+```csharp
+// 获取 Timeliner 数据
+var timeliner = document.Timeliner;
+
+// 创建任务
+TimelinerTask task = new TimelinerTask();
+task.Name = "Construction Task";
+task.StartDate = DateTime.Now;
+task.EndDate = DateTime.Now.AddDays(7);
+task.SimulationStatus = SimulationStatus.Active;
+
+// 关联模型
+task.Selection.CopyFrom(modelItems);
+
+// 添加任务
+timeliner.Tasks.Add(task);
+```
+
+### 6. Takeoff 示例
+
+**路径**: `PlugIns/Takeoff/`
+
+工程量计算 (Quantification) 示例。
+
+## 自动化示例 (Automation)
+
+### 1. CallExaminer
+
+**路径**: `Automation/CallExaminer/`
+
+展示如何通过自动化接口调用 Examiner 插件。
+
+```csharp
+// 启动 Navisworks 自动化
+NavisworksApplication app = new NavisworksApplication();
+app.OpenFile(filePath);
+
+// 执行插件
+app.ExecutePlugin("Examiner.Examiner", parameters);
+```
+
+### 2. MessageClientServer
+
+**路径**: `Automation/MessageClientServer/`
+
+展示插件间通信机制。
+
+### 3. MessageSenderReceiver
+
+**路径**: `Automation/MessageSenderReceiver/`
+
+消息发送和接收示例。
+
+## 控件示例 (Controls)
+
+### 1. Viewers
+
+**路径**: `Controls/Viewers/`
+
+独立的 Navisworks 查看器控件示例。
+
+| 示例 | 说明 |
+|------|------|
+| `SDIViewer/` | 单文档界面查看器 |
+| `MDIViewer/` | 多文档界面查看器 |
+
+```csharp
+// 使用 DocumentControl
+DocumentControl docControl = new DocumentControl();
+docControl.Dock = DockStyle.Fill;
+this.Controls.Add(docControl);
+
+// 打开文件
+docControl.Document.OpenFile(filePath);
+```
+
+### 2. PublishFile
+
+**路径**: `Controls/PublishFile/`
+
+文件发布选项示例。
+
+## 工具示例 (Tools)
+
+### 1. AppInfo
+
+**路径**: `Tools/AppInfo/`
+
+展示应用程序信息和事件监听。
+
+### 2. CodeRun
+
+**路径**: `Tools/CodeRun/`
+
+动态代码执行工具，支持 C# 和 IronPython。
+
+## 按功能查找示例
+
+| 功能需求 | 推荐示例 |
+|----------|----------|
+| 创建停靠面板 | `BasicDockPanePlugin/`, `WpfDockPane/` |
+| 使用 WPF | `WpfDockPane/`, `DatabaseDockPane/` |
+| 模型搜索 | `Examiner/`, `SearchComparisonPlugIn/` |
+| 鼠标交互 | `InputAndRenderHandling/` |
+| 自定义渲染 | `InputAndRenderHandling/` |
+| 碰撞检测 | `ClashDetective/` 下的各个示例 |
+| TimeLiner | `Timeliner/` |
+| 独立查看器 | `Controls/Viewers/` |
+| 插件通信 | `MessageClientServer/` |
+
+## 项目文件参考
+
+每个示例包含的项目文件：
+
+- `.csproj` - C# 项目文件
+- `Properties/AssemblyInfo.cs` - 程序集信息
+- 源代码文件 (.cs)
+
+## 构建和部署
+
+1. 打开 `doc/navisworks_api/NET/examples/Examples.sln`
+2. 选择项目并构建
+3. 插件输出到 Navisworks 插件目录：
+
+   ```
+   C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\
+   ```
--- a/.agents/skills/nw-api/references/plugin-types.md
+++ b/.agents/skills/nw-api/references/plugin-types.md
@ -0,0 +1,286 @@
+# Navisworks 插件类型详解
+
+## 插件基类对比
+
+| 基类 | 继承关系 | 主要用途 | 触发方式 |
+|------|---------|---------|---------|
+| `DockPanePlugin` | ← `Plugin` | 停靠面板 UI | 用户点击 Ribbon 按钮 |
+| `ToolPlugin` | ← `Plugin` | 鼠标 3D 交互工具 | 用户点击后进入工具模式 |
+| `RenderPlugin` | ← `Plugin` | 自定义 3D 渲染 | 自动在渲染时调用 |
+| `AddInPlugin` | ← `Plugin` | 简单命令 | 用户点击 Ribbon 按钮 |
+| `EventWatcherPlugin` | ← `Plugin` | 监听文档事件 | 自动注册，事件触发 |
+| `CommandHandlerPlugin` | - | 自定义命令处理器 | 命令调用时触发 |
+
+## 1. DockPanePlugin
+
+用于创建停靠在 Navisworks 窗口中的面板。
+
+```csharp
+[DockPanePlugin(400, 600, FixedSize = false)]
+[Plugin("PluginName", "DeveloperID", DisplayName = "Display Name")]
+[RibbonLayout("RibbonTabName")]
+[RibbonTab("Home", DisplayName = "Home")]
+[Command("CommandName", DisplayName = "Open Panel", Icon = "icon.png")]
+public class MyDockPanePlugin : DockPanePlugin
+{
+    public override Control CreateControlPane()
+    {
+        // 返回 Windows Forms 或 WPF 控件
+        var host = new ElementHost();
+        host.Child = new MyWpfUserControl();
+        host.Dock = DockStyle.Fill;
+        return host;
+    }
+
+    public override void DestroyControlPane(Control control)
+    {
+        control?.Dispose();
+    }
+}
+```
+
+## 2. ToolPlugin
+
+用于创建需要与 3D 视图交互的工具。
+
+```csharp
+[ToolPlugin("ToolName", "DeveloperID", DisplayName = "Tool Display Name")]
+[Plugin("PluginName", "DeveloperID")]
+[RibbonLayout("RibbonTabName")]
+[RibbonTab("Home", DisplayName = "Home")]
+[Command("CommandName", DisplayName = "Activate Tool", Icon = "icon.png")]
+public class MyToolPlugin : ToolPlugin
+{
+    public override bool MouseDown(MouseButton button, int x, int y)
+    {
+        // 处理鼠标按下
+        // 返回 true 表示已处理事件
+        return true;
+    }
+
+    public override bool MouseMove(int x, int y)
+    {
+        // 处理鼠标移动
+        return true;
+    }
+
+    public override bool MouseUp(MouseButton button, int x, int y)
+    {
+        // 处理鼠标释放
+        return true;
+    }
+
+    public override void OnActivate()
+    {
+        // 工具激活时调用
+        base.OnActivate();
+    }
+
+    public override void OnDeactivate()
+    {
+        // 工具停用时调用
+        base.OnDeactivate();
+    }
+}
+```
+
+### 获取 3D 点击坐标
+
+```csharp
+public override bool MouseDown(MouseButton button, int x, int y)
+{
+    if (button == MouseButton.Left)
+    {
+        // 将屏幕坐标转换为 3D 射线
+        var view = Application.ActiveDocument.CurrentViewpoint;
+        var pickResult = view.PickItemFromPoint(x, y);
+        
+        if (pickResult != null)
+        {
+            Point3D point = pickResult.Point;
+            // 使用点击的 3D 坐标
+        }
+    }
+    return true;
+}
+```
+
+## 3. RenderPlugin
+
+用于在 3D 视图中渲染自定义图形。
+
+```csharp
+[RenderPlugin("RenderPluginName", "DeveloperID")]
+[Plugin("PluginName", "DeveloperID")]
+public class MyRenderPlugin : RenderPlugin
+{
+    public override void Render(View view, RenderContext context)
+    {
+        // 在这里进行自定义渲染
+        // 使用 context 绘制线条、点、文本等
+        
+        // 示例：绘制一条红线
+        var points = new List<Point3D>
+        {
+            new Point3D(0, 0, 0),
+            new Point3D(10, 10, 10)
+        };
+        
+        context.DrawLines(points, new Color(1, 0, 0), 2.0f);
+    }
+}
+```
+
+## 4. AddInPlugin
+
+最简单的插件类型，用于执行一次性命令。
+
+```csharp
+[AddInPlugin("AddInName", "DeveloperID", DisplayName = "Command Name")]
+[RibbonTab("Home", DisplayName = "Home")]
+[Command("CommandName", DisplayName = "Run Command", Icon = "icon.png")]
+public class MyAddInPlugin : AddInPlugin
+{
+    public override int Execute(params string[] parameters)
+    {
+        // 执行命令逻辑
+        MessageBox.Show("Hello from AddIn!");
+        return 0; // 返回 0 表示成功
+    }
+}
+```
+
+## 5. EventWatcherPlugin
+
+用于监听文档事件。
+
+```csharp
+[EventWatcherPlugin("EventWatcherName", "DeveloperID")]
+[Plugin("PluginName", "DeveloperID")]
+public class MyEventWatcher : EventWatcherPlugin
+{
+    public override void OnDocumentChanged(object sender, DocumentEventArgs e)
+    {
+        // 文档变更时触发
+    }
+
+    public override void OnSelectionChanged(object sender, EventArgs e)
+    {
+        // 选择变更时触发
+    }
+
+    public override void OnViewChanged(object sender, ViewEventArgs e)
+    {
+        // 视图变更时触发
+    }
+}
+```
+
+## 插件属性详解
+
+### Plugin 属性
+
+```csharp
+[Plugin("PluginName", "DeveloperID", 
+    DisplayName = "显示名称",
+    ToolTip = "鼠标悬停提示",
+    LoadForCanExecute = true)]
+```
+
+### RibbonTab 属性
+
+```csharp
+[RibbonTab("TabName", DisplayName = "Tab 显示名称")]
+```
+
+### RibbonLayout 属性
+
+```csharp
+[RibbonLayout("LayoutName")]
+```
+
+### Command 属性
+
+```csharp
+[Command("CommandName", 
+    DisplayName = "命令显示名称",
+    ToolTip = "命令提示",
+    Icon = "icon.png",
+    LargeIcon = "icon_large.png",
+    Shortcut = "Ctrl+Shift+X")]
+```
+
+### DockPanePlugin 属性
+
+```csharp
+[DockPanePlugin(width, height,
+    FixedSize = false,              // 是否固定大小
+    MinimumWidth = 200,             // 最小宽度
+    MinimumHeight = 300,            // 最小高度
+    HasDockingFrames = true)]       // 是否有停靠框架
+```
+
+## COM 插件注册
+
+COM 插件需要注册到系统注册表。
+
+### 1. 为程序集添加 GUID
+
+```csharp
+// 在 AssemblyInfo.cs 中
+[assembly: Guid("YOUR-GUID-HERE")]
+
+// 在插件类上添加 ProgId
+[ProgId("YourCompany.YourPlugin")]
+public class YourPlugin : DockPanePlugin { }
+```
+
+### 2. 注册插件
+
+```bash
+# 使用 Visual Studio 自动注册（开发时）
+# 或在注册表中手动添加：
+# HKLM\SOFTWARE\Autodesk\Navisworks Manage\23.0\COM Plugins
+# 创建字符串值，名称为 ProgId，值为空
+
+# 或使用 nwregasm.bat
+nwregasm.bat "path\to\your\plugin.dll"
+```
+
+## 项目文件配置
+
+### 必要的引用
+
+```xml
+<!-- Navisworks API -->
+<Reference Include="Autodesk.Navisworks.Api" />
+<Reference Include="Autodesk.Navisworks.ComApi" />
+<Reference Include="Autodesk.Navisworks.Interop.ComApi" />
+<Reference Include="Autodesk.Navisworks.Timeliner" />
+<Reference Include="Autodesk.Navisworks.Clash" />
+<Reference Include="Autodesk.Navisworks.Controls" />
+```
+
+### 输出路径
+
+插件应该输出到 Navisworks 插件目录：
+
+```
+C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\YourPluginName\
+```
+
+## 调试插件
+
+1. 设置启动外部程序：
+   - 路径：`C:\Program Files\Autodesk\Navisworks Manage 2026\Roamer.exe`
+
+2. 附加到进程调试：
+   - 在 Visual Studio 中选择 "附加到进程"
+   - 选择 `Roamer.exe`
+
+3. 日志输出：
+
+   ```csharp
+   // 使用 System.Diagnostics.Debug
+   System.Diagnostics.Debug.WriteLine("Debug message");
+   ```