forked from YikaiFu-cart/acRealman_xr
198 lines
6.5 KiB
Markdown
198 lines
6.5 KiB
Markdown
# CODEX 项目工作流
|
||
|
||
本文件是本仓库给 Codex、Claude Code 和其他代码代理的项目规则。进入仓库后应先阅读并遵守本文件；如果系统或开发者级指令与本文件冲突，以更高优先级指令为准。
|
||
|
||
## 项目定位
|
||
|
||
本仓库是 ROS2 Humble 工作空间的 `src/` 层，用于 PICO/XR 双手柄遥操作左右睿尔曼 RM75：
|
||
|
||
```text
|
||
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、target_pose、cmd_vel
|
||
```
|
||
|
||
核心控制方式是相对位移遥操作：`grip=true` 的第一帧锁定手柄起点和机器人 TCP 起点，之后用手柄位移增量生成目标 TCP；`grip=false`、UDP 超时、异常或节点退出必须停止。
|
||
|
||
## 固定工作流
|
||
|
||
参考 `/home/robot/下载/claude_code_codex_workflow.md`，本项目采用：
|
||
|
||
```text
|
||
需求文档 / issue
|
||
-> 新建 Git 分支
|
||
-> Codex/Claude Code 先读项目，不直接改
|
||
-> 输出理解、方案、涉及文件和风险
|
||
-> 人工确认方向
|
||
-> AI 小步修改
|
||
-> 本地运行测试 / 构建 / mock 验证
|
||
-> 人工 review git diff
|
||
-> 用户决定是否 commit / push / merge
|
||
```
|
||
|
||
原则：
|
||
|
||
- 人负责目标、验收和最终合并。
|
||
- AI 负责探索、修改、运行检查、总结风险。
|
||
- Git 分支、测试和 `git diff` 是隔离与回滚边界。
|
||
- 不允许绕过人工确认直接提交、推送或删除重要文件。
|
||
|
||
## 代理执行规则
|
||
|
||
- 先探索，再修改。优先读相关 package、launch、YAML、消息、Unity 脚本和 README。
|
||
- 修改前说明目标理解、涉及文件、实现计划和风险；小任务可以简短说明后直接执行。
|
||
- 只改与任务相关的最小文件集，避免无关重构、格式化和大范围重写。
|
||
- 不要自动 `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`
|
||
- UDP 超时 / controller 数据过期
|
||
- adapter 异常
|
||
- 节点 shutdown
|
||
- PICO App 暂停、退出或关闭发送
|
||
- 默认不要打开 `move_to_initial_pose_on_connect:=true`。
|
||
- 当前没有双臂碰撞检测。不要在文档或代码中暗示已经具备双臂避碰。
|
||
- 真机验证顺序必须是 mock -> 单臂 -> 双臂。
|
||
|
||
## 标准命令
|
||
|
||
所有 ROS2 命令从工作空间根目录 `/home/robot/WS_xr` 执行：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
ros2 launch xr_rm_bringup arm_debug.launch.py arm:=both use_mock:=true
|
||
```
|
||
|
||
模拟 UDP：
|
||
|
||
```bash
|
||
ros2 run xr_rm_input sample_udp_sender --hand both --host 127.0.0.1 --port 15000 --seconds 10
|
||
```
|
||
|
||
常用话题：
|
||
|
||
```bash
|
||
ros2 topic echo /xr/left_controller
|
||
ros2 topic echo /xr/right_controller
|
||
ros2 topic echo /xr_rm/left_rm75/cmd_vel
|
||
ros2 topic echo /xr_rm/right_rm75/cmd_vel
|
||
```
|
||
|
||
单臂真机：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
双臂真机：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
图形启动面板：
|
||
|
||
```bash
|
||
python3 src/xr_rm_bringup/tools/launcher_ui.py
|
||
```
|
||
|
||
Git 检查：
|
||
|
||
```bash
|
||
git status --short
|
||
git diff
|
||
git diff --check
|
||
```
|
||
|
||
## 常用工作模式
|
||
|
||
探索项目：
|
||
|
||
```text
|
||
请阅读这个项目，不要修改任何文件。请输出项目整体功能、主要入口、关键模块关系、如何运行和当前风险。
|
||
```
|
||
|
||
定位 bug：
|
||
|
||
```text
|
||
这是报错日志：XXX。请先定位原因，不要改代码。列出最可能原因、相关文件、验证方法和最小修改方案。
|
||
```
|
||
|
||
小功能开发：
|
||
|
||
```text
|
||
请实现 XXX。限制：不改变现有接口，不重构无关代码，修改前说明计划，修改后运行测试或告诉我如何测试。
|
||
```
|
||
|
||
代码审查：
|
||
|
||
```text
|
||
请 review 当前 git diff。重点检查逻辑错误、现有功能影响、路径/权限/平台兼容、可读性和不该提交的大文件。
|
||
```
|
||
|
||
文档同步：
|
||
|
||
```text
|
||
请根据当前代码更新 README。要求：不夸大功能，写清安装、运行、常见问题，Ubuntu 和 Windows 命令分开，不删除重要说明。
|
||
```
|
||
|
||
## 包职责
|
||
|
||
- `xr_rm_interfaces`：定义 `XrController`。
|
||
- `xr_rm_input`：接收 UDP controller JSON，发布左右手柄话题，并提供 `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 工程。
|
||
|
||
## 文档规则
|
||
|
||
- 根目录保留 `README.md` 和 `CODEX.md`。
|
||
- `README.md` 是唯一项目主文档，包含 ROS2 构建、运行、mock、真机、安全和协议说明。
|
||
- `CODEX.md` 是代码代理规则文档，修改工作流时优先更新它。
|
||
- `docs/` 只保留 Ubuntu 22.04 下 PICO 发送 UDP 数据的配置教程。
|
||
- 不要新增零散 Markdown，除非用户明确要求。
|
||
- 不要声明未实现功能已经完成。mock、真机、Unity/PICO 路线要写清楚。
|
||
|
||
## Unity / PICO 规则
|
||
|
||
- 当前 Unity 工程：`unity/XR_RM_PICO_UDP_Sender`。
|
||
- 当前 PICO SDK：`unity/PICO-Unity-Integration-SDK-release_3.4.0`。
|
||
- APK、Unity `Builds/`、`Library/`、日志和临时文件不是源码，不应提交。
|
||
- PICO UDP 目标 IP 必须是当前 Ubuntu ROS 主机在同一局域网的 IPv4。
|
||
- PICO App 暂停、退出或关闭发送时必须发送 `grip=false` 或让 ROS 侧超时安全停止。
|
||
|
||
## 不在当前任务范围内
|
||
|
||
除非用户明确要求，不要实现：
|
||
|
||
- XRoboToolkit PC-Service bridge。
|
||
- D405/D435 视频流和数据记录。
|
||
- 双臂碰撞检测。
|
||
- 自动采摘任务状态机。
|
||
- QP IK、灵巧手 retarget、全身 tracker。
|