# 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 代码时，优先构建目标软件包，再进行完整工作空间构建。自动化测试无法单独证明真实硬件行为安全。