摘要：PartCAD 试图把包管理、依赖固定、按需构建和自动测试引入机械产品开发。本文解析 partcad.yaml、对象模型、装配接口、BOM、几何后端和 CI 流程，并讨论它与 PLM、ERP 和供应链主数据的衔接方式。
机械团队使用 Git 管理脚本并不稀奇，难点在于：零件模型、装配关系、参数、外购件、制造信息和验证结果如何共享同一套寻址与依赖规则。PartCAD 给出的答案，是以 partcad.yaml 描述硬件包，以统一对象模型承载草图、接口、零件、装配和供应方，再通过 CLI、Python API、VS Code 扩展及 CI 驱动解析、渲染、导出和测试。
项目将自己定位为“面向实体产品的包管理器”和产品技术数据包工具。这个定位值得重视，因为其核心价值不只在几何建模。它试图把软件工程里已经成熟的模块复用、依赖固定、按需构建、缓存、自动测试和发布习惯，引入机械与机电产品开发。对采用 CadQuery、build123d、OpenSCAD、KiCad 或 STEP 交换文件的团队，PartCAD 已具备可实验、可接入流水线的基础；若目标是覆盖企业级变更管理、配置有效性、审批、合规和供应链主数据，则仍需 PLM、ERP、QMS 等系统配合。
一、架构：清单层、对象层、执行层与交付层
PartCAD 的入口通常是包目录里的 partcad.yaml。清单声明包元数据、PartCAD 版本约束、Python 版本与依赖、子包依赖，以及包内对象。官方配置模型包含五类关键对象：sketches、interfaces、parts、assemblies、providers。其中，草图提供二维轮廓；接口描述连接端点、端口坐标和可调参数；零件对应可采购或可制造的三维对象；装配记录对象树及定位关系；供应方负责询价、采购或制造能力。
源码中的 Context 承担运行期总控：定位根包、解析包路径、按需导入依赖、缓存已加载对象，并管理形状、测试和检查结果的缓存。依赖导入由不同工厂处理，本地目录、Git 仓库、tar 包及外部来源各有入口。包对象进入上下文后，调用者可按统一路径获取零件或装配，例如 //pub/std/metric/...:fastener。路径前半部分指向包，冒号后指向对象，这种寻址方式使跨仓库引用和包内引用保持一致。
执行层围绕几何加载器、脚本运行环境、接口配合、渲染器、导出器、测试器和供应方插件展开。CadQuery 与 build123d 脚本会在隔离的 Python 环境中准备依赖；OpenSCAD 走对应执行链；STEP、BREP、STL、3MF、OBJ 等文件经几何适配器进入统一形状表示。项目依赖 cadquery-ocp，位置与装配变换使用 OCCT Location，可见 Open CASCADE/OCP 是多类几何操作的共同底座。
交付层包括 PNG、SVG 预览，STEP、BREP、STL、3MF、OBJ、ThreeJS、GLTF、IGES 等导出，以及 Markdown/PDF 类文档、BOM、采购与制造信息。CLI 适合自动化，Python API 方便嵌入 CadQuery 或 build123d 脚本，VS Code 扩展提供保存即渲染和三维检查体验。各层之间依靠声明式对象和稳定路径衔接，团队可以替换局部建模工具，同时保留包与产品结构。
二、包管理：硬件复用的最小治理单元
一个 PartCAD 包可以只含单个 STEP 文件，也可以包含参数化零件、接口、子装配、制造要求和供应信息。包边界宜围绕可独立维护、可独立发布、拥有明确负责人和兼容策略的模块划分，例如标准紧固件库、电机模组、传感器支架、机柜结构或整机产品。
典型清单如下：
1 | name: //acme/robot/gripper |
本地依赖适合单仓库协作，Git 依赖适合组织级复用，tar 依赖适合不可直接访问 Git 的交付环境。Git 依赖支持 relPath，所以大型仓库里的某个子目录也能作为包导入。子目录若含 partcad.yaml，还可自动成为本地子包。
这套机制解决了“在哪里、叫什么、怎样加载”的问题。它尚未提供类似成熟语言生态的完整求解体验：官方文档强调 revision 可固定 Git 精确版本，但未展示统一锁文件、传递依赖冲突求解、制品签名、许可证策略或兼容性自动判定。因此生产项目应把 Git commit、签名 tag 或不可变归档摘要写入清单，并由 CI 检查浮动分支、校验远程文件哈希、生成依赖快照。包内的 partcad 版本约束和 pythonVersion 也应纳入发布门禁。
版本治理可采用三层标识。源码版次使用 Git commit，保证内容唯一；包发布版使用语义化版本或组织内部版次，表达兼容承诺；产品配置版记录顶层包及全部依赖的解析结果，保证整机可复现。三者应同时写入发布清单。仅记录顶层 tag 会留下隐患，因为依赖仓库可能仍指向分支，远程归档也可能被替换。
兼容规则最好按接口和行为定义。补充说明、预览图或测试通常可视为修订；增加带默认值的参数往往能够兼容旧调用；删除端口、修改坐标系、改变参数单位、替换材料或调整装配基准则可能破坏下游。CI 可以加载上一个发布版与候选版，比较对象列表、参数模式、接口端口、包围盒、质量属性和 BOM，再依据组织策略决定是否允许沿用次版本号。
包发布也应包含来源证明。建议为 partcad.yaml、脚本、外部模型、依赖快照和导出件计算 SHA-256，连同构建镜像摘要、执行命令及时间写入 manifest。对涉密项目，依赖下载应经过内部镜像；对开源部件，需保存许可证、作者、下载地址和修改记录。PartCAD 清单能够容纳说明和联系信息，但许可证合规与软件物料清单仍要由独立工具核验。
离线生产环境需要单独演练。Git、tar、Python wheel、OpenSCAD 可执行文件和 OCP 运行库都应提前镜像，CI 禁止临时访问公网。这样才能确认某个发布版在供应商现场、隔离网络或多年后的维修场景仍可构建。包管理的工程价值最终体现在可定位、可校验、可替换和可追责，而不只是一条远程 URL。
三、组件、接口与装配：几何树之外的连接语义
零件声明支持文件模型、Code-CAD 脚本、二维轮廓拉伸/扫掠，以及 AI 生成脚本。参数声明包含类型、枚举和默认值；使用对象时传入参数，会形成可复用的参数化变体。对于系列化支架、不同长度型材或标准螺钉，这比复制文件更适合版本管理。
装配采用 .assy YAML。文件是一棵节点树，节点可引用零件、子装配或容器，并可附带名称和位置。最直接的放置方式是写 OCCT Location：
1 | links: |
更有工程意义的是接口与端口。接口可以继承，可带多个端口，还能声明 moveX、turnZ 等配合参数。零件通过 implements 表示自己具备某种接口，装配用 connect 或 connectPorts 完成对接。螺栓孔阵列、NEMA 电机安装面、导轨滑槽、插接件等对象可将连接规则写入库中，减少每个装配重复计算坐标的工作量。
端口语义目前仍偏几何。工程现场还关心自由度、紧固扭矩、胶粘剂、线束弯曲半径、公差链、装配顺序、可达性和工装约束。团队可先把关键字段放入 requirements 或自定义元数据，再由外部检查器处理。不要仅凭三维位置吻合就判定装配可生产。
四、BOM 与产品结构：可计算的基础已经出现
PartCAD README 将参数化 BOM 和 Assembly YAML 自动维护 BOM 列为已支持能力。其逻辑基础很清楚：装配树中的每个零件与子装配都有稳定包路径、对象名、参数和出现次数，递归展开即可形成工程 BOM。参数化变体也能区分，例如同一种螺钉的 M4×20 与 M4×30 应作为不同配置行处理。
建议保留两种视图。其一是缩进式产品结构，用于设计审查、影响分析和装配导航；其二是扁平 BOM，按“包路径＋对象＋参数＋版本”聚合数量，用于采购和成本核算。外购件可在零件上记录 vendor、sku，制造件可记录 manufacturing.method、材料和颜色。provider 现有 store 与 manufacturer 两类：前者按供应商和 SKU 报价或下单，后者依据三维模型处理增材制造等请求。官方把 assembler 列为未来方向，说明整机装配执行链仍在建设。
企业 BOM 还需要位号、替代料、损耗率、单位、有效日期、批次、工厂、采购状态、成本、合规声明与更改单关联。PartCAD 的装配树可作为 eBOM 计算源，却不宜直接承担全部主数据职责。稳妥方案是定义映射层：PartCAD 对象路径映射 PLM 部件号，参数散列映射配置编码，Git commit 映射设计版次，导出的 STEP 与预览图作为受控附件，BOM JSON/CSV 经校验后写入 PLM。ERP 物料号和供应商料号继续由既有系统维护。
BOM 计算时要明确实例与物料的区别。装配中的 left-jaw、right-jaw 是两个实例，二者可能归并为同一物料行；若镜像加工、表面处理或参数不同，则应拆分。建议先生成实例表，包含父节点、实例路径、对象路径、参数、位姿和数量，再依据企业规则聚合物料表。这样既能支持三维定位，也能避免过早合并导致位号丢失。
产品结构还要处理虚拟件和集合件。用于组织装配树的容器未必对应库存物料；胶水、润滑脂、线缆扎带等耗材可能没有三维形状；软件、固件和 PCB 制造文件又可能需要进入综合 BOM。可在适配层定义 phantom、consumable、software、reference 等类别，并规定是否展开、是否计库存、是否上传几何附件。PartCAD README 提到机械、电子和软件 BOM 的方向，具体企业语义仍应由项目数据规范补足。
变更影响分析可以利用包图与装配树。某个标准接口或零件更新后，先查询所有引用它的包，再渲染受影响装配、比较质量属性和 BOM。若 PLM 已保存顶层产品与发布清单的关联，适配服务还能列出受影响产品版次、在制订单和维修备件。PartCAD 提供依赖和对象图的计算基础，业务范围判断则依赖 PLM/ERP 数据。
五、几何后端：统一入口下的能力差异
PartCAD 同时接纳 CadQuery、build123d、OpenSCAD、传统交换文件和 KiCad PCB。这种多后端策略适合现实团队：标准件可能只有 STEP，内部结构件使用 Python 参数化建模，外壳使用 OpenSCAD，电路板来自 KiCad。消费端可以统一执行 pc inspect、pc render、pc export，也可通过 Python API取得 CadQuery/build123d 对象。
统一入口不代表各后端行为完全一致。STEP/BREP 较适合精确边界表达；STL/OBJ 是网格，布尔运算、拓扑命名和尺寸提取能力有限；OpenSCAD 常经网格或外部进程；CadQuery/build123d 依赖 Python 环境与 OCP 版本；KiCad 模型还涉及板层、封装和外部三维模型路径。跨后端装配应尽早导出中性格式做回归验证，并记录质量、公差、颜色、坐标系和单位约定。
缓存可显著降低脚本模型重复编译成本，项目支持内存与磁盘缓存，代码 CAD 缓存仍被文档标注为实验特性。缓存键必须覆盖源码、参数、包版本、Python 依赖和后端版本，否则会出现旧几何误复用。涉及安全时也要谨慎：官方沙箱目前主要隔离 Python 依赖，文档明确说明更强的安全隔离仍属后续目标。第三方 CadQuery/build123d 包等同于第三方代码，应在容器、低权限账户、禁网环境中执行，并限制文件系统和密钥访问。
六、AI 与 Agent：生成可审查脚本，保留确定性交付
PartCAD 支持 Google Gemini、OpenAI 和 Ollama，可生成 ai-openscad、ai-cadquery、ai-build123d 类型的零件。描述、requirements 和参考图片进入提示上下文，生成结果持久化为 Python 或 CAD 脚本。工具会多轮尝试几何建模、脚本生成与错误修正，相关次数可在用户配置中限制。
这种设计的优点是输出仍可进入 Git diff、代码审查、测试和复现流程。AI 适合创建初始脚本、补充参数、搜索已有包、生成预览说明和辅助检查。Agent 工作流可设计为：读取需求；检索组织零件库；选择复用件；生成缺失结构件；执行脚本；渲染多视角图片；导出 STEP；检查包围盒、质量和接口；生成 BOM 差异；提交候选分支。任何失败都应带着日志和中间产物退出，禁止悄悄降低约束。
边界同样清晰。LLM 对尺寸、公差、材料、法规和制造可行性的判断缺少稳定保证；几何能够生成，也可能存在薄壁、自交、不可加工、干涉或载荷不足。AI 输出必须经过确定性门禁：脚本可重复执行、几何有效、尺寸符合规则、接口存在、装配无关键干涉、BOM 可追溯、敏感设计未发送给未经批准的云模型。私有项目可优先使用 Ollama 或企业托管模型，并关闭或自托管遥测。
七、CI 与 PLM 集成：把模型当成可构建制品
PartCAD 自身仓库的 GitHub Actions 展示了较完整的工程实践：Linux、Windows、macOS 多系统矩阵，多 Python 版本，pytest 单元测试，Behave 场景测试，示例包递归测试与渲染，VS Code 扩展测试，文档以 Sphinx 严格模式构建，随后验证 wheel 构建和安装。大型场景还采用分片、并发取消、缓存及测试报告上传。
业务仓库可采用更轻的门禁：
- 校验 YAML 语法、对象引用、依赖 revision 和远程文件摘要。
- 递归加载目标包，执行
pc test，并限制并发与超时。 - 渲染关键零件及总装，保存 PNG 供评审。
- 导出 STEP/3MF，检查文件存在、体积非零、包围盒在阈值内。
- 生成缩进 BOM 与扁平 BOM，同基线比较新增、删除、数量和参数变化。
- 把 Git commit、PartCAD 版本、后端版本、依赖清单写入制品元数据。
- 合并后发布不可变包引用，并将受控制品推送至 PLM 文档库或对象存储。
PLM 集成建议使用“PartCAD 负责工程定义，PLM 负责企业治理”的分工。适配服务监听合并或发布事件，读取包与装配，按映射表创建或更新部件、版次、BOM 行和附件。写入前先做 dry-run，输出变更集；写入后回读 PLM 编号和版次，保存到发布清单，避免在建模源码中散布数据库内部 ID。审批、签字、有效性、偏离许可和工厂视图保留在 PLM；PartCAD CI 只消费已批准状态或发布快照。
接口设计应保持幂等。一次发布拥有固定的 release ID，重复推送只能得到相同结果；附件上传前比对摘要；BOM 行使用稳定键；网络中断后可安全重试。PLM 写入失败时，不应把 Git tag 标记为已交付。可设置发布状态机：候选、验证通过、等待审批、已写入 PLM、已发布、已撤回，并保存每次 API 请求的审计摘要。
CI 还应区分快速检查与受控发布。拉取请求阶段运行清单校验、代表性渲染和轻量几何测试；夜间任务覆盖全部平台、全部示例和高成本转换；发布任务使用批准的容器镜像，生成签名制品并执行 PLM 同步。这样既能控制反馈时间，也能让正式交付具备更严格的环境与权限边界。
八、落地建议：先选一个产品族，建立可验证闭环
首个试点宜具备三项特征：零件数量在几十至几百之间；参数化复用价值明显；已有 STEP 或 Code-CAD 资产。可以选择机器人末端夹具、小型工装、模块化机柜或实验设备。先定义包命名、对象路径、坐标系、单位、参数命名、接口命名和版本规则，再迁移模型。
阶段一只做可重复加载、渲染与导出；阶段二加入装配接口和 BOM 差异；阶段三接入 CI、制品库和 PLM；阶段四再引入 AI 候选生成与供应方插件。每阶段都设置量化指标，例如冷构建时间、缓存命中率、装配引用失败数、BOM 人工修订行数、发布可复现率和 PLM 同步失败率。
还应提前建立升级策略。PartCAD 演进较快，官方文档中部分页面和 README 的能力状态存在时间差，仓库 CI 也持续调整 Python、OCP 与 build123d 组合。生产环境要固定 PartCAD CLI、OCP、建模后端和基础镜像，升级时用代表性产品包跑完整回归。若团队依赖网格转换、AI 生成、实验缓存或采购下单，需给这些路径单独设置功能开关和人工确认。
试点验收不能只看演示效果。至少选取一次依赖升级、一次零件参数变更、一次装配替换和一次 PLM 写入失败，验证回滚、审计、重试与差异报告。维护人员也应能依据发布清单在空白环境恢复整机模型，并解释每个 BOM 行对应的源码、几何制品和审批记录。完成这些演练后，平台才具备推广到更多产品线的条件。
PartCAD 当前最适合承担一层开放、可审计的工程自动化骨架：Git 保存定义，包路径建立复用关系，装配树计算产品结构，几何适配器连接多种 CAD 来源，CI 负责复现与验证，PLM 接收受控结果。把它放在合适的位置，团队可以逐步提高硬件设计的模块化和自动化水平，同时保留对成熟企业系统与专业工程判断的依赖。