FreeCAD MCP 源码拆解GUI 线程分发机制让 RPC 安全驱动 CAD 主线程【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcpFreeCAD MCP 是一个让 AI如 Claude通过 MCP 协议远程控制 FreeCAD 的服务端项目。它的核心难题在于RPC 请求运行在独立线程而 FreeCAD 的文档树和 3D 视图只允许主线程GUI 线程访问。本文拆解gui_dispatch模块的 GUI 线程分发机制——它如何让跨线程调用既安全又不卡死界面。为什么必须有 GUI 线程分发FreeCAD 基于 Qt其文档对象Document、场景图Coin3D都不是线程安全的在后台线程直接调用obj.Shape ...、doc.recompute()、doc.addObject()会与 GUI 线程产生竞态轻则状态错乱重则事件循环彻底卡死wedgeRPC 服务器从此不再响应。而 XML-RPC 服务器本身跑在 daemon 线程里见 rpc_server.py 中的start_rpc_server天然与 GUI 线程分离。所以 FreeCAD MCP 的设计原则是RPC 线程只负责收请求所有触碰 FreeCAD 的操作必须搬运到 GUI 线程执行。承担这项搬运工作的是 addon/FreeCADMCP/rpc_server/gui_dispatch.py。整体架构一个队列 一条 Qt 信号核心数据结构非常简洁组件位置职责_rpc_request_queue模块级queue.QueueFIFO 任务队列存放待搬运的闭包_WakeSignal继承QObject的信号桥RPC 线程emitGUI 线程收到信号后立即处理process_gui_tasks()500ms 心跳 信号唤醒在 GUI 线程中批量消费队列dispatch_to_gui()RPC 线程调用把任务包一层、入队、唤醒 GUI、同步等结果数据流大致如下入队dispatch_to_gui(task, timeout)把task包装成_wrapped()负责计时、记录健康状态、把返回值塞进专属响应队列放入_rpc_request_queue。唤醒通过_WakeSignal.wake()发出 Qt 信号。由于连接方式是QueuedConnection槽函数一定会在 GUI 线程的事件循环中执行——这是跨线程调度的安全通道。500ms 的QTimer.singleShot心跳则作为兜底防止信号丢失。执行process_gui_tasks()在 GUI 线程中循环消费队列逐个执行任务期间把鼠标换成等待光标、状态栏显示 MCP: processing…让用户直观感知 AI 正在操作。一个细节_WakeSignal必须在 GUI 线程创建init_waker从 RPC 线程 emit 却是安全的——这正是 Qt 信号机制跨线程的典型用法。每个调用一条专属响应队列dispatch_to_gui的返回值传递方式是本文值得学习的第一个设计点每次调用新建一个queue.Queue(maxsize1)作为响应队列而不是所有调用共用一个全局队列。好处很直接A 调用超时后它遗留的迟到响应不可能污染 B 调用的结果。配合threading.Event任务开始信号和一把状态锁超时、完成、取消三种情况之间的竞态都被显式处理——例如完成与超时同时发生时代码会先尝试get_nowait()捞一次结果再判定超时。两级超时预算排队时间不算执行账GUI 线程一次只执行一个任务后来的请求要 FIFO 排队。如果简单地从入队开始计时排在慢任务后面的调用会被误判超时。因此dispatch_to_gui把时间拆成两段queue_timeout排队预算从入队到任务真正开始的等待时间超时会取消任务但不会把分发系统标记为卡死。timeout执行预算从任务在 GUI 线程实际启动开始计时。这带来一个实际收益两个并发的execute_code调用各自拥有完整的执行预算第二个不会因为第一个慢而被冤枉成卡死。对应的客户端侧freecad_client.py 会把 socket 超时放宽到2 × timeout 30s保证两级预算都有足够余量。完整说明见 docs/execution.md 的 GUI dispatch timeouts 一节。卡死检测fail-fast 而不是无限等待一个已在 GUI 线程运行的任务无法被安全取消。如果它超过执行预算dispatch_health.py 中的DispatchHealth会把状态置为stuck之后新来的 GUI 调用立即失败返回GUI_DISPATCH_STUCK错误码不再傻等但已经排队的调用继续等待等卡住的任务结束后照常执行客户端可以随时用get_rpc_status查询当前是哪个操作在卡该接口完全不经过 GUI 线程所以卡死时也能诊断。测试文件 tests/test_gui_dispatch.py 用 Fake 的 Qt/FreeCAD 模块完整覆盖了这组行为卡死后新调用秒拒、已排队调用在解除卡死后恢复、执行预算不从入队时刻计时等。鼠标按钮守卫不打断你的 3D 拖动如果你正按住鼠标在视口里旋转模型此时 AI 的建模任务插队执行体验会很糟。process_gui_tasks每个 tick 先检查QApplication.mouseButtons()有按键按下 → 跳过本 tick推迟到下个心跳但推迟最多 5 秒MOUSE_DEFER_MAX_SQt 偶发丢失鼠标释放事件例如在窗口外松手若无限推迟RPC 服务器会永久停摆超时后强制处理任务并在 FreeCAD 控制台打印一次警告。弹窗、右键菜单、模态对话框打开时同样会推迟分发且每次推迟的原因_last_defer都会被记录——超时错误信息会直接告诉用户GUI 线程没处理任务的原因3D 导航拖动中而不是抛出一个莫名的 timeout。实战启动 RPC 服务器并观察状态栏安装 addon 后在 FreeCAD 中切换到MCP Addon工作台addon/FreeCADMCP/InitGui.py 定义点击工具栏的Start RPC Server。启动逻辑在 rpc_server.py 的start_rpc_server()中绑定端口默认 9875→init_waker()创建唤醒信号 → 启动 500ms 心跳 → 启动 RPC 线程。注意状态栏底部的 RPC Server started at 127.0.0.1:91757——这就是分发桥已经就绪的信号。当 AI 提交任务时你会看到鼠标变成等待光标、状态栏显示 MCP: processing…而如果你正在拖动 3D 视图任务会自动礼让。关键源码导读想深入阅读建议按这个顺序addon/FreeCADMCP/rpc_server/gui_dispatch.py —— 模块顶部 30 行 docstring 就是一份 7 条的健壮性保证清单逐条对照源码看即可addon/FreeCADMCP/rpc_server/dispatch_health.py —— 仅 100 行的健康状态机healthy / busy / stuck三态addon/FreeCADMCP/rpc_server/rpc_server.py —— 所有 RPC 处理器如何调用dispatch_to_gui以及execute_code_async如何通过commit()助手把文档写操作交还 GUI 线程tests/test_gui_dispatch.py —— 不依赖真实 FreeCAD 的纯单元测试展示了如何 Fake 掉 Qt 来测试分发逻辑。总结FreeCAD MCP 的 GUI 线程分发机制用一个小模块解决了一个大工程问题跨线程调用 CAD 主线程的完整生命周期管理。它的几个核心取舍值得借鉴信号 心跳双通道唤醒兼顾实时性与可靠性每调用独立响应队列从结构上杜绝超时污染⏱️排队/执行两段预算慢任务不连累排队的请求stuck 状态 fail-fast卡死时快速失败 可诊断而非无限等待️有界鼠标守卫礼让用户交互但绝不被陈旧输入状态卡死。对任何需要后台线程安全驱动 GUI 应用的项目不限于 CAD这套模式都是一个很好的参考模板。【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考