docs: 添加手柄主键回位设计

docs/superpowers/specs/2026-07-31-controller-primary-initial-pose-design.md

@@ -0,0 +1,58 @@
+# 手柄主键回初始位姿设计
+
+## 背景与目标
+
+有线连接已基本解决 UDP 超时和逆解失败问题。本次只增加一个明确操作：
+点击当前机械臂对应手柄的主键，使该机械臂按已配置的关节角回到初始位姿。
+
+- 右臂模式：右手 A 键控制右臂，左手 X 键无效。
+- 左臂模式：左手 X 键控制左臂，右手 A 键无效。
+- 双臂模式：右手 A 键控制右臂，左手 X 键控制左臂。
+
+## 最小方案
+
+`XrController.primary` 已表示左手 X 键或右手 A 键。每个遥操作节点继续只订阅
+自身的手柄话题，并在 `primary` 上升沿调用适配器的初始位姿运动：
+
+```text
+左手 X → /xr/left_controller  → left_arm_teleop  → 左臂初始位姿
+右手 A → /xr/right_controller → right_arm_teleop → 右臂初始位姿
+```
+
+单臂模式只启动对应节点，因此另一只手柄天然无效；双臂模式下两个节点独立处理，
+无需新增协调节点、话题、服务或配置项。
+
+## 运动与安全行为
+
+- 只在按键从未按下变为按下时触发，持续按住不重复执行。
+- 回位前调用现有安全停止逻辑，退出当前相对位姿遥操作。
+- 使用现有 `initial_joint_pose` 和 `init_move_speed`，不修改三个 YAML 中的数值。
+- 复用现有 `rm_movej(..., block=1)` 阻塞运动，完成后重新同步关节状态和 QP 状态。
+- 回位后必须先松开 Grip，才能重新进入遥操作。
+- 回位失败时记录错误并保持停止，不自动重试。
+- mock 模式只更新模拟关节状态，不导入或调用厂商 SDK。
+
+## 代码范围
+
+- 在 `realman_adapter.py` 为真机和 mock 提供同名的公开回位方法，真机实现复用现有
+  私有初始位姿运动代码。
+- 在 `single_arm_velocity_teleop.py` 的现有手柄回调中增加主键上升沿处理。
+- 在现有测试文件中增加最小的适配器回位和按键边沿测试。
+
+不修改消息定义、UDP 输入节点、launch、机械臂 YAML、安全限位或夹爪控制。
+
+## 验证
+
+- 测试主键首次按下触发一次，持续按住不重复触发，松开后可以再次触发。
+- 测试 mock 回位后恢复配置的初始关节角。
+- 测试真机适配器仍只调用既有的关节运动命令；测试使用假 SDK 对象，不连接真机。
+- 在 `/home/robot/WS_xr` 执行：
+
+  ```bash
+  source /opt/ros/humble/setup.bash
+  pytest src/xr_rm_teleop/test/test_initial_joint_pose.py
+  pytest src/xr_rm_teleop/test/test_orientation_control.py
+  colcon build --symlink-install
+  ```
+
+全部验证使用 mock 或假对象，不连接真机、不移动机械臂、不操作夹爪。