核心设计哲学：FP + 不可变 + 接口扩展

翻阅项目的 AGENTS.md两条原则凌驾于一切之上代码必须能工作。 正确性优先。一个能工作的简单版本胜过坏掉的复杂版本。代码必须易于改进和重构。 所有其他原则服务于这个目标。这是典型的 现实主义工程哲学。作者没有追求企业级抽象和最佳实践的教条而是选择了一条更务实、也更具个人风格的路线。具体的代码准则包括不可变扩展函数 最小接口这是整个 SDK 中最高频出现的模式。看看这个// 小接口行为通过扩展函数添加public static bool InRange(this IReadOnlyList self, int n) n 0 n self.Count;// 几何操作也是如此public static TriangleMesh3D Triangulate(this QuadMesh3D mesh) new(mesh.Points, mesh.FaceIndices.QuadFacesToTriFaces());接口只定义是什么扩展函数定义能做什么。这就意味着你可以自由地添加新行为而不破坏任何调用方同时保持了纯函数的不可变性——每个操作返回新值不修改原数据。函数式风格渗透到底var 大量使用类型从右侧推演早期返回early return替代 elsemap/filter/fold 优于 for 循环readonly struct [StructLayout(LayoutKind.Sequential)] 无处不在Debug.Assert 广泛用于不变量验证三、Plato用代码生成器构建数学王国这是 Ara3D 最独特的技术决策之一。Plato 是一个独立的代码生成器有独立的仓库它为 SDK 生成了所有数学和几何类型。打开 src/Plato.Generated/你会看到 100 个 .g.cs 文件全部标记着 // Autogenerated file: DO NOT EDIT。生成的不仅仅是对 System.Numerics 的封装每个生成的类型都遵循严格的结构模板而这套模板的设计异常精巧// Vector3 的生成代码节选[StructLayout(LayoutKind.Sequential, Pack1)]public partial struct Vector3 : IVector{// 与 C# 元组的隐式双向转换public static implicit operator (Number, Number, Number)(Vector3 self) …;// 所有 6 个分量置换自动生成 public Vector3 XZY { get (this.X, this.Z, this.Y); } // 签名距离场函数直接生成在 Vector3 上 public Number SdSphere(Number r) this.Length.Subtract(r); public Number SdBox(Vector3 b) { ... } // 贝塞尔曲线及其导数展开 public Vector3 CubicBezier(Vector3 b, Vector3 c, Vector3 d, Number t) ...;}类型的泛型层次Plato 生成的接口层次是精心设计的IValue → IVectorLike → INumerical → IVector → Vector2, Vector3, Vector4└── IInterpolatable (所有类型支持 Lerp)└── IScalarArithmetic (向量 × 标量泛型)这意味着你可以写出这样的泛型算法// 对所有 IVector 类型都生效public static T LerpToHalf(this T a, T b) where T : IInterpolatable a.Lerp(b, 0.5f);为什么要自建而不是直接用 System.Numerics作者的考量很清晰。System.Numerics 的问题在于类型不完整 — 有 Vector3 但没有 Point3D、TriangleMesh3D 等几何概念缺乏统一接口 — 没有办法对所有支持加法的类型写泛型代码版本脆弱性 — .NET 6/7/8 不同版本间行为变化不可控功能不满足需求 — 签名距离场、贝塞尔展开、分量置换等功能需要自行实现Plato 通过代码生成实现了 类型一致 接口统一 版本锁定。而且生成的 SdBox、SdTorus 等 SDF 函数直接以实例方法的形式挂在 Vector3 上——这种直觉式的 API 设计不可能在 System.Numerics 中实现。四、集合与内存IReadOnlyList 的一等公民地位Ara3D 的集合库是整个 SDK 的血管系统——所有数据以 IReadOnlyList 形式传递。它回避了 IEnumerable / LINQ to Objects 的惰性求值范式转而使用一种更激进的模式。ReadOnlyList 的设计精髓ReadOnlyList 不是 List——它是一个 函数 计数的对偶// ReadOnlyList 只是一个 Funcint, T 和一个 Countpublic readonly struct ReadOnlyList : IReadOnlyList{readonly Funcint, T _getter;public readonly int Count;public T this[int index] _getter(index);}关键推导当 Select 操作应用到这个结构上时不会分配任何新数组只创建一个新的函数组合public static ReadOnlyListSelectT, U(this IReadOnlyList self, FuncT, U f) self.Count.Select(i f(self[i])); // 只创建新的 Funcint, U这个模式带来了巨大的性能优势——链式变换Select().Where().Take()没有中间分配没有任何 IEnumerator 装箱没有惰性迭代器的状态机。延伸到多维和稀疏Ara3D.Collections 还提供了IReadOnlyList2D / IReadOnlyList3D — 通过行优先索引计算的零拷贝多维视图CompressedSparseRow — CSR 格式稀疏矩阵在 Topology.cs 中用于半边的邻接查询IntegerRange — 零分配的整数范围枚举这个设计理念贯穿了所有 SDK 库——想象一下一个包含数百万面片的 BIM 模型的几何数据也是以这种零拷贝的方式传递的。五、几何引擎从三角剖分到隐式曲面Ara3D.Geometry 是 SDK 中最大的单一库覆盖了网格操作、拓扑分析、隐式曲面、三角剖分、空间查询、体素化、形状特征等几乎所有核心几何算法。精选算法一览领域 算法 文件三角剖分 Bowyer-Watson 2D Delaunay DelaunayTriangulator.cs多边形三角化 Ear-clipping支持带洞多边形 PolygonTriangulator.cs等值面提取 Marching Cubes MarchingCubes.cs隐式曲面 SDF 函数组合 逆变换 Sdf3D.cs拓扑 Half-edge 数据结构 CSR 邻接 Topology.cs空间索引 AABB Tree AABBTree.cs主成分分析 协方差矩阵 特征分解 PrincipalComponentAnalysis.cs形状分类 100 个衍生特征杆状/板状/块状 MeshFeatures.cs一个优雅的 FP 技巧SDF 变换public class Sdf3D : ITransformable3D{readonly FuncPoint3D, Number _func;public Number Eval(Point3D p) _func(p); // 对 SDF 做变换 对采样点做逆变换 public Sdf3D Transform(Transform3D t) new(p Eval(t.Invert.TransformPoint(p)));}不需要修改 SDF 函数本身——只需要对采样点应用逆变换。当你的 SDF 是一个函数组合堆栈时这种数学上的优雅直接转化为代码的简洁。半边拓扑 CSR 矩阵Topology.cs 从三角形网格构建完整的 half-edge 结构使用 CSR 矩阵存储顶点-面-边的邻接关系。这种数据结构支持高效的边界环检测、流形判断和欧拉特征数计算——对于 BIM 元素的空间关系分析至关重要。六、Bowerbird运行时 C# 编译的命令系统Bowerbird 是整个生态中最有创意的系统。它把插件这个概念从 编译时 搬到了 运行时。核心思路CommandsRoot/├── ExportGeometry/│ ├── ExportGeometry.manifest.json ← JSON 描述文件│ ├── ExportGeometryCommand.cs ← 纯 C# 源码│ └── bin/│ └── ExportGeometry-20260715T120000.dll ← Roslyn 编译产物Bowerbird 的工作流程CommandCatalog 扫描文件夹读 JSON manifest命令名、描述、类型名CommandCompiler 调用 Microsoft.CodeAnalysis.CSharp 编译 .cs 源码为 DLL通过 指纹缓存源文件哈希 引用文件指纹避免无变化的重复编译CommandLoader 用 Assembly.LoadFile 加载 DLL反射创建 INamedCommand 实例CommandRunner 执行命令返回结果应用场景Ara3D Studio 的脚本系统用户写 C# 脚本 → 编译 → 执行无需完整的 VS 项目Revit 2025 插件BowerbirdExternalCommand 让 Revit 内部也能运行动态编译的 C# 命令命令行工具Ara3D.Bowerbird.Console 提供 CLI 入口// 一个典型的 Bowerbird 命令public class ExportGeometryCommand : NamedCommand{public override string Name “export-geometry”;public override void Execute(ICommandContext context){// 获取当前 Revit 文档/3D 场景// 导出为 PLY/GLTF/BFAST}}这种设计允许终端用户Revit 建筑师、Studio 使用者在不重新编译任何东西的前提下扩展应用行为——可以做到写完即用。七、BIM 数据模型与列式存储BOSBIM Open Schema是 Ara3D 定义的工具无关 BIM 数据标准化格式设计目标非常明确面向分析优化而不是面向显示优化。列式几何存储BimGeometry 将几何数据组织为 6 个平行数组struct of arraysInstance Table: EntityIndex, MaterialIndex, MeshIndex, TransformIndexVertex Table: float[] X, Y, Z (各列独立存储)Index Table: int[] 三角形索引Mesh Table: MeshVertexOffset[], MeshIndexOffset[]Material Table: Red[], Green[], Blue[], Alpha[], Roughness[], Metallic[]Transform Table: TX[], TY[], TZ[], QX[], QY[], QZ[], QW[], SX[], SY[], SZ[]为什么用这种模式因为列式存储直接适配 DuckDB / Apache Parquet 的查询引擎——你可以用 SQL 对几何数据做聚合分析比如统计所有 MEP 元素的总体积或找出每个楼层所有窗户的面积。EAV 参数模型 15 种关系参数数据使用 Entity-Attribute-Value 模式——高度稀疏的 BIM 数据不适合扁平表EAV 是最自然的建模方式。关系层面定义了 15 种语义关系PartOf, HostedBy, Voids, Fills, ConnectsTo, BoundedBy 等同时覆盖 Revit 和 IFC 的语义。八、MCP当 3D 工具遇见 AI在 wip/Ara3D.MCP 中我们发现了一个零外部依赖的 MCPModel Context Protocol实现。这可能是整个项目中最前沿的部分。MCP 是什么为什么在这个项目里MCP 是 Anthropic 提出的开放协议允许 AI 助手通过标准化接口与外部工具交互。Ara3D 的 MCP 实现让 AICursor、Claude 等可以直接操控 3D 场景。var server new McpServer(“Ara3D Studio”, “1.0.0”, “Ara3D 3D Studio Tools”);// 注册一个工具server.Tool(“list_entities”, “列出场景中所有实体”,args {var category args.GetString(“category”);return Results.Ok(entities.Where(e e.Category category));});server.Start(“http://127.0.0.1:8766/mcp/”);与 Bowerbird 的深度绑定ScriptMcpTools.Refresh() 会扫描 Bowerbird 加载的所有插件为每个脚本自动注册一个 script_{name} MCP 工具。这就形成了完整的链路用户写 C# 脚本 → Bowerbird 编译 → MCP 暴露为 AI 工具 → Cursor/Claude 通过自然语言调用Bowerbird 的 REFACTOR.md 中也明确写道“We will use the system for compiling MCP tools”——这说明 MCP 正是 Bowerbird 的下一个演进方向。九、单人维护的工程智慧遍历整个项目后有些工程实践值得单独提炼出来技术债务看得见项目中有一整套债务追踪系统代码中的 // TODO: 标记 docs/TECHNICAL_DEBT.md 的条目 docs/TODO.md 的优先级排序。不藏污纳垢也第一时间修所有东西——而是记录、排序、在合适的时机处理。这对于单人项目是至关重要的自我管理方法。分层测试按需执行test.bat fast # 跳过 I/O 密集型测试适合高频迭代test.bat geometry # 只跑几何模块test.bat ifcmesher # IFC 网格化专项test.bat # 完整运行包含 Slow 测试还有一个 tests/Ara3D.SDK.KnownIssues.Tests 项目——专门存放已知会失败但尚不阻塞开发的测试用例。当 bug 修好时测试从 KnownIssues 移回正常项目。这种明确的用测试承载技术债务的做法在商业化项目中也少见。度量驱动的 IFC Mesherwip/Ara3D.Ifc.Mesher 的开发方式很值得学习每次改动都通过 parity score 与 web-ifc 的基准输出做对比T0: 微测试单个几何操作