wuji-cli-calib

Wuji CLI 調整

調整リクエストを適切なワークフローに振り分け、物理的な操作や永続的なモデルの変更には人間が関与するようにします。

リクエストの振り分け

• ハンドモデルの調整では、コマンドを実行する前に、このファイルのハンドモデルワークフローに従います。
• 触覚の調整では、コマンドを実行する前に、このファイルの触覚ワークフローに従います。
• ハンドモデルと触覚の意味を混同しないでください。ハンドモデルの調整では、現在の SDK ユーザーと手の側に対応するモデルを公開します。触覚の調整では、特定のグローブ SN 用の接触モデルをトレーニングしてインストールします。
• ハンドモデルの調整結果は、接続後に特定される、デバイスが紐付けられているユーザーに帰属します。wuji calib hand-model がスキャンまたは接続している間に、別のプロセスが SDK ユーザーを切り替えると、CLI は切り替えを報告し、紐付けられたユーザーに調整結果を帰属させます。そのユーザーが Default の場合、ポーズの収集を開始する前に終了コード 5 で停止します。その後の wuji user list の結果ではなく、コマンド自身の出力に示されたユーザーを信頼してください。

共通の安全ルールを適用する

• 調整は永続的に状態を変更する操作として扱います。ステータス確認、ヘルプ、計画、またはトラブルシューティングのみの依頼では開始しないでください。
• 開始前に、実行する調整モードと、人間が指示された物理的な操作を行う必要があることを伝えます。ユーザーの現在のリクエストでそのモードを今すぐ開始することが明示的に許可されている場合を除き、確認を得てください。
• 直接監視する Human TTY フローでは、wuji devices を必須の事前確認として追加しないでください。セレクターが指定されていない場合、ハンドモデルの調整は自動的にスキャンして接続します。エージェントがガイドする JSONL 調整では、開始前に SN と利き手を特定し、デバイスの選択、上書きの確認、最終的な識別情報を明確にしてください。触覚の調整では常に --sn が必要です。
• ユーザーがデバイスを選択している場合は、ハンドモデルの調整にも明示的な --sn を指定することを優先し、触覚の調整では必ず指定してください。複数のデバイスから、ユーザーが特定していないものを選んではいけません。
• ターミナルイベントが出力されて終了するまで、コマンドをストリーミングターミナルセッションに接続したままにします。調整が実行中の間に、別の調整を開始しないでください。
• キャンセルのリクエストを受けたら、Ctrl+C を一度送信し、CLI が SDK の操作を停止してデバイスを解放するまで待ちます。
• 失敗またはキャンセルされた調整を自動的に再試行しないでください。再試行すると物理的なワークフローが再び始まるため、失敗の内容を説明し、再開する前に確認を求めてください。

結果を報告する

• コマンドから情報が得られる場合は、終了ステータス、選択したデバイスの SN、モデルの識別情報、出力アーティファクトを報告してください。
• コマンドの失敗とユーザーによるキャンセルを区別してください。ハンドモデルの調整の終了コードは wuji user の規約に従います。0 は成功、5 は Default ユーザー保護、9 はキャンセル、1 はその他の失敗です。ハンドモデルの JSON／JSONL エラーにも数値の error.code が含まれます。触覚の調整中に Ctrl+C を2回目に押すと、コード 130 で直ちに終了します。
• デバイスの SN からモデルの所有者を推測してはいけません。選択した調整モードから返された識別情報フィールドを使用してください。

ハンドモデル調整ワークフロー

このワークフローに従って、ハンドモデルの wuji calib hand-model を行う人間を案内し、構造化された進行状況を監視してください。

事前条件の確認

開始する前に、以下のすべてを確認してください。

• ユーザーが今すぐハンドモデルのキャリブレーションを開始する意思があり、ハンドポーズを実行する準備ができていること。
• 直接画面を見ながら実行する Human TTY の場合は、組み込みプロンプトを使って、対象の名前付きユーザーを作成するか切り替えてください。--json / --jsonl またはリダイレクトされた Human 出力の場合は、開始前に名前付きユーザーへ切り替えてください。非対話型の出力でも Default は拒否され、終了コード 5 が返されます。
• Human TTY のフローでは、ターミナルが幅81列以上、高さ38行以上の場合、サイズ固定のカラー左／右ポーズ図が表示されます。ターミナルがそれより小さい場合は図が非表示になり、ウィンドウを拡大してキャリブレーションを再起動するようユーザーに案内します。この図は CLI に含まれており、この公開 Skill には同梱されていません。エージェントが案内する JSONL 実行では、フィードバックに基づくテキストの指示を使用します。
• 成功すると、現在の SDK ユーザー用に left_hand.urdf または right_hand.urdf が公開され、オンライン利用のためにハンドモデルがホットリロードされることをユーザーが理解していること。同じユーザー、同じ手側を再キャリブレーションすると、使用するグローブが異なっていても、その安定モデルは置き換えられます。
• Wuji Glove の電源が入り、USB またはローカルネットワーク経由で接続できること。

Human TTY フローでは、既存のハンド URDF を上書きする前に確認を求め、既定では No を選択します。マシンモードでは確認を求めないため、ユーザーの現在の依頼で再キャリブレーションが明示的に許可されていない限り、--json / --jsonl を起動する前に確認を得てください。

選択して開始する

ターミナルを見ている人間が操作する場合は、次を実行します。

wuji calib hand-model

Cliclack の操作フローでは、現在のユーザーの左右の状態を表示し、ユーザーの作成または切り替えを促した後、Wuji Gloves をスキャンして一覧表示します。次に、使用するグローブを選択し、上書きは縦方向の Yes/No セレクターで確認してから、6 つのライブポーズ手順を表示します。ポーズの図は拡大縮小されません。CLI は、ターミナルに 60 列のガイドブロックとライブ表示の両方を収められる場合に限り、固定サイズの ANSI ガイド全体を表示します。公開に成功すると、Calibration finished にはユーザー、利き手、URDF の結果（ファイルサイズと現地時刻を含む）のみが表示されます。User show は wuji user show と同じ完全なプロフィール一覧を開き、Recalibrate は追加の確認を挟まずにユーザー選択の入口へ戻り、Finish は成功の概要を再度表示せずに終了します。次のデバイスが接続され、利き手が判明した後は、通常の上書き確認が行われます。

エージェントのガイドに沿ってキャリブレーションを行う場合は、状態を変更するコマンドを開始する前に、次の事前確認を実施します。

1. wuji user show --json を実行します。現在のユーザーが Default の場合は停止します。選択した手がすでにキャリブレーション済みの場合は、現在の依頼で再キャリブレーションが明示的に許可されていない限り、上書きの確認を取ります。
2. 人間がすでに選択した SN を使用します。選択されていない場合は wuji devices --json を実行します。Wuji Glove が 1 台だけ表示される場合はそれを使用し、複数表示される場合は人間に選択を求めます。
3. wuji get hand_side --sn <SN> --json を実行し、value の値を left または right として保持します。値がないか無効な場合は停止します。
4. 同じデバイスを、永続的なストリーミングターミナルで開始します。

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

マシンモードではプロンプトは表示されません。プロセスを接続したままにし、頻繁にポーリングして、終端イベントが発生してプロセスが終了するまで続行します。キャリブレーションがデバイスを使用している間は、別のデバイスコマンドを実行しないでください。

リダイレクトされた自動化で、人間に視覚的なガイドを表示しない場合は、セレクターを省略することもできます。

wuji calib hand-model --jsonl

コマンドは自動的にスキャンします。デバイスが 1 台だけなら接続し、0 台なら 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> を使用してください。

エージェントのガイドに沿ったキャリブレーションには、進行状況をストリーミングする --jsonl を使用してください。ユーザーがターミナルを直接見る場合は、人間向けの出力（wuji calib hand-model）を使用します。ライブガイダンスでは --json を使用しないでください。最終ドキュメントのみが出力されます。

JSONL からのガイド

標準出力の各行を 1 つの JSON オブジェクトとして解析します。schema_version: 2、operation: "calibrate"、calibration: "hand_model" を想定します。

すべての進行状況イベントには、Python コールバックに公開されるものと同じキャリブレーションフィールドを含む feedback があります。独立した 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 → 4 本の指を約 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 で、該当するメトリックが残っていない場合は、現在のポーズを調整するよう人に依頼します。同じ内容を繰り返し説明するのは控え、一度に表示する診断行は最大 8 行にします。

ユーザーへの通知が多くなりすぎないようにします。ポーズや状態が変化したとき、診断に大きな変化があったとき、またはユーザーに操作を依頼する必要があるときに説明します。最後のポーズの後に、通知のない数値計算と結果の公開フェーズが続くことがあります。全体のタイムアウト内で待ち続け、フィードバックが一時的に止まっただけで処理が停止したと判断しないでください。

終了イベントの処理

終了イベントは JSONL で必ず 1 つだけ発生します。

• 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 を表示し、ユーザーに1つ選んでもらってください。自動で選択してはいけません。
• hand model calibration requires a connected Wuji Glove：選択したデバイスの種類が異なるか、キャリブレーション機能に対応していません。
• --address を指定した接続失敗：別のプログラムがデバイスのセッションを保持している可能性がある場合は、--sn を指定するか、セレクターを指定せずに再試行してください。
• ポーズのタイムアウト／0x4101：現在のポーズが120秒以内に合格せず、実行全体が失敗しました。人にポーズを調整するかチュートリアルを確認してもらい、コマンドを再実行する前に確認を求めてください。--timeout-s はコマンド全体の別の期限であり、SDK のポーズごとの120秒の制限は変更しません。
• データ収集中の切断：接続を復旧し、ユーザーの確認後にのみ再開してください。

触覚キャリブレーションのワークフロー

wuji calib tactile を使って、1つのグローブ用の接触モデルを収集、トレーニング、検証、インストールします。

選択して開始

wuji calib tactile --sn <SERIAL>

各グローブはそれぞれ独自の接触モデルを使用するため、--sn オプションは必須です。

コマンドをスクリプトまたは CI ジョブから実行する場合は、ハンズオフモードを使用してください。

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

--non-interactive は各プロンプトを自動的に承認します。中止するには Ctrl+C を押してください。