acRealman_xr/CODEX.md

CODEX 项目工作流

本文件是本仓库给 Codex、Claude Code 和其他代码代理的项目规则。进入仓库后应先阅读并遵守本文件；如果系统或开发者级指令与本文件冲突，以更高优先级指令为准。

项目定位

本仓库是 ROS2 Humble 工作空间的 src/ 层，用于 PICO/XR 双手柄遥操作左右睿尔曼 RM75：

PICO/XR UDP JSON
  -> xr_rm_input/udp_controller_receiver
  -> /xr/left_controller 与 /xr/right_controller
  -> xr_rm_teleop/single_arm_velocity_teleop
  -> MockRealManAdapter 或 RealManAdapter
  -> /xr_rm/<arm_name>/current_pose、raw_target_pose、target_pose、cmd_vel、target_clamped

核心控制方式是相对位姿透传遥操作：grip=true 的第一帧锁定手柄起点和机器人 TCP 起点，之后用手柄位移增量生成目标 TCP，并通过 rm_movep_canfd 下发位姿目标；grip=false、pose_valid=false、UDP 超时、异常或节点退出必须停止。

固定工作流

参考 /home/robot/下载/claude_code_codex_workflow.md，本项目采用：

需求文档 / issue
  -> 新建 Git 分支
  -> Codex/Claude Code 先读项目，不直接改
  -> 输出理解、方案、涉及文件和风险
  -> 人工确认方向
  -> AI 小步修改
  -> 本地运行测试 / 构建 / mock 验证
  -> 人工 review git diff
  -> 用户决定是否 commit / push / merge

原则：

• 人负责目标、验收和最终合并。
• AI 负责探索、修改、运行检查、总结风险。
• Git 分支、测试和 git diff 是隔离与回滚边界。
• 默认不允许绕过人工确认直接修改文件、提交、推送或删除重要文件。
• 除非用户明确写出“可以直接修改”“无需确认”“直接执行”等授权语句，否则任何会写入文件的操作前都必须先输出计划并等待人工确认。

代理执行规则

• 先探索，再修改。优先读相关 package、launch、YAML、消息、Unity 脚本和 README。
• 修改前必须先说明目标理解、涉及文件、实现计划、风险和验证方式，并等待用户明确回复同意后再动手。
• 小任务也遵守确认门禁；可以把计划写得很短，但不能在未获授权时直接写文件。
• 用户已经明确授权直接修改的当前请求，可以在简短说明后执行；仍需保持小步修改并在结束时总结差异。
• 在等待确认前，可以执行只读探索命令，例如查看文件、搜索代码、检查 git status --short 和阅读 diff。
• 只改与任务相关的最小文件集，避免无关重构、格式化和大范围重写。
• 不要自动 git add .、commit、push、force push、删分支或合并分支。
• 不要回滚用户已有改动。工作区有未提交内容时，默认它们属于用户。
• 删除文件、修改真机参数、修改运动控制逻辑前必须有明确任务依据。
• 修改后给出：改了哪些文件、核心行为变化、如何运行、如何测试、残余风险。

机器人安全规则

• 不要随意修改真实硬件参数：
  • 左臂 IP：192.168.192.18
  • 右臂 IP：192.168.192.19
  • RM75 TCP 端口：8080
• 不要随意修改工作空间边界、圆柱半径限制、xr_to_robot_matrix、初始化关节/TCP 位姿、速度/加速度限制、末端外设配置。
• 真机相关改动必须保持以下安全停止路径：
  • grip=false
  • PICO/Unity 发送 pose_valid=false
  • UDP 超时 / controller 数据过期
  • adapter 异常
  • 节点 shutdown
  • PICO App 暂停、退出或关闭发送
• 默认不要打开 move_to_initial_pose_on_connect:=true。
• 当前没有双臂碰撞检测。不要在文档或代码中暗示已经具备双臂避碰。
• 真机验证顺序必须是 mock -> 单臂 -> 双臂。

标准命令

所有 ROS2 命令从工作空间根目录 /home/robot/WS_xr 执行：

cd /home/robot/WS_xr
source /opt/ros/humble/setup.bash
rosdep install --from-paths src -y --ignore-src
colcon build --symlink-install
source install/setup.bash

双臂 mock：

ros2 launch xr_rm_bringup arm_debug.launch.py arm:=both use_mock:=true

模拟 UDP：

ros2 run xr_rm_input sample_udp_sender --hand both --host 127.0.0.1 --port 15000 \
  --pattern axis_sweep --seconds 60 --both-mode staggered

当前 sample_udp_sender 默认用 axis_sweep 扫轴轨迹；--both-mode staggered 会先左后右，适合双臂方向检查。

常用话题：

ros2 topic echo /xr/left_controller
ros2 topic echo /xr/right_controller
ros2 topic echo /xr_rm/left_rm75/target_pose
ros2 topic echo /xr_rm/right_rm75/target_pose
ros2 topic echo /xr_rm/left_rm75/cmd_vel
ros2 topic echo /xr_rm/right_rm75/cmd_vel

单臂真机：

ros2 launch xr_rm_bringup arm_debug.launch.py arm:=left use_mock:=false
ros2 launch xr_rm_bringup arm_debug.launch.py arm:=right use_mock:=false

双臂真机：

ros2 launch xr_rm_bringup arm_debug.launch.py arm:=both use_mock:=false \
  left_robot_ip:=192.168.192.18 \
  right_robot_ip:=192.168.192.19

图形启动面板：

python3 src/xr_rm_bringup/tools/launcher_ui.py

Git 检查：

git status --short
git diff
git diff --check

常用工作模式

探索项目：

请阅读这个项目，不要修改任何文件。请输出项目整体功能、主要入口、关键模块关系、如何运行和当前风险。

定位 bug：

这是报错日志：XXX。请先定位原因，不要改代码。列出最可能原因、相关文件、验证方法和最小修改方案。

小功能开发：

请实现 XXX。限制：不改变现有接口，不重构无关代码。本轮先不要修改文件，请先说明计划、涉及文件、风险和验证方式，等我回复“开始修改”后再动手。

直接授权小改：

请直接修改 XXX，无需等待二次确认。限制：只改相关文件，修改后说明差异和验证方式。

代码审查：

请 review 当前 git diff。重点检查逻辑错误、现有功能影响、路径/权限/平台兼容、可读性和不该提交的大文件。

文档同步：

请根据当前代码更新 README。要求：不夸大功能，写清安装、运行、常见问题，Ubuntu 和 Windows 命令分开，不删除重要说明。

包职责

• xr_rm_interfaces：定义 XrController。
• xr_rm_input：接收 UDP controller JSON，发布左右手柄话题；pose_valid=false 会强制 grip=false；提供 sample_udp_sender 扫轴/正弦调试数据。
• xr_rm_teleop：把手柄相对位移映射成 RM75 笛卡尔位姿透传目标。
• xr_rm_bringup：维护 launch、YAML、现场 UI 和运行入口。
• unity/XR_RM_PICO_UDP_Sender：PICO 4 Ultra UDP Sender Unity 工程，发送 seq、source_time、pose_valid、pose_source、tracking/controller status 等诊断字段。

文档规则

• 根目录保留 README.md 和 CODEX.md。
• README.md 是唯一项目主文档，包含 ROS2 构建、运行、mock、真机、安全和协议说明。
• CODEX.md 是代码代理规则文档，修改工作流时优先更新它。
• docs/ 下的 Markdown 只维护 Ubuntu 22.04 下 PICO 发送 UDP 数据的配置教程；已有非 Markdown 汇报材料不要扩写成源码教程。
• 不要新增零散 Markdown，除非用户明确要求。
• 不要声明未实现功能已经完成。mock、真机、Unity/PICO 路线要写清楚。

Unity / PICO 规则

• 当前 Unity 工程：unity/XR_RM_PICO_UDP_Sender。
• 当前 PICO SDK：unity/PICO-Unity-Integration-SDK-release_3.4.0。
• 当前 Unity package 还依赖 TextMeshPro，PICO 面板字体来自预生成的 Assets/Resources/Fonts/Roboto-Regular SDF.asset 和 Roboto-Bold SDF.asset；不要在 APK 运行时动态创建 TMP 字体资产。
• APK、Unity Builds/、Library/、日志和临时文件不是源码，不应提交。
• PICO UDP 目标 IP 必须是当前 Ubuntu ROS 主机在同一局域网的 IPv4。
• PICO App 暂停、退出或关闭发送时必须发送 grip=false，姿态无效时必须发送 pose_valid=false 并让 ROS receiver 强制停止。
• 当前 Unity Project (+Z back) 输出必须是 +X 右、+Y 上、+Z 后。PXR pxr_predict 原始坐标按实测先转换为 project.x=native.z、project.y=native.y、project.z=-native.x；Source raw 仅用于现场对照。若 /xr/*_controller.pose.position 已正确但某一只臂方向不对，优先改对应 YAML 的 xr_to_robot_matrix。

不在当前任务范围内

除非用户明确要求，不要实现：

• XRoboToolkit PC-Service bridge。
• D405/D435 视频流和数据记录。
• 双臂碰撞检测。
• 自动采摘任务状态机。
• QP IK、灵巧手 retarget、全身 tracker。