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/QUICKSTART.md

@@ -0,0 +1,67 @@
+# 快速上手
+
+更完整的目录说明：[WORKSPACE.md](WORKSPACE.md)。
+
+## 依赖
+
+- Ubuntu 22.04 + ROS 2 Humble
+- Conda 环境 `ros_flexiv`（本仓库脚本默认这个名字）
+- Flexiv RDK Python：`/home/cc/rdk_py310/bin/python`（flexivrdk 1.9.x）
+- 工控机与机器人在同一网段（例：`192.168.2.10` ↔ `192.168.2.101`）
+- Intel RealSense D405，`pyrealsense2`
+- YOLO：`ultralytics`；TensorRT：`tensorrt-cu12`（不要装 meta 包 `tensorrt`）
+- 夹爪：`pyserial`，USB–RS485 → `/dev/ttyUSB0`（PGEA）`/dev/ttyUSB1`（RGI）
+
+每次新开终端：
+
+```bash
+conda activate ros_flexiv
+source ~/ros2/scripts/env.sh
+```
+
+## 配置
+
+```bash
+cp ~/ros2/config/site.example.yaml ~/ros2/config/site.yaml
+```
+
+必填：`robot.sn`、`robot.robots[].ip`、`camera.serial`（多相机时）、`paths.yolo_weights`。
+
+查看解析结果：
+
+```bash
+bash ~/ros2/scripts/show_site_config.sh
+```
+
+## 编译
+
+```bash
+cd ~/ros2
+./scripts/build_all.sh
+source scripts/env.sh
+```
+
+只改 Python 应用时，develop 安装会直接读 `src/`。改了 `setup.py` 的 `console_scripts` 后需要再编一次 `arm_application`。
+
+## 第一次实机
+
+1. 示教器：AUTO + Remote Ethernet，清故障。关 Studio。
+2. `bash ~/ros2/scripts/test_rdk_python.sh`（可选）
+3. T1 `run_real.sh`，T2 `run_camera_d405.sh --preview`
+4. 手眼：见 [HANDEYE.md](HANDEYE.md)
+5. T3 `run_visual_servo_rt.sh` 先观察，再 `--control`
+
+回零：
+
+```bash
+bash ~/ros2/scripts/go_home.sh
+```
+
+会先杀掉 perception/servo，避免轨迹抢臂。
+
+## Mock（无机器人）
+
+```bash
+bash ~/ros2/scripts/run_sim.sh
+ros2 run arm_application demo_named_poses
+```