1. 为什么值得认真拆一遍FreeCAD的模块与架构
很多人第一次打开FreeCAD，看到左边一排工作台切换下拉框，下意识会觉得它跟那些把功能一股脑堆在菜单栏里的建模软件差不多——无非是建模、装配、出图几个模块换个位置而已。真上手之后才发现完全不是一回事：装了个插件突然多出一整套工具条，改两行参数整个模型从头重建，写个脚本能直接调起草图求解器。这些现象背后，是一套把“核心内核”和“功能模块”彻底分开的架构设计。
这篇内容想干的事情很明确：把FreeCAD的模块划分讲清楚，把它们与核心架构之间的依赖关系梳理明白，最后落到“知道这套结构之后，我该往哪个方向动刀”这个实际问题上。适合三类人看：一是被各种工作台绕晕、想搞明白它们到底是什么关系的新手；二是准备给FreeCAD写插件、做二次开发的人；三是想从源码层面理解一个成熟三维CAD系统怎么组织代码的老手。前两类可以重点看模块划分和工作台机制，第三类可以直接跳到核心对象模型和依赖图那几节。
先给结论性的判断，免得读到后面才反应过来：FreeCAD的架构本质是**“一个几何内核 + 一个对象文档模型 + 一堆可插拔的功能包”**。理解这句话，后面所有模块的归类、所有依赖关系的走向，都能自己推出来，不用死记。我在几个不同的三维项目里反复折腾过它的模块划分，踩过的坑大多源于一个误解——把工作台当成了模块，把模块当成了独立程序。这两者混淆，是后面一切困惑的源头。
2. 工作台不等于模块：先把这个概念错位拧正
2.1 界面上看到的“工作台”，只是模块的展示皮肤
打开软件后菜单里列出来的那一串名字，本质上是一组界面配置方案，而不是代码层面上的功能边界。一个工作台做的事情是：决定当前显示哪些工具按钮、哪些右键菜单项、哪些工具栏分组。它本身不包含任何几何计算逻辑，只是在合适的时机把某个模块里的命令对象挂到界面上。
这个区别在实操中非常明显。你可以同时打开“零件设计”工作台和“草图”工作台各自的一条命令，它们能协同工作，因为它们背后调的是不同模块里的对象，而工作台只是提供了入口。反过来，禁用某个工作台不会删掉对应的模块代码，只是把界面入口藏起来。
我把这个关系整理成一张对照表，读的时候可以对着自己装过的插件验证：
| 层面 | 具体形态 | 变更影响 |
|---|---|---|
| 工作台 | 菜单分组、工具栏布局、命令入口集合 | 只影响界面呈现，不影响内核能力 |
| 模块 | 一组相关的对象类型、命令、求解逻辑 | 影响可用的对象类型和功能范围 |
| 内核 | 几何内核、文档对象模型、依赖图 | 决定整个系统能不能跑起来 |
理解这一层之后，很多“为什么我装了插件却在某个工作台找不到按钮”的问题就自动有答案了：插件注册的是模块和新工作台，如果它没有往你当前停留的工作台里塞命令，那当然看不到。
2.2 模块的三种形态：编译进主程序、动态加载、纯脚本
从代码组织角度，模块大致分三类，这个分类对二次开发很关键。
第一类是编译进主程序的核心模块，它们跟主程序一起构建，提供最基础的对象类型和文档能力。这类模块不能单独卸载，动了它整个程序就起不来。
第二类是动态加载的功能模块，构建成独立的动态库，启动时或首次使用时加载。零件设计、草图、装配这类主体功能模块大多属于这类，它们可以独立构建，但依赖核心模块提供的对象框架。
第三类是纯脚本模块，用脚本语言写成，放在用户目录下的模块搜索路径里，启动时被扫描注册。这类模块门槛最低，一个目录加一个入口文件就能跑起来，适合做工具集、批量处理、界面定制。
这三类的差别不只是语言，更在于加载时机和失败影响范围。核心模块挂了程序直接崩溃；动态模块加载失败通常只影响对应功能，主界面还能起来；脚本模块报错往往只打印一行日志，甚至不影响其他模块继续加载。做插件开发时，选择哪种形态，取决于你能不能接受“加载失败就整个功能消失”这个代价。
2.3 一个容易踩的坑：模块初始化顺序
这里有个实际经验值得单独说。模块之间存在隐式依赖：A 模块的对象类型需要在 B 模块注册完之后才能正确注册。如果加载顺序乱了，表现是“对象类型存在但属性缺失”或者“命令存在但点下去报空指针”。
我遇到过一次典型情况：自定义模块在初始化时直接引用了另一个模块里的对象类型常量，结果在某些启动路径下那个模块还没注册，拿到的就是空值，程序能起来但一用就崩。解决办法是把这种跨模块引用延迟到真正使用的时候再取，而不是在模块初始化阶段就抓死。这个原则在几乎所有插件式系统里都通用——初始化阶段只做自己的事，跨模块的东西留到调用时再解析。
3. 核心架构的三根支柱
3.1 文档对象模型：一切皆对象，对象皆有属性
FreeCAD 里你能操作的所有东西——一个立方体、一条草图线、一个约束、一个装配关系——在文档层面都是带属性的对象。这个统一抽象是整个架构最漂亮的地方，也是最容易被低估的地方。
统一成一类东西带来的直接好处是：保存、撤销、属性编辑、脚本访问全都只需要写一套逻辑。文档负责持有对象、维护对象之间的引用、序列化到文件。对象自己只负责声明“我有哪些属性、每个属性的类型是什么、什么时候需要重算”。
实际写脚本时这个模型非常好用。你可以遍历文档里的所有对象，按类型筛选，批量改属性，批量触发重算。不用为每种几何体写一套特判逻辑。我处理过一个批量修改模型参数的场景，几十个文件，核心代码就一个循环加一次属性赋值，原因就是这套统一抽象把差异抹平了。
值得强调的是属性是有类型的，不是简单的键值对。有几何类型、有链接类型、有枚举类型，还有只读的计算结果属性。类型信息在属性声明时就固定下来，界面上的编辑控件、脚本里的赋值检查、文件里的序列化格式，全都从这份声明推出来。这也是为什么 FreeCAD 的属性面板能自动生成——它不需要为每个对象手写界面，读属性声明就够了。
3.2 参数化重建：依赖图驱动的重算机制
这是整套架构真正的发动机。对象之间的依赖关系被显式记录成一张有向图，当你改了一个上游参数，系统顺着图往下游标记“需要重算”，然后按拓扑顺序依次执行各对象的重算逻辑。
为什么必须用图而不是简单递归？因为模型里存在菱形依赖：一个对象可能同时依赖两条上游分支，而这两条分支又汇聚到同一个更上游的对象。简单递归会把共同上游算两遍，甚至陷入循环。依赖图配合拓扑排序，保证每个对象在一次重算中只算一次，顺序正确。
这个机制的直接后果是：建模时的操作顺序会体现在依赖结构里。你在草图里画一条线，再用它拉伸成实体，这条线就是拉伸对象的上游。你后面再去改草图的尺寸，拉伸会自动跟着变，因为图里有这条边。相反，如果你在某个环节做了“断开链接”的操作，那条边就没了，上游怎么改下游都不会动。
有个细节新手经常忽略：重算不是实时的，是标记后批量执行。你连续改十个参数，系统不会算十次，而是积累标记，最后一次算完。这在复杂模型上节省的时间非常可观。但也意味着，如果你的脚本在循环里每改一个参数就手动触发一次全量重算，性能会很差。正确做法是改完所有参数，最后触发一次。
3.3 几何内核：被封装起来但决定能力边界
几何内核负责真正的实体建模运算——布尔、倒角、抽壳、曲面求交。它跟上层架构的关系是被封装：上层对象不直接暴露内核的原始数据结构，而是通过一层包装来调用。
这种封装的好处是理论上可以换内核而不动上层，坏处是封装层本身有成本，某些内核的高级能力不一定能完整暴露到上层。实际操作中会遇到一类问题：某个操作在别的软件里很轻松，在这里却报错或者结果不对。追根溯源，往往是封装层传参方式、容差设置、或者内核本身对这个运算的鲁棒性不足导致的。
理解这一点对排错很有帮助。当布尔运算失败时，先别怀疑自己的模型画错了，先想想是不是两个面几乎共面导致的容差问题——这是几何内核的经典痛点，跟具体哪个软件无关。把两个面的位置错开一个微小距离再运算，往往就过了。
4. 主要功能模块的职责划分与依赖走向
4.1 草图与约束求解：参数化建模的入口
草图模块负责二维几何加约束求解。它在依赖结构里处于比较靠上的位置：草图对象产出几何轮廓，下游的拉伸、旋转、扫掠都依赖它。
这个模块的核心难点是约束求解。你画一堆线和圆弧，加一堆尺寸约束和几何约束，求解器要把这些约束转成方程组然后解出来。方程组的规模和条件数直接决定求解速度和稳定性。
实操中的经验是：约束不是越多越好，过约束和欠约束都会出问题。欠约束的草图能生成实体，但形状会随参数漂移，重建时可能变成完全不同的样子。过约束则直接报冲突。我的习惯是画完之后看剩余自由度提示，尽量收敛到零，同时避免用一堆冗余约束去“凑”零自由度。冗余约束在参数变动时最容易引发求解失败。
另一个实际技巧：求解失败时，先把约束删到最少，跑通之后再一个一个加回来，每次加完触发重算。这样能精确定位到是哪条约束导致的冲突，比盯着报错信息猜要快得多。
4.2 实体建模模块：靠内核吃饭的那一层
实体建模模块提供拉伸、旋转、扫掠、放样、布尔、倒角、抽壳这些操作。它自己不做几何运算，只负责把参数组织好、调用内核、把结果包装成对象返回。
这一层最值得说的是特征树的概念。每个建模操作产出一个特征对象，特征按顺序堆叠形成最终形状。这个顺序在依赖图里就是一条链。插入一个新特征到中间，下游全部要重算——这也是为什么在复杂模型中间插入特征会很慢的原因。
模块之间的依赖走向大致是这样的：
草图模块 → 产出轮廓对象 实体建模模块 → 消费轮廓，产出实体对象 装配模块 → 消费实体，产出装配关系 工程图模块 → 消费实体与装配，产出投影视图这个链条意味着上游出问题，下游全部受影响。草图里一条线断开了，拉伸报错，装配失败，出图空白——顺着链条往回找，永远是上游先坏。
4.3 装配模块：位置关系与求解的复杂度
装配模块负责把多个零件按约束关系摆到一起。它的复杂度和草图求解不是一回事：草图求解的是二维约束，装配求解的是三维刚体变换约束。
三维约束求解的难点在于约束组合的奇异性和冗余。同样的相对位置关系，可以用不同的约束组合表达，有些组合在数值上不稳定，稍微一动就发散。实际经验是尽量用能明确定义自由度的最小约束集，少用“对齐”这类语义模糊的约束。
装配依赖实体模块产出的零件对象，同时又会被工程图模块依赖。它在链条中间，承上启下，任何装配层面的错误都会传导到出图环节。
4.4 工程图与外围模块：消费端的位置
工程图模块从三维模型投影出二维视图，标注尺寸。它处于链条最下游，只读不写，不改变模型本身。
外围模块还包括导入导出、网格处理、渲染、测量这些。它们大多是旁路模块：从主链条上取数据，处理完输出，不回写主链。这类模块出问题通常不影响建模主流程，相对独立，开发门槛也低一些，适合作为插件开发的切入点。
5. 源码层面的目录结构与构建关系
5.1 目录组织反映的架构意图
源码树的组织方式基本就是架构的文字版。核心部分放在主目录下，包含文档对象框架、属性系统、依赖图、几何包装层；各功能模块各自一个子目录，相互平级；脚本模块放在独立的模块目录里。
这个平级结构传达的信息很明确：功能模块之间不应该互相直接依赖，只依赖核心。如果两个模块需要通信，走核心提供的机制（对象引用、信号、事件），而不是直接 include 对方的头文件。
实际维护中这条原则经常被破坏，破坏的后果是构建变复杂、循环依赖、某个模块单独构建失败。我自己写插件时踩过这个坑：为了省事直接引用了另一个模块的内部类，结果对方改了个接口，我的模块就编不过了。后来改成只依赖公开的对象类型和属性接口，稳定性立刻不一样。
5.2 构建系统的分层：核心库、模块库、可执行程序
构建产物大致分三层：核心库、各模块的动态库、主程序可执行文件。主程序负责初始化、加载模块、拉起界面，自己不包含具体建模功能。
这种分层的直接好处是模块可以单独构建和测试。你改了某个模块的代码，只需要重新构建那个模块，主程序不用动。调试时也可以只加载需要的模块，启动快很多。
但对插件开发者来说有个现实约束：如果你依赖了某个模块的内部符号，那就必须保证那个模块的版本匹配。跨版本发布插件时，这是最常见的兼容性故障源。稳妥的做法是只依赖稳定的公开接口，版本兼容范围写宽一点。
6. 从架构推出来的二次开发路径
6.1 三种开发方式的适用场景对比
知道了架构分层，开发路径的选择就变成一道有依据的选择题，而不是凭感觉。
| 开发方式 | 依赖层级 | 能力范围 | 适合场景 |
|---|---|---|---|
| 纯脚本宏 | 只依赖脚本接口 | 调用现有功能、批量处理、界面定制 | 个人效率工具、一次性任务 |
| 脚本模块 | 脚本接口加模块注册机制 | 新增命令、新增工作台、自定义对象 | 团队内部工具集、领域专用功能 |
| 编译模块 | 核心库与对象框架 | 新增对象类型、深度集成、性能敏感逻辑 | 产品级插件、需要几何计算的扩展 |
从下往上，能力增强，维护成本也同步上升。我的建议是从最轻的开始，真遇到瓶颈再往上走。很多需求用脚本模块就能解决，没必要一上来就编译模块。
6.2 自定义对象：必须理解的三个回调
写编译模块绕不开自定义对象，而自定义对象的核心就三个回调：声明属性、执行重算、序列化。
声明属性阶段决定对象有哪些数据；执行重算阶段在参数变化时被调用，负责根据上游数据算出结果；序列化阶段负责把对象状态写进文件和读回来。
这里最容易犯的错是在重算回调里做了不该做的事。重算回调应该只做纯计算：读属性、读上游、算结果、写结果属性。不要在里面改文档结构（增删对象），不要在里面触发其他对象的重算，不要在里面做界面操作。违反了轻则重算顺序错乱，重则死循环。
我吃过一次亏：在重算里顺手改了一个上游对象的属性，结果依赖图被动态修改，重算过程直接卡死。改成只读不写、把修改提前到命令执行阶段，问题立刻消失。
6.3 依赖管理：引用上游要留退路
自定义对象引用上游对象时，这个引用会被序列化进文件。上游对象被删掉，引用就悬空，读文件时对象会处于无效状态。
正确的处理方式是在重算回调里先检查引用的有效性，无效就跳过计算并把结果标记为错误状态，而不是直接崩。同时属性面板上要能看出这个对象处于错误状态，让用户知道该修哪里。这个细节看着小，实际决定了插件在用户手里是“偶尔出错但能救”还是“一崩就废”。
6.4 调试与日志：模块加载失败怎么查
模块加载失败是二次开发最高频的问题。排查顺序建议固定下来：先看模块是否被扫描到（搜索路径对不对），再看入口文件是否被调用（注册代码有没有执行），然后看依赖是否解析成功（动态库能不能加载），最后看注册的对象类型是否真的有冲突。
日志方面，模块初始化阶段打的日志一定要够细，至少把“进入初始化”“注册了哪些类型”“初始化完成”三个阶段分开打。出问题时这三行日志能立刻定位到失败发生在哪一步。这个习惯我建议从第一个模块就开始养成，后期排查能省下大量时间。
7. 几个反复出现的认知误区
第一个误区是把工作台当成功能边界。前面说过，工作台只是界面皮肤，判断一个功能属于哪个模块，看的是它产出的对象类型，不是按钮在哪个工作台里。
第二个误区是认为参数化等于自动更新。实际上依赖图只记录显式引用关系，你做了断开链接或者用了不追踪依赖的操作，参数变了模型也不会变。要参数化生效，得保证依赖链条完整。
第三个误区是觉得模块越多越好。每多一个模块，启动时多一次加载、多一份注册开销，模块之间的类型冲突风险也上升。我见过装了一堆插件之后启动慢到没法用的环境，卸载掉一半不常用的，问题就没了。
第四个误区是把几何内核当成万能。内核有它不擅长的情况，共面、微小特征、极端长宽比都是经典雷区。遇到运算失败，先怀疑几何条件，再怀疑代码逻辑，踩坑效率会高很多。
最后说个我自己的体会：这套架构最值得学的不是某个模块怎么实现，而是它怎么把“稳定的核心”和“多变的功能”切开。核心改动少、接口稳定，功能模块才能各自快速迭代而不互相拖累。做任何插件系统，这个切分思路都比具体的代码技巧更有价值。至于后续还能往哪扩展，我最近在试的是把批量处理逻辑完全放在脚本模块里，核心一行不动，跑得挺稳，维护成本也低，这条路值得继续走下去。
