[kleinlau17]

问题与修复

编辑器的 Motion.sample 已输出显式 preview 字段，但 Python SDK 编译的发布包缺少该字段，会走 runtime 的旧计划 Ghost 预览回退路径，造成编辑器与发布包行为不同。

将 _resources.py 与 BotLab canonical 模块逐字节同步：Motion.sample(..., preview=False) 默认显式关闭该采样节点的预览，允许 preview=True，并拒绝非布尔值。增加从项目加载、编译到 release 打包的回归测试，覆盖默认值、显式 false/true 和类型校验。

跨仓关系

BotLab 配套 PR：https://github.com/OpenLegged/BotLab/pull/50。
canonical 来源为 BotLab cf98f06dbc15c722189c2739772028054f9659c5 的 src/domain/python/botlab/_resources.py；逐字节比较通过。本次不带入其他 SDK 镜像差异。

平台先提供 Ghost 相机隔离并保留旧计划兼容，再配套 SDK 统一预览字段；SDK 字段同步本身不能替代 runtime 的隔离修复。未扩展回合管理、原生 runner 或策略专用 API，未修改包版本、发布 wheel 或替换线上 runtime。

本地检查

基于 ea7b5519d484abcd58f901f9d308b2933c70a0bb。

命令	结果
.venv/bin/ruff check .	通过
.venv/bin/python -m pytest --basetemp=tmp/pytest	767 passed、2 skipped、2 deselected、56 subtests passed；2 条既有 warnings
cmp src/botlab/sdk/_resources.py ../BotLab/src/domain/python/botlab/_resources.py	逐字节一致
uv build --wheel --out-dir <isolated-project>/.migration/wheels	构建通过，非 editable 安装至独立 venv

独立项目实际执行了 tools/evaluate_all.py --mode eval --episodes 2、tools/evaluate_all.py --mode play --episodes 1、tools/build_all.py、tools/build_legacy_sites.py、tools/check_browsers.py --surface editor/site/legacy（三个入口分别运行）和 tools/verify_preview_plans.py。这些为独立项目验收脚本，不是 SDK 自带命令。BotLab 配套检查包括 34 项相关单测、lint/typecheck/dev/viewer 构建、6 项嵌入 E2E 和 2 项 macOS GPU 测试；默认 Vulkan 参数在 macOS 的失败及复测条件详见配套 PR。

配套验证（2026-10-24，本地隔离环境）

使用 SuperMimic 独立项目、独立 venv 和 runtime 缓存验证；控制代码、策略、preset、阈值及回合管理保持原样。

验证	结果
全部 10 个动作 × 标准编辑器、新发布包、未改写旧包搭配新 runtime	30 条浏览器记录完成加载、推理、动作时长覆盖及暂停稳定性检查
浏览器采样跟踪检查	三个入口均只发现 case 9 原有失败；旧发布页额外失败的 case 0、2、5、6 不再出现
原生 Eval 每动作 2 回合、Play 每动作 1 回合	30 回合的 qpos、action、终止结果与旧版基线精确一致，最大差值 0；原生回合测试 7 项通过
case 9	原生 Eval 仍在 3.94 s 因右踝高度误差超过 0.25 m 终止；本次未修复策略本身
发布包	标准 CLI 构建 10 份新包，文件及字节校验通过；10 份旧包逐字节保留
编译计划	新包相对旧包仅增加 preview=False；全部动作的编辑器、新发布页、CLI 新包计划精确一致；旧包运行计划与旧包内容精确一致
RGB / 深度真实渲染	固定物理场景中切换 Ghost，实际相机路径输出变化均为 0 字节；移除隔离标记后分别变化 10692 / 13884 字节，显示状态正常恢复

浏览器跟踪检查基于显示时钟、qpos 快照和离线 FK，是采样帧检查，不是每控制步完整 Eval，也不是上游统计成功率。标准入口动作末尾仍需手动暂停；没有扩展回合管理。新旧发布页无资源失败、console error 或未捕获异常；本地编辑器仅有无账号服务的 /api/auth/me 404。

验证产物仍标为本地 0.3.0 候选，未发布，按 SHA-256 识别：

• SDK wheel：92d775ecbbee40c1fe6f3fb9417f853f9e6983e7528ef49c434140bd82634607
• runtime zip：6a0aa395f3866c74ea3c68476298e7f83551ea4485c22e0dba98786f03b73744
• runtime manifest：be6b0e8dcde26fd1732c9dba9cc3db563e77e8e0091d5cd4473904054bac2597

完整执行记录、截图和报告保留在本地 supermimic-project-ghost-fix/reports/ghost-fix-validation.md 及同目录证据文件；大体积策略和构建产物未纳入源码 PR。

审核

目标分支 main（SDK 仓不走业务仓 FAT 分支）。请项总审核实际改动和上述本地 CI 记录。已获用户授权：检查 CI、修复失败项后通过此 PR 合并；不发布 wheel。

合并前远端 CI 结果

GitHub Actions run 40081386196，head 70d9ec5a2d4c366075659e3849b8c55b1a74aae2：Python 3.10 / 3.11 / 3.12 / 3.13 四项均 SUCCESS，包含 lint、pytest、golden processor parity、非 editable source wheel contract。

Python	pytest
3.10	755 passed、5 skipped、2 deselected、56 subtests passed
3.11	763 passed、6 skipped、2 deselected、56 subtests passed
3.12	763 passed、6 skipped、2 deselected、56 subtests passed
3.13	763 passed、6 skipped、2 deselected、56 subtests passed

CI 使用不含 UI 的源码 wheel 检查，不能替代发布 wheel 的完整验收；本地带 UI 候选的验证见上文。无失败 CI 任务，无额外代码修复。BotLab 配套 PR #50 已合入 dev，提交 bd8ab6ab635fd8be6b8145db7dc74814b4fde0a1；不表示平台已部署。