Add and document soft-limit-aware action mapping

[toonasinensis]

Summary / 概述

This PR adds an optional soft_limit_bias action-to-position-target mapping.
It maps a clipped policy output in [-1, 1] affinely onto each joint's
configured soft position limits, including the offset required by asymmetric
joint ranges.

本 PR 新增了可选的 soft_limit_bias 动作到关节位置目标映射。它将裁剪到 [-1, 1] 的策略输出仿射映射到各关节配置的软位置限位，并包含覆盖不对称关节范围所需的偏置。

The existing effort_kp mapping remains the default, so existing commands and
checkpoints keep their current behavior.

现有的 effort_kp 映射仍然是默认选项，因此已有命令和检查点的行为保持不变。

Motivation / 动机

The existing effort/Kp-derived scale is centered on the configured default
joint position. For joints with asymmetric ranges, the reachable target range
can be asymmetric or may not cover the full useful joint interval. The new
mapping computes the bias and half-range after accounting for MJLab's default
offset and per-joint target scale, so normalized endpoints reconstruct the
configured soft limits exactly.

现有的 effort/Kp 缩放以配置的默认关节位置为中心。对于限位不对称的关节，可达目标范围可能不对称，或无法覆盖完整的有效关节区间。新映射在考虑 MJLab 的默认位置偏置和逐关节目标缩放后计算 bias 与 half-range，使归一化动作的两个端点能够精确还原配置的软限位。

Concrete G1 example / G1 具体例子

The G1 left_hip_roll_joint is a concrete asymmetric example from the
repository's existing configuration:

G1 的 left_hip_roll_joint 是仓库现有配置中的一个具体不对称案例：

Quantity / 配置项	Value / 数值
Hard limits / 硬限位	[-0.52360, 2.96710] rad = [-30.00°, 170.00°]
Soft limits (0.95) / 软限位	[-0.43633, 2.87983] rad = [-25.00°, 165.00°]
Default position / 默认位置	0 rad
Effort limit / 力矩上限	139 N·m
Kp / 位置刚度	99.09843 N·m/rad
Base action scale / 基础动作缩放	0.25

The existing mapping gives
s = 0.25 * 139 / 99.09843 = 0.35066. After the configured 5x action
normalization, a in [-1, 1] produces:

现有映射得到 s = 0.25 * 139 / 99.09843 = 0.35066。经过配置中的 5x 动作归一化后，a in [-1, 1] 产生：

q_target = 0 + 0.35066 * (5 * a)
         = [-1.75331, 1.75331] rad
         = [-100.46°, 100.46°]

Thus much of the negative action range requests targets below the -25° soft
limit, while the positive target is still 64.55° short of the 165° soft
upper limit. The mirrored right-hip-roll joint has the same issue in the
opposite direction.

因此，大量负方向动作对应的目标落在 -25° 软下限之外，而正方向最大目标距离 165° 软上限仍差 64.55°。镜像的右髋 roll 关节在相反方向存在同样的问题。

soft_limit_bias instead yields bias = 3.48413 and
half_range = 4.72844, so policy outputs -1, 0, and 1 map exactly to
-25°, 70°, and 165°. Both soft-limit endpoints are reachable without
allocating normalized-action range to out-of-limit targets.

soft_limit_bias 则得到 bias = 3.48413、half_range = 4.72844，使策略输出 -1、0 和 1 精确对应 -25°、70° 和 165°。这样既能覆盖两个软限位端点，也不会把归一化动作范围分配给限位之外的位置目标。

This establishes the mapping's geometric coverage property. It does not, by
itself, claim that every downstream task must improve; the controlled A/B
result below provides the empirical evidence.

这证明了映射在关节空间覆盖上的几何正确性，但不单独宣称所有下游任务都必然提升；下方的受控 A/B 实验提供经验结果。

Changes / 改动内容

• Add --action-mapping {effort_kp,soft_limit_bias} to the training CLI.

• Apply the affine mapping before passing actions to MJLab.

• Preserve effort_kp as the backward-compatible default.

• Record the mapping and resolved affine parameters in tracking ONNX metadata.

• Add endpoint, asymmetric-limit, invalid-input, CLI-default, and config
  propagation tests.

• Document the mapping and its formula in English and Chinese.

• 在训练 CLI 中新增 --action-mapping {effort_kp,soft_limit_bias}。

• 将动作传给 MJLab 前应用仿射映射。

• 保留 effort_kp 作为向后兼容的默认选项。

• 在 tracking ONNX 元数据中记录映射模式和解析后的仿射参数。

• 增加端点、不对称限位、非法输入、CLI 默认值和配置传递测试。

• 使用中英双语说明映射方法及其公式。

Controlled A/B result / 受控 A/B 实验结果

The two Roban FB runs used the same motion data, seed, optimizer settings, and
2-GPU setup. Both reached approximately 106 million global environment steps.
The table reports the mean of the final 100 logged samples.

两组 Roban FB 实验使用相同的动作数据、随机种子、优化器配置和双 GPU 设置，均训练到约 1.06 亿 global environment steps。下表统计最后 100 条训练日志的平均值。

Metric / 指标	effort_kp	soft_limit_bias	Change / 变化
Joint-limit penalty / 关节限位惩罚（越低越好）	0.01081	0.00613	-43.27%
Torque-limit penalty / 力矩限位惩罚（越低越好）	0.13127	0.03621	-72.42%
Squared-torque metric / 力矩平方指标（越低越好）	5834.43	4727.19	-18.98%
F1 representation metric / F1 表征指标（越高越好）	0.26356	0.33274	+26.25%

W&B runs / W&B 实验链接：

• Baseline / 基线：https://wandb.ai/xiechunyang1-hajimi/hajimi/runs/63m9byv1
• Soft-limit affine / 软限位仿射映射：https://wandb.ai/xiechunyang1-hajimi/hajimi/runs/ccdkmded

This is a one-seed result on one robot. Downstream tracking improvements vary
by motion, so the new behavior is intentionally opt-in rather than replacing
the default.

该结果来自单一机器人和单一随机种子。下游跟踪效果会随动作变化，因此新映射被设计为显式启用的可选功能，而不是直接替换默认行为。

Test plan / 测试方案

/home/thl/wt_wbc/UFO/.venv/bin/python -m unittest \
  tests.test_action_mapping \
  tests.test_update_z_cli \
  tests.test_robot_config_onnx_export

Ran 20 tests: OK

The tests cover the affine endpoint reconstruction, asymmetric bias,
invalid inputs, backward-compatible CLI defaults, environment-config
propagation, and ONNX mapping metadata.

测试覆盖仿射映射端点还原、不对称偏置、非法输入、向后兼容的 CLI 默认值、环境配置传递和 ONNX 映射元数据。

這個在實物和sim2sim上會有更好的效果,更好的達到工作空間.