#运行实例

使用不可变资产包创建可独立启停的本地实验室实例。Release 安装包包含本地 daemon 和实例管理，不需要从源码构建。首版使用内置 kinematic 运行时，无需 Docker、Hub 账号或实验室硬件。

#准备可运行包

在 OpenSDL 源码根目录使用仓库自带的 examples/kinematic-lab。它包含资产清单、OpenUSD 源场景、GLB 预览和世界配置。选择尚不存在的输出目录：

lab validate examples/kinematic-lab
export LAB_ASSET_CACHE="$PWD/lab-store"
lab daemon start
lab build examples/kinematic-lab --tag localhost/lab/kinematic:1.0.0

#创建与启动

run 创建并启动实例，认证并确认设备就绪后才返回；create 只创建停止状态的实例。实例名字以小写字母开头，可使用小写字母、数字、短横线和下划线，最长 63 字符。

lab instance run localhost/lab/kinematic:1.0.0 --name demo --cache-dir ./lab-store
lab instance list --cache-dir ./lab-store
lab instance inspect demo --json --cache-dir ./lab-store

完整闭环也可以使用 Docker 风格的顶层快捷命令：

lab run localhost/lab/kinematic:1.0.0 --name demo
lab ps --json
lab logs demo --tail 20
lab stop demo
lab start demo
lab stop demo
lab rm demo

lab stop NAME 停止托管实例；不带名称的 lab stop 保留关闭独立 lab serve 的语义。可复制的 Hub 发现、digest 拉取、离线复用和完整清理流程见 Hub Quick Start。

实例固定创建时解析到的 digest 和世界配置。后续标签变更不会改变它。每个实例有独立的运行数据、日志、认证和端口；默认只在本机 loopback 上提供 gRPC。

#查看设备与调用动作

lab instance devices demo --json --cache-dir ./lab-store
lab instance send demo sim:example-lab:heater-1 start --cache-dir ./lab-store
lab instance logs demo --tail 10 --cache-dir ./lab-store

示例世界提供加热器、搅拌器、阀门和传感器。动作结果 PENDING 表示已派发，设备状态用于观察效果。kinematic 是确定性的内置状态演化，不等同于刚体或机器人动力学。公共 Hub 中仅声明 visual 的包可以下载和查看，但需要明确的运行声明才能创建实例。

#停止、重启与移除

lab instance stop demo --cache-dir ./lab-store
lab instance list --all --json --cache-dir ./lab-store
lab instance start demo --cache-dir ./lab-store
lab instance stop demo --cache-dir ./lab-store
lab instance remove demo --cache-dir ./lab-store

停止会保留日志、数据和包占用。重新启动使用冻结的初始世界配置，不承诺恢复停止前的实时遥测。移除运行中的实例会失败，需要先停止；移除完成后才解除对资产包的占用。实例所在设备不在线时无法远程使用它。

#回收资产

lab asset remove localhost/lab/kinematic:1.0.0 --cache-dir ./lab-store
lab asset prune --dry-run --json --cache-dir ./lab-store

确认 dry-run 结果后，使用 lab asset prune --json --cache-dir ./lab-store 回收未引用且未被实例占用的包。GC 只删除这份资源存储拥有的 blob，保留仍被其他包需要的共享内容。

#运行声明

可运行资产在 asset.yaml 的 spec 下声明配置入口，并包含 simulation 能力：

spec:
  # Other asset fields remain required.
  capabilities: [visual, scene, simulation]
  runtime:
    engine: kinematic
    config: world.yaml

world.yaml 是随包保存的 SimulationConfig，例如：

world_id: example-lab
engine: kinematic
tick_hz: 10
seed: 0

省略 devices 时使用内置四设备世界。配置只能描述仿真世界，未知字段会被拒绝；不能声明设备 transport、外部程序或凭据。配置路径必须是包内相对 YAML 路径，实例创建时会读取并校验，避免用通用设备配置触发意外硬件操作。

#故障与诊断

失败记录保留在 list --all 中，可用 inspect 和 logs 查看。进程崩溃会被识别为失败，准备有效的实例可以重新启动；配置准备失败则需移除后重新创建。无法验证进程身份时，停止命令返回明确错误，不会仅凭记录中的 PID 杀进程。

删除中断时保留 removing 记录和包占用，重复执行 lab instance remove 即可继续；该状态不能启动。创建中断的记录会在检查时标记失败，仍可显式移除。