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

@@ -0,0 +1,45 @@
+# 视觉伺服
+
+## 启动
+
+```text
+T1  bash ~/ros2/scripts/run_real.sh --arm 89          # 或 --arm 91
+T2  bash ~/ros2/scripts/run_camera_d405.sh --arm 89 --preview
+T3  bash ~/ros2/scripts/run_visual_servo_rt.sh --arm 89            # 只看框
+    bash ~/ros2/scripts/run_visual_servo_rt.sh --arm 89 --control  # 动臂
+```
+
+三个终端必须带**同一个** `--arm`。89 相机话题是 `/d405_left/...`，91 是 `/d405_right/...`，预览顶栏会写「左臂89 / 右臂91」。不要混用。
+
+`--control` 从当前法兰位姿开节点，不再先抬 `safe_z_m`、也不回 `home`。
+
+`hover` + `ee_vertical_down`：法兰（夹爪中心）XY 压在工件上，法兰轴线朝下。腕部相机有倾角，绿框**不必**对准画面十字。锁高在 `robots[].servo.ee_z_m`，89/91 分开。
+
+## 数据流
+
+```
+D405 彩图+深度
+  → perception_node（绿框中心 × 立体平面 Z；红点应在绿框里）
+  → /visual_servo/filtered_point   (相机系)
+  → servo_node 100 Hz
+       hover: 法兰 XY → 工件 XY（基座）
+       锁高: 法兰 Z → ee_z_m
+       姿态: 法兰 +Z 朝世界 −Z
+  → /rizon_arm_controller/joint_trajectory
+```
+
+绿框：相机回调立刻把最新帧丢给 GPU；画出的框会按像素速度补上推理延迟，所以应贴在**当前**工件上，而不是 YOLO 看到的旧位置。丢检时绿框只滑行几帧（不驱动 3D）；预览 `overlay_hold_sec` 必须短，否则旧框会糊在新画面上。丢检空窗内伺服用**基座系 KF 预测**继续跟（眼在手上安全，不随臂动漂移），超过 `stale_hold_sec` 才钉住。
+
+## 调参（`site.yaml` → `servo` / `yolo`）
+
+| 目标 | 键 |
+|------|-----|
+| 绿框跟手、少丢 | 略降 `conf`/`min_conf`；加大 `jump_px`、`miss_clear_frames`；重启 T3 |
+| 绿框稳、少跳 | 略降 `box_ema_alpha`；重启 T3 |
+| 臂跟手 | 加大 `v_max_xy` `kp_xy` |
+| 臂丝滑 | 加大 `a_max` 会更快起步；减小 `a_max` / `vel_lpf_alpha` 更顺 |
+| 轨迹预测 | `predict_enable` `predict_sec`；乱飞则减小 `predict_sec` 或关预测 |
+| 画面中心对准 | `xy_track: lookat` |
+| 换模型 | `paths.yolo_weights` + `yolo.imgsz` + 导出 `.engine` |
+
+改完重启 T3。