acRealman_xr/AGENTS.md

AGENTS.md

本文件为 Codex、Claude Code 及其他编码智能体提供仓库级工作指引。若与更高优先级的系统或开发者指令冲突，以后者为准。

项目概览

本仓库是 ROS2 Humble 工作空间的 src/ 目录，用于通过 PICO/XR 控制器遥操作左右两台 RealMan RM75 机械臂。

控制器映射、运动控制链路和 IK 实现后续可能调整。修改前应阅读当前源码、启动文件、配置和 README.md，不要将现有 topic 链路、适配器或 IK 算法视为固定架构。

仓库结构

• xr_rm_interfaces：ROS 消息定义。
• xr_rm_input：XR 控制器数据输入与测试发送工具。
• xr_rm_teleop：控制器映射、机械臂控制及相关算法。
• xr_rm_bringup：启动文件、机械臂配置及启动工具。
• unity/XR_RM_PICO_UDP_Sender：Unity/PICO 数据发送项目。

工作空间根目录：/home/robot/WS_xr

源码根目录：/home/robot/WS_xr/src

除非任务明确涉及，否则将 PICO SDK、XRoboToolkit、机械臂 SDK 及其他引入的依赖视为第三方代码。

构建与运行

在工作空间根目录执行 ROS2 命令：

cd /home/robot/WS_xr
source /opt/ros/humble/setup.bash
colcon build --symlink-install
source install/setup.bash

Mock 模式启动：

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

真实机械臂支持 arm:=left|right|both 和 use_mock:=false。只有在用户明确要求且测试环境安全时，才可执行真实机械臂测试。

开发流程

• 修改前阅读相关代码、配置和文档。
• 先执行 git status --short，保留用户未提交及与当前任务无关的修改。
• 修改应尽量小，并严格限定在当前任务范围内。
• 不得自动执行 git add、提交、推送、合并、强制推送或删除分支。
• 完成后说明修改的文件、已执行的验证及剩余风险。

文件修改确认门槛

• 任何创建、编辑、删除、重命名、格式化文件或生成会写入磁盘的产物，都属于文件修改。
• 修改前必须说明目标、涉及文件、实施方案、风险和验证方式，然后等待用户明确授权。
• 只有当前消息中包含明确执行意图，如“直接修改”“执行”“应用这些修改”“写入文件”“创建”或“删除”，才视为授权。
• “可以……吗”“能否……”“是否可以”“怎么修改”“这样行吗”等疑问或讨论，只表示咨询，不构成文件修改授权。此时只能回答问题或提出方案，不得写入文件。
• 用户此前允许过其他修改，不代表自动授权新的修改；每个新增范围都应重新确认。
• 授权仅覆盖用户明确提出的范围。发现需要修改额外文件时，应先说明原因并再次取得授权。
• 执行任何可能写入文件的工具前，应再次核对用户当前消息是否已经明确授权；无法确定时，必须先询问，不得自行推断。

IK 与控制修改

• 将当前 IK 和控制策略视为可替换实现；先检查实际代码，不要预设使用笛卡尔流式控制、速度控制或某种特定求解器。
• 除非任务明确要求修改，否则保留现有 ROS 接口和启动参数；有意进行的兼容性变更必须写入文档。
• 明确坐标系、四元数顺序、单位、关节顺序和时间戳约定。
• 根据算法需要处理非有限数值、关节与工作空间限制、奇异点、指令频率限制和数据超时。
• 修改映射、滤波、IK、轨迹生成或适配器时，不得削弱停止机制。
• 算法修改应先通过静态检查、确定性输入测试或 Mock 测试，再进行真实机械臂测试。

安全规则

本项目能够控制真实机械臂，涉及硬件的修改必须保守进行。

不得随意修改机械臂 IP、端口 8080、工作空间或圆柱限制、坐标变换、初始位姿、速度/加速度限制及末端执行器配置。

当输入无效或被释放、数据过期、通信失败、适配器抛出异常、节点或应用退出时，机械臂必须安全停止。除非用户明确要求，否则 move_to_initial_pose_on_connect 默认保持为 false。

涉及安全的修改按以下顺序验证：

1. 静态检查和语法检查。
2. 针对性的单元测试或算法测试。
3. Mock 模式。
4. 单台真实机械臂低速测试。
5. 双臂真实测试。

除非相关能力已经实现并经过验证，否则不得声称项目具备碰撞规避、IK 安全保证或其他保护能力。

文档与生成文件

• README.md 是面向用户的主项目文档；AGENTS.md 用于记录智能体工作流程和安全规则。
• 与具体实现相关的协议、topic 和配置说明应放入对应 README 或专项文档，不在此处重复维护。
• 不得将尚未实现的功能描述为已完成。
• 将 Unity 的 Library/、Builds/、Logs/、UserSettings/、APK、生成日志及构建输出视为生成文件。
• 安全敏感修复期间避免大范围重构，代码应保持便于现场调试。

验证

根据修改内容选择合适的检查方式，至少执行：

cd /home/robot/WS_xr/src
git diff --check

修改 ROS 代码时，优先构建目标软件包，再进行完整工作空间构建。自动化测试无法单独证明真实硬件行为安全。