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

@@ -0,0 +1,54 @@
+# 架构
+
+## 进程（实机跟踪）
+
+```
+run_real.sh                 Flexiv RDK + ros2_control + named_pose
+run_camera_d405.sh          该臂 D405 → /d405_left 或 /d405_right（彩图+对齐深度+预览）
+run_visual_servo_rt.sh
+   perception_node          YOLO + 平面中心 → /visual_servo/filtered_point
+   servo_node               100 Hz，法兰 hover / 锁高 → JointTrajectory
+   static TF                flange → camera（手眼 T）
+run_gripper.sh              可选，IPC Modbus PGEA 或 RGI
+run_dual_gripper.sh         双爪同一节点
+run_hole_detect.sh          入孔检测（当前臂 D405）
+run_tactile.sh              Orisys 左右指视触觉
+```
+
+RDK 独占：`run_real.sh` 与 `run_handeye.sh teach`（RDK 拖拽）不能同时开。  
+D405 USB 独占：相机节点与示教/标定自己开会互斥；wrapper 会先停旧相机。
+
+## 目录
+
+```
+~/ros2/
+├── README.md                 # 克隆后怎么跑
+├── config/
+│   ├── site.example.yaml     # 模板（入库）
+│   └── site.yaml             # 本机配置（不入库）
+├── docs/                     # 说明；总表见 WORKSPACE.md
+├── models/yolo/              # 工件权重二进制不入库
+├── models/hole_insert/       # 入孔权重二进制不入库
+├── scripts/                  # 唯一操作入口
+├── src/                      # ROS 2 包
+├── build/  install/  log/    # colcon，不入库
+```
+
+## 配置流
+
+```
+config/site.yaml
+    → scripts/lib/export_site_env.py   SITE_* 环境变量 + ROS 覆盖字典
+    → run_*.sh / visual_servo.launch.py
+    → 节点参数（覆盖包内 perception.yaml / servo.yaml）
+```
+
+包内 yaml 只是默认值，日常不要改。
+
+## 跟踪几何
+
+手眼 `T_cam_to_gripper`（`handeye_result.yaml`）把相机点变到法兰。  
+`servo.xy_track`：
+
+- `hover`：基座系法兰 XY = 工件 3D 点 XY，任意 `ee_z_m`
+- `lookat`：光影像中心对准工件（倾斜相机时只有某一高度法兰才在正上方）