wuji-cli-viz

启动查看器

viz 支持 Wuji Hand 2 和 Wuji Glove。不带 --sn 时，它会扫描这两种设备：

wuji viz

它会合并统计这两种受支持的设备，且仅在恰好发现一台受支持设备时才直接连接。在交互式终端中，如果发现多台受支持的设备，则会打开可搜索的选择器，其摘要会显示 SN 和设备类型。高亮项会在单独的详细信息行中显示传输方式和地址；仅当 USB Port 或 IP 字段存在时才会显示该字段。只会连接所选设备。在选择器中按 Esc 或 Ctrl+C 会向 stderr 写入 Cancelled.，以代码 9 退出，且不会连接设备或回退到其他设备。连接失败时也不会回退。

使用 wuji viz --sn <SN> 选择特定的受支持设备。如果存在多台受支持的设备，结构化输出和无人值守调用必须指定 --sn；它们绝不会打开选择器。

该命令会输出查看器 URL，并在默认浏览器中打开。它会持续运行设备会话和查看器，直到停止。如果 Agent 在聊天中启动了该命令，请让 Agent 停止 viz；不要在聊天中让用户按 Ctrl+C。只有当用户在自己的终端中直接运行 viz 时，才适合按 Ctrl+C。

仅当主机实际上是无头环境，或者用户明确要求不要打开浏览器或手动打开输出的 URL 时，才使用 --no-open。不要仅因为 Agent 正在运行该命令就推断应使用此选项：

wuji viz --no-open

如需机器可读的启动报告，使用 --json 输出格式化 JSON，或使用 --jsonl 输出一行紧凑的 JSON。根据 Agent 执行约定中的设备特定规则选择归零行为。此示例假定主机为无头环境，且设备为配备触觉硬件或触觉能力未知的 Hand 2，并且未确认指尖未负载：

wuji viz --sn <HAND2_SN> --no-zero --no-open --jsonl

查看器就绪后，stdout 会输出且仅输出一份启动报告，并在命令继续运行前将其刷新：

{
  "status": "running",
  "device": {
    "sn": "WH2-...",
    "handedness": "left"
  },
  "viewer": {
    "url": "http://127.0.0.1:...",
    "lan": false
  }
}

实时传感器帧会保留在查看器中，不会写入 stdout。进度信息、警告和错误会写入 stderr。查看器就绪前发生故障时，stdout 保持为空，并向 stderr 写入常规结构化错误信封。后续运行时发生故障时，启动报告仍保留在 stdout 中，并向 stderr 写入错误信封。Ctrl+C 不会额外写入第二条结构化记录。

该命令不会记录 RRD 文件，也不接受 --address 或 --handedness 作为设备选择器。

所选设备决定查看器页面：

• Wuji Hand 2 显示实时手部姿态，并在可用时显示指尖触觉数据。
• Wuji Glove 显示实时手部和传感器可视化内容。

viz 仅支持实时查看：不会记录 RRD，也不会加载或重放 MCAP/RRD 文件。

解析请求的设备

根据用户对设备的描述限制选择范围：

• “hand”、“Hand 2”、“二代手”或“手”表示 wuji_hand_2。
• “glove”、“Wuji Glove”或“手套”表示 wuji_glove。

当用户指定一种类别时，将设备发现范围限制为该类别，绝不回退到另一类别。如果没有可用的所请求类别设备，应报告这一情况，而不是启动其他类型的设备。

Agent 执行约定

当用户选择此技能来启动、检查或测试 wuji viz 时，请在用户的机器上执行实际命令；不要只贴出命令让用户运行。如果未安装 wuji 二进制文件或没有可用的受支持设备，请说明这一具体阻碍，不要声称 Viewer 已启动。

如果用户提供了可执行文件路径，请在设备发现和每条 viz 命令中使用该确切路径；不要替换为裸 wuji 命令，也不要悄悄选择其他已安装的版本。

在启动长时间运行的进程之前，根据用户的意图选择调用方式：

1. 选择设备。 如果用户指定了 SN，请传入 --sn <SN>。否则，先运行 wuji devices --json，筛选出 wuji_hand_2 和 wuji_glove，并使用明确标识的单个候选设备。在 Agent 或其他非交互进程中，切勿在未指定 --sn 的情况下启动选择器；如果仍有多个受支持设备，请停止并询问用户要使用哪个 SN，不要猜测。不要使用 --address 或 --handedness 作为选择器。
2. 根据设备选择置零行为。 对于 Wuji Glove，或已确认没有触觉硬件的 Hand 2，不要添加 --no-zero，也不要询问指尖是否空载。对于带有触觉硬件或触觉能力未知的 Hand 2，如果用户要求只读启动、要求跳过置零，或尚未明确确认五个指尖都处于空载状态，请添加 --no-zero。只有在用户已确认五个指尖都处于空载状态，且未要求只读或跳过置零时，才省略该参数。此规则适用于图形界面、交互式和由 Agent 管理的启动。使用现有设备证据判断触觉能力，不要依据零力值或缺失数据。不要仅为选择此参数而单独进行探测。在普通进度消息中，不要提及置零、指尖空载检查或 --no-zero。如果 CLI 出现实际置零错误或安全限制，请说明并停止。对于 Wuji Glove，绝不要执行或提及 Hand 2 置零。
3. 选择浏览器和输出处理方式。 在图形桌面上，默认命令会打开浏览器：使用 wuji viz 或 wuji viz --sn <SN>，不要添加 --no-open。在无头主机上，添加 --no-open；不要仅仅因为由 Agent 运行就添加此参数。仅当调用方明确需要机器可读的启动记录时，才使用 --jsonl（或 --json）。只有在出现 status: "running" 记录后才解析 URL；进度、警告和错误会输出到 stderr。
4. 审慎选择网络公开方式。 本地使用时保留默认的环回绑定。只有当用户明确需要远程浏览器且网络可信时，才添加 --lan 或 --bind <local-IP>；这些模式不提供身份验证或 TLS。
5. 保持会话运行。 成功启动不代表进程已结束：viz 会继续流式传输。当 Agent 从聊天中启动它时，请让它在 Agent 管理的终端／会话中持续运行，并返回 URL，不要让用户按 Ctrl+C；该按键可能会中断整个 Agent 对话。如果用户想停止它，请通过 Agent 停止确切的 viz 会话／进程。仅当用户在自己的终端中直接运行 viz 时，才提及 Ctrl+C。除非第一个 Viewer 页面已关闭，否则不要启动第二个 Viewer 页面。断开连接后，Viewer 会保留最后的状态，命令不会自动重新连接。如果置零报告操作部分完成或失败，请停止并报告；不要自动重试。

常用调用方式：

# Local interactive desktop, Hand 2 with tactile capability unknown and no unload confirmation
wuji viz --no-zero

# Graphical desktop, Hand 2 with unloaded fingertips confirmed and zeroing allowed
wuji viz --sn <HAND2_SN>

# Graphical desktop, Hand 2 with tactile hardware or unknown capability, no unload confirmation
wuji viz --sn <HAND2_SN> --no-zero

# Graphical desktop, Hand 2 already confirmed to have no tactile hardware
wuji viz --sn <HAND2_SN>

# Graphical desktop, explicit Wuji Glove (opens the browser)
wuji viz --sn <GLOVE_SN>

# Explicitly requested manual URL / machine-readable Glove startup
wuji viz --sn <GLOVE_SN> --no-open --jsonl

# User will open the Glove URL manually on this trusted machine
wuji viz --sn <GLOVE_SN> --no-open

# Remote browser on a trusted LAN, Hand 2 with tactile hardware or unknown capability
wuji viz --sn <HAND2_SN> --no-zero --lan --no-open

Hand 2 触觉行为

Hand 2 会根据连接的硬件自动调整触觉可视化：

• 有触觉硬件时，显示触觉视图和力历史记录。
• 没有触觉硬件时，仅显示关节姿态，并隐藏触觉面板和力历史记录，同时保留完整的手部模型。
• 触觉功能不完整时，保留通用布局，并将不可用手指的视图留空。

不要根据力值推断触觉功能是否可用。如果启动时无法确定触觉功能是否可用，请保留安全的可视化效果，并跳过任何会更改设备的归零操作。

控制运行时触觉归零

该命令的默认调用方式会根据所选 Hand 2 可用的硬件处理触觉归零。无触觉功能的 Hand 2 和 Wuji Glove 会自动跳过此操作；--no-zero 仅适用于配备触觉硬件的 Hand 2。

所选设备为 Wuji Glove 时，面向用户的进度提示应简洁地说明正在启动 Glove 可视化。不要在状态消息中显示仅适用于 Hand 2 的归零细节，例如“只读”、“跳过归零”或 --no-zero。

对于配备触觉硬件或触觉功能未知的 Hand 2，请使用 --no-zero 来阻止归零：

wuji viz --sn <HAND2_SN> --no-zero

只有当 CLI 实际执行归零时，它才会检查全部五个触觉传感器是否符合预期型号且已就绪，将它们的读数记录为运行时归零基线，并等待全部五个传感器恢复到 Ready，然后才启动订阅和 Viewer。在此操作期间，所有指尖都应保持无负载，直到终端显示 Tactile zero: ready.

使用 --no-zero 时，跳过这些仅适用于归零的检查、基线采集和完成等待。在此分支中，不要要求用户为归零确认指尖无负载，也不要等待 Tactile zero: ready.。正常的触觉功能发现和可视化初始化仍会运行。

遵循 Agent 执行约定中的设备专用调用规则。Glove 和已确认无触觉功能的 Hand 2 启动时，无需确认指尖无负载，也无需使用 --no-zero。触觉功能未知并不能证明 Hand 2 没有触觉硬件。CLI 仍负责检查实际的归零条件。允许归零时，所有五个指尖表面都应保持无负载，直到终端报告 Tactile zero: ready.。归零期间存在的负载会成为基线的一部分。此操作不会写入持久化的触觉模型。如果命令报告归零可能不完整，请停止操作并报告错误。未经用户指示，不要重试。

阅读页面

对于配备触觉硬件的 Hand 2，Viewer 包含：

• 由实时关节状态驱动的 3D Wuji Hand 2 模型；
• 手部每个 taxel 的实心力箭头；
• 每根手指各一个合力箭头；
• 五个指尖 3D 面板；
• 五组合力大小序列，显示滚动的 60 秒时间窗口。

无触觉功能的 Hand 2 使用仅显示关节姿态的布局：隐藏触觉矩阵、指尖面板和合力历史记录，同时保留完整的 URDF，包括指尖外壳网格。不要为了隐藏触觉数据而从 URDF 中移除指尖外壳几何；这些网格属于手部模型的一部分。触觉功能不完整的 Hand 2 会保留五个面板位置，并将不可用手指的面板留空。

默认情况下，Viewer 以 Rerun 的深色主题打开，3D 背景为纯黑色。

当触觉数据可用时，力的方向和大小采用 Viewer 显示的坐标约定。Viewer 会显示每根手指的合力及其历史记录。

处理故障

警告 Using a standard model for visualization. 表示 Viewer 正在使用标准模型。 仍可使用实时设备数据继续可视化。

详细的警告和错误会打印在终端中。Viewer 页面不会在面板内添加健康状态标记：

• 指尖生成有效帧后，发生故障时会保留该帧；请在终端中查看受影响的手指和故障原因，其他数据流仍会继续更新；
• 关节数据流发生故障时，会保留最后一个有效手部姿势（如果有），指尖面板仍会继续更新；
• 缺少触觉数据时，仍可查看手部姿势；
• Glove 的更新会以不超过 60 Hz 的频率，根据最新可用状态进行渲染；某个数据流出现无效帧时，会保留该数据流的上一个有效视图，不受影响的数据流仍会继续更新；
• 当设备支持速率控制时，Glove 启动时会请求以 60 Hz 获取上游 emf_poses、tactile、tactile_zones 和掌部 IMU 数据，并报告实际速率；不支持速率控制时会发出警告，但 Viewer 的速率仍会限制在 60 Hz。
• 设备断开连接后，Viewer 会保留最后状态，命令会报告故障；请通过 Agent 停止由 Agent 管理的会话，或仅在独立终端中使用 Ctrl+C。

该命令不会自动重新连接。

在可信的局域网上共享

默认情况下，Viewer 使用回环地址。若要通过计算机的私有网络地址开放访问：

wuji viz --lan --no-open

--lan 会选择默认路由上的一个私有地址。如果该路由指向了错误的网络接口，请改为指定一个本地地址：

wuji viz --bind 10.42.0.7 --no-open

--lan 和 --bind 不能同时使用。非回环访问没有身份验证，也没有 TLS。仅在可信网络中使用，并且只将打印出的 URL 分享给预期的查看者。支持的用法仅限每个 wuji viz 会话同时打开一个 Viewer 页面。打开另一个页面前，请先关闭现有页面。