docs: 更新手柄输入与 Superpowers 规则

README.md

@@ -24,7 +24,7 @@ PICO/XR 双手柄 UDP JSON
 - Placo 0.9.4 RM75 QP 逆解；收到首帧有效关节反馈后才启用，求解失败时保留上一组有效关节目标。
 - 真机模式下，点击对应手柄 `trigger` 可切换并保持对应夹爪开/关状态。
 - Tkinter 启动面板 `launcher_ui.py`，用于现场快速启动、监控 topic、检查环境和清理进程。
-- 自定义 PICO 4 Ultra UDP Sender Unity 工程，负责发送左右手柄 pose、`grip`、`trigger` 和 pose 诊断字段。
+- XRoboToolkit bridge 读取左右手柄 pose、Grip、Trigger、摇杆和主副按键。
 
 暂未完成：
 
@@ -37,17 +37,8 @@ PICO/XR 双手柄 UDP JSON
 ```text
 src/
 ├── README.md                       # 项目主文档
-├── CODEX.md                        # Codex/Claude Code 项目工作流和安全规则
-├── docs/
-│   └── pico_udp_sender_ubuntu22_setup.md   # Ubuntu 22.04 下 PICO UDP Sender 配置教程
-├── unity/
-│   ├── XR_RM_PICO_UDP_Sender/      # PICO 4 Ultra UDP Sender Unity 工程
-│   │   ├── Assets/Editor/          # Android/PICO 设置与 APK 构建菜单
-│   │   ├── Assets/Scripts/         # UDP sender、配置面板、KeepAwake
-│   │   ├── Assets/Resources/       # PICO 资源与 Roboto TMP 字体
-│   │   ├── Packages/               # Unity package manifest
-│   │   └── ProjectSettings/
-│   └── PICO-Unity-Integration-SDK-release_3.4.0/
+├── AGENTS.md                       # Codex 项目工作流和安全规则
+├── docs/superpowers/               # Superpowers 设计与实施计划
 ├── xr_rm_bringup/
 │   ├── config/
 │   │   ├── dual_arm_rm75.yaml      # 双臂配置：left_arm_teleop 与 right_arm_teleop
@@ -62,12 +53,15 @@ src/
 ├── xr_rm_input/
 │   ├── launch/
 │   │   └── udp_receiver.launch.py  # 低层 UDP 接收测试入口
+│   ├── test/
+│   │   └── test_controller_fields.py
 │   └── xr_rm_input/
 │       ├── udp_controller_receiver.py
+│       ├── xrobotoolkit_to_udp_bridge.py
 │       └── sample_udp_sender.py    # 本机扫轴/正弦模拟手柄 UDP 数据
 ├── xr_rm_interfaces/
 │   └── msg/
-│       └── XrController.msg        # hand/grip/trigger/pose
+│       └── XrController.msg        # 手柄状态与位姿
 └── xr_rm_teleop/
     ├── models/
     │   ├── rm75/                   # 旧 RM75 模型资源（launch 不再选用）
@@ -81,6 +75,12 @@ src/
 
 `single_arm_velocity_teleop` 这个名字保留是有意的：双臂模式不是一个大节点直接控制两台机械臂，而是启动两个相同的单臂控制节点，分别命名为 `left_arm_teleop` 和 `right_arm_teleop`。
 
+## Superpowers Git 约束
+
+使用 Superpowers 执行任务时，只允许按 skill 工作流创建本地 Git 提交。
+禁止执行 `git push`、合并本地分支、合并 PR 或其他远程写操作。skill 如需
+独立 worktree 或配套本地分支，可以创建，但不得将其合并到其他分支。
+
 ## 环境准备
 
 在工作空间根目录，也就是包含 `src/` 的目录执行：
@@ -268,15 +268,14 @@ ros2 launch xr_rm_bringup arm_debug.launch.py arm:=both use_mock:=false
 - 当前三份 YAML 默认均使用 `follow: false` 完成安全基线验证；确认关节加速度与反馈稳定后，再单独测试高跟随。
 - `initial_joint_pose`：mock 的初始关节反馈，以及显式开启初始化移动时的真机初始关节角。
 
-当前 `/xr/*_controller` 的 Project 坐标约定：
+当前 `/xr/*_controller` 的坐标处理：
 
-- Project：`+X` 向右，`+Y` 向上，`+Z` 向后。
-- Unity APK 的 `Project (+Z back)` 会把 PXR `pxr_predict` 原始坐标转换为 `project.x=native.z`、`project.y=native.y`、`project.z=-native.x`。
-- `Source raw` 模式保留原始 pose source 坐标，只用于现场对照。
+- XRoboToolkit bridge 原样转发 SDK 的手柄位置和四元数，不额外转换坐标轴。
+- receiver 默认按 `xyzw` 解析四元数，也可通过 `quat_order:=wxyz` 切换。
 - 左臂映射：机器人位移增量 = `[-手柄y, 手柄z, -手柄x]`。
 - 右臂映射：机器人位移增量 = `[手柄y, 手柄z, 手柄x]`。
 
-如果 `/xr/*_controller.pose.position` 已符合 Project 坐标，但某个机械臂方向相反，只改对应臂的 `xr_to_robot_matrix` 符号，不要同时改多个控制参数。
+如果某个机械臂方向相反，只改对应臂的 `xr_to_robot_matrix` 符号，不要同时改多个控制参数。
 
 ## 末端工具开合
 
@@ -296,7 +295,7 @@ ros2 topic pub --once /xr_rm/right_rm75/tool_enable std_msgs/msg/Bool "{data: fa
 
 ## UDP 数据格式
 
-当前 Unity APK 每个周期发送一个双手柄 JSON 包：
+当前 XRoboToolkit bridge 每个周期发送一个双手柄 JSON 包：
 
 ```json
 {
@@ -306,42 +305,32 @@ ros2 topic pub --once /xr_rm/right_rm75/tool_enable std_msgs/msg/Bool "{data: fa
   "frame_id": "xr_world",
   "controllers": {
     "left": {
+      "hand": "left",
       "grip": true,
       "trigger": 0.0,
+      "axis": [0.2, -0.4],
+      "buttons": {
+        "primary": true,
+        "secondary": false
+      },
       "pos": [-0.12, 1.05, 0.30],
       "quat": [0.0, 0.0, 0.0, 1.0],
       "pose_valid": true,
-      "pose_source": "pxr_predict",
-      "tracking_state": 3,
-      "controller_status": 2,
-      "grip_value": 1.0,
-      "axis": [0.0, 0.0],
-      "buttons": {
-        "grip": true,
-        "primary": false,
-        "secondary": false,
-        "menu": false,
-        "axis_click": false
-      }
+      "pose_source": "xrobotoolkit"
     },
     "right": {
+      "hand": "right",
       "grip": true,
-      "trigger": 0.4,
+      "trigger": 1.0,
+      "axis": [-0.1, 0.3],
+      "buttons": {
+        "primary": false,
+        "secondary": true
+      },
       "pos": [0.12, 1.05, 0.30],
       "quat": [0.0, 0.0, 0.0, 1.0],
       "pose_valid": true,
-      "pose_source": "unity_xr",
-      "tracking_state": 3,
-      "controller_status": -1,
-      "grip_value": 0.8,
-      "axis": [0.0, 0.0],
-      "buttons": {
-        "grip": true,
-        "primary": false,
-        "secondary": false,
-        "menu": false,
-        "axis_click": false
-      }
+      "pose_source": "xrobotoolkit"
     }
   }
 }
@@ -349,21 +338,40 @@ ros2 topic pub --once /xr_rm/right_rm75/tool_enable std_msgs/msg/Bool "{data: fa
 
 字段说明：
 
-- `t` / `source_time`：Unity 端 `Time.realtimeSinceStartupAsDouble`，用于后续延迟分析。
-- `seq`：Unity 端递增包序号，用于后续丢包分析。
+- `t` / `source_time`：bridge 的 PC 单调时间，用于诊断发送周期。
+- `seq`：bridge 递增的 UDP 包序号，bridge 重启后重新计数。
 - `frame_id`：默认 `xr_world`，会写入 `XrController.header.frame_id`。
 - `grip`：运动使能。`true` 时进入相对位姿控制，`false` 时停止。
-- `trigger`：扳机值，范围 `0.0-1.0`。真机模式下跨过 `0.95` 的上升沿会切换对应夹爪开/关状态。
+- `trigger`：经过 bridge 滞回处理的 `0.0/1.0` 值；上升沿切换对应夹爪状态。
+- `axis`：摇杆 `[x, y]`，每个分量限制在 `-1.0` 到 `1.0`。
+- `buttons.primary`：左手 X 键或右手 A 键。
+- `buttons.secondary`：左手 Y 键或右手 B 键。
 - `pos`：手柄位置，长度 3。
-- `quat`：手柄姿态四元数，默认按 `xyzw` 解析；遥操作节点会用 grip 锁定后的相对旋转控制 TCP 姿态。
-- `pose_valid`：姿态是否可信。ROS 接收端看到 `false` 会强制 `grip=false`。
-- `pose_source`：`pxr_predict`、`unity_xr`、`xrobotoolkit` 或 `none`，用于判断姿态来自 PICO 预测接口、Unity XR fallback 还是官方 XRoboToolkit SDK bridge。
-- `tracking_state` / `controller_status`：Unity/PICO 侧追踪诊断值，只用于日志和排查。
-- `grip_value`、`axis`、`buttons`：PICO 端输入诊断字段，当前不会写入 `XrController` 消息。
+- `quat`：手柄姿态四元数，默认按 `xyzw` 解析。
+- `pose_valid`：姿态是否可信；`false` 时接收端强制 `grip=false`。
+- `pose_source`：当前 bridge 使用 `xrobotoolkit`。
 
-`udp_controller_receiver` 仍兼容调试用的单手柄包：可以直接发送带 `hand`、`pos`、`quat` 的 JSON object，也可以用 `controllers` list、顶层 `left/right`、`pose.position`、`position`、`p`、`q` 等常见字段。四元数默认按 `xyzw` 解析，也可通过 `quat_order:=wxyz` 切换。
+`axis`、`buttons.primary` 和 `buttons.secondary` 会进入 `XrController`；旧 UDP
+包缺少这些字段时分别回退为 `[0,0]`、`false` 和 `false`。
 
-PICO 4 Ultra 在 Ubuntu 22.04 下配置 Unity、构建 APK、安装到头显并向 ROS2 主机发送 UDP 的详细步骤见 [docs/pico_udp_sender_ubuntu22_setup.md](docs/pico_udp_sender_ubuntu22_setup.md)。
+接收端发布的消息格式为：
+
+```text
+std_msgs/Header header
+string hand
+
+bool grip
+float32 trigger
+bool primary
+bool secondary
+float32[2] axis
+
+geometry_msgs/Pose pose
+```
+
+`udp_controller_receiver` 仍兼容调试用的单手柄包：可以直接发送带 `hand`、`pos`、
+`quat` 的 JSON object，也可以用 `controllers` list、顶层 `left/right`、
+`pose.position`、`position`、`p`、`q` 等常见字段。
 
 ## 官方 XRoboToolkit bridge
 
@@ -466,7 +474,8 @@ Controller topic 没有数据：
 - 确认 UDP 发送端目标 IP 是运行 ROS2 的主机 IP。
 - 确认端口是 `15000`，或 launch 与发送端端口一致。
 - 用 `sample_udp_sender` 在本机验证接收链路。
-- 如果 Unity HUD 显示某个手柄 `invalid none`，ROS 侧会把该手柄 `grip` 强制置为 `false`。
+- 确认 `xrobotoolkit_to_udp_bridge` 没有持续打印 SDK read failed；SDK
+  读取失败时 bridge 会发送 `pose_valid=false` 的停止包。
 
 机械臂不动：