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

@@ -0,0 +1,62 @@
+# devices/ —— 设备与外部文件总目录
+
+这个目录存在的唯一目的：**把「换个硬件」从改代码变成改配置**。
+
+## 设计原则（务必先读）
+
+### 1. 选型与数值分离
+
+| 关注点 | 放在哪 | 谁改 |
+|--------|--------|------|
+| **用哪个品牌的哪个驱动** | `devices/registry.yaml` | 集成工程师（很少改） |
+| **设备号 / 速度 / 阈值 / 悬高** | `config/site.yaml` | 现场操作人员（经常改） |
+
+**`devices/` 下不允许出现任何现场数值。** 数值只有 `config/site.yaml` 一个来源。
+这样可以避免现在这种「同一个值三处定义、改了不生效」的问题。
+
+### 2. 目录约定
+
+```
+devices/
+├── registry.yaml        # 选型开关（唯一入口）
+├── robots/              # 机械臂：RDK + 适配器
+├── grippers/            # 夹爪
+├── sensors/
+│   └── orisys/          # ★ 视触觉核心，长期迭代，单独占一个大文件夹
+├── cameras/             # 相机
+└── sim/                 # 仿真平台（当前 Gazebo）
+```
+
+每个品牌一个子目录，子目录内固定结构：
+
+```
+<类别>/<品牌>/
+├── manifest.yaml        # 我是谁 / 支持什么能力 / 需要哪些配置 / 外部文件放哪
+├── driver/              # 适配器（把厂商 API 翻译成框架接口）
+└── <厂商物料>/          # 如 rdk/、sdk/，原样放置，不要改名
+```
+
+### 3. 一个新品牌要接进来，只需要四步
+
+1. **丢物料**：把厂商的 RDK / SDK / 驱动包放进 `<类别>/<品牌>/` 下对应文件夹
+   （格式和命名要求写在该类别的 `README.md` 里，**必须按它要求放**）。
+2. **填 manifest**：复制同类别的 `manifest.yaml` 改四个字段（id / label / driver.package / config_schema）。
+3. **写适配器**：在 `driver/` 下实现框架的接口契约（见 `src/arm_interfaces/`）。
+   这一步的工作量取决于厂商 —— 如果厂商本来就提供符合契约的 ROS 2 驱动，这一步几乎为零。
+4. **改一行选型**：把 `registry.yaml` 里对应类别的值改成新品牌 id。
+
+> **诚实说明**：第 3 步无法完全避免。Flexiv 的 RDK 是 C++/Python 库而不是 ROS 2 驱动，
+> 所以它外面永远需要一层薄适配器。框架能做的是把这层适配器写到最薄（只做 API 翻译，
+> 不含任何业务逻辑），而不是让你零代码接入。
+
+### 4. 启动时的校验
+
+框架启动会依次读 `registry.yaml` → 各 `manifest.yaml` → `config/site.yaml`，
+校验三件事：
+
+- 选中的品牌目录存在，且 `manifest.yaml` 可解析；
+- manifest 里 `assets` 声明的必需物料文件都在；
+- `config_schema` 里标记 `required: true` 的配置键，在 `site.yaml` 里都有值。
+
+任何一项不满足**立即报错并明确指出该去哪个文件补什么**，不允许静默降级。
+这是替代现在「`run_handeye.sh` 传了 5 个节点没声明的参数、调参静默失效」那类问题的机制。