wuji-cli-doctor

wuji doctor 会连接到每台设备，采集实时数据（约 100 帧，几秒内即可完成），并输出树状检查报告。

目前支持的设备和故障类型：

• wuji_glove
  • EMF 断连检测：定位受影响的手指，并区分 RX（接收）故障和 TX（发送）故障
  • 触觉传感器坏点／坏行／坏列检测（保持手套静止——不要佩戴或按压，否则可能出现误报）

用法

wuji doctor                           # Run the default item: read-only checkup on every device
wuji doctor --sn <SN>                 # Read-only checkup on one device
wuji doctor -v                        # Show all check items (passing items hidden by default)
wuji doctor --json                    # The same information as the tree report, as structured JSON
wuji doctor --list                    # List every diagnostic item (local query, no connection)
wuji doctor ITEM [--sn <SN>]          # Run one specific item

如果未指定 ITEM，wuji doctor 会运行 default 项目（只读检查）。wuji doctor 可运行的每项检查都是一个项目；wuji doctor --list 会列出这些项目，但不会连接设备。 在 JSON 输出中，只有带副作用的项目才会包含 effects 字段（default 等只读项目不会包含该字段）：moves_device 表示项目会驱动设备进行物理运动。

活动项目

活动项目会驱动设备。只有在操作员已准备好明确的运动区域、接受运动，并确认目标序列号与其面前的手部相符时，才运行这些项目。

活动项目还会在驱动手部之前重新配置手部。请先记录当前的力限制和 MIT 增益（wuji get effort_limit、wuji get mit_params）——运行过程会将它们写回；如果进程被直接终止（SIGKILL、电源故障），这是唯一的恢复方式。

当前列表包含一个活动项目：

• thumb_opposition（仅限 wuji_hand_2）：检查 joint_states 和 joint_diagnostics，确认序列号对应的手部侧别，然后依次驱动食指、中指、无名指和小指。每根手指使用 2 N、4 N 和 6 N 的控制器力设定值——这些是控制器设置，并非经过校准的实际力测量值。超时时间为 120 秒。按一次 Ctrl+C 可安全停止；该命令会先卸载手部，然后释放设备。 每根手指也有 10 秒时间到达拇指。未能及时到达的手指会被跳过，其余手指仍会运行，结果为 indeterminate，且该手指会在 summary.message 中列出。清除阻挡手部的物体，然后重新运行该项目。

wuji doctor thumb_opposition --sn <SN>
wuji doctor thumb_opposition --sn <SN> --json
wuji doctor thumb_opposition --sn <SN> --jsonl

在终端中运行活动项目时，如果省略 --sn，会打开一个筛选出适用设备的设备选择器。继续之前，请核对所选设备的序列号。在终端之外（脚本、Agent）运行时，请显式传入 --sn。

在人工模式下，活动项目会打印其前置条件，然后等待输入 proceed? [y/N]。在你输入 y 之前，它不会发送任何驱动命令；其他任何输入都会中止并以退出码 9 退出。--json 和 --jsonl 模式不会提示：如果没有显式授权标志，项目会在连接前被拒绝，并以退出码 2 退出；错误消息会列出需要确认的前置条件。出现此错误时，请停止操作，并与用户确认列出的每项前置条件，然后使用消息中指定的授权标志重新运行。只读项目（例如 default）无需授权，也会静默接受该标志。

活动项目通过 JSON 和 JSONL 中的信封字段报告结果。verdict 使用蛇形命名格式，取值为 pass、fail、warn、skip、indeterminate 或 unsupported；summary 包含 label、message 和 next_action。checks 始终存在；项目未生成检查树时，它是一个空数组。人工模式会显示判定标签，逐指手指表格使用大写状态词（PASS / FAIL / NOT_RUN）。

判定含义：

• pass：运行已完成，手部已达到安全状态。
• fail：运行已完成，且至少有一项检查失败。运动已执行——这并非提前停止的运行。
• indeterminate：运行在得出安全判定前停止（前置条件不满足、执行错误、Ctrl+C，或无法运行某项检查）。
• unsupported：设备无法运行该项目。
• warn / skip：运行已结束，但某项检查报告了信息性异常，或某项检查不适用。

人工模式会将前置条件写入 stderr，并将最终报告写入 stdout——其中包含判定卡片和逐指手指表格（finger、status、force stages），表格根据同一份 checks 生成。JSON 和 JSONL 模式不会输出前置条件。

退出码：0 = pass，1 = fail / unsupported / timeout（包括因 10 秒接近时限而跳过手指），2 = 参数错误（未知项目、缺少或不适用的 --sn），9 = 操作员停止运行（Ctrl+C、取消设备选择，或拒绝确认提示）。如果命令提示设备正被其他程序使用，请关闭该程序，然后使用相同的序列号重试。

设备参数变更

device_changes 会报告活动项更改且无法写回的参数：缺失表示运行已恢复所有内容，存在则表示设备仍处于已更改状态。存在时，报告会列出每个参数及其关节，并给出需要写回的值：

• param 和 targets 分别标明参数及其关节
• expected 给出需要写回的值，每个关节一个；原始值未知时为 null

verdict 和退出代码会忽略此字段。使用 wuji set <param> <value> --sn <SN> 写回这些值（参见 wuji-cli-base skill）；如果无法通过 CLI 写入某个参数，请按照支持渠道处理（参见 wuji-cli-support skill）。

"device_changes": {
  "unrestored": [{"param": "effort_limit", "targets": [5, 6], "reason": "readback mismatch", "expected": [1.5, 1.5]}]
}

读取报告

• 状态：✔ 通过 / ! 警告（提示性异常） / ✘ 失败（已确认故障） / ~ 跳过（检查不适用或无法运行）
• Tip: 行是修复建议
• 退出代码：0 = 没有失败（允许有警告）。1 = 存在失败或无法完成诊断，可直接用于脚本。未连接设备不算错误——主机环境和设备发现检查仍会运行并决定退出代码。
• 触觉检查结果仅供参考（最高为警告）。请在 Wuji Studio 中通过触觉热图进行验证。
• 只有设备发现到 UDP 设备时，才会检查重复设备 IP 和主机子网。如果所有设备都使用 USB 或 Zenoh，这两项检查都会显示 ~ not attempted: no UDP devices。跳过这些检查不会导致退出代码为 1。
• 没有诊断配方的设备会显示一个 ~ connect & diagnose 节点。此节点被跳过不会导致退出代码为 1。连接或数据收集失败仍会显示 ✘ 并返回 1。

示例

$ 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: WG1KXXXXXXXXXX01 ══════
├─ ✔ EMF disconnect check: all 5 fingers normal
└─ ! tactile dead-pixel check: 0 dead pixels, 0 bad rows, 0 bad cols

══════ wuji_glove: WG1KXXXXXXXXXX02 ══════
├─ ✔ 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 tactile heatmap in Wuji Studio

wuji doctor -v 会列出每个检查项。默认情况下会隐藏通过的项目，因此添加 -v 可显示全部项目。此处仅显示设备部分——为简洁起见，省略了上文展示的 Environment / Generic 部分（实际输出中它们会显示在设备部分之前）：

$ wuji doctor

══════ wuji_glove: WG1KXXXXXXXXXXX ══════
├─ ✔ EMF disconnect check: all 5 fingers normal
└─ ! tactile dead-pixel check: 0 dead pixels, 0 bad rows, 1 bad col
   └─ ! Bad cols: 1 bad col(s)
   Tip: Tactile check result is for reference only. Verify via tactile heatmap in Wuji Studio

$ 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 col
   ├─ ✔ Thumb
   ├─ ✔ Index
   ├─ ✔ Middle
   ├─ ✔ Ring
   ├─ ✔ Pinky
   ├─ ✔ Palm
   └─ ! Bad cols: 1 bad col(s)
   Tip: Tactile check result is for reference only. Verify via tactile heatmap in Wuji Studio

每个诊断项都使用相同的结构报告。每次运行只报告所运行的项目（未指定 ITEM 时为 default）：

字段	含义
item	生成报告的诊断项（单独运行 wuji doctor 时为 default）
device	适用的设备；适用于多个设备的项目则为 all
sn	目标序列号；适用于多个设备的项目不包含此字段
verdict	pass | fail | warn | skip | indeterminate | unsupported，根据 checks 得出；活动项只有在所有检查都通过时才报告 pass
summary	{label, message, next_action} — 一句话结论及后续操作
checks	检查树（id / label / status / summary / fix / children）；始终存在，如果该项目未生成检查树则为空数组
device_changes	活动项更改且无法恢复的设备参数；仅当运行导致设备仍处于已更改状态时存在（参见“设备参数变更”）

对于 default，checks 会先包含主机环境检查，然后为每个设备结果包含一个节点——设备发现节点（Generic，只要运行了扫描就会添加，即使未发现设备），以及一个标题为 wuji_glove: <SN> 的节点。

请根据 id 而非 label 定位节点：id 稳定，发布后不会更改；label 是面向用户的文本，可能会调整措辞。设备结果中的节点可能没有 id；请根据其在最近一个具有 id 的父节点下的位置来定位。

此示例假设发现了一个 UDP 设备。如果只有 USB 或 Zenoh 设备，发现节点和两项 IP 检查的 "status" 都会是 "skip"，且摘要会说明未发现 UDP 设备。

$ wuji doctor --json

{
  "item": "default",
  "device": "all",
  "verdict": "warn",
  "summary": {
    "label": "Needs attention",
    "message": "The checkup completed with warnings.",
    "next_action": "Review the warnings above for details."
  },
  "checks": [
    {
      "id": "env_software",
      "label": "Software",
      "status": "warn",
      "summary": "updates available or unable to verify latest",
      "children": [
        {
          "id": "sw_cli",
          "label": "CLI",
          "status": "warn",
          "summary": "2026.8.3 (unable to check latest version)"
        },
        {
          "id": "sw_sdk",
          "label": "SDK",
          "status": "skip",
          "summary": "not installed or version undetectable (skipped)"
        },
        {
          "id": "sw_studio",
          "label": "Studio",
          "status": "pass",
          "summary": "2026.8.3 (up to date)"
        }
      ]
    },
    {
      "id": "env_system",
      "label": "System",
      "status": "pass",
      "summary": "supported",
      "children": [
        {
          "id": "env_system_os",
          "label": "OS",
          "status": "pass",
          "summary": "Ubuntu 26.04 (supported)"
        }
      ]
    },
    {
      "id": "device_generic",
      "label": "Generic",
      "status": "pass",
      "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"
            }
          ]
        }
      ]
    },
    {
      "id": "device_wg1kxxxxxxxxxxx",
      "label": "wuji_glove: WG1KXXXXXXXXXXX",
      "status": "pass",
      "children": [
        {
          "id": "emf_disconnect",
          "label": "EMF disconnect check",
          "status": "pass",
          "summary": "all 5 fingers normal",
          "children": [
            {
              "label": "Thumb",
              "status": "pass",
              "summary": "normal"
            },
            {
              "label": "Index",
              "status": "pass",
              "summary": "normal"
            },
            {
              "label": "Middle",
              "status": "pass",
              "summary": "normal"
            },
            {
              "label": "Ring",
              "status": "pass",
              "summary": "normal"
            },
            {
              "label": "Pinky",
              "status": "pass",
              "summary": "normal"
            }
          ]
        }
      ]
    }
  ]
}