#Hub Quick Start

这份流程给第三方智能体使用。它从公共 Hub 目录找到一个固定版本，验证并缓存 OCI 资产包，再把包还原到工作目录；最后使用仓库自带的 kinematic 示例完成本地实例的启动、设备动作、停止和回收。浏览公共资产和拉取公开版本不需要 Hub 账号、Docker、实验室硬件或运行中的 lab serve。

#0. 安装并确认 CLI

先按安装 lab CLI完成安装。使用 v0.3.1 或更新版，lab --help 应出现 daemon、build、split、run、ps、logs 和 rm；如果没有，重新运行 Release 安装器。

lab --version
lab --help
lab pull --help
lab run --help

所有后续命令建议使用同一个空目录和同一个缓存目录。--cache-dir 是内容寻址资源存储，里面有包 blob、引用清单和实例记录；设置 LAB_ASSET_CACHE 后可以省略每条命令的参数：

mkdir -p opensdl-demo
cd opensdl-demo
export LAB_ASSET_CACHE="$PWD/lab-cache"
demo_dir="$PWD"
lab daemon start

PowerShell 对应写法：

New-Item -ItemType Directory -Force opensdl-demo | Out-Null
Set-Location opensdl-demo
$env:LAB_ASSET_CACHE = "$PWD/lab-cache"
$demo_dir = "$PWD"
lab daemon start

#1. 从目录发现资产

浏览 OpenSDL Hub Test，进入资产详情页，查看版本、许可证、能力标签、预览和页面生成的 lab pull 命令。网页目录和 OCI Registry 是两个入口：网页用于搜索，命令中的完整 Registry 主机和 digest 用于下载。不要把 hub.test.sciol.ac.cn 网页地址自行改写成 Registry 地址，直接复制详情页的 pull_reference。

智能体也可以直接调用公开目录 API：

curl --fail --silent --show-error \
  'https://hub.test.sciol.ac.cn/api/v1/assets?q=robot&limit=20'

curl --fail --silent --show-error \
  'https://hub.test.sciol.ac.cn/api/v1/assets/scienceol/elevrail-1-5m-v1-5167d813ec'

curl --fail --silent --show-error \
  'https://hub.test.sciol.ac.cn/api/v1/assets/scienceol/elevrail-1-5m-v1-5167d813ec/versions/1.0.0'

列表响应使用 items 和 next_page_token，详情响应包含 pull_reference、manifest_digest、capabilities、preview 和许可证。需要下一页时把 next_page_token 原样作为 page_token 查询参数传回。资源地址的最后一段可以是版本 tag，也可以是 digest；自动化任务优先保存 digest。

下面使用一个公共可视资产作为拉取示例：

asset_ref="hub.sciol.ac.cn/scienceol/elevrail-1-5m-v1-5167d813ec@sha256:2f5734742ca8694602faead5517ef6cf68f0db399ea9bb0e9c160d58f2efc1f2"

PowerShell：

$asset_ref = "hub.sciol.ac.cn/scienceol/elevrail-1-5m-v1-5167d813ec@sha256:2f5734742ca8694602faead5517ef6cf68f0db399ea9bb0e9c160d58f2efc1f2"

#2. 拉取、校验和物化

lab pull "$asset_ref" --output ./assets/elevrail
lab images --json
lab inspect ./assets/elevrail --json
lab validate ./assets/elevrail

lab pull 会验证 Registry 返回的 manifest digest、config 和每一层 blob，并把完整包写入本地缓存；--output 再把包还原到一个必须尚不存在的新目录。输出目录存在时命令会拒绝覆盖，请换一个目录名。lab images 是 lab asset list 的快捷形式。

lab inspect 和 lab validate 检查还原后的 asset.yaml、许可证、源文件、GLB/缩略图以及声明的相对路径。visual 能力表示这个包可以查看或交给下游渲染器，不表示它可以直接启动仿真。

只想缓存而不物化时省略 --output：

lab pull "$asset_ref"
lab asset inspect "$asset_ref" --json

#3. 离线复用

保持同一个 LAB_ASSET_CACHE，离线物化到另一个新目录：

lab pull "$asset_ref" --offline --output ./assets/elevrail-offline
lab validate ./assets/elevrail-offline

--offline 不访问网络，只读取本地完整缓存。缓存缺少任意 config、source、preview 或 thumbnail blob 时会失败并指出缺失内容；联网执行一次不带 --offline 的拉取后再重试即可。digest 引用保证不同机器在相同包可用时得到相同字节。

#4. 编辑 USD、拆分和再次构建

拉取后的 --output 目录是可编辑工作区；修改 USD 后重新 build，得到新镜像 digest，旧镜像保持不变。拆分是可选步骤，需要先按安装页配置 OpenUSD Python。

下面使用固定版本的示例文件准备两个确实存在的部件，不假设公共 elevrail 模型中有 /Robot/Arm。Git 只用于获取示例，不需要编译 CLI。后续 Shell 代码使用 Bash / zsh；Windows 用户可在 Git Bash 使用这些文件操作，并把 LAB_USD_PYTHON 指向安装页中的 Python 解释器。

如果从 PowerShell 切换到 Git Bash，先进入原来的 opensdl-demo 目录，再恢复环境：

export LAB_ASSET_CACHE="$PWD/lab-cache"
demo_dir="$PWD"
export LAB_USD_PYTHON="$LOCALAPPDATA/opensdl-usd/Scripts/python.exe"

git clone --depth 1 --branch v0.3.1 https://github.com/ScienceOL/OpenSDL.git opensdl-source
cp -R opensdl-source/examples/kinematic-lab ./parts-demo
cat > ./parts-demo/scene.usda <<'USD'
#usda 1.0
def Xform "Lab" {
    def Cube "Workstation" {
        double size = 1
    }
    def Cube "Shelf" {
        double size = 2
    }
}
USD
lab build ./parts-demo --tag localhost/demo/parts:1.0.0
lab split ./parts-demo --output ./components \
  --part workstation=/Lab/Workstation \
  --part shelf=/Lab/Shelf
lab validate ./components/workstation
lab build ./components/workstation --tag localhost/demo/workstation:1.0.0
lab build ./components/shelf --tag localhost/demo/shelf:1.0.0
lab images --json

两个子目录都含独立清单、USD、许可证、预览和缩略图，记录同一个父 digest 与各自的原始 prim 路径。源资产包含的纹理依赖会复制并重写为子目录相对路径；失败不会留下半套输出。子资产继承的 GLB/缩略图展示父资产，请在发布前替换为对应部件的预览。对子资产编辑后再次 build，会得到新的 digest。

有 Registry 写权限后，使用真实的 Registry/命名空间替换下面的目标。通过 LAB_REGISTRY_USERNAME + LAB_REGISTRY_PASSWORD 或 LAB_REGISTRY_TOKEN 提供该 Registry 的凭据；公共拉取不需要它们。

publish_tag='YOUR_REGISTRY/YOUR_NAMESPACE/workstation:1.0.0'
lab push localhost/demo/workstation:1.0.0 "$publish_tag"

push 输出 sha256:...。在另一台机器安装同版 lab 后，用完整的 YOUR_REGISTRY/YOUR_NAMESPACE/workstation@sha256:... 执行 lab pull ... --output ./workstation，然后编辑、build、push 到一个新版本 tag。保留 digest 即可重现原包。

Registry 上传完成后，Hub 线上可见还需要预览上传和目录 admission，详见 Hub 发布说明。目前 lab push 不自动完成这一步；需要具有 Hub 发布权限的账号或发布流水线。

#5. 用内置 kinematic 包完成运行闭环

Hub 当前公共目录主要是可视资产。要验证“资产 → 实例 → 设备动作 → 停止 → 清理”，沿用已经安装的 Release CLI，使用上一步下载的原始可运行示例：

cd "$demo_dir/opensdl-source"
export LAB_ASSET_CACHE="$demo_dir/lab-cache"
lab validate examples/kinematic-lab
lab build examples/kinematic-lab --tag localhost/lab/kinematic:1.0.0

lab run localhost/lab/kinematic:1.0.0 --name demo --json
lab ps --json
lab logs demo --tail 20
lab instance devices demo --json
lab instance send demo sim:example-lab:heater-1 start --json
lab stop demo --json
lab start demo --json
lab stop demo --json
lab rm demo
lab asset remove localhost/lab/kinematic:1.0.0
lab asset prune --dry-run --json
lab asset prune --json
lab daemon stop

lab run 是 lab instance run 的快捷形式；ps、start、stop NAME、logs 和 rm 对应实例列表、启停、日志和删除。lab stop 不带名称时仍然关闭独立的 lab serve，因此旧的设备服务脚本不需要改写。实例启动只允许包内声明 simulation 能力和 kinematic runtime 的资产；可视包会在创建阶段明确拒绝。

运行实例会固定创建时的 manifest digest 和 world.yaml，为每个实例分配独立的数据目录、日志、loopback gRPC 端口和认证 token。停止会保留记录和包占用，必须 lab rm 后才允许 GC 回收。实例崩溃会在 lab ps --all 或 lab instance inspect 时收敛为 failed，保留日志并允许有效实例重新 lab start。

#6. 故障恢复和清理顺序

lab ps --all --json
lab instance inspect demo --json
lab logs demo --tail 200

配置错误、非法路径或启动失败会留下可检查的失败记录；先读 inspect 和 logs，确认不再需要后执行 lab rm demo。运行中的实例不能删除，必须先停止。删除中断时保留 removing 记录，重复 lab rm demo 会继续完成删除。不要手工删除 lab-cache/instances 或 catalog.sqlite，否则会破坏 digest 占用和 GC 的一致性。

推荐始终使用下面的顺序回收：

lab stop demo --json       # 如果仍在运行
lab rm demo                # 释放实例对包的占用
lab asset remove REF      # 删除本机 tag；REF 可换成 digest
lab asset prune --dry-run --json
lab asset prune --json

#常见问题

关于版本、发布和运行时边界，继续阅读 OpenSDL Hub 概览。