docs: 增加 cad_mcp_frame 的移植说明与代码审查

移植已完成(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 里实测
This commit is contained in:
company-desktop committed 2026-10-28 23:20:14 +08:00
1 parent 0d02d33f1d
commit 1dec459be9
1 file changed
+194
+194
View File
@@ -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,故 `<nlohmann/json.hpp>`、`<ghc/filesystem.hpp>` 直接可用 |
| `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<HWND>` 或加载期一次性初始化更稳。
### 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 启动。