每一节的处理步骤都无效时，先按 Debug 日志 复现一次，再把这次运行的日志连同终端输出提供给我们的技术支持。

装不上 SDK 或算法包

确认 Python 版本和平台在支持范围内，pip install qnbot-sdk-glove 没有报错；完整要求见 安装与环境要求。

确认算法包在创建 Sdk 前已经安装：qnbot algorithm list 能看到目标包，包 ID 与 TargetAlgorithm 一致。安装、升级和卸载见 算法包管理。

处理：装好算法包后重新创建 Sdk，运行中的实例不会热更新包列表；仍然失败时，把安装命令和报错一起附到 Debug 日志里，开启方式见 Debug 日志。

找不到设备

确认步骤：运行 discover_gloves() 查看候选串口、左右手和设备身份；已经创建 SDK 时看 device.status() 的 connected 和 last_error。

• 候选为空：检查 USB 连接和串口权限，换一个端口重试。
• 候选不唯一：用 SerialConnection(port=...) 或 serial_number=... 固定选择，或为手套配置 name / side。
• glove.device() 报 AmbiguousSelectionError：无条件选择必须得到唯一设备，存在多个候选项时改用 device(name="...") 或 device(side=Side.LEFT) 显式选择。

详细配置见 设备发现与连接。

连接成功但收不到数据

确认步骤：device.status() 的 connected 是否为 true、stale 是否一直为 true；pose().latest() 是否返回 None。

• latest() 返回 None 不是错误：它是非阻塞查询，表示对应数据还没有到达。需要等待数据时用 callback、await device.pose().next() 或 async for sample in device.pose()。
• 原始数据：确认在 start() 前注册了 subscribe()，或启动后用 next() / async for 等待；只调用一次 latest() 不会等待。
• SDK 处理后的数据：需要选择一种 运行方式 并持续推进；target 需要先安装算法包，见 读取 Retargeting 数据。

仍然没有数据时，在 设备状态与诊断 里看 last_error 和 stale，并先打开 Debug 日志。

标定没有通过

确认步骤：device.calibration_status() 是否仍提示需要标定；capture_progress() 卡在哪个阶段；终端引导里哪个动作没有通过。

• 按提示重试失败的动作；需要重新采集用 CaptureConfig(force=True)，只重新计算标定用 CalibrationConfig(force=True)，两者含义不同。
• 外部接管流程用 capture_control() 和对应的 session 接口确认、跳过、重试或取消，见 采集。

仍然失败时，保留 Debug 日志里的 capture 与 calibration 模块输出，连同终端提示一起报告。

数据延迟或输出不更新

确认步骤：glove.health() 里的 runtime_overrun 和 topic_callback_error；SDK 调度是否一直在推进。

• 处理后的数据依赖运行方式：持续 update()，或保持 run_forever() / run_background() 运行；只等待输出而不推进调度不会产生新数据，见 运行方式。
• callback 里不要做耗时操作：SDK 收到数据后会依次执行 callback，耗时操作会耽误后续数据处理。先把数据放进业务 queue，再由工作线程处理。
• 同一次运行中混用运行方式会抛出 LifecycleError，只选一种。

Glove 是否只表示一只手套？

不是。Glove 用于管理所有已配置的手套；每个 GloveDevice 表示其中一只实体手套。

一只手套能否同时驱动多个灵巧手？

可以。为同一个 source 配置多个 target，再通过 device.output(name=...) 分别读取对应输出。手套连接和输入数据流仍然只有一份。

为什么数据读取不使用 poll_pose() 或 on_output()？

直接通过 pose()、output() 或 status() 取得相应数据，再按需要调用 latest()、 subscribe()、await next() 或使用 async for。

为什么没有 set_haptics()？

调用 device.haptics() 后，使用 set() 设置各手指的震动强度，使用 clear() 停止震动。

callback 里抛出未处理的异常会怎么样？

不会终止 SDK，后续数据仍会继续处理。如需看到异常，请在 callback 内自行捕获并记录。

能否同时调用 update() 和 run_background()？

不能。手动、当前线程和后台线程是互斥运行模型。同时启用会抛出 LifecycleError。