> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 附录

术语定义、错误码载体与版本要求集中在本页，完整说明保留在各能力章。

## 术语表

| 术语 | 说明 |
| - | - |
| 资源（resource） | 设备能力在 SDK 中的统一表示，按语义方法访问。一个资源可以是可读写参数，也可以是可订阅的 Topic，列出方式见 [SDK 用户与标定数据 — 查看所有资源](/docs/wuji-sdk/device-params/#查看所有资源) |
| Topic | 可订阅数据流的标识，一个 Topic 对应一种传感器输出或计算结果 |
| 订阅（Subscription） | 接收某个 Topic 数据的句柄，支持异步、同步非阻塞与回调三种接收方式，见 [数据订阅机制 — 订阅模式](/docs/wuji-sdk/data-subscription/#订阅模式) |
| 全局资源 | 自动聚合全部已连接设备数据的资源，通过 `SdkManager` 级 API 订阅，见 [数据订阅机制 — 跨设备合并订阅](/docs/wuji-sdk/data-subscription/#跨设备合并订阅) |
| 派生流 | 由设备源流计算得到的数据流，如 `hand_joint_angles`、`hand_skeleton`、`tip_poses` 与 `imu_data_<finger>`。派生流跟随源流降频，不能单独调节输出率 |
| 输出率（output rate） | 固件推送某条数据流的频率，调节方式见 [数据订阅机制 — 调节订阅流输出率](/docs/wuji-sdk/data-subscription/#调节订阅流输出率) |
| MCAP | 录制文件格式，多路传感器数据同步写入同一个文件，见 [数据录制与离线处理](/docs/wuji-sdk/data-recording/) |
| Episode | 一次录制会话中的独立片段，切换后写入新文件并复用已注册的通道配置，见 [数据录制与离线处理 — Episode 切换](/docs/wuji-sdk/data-recording/#episode-切换) |
| SDK 用户 | 本地参数与标定文件的隔离单位，按操作者区分存放路径，见 [SDK 用户与标定数据 — SDK 用户管理](/docs/wuji-sdk/device-params/#sdk-用户管理) |
| 手部模型标定 | 为当前 SDK 用户与左右手生成手部模型的过程，产物按用户隔离存放，见 [SDK 用户与标定数据 — 标定](/docs/wuji-sdk/device-params/#标定) |
| 手部重定向（retargeting） | 把 21 个 MediaPipe 格式人手关键点映射为 20 维关节角度命令的计算，见 [手部重定向](/docs/wuji-sdk/retargeting/) |
| 手性（Handedness） | 数据帧与设备的左右手标识，字段定义见 [通用数据类型 — Handedness](/docs/wuji-sdk/data-reference/#handedness) |
| FrameHeader | 数据帧共用的帧头，携带 `frame_id` 与 64 位微秒时间戳 `timestamp_us`，见 [通用数据类型 — FrameHeader](/docs/wuji-sdk/data-reference/#frameheader) |
| 同步偏移量（`offset_us`） | 一次时间同步算出的设备时钟与主机 UTC 时钟之差，单位微秒 |
| 往返时延（`round_trip_us`） | 一次时间同步的往返耗时，数值越小同步质量越高，见 [时间同步与坐标变换 — 同步精度](/docs/wuji-sdk/time-sync/#同步精度) |
| typed 回调 | C 接口按设备类型提供的强类型订阅回调，帧指针仅在回调期间有效，见 [C 接口参考 — 使用约束](/docs/wuji-sdk/data-reference/#使用约束) |

## 错误码索引

SDK 的错误信息分五类载体。三类设备侧码值互不相通，数值不能跨类解读。

| 错误载体 | 形态 | 产生位置 | 解读方式 |
| - | - | - | - |
| Python 异常 | `WujiException` 及更具体的子类 | 多数 Python 接口调用 | 捕获后按错误名分支，常见类型见本页 [Python 异常类型](#python-异常类型) |
| C 返回码 | `WujiStatus` 枚举 | 多数 C 接口调用 | `WUJI_STATUS_OK` 表示成功，失败后用 `wuji_last_error()` 读取当前线程的错误描述，见 [C 接口参考 — 初始化与约定](/docs/wuji-sdk/data-reference/#初始化与约定) |
| 设备故障码 | `u16` | Wuji Hand 2 关节诊断、错误状态、错误历史与编码器标定结果 | `WujiHand2.describe_error()` 或 `wuji_hand_2_describe_error()` 解码，见 [通用数据类型 — 错误码分类](/docs/wuji-sdk/data-reference/#错误码分类) |
| 编码器标定码 | `u8` | 编码器标定结果的 `enc1_error_code` 与 `enc2_error_code` | 标定专用枚举，读取结果对象的 `enc1_error_name` 与 `enc2_error_name`，不可传入解码函数，见 [通用数据类型 — 错误码分类](/docs/wuji-sdk/data-reference/#错误码分类) |
| Wuji Hand 错误码位域 | `u32` | Wuji Hand 关节诊断的 `error_code` | 每位对应一种故障，按位判读，不可传入解码函数，见 [通用数据类型 — 错误码分类](/docs/wuji-sdk/data-reference/#错误码分类) |

错误码 `0` 表示当前无故障，码表不包含该值。非零码值无法解码时保留原始数值，用于日志与故障报告。

### Python 异常类型

多数 Python 接口调用出错时抛 `WujiException`，消息携带错误类型前缀。部分接口针对文件系统或参数校验错误抛出更具体的异常，见对应接口说明。

| 错误 | 说明 |
| - | - |
| `DeviceNotFound` | 未找到指定设备 |
| `DeviceMismatch` | 设备类型不匹配 |
| `Disconnected` | 设备已断开连接 |
| `ConnectionTimeout` | 连接超时 |
| `OperationTimeout` | 操作超时 |
| `PathNotFound` | 资源路径不存在 |
| `SchemaMismatch` | 数据类型不匹配 |
| `NoData` | 无可用数据 |
| `StreamClosed` | 订阅流已关闭 |

捕获与按类型分支的示例见 [最佳实践 — 错误处理](/docs/wuji-sdk/advanced/#错误处理)，断开后的重连写法见 [最佳实践 — 重连策略](/docs/wuji-sdk/advanced/#重连策略)。

## 版本兼容

运行环境要求见 [安装与环境 — 系统要求](/docs/wuji-sdk/quick-start/#系统要求)。手部重定向只分发 Linux x86\_64 与 Linux aarch64 的预编译包，见 [手部重定向 — 平台与限制](/docs/wuji-sdk/retargeting/#平台与限制)。

下列能力对固件与 SDK 版本有最低要求。表中未列的能力随所装 SDK 版本可用。

| 能力 | 最低固件版本 | 最低 SDK 版本 | 详见 |
| - | - | - | - |
| 指尖触觉数据 | Wuji Hand 2 v2.1.0 | v2026.7.21 | [指尖触觉 — 使用要求](/docs/wuji-sdk/wuji-hand-2-tactile/#使用要求) |
| 指尖触觉流输出率调节 | Wuji Hand 2 v2.3.0 | v2026.8.17 | [指尖触觉 — 使用要求](/docs/wuji-sdk/wuji-hand-2-tactile/#使用要求) |
| 分点力归一化格式 | Wuji Hand 2 v2.4.0 | v2026.8.17 | [指尖触觉 — 自描述数据格式](/docs/wuji-sdk/wuji-hand-2-tactile/#自描述数据格式) |
| 触点在手模型中的位置 | Wuji Hand 2 v2.5.0 | 随固件可用 | [指尖触觉 — 触点在手模型中的位置](/docs/wuji-sdk/wuji-hand-2-tactile/#触点在手模型中的位置) |
| 三轴合力的作用点 | Wuji Hand 2 v2.6.0 | 随固件可用 | [指尖触觉 — 触点在手模型中的位置](/docs/wuji-sdk/wuji-hand-2-tactile/#触点在手模型中的位置) |
| 触觉标定命中离线手指时抛出 `NodeOfflineError` | Wuji Hand 2 v2.6.0 | v2026.8.31 | [指尖触觉 — 零基线标定与状态查询](/docs/wuji-sdk/wuji-hand-2-tactile/#零基线标定与状态查询) |
| Flash 历史日志导出 | 无附加要求 | v2026.8.31 | [故障排查 — 设备日志导出](/docs/wuji-sdk/troubleshooting/#设备日志导出) |
| 同一设备并发导出 Flash 日志 | Wuji Hand 2 v2.6.0 | v2026.8.31 | [Wuji Hand 2 诊断与日志 — Flash 日志导出](/docs/wuji-hand/latest/sdk-reference/diagnostics/#flash-日志导出) |

各版本的完整变更见 [版本发布记录](/release-notes/)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.