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

@@ -0,0 +1,95 @@
+# devices/sim/gazebo/ —— Gazebo 仿真平台
+
+## 先读这段：当前仿真是假的
+
+**现在项目里的「仿真」并不是 Gazebo。** 实际情况是：
+
+- `src/arm_description/urdf/arm.gazebo.xacro` 是零引用的死文件；
+- `arm_bringup/stack.launch.py` 的 `isaac` 分支只有一行日志，没有任何实际动作；
+- `run_sim.sh` 走的是 `sim.launch.py`，底层是 **mock 驱动**（`mock_arm_driver.py`），
+  即用假数据模拟机器人状态，不是物理仿真；
+- Gazebo 从未真正接线。
+
+所以这份文档分两部分：**第一部分是怎么把 Gazebo 真正跑起来**（当前必须做的前置工作），
+**第二部分才是日常怎么用**。不要跳过第一部分。
+
+---
+
+## 第一部分：把 Gazebo 真正接起来（前置工作）
+
+要让 Gazebo 跑起来，缺的是这几块，按顺序补齐：
+
+### 1. URDF 加 Gazebo 标签
+
+现有 `arm_description/urdf/arm.gazebo.xacro` 是死文件，需要重写。每个 link 必须补：
+
+```xml
+<!-- 视觉碰撞体 -->
+<gazebo reference="${prefix}link1">
+  <material>Gazebo/Grey</material>
+</gazebo>
+```
+
+并在 `arm.ros2_control.xacro` 里把 `ros2_control` 标签的 hardware 插件从
+`flexiv_hardware/FlexivHardware` 换成 `gazebo_ros2_control/GazeboSystem`。
+
+### 2. 关节传动与控制器
+
+Gazebo 需要 `transmission` 标签把关节映射到 `ros2_control`。控制器配置可以直接复用
+`arm_control/config/controllers.yaml` 里的 `rizon_arm_controller`，只需把关节名前缀
+从真实 SN（如 `Rizon4-063989_`）换成仿真专用的前缀（如 `sim_`）。
+
+### 3. 传感器插件
+
+| 仿真对象 | 插件 | 对应真实设备 |
+|----------|------|--------------|
+| 腕部相机 | `libgazebo_ros_camera.so` | D405 |
+| 手外相机 | `libgazebo_ros_camera.so` | D435 |
+| 深度 | `libgazebo_ros_depth_camera.so` | 对齐深度流 |
+| 触觉力 | **需要自己写插件** | Orisys |
+
+**最关键的一条：Orisys 视触觉没有现成的 Gazebo 插件。**
+3 路切向力 + 1 路法向力 + 深度图 + 力矢量图 这套数据需要自定义 Gazebo 插件来模拟。
+在它做出来之前，仿真里**无法验证通止规装配的力控部分**（S07 接触、S08 拧紧判定）。
+建议的自定义插件做法：订阅 Gazebo 的接触传感器数据，按接触深度和相对滑动速度合成
+出一组「类触觉」读数，再按真实传感器的量纲（任意单位增量）发布到同样的内部话题上。
+
+### 4. 工件与通止规模型
+
+需要给工件（含 k0 中心孔、k1/k2 螺纹孔）和通止规建简化网格，并保证：
+
+- 工件的 k0/k1/k2 三个点在模型坐标系里的位置与实际一致 —— 否则推理出的坐标映射到仿真里会对不上；
+- 螺纹孔要能表达「拧入」的几何阻力，否则 S08 的力反馈无法触发。
+
+---
+
+## 第二部分：日常怎么用
+
+### 放置格式与命名要求
+
+| 类型 | 放哪 | 格式 | 命名要求 |
+|------|------|------|----------|
+| 世界文件 | `worlds/` | `.world` 或 `.sdf` | `<场景名>.world`，如 `assembly.world` |
+| 机器人模型 | `urdf/` | `.urdf` / `.xacro` | 必须以 `sim_` 为关节前缀，与真实臂区分 |
+| 工件/夹具网格 | `models/<模型名>/` | `<模型名>.sdf` + `meshes/` | **模型名必须与推理用的类别名一致**，如 `workpiece` |
+| 传感器插件 | `sensor_plugins/` | `.so` 源码 + `CMakeLists.txt` | 插件类名以 `Orisys` 开头 |
+| 网格文件 | `models/<模型名>/meshes/` | `.stl` / `.dae` | 单位必须是米。用毫米建模的必须先缩放到米 |
+
+### 导入一个新场景
+
+1. 把 `.world` 放进 `worlds/`，网格放进 `models/<模型名>/`
+2. 改 `config/site.yaml` 的 `sim.world` 指向该文件
+3. 改 `devices/registry.yaml` 的 `sim: gazebo`（通常已是）
+4. 启动 `scripts/run_sim.sh`
+
+### 修改哪个配置才会生效
+
+| 想改什么 | 改哪里 |
+|----------|--------|
+| 用哪个场景 | `site.yaml` → `sim.world` |
+| 仿真是否启用物理 | `site.yaml` → `sim.physics_enable` |
+| 仿真里的悬高/速度 | **复用真实的那套参数**（`servo.*` / `hole_detect.stage2.*`），不要另建一套，否则仿真调好的值搬到真机不生效 |
+| 关节前缀 | `site.yaml` → `sim.joint_prefix`（默认 `sim_`） |
+
+> **设计约束**：仿真与真机必须共用同一套 `site.yaml` 参数。任何「仿真专用参数」都是未来
+> 仿真调参搬到真机失效的隐患。只允许物理引擎本身的参数（如重力、步长）放在 `sim.*` 下。

devices/sim/gazebo/manifest.yaml

@@ -0,0 +1,91 @@
+# =============================================================================
+# devices/sim/gazebo/manifest.yaml
+#
+# Gazebo 仿真平台清单。
+#
+# 重要：本项目的 Gazebo 目前【尚未接线】。详见本目录 README.md。
+# 这份清单声明的是「接线完成之后」应有的配置项，并把 world 设为非必填，
+# 这样在仿真还没搭建好时不会阻塞 device_check。
+# =============================================================================
+
+id: gazebo
+label: Gazebo 仿真
+kind: sim
+vendor: openrobotics
+version: "待填 —— 接线后记录 Gazebo 版本"
+
+description: >
+  物理仿真平台。当前项目的「仿真」实际是 mock 驱动（假数据），Gazebo 尚未接线：
+  arm.gazebo.xacro 零引用、stack.launch.py 的 isaac 分支只有日志、没有 world 文件。
+  接线步骤见本目录 README.md 的第一部分。
+  注意：Orisys 视触觉没有现成 Gazebo 插件，自定义插件做出来之前，
+  仿真里无法验证通止规装配的 S07 接触与 S08 拧紧力判据。
+
+# --- 物料放置要求 ----------------------------------------------------------
+assets:
+  - path: worlds
+    required: false
+    what: Gazebo 世界文件（.world / .sdf）
+    format: Gazebo 原生格式
+    naming: 场景名.world，如 assembly.world
+    where_used: 由 site.yaml 的 sim.world 指向
+
+  - path: models
+    required: false
+    what: 工件 / 夹具 / 通止规模型
+    format: 每个模型一个子目录，内含 <模型名>.sdf 与 meshes/
+    naming: >
+      模型名必须与推理用的类别名一致（如 workpiece），否则仿真里算出的坐标
+      与推理结果对不上。网格单位必须是米，用毫米建模的必须先缩放。
+    where_used: Gazebo 场景加载
+
+  - path: urdf
+    required: false
+    what: 仿真版机器人描述
+    format: .urdf / .xacro，需含 gazebo 与 ros2_control 标签
+    naming: 关节前缀必须以 sim_ 开头，与真实臂（Rizon4-xxxxxx_）区分
+    where_used: 仿真机器人加载
+
+  - path: sensor_plugins
+    required: false
+    what: 传感器插件（含 Orisys 触觉自定义插件）
+    format: 插件源码 + CMakeLists.txt
+    naming: 插件类名以 Orisys 开头
+    where_used: 仿真传感器数据发布
+
+# --- 适配器 ----------------------------------------------------------------
+driver:
+  package: arm_sim_gazebo
+  executable: gazebo_sim_launcher
+  build: colcon
+  notes: >
+    当前尚未实现。接线前 run_sim.sh 走的是 arm_bringup 的 mock 驱动路径。
+
+# --- 配置项声明 ------------------------------------------------------------
+# 设计约束：仿真与真机共用同一套 site.yaml 参数（servo.* / hole_detect.stage2.*），
+# 避免「仿真调好的值搬到真机不生效」。只有物理引擎自身的参数放在 sim.* 下。
+config_schema:
+  - key: world
+    site_path: sim.world
+    type: str
+    required: false
+    default: ""
+    doc: >
+      仿真世界文件路径。留空表示使用 Gazebo 默认空场景。
+      Gazebo 接线完成后填真实路径，如 devices/sim/gazebo/worlds/assembly.world。
+
+  - key: physics_enable
+    site_path: sim.physics_enable
+    type: bool
+    required: false
+    default: true
+    doc: 是否启用物理引擎。关闭可用于纯运动学验证。
+
+  - key: joint_prefix
+    site_path: sim.joint_prefix
+    type: str
+    required: false
+    default: sim_
+    doc: >
+      仿真关节名前缀。必须与真实臂的前缀（Rizon4-xxxxxx_）不同，
+      否则仿真与真机的 TF 会互相污染。