FreeCAD MCP 三种执行模式怎么选？execute_code / async / headless 终极对比-拓冰网站定制

FreeCAD MCP 三种执行模式怎么选？execute_code / async / headless 终极对比

【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp

FreeCAD MCP 是一个让 Claude Desktop 等 AI 助手直接操控 FreeCAD 的 MCP（Model Context Protocol）服务器，可以建模、跑 Python 脚本、查看文档、执行 FEM 分析。它的代码执行能力分为三种模式：execute_code、execute_code_async（异步）和execute_code_headless（无头模式）。本文帮你在 1 分钟内搞清楚三者的区别，并给出直接的选择建议。

30 秒快速决策：选哪个执行模式？

模式	运行位置	适合的任务	时间预算
`execute_code`	FreeCAD GUI 主线程	常规建模、编辑对象、截图反馈	默认 90 秒，可调到 1800 秒
`execute_code_async`	后台工作线程	长时间、独立的几何计算	返回`job_id`，轮询状态
`execute_code_headless`	独立的`freecadcmd`进程	可能让 OCCT 崩溃的重载操作	默认 600 秒

一句话决策：常规操作选execute_code；跑几分钟且只算几何、不碰界面选 async；怕把 FreeCAD 搞崩的"危险任务"选 headless。

共同前提：先启动 RPC 服务器

三种模式都跑在已连接的 FreeCAD 之上。安装好附加组件并重启 FreeCAD 后，从工作台列表选择MCP Addon：

再在FreeCAD MCP工具栏点击Start RPC Server，状态栏显示监听地址（默认127.0.0.1:9875）即启动成功：

详细步骤见安装指南。

模式一：execute_code —— 默认首选，直接跑在 GUI 线程

execute_code是最常用的执行模式，脚本直接在 FreeCAD 的 GUI 线程上运行，因此它可以直接读写文档、操作视图并返回截图，是普通建模任务的默认选择。

适用场景🖥️

创建/修改/删除对象、导入导出模型
需要即时看到效果的交互式建模（如演示图中的法兰）
运行 FEM 悬臂梁示例这类标准脚本

关键机制：

共享脚本状态：execute_code与 async 共享一个持久脚本命名空间（内置FreeCAD/FreeCADGui别名），变量在多次调用之间保留，无需每次重新定义
超时预算：队列等待与执行各有 90 秒预算；耗时更久的 GUI 任务可传入timeout（正数、上限 1800 秒），客户端会自动放宽套接字超时
卡死恢复：GUI 任务一旦开始就无法取消。若任务超时卡住，桥接层返回GUI_DISPATCH_STUCK，可另开一个客户端用get_rpc_status诊断，仍不恢复则重启 FreeCAD

完整规则见代码执行文档。

模式二：execute_code_async —— 长耗时后台计算与任务跟踪

当几何计算要跑几分钟，又不想阻塞 GUI 时，用execute_code_async。它把脚本丢到独立的工作线程，立即返回一个job_id：

用get_async_status(job_id)查询任务是running、done还是failed，失败时附带异常和堆栈；不带参数可查看全部任务历史
工作线程里构建独立的 OCCT 几何，再用commit(fn, timeout=120)回到 GUI 线程应用结果并重算文档
与execute_code共享持久脚本命名空间，之前定义的变量可以直接复用

适用场景⚡

只涉及几何、不碰文档和视图的纯计算：扫描、放样、批量布尔
可以"提交后先去干别的"的批处理型建模

像下面这类带复杂轮廓的零件，建模过程往往就是典型的长耗时几何任务：

模式三：execute_code_headless —— 崩溃隔离的独立进程执行

execute_code_headless是"保险箱"模式：脚本被写入临时文件，用freecadcmd -c在单独的进程中执行。螺旋扫掠（makeHelix+makePipeShell）、复杂放样、带大量 B 样条的布尔运算这类操作可能让 OpenCascade 段错误——在 GUI 进程里跑会连同所有未保存文档一起崩溃，而在无头进程里崩溃只会结束辅助进程，工具会报告信号（如SIGSEGV）和脚本全部输出，GUI 安然无恙。

使用注意🛡️

脚本要自己管理文档：自行FreeCAD.openDocument创建、doc.save()或Shape.exportBrep导出；保存了 GUI 中打开的.FCStd后，用reload_document刷新界面副本
可执行文件在MCP 服务器所在机器上运行，文件路径必须是该机器可访问的；--host参数只影响 GUI RPC 连接
freecadcmd自动检测（PATH 或 Flatpak），也可用--freecadcmd参数显式指定

实现逻辑可参考 headless 执行器源码，工具注册见 MCP 服务器源码。

常见坑位 FAQ

问：async 脚本里能直接改文档吗？不能。文档和视图访问必须留在 GUI 线程，用commit()把最终函数提交过去。

问：execute_code 超时了怎么办？任务无法取消，结果会被丢弃但计算仍在跑。耗时任务请显式传timeout；纯几何计算请改用execute_code_async。

问：headless 结果和 GUI 里的文档不一致？无头脚本运行在新进程中，不与 GUI 共享脚本状态和文档，保存后用reload_document同步即可。

问：脚本变量在多次调用之间丢了吗？execute_code和 async 共享持久命名空间，变量会保留；headless 每次都是全新进程，不会保留。

资讯详情

FreeCAD MCP 三种执行模式怎么选？execute_code / async / headless 终极对比