i4h-workflow-scene-edit

编辑 i4h 工作流场景

目的

在一个实时模拟器会话中迭代现有场景，并且仅在收到明确的烘焙、保存或持久化指令时，才持久化已确认的状态。

说明

1. 运行检出解析器并检查目标所有权。
2. 默认启动或复用一个由桥接支持的实时编辑会话，并记录可见基线。
3. 阅读最少量的上游指南，并将每项请求的编辑作为独立、可观察的实时阶段事务应用，不更改源代码。
4. 收到明确的烘焙／保存／持久化指令后，导出累积的实时状态，检查解析后的创作事实，并让编码 Agent 编辑最小范围的所属源文件。
5. 持续运行会话以处理后续提示，直到用户明确要求停止或退出。
6. 烘焙时运行静态、持久化可见性以及受影响的动态验证。

解析并检查

解析检出内容之前，请使用下方维护的仓库，或用户或受信任项目配置已选定的替代来源。执行脚本前，先检查现有检出内容的来源和工作区改动；仅凭继承的环境变量不足以证明替代来源可信。遵循用户指定的修订版本并保留本地改动。如果来源不符合预期，请先停止并解析来源，再进行克隆或启动。

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
./run.sh list
./run.sh show <workflow>

将上述解析器视为技能契约的一部分：托管副本可能在基础仓库之外运行，因此切勿假设当前检出内容包含 workflows/i4h_workflows。I4H_WORKFLOWS_REPO_URL 用于选择克隆来源。未设置 I4H_WORKFLOWS 时，根据该 URL 推导回退目录；仅在复用或选择特定目标目录时设置 I4H_WORKFLOWS。切勿替换现有检出内容。

阅读 DESIGN.md、目标工作流、Scene Python、场景清单、具身化清单以及相关任务清单。使用 $ROOT/skills/i4h-workflow/references/repo-map.md 确定所有权。

对于 G1 面部、行走、伸手或碰撞敏感的成功契约，请阅读 references/g1-reach-and-contact.md。复用其中的 Tasks 和由 Scene 所属的占地接口；不要生成特定于工作流的运动辅助程序，也不要在 Workflow 中硬编码物体尺寸。

如果用户仅要求打开／运行而未要求编辑，则执行 ./run.sh <workflow> --idle；不要自行编造源代码改动。编辑场景的请求始终意味着启动或复用 ./run.sh <workflow> --live，除非用户明确要求离线／非实时操作。默认采用实时编辑，无需确认。“保存”“持久化”或“烘焙”意味着将累积的实时阶段编辑序列化到其所属源文件；未出现这些词时，保持源代码不变。“停止”或“退出”会关闭会话；若未要求持久化，则丢弃仅存在于实时阶段的编辑。不要仅因为完成了一项编辑提示就停止。

添加或调整大小之前，如果某个资产已出现在维护的场景中，请先阅读 references/existing-scene-assets.md。复用其中已知的 USD 身份、创作缩放、支撑高度、物理角色和具身化惯例，不要从原始 USD 重新发现这些信息。以所属 Python 文件为事实来源；仅在已知基线可见后，才使用视觉语言检查对特定场景进行有限微调。

建立可见基线

将现有 Scene 作为一个持久的实时创作会话打开。仅当 I4H_LOCAL_AGENT=1 时使用桥接：Local Agent 命令共用一个串行 shell，因此前台 --live 命令会阻塞所有后续编辑事务。

I4H_RUN_DIR="$(pwd)/runs/<workflow>/$(date +%Y%m%d_%H%M%S)"
if [ "${I4H_LOCAL_AGENT:-0}" = 1 ] && [ -x ./local-agent/bridge.sh ]; then
  ./local-agent/bridge.sh start <workflow> "$I4H_RUN_DIR"
else
  ./run.sh <workflow> --live --run-dir "$I4H_RUN_DIR"
fi

备用方案 ./run.sh <workflow> --live 必须通过宿主 Agent 的持久化／可让出前台会话机制运行。切勿将该备用方案作为普通阻塞式 shell 调用启动，并等待它退出后再进行编辑。

--live 会解析工作流声明的 idle 模式，在端口 8226 上启用 isaacsim.code_editor.python_server，并保持模拟器运行，直到显式停止。等待端口 8226 最长 ${I4H_AGENT_BRIDGE_TIMEOUT:-900} 秒（与桥接启动默认值一致）；如果启动器退出，则提前停止等待。超时后，报告运行日志和桥接阻塞原因，仅停止这个失败的会话；仅对已获授权的工作使用文档说明的离线备用方案；源文件持久化仍需执行 bake/save/persist。 就绪后，使用固定版本的上游 isaac-sim-remote 客户端检查并修改正在运行的 stage。所有常规编辑都只保存在该实时 stage 中；暂不更改所属源文件。后续编辑提示词应累积在同一会话中。只有“bake”“save”或“persist”才授权将已确认的实时值写入源文件。烘焙后，通过 run.sh 重启，验证持久化结果与实时 stage 一致，并在收到请求时停止。先离线编辑源文件再重新打开，不属于实时创作。

保留实时解释器体验

将复合提示词视为有序的编辑流，而不是一个批处理脚本。每个用户可见的操作都运行一次桥接事务，等待视口更新，检查结果，然后再应用下一个操作。例如，添加一张桌子、两个工具、两个托盘和一个机器人，就是六次实时事务。切勿把所有请求的编辑都藏在一个远程 Python 文件中，也不要在用户等待场景变化时修改源代码。

对于常见编辑，请在工作流根目录使用单操作辅助工具：

arena/.venv/bin/python scripts/live_scene_edit.py add-known-asset \
  --asset surgical_table \
  --prim-path /World/envs/env_0/Table \
  --position 0,0,0

arena/.venv/bin/python scripts/live_scene_edit.py add-cube \
  --prim-path /World/envs/env_0/RedCube \
  --position 0,0,0.3 \
  --size 0.1 \
  --color 1,0,0

arena/.venv/bin/python scripts/live_scene_edit.py scale-by \
  --prim-path /World/envs/env_0/RedCube \
  --factor 2

arena/.venv/bin/python scripts/live_scene_edit.py set-transform \
  --prim-path /World/envs/env_0/Robot \
  --position=-4.64,0,0.8 \
  --rotation 0,0,0

arena/.venv/bin/python scripts/live_scene_edit.py set-view \
  --eye 2.6,-7,3.4 \
  --target=-1.8,0,0.75

arena/.venv/bin/python scripts/live_scene_edit.py camera-from-view \
  --prim-path /World/envs/env_0/RoomCamera

arena/.venv/bin/python scripts/live_scene_edit.py capture-camera \
  --prim-path /World/envs/env_0/RoomCamera \
  --output-path "$I4H_RUN_DIR/room-camera.png"

当以逗号分隔的向量以负数开头时，请用 = 绑定它（例如，--position=-0.5,0.5,0.1），避免参数解析器将该值视为另一个选项。

该辅助工具有意限制为每次调用执行一个操作，会选中受影响的 prim、推进可见渲染更新，并打印生成的世界边界。对于已编入目录的 Healthcare 资产，优先使用 add-known-asset：它会复用规范 USD、比例、方向、物理元数据、附加摄像头元数据、具身元数据和预期公制边界，然后拒绝尺寸偏差超过 20% 的结果。g1 预设必须在实时机器人预览下方创建标准的 head 摄像头；若缺少摄像头 prim，则视为机器人编辑失败，启用该摄像头，并在继续前确认其视图。若没有可执行预设，请先参考 references/existing-scene-assets.md 及其所属源代码，再使用通用的 add-usd。这两个资产添加命令都会将引用放在变换包装器下方，防止被引用资产编写的根变换覆盖请求的实时位置、旋转或比例。add-known-asset、add-usd、add-cube 和 camera-from-view 会为其 prim 添加标签，以便确定性导出；如果无法根据 prim 路径通用地推导源名称或清单名称，请传入 --name 或 --alias。继续前请检查边界。快速检查摄像头画面时请使用 capture-camera：它会启用指定摄像头、安排同步的 FileCapture、推进渲染器，并拒绝缺失、空白或过时的输出。在持久桥接会话中，请勿使用上游异步视口截图辅助工具。如果不需要捕获画面，请使用 activate-camera；若要验证单个 prim，请使用 inspect。只有在辅助工具不支持某项操作时才使用原始 isaacsim_send.py，且每次调用仍只发送一个可观察的编辑；烘焙时明确记录任何未添加标签的 prim。

根据请求的工作区和测得的边界，推断一般性的支撑关系。原本要放在桌子、推车、托盘、垫板或地板上的机器人或物体，其底部支撑边界必须与相应表面对齐，占地范围也应合理地落在其上；不能仅因所有指定资产都已存在，就接受落地放置、悬空放置或明显相互穿插的布局。烘焙前，请在有界视觉评估标准中纳入这些支撑关系。

场景可见变化时，请发送简短的进度更新。首次执行请求的实时编辑前，不要花过多时间设计最终的源表示。实时结果生成后，再检查所有权并准备烘焙。

会话生命周期

• 在首次“编辑场景”提示时，仅当 I4H_LOCAL_AGENT=1 时使用 local-agent/bridge.sh；否则通过持久/可让出控制权的宿主会话启动 ./run.sh <workflow> --live。使用上文规定的有界就绪等待。
• 在之后的每次场景提示中，对于由 Local Agent 管理的会话，使用 ./local-agent/bridge.sh status <workflow> 和 rundir <workflow>；对于前台启动，则使用保留的宿主会话和运行目录。确认会话对应的是预期工作流；仅有端口在监听并不足以证明这一点。复用该会话；除非请求的更改有此需要，否则不要重置或重新启动 Scene。
• 在同一个实时舞台上分别执行每项添加/移动/旋转/缩放/材质/相机操作，选中受影响的 prim，推进视口，并在继续之前进行验证。
• 添加机器人后，验证其创作预设中声明的每台相机。对于 G1，必须确认实时的 Robot/Asset/head_link/RobotHeadCam 预览，并使用已注册的 G1 embodiment 进行烘焙，其中 robot_head_cam 传感器通过 head 别名公开。
• 每次提示后将控制权交还给用户，同时保持模拟器和桥接程序运行。
• 仅在获得明确授权后才进行烘焙。烘焙并不意味着停止，除非用户同时要求停止/退出。
• 如果用户要求停止/退出但未要求烘焙，则关闭会话并保持源文件不变。Local Agent 会话通过 ./local-agent/bridge.sh stop <workflow> 关闭。
• 仅当用户明确禁用实时模式或桥接程序无法运行时，才使用离线/源文件优先编辑。使用该回退方式前，先报告桥接阻碍；绝不要悄然替换。

使用上游 Isaac Sim 技能

阅读 references/isaacsim-skill-routing.md，然后仅加载请求所需的上游技能。编辑前说明技能选择。通用物理、相机、传感器、USD、渲染和空间推理应采用当前上游语义；并通过最接近的当前 i4h Scene 模式将其整合。

先实时迭代，再让编码 Agent 固化

先通过端口 8226 应用请求的资源、布局、物理、相机和变换更改。对于复合提示词，保留其顺序，并在每项操作后检查实时场景。不要仅仅因为最终负责的文件已确定，就提前修改文件。

明确要求固化／保存／持久化时，导出已确认的实时值，并解析可复用的目录事实，无需启动另一个模拟器：

I4H_RUN_DIR="runs/<workflow>/<YYYYMMDD_HHMMSS>"
mkdir -p "$I4H_RUN_DIR"

arena/.venv/bin/python scripts/live_scene_edit.py export-scene \
  --workflow <workflow> \
  --root-path /World/envs/env_0 \
  --output-path "$I4H_RUN_DIR/live_scene.json"

arena/.venv/bin/python scripts/authoring_info.py snapshot \
  <workflow> "$I4H_RUN_DIR/live_scene.json"

export-scene 会记录每个由助手管理的资源、基元、机器人和相机，以及已确认的变换和相机光学参数。将该快照保存在运行目录中，作为创作依据。只有在后续实时导出需要合并先前快照时，才通过 --baseline 传入该快照：现有 prim 会从当前场景重新读取，新添加带标签的 prim 会被纳入，已移除的 prim 则会被省略。authoring_info.py 是只读的；它会验证快照，并立即返回可用于代码的目录元数据和推导出的清单能力。它不会生成或编辑工作流代码。

随后，编码 Agent 会参照最接近且受维护的源代码模式，修改现有的资源、Scene 和清单模板。如果用户的请求包含提交更改，则检查 git diff -- <owning-files>，并且只暂存此任务的更改，保留无关编辑。只提交负责这些更改的源文件；不要提交导出的创作快照，也不要将其视为第二份 Scene 契约。切勿凭记忆复制可复用的 USD 路径、规范缩放比例、质量、具身注册表名称、动作契约、附加相机或相机别名：查询 authoring_info.py asset <preset> 或完整的快照报告，然后使用负责源文件中的目录数据。特定于 Scene 的名称、位置、相机光学参数和显式覆盖值则来自快照。

只写入负责的层：

• 将资源、布局、物理、相机、随机化、视图别名、驱动映射或重置钩子固化到 Scene／资源／envcfg 源代码中。
• 将跨边界的相机／对象名称、控制频率、上限或模式覆盖值固化到场景清单中。
• 将模式组合和目标语义固化到工作流中。
• 将可复用行为固化到 Task 中。
• 将跨进程的机器人标签、校准或远程操作设备固化到具身清单中。
• 将策略提示词、相机、观测、模型或训练契约固化到远程任务清单中。

在每个具体 API 边界处保留四元数约定。不要添加兼容性转换，也不要在 Python 和 YAML 之间重复目录事实。

对于基于当前透视图的相机，将视口姿态视为初始估计。根据与任务相关的边界框计算并验证稳定的实时注视目标。固化时，参照最接近的 Scene 模式添加已确认的环境局部相机，在清单中声明该相机，并验证所有应接收该相机的录制／策略使用方。

验证

./run.sh show <workflow> --mode <affected-mode>
./run.sh lint <workflow> --mode <affected-mode>
./run.sh lint --all
uvx ruff==0.5.2 check --config pyproject.toml <changed-python-files...>

上方的 Ruff 版本与维护中的检出版本 .pre-commit-config.yaml 相符；如果其中的固定版本发生变化，请使用该文件中精确固定的版本。通过每个受影响组件的 uv 项目运行针对性测试。编码 Agent 完成静态验证后，使用 ./run.sh <workflow> --live 重新打开一次，将每项请求的视觉变更和声明的相机与导出的快照进行比较，然后按要求停止。在导出、编辑源文件和检查持久化可见效果之间，不要额外重启。将持久化的变换、世界边界和相机视图与实时快照进行比较；静态 lint 无法发现错误的四元数约定。 从 run.sh list 和 run.sh show 中选择实际会使用已更改 Scene、Task、相机、观测或成功契约的动态模式。当物理、重置、驱动、策略观测、任务行为或成功条件发生变化时，运行这些模式。对于这些变更，仅运行 Idle 模式并不足够。

当成功条件排除碰撞时，动态验证必须包含一个强制接触的负向测试，以及一个来自 references/g1-reach-and-contact.md 的全新重置恢复测试。如果配置的接触信号始终只返回 false，就不要声称成功规则已通过验证。

需要清理时，使用 ./local-agent/bridge.sh stop <workflow> 停止托管会话，或中断其保留的前台会话，并确认其子进程已退出。./stop.sh all 会影响此检出中的其他运行；只有当这些运行都属于请求的清理范围时才使用它。

故障排查

启动前修复 manifest/workflow lint。如果渲染结果不同，请比较基线、创建的 prim、边界、相机和对应的源文件。进行一项有针对性的修正并重新验证；如果仍存在相同的不一致，请保留快照并报告未解决的差异，不要反复尝试或声称验证通过。

前置条件

需要有受支持且已存在的工作流、完整的模拟器设置，以及用于通用场景语义的相关上游 Isaac Sim 技能。

限制

新建工作流请使用 i4h-workflow-create。实时 Idle 模式可验证静止布局，但无法验证物理、驱动、策略观测或成功条件。实时会话仅在进程内有效；停止前请先导出，因为进程退出后，未导出的编辑会丢失。实时辅助工具支持常见资产、原始 USD、立方体、变换、相机、检查、捕获和导出；编码 Agent 负责源文件编写，以及这些工具未涵盖的语义。

示例

• 添加一个红色立方体，移动 G1，添加一个房间相机，烘焙所有变更，然后停止。 → 保持一个由 bridge 支持的模拟器会话开启，按顺序实时应用这三项编辑，在“烘焙”时导出并检查一份快照，修补并静态验证对应的源文件，然后重新打开一次以验证持久化后的可见效果，最后停止。

完成条件

报告使用的上游技能、实时会话/bridge 状态、实时应用的编辑、是否获准持久化、仅在烘焙期间变更的对应源文件、静态测试、实时与持久化后的可见观察结果、相机检查、动态运行结果（如适用，须包含碰撞负向证据）、正常停止状态，以及任何未解决的不一致。