wuji-cli-calib

Wuji CLI Calib

将校准请求路由到正确的工作流，并确保涉及实际操作和持久模型变更时有人工参与。

路由请求

• 对于手部模型校准，执行任何命令前，先遵循本文件中的手部模型工作流。
• 对于触觉校准，执行任何命令前，先遵循本文件中的触觉工作流。
• 将手部模型和触觉语义分开。手部模型校准会为当前 SDK 用户和手侧发布模型；触觉校准则会为指定手套 SN 训练并安装接触模型。
• 手部模型校准会将结果归属到设备绑定的用户，此用户会在连接后确定。如果其他进程在 wuji calib hand-model 扫描或连接期间切换了 SDK 用户，CLI 会报告此切换，并将校准结果归属到绑定的用户；如果最终用户是 Default，则会在采集任何姿势前以退出码 5 停止。请以命令自身输出中显示的用户为准，不要依据之后 wuji user list 的结果判断。

应用通用安全规则

• 将校准视为会持久更改状态的操作。对于仅涉及状态查询、帮助、规划或故障排查的请求，不要启动校准。
• 启动前，说明将运行哪种校准模式，以及人必须执行提示的实际操作。除非用户当前请求已明确授权立即启动该模式，否则应先征求确认。
• 对于直接监控 Human TTY 流程，不要将 wuji devices 设为强制预检步骤。如果未提供选择器，手部模型校准会自行扫描并连接。对于由 Agent 引导的 JSONL 校准，应在启动前确定 SN 和左右手信息，以便明确设备选择、覆盖确认和最终身份。触觉校准始终需要 --sn。
• 用户已选择设备时，手部模型校准优先使用明确的 --sn；触觉校准始终提供该参数。若有多个设备，绝不要在用户未指定的情况下自行选择。
• 将命令保持在持续输出的终端会话中，直到它发出终止事件并退出。活动校准期间不要启动第二个校准。
• 用户请求取消时，只发送一次 Ctrl+C，并允许 CLI 停止 SDK 操作并释放设备。
• 不要自动重试失败或取消的校准。说明失败原因，并在重新启动前征求确认，因为重试会重新开始实际操作流程。

报告结果

• 如果命令提供了相关信息，请报告终止状态、所选设备 SN、模型身份和输出产物。
• 区分命令失败和用户取消。手部模型校准的退出码遵循 wuji user 约定：0 表示成功，5 表示默认用户保护，9 表示取消，1 表示其他失败。手部模型 JSON/JSONL 错误还会包含数字类型的 error.code；触觉校准期间第二次按下 Ctrl+C 会立即以代码 130 退出。
• 绝不要根据设备 SN 推断模型归属。请使用所选校准模式返回的身份字段。

手部模型校准工作流

使用此工作流引导人工完成 wuji calib hand-model，并监控其结构化进度。

确认前提条件

开始前，请确认以下所有事项：

• 用户有意现在开始手部模型校准，并已准备好摆出手势。
• 对于有人直接查看的 Human TTY 运行，请让内置提示词创建或切换到预期的命名用户。对于 --json / --jsonl 或重定向的 Human 输出，请在开始前切换到命名用户；非交互式输出仍会拒绝 Default，并以退出码 5 退出。
• 当终端至少为 81 列 × 38 行时，Human TTY 流程会显示固定尺寸、彩色的左右手 ANSI 姿势图。终端较小时会隐藏姿势图，并提示用户放大窗口后重新开始校准。姿势图属于 CLI，不包含在此公开 Skill 中；由 Agent 引导的 JSONL 运行会使用根据反馈生成的文本说明。
• 用户理解，校准成功后会为当前 SDK 用户发布 left_hand.urdf 或 right_hand.urdf，并热重载手部模型以供在线使用。即使使用不同的手套，重新校准同一用户的同一侧手也会替换该稳定模型。
• Wuji Glove 已开机，并可通过 USB 或本地网络连接。

Human TTY 流程会在覆盖现有手部 URDF 前请求确认，且默认选择 No。机器模式不会提示，因此除非用户当前请求明确授权重新校准，否则请在启动 --json / --jsonl 前获得确认。

选择并开始

对于在终端前观看的用户，请运行：

wuji calib hand-model

Cliclack 流程会显示当前用户的左右手状态，提供创建或切换用户的选项，扫描并列出 Wuji Gloves，询问要使用哪个手套，通过垂直排列的“是/否”选择器确认覆盖，并显示六个实时姿势步骤。姿势图不会调整大小：只有当终端能够容纳 60 列的指南块和实时内容时，CLI 才会显示完整的固定尺寸 ANSI 指南。发布成功后，Calibration finished 只显示用户、惯用手和 URDF 结果（包含文件大小和本地时间）。User show 会打开与 wuji user show 相同的完整用户资料清单，Recalibrate 会直接返回用户选择入口，不会额外弹出确认步骤，而 Finish 会直接关闭，不会再次显示成功摘要。连接下一个设备并确认其惯用手后，仍会执行标准覆盖确认。

对于由 Agent 引导的校准，请在启动会更改状态的命令前完成以下预检：

1. 运行 wuji user show --json。如果当前用户是 Default，则停止。如果所选手已经校准，则需取得覆盖确认，除非当前请求明确授权重新校准。
2. 使用已由用户选定的 SN。否则运行 wuji devices --json；如果只有一只 Wuji Glove，则使用该设备；如果能看到多只，则请用户选择。
3. 运行 wuji get hand_side --sn <SN> --json，并将 value 保留为 left 或 right。如果该值缺失或无效，则停止。
4. 在持久流式终端中启动同一设备：

wuji calib hand-model --sn <SN> --jsonl

机器模式不会弹出提示。保持进程运行，频繁轮询，并持续执行，直到出现一个终止事件且进程退出。校准占用设备期间，不要运行其他设备命令。

对于不会以视觉方式引导用户的重定向自动化场景，可以省略选择器：

wuji calib hand-model --jsonl

命令会自动扫描。只有一台设备时会连接该设备；没有设备时会报告 no device found；如果发现多台设备，则会列出候选 SN，但不会连接。用户选择候选项后，再次运行命令：

wuji calib hand-model --sn <SN> --jsonl

互斥的替代选项如下：

wuji calib hand-model --handedness left --jsonl
wuji calib hand-model --address 192.168.1.100:50000 --jsonl

优先使用 --sn。如果另一个程序占用了直接设备会话，使用地址作为目标时无法回退到共享访问。只有在默认的 900 秒总时限不合适时，才使用 --timeout-s <SECONDS>。

由 Agent 引导校准时请使用 --jsonl，因为它会流式输出进度。用户会直接观看终端时，请使用面向用户的输出（wuji calib hand-model）。实时引导时不要使用 --json，因为它只会输出最终文档。

JSONL 指南

将 stdout 的每一行解析为一个 JSON 对象。预期字段为 schema_version: 2、operation: "calibrate" 和 calibration: "hand_model"。

每个进度事件都包含 feedback，其中的校准字段与提供给 Python 回调的字段相同。没有单独的 guidance 或 presentation 对象。遵循 Python 示例中的推导规则：

• 将 step_index + 1 作为面向用户的步骤编号。若状态为 done，则已完成的姿势数为 step_index + 1；否则为 step_index，且不超过 step_total。
• 当 step_name 首次出现或发生变化时，播报一次姿势名称，并使用以下准确动作说明：pinch_index → 用拇指指尖触碰食指指尖；pinch_middle → 用拇指指尖触碰中指指尖；pinch_ring → 用拇指指尖触碰无名指指尖；pinch_pinky → 用拇指指尖触碰小指指尖；four_finger_bend_90 → 将四根手指弯曲约 90 度；flat_open → 摊平手掌，伸直所有手指，并保持手腕不动。立即发送动作说明文本并继续轮询；不要等待确认，因为设备会直接检测实际姿势。对于未知姿势 ID，将下划线替换为空格，并请用户摆出该姿势且保持不动。此公共 Skill 不包含姿势图片资源；不要虚构或重现姿势图。
• 对于 state: "waiting_movement"，请用户张开手掌，然后摆出 step_name 所指的姿势。
• 对于 state: "waiting_stable"，请用户保持不动。如果 variance_ok 为 false，则说明手部移动过多。
• 对于 state: "collecting"，请用户继续保持姿势；概述 collect_elapsed / collect_target 或 frames_collected，不要逐帧播报。
• 对于 state: "done"，说明已采集该姿势。如果面向用户的步骤编号至少为 step_total，则继续等待数值求解和结果发布；否则请用户在下一个姿势前张开手掌。
• 使用提供的 progress 值，并将其限制在 0 到 1 之间。不要根据耗时字段重新计算。

进行诊断时，按原顺序遍历 metrics 数组。将 unit: "m" 的误差转换为毫米，然后跳过显示值小于或等于 0.0001 的误差。按 finger 或 finger-finger_b 分组，对组名排序，并转达指标中的 hint。如果 constraints_ok 为 false 且没有剩余指标，请用户调整当前姿势。限制重复播报，每次最多显示八条诊断信息。

避免向用户发送过多信息。仅在姿势或状态变化、诊断出现实质性变化，或需要用户采取操作时进行播报。最后一个姿势之后可能会进入静默的数值求解和结果发布阶段；请在总超时时间内继续等待，不要仅因反馈暂停就声称进程卡住。

处理终端事件

预期恰好出现一个终端 JSONL 事件：

• event: "result"、status: "ok"：报告成功，并检查存在时的 result.handedness、result.calibrated_urdf、result.sdk_user 和 result.frames_per_pose。确认报告的用户和手部侧别符合用户意图。
• event: "error"、status: "failed"：报告 error.kind、error.code 和 error.message；使用其中包含的 device 和 user 上下文。进程退出码与 error.code 相同（1 或 5）。姿势采集在 120 秒后超时会终止整个校准运行；CLI 不会重试该姿势。
• event: "cancelled"、status: "cancelled"：报告用户已正常取消。退出码为 9。

还要检查进程退出码。若数据流结束时没有终端事件，不要将其视为成功。

安全取消

用户要求停止时，发送一次 Ctrl+C。CLI 会请求 SDK 操作取消，短暂等待操作结束，释放设备，发出 cancelled 事件，并以退出码 9 退出。继续等待该终端事件，不要立即强制终止进程。

解决常见故障

• the default SDK user cannot run hand model calibration：请用户使用 wuji user create <name> 创建一个命名用户，并使用 wuji user switch <name> 激活，然后在重试前请求确认。
• no device found：检查电源、USB 和本地网络连通性；仅在排查设备发现问题时使用 wuji devices --json。
• found N devices：显示候选设备的 SN，并请用户选择一个；绝不自动选择。
• hand model calibration requires a connected Wuji Glove：所选设备类型不正确，或不具备校准能力。
• 使用 --address 时连接失败：如果设备会话可能被其他程序占用，请改用 --sn 或不指定选择器后重试。
• 姿势超时 / 0x4101：当前姿势在 120 秒内未通过，整个运行失败。请用户调整姿势或查看教程，然后在再次运行命令前请求确认。--timeout-s 是单独的命令总时限，不会改变 SDK 每个姿势 120 秒的时限。
• 采集期间断开连接：恢复连接，并仅在用户确认后重新开始。

触觉校准工作流

使用 wuji calib tactile 为一只手套采集、训练、验证并安装接触模型。

选择并开始

wuji calib tactile --sn <SERIAL>

--sn 选项为必填项，因为每只手套都使用自己的接触模型。

如果命令通过脚本或 CI 作业运行，请使用无人值守模式：

wuji calib tactile --sn <SERIAL> --non-interactive

--non-interactive 会自动接受每个提示。按 Ctrl+C 中止。