cleanup: drop never-runnable G1 deploy scripts, bind docs to task owners(issue #1029)

[LeeLeno]

scripts/deploy/ 的 6 个脚本（1715 LOC）把 owner 派生值硬编码为模块常量，而不经
Hydra 读取，违反 Config first 与 Fix at owner layer。

移除依据（均为实跑 / compose 验证，非代码审读推断）

1. sim_prototype.py 自 0e534e13 引入起从未成功运行

$ uv run scripts/deploy/sim_prototype.py --no-onnx --config ... --motion ...
obs_dim=514, layout segments=[...]
sim_dt=0.00667, ctrl_dt=0.020, substeps/ctrl=3
init_mode=rsi: base xyz=[...]
'gyro' sensor not found in model          ← 死在这里

该脚本查 mj_name2id(model, mjOBJ_SENSOR, "gyro")，而 robots/g1/ 只暴露
pelvis_gyro / torso_gyro。git show 0e534e13:src/unilab/assets/robots/g1/g1.xml
确认引入当天亦如此，且 git log -S'"gyro"' -- scripts/deploy/sim_prototype.py
只返回引入那一个 commit——该行从未被改动。

文档称其为"上机前的字节级验证"，而它一次都没执行过。这违反 Validate near risk：
验证挂在最接近风险的边界上，但那个边界是断的。

2. 文档规定的 owner 绑定是错的（不是"未确认"）

两份 2-g1_whole_body.md 原先都是 eval --algo ppo --task g1_motion_tracking
→ 跑 exporter。Hydra compose + 实跑 env 结果：

owner	action_scale	actor 宽度（实测）
ppo/g1_motion_tracking	无 override → dataclass 默认 0.25	160
ppo/g1_motion_tracking_deploy	29 维非均匀 list	154
offpolicy/sac/g1_wbt_obs	2.0	514
exporter 默认输出	2.0	514

唯一两轴都吻合的是 g1_wbt_obs。文档指的 owner 两轴都不吻合——ONNX 宽度不匹配会被
拦住（那个检查有效），但 action_scale 会静默错 8 倍。

这同时解答了原 issue 结论 3 悬置的疑问：仓内不存在任何 owner 既是 514-d/H=5
又带非均匀 list。514 唯一属于 g1_wbt_obs（标量 2.0）；29 维 list 唯一属于
g1_motion_tracking_deploy（154-d，H=1）。exporter 的 H=1 schema 恰好逐段等于
build_mimic_actor_obs 的顺序——正确的 obs schema 配错误的 action 映射，
这才是漂移的真实形态。原 issue 结论 2"仓内不存在 action-scale 数值或形态漂移"
成立；漂移在 owner 绑定上。

3. 两个 CLI flag 物理上无法取 False

--enable-zero-anchor-pos / --enable-zero-linvel 使用
action="store_true", default=True：带不带 flag 都是 True。两个布局分支
（motion_anchor_pos_b、base_lin_vel）与两个 segment 别名（base_lin_vel、
linvel）不可达。--help 承诺了不存在的能力。

4. sim_dt 漂移

exporter 硬编码 CTRL_DT = 0.02（与 owner 一致），但 prototype 直接用 XML 的
model.opt.timestep = 0.006667 → substeps=3；owner 声明 env.sim_dt: 0.005
→ substeps=4，且 prototype 从不写回。所谓"用同一份配置验证"，物理步长本身不同。

5. 23-dof 直接失败

$ uv run scripts/deploy/export_deploy_config.py --scene .../scene_flat_23dof.xml
Expected 29 actuators, got 23

而 G1WBTObs23Dof（action_scale: 2.0）与 G1MotionTracking23DofDeploy
（23 维 list）均已注册。支持面不对称且无任何测试或文档记录。

6. exporter 不读任何 owner YAML（核心契约违反）

$ grep -rn "conf/\|hydra\|OmegaConf\|compose" scripts/deploy/*.py
（无输出）

ACTION_SCALE=2.0、CTRL_DT=0.02、DEFAULT_OBS_HISTORY_LENGTH=5、
ANCHOR_BODY_NAME、training_noise_scales 5 个数值、TRACKED_BODY_NAMES
（全仓第三份副本，另两份在 export_motion_bin.py 与
common/config.py:125）全部硬编码。

今天这些值对 g1_wbt_obs 全部吻合，仓内无数值漂移——但每一个都是静默漂移
陷阱：改 owner YAML 不会有任何东西提示 exporter 也要改。正确做法仓内已有先例：
scripts/audit_sim2sim_contracts.py:53-67 用 initialize_config_dir + compose
读 owner。

7. 零 in-repo 消费者

• prepend_warmup.py / append_cooldown.py / motion_primitives.py（688 LOC）
  在 docs / tests / CI / Makefile 中零引用
• deploy_config.yaml 的 joint_ids_map（identity 占位）/ force_lower /
  force_upper / training_noise_scales（纯注释且重复 owner noise config）/
  joint_names / obs_history_length / kp / kd — 零消费者
• build_obs_from_layout() 定义后从未被调用
• load_motion_bin 在 sim_prototype.py 与 motion_primitives.py 各一份
  （d20a5411 那次去重漏了前者）
• 唯一测试耦合：test_obs_alignment_g1_wbt.py importlib 加载 sim_prototype
  仅为取 ObsAssembler——1715 LOC 中约 90 LOC

改动内容

删除 scripts/deploy/ 全部 6 文件（−1715 LOC）

文件	LOC	依据
sim_prototype.py	520	依据 1、4
export_deploy_config.py	328	依据 2、3、5、6
append_cooldown.py	299	依据 7
prepend_warmup.py	215	依据 7
export_motion_bin.py	179	依据 6（第二份 TRACKED_BODY_NAMES），仅服务已删链路
motion_primitives.py	174	依据 7（仅服务 warmup/cooldown）

git 历史（0e534e13..HEAD）保留全部内容。

测试收敛，守护的不变量不变

移除"schema 端"那条腿（importlib 加载 sim_prototype.ObsAssembler）。保留的两条腿
现在直接对照：

1. 训练侧 — _fill_obs_history / _push_obs_history ring buffer 语义 +
   _build_actor_obs 装配顺序（测试内以纯 numpy 复现）
2. 消费者侧 — 逐项 deque 语义（_DeployTerm，测试内早已完整实现）

TestBackCompat 的 H=1 用例改为自证"H=1 等价于按布局顺序平铺 concat"，不再需要
外部 assembler。测试同时不再从 tests/ 反向依赖 scripts/ 的内部类。

部署文档 14 文件（zh / en 严格对称）

文档	改动
2-g1_whole_body.md ×2	整页重写为纯契约页（Go2 风格）。owner YAML 为权威；新增 g1_wbt_obs(514/H=5) 与 g1_motion_tracking_deploy(154/H=1) 对照表；§3 明确 action_scale 标量与逐关节列表形态不可互换，禁止取平均 / 取首项 / 静默广播；eval 示例改为 --algo sac --task g1_wbt_obs
5-onnx_runtime.md ×2	删除"G1 部署原型"整节，替换为"校验导出的计算图"
8-latency_budget.md ×2	表格 2 行改指 owner YAML 与守护测试；删除脚本命令块
7-safety_layers.md ×2	deploy_config.yaml 字段块 → 权威来源表（action_scale←owner YAML；default_angles / 限位 / kp / kd←场景 XML）
9-troubleshooting.md ×2	改为对照 owner 的 _build_actor_obs；bug report 清单改为 owner YAML 路径
1-overview.md ×2	删除"物化为 policy.onnx + deploy_config.yaml + 运动二进制"的表述
2-motion_tracking.md ×2	删除"部署工具在 scripts/deploy/"

文档中的 514 / 154 是从跑起来的 env 读出来的，非抄自被删脚本的注释。

原 issue 要求保留的语义（形态保真、禁止平均 / 取首项 / 广播）现以契约说明
落在 2-g1_whole_body.md §3 与 7-safety_layers.md。将来若重建导出链，不必
再从外部源码推导。

src/ 仅注释，零代码行

tracking_obs.py 原先在 3 处断言"与部署侧 ObservationManager /
ObservationTermCfg 按字节对齐（use_gym_history=false）"。删除脚本后仓内已无
该 flag 与该类的任何证据，按 Evidence only 改为陈述逐项 deque 语义并指向
守护它的测试。另按 review 要求移除两文件的 # 注释与 module docstring
（保留类 / 方法 docstring 与 2 条 # type: ignore[assignment] —— 后者是 mypy
指令，删除会导致 make type 失败）。所有注释改动经 AST 逐节点比对确认未触碰代码。

Validation

在最终 head 运行 make test-all，全绿：

Gate	结果
ruff format --check .	476 files already formatted
ruff check .	All checks passed
mypy src/unilab	Success: no issues found in 229 source files
pyright	0 errors, 0 warnings
pytest -m "not slow" --cov --cov-fail-under=25	1759 passed, 25 skipped, 1 xfailed, 覆盖率 73.60%
scripts/benchmark/smoke_test.py	32/33 + 33/34（1 skip 为 platform-optional mlx）
Sphinx -n 严格构建（复现 docs.yml）	构建成功
doc / hygiene / support-matrix gate	38 passed

Sphinx 余下的 1 条 warning（en 侧 unknown document: '../../4-developer_guide/9-sim2sim_contract_status'）先于本分支存在：en 侧
无该文件（仅 zh 有），且 7-config_guard.md 不在本 PR 改动范围。已通过 stash 验证。

训练端未受影响（实跑证据）

• conf/ 零改动；src/ 零代码行改动
• G1WBTObs / G1WBTObs23Dof / G1MotionTracking / G1MotionTrackingDeploy
  四个注册项完好
• G1WBTObs 在 owner overrides 下构造 + reset + step：actor 宽度 514
  （obs_groups_spec: {'obs': 514, 'critic': 289}），step 后稳定；
  G1MotionTrackingDeploy 154
• tests/envs/test_env_configs.py 273 passed

Dangling reference 清零

全仓（排除 .git / .venv / __pycache__ / logs）扫描
scripts/deploy|sim_prototype|export_deploy_config|export_motion_bin|prepend_warmup|append_cooldown|motion_primitives|deploy_config|dance1.bin|State_WBT
→ 零命中。

排除的 false positive（确认无关，未改动）：SymmetryObsLayout
（locomotion/g1/ 的对称性特性）、测试内自有的 obs_layout fixture、
dance1_subject2_part.npz（训练用运动资产，与已删的 dance1.bin 无关）。

未做 / 待 maintainer 确认

1. 原 issue 的 tracking-only 核心问题随 exporter 一起消失——"exporter 在 owner
   为非均匀 list 时是否应主动 fail-closed"已无载体。我没有替它下结论；其语义已
   转为文档契约。是否可以据此关闭该 issue，请 maintainer 判断。
2. tracking_obs.py 原 module docstring 记录了 G1WBTObs 相对基类新增的 7 项能力
   及"基类不受影响"这一契约，现仅存于 git 历史。如需保留，建议补入
   2-motion_tracking.md（该文件已在本 PR 范围内）——尚未执行，等确认。
3. 顺带消除的不对称：23-dof owner 原先根本导不出（依据 5），现无此隐式 29-dof 假设。

PR Gate

• 最终提交已完成，git status --short --branch 工作树干净
• 最终 head 已通过本地 make test-all（结果见上）
• 本 PR base 为 main，故按 CLAUDE.md gate 需等待远程 CI 全绿后再报告完成

[LeeLeno]

针对原motion tracking任务sac算法的部署端特供脚本，现训练端及docs内容做相应改动和清理