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

devices/robots/README.md

@@ -0,0 +1,61 @@
+# devices/robots/ —— 机械臂
+
+## 厂商物料放置要求
+
+每个品牌一个子目录，物料放在该子目录下的 `rdk/`（或厂商自定的物料目录，须在 `manifest.yaml`
+的 `assets` 里声明）。
+
+**通用要求：**
+
+| 项 | 要求 |
+|----|------|
+| 格式 | 厂商**原始发布格式**，不要自行转换、不要重新打包成 zip/tar 后不展开 |
+| 命名 | **保持厂商原目录名和原文件名，一律不要改名**。改名会导致 RDK 内部的 include 路径、CMake 查找路径、Python 包名全部失效 |
+| 版本 | 在 `manifest.yaml` 的 `version` 字段里记录版本号，方便日后排查 |
+| 编译产物 | 不要把编译产物（`.a` `.so` `build/`）提交进 git；离线库放 `vendor/` |
+| 生效 | 放好物料 → 编译一次 → 改 `devices/registry.yaml` 选型 → 重启 `scripts/run_real.sh` |
+
+## 目录结构
+
+```
+robots/
+├── README.md
+├── flexiv/                      # 非夕（当前在用）
+│   ├── manifest.yaml
+│   ├── rdk/                     # 厂商 RDK 源码或安装包，原样放置
+│   └── driver/                  # 适配器：把 RDK API 翻译成框架接口
+└── <新品牌>/
+    ├── manifest.yaml
+    ├── rdk/ 或 sdk/
+    └── driver/
+```
+
+## 适配器必须实现的接口契约
+
+框架上层（伺服、跟踪、装配状态机、手眼标定）**只调用下面这组接口，不认识任何厂商 SDK**。
+契约定义在 `src/arm_interfaces/`，每个方法对应的 ROS 2 话题/服务/action 也在那里声明。
+
+| 能力 | 用途 | 谁在用 |
+|------|------|--------|
+| `get_arm_state` | 读关节角 + 末端位姿 | 手眼标定、状态记录 |
+| `follow_joint_trajectory` | 关节轨迹（点到点、多路点） | 手眼标定走点、装配移动 |
+| `servo_joint` | 高频关节伺服 | 视觉伺服 `servo_node` |
+| `servo_cartesian` | 笛卡尔位姿伺服 | 跟踪、悬停 |
+| `compliant_descent` | 柔顺下臂（接触力约束） | 装配接触阶段 |
+| `set_tool` / `switch_tool` | 设置/切换工具坐标系（如 tool1） | 全局工具系锁定 |
+| `home` | 回到初始位姿 | 每个循环开始、异常复位 |
+| `enable` / `clear_fault` | 使能、清故障 | 启动自检、异常恢复 |
+
+**缺哪个能力就在 manifest 的 `capabilities` 里不写哪个**，框架启动时会检查上层要用的能力是否都被支持，
+不支持就明确报错，而不是运行时莫名其妙失败。
+
+## 当前状态（迁移参考）
+
+非夕臂的现有实现分散在这些地方，P1 之后会收敛到 `flexiv/driver/` 下：
+
+- 硬件接口：`src/flexiv_hardware/`（ros2_control 插件，上游官方）
+- bringup：`src/arm_bringup/stack.launch.py` 的 `backend:=real` 分支
+- 轨迹适配：`src/arm_control/arm_control/real_trajectory_adapter.py`
+- 几何 IK 与手眼加载：`src/arm_application/arm_application/geom_ik.py`
+- 软拖拽：`scripts/rdk_drag_bridge.py`
+- 工具系切换：`scripts/rdk_switch_tool.py`

devices/robots/flexiv/manifest.yaml

@@ -0,0 +1,116 @@
+# =============================================================================
+# devices/robots/flexiv/manifest.yaml
+#
+# 非夕机械臂（Flexiv Rizon / AICO）驱动清单。
+# 框架启动时读这个文件，决定加载哪个适配器、校验哪些配置、检查哪些外部物料。
+#
+# 这里【不放现场数值】。SN / IP / 速度 / 悬高一律在 config/site.yaml。
+# =============================================================================
+
+id: flexiv
+label: 非夕 Flexiv Rizon / AICO
+kind: robot
+vendor: flexiv
+version: "RDK 1.9.x（与 flexiv_ros2 humble-v1 v1.9.1 配套）"
+
+description: >
+  非夕七轴力控机械臂。当前项目使用 Rizon4 双臂（SN 尾号 89 / 91）。
+  上层通过 ros2_control + rizon_arm_controller 下发关节轨迹，柔顺下臂走 RDK 力控原语。
+
+# --- 厂商物料放置要求 ------------------------------------------------------
+# 每个条目会在框架启动时被检查；required: true 且文件缺失时直接报错。
+assets:
+  - path: rdk
+    required: true
+    what: Flexiv RDK 源码或安装包
+    format: 厂商原始发布格式，不要转换、不要重新打包
+    naming: 保持厂商原目录名与文件名，一律不要改名
+    where_used: driver 通过此路径加载 RDK
+    notes: >
+      与 flexiv_ros2 humble-v1 配套的是 RDK 1.9.x。仓库外的已编译安装位于
+      ~/flexiv_install（由 scripts/env.sh 与 run_real.sh 注入 LD_LIBRARY_PATH）。
+      离线安装库在 vendor/rdk_libs/。
+
+# --- 适配器 ----------------------------------------------------------------
+driver:
+  package: arm_driver_flexiv
+  executable: flexiv_arm_driver
+  build: colcon
+
+# --- 能力声明 --------------------------------------------------------------
+# 框架上层只会调用这里列出的能力。少写一项，上层用到时会启动即报错。
+capabilities:
+  - get_arm_state
+  - follow_joint_trajectory
+  - set_named_pose
+  - servo_joint
+  - servo_cartesian
+  - compliant_descent
+  - set_tool
+  - switch_tool
+  - home
+  - enable
+  - clear_fault
+  - soft_drag              # 软拖拽，手眼标定走点用
+
+# --- 配置项声明 ------------------------------------------------------------
+# 框架启动时按 site_path 去 config/site.yaml 取值，required 的键缺失即报错。
+# unit 会打印在人读的错误信息里，避免「填了毫米但代码按米」这类问题。
+config_schema:
+  - key: sn
+    site_path: robot.robots[].sn
+    type: str
+    required: true
+    doc: 机械臂完整 SN（如 Rizon4-063989）。必须与示教器上显示的一致。
+
+  - key: ip
+    site_path: robot.robots[].ip
+    type: str
+    required: true
+    doc: 控制柜 IP。同一网段的工控机地址填 pc_ip。
+
+  - key: pc_ip
+    site_path: robot.robots[].pc_ip
+    type: str
+    required: true
+    doc: 工控机在本网段的地址，RDK 白名单用。
+
+  - key: iface
+    site_path: robot.robots[].iface
+    type: str
+    required: true
+    doc: 连接控制柜的网卡名（如 enp4s0）。
+
+  - key: tool_name
+    site_path: robot.tool_name
+    type: str
+    required: false
+    default: ""
+    doc: 示教器 Studio 里的工具坐标系名。留空表示不切换。
+         本项目要求 tool1 全程保持垂直向下且位姿锁定，需在此指定。
+
+  - key: tool_z_extend_m
+    site_path: robot.tool_z_extend_m
+    type: float
+    unit: m
+    required: false
+    default: 0.0
+    doc: >
+      工具坐标系沿 Z 的延长量。用于补偿「夹具 + 夹持物」超出原质心的距离。
+      当前 tool1 质心在未装夹具的平行夹爪末端，装上夹具并夹持通止规后需沿 Z 延长。
+      标定方法见 docs/TOOL_FRAME.md。
+
+  - key: ee_z_m
+    site_path: robot.robots[].servo.ee_z_m
+    type: float
+    unit: m
+    required: true
+    doc: 视觉跟踪锁高 —— 法兰相对基座系的 Z。
+         注意与悬高（相对工具系）区分，两者是不同概念。
+
+  - key: safe_z_m
+    site_path: robot.robots[].servo.safe_z_m
+    type: float
+    unit: m
+    required: true
+    doc: 防撞安全高度。启动归位时先抬到这个高度再水平移动。

devices/robots/flexiv/rdk/README.md

@@ -0,0 +1,53 @@
+# devices/robots/flexiv/rdk/ —— 放置非夕 RDK
+
+## 放什么
+
+Flexiv RDK（Robotic Development Kit）的源码或安装包。
+
+## 格式与命名要求（必须遵守）
+
+| 项 | 要求 | 违反的后果 |
+|----|------|-----------|
+| 格式 | 厂商原始发布格式（`.tar.gz` 需展开，不要留着压缩包） | 驱动加载不到 |
+| 目录名 | 保持厂商原目录名（通常是 `flexiv_rdk`） | CMake 的 include 路径失效 |
+| 文件名 | 一律不改名 | CMake 查找 `libflexiv_rdk.*.a` 时按原名匹配 |
+| 版本 | 在 `../manifest.yaml` 的 `version` 字段记录 | 日后无法排查版本不匹配 |
+| 编译产物 | 不要把 `build/` 提交进 git | 仓库膨胀 |
+
+## 版本必须配对（这是已踩过的坑）
+
+项目里同时存在两个 RDK 版本，**不能混用**：
+
+| 用途 | 需要的 RDK 版本 | 位置 |
+|------|----------------|------|
+| 编译 `flexiv_ros2`（humble-v1，v1.9.1） | **1.9.x** | 已编译安装于 `~/flexiv_install` |
+| 单独跑 RDK Python 脚本（软拖拽、切工具） | 2.1.x | `src/flexiv_rdk`（符号链接到仓库外） |
+
+`flexiv_ros2` 是 humble-v1 版本，它期望的 RDK 是 1.9.x。当前 `src/flexiv_rdk` 指向的是
+**2.1.x**，两者靠 `~/flexiv_install` 里已编译好的 1.9.1 解耦。
+
+离线安装 1.9.1 需要的静态库在 `vendor/rdk_libs/`，由
+`scripts/install_rdk_offline.sh` 校验 sha256 后使用。
+
+## 放好之后怎么让它生效
+
+```bash
+# 1. 若 RDK 未编译，先编译并安装到 ~/flexiv_install
+bash scripts/build_flexiv_rdk.sh
+
+# 2. 重新编译依赖 RDK 的 ROS 包
+source scripts/env.sh
+./scripts/build_all.sh
+
+# 3. 确认选型
+cat devices/registry.yaml     # robots: flexiv
+
+# 4. 实机启动
+bash scripts/run_real.sh --arm 89
+```
+
+## 排查
+
+- `run_real.sh` 会先调 `scripts/rdk_switch_tool.py` 做预检；失败会直接 `exit 1` 并打印原因。
+- 网络不通先跑 `scripts/check_robot_network.sh`。
+- RDK Python 冒烟测试：`scripts/test_rdk_python.sh <SN>`。