> ## 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.

# 健康诊断

> 用 wuji doctor 逐项检查设备，定位 EMF 断线与触觉坏点故障

设备无法连接或数据异常时，先运行 `wuji doctor`。命令先检查主机环境，再扫描设备并采样实时数据（约 100 帧，数秒内完成），输出逐项检查的树形报告，帮助缩小故障范围。

## 检测范围

检查分为主机环境、设备发现与逐设备三层。

**主机环境（Environment）**

* 软件版本：CLI、Wuji SDK、Wuji Studio 各自的版本与是否有更新
* 系统信息：操作系统与版本是否在支持范围内
* 网络接口：在网接口及其地址，多接口时提示可能的路由问题

**设备发现（Generic）**

扫描一次即产生，即使未发现任何设备也会出现：发现的设备数、设备 IP 是否重复、设备是否与主机同一子网。

**逐设备**

* **wuji\_glove**
  * EMF 断线检测：定位到具体手指，区分 RX（接收）与 TX（发射）故障
  * 触觉传感器坏点/坏行/坏列检测

<Warning>
  触觉检测需将手套静态放置，勿佩戴或按压，否则可能误报。
</Warning>

## 用法

```bash theme={null}
wuji doctor                # 诊断全部设备
wuji doctor --sn <SN>      # 只诊断指定设备
wuji doctor -v             # 显示全部检查项（默认隐藏通过项）
wuji doctor --json         # 与树形报告同等信息的结构化输出
```

## 读懂报告

```bash theme={null}
$ wuji doctor

══════ Environment ══════
~ Software: version info incomplete
├─ ✔ CLI: 2026.8.3 (up to date)
├─ ~ SDK: not installed or version undetectable (skipped)
└─ ✔ Studio: 2026.8.3 (up to date)

✔ System: supported
└─ ✔ OS: Ubuntu 26.04 (supported)

! Network interfaces: 2 interfaces, see interface count
├─ ✔ eth0 (192.168.1.50/24, fe80::abcd:.../64)
└─ ! Interface count: 2 interfaces — multiple interfaces may cause routing issues

══════ Generic ══════
✔ Device discovery: 2 device(s) found, no issues
├─ ✔ Devices found: 2 device(s) found
├─ ✔ Duplicate device IP
└─ ✔ Host subnet

══════ wuji_glove: WG1KXXXXXXXXXXX ══════
├─ ✔ EMF disconnect check: all 5 fingers normal
└─ ! tactile dead-pixel check: 0 dead pixels, 2 bad rows, 2 bad cols
   ├─ ! Bad rows: 2 bad row(s)
   └─ ! Bad cols: 2 bad col(s)
   Tip: Tactile check result is for reference only. Verify via the tactile matrix in wuji viz
```

* **状态标记**：✔ 通过、! 警告（参考性提示）、✘ 失败（确定故障）、\~ 跳过（检查不适用或无法执行）
* **Tip: 行**是修复建议
* **退出码**：0 表示无失败项（警告不算失败），1 表示存在失败项或诊断无法完成，脚本可直接判定。未连接任何设备不算错误，主机环境与设备发现照常检查并决定退出码
* **不适用或无法执行的检查**：只有发现 UDP 设备时才执行 `Duplicate device IP` 和 `Host subnet`。全部设备均使用 USB 或 Zenoh 时，两项显示 `~ not attempted: no UDP devices`。没有诊断配方的设备也会显示 `~ connect & diagnose`，不再误报故障。这些跳过项本身不会让退出码变为 1。连接或数据采集失败仍显示 ✘ 并返回 1
* 触觉检查结果仅供参考（最高只到警告级），需要通过 [`wuji viz`](/docs/wuji-cli/visualization#wuji-glove) 显示的原始触觉矩阵验证

## 展开全部检查项

默认只显示异常项，`-v` 展开全部检查项（含通过项），完整呈现检查范围。以下只截取设备段，实际输出中主机环境与设备发现两段仍排在设备之前：

```bash theme={null}
$ wuji doctor -v

══════ wuji_glove: WG1KXXXXXXXXXXX ══════
├─ ✔ EMF disconnect check: all 5 fingers normal
│  ├─ ✔ Thumb
│  ├─ ✔ Index
│  ├─ ✔ Middle
│  ├─ ✔ Ring
│  └─ ✔ Pinky
└─ ! tactile dead-pixel check: 0 dead pixels, 0 bad rows, 1 bad cols
   ├─ ✔ Thumb
   ├─ ✔ Index
   ├─ ✔ Middle
   ├─ ✔ Ring
   ├─ ✔ Pinky
   ├─ ✔ Palm
   └─ ! Bad cols: 1 bad col(s)
   Tip: Tactile check result is for reference only. Verify via the tactile matrix in wuji viz
```

## 结构化输出

`--json` 以机器可读形式输出与树形报告相同的检查结果，便于保存和脚本处理：

```bash theme={null}
wuji doctor --json > doctor-report.json
```

顶层对象按诊断层分成两个数组，每个检查项一个节点，经 `children` 嵌套：

| 字段 | 内容 |
| - | - |
| `env` | 主机环境检查：`env_software`（CLI / SDK / Studio 版本）、`env_system`（系统信息）、网络接口 |
| `device` | 设备层结果：一条不带 `sn` 的 `Generic` 条目包含设备发现检查，其后每台设备一条，含 `label`、`sn` 与检查树 |

数组为空时才省略。联网运行时 `env` 始终存在，扫描过设备或指定了目标设备时 `device` 存在。

以下示例假设已发现 UDP 设备。如果只发现 USB 或 Zenoh 设备，设备发现节点和两项 IP 检查的状态均为 `"status": "skip"`，摘要会说明因未发现 UDP 设备而跳过 IP 检查。

<Warning>
  早前版本输出的是 `system` 与 `devices` 两个平铺数组。按旧字段名取值的脚本需改为读取 `env` 与 `device`。
</Warning>

```json theme={null}
{
  "env": [
    {
      "id": "env_software",
      "label": "Software",
      "status": "warn",
      "summary": "updates available or unable to verify latest",
      "children": [
        { "label": "CLI", "status": "warn", "summary": "2026.8.3 (unable to check latest version)" },
        { "label": "SDK", "status": "skip", "summary": "not installed or version undetectable (skipped)" },
        { "label": "Studio", "status": "pass", "summary": "2026.8.3 (up to date)" }
      ]
    }
  ],
  "device": [
    {
      "label": "Generic",
      "children": [
        {
          "id": "device_discovery",
          "label": "Device discovery",
          "status": "pass",
          "summary": "1 device(s) found, no issues",
          "children": [
            { "label": "Devices found", "status": "pass", "summary": "1 device(s) found" },
            { "label": "Duplicate device IP", "status": "pass" },
            { "label": "Host subnet", "status": "pass" }
          ]
        }
      ]
    },
    {
      "label": "wuji_glove",
      "sn": "WG1KXXXXXXXXXXX",
      "children": [
        { "id": "emf_disconnect", "label": "EMF disconnect check", "status": "pass", "summary": "all 5 fingers normal" }
      ]
    }
  ]
}
```


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