配置字段速查 | Qnbot Docs Center

`GloveConfig`

字段	类型	默认值
`side`	`Side \| None`	默认为 `None`；串口设备从已验证身份读取
`connection`	`SerialConnection \| ExternalConnection`	默认为 `SerialConnection()` 自动发现
`name`	`str \| None`	默认为 `None`
`enabled`	`bool`	默认为 `True`

side：external input 必填
side：显式值必须与设备或输入帧一致
connection：串口用于实体手套
connection：external 用于逐帧外部输入
name：提供时必须为非空名称且在启用设备中唯一
name：多设备建议显式命名
enabled：False 时不连接、不启动、不可选择，也不能作为 target source

`SerialConnection`

字段	类型	默认值
`auto_discover`	`bool`	未提供任何定位字段时自动变为 `True`
`port`	`str \| None`	默认为 `None`
`serial_number`	`str \| None`	默认为 `None`
`baudrate`	`int \| None`	默认为 `None`，使用 SDK 默认值

auto_discover：与 port、serial_number 三选一
auto_discover：发现结果必须唯一且通过身份校验
port：指定串口
port：只有同时提供 GloveConfig.side、端口被识别为受支持的有线直连手套且旧固件不支持 id 时，才可使用配置身份
serial_number：按 USB 序列号发现，始终要求有效设备身份，不能使用旧固件回退
baudrate：提供时必须是 1 到 4294967295 之间的整数

`ExternalConnection`

ExternalConnection 没有配置字段，但要求 GloveConfig.side 必填。

`TargetConfig`

字段	类型	默认值
`type`	`TargetType \| None`	候选唯一时推导
`name`	`str \| None`	保持省略，不从包资源生成
`side`	`Side \| None`	候选唯一时推导
`source`	`DeviceSelector \| None`	候选唯一时推导
`algorithms`	`Sequence[TargetAlgorithm]`	默认为空序列

type：显式值用于缩小并校验候选
type：当前公开值为 HAND、ARM
name：调用方定义的 output 实例名
name：同一 target ID 不可重复，保留名 skeleton 不可作为普通 target 名
side：显式值必须与 source 和算法能力兼容
source：零候选或多候选都会使 SDK 创建失败
algorithms：按配置顺序执行
algorithms：空序列表示直接传递输入

`DeviceSelector`

字段	类型	默认值
`type`	`str`	无默认值
`name`	`str \| None`	默认为 `None`
`side`	`Side \| None`	默认为 `None`

type：必须是非空设备类型
type：手套使用 "glove"
name：与配置中的设备名匹配
side：与设备物理侧匹配
side：组合条件必须唯一选择一个启用 source

`TargetAlgorithm`

字段	类型	默认值
`id`	`str`	无默认值

id：必须是非空算法包 ID，且对应包已安装完成并兼容当前平台和 SDK

`AlgorithmsConfig`

字段	类型	默认值
`calibration`	`CalibrationConfig`	默认为 `CalibrationConfig()`
`capture`	`CaptureConfig`	默认为 `CaptureConfig()`

calibration：控制是否重新计算标定
capture：控制交互方式、佩戴者标识与是否复用已有采集

`CaptureConfig`

字段	类型	默认值
`interaction`	`CaptureInteractionMode`	默认为 `AUTO_TERMINAL`
`force`	`bool`	默认为 `False`
`operator_id`	`str`	默认为 `"default"`

interaction：AUTO_TERMINAL 适合前台终端
interaction：GUI、远程或无 TTY 宿主使用 EXTERNAL 并处理 Capture 控制
force：True 时忽略可复用原始帧并重新采样
force：不是持续采集，也不会在每次 update 时重新采样
operator_id：必须是非空字符串
operator_id：作为佩戴者标识，用于分别查找和保存不同佩戴者的标定记录

`CalibrationConfig`

字段	类型	默认值
`force`	`bool`	默认为 `False`

force：True 时使用当前可用采集重新计算标定，不强制重新采样
force：成功后同一个 SDK 在 stop 或重连时复用新结果；下次创建 SDK 时若仍设为 True 会再次计算

两个 force 不可互换：要重新采样，设置 CaptureConfig.force；只重新计算标定，设置 CalibrationConfig.force。

`DebugConfig`

字段	类型	默认值
`modules`	`Sequence[DebugModule]`	默认为空
`detail`	`DebugDetail`	默认为 `SUMMARY`
`sample_rate`	`int \| None`	默认为 `None`，普通事件不采样

modules：可选 TRANSPORT、DEVICE、CAPTURE、CALIBRATION、RETARGETING、OUTPUT
detail：只能是 SUMMARY 或 FULL
detail：FULL 记录更多运行数据，日志量更大
sample_rate：提供时必须是正 uint32
sample_rate：值 N 表示每 N 条记录一条，重要事件不丢弃

`SdkConfig` 与 `Sdk(...)`

字段	类型	默认值
`devices`	`Sequence[DeviceConfig]`	`SdkConfig` 必填；`Sdk(...)` 省略时等同空序列
`targets`	`Sequence[TargetConfig]`	默认为空序列
`debug`	`DebugConfig \| None`	默认为 `None`，不创建 Debug 日志
`algorithms`	`AlgorithmsConfig`	使用默认配置

devices：每项必须是公开设备配置
devices：启用设备名称和最终 source 必须唯一
targets：每个 target 必须能解析到启用 source
targets：重复、歧义或不兼容时创建失败
debug：提供后启用该 SDK 实例的 Debug 日志
algorithms：控制 Capture 和 Calibration 行为，不负责安装算法包

应用数据目录

不设置 QNBOT_HOME 时，SDK 使用 ~/.qnbot 作为应用数据根目录。

设置该环境变量可以改用其他目录。标定记录保存在 <QNBOT_HOME>/glove/calibrations，Debug 日志保存在 <QNBOT_HOME>/logs。

设置时机：必须在创建 Sdk 前
取值一致性：CLI 与 SDK 应使用相同的值，否则 SDK 可能找不到 CLI 已安装的算法包

终端输出与交互

不设置任何内容时，内置终端只在交互式 TTY 中启用级别颜色：Error 标签红色加粗，Warning 标签黄色，Info 标签使用终端默认前景色，Success 的关键结果使用绿色。只着色级别标签和关键结果，不会把整段消息染色。Debug 日志和诊断 JSON 始终不包含 ANSI 颜色。

NO_COLOR 设置后消息保持纯文本；QNBOT_INTERACTIVE_CONSOLE=1 告诉 SDK 当前控制台可以接收用户输入；PYCHARM_HOSTED=1 由 JetBrains 设置，表示 JetBrains Python Run/Debug Console 即使使用 pipe 也按可接收输入的控制台处理。

着色范围：只着色级别标签与关键结果，不染色整段消息
非 TTY：输出被重定向、通过 pipe 传递或运行在其他非 TTY 环境时，行为与设置 NO_COLOR 相同
仅设置 TERM：不会让 SDK 认为控制台可以接收输入
interaction mode：这些变量不改变配置中的 interaction mode；要接管交互仍需把 CaptureConfig.interaction 设为 EXTERNAL，见采集