scenescape-setup

SceneScape 端到端设置

主机需要 Docker、docker-compose 和带有 requests 的 Python 3.10+。

概览

此技能会在仓库外部署并恢复 Intel® SceneScape 环境，从用户处收集所需的部署输入，并协调引导、校准、场景重建和验证工作流。它适用于首次安装、使用现有 deploy-inputs.json 重新运行，以及针对特定阶段（如 bootstrap、calibrate 或 scene）的恢复操作；当用户只需重复或继续部署的某个部分时，可使用此技能。

参数 / 参数值

全新部署所需的运行时输入：deploy_dir、streams（或视频文件）、camera_ids、scene_name、mapping（场景地图源：默认值为 reconstruction，也可以是 blueprint、.glb/.ply 网格或地理空间数据）。可选状态字段：--phase、--fresh，以及 Fast Path 中隐含的恢复标记。

返回值 / 输出

deploy_dir 中的部署产物：deploy-inputs.json（事实来源）、.deploy-state.json、编排器日志、校准/重建/验证输出，以及包含 scene_uid 和部署指标的最终结果 DEPLOY COMPLETE。

错误处理

安全失败，不要猜测：streams 与 camera_ids 不匹配或存在重复项 → 停止并要求用户提供修正后的输入；因相机变更而进行全新重新部署时，先前输入无法读取 → 请用户确认要保留的集合；本地仓库/文档缺失 → 回退到规范 GitHub URL，不要编造；收到恢复/继续信号 → 将 deploy-inputs.json 视为现有文件，跳过步骤 1，除非用户表示目录有误；步骤失败 → 仅阅读匹配的故障排除参考，不要大量输出日志。

文件解析

所有脚本、参考资料和资源都相对于 $SKILL_DIR 解析，因此技能文件夹自成一体且可移植。docs/user-guide/... 链接优先指向本地检出目录；若本地不可用（独立技能副本），则回退到 https://github.com/open-edge-platform/scenescape/blob/main/<path>，不要猜测。不要将 Scenescape 仓库文档复制到 references/；新建参考资料仅用于记录其他地方没有书面形式的知识。

始终生效的规则（无例外）

• 在启动任何部署/恢复/阶段任务之前，先阅读 agent-guardrails.md。
• 每次启动编排器时，都要在后台针对编排器 PID 启动 watch_orchestrator.sh，并在收到 RESULT= 时通知；依靠监视器通知，而不是由用户发起轮询。
• 绝不编造相机 ID/流/场景名称；绝不将原始输入插入临时 shell 单行命令；破坏性操作（--fresh、删除 deploy_dir、docker compose down -v）始终需要明确确认。
• 仅加载与已报告故障相匹配的单个阶段/症状参考资料。

步骤 0 — 引导技能目录

在执行任何其他步骤之前，使用第一个匹配的策略解析 SKILL_DIR：

A. 脚本已在磁盘上（本地已检出 scenescape 仓库）：

export SKILL_DIR=<path-to-scenescape-checkout>/.github/skills/scenescape-setup

B. 从 git 提取（无需完整检出 — 快速且不会留下分支状态）：

SCENESCAPE_REPO=$(find ~ -maxdepth 5 -type d -name scenescape 2>/dev/null | head -1)
git -C "$SCENESCAPE_REPO" fetch origin main
mkdir -p /tmp/scenescape-skill
git -C "$SCENESCAPE_REPO" archive origin/main \
  -- .github/skills/scenescape-setup | tar -x -C /tmp/scenescape-skill
export SKILL_DIR=/tmp/scenescape-skill/.github/skills/scenescape-setup

验证：在继续之前，ls "$SKILL_DIR/scripts/deploy_scenescape.sh" 必须成功。

路由

情况	要阅读的参考文档
新部署（收集输入、选择映射、视频文件）	step-1-gather-inputs.md
继续 / 重复 / Fast Path（“继续”“恢复”、输入未更改）	fast-path.md
启动（完整部署、恢复，或使用 --phase 的编排器 + 监视器 + README + 交接）	deploy-and-complete.md
单个阶段：引导（6–8）、校准（9–10）、场景（11–13）	phase-bootstrap.md / phase-calibrate.md / phase-scene.md
跟踪闪烁、消失或 ID 改变（同一摄像头）	tuning-tracker.md
跨摄像头 Re-ID 未能识别 / 识别错误人员	tuning-reid.md
防止视觉属性重置	attribute-persistence.md
外部非视觉传感器读数/事件	singleton-sensors.md
类别的预期尺寸/形状（Object Library）	object-library.md
成功部署后——利用场景输出构建内容（必须进行交接）	using-scene-output.md
生成文件布局 / Web UI 交接 / 引导阶段运行时重建诊断	operational-reference.md（仅用于这些需求——不要在常规部署期间使用）

调整跟踪器/Re-ID 行为（仅在出现问题后）

不要在步骤 1 开始前询问调整相关问题——始终先使用随附的 tracker-config.json / reid-config.json 默认值进行部署。仅在用户反馈跟踪/Re-ID 效果不满意 之后，才打开相应的问卷。在首次回复中：

1. 说明你打开了哪份参考文档（tuning-tracker.md 或 tuning-reid.md——只能选一份）。
2. 在回复中列出该参考文档中的编号问卷。
3. 在同一轮中，根据该参考文档的建议逻辑，从症状推导出初始值，并应用到已部署副本的 <deploy_dir>/controller/tracker-config.json 或 <deploy_dir>/controller/reid-config.json（绝不能修改技能的 assets/ 原始文件）。展示 具体的 JSON 字段更改和确切的重启命令 docker compose up -d --force-recreate scene。
4. 说明问卷回答可进一步调整这些初始值。

不要省略问卷，也不要省略已部署路径中的修改及仅重启 scene 的说明。只加载一份匹配的参考文档（跟踪器时序或跨摄像头 Re-ID）。

质量与评估

自动评估用例位于 evals/evals.json 中，每个 example-prompts/ 文件对应一条记录（prompt_file 将两者关联起来）。当前基准测试请参阅 benchmark/benchmark.md。