过去一段时间，我一直在做一个三轴云台。

它看起来只是一个小机构，但实际做起来很容易把人折磨到怀疑人生：pan、pitch、roll 三条轴要尽量正交，还要尽量共点；结构件要能 3D 打印；舵机、相机、连接件都要装得上；最后还要真的能转、能调、能验证。

这类项目最难的地方，不是画出一个“看起来像云台”的模型，而是不断回答一些非常具体的问题：

• 这三条轴线到底有没有交在一起？

• 装配约束是不是还有效？

• 某个零件被拖歪了，还是 sketch 本身就错了？

• mate connector 的方向对不对？

• 手动调整之后，误差是变小了，还是只是肉眼感觉变好了？

如果每次都只靠眼睛看 CAD 界面，AI 很难真正帮上忙。
如果只靠代码生成 STEP，又会丢掉装配约束、mate、求解器状态这些真实 CAD 里最关键的信息。

所以我最近尝试了一套新的工作流：让 Codex / Claude 能读 CAD、写 CAD、生成检查报告，同时保留人在 Onshape 页面里直接操作模型的能力。

这件事的目标不是让 AI “凭空画一个模型”，而是让 AI 真正进入 CAD 工程回路。

为什么我选 Onshape

我现在越来越觉得，Onshape 最大的价值不是“在线版 SolidWorks”，而是它天然适合被 AI 接入。

它是云原生 CAD。模型在浏览器里打开，Mac、Windows、Linux、iPad 上看到的都是同一个状态。模型会自动保存，版本和分支也在云端管理。

这件事对 AI 工作流非常关键。

传统桌面 CAD 的状态，往往锁在本机软件、安装环境、插件版本、文件路径和当前 UI 里。你想让 AI 参与进来，就要先解决一堆“它怎么读取当前模型”的问题。

但 Onshape 不一样。一个 CAD 文档天然有 document id、workspace id、element id。也就是说，一个页面链接本身就可以拆成机器能识别的坐标：

https://cad.onshape.com/documents/{did}/w/{wid}/e/{eid}

对人来说，这是一个 CAD 页面。
对 AI 来说，这是一个可以通过 API 访问的工程状态。

这就很有意思了。

AI 不必隔着截图猜“这个零件大概在什么位置”，而是可以直接问 CAD 系统：

• 这个文档里有哪些 element？

• 哪些是 Part Studio？

• 哪些是 Assembly？

• feature tree 里有哪些建模特征？

• 某个 mate connector 在世界坐标下的位置和方向是什么？

• 装配里有哪些 fastened mate、revolute mate、grounded body？

这比让 AI 看图猜测要可靠得多。

Onshape 不只是能导入导出 STEP。它有 REST API，有 FeatureScript，有 Assembly mate 信息，也有版本和分支机制。对于 Codex / Claude 这类擅长读写文本、JSON、API、脚本和报告的 agent 来说，这种结构非常友好。

这也是为什么很多 AI-CAD 和机器人项目会选择 Onshape 或 FeatureScript。比如 CADFS 使用 FeatureScript 表示真实 CAD 建模历史；Claude / MCP 生态里已经有 shapecraft 这类直接驱动 Onshape 的工具；机器人侧也长期有 onshape-to-robot，把 Onshape 装配导出为 URDF、SDF 或 MuJoCo。

它们看中的不是“网页 CAD”这个外壳，而是 Onshape 背后那套可读、可写、可版本化的数据结构。

为什么不只用 CadQuery / build123d

我并不是不用代码 CAD。

事实上，在早期结构探索阶段，CadQuery / build123d 非常好用：参数集中管理，几何体可复现，快速生成 STEP，适合做第一版零件。

比如支架大概多宽、孔位在哪里、壁厚多少、舵机包络怎么避让，这些都很适合用代码生成。

但项目一旦进入装配阶段，纯代码 CAD 的短板就会很明显。

第一，装配语义不够

三轴云台真正要验证的，不只是某个零件的几何形状，而是整套机构的装配关系：

• pan 轴在哪里？

• pitch 轴在哪里？

• roll 轴在哪里？

• 三条轴是否正交？

• 三条轴是否尽量共点？

• 哪些零件是 fastened？

• 哪些关节是 revolute？

• 哪个 body 被 ground？

• solver 解出来的世界位姿是否符合预期？

CadQuery / build123d 擅长生成几何，但不擅长承载 Onshape 这种交互式装配求解状态。

代码能生成零件，不代表装配真的能装。

第二，AI 容易局部正确、整体错误

让 Codex 写一个支架、一个孔位、一个倒角，通常效果不错。
但让它凭空维护一整套舵机装配、转轴共点、相机姿态、干涉关系和装配约束，反馈环就太慢了。

很多时候代码是能跑的，STEP 也是能导出的，但导入 CAD 后一看：

• 轴线偏了；

• 孔位不对；

• 零件姿态错了；

• 装配约束接不上；

• 局部看合理，整体完全不对。

这就是代码 CAD 在真实机械装配里容易遇到的问题。

第三，真实 CAD 仍然需要人工判断

比如一个 mate 应该选哪个面，一个舵机初始姿态是否合理，某个连接件是不是方便装配，拖动机构后运动是否符合直觉。

这些事情在 Onshape UI 里非常自然。

你可以直接拖、转、选面、重建 mate connector、观察装配求解结果。
如果全部抽象成 Python 代码，反而会变成一套很脆弱的间接表达。

所以我现在更倾向于分层使用：

代码 CAD 负责快速生成初始零件；
Onshape 负责真实装配、约束、版本、协作和可视检查；
Codex / Claude 负责读写 API、做几何审计、生成修改建议和报告。

这样各自发挥长处，而不是硬让某一个工具包办所有事情。

为什么不只用 SolidWorks / Fusion 360

SolidWorks 和 Fusion 360 都是很成熟的 CAD。单论建模能力，它们当然很强。

但如果目标是让 AI 稳定进入工程回路，它们并不是最顺手的选择。

SolidWorks 的强项在本地桌面和企业工程环境，但它的代价也很明显：安装、授权、Windows 环境、插件接口、文件管理都更重。AI 可以通过脚本或宏去操作它，但很难做到“一个 URL 就是当前真相”。

Fusion 360 云属性更强，也有 API，但它仍然不是 Onshape 这种从底层就围绕浏览器、数据库、文档分支、REST API 设计出来的系统。

对于 Codex / Claude 这种 agent 来说，Onshape 的摩擦更低。它更像一个可以被程序访问的 CAD 状态机，而不只是一个 CAD 软件。

这不是说 SolidWorks / Fusion 360 不好。
而是在这个场景里，最重要的不是最强的单机建模器，而是一个 AI 能稳定接入、用户也能随时介入的 CAD 环境。

我的实际工作流

我现在的工作流大概是这样的：

用户在 Onshape 页面里做直觉操作
AI 通过 API 读取精确状态
AI 给出诊断和最小修改建议
用户确认或手动调整
AI 再验证、写报告、沉淀脚本

这套流程里，我封装了一个内部 CLI，用来把 Onshape 的文档状态读出来，并转换成 AI 更容易处理的信息。

目前它主要做几类事情。

1. 读取文档和元素信息

比如读取当前文档信息，列出里面的 Part Studio、Assembly、Blob、BOM 等 element。

这样 AI 不是在猜“这个模型里有什么”，而是能直接拿到结构化信息。

2. 读取 Part Studio 的 feature tree

Part Studio 里有哪些 sketch、extrude、fillet、boolean、derived part，都可以被读取出来。

这对排查问题很有用。

很多时候一个模型错了，不是最后的实体错，而是某个历史 feature 已经过期、引用断了、或者某个 sketch 约束没有闭合。

3. 计算零件包围盒

通过 Onshape 的 evalFeatureScript，可以跑一个 bbox 检查脚本，拿到零件的包围盒。

这对机械设计非常实用。比如我可以快速检查：

• 舵机外壳包络有没有超出预期？

• 相机安装座有没有挡住旋转空间？

• 某个连接件是不是侵入了预留区？

• 零件整体尺寸有没有异常？

这比肉眼看模型稳定得多。

4. 导出 STEP

STEP 导出仍然很重要。
因为最终 3D 打印、仿真、外部检查，还是经常要用 STEP 作为中间格式。

但区别在于：STEP 不再是唯一真相。
它只是 Onshape 工程状态的一个输出结果。

5. 生成 Markdown 报告

每次检查后，AI 可以把文档信息、元素列表、feature 状态、bbox、STEP 导出结果串成一份报告。

这样每次修改不是“改完就忘”，而是有记录、有结论、有下一步建议。

对机械迭代来说，这个非常重要。否则过几天回头看，很容易忘记当时为什么这么改。

6. 检查装配轴线

对三轴云台来说，最有价值的是轴线检查。

Onshape Assembly 不能像 Part Studio 那样直接跑 FeatureScript，所以我把 Assembly 里的两类信息组合起来解析：

occurrence transform
+ mateConnectorCS
= mate connector 的世界坐标系

这一步很关键。

因为它让 AI 不再需要看截图猜轴线，而是能直接得到毫米级数据：

• 某条轴经过哪个点；

• 方向向量是多少；

• 它离 assembly origin 多远；

• 它和另外两条轴是否正交；

• 三条轴是否近似共点。

也就是说，过去靠肉眼判断的问题，现在可以变成一组明确的几何计算。

一个真实例子：三轴云台轴线检查

以我当前这个三轴云台为例，主装配里有几个核心 element：

• Feetech STS3032-C036；

• Feetech STS3032-C001；

• 相机模型；

• 相机安装座；

• pan-pitch 连接件；

• pitch-roll 连接件；

• 轴线辅助 Part Studio；

• 主 Assembly。

我用 CLI 对当前 workspace 做了一次轴线检查，结果大概是这样：

mc_pan
origin = (0.000, 0.000, -45.199) mm
z = (0, 0, 1)
d to O = 0.0000 mm

mc_pitch
origin = (-70.596, 3.161, 0.201) mm
z ≈ (-0.999, 0.045, 0)
d to O = 0.2010 mm

mc_roll
origin = (0.943, 21.066, 0.201) mm
z ≈ (-0.045, -0.999, 0)
d to O = 0.2010 mm

这组数据说明什么？

第一，pan、pitch、roll 三条轴的方向已经基本正交。
第二，pan 轴已经过 assembly origin。
第三，pitch 和 roll 也基本在同一个平面里，但它们相对 assembly origin 还有大约 0.201 mm 的 Z 向残差。

这个结果如果只靠肉眼看，是很难稳定判断的。
但对 CLI 来说，它只是一次 API 读取和线-点距离计算。

接下来要判断的就不是“看起来正不正”，而是一个工程问题：

这个 0.201 mm 是有意保留的装配余量？
还是应该继续调整 mate offset / connector，让三条轴进一步共点？

这就是 AI 接入 CAD 之后最有价值的地方。
它不替你做工程判断，但它能把模糊感觉变成可验证的数据。

人和 AI 应该怎么配合

我现在越来越不相信“AI 全自动画 CAD”这件事，至少在真实机械项目里不太现实。

更有效的方式是：人负责工程直觉，AI 负责精确读取和反复验证。

人适合做这些事：

• 判断结构是否合理；

• 在 Onshape 里直接拖动机构；

• 选择合适的 mate connector；

• 观察运动是否符合直觉；

• 判断某个误差是否可以接受；

• 决定下一步设计方向。

AI 适合做这些事：

• 读取 CAD 当前状态；

• 检查轴线、包围盒、feature tree；

• 找出残留 mate 和异常引用；

• 生成最小修改建议；

• 调用 API 修改参数；

• 导出 STEP；

• 生成结构审查报告；

• 对比修改前后的几何误差。

这两者结合起来，反馈环会明显变短。

过去我可能要在 CAD 页面里反复看、反复拖、反复猜。
现在可以让 AI 直接告诉我：哪条轴偏了多少，哪个 connector 的方向不对，哪个 mate 可能是历史残留。

用户不用把 CAD 里的每一步都翻译成代码。
AI 也不用隔着截图和自然语言猜模型状态。

页面操作提供工程直觉，API 读写提供可验证事实。

这套方法真正改变了什么

以前做 AI-CAD，很多时候会停在“生成一个模型文件”。

比如让 AI 生成一个 STL、一个 STEP、一个 CadQuery 脚本。
这当然有用，但它离真实工程还有距离。

真实机械项目里的核心问题往往不是“有没有一个模型”，而是：

• 这个 mate 还约束真实零件吗？

• 这个轴线到底有没有过原点？

• 这个 STEP 是当前几何，还是历史导出文件？

• 手动拖动之后，误差变大还是变小？

• API 改了一个参数后，CAD solver 真的接受了吗？

• 这次修改有没有破坏其他约束？

• 这个零件到底能不能装、能不能转、能不能打印？

Onshape + Codex / Claude 的意义，就是把这些问题变成可查询、可复现、可写入报告的工程事实。

AI 的长处是读代码、写脚本、调 API、总结差异。
人的长处是看机构、判断意图、做高带宽交互。
把两者放到同一个云端 CAD 文档上，工作流就不再是“AI 替我画图”，而是“AI 进入我的工程回路”。

这对我来说是一个很大的变化。

CAD 仍然是 CAD。
工程判断仍然在人手里。
但 AI 第一次真正站在 CAD 文档内部工作。

后面还想继续做什么

短期，我想把几个高频操作继续工具化。

比如做一个 patch-mate 命令，把 mate offset 修改变成可审计操作。
再做一个 ground 命令，把“用指定 mate connector 接地到 assembly origin”沉淀成稳定流程。
还可以做一个 axes-fix-suggest，自动给出让所有 mc_* 轴线尽量过 origin 的最小修改建议。

中期，我想把变量写入也接进来。

如果 Onshape 的 Variable Studio / Part Studio 变量可以被 CLI 安全修改，那么 AI 就能从“诊断装配”进一步走向“参数化改型”。

比如自动调整：

• 孔距；

• 壁厚；

• 舵机安装高度；

• 相机光心偏移；

• 连接件厚度；

• 线缆预留空间；

• 打印公差。

然后重新导出 STEP，重新跑检查，再生成报告。

长期看，最值得做的是一个完整的 guarded edit loop：

建分支
读取状态
提出修改
写入 Onshape
重建并验证
生成报告
由用户决定 merge 或丢弃

这会让 AI-CAD 从“一次性生成”，变成真正适合工程迭代的工作流。

它不追求完全替代 CAD 工程师。
更现实、也更有价值的方向，是让每一次页面操作、每一次 API 写入、每一份验证报告，都接在同一条链路上。

对我来说，这才是 Onshape + Codex / Claude 最有意思的地方：

人仍然做工程判断，CAD 仍然负责几何和约束，AI 则负责把大量重复、精确、可审计的检查工作接起来。

这不是“AI 画了一个模型”。
这是 AI 终于开始进入真实机械设计流程。

参考资料

• Onshape Getting Started：https://cad.onshape.com/help/Content/getting-started.htm

• Onshape REST API Introduction：https://onshape-public.github.io/docs/api-intro/

• Onshape FeatureScript Documentation：https://cad.onshape.com/FsDoc/index.html

• CADFS: A Big CAD Program Dataset and Framework for Computer-Aided Design with Large Language Models：https://arxiv.org/abs/2605.01925

• CADFS Dataset：https://huggingface.co/datasets/VladPyatov/CADFS

• shapecraft: Craft real CAD with Claude：https://pypi.org/project/shapecraft/

• onshape-to-robot documentation：https://onshape-to-robot.readthedocs.io/en/stable/