From 1dec459be97fa21508223566b8d68ffc3ea427d5 Mon Sep 17 00:00:00 2001 From: company-desktop-computer Date: Wed, 28 Oct 2026 23:20:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=20cad=5Fmcp=5Fframe?= =?UTF-8?q?=20=E7=9A=84=E7=A7=BB=E6=A4=8D=E8=AF=B4=E6=98=8E=E4=B8=8E?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E5=AE=A1=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移植已完成(R230 ARX + Z2026 ZRX 均编译通过并部署),本文记录: - 移植做了哪些改动(cadsdk.h->KTCad.h、两个单头依赖、SUB_ARX、中望 .def 与版本号函数) - C++11+ 限制:R180/R190 是 C++98,无法编译 nlohmann/json,故按 preset 条件跳过 - 架构:后台线程收包 -> PostMessage -> 主线程执行,工具调用全在主线程,避开了跨线程访问数据库 - 问题清单(按严重度): P0 收包只 recv 一次、缓冲固定 2048:大报文截断、TCP 分包即失败,且没有长度前缀 P0 bytesReceived<=0 时 socket 泄漏 P1 socket/bind/listen 返回值全未检查,端口占用时静默失败但 g_bRunning 仍为 true P1 无鉴权:本机任意进程都能调用会改图的工具 P1 端口 8080 硬编码;代码找 mcp_config.json 而仓库里是 cad-mcp-frame.json P2 卸载时挂起的 PostMessage 任务不释放;LISP 工具是异步 fire-and-forget 无结果回传; 加载期弹 AfxMessageBox 会卡住 CAD 启动;g_hMsgWnd 无同步; .def 的 LIBRARY 名与实际输出不一致;/Zc:forScope 语义与 code2026 全局设置相反 - 移植后仍需处理:统一配置文件名、移植 cad_mcp_plugins、带上 lisp 目录、在 CAD 里实测 --- cad_mcp_frame-review.md | 194 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 cad_mcp_frame-review.md diff --git a/cad_mcp_frame-review.md b/cad_mcp_frame-review.md new file mode 100644 index 0000000..59478e7 --- /dev/null +++ b/cad_mcp_frame-review.md @@ -0,0 +1,194 @@ +# cad_mcp_frame 移植与代码审查 + +> 源工程:`d:\new-start\CadProject\src\cad_mcp_frame`(vcpkg 构建,独立 CMake 工程) +> 目标:整合到 `SourceCode/Code2026` 下,走 code2026 的 preset / CMake 体系 +> 结果:**R230 Debug 编译通过并自动部署** + +## 1. 移植做了什么 + +| 项 | 处理 | +| --- | --- | +| 源码 | 12 个 cpp/h + `.def` + `.rc` + `res/` + `cad-mcp-frame.json` 拷到 `SourceCode/Code2026/cad_mcp_frame/` | +| 插件接口头 | `mcp_plugin_api.h`(原在 `CadProject/inc/`)放到 `cad_mcp_frame/inc/` | +| `cadsdk.h` | 改为 `#include "KTCad.h"`(两者除尾部 4 个 include 与 `using namespace MemOper` 外完全一致) | +| `nlohmann/json` | 单头下载后放 `SourceCode/dep_inc/nlohmann/json.hpp`(仓库已跟踪 `dep_inc/`,与 `rapidjson` 同级) | +| `ghc::filesystem` | 单头放 `SourceCode/dep_inc/ghc/filesystem.hpp` | +| 头文件路径 | `target_link_objectarx()` 已把 `${DEP_INC_ROOT}` 加进 include,故 ``、`` 直接可用 | +| `SUB_ARX` 宏 | 原工程由 CadProject 的 cmake 注入;code2026 只注入 `ARX`。在模块自己的 CMake 里补 `SUB_ARX=${CAD_SDK_SUBVERSION}`(中望给 0),不动共享的 `functions.cmake` | +| CMake | 新增 `cad_mcp_frame/cmakelists.txt`,按 `PipeHangerCmd` 的写法:`add_def_file_name` / `target_set_name_and_suffix(... ".arx")` / `target_link_objectarx(CADMCPFRAME_EXPORT)` / `set_debug_post_build` | +| 顶层挂载 | `add_custom_module_2(cad_mcp_frame CadMcpFrame "SH/Other")` | +| ZRX `.def` | 中望要导出 `zcrxEntryPoint` / `zcrxGetApiVersion`(ARX 下 `acrxEntryPoint` 被 SDK 宏改名,`def` 里必须写 zcrx 名) | +| ZRX 版本号函数 | 代码里显式声明的 `acrxGetApiVersion()` 不会被宏改名,中望下未解析。改为按平台取 `zcrxGetApiVersion()`(`#ifdef ZWCAD`) | +| 编码 | 全部 `.cpp/.h` 规整为 UTF-8 with BOM(仓库红线) | + +## 2. 一个必须知道的限制:C++11+ + +`nlohmann/json` 与 `ghc::filesystem` 都需要 **C++11 以上**,而 code2026 的 +`R180/R190` preset 是 **C++98**(`CAD_SDK_VERSION < 20`)。因此在顶层加了条件挂载: + +```cmake +if (IS_ZWCAD OR CAD_SDK_VERSION GREATER_EQUAL 20) + add_custom_module_2(cad_mcp_frame CadMcpFrame "SH/Other") +else() + message(STATUS ">>> 跳过 cad_mcp_frame:需要 C++11+(当前 preset 为 C++98)") +endif() +``` + +**后果:本机习惯用的 R190 编不出这个模块。** 要调试它请用 R200 以上(用户日常用 R230)。 +中望的现代 SDK 都是 C++14,不受影响。 + +已实际验证的平台: + +| preset | 结果 | +| --- | --- | +| **R230**(AutoCAD 2020,C++14) | ✅ 编译通过,`cad_mcp_frame.arx` 818 KB,已自动部署 | +| **Z2026**(中望 2026,C++14) | ✅ 编译通过,`cad_mcp_frame.zrx` 818 KB,已自动部署 | +| R190 / R180(C++98) | ⏭ 按条件跳过(见上) | + +## 3. 工程结构与架构 + +``` +cad_mcp_frame.cpp 标准 ARX 入口:kInitAppMsg → init_mcp_server();kUnloadAppMsg → close_mcp_server() +mcp_server.cpp TCP 服务端(后台线程)+ JSON-RPC 2.0 分发 + 主线程投递 +mcp_ConfigParser.cpp 读 JSON 配置,按 backend.type 生成工具 +mcp_tool.cpp 三种工具实现:lisp_inline / lisp_file / c++_dll +mcp_utils.cpp 路径与环境(ghc::filesystem) +inc/mcp_plugin_api.h mcp_Tool 基类 / mcp_Tools 注册表 / 响应构造辅助 +cad-mcp-frame.json 工具清单(18 个:16 个 c++_dll + 2 个 lisp_inline) +``` + +**线程模型**(设计上是对的): + +``` +LLM/客户端 --TCP 127.0.0.1:8080--> 后台线程 select() 收包 + | + | PostMessage(WM_MCP_EXECUTE_TASK, pTask) + v + 主线程的 message-only 窗口 → ExecuteTaskInMainThread() + | + +-- tools/list : g_mcpTools.ToLLM() + +-- tools/call : g_mcpTools.Call(...) + | + +-- send() 回写响应 +``` + +调用 AutoCAD/AecRxBase 的部分全在主线程执行,避开了跨线程访问数据库的坑,这点值得保留。 + +**插件机制**:`c++_dll` 工具会 `LoadLibrary` 插件 ARX,用 `acrxGetApiVersion()` 比对版本, +用 `CreateTool`/`DestroyTool` 做对象生命周期,并用 `mcp_Tool_DllProxy` 的析构做 RAII +(通知 DLL 释放 + `FreeLibrary`)。设计合理。 + +## 4. 问题清单 + +### P0:请求会被截断 / 分包即失败 + +```cpp +char recvBuf[2048] = { 0 }; +int bytesReceived = recv(clientSocket, recvBuf, sizeof(recvBuf) - 1, 0); +if (bytesReceived > 0) { pTask->rawJson = recvBuf; ... } +``` + +- 只 `recv` **一次**,缓冲固定 2048:**超过 2047 字节的 JSON 直接被截断** → + 客户端收到 `Parse error`。MCP 的 `tools/call` 参数多时很容易超。 +- 没有长度前缀(`Content-Length`)或行分隔符约定:**TCP 分包时必然解析失败** + (大报文几乎一定分包)。 +- 建议:`Content-Length: N\r\n\r\n{...}` 或 `\n` 分隔 + 循环 `recv` 拼到完整一帧; + 缓冲改成 `std::string` 动态追加,并加上报文大小上限。 + +### P0:Socket 泄漏 + +`bytesReceived <= 0`(客户端关闭/半关闭)时不走任何分支,**既不 `closesocket` 也不 delete `pTask`**。 +建议 `else { closesocket(clientSocket); }`,并在 `accept` 失败分支去掉对 `INVALID_SOCKET` 的 `closesocket`。 + +### P1:监听失败是静默的 + +`socket/bind/listen/WSAStartup` 的返回值**全未检查**。端口 8080 被占用时: +`bind` 失败 → `listen` 失败 → `select` 空转,但 `g_bRunning` 仍是 `true`, +`init_mcp_server()` 照样返回成功,CAD 里还打印"listening thread started"。 +建议逐个检查并在失败时置 `g_bRunning=false` + `acutPrintf` 说明原因(端口占用是最常见故障)。 + +### P1:没有任何鉴权 + +只绑 `127.0.0.1`(好),但**本机任意进程都能连上来调用工具**,而这些工具会 +直接操作当前图纸(画图、炸开、修改)。建议: +- 启动时生成随机 token 写入 `%TEMP%`,客户端在首帧 `Authorization` 里带上; +- 或只允许配置文件里登记的 PID/路径。 + +### P1:端口与配置文件写死 + +```cpp +#define MCP_SERVER_PORT 8080 +#define MCP_SERVER_CONFIG _T("mcp_config.json") +``` + +- 端口没有配置项,与本机其它服务冲突概率不低(本项目 `netstat` 里就有 8731、5040 等占用)。 +- 代码找的是 **`mcp_config.json`**,而仓库里带的是 **`cad-mcp-frame.json`**; + 两者不一致时 `LoadAndRegister()` 返回 false → 服务直接自关。 + 移植后要么改文件名,要么加配置项,**否则加载即失败**(本次未改,见 §6)。 + +### P2:卸载时可能漏释放挂起的任务 + +`close_mcp_server()` 里 `DestroyWindow(g_hMsgWnd)` 会丢掉尚未处理的 +`WM_MCP_EXECUTE_TASK`,对应 `TaskData*`(以及其中的 socket)不会释放。 +建议在销毁窗口前 `PeekMessage` 排空该消息并 delete,或改用 `std::vector` 托管。 + +### P2:LISP 工具是"发射后不管" + +```cpp +acDocManager->sendStringToExecute(acDocManager->curDocument(), finalScript.c_str()); +return mcp_Tool_Utility::make_text_result(L"LISP inline command issued for execution (asynchronous)"); +``` + +永远返回"已下发",LLM 不知道执行成功还是失败,也拿不到任何数据。 +如果工具语义需要结果(例如"取选中对象信息"),应改成同步执行并回传结果。 + +### P2:加载期弹 `AfxMessageBox` + +配置/插件目录不存在、插件版本不匹配时用 `AfxMessageBox` 提示。问题: +- ARX 加载是被 AutoCAD 启动流程调用的,**模态框会卡住启动**(脚本化部署/CI 里直接挂死); +- 弹窗内容多为英文,且提示后仍继续加载,行为不明确。 +建议统一改成 `acutPrintf` 输出(需要人看的才用弹窗),并把致命错误做成"明确失败"。 + +### P2:`g_hMsgWnd` 无同步 + +主线程写、后台线程读的裸 `HWND` 全局,`g_bRunning` 是 `std::atomic` 但窗口句柄不是。 +启动顺序保证了可见性,但严格说存在数据竞争;用 `std::atomic` 或加载期一次性初始化更稳。 + +### P3:其它 + +| 项 | 说明 | +| --- | --- | +| `.def` 里的 `LIBRARY "AutoAgent.arx"` | 与实际输出 `cad_mcp_frame.arx` 不一致(不影响导出符号,但会误导) | +| `cad_mcp_frame.rc` 资源名 `AutoAgent` | 同上,历史遗留命名 | +| `try/catch` 只包了 `std::thread` 创建 | `LoadAndRegister` 内部若抛出(`nlohmann` 部分已用 `false` 免抛)会漏出到 CAD | +| `/Zc:forScope` 差异 | 原工程要求 `/Zc:forScope`(严格 for 作用域),code2026 顶层统一 `/Zc:forScope-`(放宽)。本次编译通过,但语义不同,若将来代码依赖严格作用域要注意 | +| `#pragma comment(lib,"ws2_32.lib")` | 在 CMake 工程里建议改成 `target_link_libraries(... ws2_32)` | +| 单连接串行 | 每个连接同步处理完才 `accept` 下一个;MCP 一般单客户端,可接受但要注意超时阻塞 | + +## 5. 依赖与体积 + +| 新增文件 | 大小 | +| --- | ---: | +| `SourceCode/dep_inc/nlohmann/json.hpp` | 920 KB | +| `SourceCode/dep_inc/ghc/filesystem.hpp` | 192 KB | + +两者都是单头、MIT 许可,随仓库走,不依赖 vcpkg。**代价是仓库多约 1.1 MB 头文件**; +好处是别人 clone 下来直接能编,不用装 vcpkg。 + +## 6. 移植后仍需处理(未做) + +1. **配置文件名**:把 `cad-mcp-frame.json` 改成代码里找的 `mcp_config.json` + (或把代码改成读 `cad-mcp-frame.json`)——现在是"能编译但一加载就自关"的状态。 +2. **插件工程未移植**:18 个工具里 16 个是 `c++_dll`,指到 `cad_mcp_plugins` 生成的 ARX; + 该工程还在 `CadProject` 下,没进 code2026。工具要真正可用,插件也得按同样方式移植。 +3. **LISP 目录**:`global_settings.lisp_directory` 指向的脚本目录需要随部署带上。 +4. **实测**:本次只验证"编译 + 部署",没有在 CAD 里加载验证(`NETLOAD`/启动自动加载后 + 看命令行是否打印 `[MCP Server] ... started`,以及能否 `tools/list`)。 + +## 7. 建议的优先顺序 + +1. 修 P0(收包协议 + socket 泄漏)——否则大参数请求根本用不了。 +2. 加 P1 的启动失败诊断(端口占用要能看见)。 +3. 明确配置文件名,并把插件工程一起移植。 +4. 加 token 鉴权(工具能改图,本机也不该无保护)。 +5. 把两类 `AfxMessageBox` 改成命令行输出,避免卡住 CAD 启动。