[kleinlau17]

关联

来自用户要求：将选项参数、动作切换及 Ghost 同步作为通用能力提交，分别开 PR；用户随后明确授权审核并合并。没有单独 Issue。
配套 BotLab PR：https://github.com/OpenLegged/BotLab/pull/54 （分支 feat/option-parameters，目标 dev）。
本 PR：feat/option-parameters → main；负责人：项总。用户已授权审核并合并到 main，未授权发版或上传 wheel。

改动

命名选项参数以前无法由原生 host 校验；在推理后的 action hook 中直接复位，也会让旧观测和历史产生的过渡动作进入下一次物理步。本次为 host 加入选项成员校验，并让单计划控制器在动作切换时先复位、清理历史和上一动作，再从复位帧重新计算输出。

• 支持 project(parameters=...) 的 options：非空名称、唯一安全整数、默认值属于选项，禁止与 range/step/unit 混用。
• 从 BotLab 同步 PolicyController(reset_on_change=...) 声明，记录参数与 Motion 的映射。同步文件也包含 BotLab 已有的动态 PD 增益信号支持，保持 _controllers.py 与来源逐字节一致。
• 原生 runner 执行 compiled resetOnChange 元数据；控制时钟重新从所选参考帧开始；若第一帧再次请求复位则报错，避免无限循环。
• 补齐 host/无头集成测试与配置文档。Motion.sample(preview=...) 已在 main 的 fix: align motion preview in SDK and editor release plans #7，未重复引入。
• 未提交用户 checkpoint、ONNX、动作资产、独立项目、UI 构建产物或本地运行环境。

影响面	变化	兼容性
参数声明	新增可选 options	原有数字范围参数继续使用原契约
单计划原生控制	reset_on_change 或 action hook 请求复位时丢弃过渡动作并清理状态	这是有意修正的复位时序；没有复位请求的路径不变
自定义控制器/控制器组	不新增动作切换能力	reset_on_change 明确拒绝组控制器和 Python modifier 组合

跨仓依赖与发布边界

公共 SDK 真源是 BotLab 的 src/domain/python/botlab；本仓维护原生 host/runner。BotLab 配套改动负责下拉框、浏览器 compiled resetOnChange 执行及 Ghost 同步，本 PR 负责 CPython 侧同一契约。

• 只更新本 SDK，不会让旧的缓存浏览器 runtime 自动获得下拉框/Ghost 切换能力。
• 原生执行可使用本 PR；浏览器/静态导出使用新字段时必须配套支持它们的 BotLab runtime。旧运行时对新 metadata 的行为不作兼容承诺。
• BotLab 工作分支先进入 dev 供集成；本仓只有 main，不套用 FAT 分支模型。发布前应验证配套 browser runtime 与 wheel 的组合，先提供兼容 runtime，再推广依赖新功能的 SDK/项目；合并顺序不等于发布已完成。
• 没有改变包 ABI 版本；这是可选声明的扩展，旧工程无需迁移。本 PR 不更新运行时发布版本、不上传 wheel。

测试方式

环境：macOS，Python 3.12，runtime extras 已安装，Node 24.21.0。使用项目现有虚拟环境解释器，PYTHONPATH=src 保证测试本工作树源码；BOTLAB_ENGINE_REPO 指向配套 BotLab 工作树。

PYTHONPATH=src BOTLAB_ALLOW_MISSING_UI=1 BOTLAB_ENGINE_REPO="$BOTLAB" "$PYTHON" -m pytest --basetemp=tmp/pr-submission/pytest
uvx ruff check .
PYTHONPATH=src "$PYTHON" -m botlab._runtime.golden_check tests/fixtures/processors.json
PYTHONPATH=src BOTLAB_ENGINE_REPO="$BOTLAB" "$PYTHON" -m pytest -q tests/test_headless.py tests/test_host.py

实际结果（2026-10-24）：

• pytest：退出码 0；778 passed，2 skipped，2 deselected，56 subtests passed。2 个 skip 分别为已安装 runtime extras 时不适用的缺依赖路径，以及缺少生成 UI 的 native viewer 集成；默认配置排除了 2 个浏览器 e2e。
• Ruff：退出码 0，All checks passed。首次发现新增测试 import 分组格式问题，修正后复查通过。
• Golden：退出码 0，53 cases replayed within tolerance。
• 最终 host/headless 定向复查：退出码 0，32 项通过。
• _controllers.py 与 _resources.py 已 cmp 对比配套 BotLab 文件，退出码 0。
• 此前在独立项目中验证三段动作按 0→2→1→2→0 切换并手动复位，相对每段 fresh-run 的 action/qpos 最大绝对差均为 0；此证据来自 rebase 前的功能验证，不冒充最终提交上的重复长轨迹测试。

本地日志位于 tmp/pr-submission/{pytest,ruff,golden,targeted-final}.log；日志和用户资产未上传。未重新执行候选发布 wheel 验收、Python 3.10/3.11/3.13 矩阵或完整浏览器 E2E，不能据此宣称可发布。

风险和未通过项

• 配套 BotLab 的硬件 GPU 检查未通过：Chromium 报告 ANGLE / Vulkan / SwiftShader 软件渲染，命中了禁止软件 renderer 的断言；1 failed、后续性能用例 1 did not run。功能测试通过不代表硬件 WebGPU 或实时性能验收通过，需在真实 GPU 环境补测。
• 新声明限制为单控制器、完整选项映射、参考第 0 帧、root body 通道 0、原生关节顺序；项目须显式保证动作资产与机器人对应。
• 审核补齐 resetOnChange 元数据的 processor golden，两端共 54 项通过；生命周期继续由两仓单元/集成测试验证。
• 用户已要求审核并合并；本轮为 Codex 审核，不声称人工负责人审批。最新 CI 通过后按正常 PR 合并，不发布，不影响旧项目运行服务。

AI 使用说明：

• 模型：OpenAI Codex（本次会话未提供可核实的具体模型版本）。
• 生成内容：选项校验、原生复位时序、SDK 镜像接入、相关测试和文档由 AI 辅助完成。
• 人工修改：本次对话没有确认人工修改或人工代码审核；待项总审核。
• 风险点：过渡动作是否泄漏、历史/时钟是否正确重置、两端 metadata 是否一致；以上由 AI 运行单元/无头/计算基准验证，不能替代人工审查或硬件 GPU 验收。

合并前 AI 审核（2026-10-24）

审核 head 01c5c7b：未发现阻断功能缺陷，核对了选项声明/取值校验、编译规则、延迟复位后丢弃旧动作并重算、时钟/历史清理和测试覆盖。同步 BotLab 的 resetOnChange 元数据 golden 后，54 项原生回放通过。

新 Python 3.10–3.13 CI：https://github.com/OpenLegged/botlab-python/actions/runs/40093859497 ，待完成后更新。先合 BotLab #54 到 dev，再合本 PR 到 main；不上传 wheel、不发布运行时。

最终合并检查（2026-10-24 13:18 UTC）

最新 head 01c5c7b 的 CI run 40093859497 全成功，已核对日志：Python 3.10 为766 passed/5 skipped/2 deselected；3.11、3.12、3.13各774 passed/6 skipped/2 deselected，均56 subtests passed。各版本54项golden、lint和source-wheel contract通过，无失败。main仍为7eb3cd6。

依据用户明确审核合并授权，在 BotLab #54 合入 dev 后，普通 squash 合入 main。不发布 wheel 或浏览器 runtime；跨仓上线依赖和硬件GPU未验收限制仍保留。

合并结果：2026-10-24 13:19:26 UTC 已 squash 合入 main，提交 3173fc6；依赖 BotLab #54 已先合入 dev（794ccea86ce099110fb9fec93a96b31641414a30）。未发布 wheel 或 runtime。