配置字段速查

source、target、算法、标定和 Debug 配置必须在创建 Sdk 时一次性提供，现有 SDK 不支持动态增删或修改。配置或已安装算法包发生变化后，应关闭并重新创建 Sdk。

只读取手套姿态时，从最小配置开始即可。需要 retargeting 输出时，先配置 target，再在其中指定算法包；标定与 Debug 按应用需要启用。

source 配置

GloveConfig

• name：提供时必须是非空名称，且在启用设备中唯一。
• name：选择已明确时可以不填。
• side：外部输入时必填。
• side：显式值必须与设备或输入帧一致。
• connection：串口用于实体手套。
• connection：ExternalConnection 用于应用逐帧输入。
• enabled：false 时不连接、不启动、不可选择，也不能作为 target source。

SerialConnection

• auto_discover：与 port、serial_number 三选一。
• auto_discover：发现结果必须唯一且通过身份校验。
• port：指定串口。
• port：只有满足下述 port + side 条件时才允许旧固件身份回退。
• serial_number：按 USB 序列号发现，始终要求有效设备身份。
• baudrate：提供时必须为正整数。

auto_discover、port 与 serial_number 必须三选一；三个定位字段都省略时按自动发现处理。只提供 port 时必须从设备身份得到 side；只提供 side 或两者都不提供时仍走自动发现并严格校验身份；使用 serial_number 时也不回退。

ExternalConnection

ExternalConnection 没有配置字段。使用它时 GloveConfig::side 必填，应用提交的每一帧必须与该 side 一致；它不执行串口发现，也不支持设备信息、震动反馈或其他实体设备控制。

target 配置

TargetConfig

• type：显式值用于缩小并校验候选。
• type：当前公开值为 hand、arm。
• name：提供时必须是非空名称。
• name：保留名 skeleton 不可用于普通 target。
• side：显式值必须与 source 和算法能力兼容。
• source：零候选或多候选都会使 SDK 创建失败。
• algorithms：按声明顺序执行。
• algorithms：空列表表示直接传递输入。

DeviceSelector

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

TargetAlgorithm

• id：必须是非空算法包 ID。
• id：对应包必须已通过 Qnbot CLI 安装。
• id：对应包必须兼容当前平台和 SDK。

自定义 retargeting 包需要在创建 Sdk 前通过 Qnbot CLI 安装。安装步骤见下方的 算法包配置。

单手套、单 target 场景可以只声明算法：

qnbot::TargetConfig target_config;
target_config.algorithms = {
    qnbot::TargetAlgorithm{"<package-id>"},
};

type、side 和 source 可省略，并仅在候选唯一时推导；省略的 name 保持省略。固定部署可以显式提供约束：

qnbot::TargetConfig target_config;
target_config.source = qnbot::DeviceSelector{
    "glove", std::string("primary"), std::nullopt,
};
target_config.name = "dexhand";
target_config.side = qnbot::Side::right;
target_config.algorithms.push_back(qnbot::TargetAlgorithm{"<package-id>"});

TargetAlgorithm 只包含 id，其值是已安装算法包的包 ID。SDK 使用配置中指定且已通过产品 CLI 安装的算法包；它不会安装算法包。

省略 algorithms 或使用空列表表示不执行转换算法，直接传递输入。一个 source 可以配置多个 target；读取多个输出时，按应用提供的实例名选择对应输出。省略的公开实例名保持省略，不会根据算法包自动生成。包 ID 负责选择算法包，包内资源名称不会覆盖、生成或约束实例名；TargetConfig::name 只由应用定义，并用于按实例名读取输出。

采集与标定配置（可选）

通常不需要显式配置标定。如果所选 retargeting 算法需要标定，SDK 会在运行时引导操作，并在后续运行中复用已保存的标定记录。

需要区分佩戴者时，再提供标定配置：

qnbot::SdkConfig config;
config.algorithms.capture.operator_id = "operator-a";

GUI 或远程应用需要自行呈现标定交互时，参见外部接管引导交互。

AlgorithmsConfig

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

CaptureConfig

• force：true 时忽略可复用原始帧并重新采样。
• force：不是持续采集，也不会在每次 update 时重新采样。
• interaction：终端程序使用 auto_terminal。
• interaction：GUI、远程或无 TTY 应用使用 external，并处理采集控制。
• operator_id：必须是非空字符串。
• operator_id：用于区分不同佩戴者的标定记录。

CalibrationConfig

• force：true 时使用当前可用采集重新计算标定。
• force：不强制重新采样。
• force：成功后同一实例在 stop 或重连时复用新结果；新建的 forced 实例会再次计算。
• force：忽略本实例创建前已有的兼容记录，并为每个 target 强制标定一次。

Debug 配置（可选）

省略 Debug 配置时不会生成日志。需要排查运行问题时，可选择记录的模块和采样率：

qnbot::DebugConfig debug_config{
    {qnbot::DebugModule::transport, qnbot::DebugModule::device,
     qnbot::DebugModule::capture, qnbot::DebugModule::calibration,
     qnbot::DebugModule::retargeting, qnbot::DebugModule::output},
    qnbot::DebugDetail::summary,
    10,
};

DebugConfig

• modules：可选 transport、device、capture、calibration、retargeting、output。
• detail：summary 适合普通问题排查。
• detail：full 数据更多，且可能包含敏感值。
• sample_rate：必须是正整数。
• sample_rate：值 N 表示普通记录每 N 条保留一条。

日志位置和内容范围见 Debug 日志。

完整配置

SdkConfig 与 Sdk(...)

• SdkConfig::devices：名称和最终 source 必须唯一。
• SdkConfig::targets：每个 target 必须能唯一匹配一个启用 source。
• SdkConfig::debug：提供后为该 SDK 实例记录 Debug 日志。
• SdkConfig::algorithms：控制采集和标定。
• Sdk(SdkConfig)：配置按值移入 SDK。
• Sdk(SdkConfig)：构造期间完成设备和 target 解析。

下面组合固定设备、retargeting 算法包、target、标定和 Debug。只使用其中部分能力时，删除对应的可选配置即可：

qnbot::SerialConnection connection;
connection.serial_number = "YOUR-SERIAL-NUMBER";

qnbot::GloveConfig device_config{qnbot::Side::right, connection};
device_config.name = "primary";

qnbot::TargetConfig target_config;
target_config.name = "dexhand";
target_config.side = qnbot::Side::right;
target_config.source = qnbot::DeviceSelector{
    "glove", std::string("primary"), std::nullopt,
};
target_config.algorithms = {
    qnbot::TargetAlgorithm{"<package-id>"},
};

qnbot::SdkConfig config;
config.devices = {device_config};
config.targets = {target_config};
config.algorithms.capture.operator_id = "operator-a";
config.algorithms.capture.force = false;

qnbot::DebugConfig debug_config{
    {qnbot::DebugModule::transport, qnbot::DebugModule::device,
     qnbot::DebugModule::capture, qnbot::DebugModule::calibration,
     qnbot::DebugModule::retargeting, qnbot::DebugModule::output},
    qnbot::DebugDetail::summary,
    10,
};
config.debug = debug_config;

qnbot::Sdk sdk(std::move(config));

应用数据目录

不设置 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，见 采集