第10章：二次开发实战——构建、测试与发布

最后一章面向真正的“二次开发”：如何在自己的工程里消费 Ara3D SDK，如何用 Bowerbird 做实时脚本，如何写 Revit 插件把 BIM 数据导出为 BOS，以及仓库自身的构建/测试/发布工作流。掌握这些，你就能把 SDK 用于生产。

1. 在你的项目中消费 SDK

最简单的方式是引用 NuGet 元包（见第 02 章）：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Ara3D.SDK" Version="1.6.*" />
  </ItemGroup>
</Project>

• 只做几何/IO、跨平台：用 Ara3D.SDK.Core + Ara3D.SDK.Geometry（net8.0）；
• 需要 IFC/Revit/glTF/VIM 全家桶：用 Ara3D.SDK（net8.0-windows）；
• 也可只引用需要的细粒度包（如仅 Ara3D.IO.PLY）以减小依赖面。

2. Bowerbird——实时 C# 脚本

Bowerbird 让你在宿主应用（Studio、Revit 等）中热加载、实时运行 C# 脚本，靠 Roslyn 在运行时编译。它是快速原型/现场调试的利器。

关键类型：

public class BowerbirdOptions          // 脚本目录、引用程序集、编译选项
public class BowerbirdService          // 监视脚本目录、编译、执行
public class CommandCatalog            // 发现并登记脚本中的命令

工作方式：

1. 你把 .cs 脚本放进配置的脚本目录（manifest 驱动）；
2. BowerbirdService 监视目录，用 Roslyn 编译成程序集；
3. CommandCatalog 反射发现其中的命令类型；
4. 宿主 UI 列出命令，点击即执行——改脚本存盘即生效，无需重启宿主。

var options = new BowerbirdOptions
{
    ScriptDirectory = @"C:\MyScripts",
    ReferencedAssemblies = { typeof(Ara3D.Geometry.TriangleMesh3D).Assembly },
};
var service = new BowerbirdService(options);
service.Recompile();                       // 编译目录中所有脚本
foreach (var cmd in service.Catalog.Commands)
    Console.WriteLine(cmd.Name);

Bowerbird 依托第 03 章的 Ara3D.Utils.Roslyn（Roslyn 封装）实现运行时编译。

3. Revit 插件——BIM 数据导出

Ara3D 提供 Revit 集成，把 Revit 模型导出为开放 BOS（见第 08 章）。

• BowerbirdRevitApp : IExternalApplication——Revit 外部应用入口，把 Bowerbird 脚本能力带进 Revit（在 Revit 里实时跑 C#）；
• BIMOpenSchema.Revit2025——针对 Revit 2025 的导出器，遍历 Revit 文档，把元素/参数/关系/几何写成 BOS。

一个导出器的骨架：

public class BosExportCommand : IExternalCommand
{
    public Result Execute(ExternalCommandData data, ref string msg, ElementSet elems)
    {
        Document doc = data.Application.ActiveUIDocument.Document;
        IBimData bim = RevitToBosConverter.Convert(doc);  // 遍历 Revit → BOS
        ParquetUtils.Write(bim, @"C:\out\model_bos.parquet");
        return Result.Succeeded;
    }
}

导出后即可用第 08 章的 DuckDB/Parquet/Excel 工具做分析——打通 Revit → 开放数据 → 数据科学 的链路。

Revit 插件面向具体 Revit 版本（如 2025），需引用对应 RevitAPI.dll，并作为 .addin 部署到 Revit 插件目录。

4. apps——BOS Browser 等示例应用

apps/ 目录提供成品应用做参考，最典型的是 BOS Browser：一个 WPF 桌面应用，用来打开并浏览 BOS 数据（实体表、参数、关系、几何预览）。它展示了如何在 GUI 里消费 IBimData / BimObjectModel，是构建你自己的 BIM 数据工具的现成模板。

5. 仓库构建工作流

从源码构建/开发时，仓库根目录提供了一组批处理脚本：

版本单一真源：Directory.Build.props 里的 Ara3DVersion 属性统一控制所有包版本；bump-version.bat 修改的就是它。这保证 monorepo 里几十个包版本一致。

6. 运行测试

test.bat 支持按测试区域筛选，加速本地迭代：

REM 全部测试
test.bat all

REM 只测几何，快速模式
test.bat geometry fast

REM 只跑名字匹配的测试
test.bat sdk fast MyMeshTest

可用区域（area）：

7. 打包与发布

发布 NuGet 的典型流程：

REM 1) 递增版本（改 Directory.Build.props 的 Ara3DVersion）
bump-version.bat

REM 2) 构建
build.bat

REM 3) 跑测试确保绿灯
test.bat all

REM 4) 打包所有 NuGet
pack.bat

REM 5) 推送到 NuGet 源
release-nuget.bat

因为版本来自单一真源，pack.bat 产出的所有包版本天然对齐，避免元包与细粒度包版本错配。

8. 二次开发的推荐路径

1. 原型阶段：用 Bowerbird 在 Studio/Revit 里实时写脚本，快速验证几何/数据处理逻辑；
2. 固化阶段：把稳定逻辑抽成引用 Ara3D.SDK.* NuGet 包的独立类库；
3. 交付阶段：
   • 交互工具 → 打包成 Studio 插件（第 09 章）；
   • BIM 数据管道 → Revit 导出器 + BOS + DuckDB/Parquet 分析（第 08 章）；
   • 数据/几何转换服务 → 用 Ara3D.SDK.Core/Geometry/IO 组合，跨平台部署；
4. 发布阶段：若贡献回上游或维护自有分支，遵循 Directory.Build.props 版本单一真源 + pack.bat/release-nuget.bat 流程。

9. 全书回顾

至此我们走完了 Ara3D SDK 的全景：

• 第 01–02 章：架构全景、元包体系、环境搭建与第一个程序；
• 第 03–04 章：Core 基础库、Plato 数学与 F8 SIMD 加速；
• 第 05–06 章：不可变值类型几何/网格建模、场景模型与实例化渲染；
• 第 07 章：BFAST/G3D/PLY/glTF/VIM/STEP/GeoJSON 全套 IO；
• 第 08 章：BimOpenSchema、IFC 加载与开放数据导出；
• 第 09 章：Studio 插件（脚本组件 + FlowObject + 特性 UI）；
• 第 10 章：Bowerbird 实时脚本、Revit 集成、构建/测试/发布工作流。

Ara3D SDK 的设计哲学一以贯之：零依赖、值语义、列式数据、SIMD 高性能、开放格式。理解并善用这些原则，你就能用它高效构建从几何处理到 BIM 数据分析的各类三维应用。祝开发愉快！