wuji-cli-base

运行命令前

将这些技能同步到已安装的 CLI 版本：

wuji update --skills

如果本地技能已与 CLI 版本匹配，该命令不会安装任何内容，但仍会报告过期的技能目录；使用 --yes 或确认提示后，会将这些目录移出 ~/.agents/skills（见下文“过期技能目录”部分）。只有同步未能收敛时，命令才会以非零状态退出。

心智模型

• 无状态：每条命令都会独立执行连接 → 操作 → 断开。命令之间不会保持连接，因此无需单独执行“连接”步骤。
• 单占用：设备固件一次只允许一个直接会话。主机应用（例如 Wuji Studio）占用设备时，CLI 会自动回退到通过 Zenoh 桥接进行只读访问（此模式下会拒绝设置写入）。
• 退出代码：0 = 成功；非零 = 失败（任何设备的 ping 失败，或 doctor 报告 Fail，都会以 1 退出），可直接用于脚本。

命令概览

命令	用途
wuji devices	扫描并列出设备（USB/UDP）
wuji ping	握手探测；报告 SN/固件/IP（默认探测所有设备）
wuji resources	列出可读/可写参数和可订阅主题
wuji get <path>	读取参数（根据架构自动解码为 JSON）
wuji set <path> <value>	写入参数（值为 JSON；0x 前缀表示原始十六进制字节）
wuji sub <topic>	订阅实时数据（--count N 在收到 N 帧后退出）
wuji viz --sn <SN>	可视化 Wuji Hand 2 实时数据（见 wuji-cli-viz 技能）
wuji calib hand-model	手部模型校准（见 wuji-cli-calib 技能）
wuji calib tactile	触觉接触模型校准（见 wuji-cli-calib 技能）
wuji doctor	设备健康自检（见 wuji-cli-doctor 技能）
wuji upgrade	检查并升级固件（见 wuji-cli-upgrade 技能）
wuji user	管理 SDK 用户并导出/导入校准数据（见 wuji-cli-user 技能）
wuji update	更新 CLI 及其 Agent Skills（--check 仅检查，--skills 仅同步 Skills）
wuji completions <shell>	生成 Shell 补全脚本

在任意命令后添加 --help，即可查看详细帮助。

选择设备

大多数命令都接受以下三种互斥选择器之一：

--sn WG1KXXXXXXXXXXX            # By serial number (recommended, most precise)
--address 192.168.1.100:50000    # By address: ip:port for UDP, /dev/ttyACM0 for USB
--handedness left                # By handedness left/right (two-handed setups)

未指定设备选择器时：ping / doctor 会处理所有设备；get / set / sub / resources 需要指定设备，否则会报错并列出候选 SN。

典型工作流

wuji devices --json                            # 1. What devices are there
wuji ping --json                               # 2. Can they all connect (confirm SN/firmware/IP)
wuji resources --sn <SN> --json                # 3. What params / topics are available
wuji get data_port --sn <SN> --json            # 4. Read a parameter
wuji set data_port 50001 --sn <SN>             # 5. Write a parameter (JSON value)
wuji sub tactile --sn <SN> --count 10 --jsonl  # 6. Capture 10 tactile frames

常用资源速览

wuji resources --sn <SN> --json 是权威列表；以下是常用项：

• 常用参数（get/set）：hand_side、firmware_version、serial_number、ip_address、data_port — 各设备支持的能力不同，以 wuji resources --sn <SN> 中的 GET/SET 列为准
• 常用主题（sub）：tactile（触觉矩阵）、emf_poses（EMF 姿态）、imu_data/palm（IMU）、tip_poses（指尖姿态）、hand_joint_angles（关节角度）、hand_skeleton、tf

将数据录制到文件

--jsonl 每行打印一帧，因此只需使用管道即可轻量录制：

wuji sub tactile --count 500 --jsonl > data/tactile.jsonl             # Silent recording
wuji sub emf_poses --count 500 --jsonl | tee data/emf.jsonl | jq      # Record and watch

常见错误及处理

症状	含义和处理
found N devices: ...	未指定设备且总线上有多个设备；按提示使用 --sn
Session already exists (0x0013)	另一个进程持有直接会话；使用 --sn 或未指定目标时，CLI 会自动回退到 Zenoh 只读模式
connected to wrong device: requested sn=X, got sn=Y	多个设备共用一个地址，或扫描条目已过期；重新运行 wuji devices 进行确认
virtual parameter 'X' currently has no value	虚拟参数没有默认值，且无状态 CLI 不会持久化写入；这是预期行为
'X' does not support set. Supported operations: get	该资源不支持此操作，因此 CLI 不会向设备发送任何内容，并以代码 1 退出。请在 wuji resources --sn <SN> 中检查资源的 GET、SET 或 SUB 列。使用 --json 或 --jsonl 时，错误还会包含 kind: "unsupported_operation"、path、operation、device 和 capabilities
set rejected (direct_only)	目前通过 Zenoh 桥接时为只读；待直接会话持有者释放设备后重试
set succeeds but wuji devices shows no change	ip_address/data_port 等网络参数会在设备重启后生效

大多数命令都支持 --json，可为 Agent 提供更详细的结构化输出。

不使用 --json 时，输出更便于人类阅读，例如：

$ wuji devices
found 1 device(s)
┌──────────────────┬───────────┬──────────┬─────────────────────┬─────────────────────┐
│ SN               ┆ Transport ┆ USB Port ┆ IP                  ┆ Address             │
╞══════════════════╪═══════════╪══════════╪═════════════════════╪═════════════════════╡
│ WG1KXXXXXXXXXXX  ┆ Udp       ┆ -        ┆ 192.168.1.100:50001 ┆ 192.168.1.100:50001 │
└──────────────────┴───────────┴──────────┴─────────────────────┴─────────────────────┘
💡 run `wuji ping` to get device type and firmware version

$ wuji devices --json
{
  "devices": [
    {
      "sn": "WG1KXXXXXXXXXXX",
      "transport": "Udp",
      "usb_port": null,
      "ip": "192.168.1.100:50001",
      "address": "192.168.1.100:50001"
    }
  ]
}

此处不会显示设备类型和固件版本：发现过程是广播扫描，不会进行握手。使用 wuji ping 获取这些信息。

使 CLI 和 Skills 保持最新

wuji update --check --json   # {"current": ..., "latest": ..., "update_available": true/false}
wuji update                  # Download, verify, and replace the binary in place
wuji update --skills         # Sync Agent Skills to this CLI's companion version only

update --check 在检查本身成功时始终以 0 退出。应根据 JSON 字段 update_available 进行判断，而不是依据退出代码。后台检查每 24 小时最多运行一次，并在 stderr 上打印通知——不会阻塞命令，也不会触及 stdout。设置 WUJI_NO_UPDATE_CHECK=1 可禁用检查。

检查确切版本

wuji --version          # Two lines: short commit and version
wuji --version --long   # Four lines: full commit, version, build target, profile
wuji --version --json   # {"version", "commit" (full sha or "unknown"), "target", "profile"}

--long 输出是供脚本使用的稳定逐行文本：每行格式为 key: value，顺序为 commit、version、target、profile。commit 是构建此二进制文件所用的 40 个字符的 sha；对于在 Git 检出目录之外构建的版本，则为 unknown。

Agent Skills

wuji update 和 wuji update --skills 会确保 ~/.agents/skills 中的 Wuji CLI Skills 版本不低于随 CLI 附带的版本。报告的 skills.status 字段有三种状态：

状态	含义
up-to-date	已安装的 Skills 版本不低于 CLI 附带的版本
update-required	已安装的 Skills 版本较旧，或无法读取其版本。二进制文件成功升级后会自动同步 Skills；也可运行 wuji update --skills
not-installed	未找到 Wuji CLI Skills。wuji update 会报告此状态，而 wuji update --skills 会安装它们

wuji update --skills 会同步 Skills，而不触及二进制文件，因此无需升级 CLI 即可让 Skills 达到 CLI 所附带的版本或更高版本。如果同步后 Skills 仍低于该版本，或其版本仍无法读取，该命令将以 1 退出。

过期的技能目录

重命名或停用的技能在同步后仍会保留在磁盘上的目录中，因为安装程序只会写入文件。同步后，CLI 会列出这些目录、在 stderr 中发出警告，并在将它们移出 ~/.agents/skills 前征求确认。移出的目录会保留在临时目录中，报告会列出每个目录及其新路径，并标记 "action": "moved"。不会删除任何内容。

在 JSON 输出中，这些目录会显示在 stale_skills 下；没有过期目录时会省略该字段。每个条目包含 name、action（moved、kept 或 failed），以及在适用时包含 version、path 和 error。

传入 --yes 可跳过确认，例如 wuji update --yes 或 wuji update --skills --yes。在没有终端的情况下运行时，会报告过期目录，并将其保留在原处，除非同时传入 --yes。传入 --yes 后，无论是否有终端，这些目录都会被移出；因此，传入该标志的自动化运行会修改 ~/.agents/skills。

wuji update --skills --json   # Report stale directories without moving them (no --yes)
wuji update --skills --yes    # Move them out without asking, with or without a terminal

wuji update --check 不会移动目录。

安装 Shell 补全（可选）

# bash example; for other shells (zsh/fish/powershell/elvish), see wuji completions --help
mkdir -p ~/.local/share/bash-completion/completions
wuji completions bash > ~/.local/share/bash-completion/completions/wuji
exec bash   # Takes effect in the current session