i4h-workflow-validate

ワークフローを検証する

目的

選択したワークフローの実行モードを統合ランチャーで実行し、完了した記録を確認して、シミュレーターでの成功を報告します。

手順

1. ベースとなるチェックアウトと、実行可能なワークフローの実行モードを解決します。
2. 統合ランチャーをフォアグラウンドで実行します。
3. 最終エピソードの成功サマリーが出力されることを必須とします。
4. 表示された動作とすべてのロールアウト成果物を確認します。作成または変更した成功ルールで衝突を除外する場合は、以下の衝突があるケースも検証します。

export I4H_WORKFLOWS_REPO_URL="${I4H_WORKFLOWS_REPO_URL:-https://github.com/isaac-for-healthcare/i4h-workflows}"
I4H_REPO_DIR_NAME="${I4H_WORKFLOWS_REPO_URL%/}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*/}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*:}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME%.git}"
[ -n "$I4H_REPO_DIR_NAME" ] || { echo "Cannot derive a checkout name from I4H_WORKFLOWS_REPO_URL" >&2; exit 2; }
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/i4h_workflows" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/$I4H_REPO_DIR_NAME}"
  [ -d "$ROOT/workflows/i4h_workflows" ] || git clone "$I4H_WORKFLOWS_REPO_URL" "$ROOT" || exit 2
fi
[ -d "$ROOT/workflows/i4h_workflows" ] && [ -x "$ROOT/run.sh" ] || { echo "Incomplete workflow checkout: $ROOT" >&2; exit 2; }
export I4H_WORKFLOWS="$ROOT"
cd "$ROOT" || exit 2
git remote get-url origin || exit 2
git status --short || exit 2

報告されたリモートが意図したソースであることを確認し、リポジトリのスクリプトを実行する前にローカルの変更を確認します。想定外のソース、または未確認のランチャー変更がある場合は中止してください。次に、サポートされているモードを検出します。

./run.sh list

上記の解決手順はスキルの契約の一部として扱ってください。ホストされたコピーはベースリポジトリの外部で実行されることがあるため、現在のチェックアウトに workflows/i4h_workflows が含まれていると決めつけないでください。I4H_WORKFLOWS_REPO_URL はクローン元を指定します。I4H_WORKFLOWS が未設定の場合は、その URL からフォールバック先のディレクトリを導き出します。I4H_WORKFLOWS を設定するのは、特定の保存先を再利用または選択する場合に限ります。既存のチェックアウトを置き換えないでください。

./run.sh list の出力を、ワークフローとモードの完全かつ正式な一覧として扱ってください。このコマンドは依存関係が少なく、ワークフローモジュールをスキャンするより高速です。このスキル内で、変更される可能性のある一覧を重複して記載しないでください。ユーザーが自然言語で指定した名称を、一覧にあるワークフロー ID に対応付け、同じ行に示されたモードのみを選択してください。

ユーザーの意図	必須の実行モード	ランチャー引数
通常の学習済みポリシー評価	policy	--policy
要求された、または唯一利用可能なローカルコントローラー	rule-based	--rule-based
N1.7 のように明示的に指定された別モード	一覧にある対応モード（例：policy_n17）	--mode <name>

モデル、プロンプト、チェックポイント、ゴール、またはステップ上限の動作が重要な場合は、./run.sh show <workflow> --mode <mode>、ワークフローモジュール、Scene マニフェスト、選択した Task マニフェストを確認してください。

準備状況は正確に表現してください。

• 構造的に妥当：show、モードごとの lint、lint --all がすべて成功しています。
• 起動可能：選択したシミュレーターモードが起動し、必要なバックエンドとチェックポイントがすべてプリロードされています。
• ロールアウト検証済み：要求されたエピソードが完了し、記録された成功の証拠が検査に合格しています。

どのレベルに到達したかを明記せずに「検証済み」と報告しないでください。

フォアグラウンド実行ルール

run.sh は、このエージェントのフォアグラウンドツール呼び出しとして実行してください。サブエージェント、監視タスク、シェルのバックグラウンド実行、nohup、tmux、デタッチされたプロセスは使用しないでください。セッションが中断状態で返された場合は、終了するまでポーリングし、応答する前に最終エピソードの概要を確認してください。選択した Task がリモートの場合、run.sh が内部で所有するポリシーバックエンドのサブプロセスは想定どおりです。シミュレーター互換のエクスポート済み RSL-RL Task はプロセス内で実行されます。

デフォルトでは、実行状況を表示してください。ユーザーがヘッドレス実行を明示的に要求した場合、または文書化された環境上の制約により必要な場合は、起動前にその旨を伝え、--headless を含めてください。黙ってヘッドレスに切り替えてはいけません。

指定されたエピソード数を使用してください。指定がない場合は、1 エピソードのスモークチェックであることを伝え、N=1 に設定してください。ランチャーのエピソードごとの --attempts 3 の予算と、以下の実行全体を対象とする上限付きリカバリーは、別々に扱ってください。

ポリシー：

./run.sh <workflow> --policy \
  --episodes <N> --attempts 3 \
  --record verify.hdf5

ルールベース：

./run.sh <workflow> --rule-based \
  --episodes <N> --attempts 3 \
  --record verify.hdf5

ランチャーは一意な正規実行ディレクトリを作成し、相対パスの verify.hdf5 をその中に配置します。==> run dir ... 行または機械可読な run.json から RUN_DIR を解決してください。ランチャーのタイムスタンプを再作成してはいけません。別のステージと共有する場所を呼び出し元が選択した場合に限り、--run-dir "$RUN_DIR" を使用してください。ディレクトリはランチャーが作成します。絶対パスの記録先も引き続き使用できます。

別の宣言済みモードを使用する場合は、--mode <name> を指定してください。「300 timesteps」の場合は、--episode-steps 300 を渡してください。

指定チェックポイントの事前確認

指定されたチェックポイントを既存の絶対パスとして解決し、同じパスを --checkpoint に渡してください。./run.sh show <workflow> --mode <mode> を実行して、選択されるポリシー Task を特定してください。そのマニフェストとローダーを tasks/<project>/i4h_tasks/<project>/ で確認し、チェックポイントのモデル／エクスポートのメタデータを、必要なモデル、形式、観測値の順序／次元、アクションマッピングと照合してください。パスまたは契約を解決できない場合は中止してください。ファイル名から互換性を推測してはいけません。

リモート Task の場合は、宣言されたバックエンドの --preload-only オプションを使用してチェックポイントを読み込み、シミュレーターの起動前に終了してください。たとえば、gr00t_n15/assemble_trocar Task では次のコマンドを使用します。

uv run --project tasks/gr00t_n15 python -m i4h_tasks.gr00t_n15.server \
  --namespace assemble_trocar --preload gr00t_n15/assemble_trocar \
  --checkpoint /absolute/path/to/checkpoint --preload-only

別の Task の場合は、ライブ宣言から、その Task 独自のバックエンドプロジェクト、サーバーのエントリーポイント、Task ID を解決してください。この例のモデルファミリーを流用してはいけません。終了コードが 0 で、ローダーエラーがないことを確認してください。通常のフォアグラウンドロールアウト中は、実行ディレクトリ内のバックエンドログに ready for specs があり、実行時の観測値／アクション契約チェックが成功することも確認してください。読み込みに成功しただけでは、Scene との互換性は確認できません。

プロセス内の RSL-RL Task には、エクスポート済みの TorchScript policy.pt が必要です。上記で選択したフォアグラウンドポリシーコマンドに渡してください。Task は開始時に torch.jit.load で読み込み、最初のポリシーステップで出力形状をチェックします。起動可能と報告する前に、読み込みの成功と最初のポリシーステップの有効性を確認し、その後、指定されたエピソードを完了してください。このランタイム Task にネイティブのトレーナーチェックポイントを渡してはいけません。

show、lint、--dry-run は構造のチェックであり、ポリシーチェックポイントは読み込みません。ローダー／ランタイムチェックを実行できない場合は、実際に完了した構造チェックのみを報告し、チェックポイントの互換性やロールアウトの検証については報告しないでください。

Scene マニフェストの上限を引き上げてはいけません。--episode-steps でできるのは、その上限を下げることだけです。リモート推論の待ち時間はシミュレーションのステップ数に含まれません。同じワークフローの別の実行がアクティブな場合は、一意な --namespace を使用してください。

検証

終了ステータスが 0 であり、最終結果が N/N episodes succeeded であることを必須とします。失敗した試行の後に再試行が成功した場合、要求されたエピソードは成功したものとして数えます。試行回数と再試行回数を報告してください。

RUN_DIR="<absolute run_dir from run.json or launcher output>"
uv run --project tools/dataset i4h-dataset inspect "$RUN_DIR/verify.hdf5" --segments

エピソードのメタデータ、アクション／状態の幅、宣言されたカメラ、実行されたノードのセグメント、成功フラグを、Scene／Task の契約および最終サマリーと照合してください。データの欠落、破損、不整合がある場合、ロールアウトの検証はできません。失敗したチェックを報告してください。画面に表示される実行では、Scene／カメラの動作と最終的なタスク結果を確認してください。失敗時は、最初に対処可能なバックエンド、契約、グラフ、またはシミュレーターのエラーを使用してください。モードを切り替えたり、上限を黙って引き上げたりしないでください。クラッシュ後は、保持されているフォアグラウンドセッションを停止し、その子プロセスが終了したことを確認してください。./stop.sh all はこのチェックアウト内のすべての実行に影響します。対象とするクリーンアップの範囲内にすべての実行が含まれる場合に限り、使用してください。

衝突を除外する成功ルールを作成または変更した後は、Scene の接触設定を使って、設定されたボディペアをテストしてください。ゼロでないフィルター後の力、成功の拒否、リセット後に衝突履歴がクリアされることを必須とします。保存された証拠に、センサー名、力行列の形状、最大力、結果を記録してください。初期化できたことや力がゼロだったことだけでは不十分です。テストを実行できない場合は、検証上の不足を報告してください。

トラブルシューティング

対象範囲内で最初に対処可能なエラーを修正し、同じモード、上限、エピソード数で実行全体を一度だけ再試行してください。エラーが再発するか修正できない場合は、停止して実行ディレクトリとともに報告してください。エピソードごとの試行によって、この実行全体の再試行回数の上限がリセットされることはありません。

前提条件

選択した実行モードで宣言されている、同期済みのシミュレーターアセットおよびバックエンド／チェックポイントを必須とします。

制限事項

run.sh list に表示されるモードのみがサポートされます。また、実行時のステップ数の上書きで Scene の検証済み上限を下げることはできますが、引き上げることはできません。

例

• Evaluate scissor pick and place for 2 episodes. → 2 つのエピソードが成功するまでポリシーモードで実行し、記録、確認したうえで、試行回数と画面上で確認できる結果を報告します。
• Run surgical_reach_psm in rule-based mode for 1 episode. → 宣言されているローカルコントローラーモードのみを使用します。

完了条件

ワークフロー、モード、モデル／チェックポイントの取得元、要求された成功数、試行／再試行回数、完了ステップ数、画面上で確認できる結果、HDF5 のパスと確認結果、該当する場合は衝突を含む失敗／リセットの証拠、最終終了ステータス、未解決の失敗がある場合はそのうち最初のものを報告してください。