API 参考 | Qnbot Docs Center

Python SDK 没有为 Sdk 提供 context manager。请使用 try/finally 显式清理：

sdk = Sdk(devices=(...))

try:
    ...
finally:
    sdk.close()

只使用手套功能时，可以在 finally 中调用 glove.close()。关闭后不能继续读取数据或使用已有的 GloveDevice 和 subscription，否则会抛出 ClosedHandleError。

close() 会回收仍然有效的 subscription。只有 SDK 还要继续运行、但需要提前停止某个 callback 时，才调用 subscription.unsubscribe()；最终关闭前不需要逐个取消订阅。

推荐清理顺序：

后台运行时调用 request_stop() 停止产生新数据。
后台运行时调用 join() 等待线程结束。
如果设置过震动，按业务需要调用 clear()。
调用 glove.close() 或 sdk.close()，统一回收剩余 subscription。

公开命令行示例按 Ctrl+C 直接结束进程；正式程序需要主动停止时，使用后台模式执行上述顺序。

Sdk.close() 可重复调用。Glove.close() 会停止并关闭全部已配置手套，应在正常清理路径中调用一次。析构函数只作为异常情况下的兜底，不应代替显式关闭。

对象与方法总表

无参数方法在“参数、类型与默认值”列写“无”。

顶层函数

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`discover_gloves()`	查看当前可发现的手套	无	`tuple[DiscoveredGlove, ...]`	创建 SDK 前	顶层发现错误；逐端口错误在结果中

`Sdk`

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`Sdk.glove()`	进入手套功能	无	`Glove`	SDK 未关闭	`ClosedHandleError`、能力不可用
`Sdk.start()`	启动已配置功能和设备数据流	无	`None`	准备数据读取和订阅后	连接、身份、数据流或生命周期错误
`Sdk.update()`	在当前循环中执行一次 SDK 任务调度	无	`UpdateResult`	已启动且未使用其他运行方式	`LifecycleError`
`Sdk.run_forever()`	在当前线程持续推进 SDK 调度任务	无	`None`	已启动且未使用其他运行方式	`LifecycleError`
`Sdk.run_background()`	在后台推进 SDK 调度任务	无	`None`	已启动且未使用其他运行方式	`LifecycleError`、后台运行错误
`Sdk.request_stop()`	请求正在运行的调度任务停止	无	`None`	前台或后台运行期间	`LifecycleError`
`Sdk.join()`	等待后台调度线程结束	无	`None`	已请求后台停止后	`LifecycleError`、后台错误
`Sdk.stop()`	停止运行并断开设备	无	`None`	SDK 已启动	停止过程错误
`Sdk.close()`	最终关闭 SDK 并释放资源	无	`None`	不再使用 SDK 时	关闭过程错误；关闭后对象失效
`Sdk.health()`	查看整个 SDK 的健康状态	无	`Health`	SDK 未关闭	`ClosedHandleError`

`Glove`

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`Glove.device(name=None, *, side=None)`	从已配置手套中选择一只设备	`name: str \| None = None` 或 `side: Side \| None = None`，两者互斥	`GloveDevice`	SDK 创建后	`NotFoundSelectionError`、`AmbiguousSelectionError`
`Glove.sync_time(reference_time_ms)`	为所有手套 source 设置统一的外部绝对时间基准	`reference_time_ms: float`，有限的 Unix 毫秒值	`None`	建议在 `start()` 前；运行中可再次调用以重新授时	`InvalidArgumentError`、`ClosedHandleError` 或底层授时错误
`Glove.start()`	启动全部已配置手套和功能	无	`None`	准备数据读取和订阅后	连接、身份、数据流或生命周期错误
`Glove.update()`	在当前循环中执行一次 SDK 任务调度	无	`UpdateResult`	已启动且未使用其他运行方式	`LifecycleError`
`Glove.run_forever()`	在当前线程持续推进 Retargeting 和恢复等 SDK 调度任务	无	`None`	已启动且未使用其他运行方式	`LifecycleError`
`Glove.run_background()`	在后台推进 Retargeting 和恢复等 SDK 调度任务	无	`None`	已启动且未使用其他运行方式	`LifecycleError`、后台运行错误
`Glove.request_stop()`	请求正在运行的调度任务停止	无	`None`	前台或后台运行期间	`LifecycleError`
`Glove.join()`	等待后台调度线程结束	无	`None`	已请求后台停止后	`LifecycleError`、后台错误
`Glove.stop()`	停止全部手套并断开设备	无	`None`	Glove 已启动	停止过程错误
`Glove.close()`	最终关闭手套功能并释放资源	无	`None`	不再使用 Glove 时	关闭过程错误；关闭后对象失效
`Glove.health()`	查看全部已配置手套的健康状态	无	`Health`	Glove 未关闭	`ClosedHandleError`

`GloveDevice`

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`GloveDevice.name` / `GloveDevice.source_id`	读取配置名称和运行时 source 标识	无，property	`str \| None` / `str`	SDK 未关闭	`ClosedHandleError`
`GloveDevice.get_device_info()`	读取已验证的设备信息快照	无	`DeviceInfo`	SDK 创建后，可在 start 前	`UnavailableFeatureError`（身份未验证）
`GloveDevice.start()` / `GloveDevice.stop()`	只启动或停止选中的一只手套	无	`None`	需要单独控制设备时	连接、身份、数据流或生命周期错误
`GloveDevice.health()`	查看所选手套的健康状态	无	`Health`	设备未关闭时	`ClosedHandleError`
`GloveDevice.close()`	释放所选手套的设备作用域	无	`None`	不再使用该设备时；关闭后不可重启	`ClosedHandleError`
`GloveDevice.pose()`	读取手套原始姿态	无	`ReadChannel[GlovePose]`	SDK 创建后；建议 start 前调用	生命周期或关闭错误
`GloveDevice.imu()`	读取手套的原始 IMU 数据	无	`ReadChannel[GloveImu]`	SDK 创建后；建议 start 前调用	生命周期、关闭或不支持错误；实验性功能
`GloveDevice.status()`	读取设备连接和恢复状态	无	`ReadChannel[GloveStatus]`	SDK 创建后；建议 start 前调用	生命周期或关闭错误
`GloveDevice.skeleton()`	启用并访问 Skeleton 数据	无	`Skeleton`	必须在 start 前调用	`LifecycleError`、能力不可用
`GloveDevice.skeleton().joint_angles()`	读取 Skeleton 关节角	无	`ReadChannel[HandJointCommand]`	skeleton 启用后	所属对象已关闭或功能不可用
`GloveDevice.skeleton().pose()`	读取 OpenXR 骨骼节点姿态	无	`ReadChannel[HandSkeletonPose]`	skeleton 启用后	所属对象已关闭或功能不可用
`GloveDevice.output(name=None)`	读取指定 target 的灵巧手输出	`name: str \| None = None`；省略时要求 target 唯一	`ReadChannel[HandJointCommand]`	SDK 创建后	target 未找到或歧义
`GloveDevice.haptics()`	取得指尖震动控制入口	无	`StateChannel[Haptics]`	串口设备选择后	external、无线或断连时不支持或拒绝
`GloveDevice.push_frame(frame)`	向外部输入 source 提交一帧手部数据	`frame: ExternalGloveFrame`，必填	`GlovePose`	external device 已 start	参数、时间戳或生命周期错误
`GloveDevice.calibration_status(name=None)`	查看指定 target 的标定状态	`name: str \| TargetName \| None = None`；省略时要求 target 唯一	`CalibrationReadiness`	SDK 创建后	target 未找到或歧义
`GloveDevice.capture_status(package_ids, operator_id)`	检查该设备的手动采集是否可以开始	`package_ids: Sequence[str]`、`operator_id: str`，均必填	`CaptureReadiness`	创建 Capture Session 前	`InvalidArgumentError`、`WorkflowError`
`GloveDevice.start_capture(package_ids, operator_id, force=False)`	在该设备上启动手动采集	上述参数；`force: bool = False`	`CaptureSession`	准备开始采集时	`InvalidArgumentError`、`WorkflowError`
`GloveDevice.start_calibration(completed_capture_session, targets)`	用该设备已完成的采集启动标定	`completed_capture_session: CaptureSession`；`targets` 为非空 target 序列，均必填	`CalibrationSession`	Capture 完成且 Session 保持打开	Session 或 target 验证错误
`GloveDevice.capture_progress()`	读取当前 Capture 进度	无	`ReadChannel[CaptureProgress]`	external 交互流程	生命周期或关闭错误
`GloveDevice.capture_control()`	提交 Capture 确认、跳过、重试或取消	无	`CaptureControl`	external 交互流程	生命周期或控制请求错误
`GloveDevice.calibration_progress(name=None)`	读取指定 target 的 Calibration 进度	`name: str \| TargetName \| None = None`；省略时要求 target 唯一	`ReadChannel[CalibrationProgress]`	标定观察期间	target 未找到或歧义

Sdk、Glove 和 GloveDevice 仍提供 connect() 与 disconnect()。connect() 仅为兼容旧代码保留，不会打开设备；disconnect() 等同于 stop()。新代码直接使用 start() 和 stop()。

数据读取与订阅

StateChannel[T] 继承 ReadChannel[T] 的读取能力，同样支持 latest()、subscribe()、next() 和异步迭代，并额外提供 set() 和 clear()。

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`ReadChannel.latest()`	读取最近一条数据且不等待	无	`Sample[T] \| None`	所属对象未关闭	关闭错误
`ReadChannel.subscribe(callback)`	每次收到新数据时执行 callback	`callback: Callable[[Sample[T]], None]`，必填	`Subscription`	建议在 start 前注册	参数或关闭错误
`ReadChannel.next()` / 异步迭代	异步等待下一条或持续读取数据	无	awaitable `Sample[T]` / `AsyncIterator[Sample[T]]`	所属对象运行期间	取消、关闭或数据流错误
`StateChannel.set(value)`	更新当前震动设置	`value: Haptics`，必填	`None`	设备已连接且能力受支持	参数、拒绝或断连错误
`StateChannel.clear()`	清除当前震动设置	无	`None`	设备已连接且能力受支持	拒绝或断连错误
`Subscription.unsubscribe()`	提前停止一个 callback	无	`None`	SDK 继续运行但不再需要该 callback 时	callback 内同步取消不安全

Capture/Calibration 会话

API	用途	参数、类型与默认值	返回值	调用时机	主要错误
`CaptureControl.confirm()` / `CaptureControl.skip()` / `CaptureControl.cancel()`	确认、跳过或取消当前 Capture 请求	`request_id: str`，必填	`None`	external 交互收到当前请求后	空、过期或不适用于当前状态的请求
`CaptureControl.retry()`	重新执行一个 Capture 阶段	`stage_id: str`，必填	`None`	external 交互需要重试阶段时	空、未知或当前不可重试的阶段
`CaptureSession`	控制手动采集并读取状态或结果	`confirm(request_id)`、`skip(request_id)`、`retry(stage_id)`、`cancel()`、`snapshot()`、`result()`、`close()`	状态、结果或 `None`	Session 打开期间	过期请求、无效阶段、关闭错误
`CalibrationSession`	控制手动标定并读取或等待结果	`snapshot()`、`result()`、`wait()`、`cancel()`、`close()`	状态、可选结果或结果 tuple	Session 打开期间	工作流、取消或关闭错误

GloveDevice.capture_status(...) 的参数（设备已由 Glove.device() 选定，不再传 source 或 side）：

参数	类型	必填/默认	说明与约束
`package_ids`	`Sequence[str]`	必填	非空算法包 ID 序列；同时查询多个包时按本次实际需要传入
`operator_id`	`str`	必填	非空佩戴者标识，用于查找该佩戴者可复用的采集

GloveDevice.start_capture(...) 的参数：

参数	类型	必填/默认	说明与约束
`package_ids`	`Sequence[str]`	必填	非空算法包 ID 序列，决定本次需要完成的采集计划
`operator_id`	`str`	必填	非空佩戴者标识；后续标定结果与该佩戴者关联
`force`	`bool`	默认 `False`	`False` 复用可用采集；`True` 忽略可复用采集并重新完成当前计划

GloveDevice.start_calibration(...) 的参数：

参数	类型	必填/默认	说明与约束
`completed_capture_session`	`CaptureSession`	必填	必须由同一个 `Sdk` 创建、已经完成且仍保持打开
`targets`	`Sequence[str \| TargetName \| None]`	必填	非空且不能重复；名称选择已配置 target，`None` 选择唯一未命名 target，Skeleton 使用 `TargetName.SKELETON`

数据与结果模型

以下表格说明公开 API 接收或返回的数据。表中的“可为空”表示该字段是否可能为 None；空序列或空映射会在说明中单独指出。

`TelemetryMeta`

TelemetryMeta 是手套原始数据附带的来源和帧信息，作为 GlovePose.meta、GloveImu.meta 等字段出现。它同时覆盖实体手套数据和通过 ExternalConnection 提交的外部输入，便于关联 source、设备时间与帧标识。

字段	类型	可为空	说明
`source`	`str`	否	产生这条数据的 source ID
`timestamp`	`float`	否	数据时间戳
`sequence`	`int \| None`	是	设备或数据源提供的序号
`frame_id`	`str \| None`	是	设备或数据源提供的帧标识

latest() 和 next() 取得 Sample[T]；subscribe() 返回 Subscription，注册的 callback 接收 Sample[T]。T 是 GlovePose、GloveImu、HandJointCommand 或 GloveStatus 等具体数据类型；value 保存该数据，其余字段描述 SDK 发布序号和时间。

字段	类型	可为空	说明
`value`	`T`	否	当前业务数据
`sequence`	`int`	否	同一类数据中单调递增的 SDK 序号
`source_time`	`float \| None`	是	数据源时间；数据源没有提供时为 `None`
`observed_at`	`float`	否	SDK 接收到数据的时间

source_time 与 observed_at 都不是系统日历时间。

`DiscoveredGlove`

DiscoveredGlove 是 discover_gloves() 返回的单个发现结果，用于查看候选设备的端口、左右手、SN 和该端口的发现错误。

字段	类型	可为空	说明
`port`	`str`	否	发现的串口路径
`hand`	`Side \| None`	是	成功识别的左右手；识别失败时可能不存在
`sn`	`str \| None`	是	成功读取的设备 SN
`error`	`GloveDiscoveryIssue \| None`	是	该端口的发现错误；成功时为 `None`

`GloveDiscoveryIssue`

GloveDiscoveryIssue 作为 DiscoveredGlove.error 出现，说明某个候选端口为什么没有完成身份读取。程序应按稳定的 code 分类处理，message 仅用于展示或记录。

字段	类型	可为空	说明
`code`	`GloveDiscoveryErrorCode`	否	稳定的错误分类，应使用它判断失败原因
`message`	`str`	否	面向日志或界面展示的错误说明，不用于程序分支判断

`DeviceInfo`

DeviceInfo 由 get_device_info() 返回，是 SDK 创建期间保存的已验证设备身份快照。它用于展示或记录设备的规范 SN、型号、固件版本和左右手信息。

字段	类型	可为空	说明
`canonical_sn`	`str`	否	经过设备身份验证的规范 SN
`device_type`	`str`	否	设备类型
`model`	`str`	否	设备型号
`firmware_version`	`str`	否	固件版本
`hand`	`Side`	否	设备左右手
`hand_source`	`str`	否	左右手信息的来源

`GloveNodePose`

GloveNodePose 表示一个手部节点的位置和旋转。它既用于构造 ExternalGloveFrame 的指尖输入，也作为 GloveFeaturePayload 中根节点和指尖姿态的字段类型。

字段	类型	可为空	说明
`position`	`tuple[float, float, float]`	否	三维位置，单位为米
`quaternion_xyzw`	`tuple[float, float, float, float]`	否	XYZW 顺序的旋转四元数

`ExternalGloveFrame`

ExternalGloveFrame 是传给 push_frame() 的外部手部帧，用于在没有实体手套输入时提交五个指尖的姿态和可选时间戳。

字段	类型	可为空	说明
`thumb`	`GloveNodePose`	否	拇指指尖姿态
`index`	`GloveNodePose`	否	食指指尖姿态
`middle`	`GloveNodePose`	否	中指指尖姿态
`ring`	`GloveNodePose`	否	无名指指尖姿态
`pinky`	`GloveNodePose`	否	小指指尖姿态
`timestamp_ms`	`float \| None`	是	推荐输入；有限的毫秒时间戳，省略时沿用当前共享时间基准；时间语义见时间戳与外部授时
`timestamp_sec`	`float \| None`	是	已废弃的兼容输入；SDK 会乘以 `1000` 转为毫秒，不得与 `timestamp_ms` 同时设置

`GloveFeaturePayload`

GloveFeaturePayload 是 GlovePose.payload 的内容，保存一帧手套原始姿态中的根节点、五指姿态和有效性信息。

字段	类型	可为空	说明
`glove_id`	`str`	否	手套数据标识
`timestamp_ms`	`float`	否	设备数据时间，单位为毫秒
`root_pose`	`GloveNodePose`	否	手部根节点姿态
`fingertip_world`	`dict[GloveFinger, GloveNodePose]`	否	五指指尖在世界坐标系中的姿态
`fingertip_local`	`dict[GloveFinger, GloveNodePose]`	否	五指指尖相对根节点的局部姿态
`hand_side`	`str`	否	帧中报告的左右手
`finger_names`	`tuple[GloveFinger, ...]`	否	当前帧包含的手指顺序
`raw_valid_mask`	`dict[GloveFinger, bool]`	否	各手指原始数据是否有效
`held_mask`	`dict[GloveFinger, bool]`	否	各手指是否沿用上一条有效值
`quality_flags`	`tuple[str, ...]`	否	当前帧的质量标记，可为空序列

`GlovePose`

GlovePose 是 device.pose() 发布的手套原始姿态，也是 push_frame() 接受外部帧后返回的解析结果。它组合来源信息、姿态内容和可扩展质量信息。

字段	类型	可为空	说明
`meta`	`TelemetryMeta`	否	source、时间和帧标识
`payload`	`GloveFeaturePayload`	否	根节点、指尖和质量状态
`quality`	`dict[str, object]`	否	可扩展质量信息，可为空映射

`GloveImuPayload`

GloveImuPayload 是 GloveImu.payload 的内容，保存一帧 IMU 的有效状态、三轴陀螺仪计数和三轴加速度计计数。

字段	类型	可为空	说明
`valid`	`bool`	否	当前 IMU 原始计数是否有效
`gyroscope_raw`	`tuple[int, int, int]`	否	三轴陀螺仪原始计数
`accelerometer_raw`	`tuple[int, int, int]`	否	三轴加速度计原始计数

`GloveImu`

GloveImu 是 device.imu() 发布的 IMU 原始数据，组合来源信息、六轴原始计数和可扩展质量信息。

字段	类型	可为空	说明
`meta`	`TelemetryMeta`	否	source、时间和帧标识
`payload`	`GloveImuPayload`	否	有效状态及六轴原始计数
`quality`	`dict[str, object]`	否	可扩展质量信息，可为空映射

`HandJointCommand`

HandJointCommand 表示一组关节角输出，包含 target、关节名到角度的映射、输出时间、可选 source 和 metadata。device.output() 与 skeleton().joint_angles() 都提供这类数据的读取；每次读取获得 Sample[HandJointCommand]，其中 sample.value 才是 HandJointCommand。该类型本身不规定固定的关节名称和数量。

字段	类型	可为空	说明
`target`	`str`	否	目标标识
`joints`	`dict[str, float]`	否	关节名称到目标位置的映射
`timestamp`	`float`	否	输出时间戳
`source`	`str \| None`	是	产生该输出的 source ID
`metadata`	`dict[str, object]`	否	算法附加信息，可为空映射

Skeleton 固定关节

当数据来自 skeleton().joint_angles() 时，HandJointCommand.joints 固定包含以下 25 个 active joints。名称中的 <side> 替换为 left 或 right；你的代码应按关节名读取，不能依赖 JSON/字典的键遍历顺序。

索引	关节名
0	`<side>_thumb_cmc_abduction`
1	`<side>_thumb_cmc_flexion`
2	`<side>_thumb_cmc_opposition`
3	`<side>_thumb_mcp_abduction`
4	`<side>_thumb_mcp_flexion`
5	`<side>_thumb_ip_flexion`
6	`<side>_index_mcp_abduction`
7	`<side>_index_mcp_flexion`
8	`<side>_index_pip_flexion`
9	`<side>_index_dip_flexion`
10	`<side>_middle_mcp_abduction`
11	`<side>_middle_mcp_flexion`
12	`<side>_middle_pip_flexion`
13	`<side>_middle_dip_flexion`
14	`<side>_ring_cmc_cup`
15	`<side>_ring_mcp_abduction`
16	`<side>_ring_mcp_flexion`
17	`<side>_ring_pip_flexion`
18	`<side>_ring_dip_flexion`
19	`<side>_little_cmc_opposition`
20	`<side>_little_cmc_cup`
21	`<side>_little_mcp_abduction`
22	`<side>_little_mcp_flexion`
23	`<side>_little_pip_flexion`
24	`<side>_little_dip_flexion`

device.output() 提供的灵巧手输出仍使用 HandJointCommand，但关节名称和数量由对应灵巧手算法包定义，不使用上述 Skeleton 固定列表。

`HandSkeletonPose`

HandSkeletonPose 是 skeleton().pose() 发布的 OpenXR 骨骼节点姿态，用于按相同索引读取 25 个节点的名称、位置和旋转。

字段	类型	可为空	说明
`timestamp_ms`	`float`	否	骨骼输出时间，单位为毫秒
`hand_side`	`Side`	否	左右手
`coordinate_frame`	`str`	否	当前为 `wrist_local`
`names`	`tuple[str, ...]`	否	25 个骨骼节点名称，顺序与位置和旋转数组一致
`positions_local`	`tuple[tuple[float, float, float], ...]`	否	25 个 wrist-local 节点位置
`orientations_local_xyzw`	`tuple[tuple[float, float, float, float], ...]`	否	25 个 wrist-local 节点 XYZW 四元数

`Haptics`

Haptics 同时用于 set() 的输入，以及 latest() 和 subscribe() 取得的震动输出状态。device.haptics() 返回指尖震动控制和读取入口，不直接返回 Haptics。

字段	类型	可为空	说明
`strengths`	`dict[GloveFinger, int]`	否	手指到 `0..100` 整数震动强度的映射；可为空映射，未列出的手指不包含在当前震动设置中

`GloveStatus`

GloveStatus 是 device.status() 发布的设备状态，用于观察当前连接、数据是否过期、最近错误和成功恢复次数。

字段	类型	可为空	说明
`device_type`	`str`	否	设备类型
`connected`	`bool`	否	当前是否已连接
`stale`	`bool`	否	当前数据是否已经过期或尚未开始流动
`timestamp`	`float`	否	状态时间戳
`last_error`	`str \| None`	是	最近一次设备错误；没有错误时为 `None`
`reconnect_count`	`int`	否	成功恢复连接的累计次数
`fields`	`dict[str, object]`	否	设备类型相关的附加状态，可为空映射

`DeviceHealth`

DeviceHealth 是 Health.devices 中每条 source 对应的设备健康摘要，用于同时查看多只手套的连接、数据时效和最近错误。

字段	类型	可为空	说明
`connected`	`bool`	否	设备是否已连接
`stale`	`bool`	否	设备数据是否过期或尚未开始流动
`last_error`	`str \| None`	是	最近一次设备错误

`Health`

Health 由 sdk.health() 或 glove.health() 返回，用于汇总 SDK 或全部手套的告警、错误、设备状态和调度状态。

字段	类型	可为空	说明
`ok`	`bool`	否	当前汇总状态是否健康
`warning_count`	`int`	否	当前汇总中的告警数量
`error_count`	`int`	否	当前汇总中的错误数量
`devices`	`dict[str, DeviceHealth]`	否	source ID 到设备健康状态的映射
`last_error`	`str \| None`	是	最近一次 SDK 错误
`runtime_overrun`	`bool`	否	SDK 调度是否发生过超时
`topic_callback_error`	`bool`	否	callback 是否发生过未处理异常

`CalibrationReadiness`

CalibrationReadiness 由 device.calibration_status() 返回，用于判断指定 target 对当前佩戴者是否无需标定、可以直接使用或需要重新标定。

字段	类型	可为空	说明
`state`	`CalibrationReadinessState`	否	`NOT_REQUIRED`、`READY` 或 `NEEDS_CALIBRATION`
`operator_id`	`str`	否	本次判断使用的佩戴者标识

`UpdateResult`

UpdateResult 由 sdk.update() 或 glove.update() 返回，用于查看本次手动调度执行了多少任务、是否仍有后续任务，并等待下一项任务到期。

字段	类型	可为空	说明
`tick`	`int`	否	当前更新序号
`ran_task_count`	`int`	否	本次执行的任务数量
`has_next_task`	`bool`	否	是否还有后续调度任务
`sleep()`	`() -> SleepResult`	—	等待下一项任务到期；每个结果只能调用一次

Capture 模型

Capture 类型共同描述采集计划、开始前的准备状态、运行进度、Session 快照和最终结果。

`CapturePlanStage`

CapturePlanStage 是 CapturePlan.stages 中的一个动作阶段，用于告诉程序应展示什么动作、需要采集多少样本以及是否允许跳过。

字段	类型	可为空	说明
`stage_id`	`str`	否	动作阶段标识
`prompt`	`str`	否	展示给佩戴者的动作提示
`required_sample_count`	`int`	否	完成阶段需要的样本数
`optional`	`bool`	否	是否允许跳过

`CapturePlan`

CapturePlan 作为 CaptureReadiness.plan 和 CaptureSessionSnapshot.plan 出现，说明本次 Capture 涉及哪些算法包以及阶段执行顺序。

字段	类型	可为空	说明
`package_ids`	`tuple[str, ...]`	否	本次计划覆盖的算法包 ID
`stages`	`tuple[CapturePlanStage, ...]`	否	按顺序执行的采集阶段

`CaptureStageReadiness`

CaptureStageReadiness 是 CaptureReadiness.stages 中一个阶段的准备状态，用于判断该阶段可复用已有数据还是需要重新采集。

字段	类型	可为空	说明
`stage_id`	`str`	否	阶段标识
`required_sample_count`	`int`	否	所需样本数
`state`	`CaptureStageReadinessState`	否	`REUSABLE` 或 `NEEDS_CAPTURE`

`CaptureReadiness`

CaptureReadiness 由 GloveDevice.capture_status() 返回，用于在创建 Capture Session 前查看整体准备状态、采集计划和各阶段是否需要采集。

字段	类型	可为空	说明
`state`	`CaptureReadinessState`	否	`NOT_REQUIRED`、`READY` 或 `NEEDS_CAPTURE`
`plan`	`CapturePlan`	否	解析后的采集计划
`stages`	`tuple[CaptureStageReadiness, ...]`	否	各阶段准备状态

`CaptureStageProgress`

CaptureStageProgress 作为 CaptureProgress.stage 和 CaptureSessionSnapshot.stage_progress 的元素出现，用于驱动动作提示、样本进度和当前允许的交互。

字段	类型	可为空	说明
`stage_id`	`str`	否	当前阶段标识
`prompt`	`str`	否	当前动作提示
`optional`	`bool`	否	当前阶段是否允许跳过
`state`	`CaptureStageState`	否	当前阶段状态
`origin`	`CaptureStageOrigin`	否	新采集或复用已有采集
`collected_sample_count`	`int`	否	已采集样本数
`required_sample_count`	`int`	否	所需样本数
`request_id`	`str \| None`	是	当前确认或控制请求标识

`CaptureFailure`

CaptureFailure 作为 CaptureProgress.failure 和 CaptureSessionSnapshot.failure 出现，用稳定代码和可读消息说明 Capture Session 的失败原因。

字段	类型	可为空	说明
`code`	`str`	否	稳定失败代码
`message`	`str`	否	展示或记录用失败说明

`CaptureProgress`

CaptureProgress 由 device.capture_progress() 发布，用于外部交互界面持续显示当前 source、佩戴者、Session 状态和动作阶段。

字段	类型	可为空	说明
`session_id`	`str`	否	Capture Session 标识
`session_state`	`CaptureSessionState`	否	Session 状态
`failure`	`CaptureFailure \| None`	是	Session 失败信息
`source_id`	`str`	否	采集使用的 source ID
`side`	`Side`	否	采集左右手
`operator_id`	`str`	否	佩戴者标识
`stage`	`CaptureStageProgress`	否	当前阶段进度

`CaptureSessionSnapshot`

CaptureSessionSnapshot 由 CaptureSession.snapshot() 返回，是手动 Capture Session 的当前完整快照，用于显示进度并决定下一项允许的操作。

字段	类型	可为空	说明
`side`	`Side`	否	采集左右手
`plan`	`CapturePlan`	否	本次采集计划
`state`	`CaptureSessionState`	否	Session 状态
`current_stage`	`str \| None`	是	当前阶段标识
`request_id`	`str \| None`	是	当前控制请求标识
`collected_sample_count`	`int`	否	当前阶段已采集样本数
`required_sample_count`	`int`	否	当前阶段所需样本数
`remaining_stages`	`tuple[str, ...]`	否	尚未完成的阶段
`stage_progress`	`tuple[CaptureStageProgress, ...]`	否	全部阶段进度
`allowed_operations`	`tuple[CaptureControlAction, ...]`	否	当前允许的控制操作
`next_action`	`str`	否	下一步操作提示
`failure`	`CaptureFailure \| None`	是	Session 失败信息

`CaptureStageSamples`

CaptureStageSamples 是 CaptureResult.stage_samples 中一个阶段的采集摘要，用于查看该阶段最终保存了多少帧。

字段	类型	可为空	说明
`stage_id`	`str`	否	阶段标识
`frame_count`	`int`	否	该阶段保存的帧数

`CaptureResult`

CaptureSession.result() 返回 CaptureResult | None：Session 完成后得到本次采集结果，尚未完成时得到 None。CaptureResult 记录本次采集的佩戴者、左右手、完成时间和各阶段帧数摘要。

字段	类型	可为空	说明
`operator_id`	`str`	否	佩戴者标识
`side`	`Side`	否	采集左右手
`created_at`	`float`	否	采集结果创建时间
`stage_samples`	`tuple[CaptureStageSamples, ...]`	否	各阶段保存的帧数摘要

Capture 会话相关枚举的取值：

枚举	取值
`CaptureSessionState`	`RUNNING`、`COMPLETED`、`FAILED`、`CANCELLED`
`CaptureStageState`	`PENDING`、`AWAITING_CONFIRMATION`、`COLLECTING`、`COMPLETED`、`SKIPPED`
`CaptureStageOrigin`	`NEW_CAPTURE`、`REUSED`
`CaptureControlAction`	`CONFIRM`、`RETRY`、`SKIP`、`CANCEL`

Calibration 模型

Calibration 类型按 target 描述计算进度，并提供整个 Session 的快照和最终结果。

`CalibrationJobFailure`

CalibrationJobFailure 作为 CalibrationJobProgress.failure 出现，用稳定代码和可读消息说明某个 target 的标定失败原因。

字段	类型	可为空	说明
`code`	`str`	否	稳定失败代码
`message`	`str`	否	展示或记录用失败说明

`CalibrationJobProgress`

CalibrationJobProgress 作为 CalibrationProgress.job 和 CalibrationSessionSnapshot.jobs 的元素出现，用于查看单个 target 的标定状态和失败信息。

字段	类型	可为空	说明
`target_id`	`str`	否	target 标识
`state`	`CalibrationJobState`	否	当前 target 的标定状态
`failure`	`CalibrationJobFailure \| None`	是	当前 target 的失败信息

`CalibrationProgress`

CalibrationProgress 由 device.calibration_progress() 发布，用于外部交互界面持续显示一个 target 在当前 Calibration Session 中的计算状态。

字段	类型	可为空	说明
`session_id`	`str`	否	Calibration Session 标识
`source_id`	`str`	否	标定使用的 source ID
`job`	`CalibrationJobProgress`	否	当前 target 的标定进度

`CalibrationSessionSnapshot`

CalibrationSessionSnapshot 由 CalibrationSession.snapshot() 返回，用于一次查看整个 Session 及其全部 target 的当前状态。

字段	类型	可为空	说明
`state`	`CalibrationSessionState`	否	Session 状态
`jobs`	`tuple[CalibrationJobProgress, ...]`	否	按 targets 顺序排列的任务状态

`CalibrationResult`

CalibrationResult 是标定结果集合中的单个 target 结果，用于记录已保存标定的记录 ID、source、target 和创建时间。CalibrationSession.result() 返回 tuple[CalibrationResult, ...] | None，wait() 返回 tuple[CalibrationResult, ...]。

字段	类型	可为空	说明
`record_id`	`str`	否	保存后的标定记录标识
`source_id`	`str`	否	标定使用的 source ID
`target_id`	`str`	否	标定对应的 target ID
`created_at`	`float`	否	标定结果创建时间

CalibrationSessionState 和 CalibrationJobState 的值均为 RUNNING、COMPLETED、FAILED、CANCELLED，其中 CalibrationJobState 还包含等待执行的 PENDING。