isaac-mission-control-showcase

Mission Control 展示

对于默认的小型仓库 Nova Carter 展示，请使用随附的运行器。 它负责集成，并在运行时解析而非随项目一同打包的五项上游技能，从而协调它们。 首次运行前，请使用 python3 "$SKILL_DIR/scripts/doctor.py" dependencies --prepare 一次性解析这些依赖。

主机交换空间变更安全

未经用户明确批准具体操作、设备或文件路径以及大小，绝不要创建、调整大小、启用或移除主机交换空间。例如，“在 /swapfile 创建一个 8 GB 的交换文件”明确了这三项。笼统要求运行展示、通过预检或解决内存不足，都不构成进行任何交换空间变更的授权。如果内存预检未通过，请报告内存不足的情况，并建议释放内存或使用配置更高的主机。仅当用户希望采用此方案时，才询问其是否明确批准具体的交换空间变更；在获得批准前，不要提供更改交换空间的命令，也不要执行相关变更。交换空间变更可能会在展示结束后继续生效。

定位随附资源

运行任何命令前，请根据技能加载器提供的技能位置，将 SKILL_DIR 设为包含此 SKILL.md 的目录的绝对路径。每次 shell 调用时都要保留此值。不要从当前工作目录推导此路径，也不要假定源码仓库布局或固定安装目录。

本文档及其引用中提到的所有随附路径，包括 scripts/、 references/、shared/、assets/、config/ 和 upstream-versions.lock.json，均相对于 SKILL_DIR。请在该目录下读取这些路径，并在参考文档中的命令示例里引用随附脚本路径时，为其添加 "$SKILL_DIR/" 前缀。运行时输出路径和依赖清单报告的上游技能路径保留其各自的位置。以下命令可在任意工作目录中运行。

运行时选择

始终通过此展示项目的运行器从本地安装启动 Isaac Sim，并在主机显示屏上显示其 GUI 窗口。在该窗口中观察机器人。所有阶段操作都通过 ISAAC_PYTHON_PORT 上的 isaac-sim-remote Python 服务驱动。此工作流不使用 WebRTC、浏览器查看器或容器化的 Isaac Sim。

预检之前，以只读方式检查现有状态。确定安装路径和版本、是否存在 isaac-sim.sh 和捆绑的 ROS 2 桥接库、是否有可用显示器，以及是否已有 Isaac Sim 在运行。不要启动或导入 Isaac Sim，不要启动或停止容器，不要运行安装程序，也不要更改文件。

将已安装版本、仓库 URI、Nova Carter 资源和传感器图，以及就绪探针视为一个兼容性整体。仅仅存在 Isaac Sim 并不能证明兼容。

应用以下选择策略：

• 如果 ISAAC_SIM_DIR 中存在 6.1.0 安装，报告检测到的版本并继续，无需进行不必要的询问。

• 如果检测到的是其他版本，且启动器、ROS 2 桥接和已验证的仓库 URI 均存在，则自动使用该版本，无需询问，并报告选择结果：

  在 <path> 检测到 Isaac Sim <version>，可以使用（启动器 <ready/status>，ROS 2 桥接 <ready/status>）。正在使用此安装。

  尝试执行常规预检和就绪契约；如果存在不匹配，则停止并报告，不要修改该安装。

• 仅当无法确定版本，或无法确认启动器、ROS 2 桥接、已验证的仓库 URI 中任何一项时，才在预检前询问用户——这是唯一需要用户输入的运行时选择情形，因为无法安全地验证任何自动选择：

  检测到 Isaac Sim <version>，位于 <path>。启动器： <ready/status>。ROS 2 桥接：<ready/status>。请选择使用检测到的版本，还是选择或安装其他版本。

• Mission Control 云端堆栈和 Nova Carter SIL 仍需要 Docker，但 Isaac Sim 本身绝不需要。

• 如果未安装任何版本，则转到已解析的 isaac-sim-installation 技能，不要猜测路径。通过 python3 "$SKILL_DIR/scripts/doctor.py" dependencies 解析它；绝不要搜索该技能，也不要随附一份副本。

绝不要为了恢复展示项目而升级、降级、覆盖、删除、修复、重新标记、刷新或以其他方式修改现有 Isaac Sim 安装。停止已经运行的 Isaac Sim 前，必须获得用户明确指示。

如果用户要求安装、升级、降级或以其他方式获取不同版本的 Isaac Sim，则停止展示项目工作流，并交接给已解析的 isaac-sim-installation 技能。读取依赖清单报告路径下该技能运行时的 SKILL.md，并遵守其自身的门槛，不得绕过任何门槛。不要在此处复述或重述其安装逻辑。运行器要求本地独立安装，因此请预先选择该方式。报告安装路径后即停止；不要启动 Isaac Sim。只有在该技能完成交接且用户要求继续后，才恢复运行时选择。 该技能运行兼容性检查时，优先使用较大的 --timeout-seconds 值，例如 3600；首次运行仍在填充着色器和资源缓存时，默认的 600 秒通常会超时。

默认工作流

1. 检查用户是否已在对话中指定其他地图、机器人平台、模拟器或任务目标；如果没有，则使用规范默认值，无需询问。在预检前，告知用户 规范默认值 和 确定性路线 中的确切仓库 URI、机器人 ID carter01、按顺序排列的全部五个航点坐标、仅路线任务类型，以及 900 秒的任务超时时间。说明默认演示命令 bash "$SKILL_DIR/scripts/run.sh" --demo 使用这些值，且不进行场景覆盖。即使预检随后阻止运行，也必须发布此说明。

2. 按照 运行时选择 操作，不得更改任何检测到的安装。处理用户的选择或安装交接，然后运行只读预检：

   bash "$SKILL_DIR/scripts/run.sh" --preflight
   

3. 要求用户停止或迁移所有已报告且未明确允许的运行中容器。允许按确切容器名称指定无关工作负载，重复使用 --ignore-container NAME；被忽略的容器仍须接受常规端口冲突检查。不要自动停止现有的 Isaac Sim。确保 ISAAC_PYTHON_PORT 空闲。

4. 启动整个运行栈，并让机器人保持空闲：

   bash "$SKILL_DIR/scripts/run.sh"
   

5. 或者运行确定性的闭合路线并等待完成：

   bash "$SKILL_DIR/scripts/run.sh" --demo
   

6. 在运行程序打开的 Isaac Sim 窗口中观察机器人。运行程序会先加载场景，再启动 Carter，因此可以看到机器人的初始运动。

7. 仅停止记录在案的演示资源：

   bash "$SKILL_DIR/scripts/run.sh" --stop
   

每次运行都会在任何内容启动前，将 run-manifest.json 写入其工作目录，并在每次状态转换时更新它，以便准确描述和停止中断的运行。run-result.json 是机器可读的验收产物。使用以下命令检查运行，包括已中断的运行：

python3 "$SKILL_DIR/scripts/showcase.py" \
  run-status --work-dir <dir>

停止操作仅针对运行记录的容器，可重复执行，并会保留日志和证据。观察到运动时会持久化运动证据，因此之后的静止采样不会覆盖已确认的观察结果。验收标准始终严格：任务为 COMPLETED，机器人在线、健康且处于 IDLE 状态，运动已确认，无 OOM，且必需进程健康。

请参阅 references/troubleshooting.md，了解生命周期状态、恢复流程、运动判定、Isaac Sim 退出处理、主机内存策略以及 ROS 2 bridge 可执行文件检查。

运行程序会在 ${TMPDIR:-/tmp} 下创建一个全新目录，并打印其路径；所有生成的 Mission Control 配置、地图、Isaac 缓存、日志和状态都写入该目录。不得在调用方的工作目录中创建运行时文件。如果 Nova Carter 容器创建后启动或演示执行失败，运行程序会将带完整时间戳的 ROS 2 启动输出保存到 $SHOWCASE_WORK_DIR/logs/nova-carter-ros2.log。使用 --stop 停止 Nova Carter 后，也会更新同一日志。

组合模型

分为两层。

随包提供且由父项目拥有——本包中的所有内容：references/、 shared/、scripts/、assets/、config/。references/ 目录树包含为 本展示项目编写的集成适配器和路由约定。它们不是上游技能的副本。

运行时解析——本展示项目编排的五项技能。它们由各自的仓库拥有，从本包 之外固定版本的检出目录中读取并调用，绝不复制进来。

下表中的适配器路径相对于相应的 reference 目录。

Reference	面向	适配器
references/bring-up-cloud-stack/	bring-up-cloud-stack	scripts/run.py
references/change-map/	change-map	scripts/run.py
references/change-fleet-composition/	change-fleet-composition	scripts/run.py
references/isaac-sim-remote/	isaac-sim-remote	scripts/run.py
references/isaac-sim-installation/	isaac-sim-installation	无，按设计如此

upstream-versions.lock.json 是唯一的依赖声明：其中列出了两个公开的 GitHub 仓库、固定的 ref 和不可变提交，以及每项技能所需的入口文件和资源。

每台主机解析一次，然后运行：

python3 "$SKILL_DIR/scripts/doctor.py" dependencies --prepare \
  --env-file "$HOME/.mission-control-showcase/state/showcase-deps.env"

scripts/doctor.py 会运行两个阶段：dependencies 阶段解析上游技能并写入清单， host 阶段检查此机器。必须先成功完成依赖阶段，因为主机阶段会使用该阶段 解析出的入口文件。

有关阶段路由，请阅读 references/workflow.md；使用某个阶段前，请先阅读其 reference 中的 README.md。

使用上游技能

reference 会告诉你上游技能的位置；上游技能会告诉你它的行为方式。

1. 阅读其运行时 SKILL.md，路径由清单中的 skills.<name>.skill_md 记录。本包中的任何内容都不会重述它。
2. 遵循其自身的门控要求，包括确认、许可和执行审批门控。
3. 通过 reference 适配器调用它；适配器会从技能自身目录运行它，以便正确解析相对资源。
4. 切勿重新实现它、将其打包进本项目，或改用机器上找到的其他副本。

请勿使用 --with-sim 调用 bring-up-cloud-stack；这会启动通用的 mission-simulator，而不是 Nova Carter SIL。本展示项目负责 Nova SIL、Isaac Sim 的启动和关闭、场景恢复、跨域就绪状态、任务提交和完成证据。

缺少依赖

运行器会执行只读的新鲜度检查，适配器会使用已持久化的清单。正常执行绝不会 克隆、获取、拉取、安装或更新任何内容。

设置 MISSION_CONTROL_SHOWCASE_REQUIRE_PREFLIGHT=1 后，无法加载就绪清单的 reference 会阻止执行，而不会回退到发现流程。适配器会以 3 退出，并输出 BLOCKED [<component>]: …，说明技能名称、预期内容和预检命令。切勿通过将技能 打包进本项目来绕过阻止。

规范默认配置

默认配置如下：

• Isaac Sim：位于 ISAAC_SIM_DIR 的本地安装（默认为 ~/isaacsim）， 以 GUI 窗口启动。已知最后一个运行正常的版本是 Isaac Sim 6.1.0。 这只是默认配置，并非兼容性上限。
• Warehouse： https://omniverse-content-production.s3-us-west-2.amazonaws.com/Assets/Isaac/6.1/Isaac/Environments/Simple_Warehouse/warehouse.usd。
• Nova Carter SIL： nvcr.io/nvidia/isaac/nova_carter_sil:release-3.2。
• NVIDIA 驱动 R590 或更新版本。
• 64 GB 级别的主机，启动前至少有 48 GB 可用内存和 4 GB 可用交换空间。
• Nova Carter SIL 的内存限制为 20 GB RAM，外加最多 4 GB 交换空间。
• 机器人标识：carter01。
• Isaac Sim Python 服务使用端口 8226。
• Websocket MQTT 使用端口 9001，与打包的 Mission Control 堆栈匹配。
• Isaac Sim 和 Carter SIL 均使用 ROS domain 77，并采用正常的主机 传输。隔离的 domain 可防止无关的 domain-0 DDS 参与者耗尽 Carter SIL 内存，同时保留 Isaac 与 SIL 之间的发现能力。

确切的仓库 URI 会传入 Isaac Sim，并在场景加载后进行验证。切勿通过 get_assets_root_path、本地缓存、源代码检出目录或文件系统搜索来查找仓库。

runner 会配置 Mission Control 并启动云端堆栈，然后在云端初始化期间启动 Isaac Sim 并恢复场景。Carter SIL 最后启动，因此 Isaac Sim 窗口会显示机器人的初始运动。

对于用户选择的、已安装的非规范 Isaac 版本：

1. 要求使用兼容的安装版本和规范资源 URI。

2. 显式传入两者：

   ISAAC_SIM_DIR=<resolved-install-path> \
   WAREHOUSE_USD_URI=<resolved-uri> \
     bash "$SKILL_DIR/scripts/run.sh"
   

3. 不要通过替换版本号来推断未来的 URI。本地安装不带可供检查的版本标签，因此资源契约由调用方负责。

4. 如果请求的版本尚未安装，请停止并交由 isaac-sim-installation 处理；不要在此工作流中安装该版本。

机器人标识

carter01 只是默认值。可通过以下任一方式设置其他标识：

bash "$SKILL_DIR/scripts/run.sh" \
  --robot-name my_robot --demo

或使用 ROBOT_NAME=my_robot。

runner 会将相同的值应用于 Mission Control 车队配置、Mission Client 的 serial_number、MQTT bridge 客户端名称、就绪状态轮询和任务提交。不要只更改任务负载。

确定性路线

默认回放是一条闭合路线：

[
  {"x": -5.1, "y": 1.4},
  {"x": -2.625, "y": 1.2},
  {"x": -0.2, "y": -2.075},
  {"x": -2.625, "y": -5.35},
  {"x": -5.1, "y": 1.4}
]

将其作为仅包含路线的任务提交，超时时间设为 900，solver 使用 NVIDIA_CUOPT。不要添加起点／终点位置或迭代次数。

对于自定义坐标，先在不使用 --demo 的情况下启动堆栈，再通过 WPG nearest_nodes 对请求点进行对齐，使用 visualize_route 验证，最后仅提交得到的可路由点。

就绪条件

只有确认以下所有条件后，运行器才能提交任务：

• 规范阶段处于活动状态，且 Isaac 时间线正在播放；
• ROS /clock 持续前进；
• 实时 /scan LaserScan 使用帧 front_2d_lidar，且其时间戳与仿真时间相差不超过一秒；
• TF 能在该传感器的准确时间戳将 LiDAR 帧解析到 map；
• map -> base_link 可解析；
• 机器人位姿位于活动全局代价地图内；
• Nav2 规划器、控制器和导航器生命周期节点均处于活动状态；
• Carter SIL 未记录 cgroup OOM 事件，且其所需的地图、定位、规划、控制、导航和任务客户端进程仍在运行；
• Mission Control 报告已配置的机器人在线、状态为 IDLE、无错误、位置已初始化，且位于重置位姿附近。

将初始的准确时间戳 LiDAR TF 未命中视为有时限的启动状态。 继续读取更新的扫描样本，直到其中一个能解析到 map；如果在就绪期限前仍未解析，则报告失败，并附上最新测得的时间戳。绝不能用最新 TF 查询替代这一检查。

失败时，报告未通过的观测项及测量值。没有这些测量数据时，不要断言根本原因是时钟、TF、代价地图或权限问题。

捆绑的 carter_warehouse_navigation.png 及其配套 YAML 是唯一地图资源。运行时会将这对文件复制到 Mission Control 生成的配置中，以及 Carter SIL 的只读 /maps 挂载中。Mission Control 使用相同的 PNG 和元数据，在 carter_warehouse_navigation.png 下生成 WPG 资源。运行器会在启动前校验源文件、Mission Control 和 Carter 的哈希值，然后校验活动 WPG 地图标识、Carter 启动选项和容器挂载的文件内容。绝不要递归更改源目录树的权限，也不要在服务启动后应用权限修复。

模式和覆盖项

• --preflight：只读检查安装、显示、Docker、GPU、依赖项、端口、镜像和资源。
• 不带参数：干净启动并完整验证就绪状态，然后让机器人保持空闲。
• --demo / --replay：启动、就绪验证、圆形任务、规范任务完成状态和位姿运动证据。
• --stop：停止最后记录的服务栈，并向 Isaac Sim 进程发送 SIGTERM；不删除容器、镜像、卷、缓存或日志。
• --dry-run：打印解析后的命令，不更改运行时状态。
• --work-dir PATH：使用调用方指定的新建或空运行目录。
• --no-pull：要求所需镜像已在本地。
• --ignore-container NAME：在预检和启动期间，允许一个名称完全匹配且已在运行的容器；每个允许的容器都要重复指定该选项。端口冲突仍视为失败。

支持的环境变量覆盖项包括 ISAAC_SIM_DIR、WAREHOUSE_USD_URI、NOVA_CARTER_IMAGE、NOVA_CARTER_MEMORY_LIMIT、NOVA_CARTER_MEMORY_SWAP_LIMIT、ROBOT_NAME、SHOWCASE_GPU_DEVICE、SHOWCASE_ROS_DOMAIN_ID、SHOWCASE_ROS_LOCALHOST_ONLY、ISAAC_PYTHON_PORT 和 SHOWCASE_WORK_DIR。除非默认隔离域与其他本地 ROS 部署冲突，否则请保留默认值。对 Isaac Sim 和 Carter SIL 应用相同的域和 localhost 设置。未经验证主机 Isaac Sim bridge 与使用主机网络的 Carter SIL 之间能否跨进程发现，不要启用 localhost-only 传输。

验收

成功的 --demo 必须满足：Mission Database 报告提交的任务状态为 COMPLETED，同一机器人无错误地返回 IDLE，并且 Mission Database 中的位姿能够证明机器人发生了运动。仅凭机器人状态、日志、可见的 Isaac Sim 窗口或单张截图，均不能证明任务完成。

不要运行 docker compose down -v、删除容器、清理 Docker 状态，或将删除运行目录作为自动恢复操作。