Add IK types, validation, and tests for RM75 kinematics

AGENTS.md

@@ -0,0 +1,106 @@
+# 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 命令：
+
+```bash
+cd /home/robot/WS_xr
+source /opt/ros/humble/setup.bash
+colcon build --symlink-install
+source install/setup.bash
+```
+
+Mock 模式启动：
+
+```bash
+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、生成日志及构建输出视为生成文件。
+- 安全敏感修复期间避免大范围重构，代码应保持便于现场调试。
+
+## 验证
+
+根据修改内容选择合适的检查方式，至少执行：
+
+```bash
+cd /home/robot/WS_xr/src
+git diff --check
+```
+
+修改 ROS 代码时，优先构建目标软件包，再进行完整工作空间构建。自动化测试无法单独证明真实硬件行为安全。