时间戳与外部授时

Glove SDK 的公开数值时间统一使用毫秒。只有需要与外部系统对时，或需要让多路 Glove source 使用同一个绝对时间基准时，才需要调用 sync_time()；普通单手套应用可以直接使用默认时间基准。

时间单位

手套帧、运行状态、采集、标定和 SDK 派生数据中的公开数值时间都以毫秒表示。读取、存储、相减或转发这些字段时，不要再按秒处理。

外部输入优先使用 timestamp_ms。完整字段定义见 GloveNodePose 与 ExternalGloveFrame，各数据来源和读取方式见数据来源与读取方式。

时间基准

默认时间基准

不调用 sync_time() 时，SDK 使用主机 Unix 毫秒时间。省略外部帧的 timestamp_ms 时，该帧沿用当前 Glove 共享时间基准。

如果应用只在同一台主机上读取单只或多只手套，并且不需要和外部系统对齐，保持默认行为即可。

外部时间基准

把外部时钟提供的绝对 Unix 毫秒传给 qnbot::Glove::sync_time()。建议在 start() 前授时：

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

// reference_time_ms 来自 PTP、ROS 或其他外部时钟，
// 必须表示绝对 Unix 毫秒。
glove.sync_time(reference_time_ms);
glove.start();

// 按应用需要读取数据或启动运行方式。
glove.close();

参数类型为 double，必须是有限数值，单位不是秒或纳秒。完整可运行示例见 time_sync.cpp。

运行中重新授时

外部时钟更新后，可以在运行中再次调用 sync_time()。后续没有显式时间戳的 Glove 帧会从新基准继续推进；已有订阅和生命周期不会重置。

glove.sync_time(updated_reference_time_ms);

时间戳

SDK 生成的时间戳

实体手套帧由 SDK 按当前 Glove 共享时间基准自动写入时间戳；骨骼姿态等 SDK 派生结果会沿用对应输入帧的时间。应用只需读取这些时间戳，不需要自行填写。

外部输入省略 timestamp_ms 和 timestamp_sec 时，也会使用 SDK 自动生成的时间戳。未调用 sync_time() 时，时间来自主机 Unix 毫秒时间；调用后，SDK 按“最近一次授时值 + 授时后经过的时间”计算，并保证共享时钟生成的值递增。

外部输入时间戳

只有提交 qnbot::ExternalGloveFrame 时，应用才需要决定是否显式提供时间戳：

1. 显式提供的 timestamp_ms 优先，不会被共享时间基准覆盖。
2. 只提供 timestamp_sec 时，SDK 为兼容旧代码执行 timestamp_ms = timestamp_sec * 1000。
3. 两个字段都省略时，使用上文说明的 SDK 自动时间戳。

不要同时设置两个 std::optional 字段；两者同时有值会产生参数错误。显式时间戳必须是有限毫秒值，并对同一设备严格递增。完整的外部输入配置和帧约束见外部输入。