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:
1 parent
0d02d33f1d
commit
1dec459be9
1 file changed
+194
@@ -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 启动。
|
||||
Reference in new issue
Block a user