迁移

从 1.3.0 升级到 1.4.0

1.4.0 的主要迁移动作是统一时间单位和 native ABI。现有单手套应用不需要改成组合设备，也不要求调用 sync_time()；只有使用外部时间源、读取时间字段或准备接入 Exo + Glove 时，才需要完成对应步骤。

同时替换 Core 与 Glove 并重新编译

同时更新 1.4.0 的 Core/Glove 头文件、库文件、CMake package 和 Conan 包。清理 CMake 缓存、对象文件、静态库和插件后完整重新编译；不能混用 1.3.0 与 1.4.0 的头文件或 native 库，旧 ABI 会在 SDK 构造前被拒绝。

将公开数值时间改为毫秒

1.4.0 的 Glove 帧、运行状态、采集、标定和派生数据统一使用毫秒。新输出字段为 timestamp_ms；所有把时间当秒读取、存储、相减或传给下游协议的代码都需要同步修改。

外部帧从秒字段迁移到毫秒字段：

qnbot::ExternalGloveFrame frame;
// ...填写 thumb、index、middle、ring、pinky...
frame.timestamp_ms = 1'700'000'000'123.0;

旧的 frame.timestamp_sec 仍可作为兼容输入，SDK 会明确执行 timestamp_ms = timestamp_sec * 1000。不要根据数值大小猜测单位，也不要同时设置两个 std::optional；两者同时有值时会抛出参数错误。

按需设置外部时间基准

如果应用需要让所有 Glove source 使用同一个外部绝对时间基准，调用公开入口 qnbot::Glove::sync_time()。参数是 double 表示的绝对 Unix 毫秒，不是秒或纳秒：

qnbot::Sdk sdk(config);
auto glove = sdk.glove();
glove.sync_time(reference_time_ms);
glove.start();

可以在运行中再次调用 sync_time()；后续未显式携带时间的 Glove 帧会从新基准继续推进，已有订阅和生命周期不会重置。显式 timestamp_ms 优先，不会被共享时钟覆盖。不调用时， SDK 使用主机 Unix 毫秒时间。该操作只调整 Glove 域，不会修改 Exo 时间。

按需接入 Exo + Glove 组合设备

组合设备是新增能力，不影响原有 qnbot::GloveConfig。需要共享串口时，改用 qnbot::CompositeExoGloveConfig，并从同一个 qnbot::Sdk 取得 Glove 与 Exo facade；完整配置和能力边界见手套 + 外骨骼融合方案。

迁移检查清单

• 同时替换 Core 与 Glove 1.4.0，清理旧 CMake 缓存和构建产物后完整重新编译
• 将输出字段和下游协议中的秒值改为毫秒，优先使用 timestamp_ms
• 如暂时保留 timestamp_sec 输入，确认没有同时设置 timestamp_ms
• 对外部时间源使用绝对 Unix 毫秒，并在需要时调用 glove.sync_time()
• 只有使用融合硬件时才改用 qnbot::CompositeExoGloveConfig
• 用真实设备复测采集记录、时间对齐、断线恢复和关闭流程

从 1.2.x 升级到 1.3.0

本文只列出 Glove SDK 从 1.2.0 升级到 1.3.0 时必须修改的内容。SerialConnection、后台运行方式和算法包 package_id 语义没有变化，因此不列入本次不兼容变更。

采集接口从 Glove 移到 GloveDevice

1.2.0 中，应用构造请求对象并通过 Glove 调用采集接口，设备选择参数写在请求里：

qnbot::CaptureStartRequest request{
    package_ids,
    operator_id,
    std::nullopt,
    qnbot::Side::left,
    false,
};

auto capture = glove.start_capture(request);

1.3.0 中，CaptureStartRequest 已删除，需要先获取目标设备，再执行采集：

auto device = glove.device(qnbot::Side::left);

auto capture = device.start_capture(
    package_ids,
    operator_id,
    false
);

也可以按名称选择：

auto device = glove.device("my-glove");

设备选择从采集请求中独立出来，由应用先明确选择 GloveDevice。

删除 C++ 请求结构

qnbot::CaptureStartRequest 和 qnbot::CaptureStatusRequest 在 1.3.0 已删除，采集准备查询改为直接调用设备接口：

// 1.2.0
qnbot::CaptureStatusRequest status_request;
status_request.package_ids = package_ids;
status_request.operator_id = operator_id;
status_request.source = "left";
status_request.side = qnbot::Side::left;
auto readiness = glove.capture_status(status_request);

// 1.3.0
auto device = glove.device(qnbot::Side::left);
auto readiness = device.capture_status(package_ids, operator_id);

如果项目、封装层或配置转换代码中直接创建了这两个结构，需要全部改为直接调用设备接口。

start_calibration() 移到 GloveDevice

1.2.0：

auto calibration = glove.start_calibration(left_session, targets);

1.3.0：

auto device = glove.device(qnbot::Side::left);

auto calibration = device.start_calibration(left_session, targets);

采集会话和标定会话由同一个 GloveDevice 管理：

auto device = glove.device(qnbot::Side::left);

auto capture = device.start_capture(package_ids, operator_id, false);
auto calibration = device.start_calibration(capture, targets);

CalibrationInteractionMode 更名

1.2.0 的 qnbot::CalibrationInteractionMode 在 1.3.0 更名为 qnbot::CaptureInteractionMode，取值不变（auto_terminal、external）：

qnbot::CaptureInteractionMode::external

项目代码、配置文件映射和自定义封装中使用旧枚举名称的地方都需要修改。

采集交互配置从 CalibrationConfig 移到 CaptureConfig

1.3.0 把采集阶段配置和标定阶段配置分开：interaction 和 operator_id 属于采集阶段，已从 CalibrationConfig 移到 CaptureConfig；CalibrationConfig 只保留 force。

1.2.0 的写法：

config.algorithms.calibration.interaction =
    qnbot::CalibrationInteractionMode::external;
config.algorithms.calibration.operator_id = "operator-001";
config.algorithms.calibration.force = false;

1.3.0 应改为：

config.algorithms.capture.interaction =
    qnbot::CaptureInteractionMode::external;
config.algorithms.capture.operator_id = "operator-001";
config.algorithms.calibration.force = false;

字段定义见 CaptureConfig 与 CalibrationConfig。

C++ 项目必须重新编译

1.3.0 删除了 Glove 的采集与标定入口和两个请求结构，并更名了交互枚举、调整了采集交互配置的归属。C++ 项目必须同时替换 1.3.0 的 Core/Glove 头文件和库文件、清理旧的 CMake 构建缓存并完整重新编译；不能混用 1.2.0 和 1.3.0 的头文件、库文件或 Conan 包。

迁移检查清单

• 将 glove.start_capture(request) 改为 device.start_capture(package_ids, operator_id, force)
• 将 glove.capture_status(request) 改为 device.capture_status(package_ids, operator_id)
• 将 glove.start_calibration(...) 改为 device.start_calibration(...)
• 删除 CaptureStartRequest
• 删除 CaptureStatusRequest
• 将 CalibrationInteractionMode 改为 CaptureInteractionMode
• 将 interaction 和 operator_id 从 algorithms.calibration 移到 algorithms.capture
• 使用 1.3.0 的 Core/Glove 头文件和库文件重新编译
• 确保采集和标定使用同一个 GloveDevice

从 1.1.x 升级到 1.2.0

最低迁移要求：同时替换 Core 与 Glove 1.2.0 包，清理旧 CMake 构建缓存并完整重新编译；不要混用 1.1.x 头文件、动态库、对象文件或插件。应用不再依赖 connect() 建立连接，SDK 构造和 start() 都应位于异常处理范围；Skeleton 关节角数组或映射应按 25 个 active joints 处理。

以下仅列出升级时需要修改现有代码或重新构建的不兼容变化。完整的新增功能、修复和版本变化请查看 C++ SDK 更新日志。