chore: 框架科学优化前的完整基线

在开始'设备契约层 + 目录重构 + 通止规装配'改造之前，先钉住当前可运行状态，
使后续任何删除/重构都可回退。

本基线包含：
- 现有 ROS 2 工作区全部源码（arm_application / arm_control / arm_bringup 等）
- 官方 flexiv_ros2 栈（含 flexiv_hardware / flexiv_controllers 等符号链接）
- 设备契约层 src/arm_interfaces（新增，46 项单测通过）
- devices/ 设备选型与品牌清单（新增）
- scripts/gen_site_example.py 与由它生成的 config/site.example.yaml

按 .gitignore 排除：build/ / install/ / log/ / config/site.yaml / 模型权重二进制。

docs/HANDEYE.md

@@ -0,0 +1,44 @@
+# 手眼标定（眼在手上）
+
+每台机械臂一份结果，**禁止混用**：
+
+| 臂 | 结果 | 示教关节 | 工作目录 |
+|----|------|----------|----------|
+| 89 左 | `src/arm_application/config/handeye_result_89.yaml` | `handeye_poses_89.yaml` | `/tmp/handeye_calib_89` |
+| 91 右 | `src/arm_application/config/handeye_result_91.yaml` | `handeye_poses_91.yaml` | `/tmp/handeye_calib_91` |
+
+`T_4x4` = **相机 → 法兰**。跟踪和静态 TF 都读当前 `--arm` 对应的文件。
+
+棋盘尺寸只改 `site.yaml` → `handeye.board_*` / `square_size_m`（内角点 = 方格数 − 1）。两臂可共用同一块板。
+
+## 流程
+
+`teach`（RDK 软拖拽）与 `run_real.sh` **互斥**。全程带同一 `--arm`。
+
+```bash
+# 1) 停掉 run_real.sh 和视觉伺服
+# 2) 示教 8–12 个姿态（棋盘清晰、占画面 30–70%，姿态拉开）
+bash ~/ros2/scripts/run_handeye.sh --arm 89 teach
+#    窗口：d=拖拽  Enter=拍照  q=结束
+#    接着采、不清空旧点：  teach --append
+
+# 3) 写入该臂的 handeye_poses_XX.yaml
+bash ~/ros2/scripts/run_handeye.sh --arm 89 merge
+
+# 4) 再开实机 + 相机，棋盘不要动
+bash ~/ros2/scripts/run_real.sh --arm 89
+bash ~/ros2/scripts/run_camera_d405.sh --arm 89 --preview
+bash ~/ros2/scripts/run_handeye.sh --arm 89 calibrate
+```
+
+91 把 `--arm 89` 改成 `--arm 91`。91 的结果文件初始是 `uncalibrated: true`，标定成功后才会写出 `T_4x4`。
+
+查看路径与板参数：`bash ~/ros2/scripts/run_handeye.sh --arm 89 show`
+
+## 结果怎么用
+
+`visual_servo.launch.py` 读当前臂 `T_4x4`，发布 `{ee_frame}` → `{camera_frame}` 的 static TF。
+
+`servo_node` 用同一份 T 做 `hover` / `lookat`。换结果后**重启** `run_visual_servo_rt.sh --arm …`。
+
+装配 HMI（`ros_flexiv`）选左/右臂后，读同一份 `handeye_result_89.yaml` / `_91.yaml`。