示例：ExtlibTestPlugin

ProcessCraft 插件开发指导文档

本文档指导开发者从零开始搭建 ProcessCraft 插件开发环境，下载并理解官方示例项目 ExtlibTestPlugin（一个"依赖其它动态链接库的插件"示例），并在此基础上完成插件的修改、编译、安装与测试。

适用读者：具备 C++ 基础、使用 Windows（MSVC 工具链）的插件开发者。

参考资料：

• 官方开发环境文档：https://www.geomland.cn/docs/sdk/overview/devenv
• 官方 SDK 总览：https://www.geomland.cn/docs/sdk/overview/start
• 示例项目仓库：https://gitcode.com/geomland/ExtlibTestPlugin

---

目录

1. 概述
2. 安装和配置开发环境
3. 下载并理解示例项目
4. 修改、编译、安装与测试
5. 常见问题（FAQ）
6. 附录：命令速查与参考链接

---

1. 概述

ProcessCraft 是 Geomland 推出的机器人工艺编程软件，其功能可以通过 插件(Plugin) 扩展。一个 ProcessCraft 插件本质上是一个实现了 mpl::IPlugin 接口的 Qt 共享库（.dll / .so），ProcessCraft 启动时会自动扫描安装目录 bin/plugins 下的插件并加载。

完整的开发流程如下：

搭建开发环境          获取示例项目         按需修改源码          编译                安装                测试
(CMake/VS/Qt/  →  (git clone 或     →  (改元数据/源文件/ →  (cmake 配置 +  →  (编译产物自动    →  (启动 ProcessCraft,
 ProcessCraft)     下载 ZIP)             依赖库)             构建)             落入安装目录)        验证插件行为)
                                           ↑_________________________________________|
                                                        迭代循环（见 4.4 节）

官方示例 ExtlibTestPlugin 演示了一个"依赖外部动态链接库（mathlib）的插件"应当如何组织源码、编写 CMake 构建脚本、声明插件元数据（JSON），以及如何让插件与依赖 DLL 一起部署到 ProcessCraft 安装目录并在启动时被正确加载——这是最小而完整的插件工程模板，绝大多数插件都可以以此为起点开发。

---

2. 安装和配置开发环境

按照官方文档，除 ProcessCraft 软件本身外，还需要 CMake、最新版本的 Visual Studio 和最新公开发布版本的 Qt。

2.0 准备清单

组件	版本要求	用途
ProcessCraft	最新安装包	插件宿主程序 + mpl SDK（头文件与mplsdk 库）
CMake	≥ 3.25（示例工程最低要求 3.24）	构建配置
Visual Studio	最新版本，社区版即可	提供 MSVC 编译器（cl）、链接器、dumpbin、Ninja
Qt 6	最新发布版，MSVC 64-bit 套件	插件基于 Qt 开发；版本必须与 ProcessCraft 内嵌 Qt 一致（见 4.2 节）
Git	任意较新版本	克隆示例项目（可选，也可下载 ZIP）

2.1 ProcessCraft 本体的安装

到官网下载页 https://www.geomland.cn/download 下载并安装 ProcessCraft。

安装完成后请记下安装目录（下文用 <mplpath> 指代）。它是后续编译插件时必须传入的 CMake 参数，其下应当能看到：

<mplpath>/
├── bin/
│   ├── processcraft.exe        ← 判定 Debug/Release 与位数的依据
│   ├── plugins/                ← 插件 dll 的加载目录
│   └── 3rd/                    ← 插件依赖的第三方 dll 存放目录
├── lib/cmake/                  ← mpl SDK 的 CMake 包（find_package(mpl)）
└── qml/                        ← ProcessCraft 的 QML 模块（编辑器代码补全用）

提示：ProcessCraft 的下载与试用通常需要注册 Geomland 账号，请以官网实际流程为准。

2.2 CMake 的安装

1. 从 https://cmake.org/download/ 下载并安装 CMake 最新版本。
2. 安装时勾选 "Add CMake to the system PATH"（将 cmake 命令所在路径加入系统环境变量 Path）。
3. 若安装时未勾选，可手动把以下目录加入系统 Path：

C:\Program Files\CMake\bin

2.3 Visual Studio 的安装

1. 从 https://visualstudio.microsoft.com/ 下载社区版（Community）。
2. 安装时在"工作负载"页面勾选 “使用 C++ 的桌面开发”。该工作负载自带 MSVC x64 工具链、dumpbin 等调试诊断工具，以及 "C++ CMake tools for Windows"（内含 Ninja 构建器）。
3. 配置默认命令行环境（二选一）：
   • 推荐：打开 Windows Terminal → 设置 → 启动，将默认配置文件设为 "Developer Command Prompt for VS"（Visual Studio 的 Developer Command 环境），之后新开的命令行即自带 MSVC 环境变量；
   • 或者手动把 MSVC 工具链路径加入系统 Path（官方文档示例路径如下，年份与版本目录请按实际安装的调整，如 2022 / 2026、Community / Professional）：

C:\Program Files\Microsoft Visual Studio\<版本>\< editions>\VC\Auxiliary\Build

4. 无论采用哪种方式，在普通 cmd 窗口中开发前都需要先执行一次：

vcvars64

它把 x64 的 MSVC 编译/链接环境（cl、link、dumpbin、ninja 等）注入当前命令行会话。后续所有 cmake 命令都要在已执行 vcvars64（或使用 Developer Command Prompt）的窗口中运行。

2.4 Qt 的安装

Qt 只支持通过 维护工具（Online Installer） 下载和安装 SDK 及源代码：

1. 下载维护工具：访问 https://download.qt.io/official_releases/online_installers，选择 Windows x64 版本： https://download.qt.io/official_releases/online_installers/qt-online-installer-windows-x64-online.exe
2. 注册 Qt 账号：运行安装工具，注册并登录个人开发者账号（开源版免费）。
3. 选择开发套件：进入"开发套件"选择页，勾选 最新版 Qt 下的 MSVC 64 bit 组件（注意：不是 ARM64 版本）。Sources（Qt 源代码）可按需下载，仅开发插件时不是必需的。等待安装完成（默认安装到 C:\Qt）。
4. 配置运行库路径：安装完成后，将 Qt 运行库目录加入系统环境变量 Path，例如：

C:\Qt\<Qt版本>\msvc2022_64\bin

⚠️ 版本匹配：插件所用的 Qt 版本必须与 ProcessCraft 自带的 Qt 版本完全一致，否则 CMake 配置阶段会直接报错（Qt6 version does not match!）。如果你安装后发现不匹配，请回到维护工具补装日志中提示的那个版本。

2.5 验证环境

环境配置完成后，重新打开一个命令行窗口（确保 PATH 修改生效；若不是 Developer 环境，先执行 vcvars64），依次验证：

cmake --version     :: 版本需 ≥ 3.25
ninja --version     :: 能输出版本号（由 VS "C++ CMake tools" 提供）
cl /?               :: 显示编译器帮助；确认是 64 位（x64）版本的 cl
linguist            :: 能启动 Qt 语言家（Linguist），说明 Qt 的 bin 已在 PATH 中

四项全部通过后，开发环境即搭建完毕。

---

3. 下载并理解示例项目

3.1 克隆 / 下载示例项目

示例项目仓库地址：https://gitcode.com/geomland/ExtlibTestPlugin

方式一：git 克隆（推荐，便于拉取更新）

git clone https://gitcode.com/geomland/ExtlibTestPlugin.git

方式二：下载 ZIP

在仓库页面点击 “下载 ZIP” 按钮，下载 main 分支压缩包后解压。

3.2 工程结构

ExtlibTestPlugin/
├── CMakeLists.txt          # 构建脚本（核心，含插件工程的通用套路）
├── get_exe_info.cmake      # 辅助脚本：探测 ProcessCraft 主程序的 Debug/Release 与位数
├── ExtlibTestPlugin.h      # 插件类声明：继承 mpl::IPlugin
├── ExtlibTestPlugin.cpp    # 插件类实现：initialize / extensionsInitialized
├── ExtlibTest.json         # 插件元数据（清单文件，随 dll 一起编入）
├── .gitignore
└── mathlib/                # 示例依赖的第三方动态库（含头文件与各平台成品库）
    ├── include/
    │   └── mathlib.h       # 导出函数：math_add / math_sub / math_mul / math_div
    ├── msvc/               # Release 版（MSVC）：lib/ 导入库 + dll/ 运行库
    ├── msvc_d/             # Debug   版（MSVC）：lib/ + dll/
    ├── gcc/                # Release 版（Linux）：so/
    └── gcc_d/              # Debug   版（Linux）：so/

3.3 核心文件详解

（1）插件类 ExtlibTestPlugin.h

#pragma once

#include "esys/IPlugin.h"

namespace plugin::extlibtest {

class ExtlibTestPlugin final : public mpl::IPlugin {
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "cn.geomland.ProcessCraftPlugin" FILE "ExtlibTest.json")

public:
    ExtlibTestPlugin();
    ~ExtlibTestPlugin() final;

    bool initialize() final;
    void extensionsInitialized() final;
};

}

要点：

• 插件类必须继承 mpl::IPlugin（头文件由 mplsdk 提供），并使用 Q_OBJECT 宏（Qt 元对象）。
• Q_PLUGIN_METADATA 的 IID 固定为 cn.geomland.ProcessCraftPlugin——这是 ProcessCraft 识别插件的"接头暗号"，克隆工程时不要改动；FILE 指向插件的元数据 JSON 文件。
• initialize()：插件加载时的入口，返回 true 表示初始化成功（可在此注册界面元素、信号槽等）。
• extensionsInitialized()：所有插件都完成 initialize() 之后被调用，适合做跨插件的联动逻辑。示例的重载函数就在这里调用了外部库的四个数学函数并用 qDebug() 打印结果。

（2）插件实现 ExtlibTestPlugin.cpp

#include "ExtlibTestPlugin.h"
#include "mathlib.h"
#include <QDebug>

namespace plugin::extlibtest {

bool ExtlibTestPlugin::initialize() {
    return true;
}

void ExtlibTestPlugin::extensionsInitialized() {
    int a = 20;
    int b = 4;

    qDebug() << a << " + " << b << " = " << math_add(a, b);
    qDebug() << a << " - " << b << " = " << math_sub(a, b);
    qDebug() << a << " * " << b << " = " << math_mul(a, b);
    qDebug() << a << " / " << b << " = " << math_div(a, b);
}

}

这段代码演示了插件的两大核心能力：响应宿主生命周期（重载 IPlugin 回调）与调用外部动态库（math_add 等来自 mathlib）。

（3）插件元数据 ExtlibTest.json

字段	示例值	说明
Id	extlibtest	插件唯一标识，用于依赖声明与模块管理
Name	ExtlibTest	插件显示名称
Version / CompatVersion	0.1.0	插件版本号 / 兼容版本号
Vendor / VendorId	Geomland / geomland	开发者（厂商）信息
Copyright / License	—	版权与许可证信息
Description / Url	—	描述与主页
Dependencies	[{"Id":"core","Version":"0.1.0"}]	依赖的其它插件；core 是 ProcessCraft 核心插件，一般都要依赖，且会被优先加载
DllDirs	["%appdir%/3rd", "%appdir%/3rd2"]	插件运行时查找依赖 DLL 的附加目录；%appdir% 指 ProcessCraft 的 bin 目录。示例把第三方 dll 部署到 bin/3rd 并在此声明，进程启动时即可找到它们

（4）构建脚本 CMakeLists.txt

示例的 CMake 脚本包含了一套对所有插件工程都通用的"体检"逻辑，值得逐段理解：

段落	作用
if (NOT mplpath) ... FATAL_ERROR	强制要求通过 -Dmplpath=<ProcessCraft安装目录> 指定宿主路径
include(get_exe_info.cmake) + get_exe_info(...)	用 dumpbin（Windows）或 readelf/file（Linux）探测 processcraft.exe 的构建类型（DEBUG/RELEASE）与位数（32/64）
find_package(mpl COMPONENTS sdk REQUIRED PATHS ${mplpath}/lib/cmake)	从安装目录引入 mplsdk 目标（含头文件与库），失败即终止
find_package(Qt6 COMPONENTS Core REQUIRED) + 版本比对	查找 Qt6 并要求其版本号与 MPL_QT_VERSION（ProcessCraft 自带 Qt 版本）严格相等
CMAKE_CXX_STANDARD 23 / AUTOMOC / AUTORCC	C++23 标准；打开 Qt 元对象编译（Q_OBJECT 必需）与资源编译
MSVC /utf-8 /EHsc	源文件按 UTF-8 编译（避免中文乱码）、同步异常模型
QML_IMPORT_PATH	指向 <mplpath>/qml，供 IDE 编写 QML 时补全
位数检查	编译器位数与宿主 exe 位数不一致时直接报错
if (EXE_TYPE STREQUAL "DEBUG") set(CMAKE_BUILD_TYPE Debug)	插件的 Debug/Release 自动跟随宿主，避免运行时库混用
qt_add_library(extlibtestplugin SHARED ...)	声明插件编译目标（共享库）
target_include_directories(... mathlib/include)	依赖库头文件目录
target_link_directories(... msvc/lib 或 msvc_d/lib)	按构建类型链接对应的导入库
target_link_libraries(... math mplsdk Qt::Core)	链接：外部依赖库 + ProcessCraft SDK + Qt Core
POST_BUILD copy_directory → ${mplpath}/bin/3rd	编译完成后自动把依赖 dll 部署到宿主 bin/3rd（Linux 下部署到 ${mplpath}/lib 并设置 INSTALL_RPATH "$ORIGIN/../../lib/"）
RUNTIME_OUTPUT_DIRECTORY → ${mplpath}/bin/plugins	插件 dll 直接输出到宿主的 bin/plugins——即"编译即安装"

💡 正因为"编译即安装"，示例工程没有单独的 install 步骤：cmake --build 成功的那一刻，插件和依赖库就已经部署到 ProcessCraft 里了。

3.4 插件部署模型小结

内容	部署位置（Windows）	由谁完成
插件本体 <name>.dll	<mplpath>/bin/plugins/	RUNTIME_OUTPUT_DIRECTORY 属性
插件依赖的第三方 dll	<mplpath>/bin/3rd/（须被 DllDirs 覆盖）	POST_BUILD copy_directory
插件元数据 JSON	编入 dll 资源（Q_PLUGIN_METADATA ... FILE）	Qt 插件机制

---

4. 修改、编译、安装与测试

4.1 按需求修改示例项目

以下给出四类最常见的修改场景，可单独或组合使用。修改前建议用 git 建立基线（示例仓库克隆后直接提交一次本地快照即可），便于回退。

场景 A：修改插件名称与元数据

把示例改造成你自己的插件时，需要同步修改以下几处（以一个虚构的 MyTool 插件为例）：

1. ExtlibTest.json → 复制为 MyTool.json，修改 Id（小写无空格，如 mytool）、Name（如 MyTool）、Version、Vendor、Description 等；Dependencies 通常保留对 core 的依赖；若依赖库仍部署到 bin/3rd，DllDirs 保留不动。
2. ExtlibTestPlugin.h → 修改命名空间（如 namespace plugin::mytool）、类名（MyToolPlugin）、Q_PLUGIN_METADATA 中 FILE 指向新的 JSON 文件名。IID 保持 cn.geomland.ProcessCraftPlugin 不变。
3. ExtlibTestPlugin.cpp → 同步改名并包含新头文件。
4. CMakeLists.txt → 修改 project(MyTool ...) 与 qt_add_library(mytoolplugin SHARED MyTool.h MyTool.cpp ...) 的文件列表；输出目标名（如 mytoolplugin）建议与 Id 呼应，最终生成的 mytoolplugin.dll 会以文件名+清单双重身份被宿主管理。

场景 B：增删源码文件

所有参与编译的源文件都列在 qt_add_library 中，例如新增 Helper.h/Helper.cpp：

qt_add_library(extlibtestplugin SHARED
    ExtlibTestPlugin.h ExtlibTestPlugin.cpp
    Helper.h Helper.cpp          # ← 新增
)

含 Q_OBJECT 的新类无需额外配置（CMAKE_AUTOMOC ON 会自动处理）。改完后重新执行 4.2 节的配置与构建即可。

场景 C：调用 ProcessCraft SDK 接口做实际功能

SDK 的全部 C++ 接口都声明在 mpl 命名空间中，链接 mplsdk 目标后即可使用。官方文档列出的常用界面接口有：

QQmlContext* mpl::GetRootContext();                       // 获取 QML 根上下文
void mpl::AddToolGroup(QString text, QString url);        // 顶部栏添加一组图标工具
void mpl::AddActivityControl(QString text, QString icon, QString url); // 活动栏按钮+侧边面板
void mpl::AddPanel(QString text, QString url);            // 底侧边栏面板
void mpl::AddStatusControl(QString url);                  // 状态栏区域
void mpl::ShowMessage(QString msg);                       // 弹出信息提示框
std::vector<unsigned> mpl::GetSelectedIdList();           // 当前选中对象 id 列表

修改示例：让插件加载完成后弹出一个对话框（可直接肉眼验证插件被加载）：

#include "ExtlibTestPlugin.h"
#include "mathlib.h"
#include <QDebug>
// mpl SDK 接口声明包含在安装目录提供的 mplsdk 头文件中，
// 具体 include 名称以 <mplpath> 安装目录 include 下实际头文件为准，
// 接口清单与用法参见官网“开发接口”文档。

namespace plugin::extlibtest {

bool ExtlibTestPlugin::initialize() {
    return true;
}

void ExtlibTestPlugin::extensionsInitialized() {
    int a = 20;
    int b = 4;
    int sum = math_add(a, b);
    // 官方文档示例写法：显示文本需要 tr() 翻译
    mpl::ShowMessage(tr("ExtlibTest 插件已加载，%1 + %2 = %3").arg(a).arg(b).arg(sum));
}

}

更多接口（建模、工序与指令、任务与位姿、选择与高亮、点云、命名附件、信号代理等）请查阅官网"开发接口"章节：https://www.geomland.cn/docs/sdk/，其中信号代理用法见 https://www.geomland.cn/docs/sdk/overview/proxy。

场景 D：更换 / 删除外部依赖库

示例的 mathlib 演示了依赖外部动态库的标准姿势。若你要换成自己的库 foo.dll（或不再需要外部库）：

1. 在 mathlib/include 同级建立（或直接替换）foolib/include、foolib/msvc/{lib,dll}、foolib/msvc_d/{lib,dll} 目录结构，放入头文件、导入库（.lib）与运行库（.dll）；Debug/Release 各一套。
2. CMakeLists.txt 中改三处：
   • target_include_directories(... foolib/include)
   • target_link_directories(... foolib/msvc/lib 或 msvc_d/lib)
   • target_link_libraries(... foo mplsdk Qt::Core)
   • POST_BUILD 复制源目录改为 foolib/msvc(_d)/dll
3. 不再需要外部库时，删除上述相关段落即可，插件目标只链接 mplsdk 和 Qt。
4. 若依赖库部署目录不再是 bin/3rd，记得同步修改 ExtlibTest.json 的 DllDirs。

4.2 编译（配置 + 构建）

第 1 步：打开可用的开发命令行

打开 cmd（或 Windows Terminal），先注入 MSVC 环境：

vcvars64

第 2 步：CMake 配置

进入项目目录，指定 ProcessCraft 安装路径进行配置（路径用正斜杠 /，不要带中文/空格更佳；下文以默认安装位置为例，请按实际修改）：

cd /d D:\work\ExtlibTestPlugin
cmake -S . -B build -G Ninja -Dmplpath="C:/Program Files/Geomland/ProcessCraft"

配置成功时日志中会看到类似输出：

-- ProcessCraft found at C:/Program Files/Geomland/ProcessCraft/bin/processcraft.exe, type: RELEASE, arch: 64
-- Found Qt6 in C:/Qt/6.x.x/msvc2022_64/lib/cmake/Qt6, version: 6.x.x; Found mplsdk, its Qt version: 6.x.x
-- Plugin building type: Release

注意核对两点：

• Qt 版本与 mplsdk 要求版本一致（不一致会 FATAL_ERROR: Qt6 version does not match!）；
• Plugin building type 自动跟随宿主（宿主是 Release 版就用 Release 编译，反之亦然），无需手工指定 CMAKE_BUILD_TYPE。

第 3 步：构建

cmake --build build

构建成功后即完成部署（见下节）。若修改过 CMakeLists.txt 或增删过源文件，无需删除 build 目录重跑配置，直接再次 cmake --build build，Ninja 会自动感知并重配置；只有报生成器/缓存类错误时才需要删掉 build 目录重新执行第 2 步。

Linux 说明：示例工程同样支持 Linux（gcc 的 .so 依赖部署到 ${mplpath}/lib 并设置 RPATH）。在 Linux 下执行 cmake -S . -B build -Dmplpath=/opt/processcraft && cmake --build build 即可，环境准备为对应发行版的 GCC/CMake/Qt6。

4.3 安装

示例工程采用 "编译即安装" 模式，构建完成后无需手工拷贝，产物已就位：

检查项	期望位置	验证命令（Windows）
插件 dll	<mplpath>/bin/plugins/extlibtestplugin.dll	dir "<mplpath>\bin\plugins"
依赖 dll	<mplpath>/bin/3rd/（math.dll、add.dll、sub.dll）	dir "<mplpath>\bin\3rd"

:: 示例：确认部署产物
dir "C:\Program Files\Geomland\ProcessCraft\bin\plugins\extlibtestplugin.dll"
dir "C:\Program Files\Geomland\ProcessCraft\bin\3rd"

手动安装 / 分发给他人：如果要把开发机上编译好的插件安装到另一台 ProcessCraft，只需把 plugins/<name>.dll 拷到对方的 <mplpath>/bin/plugins/，把依赖 dll 拷到 <mplpath>/bin/3rd/（或 DllDirs 声明的其它目录，如 3rd2）。注意目标机的 ProcessCraft 必须与本机构建时匹配的 Qt 版本、构建类型（Debug/Release）一致。

4.4 测试

第 1 步：启动 ProcessCraft

关闭正在运行的 ProcessCraft（插件只在启动时加载一次），从开始菜单或命令行启动 processcraft.exe。

第 2 步：确认插件行为

示例插件在 extensionsInitialized() 中用 qDebug() 输出四行结果，GUI 程序默认无控制台，推荐使用以下任一方式查看：

• Sysinternals DebugView（https://learn.microsoft.com/sysinternals/downloads/debugview）：以管理员身份运行，勾选 Capture Win32/Global，再启动 ProcessCraft，可看到：

20 + 4 = 24
20 - 4 = 16
20 * 4 = 80
20 / 4 = 5

• Visual Studio 调试：打开源码后用"项目属性 → 调试器 → 启动程序"指向 <mplpath>\bin\processcraft.exe，或菜单"调试 → 附加到进程"，在 VS 的"输出"窗口查看 qDebug 信息，并可设断点调试 initialize/extensionsInitialized。
• 若你按 场景 C 改成了 mpl::ShowMessage(...)，则启动后会直接弹出对话框，肉眼即可确认插件已被加载和执行——这也是最快的冒烟测试改法。

第 3 步：确认插件被宿主识别

若看不到预期行为，按顺序检查：bin/plugins 下是否存在新 dll → bin/3rd 下依赖 dll 是否齐全 → ProcessCraft 的启动日志/输出中是否有该插件的加载或错误信息（详见 FAQ）。

第 4 步：功能测试与回归

• 针对你的功能点设计用例（例如：修改任务数据后验证界面刷新、选中对象后验证 GetSelectedIdList 返回值等）；
• 每次改动源码后执行 cmake --build build（自动重新部署）→ 重启 ProcessCraft → 复测，形成迭代闭环；
• 发布前：在Release 版宿主上完整走一遍冒烟测试（宿主版本不同，插件构建类型也不同），并清理 build 目录做一次全新构建，排除缓存因素。

---

5. 常见问题（FAQ）

症状	原因	处理
配置报 You should specify the directory of ProcessCraft with '-Dmplpath=...'	未传 mplpath	配置命令追加 -Dmplpath=<安装目录>
配置报 File not exists: .../processcraft.exe	mplpath 指向了错误目录	指向包含 bin/、lib/cmake/ 的 ProcessCraft 根目录
配置报 Qt6 version does not match!	本机 Qt 与宿主内嵌 Qt 版本不一致	按日志中 MPL_QT_VERSION 提示的版本，用 Qt 维护工具补装对应 MSVC 64-bit 套件，并在 Path 中优先指向它
配置报 mplsdk not found! / Could not find a package configuration file provided by "mpl"	mplpath 下没有 lib/cmake，或 ProcessCraft 版本过旧不含 SDK	确认安装完整、路径正确；必要时升级 ProcessCraft
配置报 no dumpbin found	命令行不是 Developer 环境	先执行 vcvars64 再重新配置
配置报位数不匹配（built with '32bit' ... 等）	使用了 x86 工具链	用 vcvars64（而不是 vcvars 默认值）确保 x64 的 cl
编译通过但插件不加载、或 ProcessCraft 启动即崩溃	依赖 dll 缺失 / 未声明查找目录 / Debug-Release 与宿主不匹配	检查 bin/3rd 与 DllDirs；用 dumpbin /dependents extlibtestplugin.dll 核对依赖链；确认插件构建类型与宿主一致（由 get_exe_info.cmake 自动保证）
中文注释/字符串乱码或编译告警	源文件编码非 UTF-8	工程已加 /utf-8，请确保源文件本身以 UTF-8 保存
想强制编 Debug 版插件测试	构建类型被脚本自动覆盖	这是设计行为（避免与 Release 宿主混用 CRT）；如确需 Debug，请换装 Debug 版 ProcessCraft 宿主
修改 JSON/类名后仍显示旧插件名	dll 未重新生成，或 bin/plugins 下残留旧 dll	重新构建；删除 bin/plugins 下旧的 <name>.dll 后重启软件

---

6. 附录：命令速查与参考链接

从零到跑通的全部命令（Windows）

:: 0) 安装 CMake / Visual Studio(桌面C++) / Qt(MSVC64) 并配置 PATH，见第 2 章

:: 1) 打开 cmd，注入 MSVC 环境并自检
vcvars64
cmake --version && ninja --version && cl /?

:: 2) 获取示例
git clone https://gitcode.com/geomland/ExtlibTestPlugin.git
cd ExtlibTestPlugin

:: 3) 配置（按实际安装路径修改 mplpath）
cmake -S . -B build -G Ninja -Dmplpath="C:/Program Files/Geomland/ProcessCraft"

:: 4) 构建（即自动部署到 ProcessCraft）
cmake --build build

:: 5) 验证部署
dir "C:\Program Files\Geomland\ProcessCraft\bin\plugins\extlibtestplugin.dll"
dir  "C:\Program Files\Geomland\ProcessCraft\bin\3rd"

:: 6) 启动 ProcessCraft，用 DebugView / 附加调试查看插件输出

参考链接

主题	链接
开发环境安装配置（本文第 2 章依据）	https://www.geomland.cn/docs/sdk/overview/devenv
SDK 总览（API 规范、界面/任务/数据结构接口）	https://www.geomland.cn/docs/sdk/overview/start
界面元素介绍	https://www.geomland.cn/docs/sdk/overview/ui
信号代理介绍	https://www.geomland.cn/docs/sdk/overview/proxy
SDK 数据类型	https://www.geomland.cn/docs/sdk/overview/datatype
API 参考（UI/建模/工序/任务/选择/点云/附件）	https://www.geomland.cn/docs/sdk/
示例项目仓库	https://gitcode.com/geomland/ExtlibTestPlugin
ProcessCraft 下载	https://www.geomland.cn/download
CMake 下载	https://cmake.org/download/
Visual Studio 下载	https://visualstudio.microsoft.com/
Qt 在线安装器	https://download.qt.io/official_releases/online_installers
DebugView（查看 qDebug 输出）	https://learn.microsoft.com/sysinternals/downloads/debugview
案例演示（B 站）	https://space.bilibili.com/256871988
问题报告	https://gitcode.com/geomland/processcraft/issues

---

本文档基于 ProcessCraft 官网 SDK 文档（2026-07 版）与 ExtlibTestPlugin main 分支源码编写；接口与目录结构如有出入，以官网文档及你实际安装的 SDK 版本为准。