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 / 模型权重二进制。

README.md

@@ -0,0 +1,82 @@
+# Flexiv Rizon 视觉伺服（`~/ros2`）
+
+独立工作空间：腕部 D405 眼在手上、手眼标定、YOLO 找工件、法兰悬停跟踪、DH 夹爪、入孔检测。  
+**一份仓库即可跑完整跟踪与检测**，不依赖 `camera_test` 或装配 HMI。
+
+工作目录必须是 ASCII 路径（推荐克隆到 `~/ros2`）。
+
+| 项 | 值 |
+|----|-----|
+| 配置 | [`config/site.yaml`](config/site.example.yaml)（从 example 复制，不进 git） |
+| 操作 | [`scripts/`](scripts/README.md) |
+| 目录说明 | **[docs/WORKSPACE.md](docs/WORKSPACE.md)**（每个文件夹做什么） |
+| Conda | `ros_flexiv` |
+| ROS | Humble |
+
+## 克隆后
+
+```bash
+cd ~/ros2
+cp config/site.example.yaml config/site.yaml
+# 编辑 site.yaml：robot.sn / robots[].ip / camera.serial / paths.yolo_weights
+# 权重文件放到 models/yolo/（二进制不在 git 里）
+
+conda activate ros_flexiv
+source scripts/env.sh
+./scripts/build_all.sh
+source scripts/env.sh
+```
+
+示教器：**AUTO + Remote Ethernet**，关掉 Flexiv Studio（RDK 独占）。
+
+```bash
+# 三个终端必须带同一个 --arm（89=左  91=右）
+bash ~/ros2/scripts/run_real.sh --arm 89
+bash ~/ros2/scripts/run_camera_d405.sh --arm 89 --preview
+bash ~/ros2/scripts/run_visual_servo_rt.sh --arm 89 --control
+```
+
+改 `site.yaml`：锁高 / YOLO / 伺服 → 重启第三终端；分辨率 / 曝光 → 重启相机。
+
+## 功能入口
+
+| 功能 | 命令 |
+|------|------|
+| 实机 | `scripts/run_real.sh --arm 89\|91` |
+| 腕部相机 | `scripts/run_camera_d405.sh --arm … --preview` |
+| 顶视 D435 | `scripts/run_camera_d435.sh --preview` |
+| 列出相机 | `scripts/list_realsense.sh` |
+| 跟踪 | `scripts/run_visual_servo_rt.sh --arm … [--control]` |
+| 回 home | `scripts/go_home.sh --arm …` |
+| 手眼 | `scripts/run_handeye.sh --arm … teach` → `merge` → `calibrate` |
+| PGEA / RGI 夹爪 | `scripts/run_gripper.sh --arm 89\|91 --cli …` |
+| 双爪 ROS | `scripts/run_dual_gripper.sh` |
+| 入孔检测 | `scripts/run_hole_detect.sh --arm … --preview` |
+| Orisys 触觉 | `scripts/run_tactile.sh [--cli]` |
+| 看配置 | `scripts/show_site_config.sh` |
+
+89 与 91 **各有** 手眼、相机序列号、锁高、named poses，禁止混用。
+
+## 文档
+
+| 文档 | 内容 |
+|------|------|
+| [docs/WORKSPACE.md](docs/WORKSPACE.md) | 每个目录 / 脚本 / 包 |
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | 环境与第一次跑通 |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 进程与几何 |
+| [docs/SITE_CONFIG.md](docs/SITE_CONFIG.md) | `site.yaml` 字段 |
+| [docs/HANDEYE.md](docs/HANDEYE.md) | 手眼标定 |
+| [docs/TRACKING.md](docs/TRACKING.md) | 视觉伺服 |
+| [docs/GRIPPER.md](docs/GRIPPER.md) | PGEA + RGI |
+| [docs/HOLE_DETECT.md](docs/HOLE_DETECT.md) | 入孔检测 |
+| [docs/TACTILE.md](docs/TACTILE.md) | Orisys 视触觉 |
+| [docs/INTERFACES.md](docs/INTERFACES.md) | ROS / 脚本接口 |
+| [docs/TRAJECTORIES.md](docs/TRAJECTORIES.md) | 轨迹回放 |
+
+## 上传 git 时
+
+- **要提交**：`src/` `scripts/` `docs/` `config/site.example.yaml` `models/yolo/README.md` `models/hole_insert/README.md`
+- **不要提交**：`config/site.yaml`（含本机 IP/序列号）、`build/` `install/` `log/`、YOLO `.pt/.onnx/.engine`、`thirdparty/` `vendor/`
+- 规则已写在 `.gitignore`
+
+别人克隆后必须自己 `cp site.example.yaml site.yaml` 并重新手眼标定（不要直接用仓库里某台现场的 `T_4x4` 当真值）。