i4h-workflow-validate

验证工作流

目的

通过统一启动器运行选定的工作流运行模式，检查已完成的录制内容，并报告模拟器是否成功。

说明

1. 确定基础检出目录和可运行的工作流模式。
2. 在前台运行统一启动器。
3. 要求提供最终回合成功摘要。
4. 检查可见行为和每项 rollout 产物；对于新编写或已更改的排除碰撞成功规则，还要验证下方的碰撞反例。

确定实时支持情况

使用下方维护的仓库，或用户指定的来源，或受信任的项目配置中选定的来源。仅凭继承的环境变量不足以授权使用其他来源。遵循指定的修订版本，并保留本地更改。

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 均通过。
• 可启动：选定的模拟器模式成功启动，且所有必需的后端和检查点均已预加载。
• Rollout 已验证：请求的回合已完成，且录制的成功证据通过检查。

报告时若使用“已验证”，必须说明实际达到的级别。

前台执行规则

将 run.sh 保持为此 Agent 的前台工具调用。不要使用子 Agent、监控任务、Shell 后台运行、nohup、tmux 或脱离终端的进程。若会话返回控制权，请持续轮询，直到进程退出，并在回复前检查最终回合摘要。当选定的 Task 是远程 Task 时，run.sh 内部管理的策略后端子进程属于预期行为；与模拟器兼容的导出 RSL-RL Task 在进程内运行。

默认以可见方式运行。如果用户明确要求无头执行，或有文档说明的环境限制使其成为必要，请在启动前说明，并加入 --headless；绝不要悄悄切换为无头模式。

使用指定的回合数；如果未指定，请说明这是一次单回合冒烟检查，并设置 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 个时间步”，传入 --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 id；不要照搬示例中的模型系列。要求退出状态为 0，且没有加载器错误。在正常的前台运行过程中，还必须确认后端日志位于运行目录中，且其中包含 ready for specs，并且运行时观测／动作契约检查成功。成功加载本身并不能证明与 Scene 兼容。

进程内运行的 RSL-RL Task 则需要导出的 TorchScript policy.pt。将其传给上方选定的前台策略命令；Task 进入时会通过 torch.jit.load 加载该文件，并在首次策略步骤检查其输出形状。只有确认加载成功且首次策略步骤有效后，才能报告该 Task 可启动；随后完成指定回合。不要将原生训练器检查点传给此运行时 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 合约和最终摘要，检查剧集元数据、动作/状态宽度、声明的摄像头、已执行节点片段和成功标志。数据缺失、损坏或不一致时，禁止验证 rollout；报告未通过的检查。对于可视运行，观察 Scene/摄像头行为和最终任务结果。发生失败时，使用第一个可采取行动的后端、合约、图或模拟器错误；不得静默切换模式或提高上限。发生崩溃后，停止保留的前台会话，并确认其子进程已退出。./stop.sh all 会影响此检出目录中的所有运行；仅当所有这些运行都在请求的清理范围内时才使用。

在编写或更改排除碰撞的成功规则后，使用 Scene 的接触设置测试配置的实体对。要求过滤后的力非零、成功被拒绝，并且重置后碰撞历史已清除。将传感器名称、力矩阵形状、最大力和结果记录在保存的证据中。仅完成初始化或得到零力并不足够。如果无法运行此测试，请报告验证缺口。

故障排除

在范围内修正第一个可采取行动的错误，然后使用相同模式、上限和剧集数量完整重试一次。如果错误再次出现或无法修复，请停止并报告错误及运行目录。单个剧集的尝试不会重置整次运行的重试次数上限。

前置条件

要求模拟器资源已同步，且所选运行模式声明的任何后端/检查点均已就绪。

限制

仅支持 run.sh list 中的模式，运行时步骤覆盖值可以降低已验证的 Scene 上限，但不得提高。

示例

• 评估剪刀取放，运行 2 个剧集。 → 以策略模式运行两个成功的剧集，记录、检查并报告尝试次数及可见结果。
• 以基于规则的模式运行 surgical_reach_psm，运行 1 个剧集。 → 仅使用声明的本地控制器模式。

完成门槛

报告工作流、模式、模型/检查点来源、请求的成功次数、尝试/重试次数、完成步骤、可见结果、HDF5 路径及检查结果、适用时的碰撞负向/重置证据、最终退出状态，以及任何尚未解决的首个故障。