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

src/arm_msgs/CMakeLists.txt

@@ -0,0 +1,32 @@
+cmake_minimum_required(VERSION 3.8)
+project(arm_msgs)
+
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+find_package(ament_cmake REQUIRED)
+find_package(rosidl_default_generators REQUIRED)
+find_package(std_msgs REQUIRED)
+find_package(geometry_msgs REQUIRED)
+find_package(builtin_interfaces REQUIRED)
+find_package(sensor_msgs REQUIRED)
+
+rosidl_generate_interfaces(${PROJECT_NAME}
+  "msg/ArmStatus.msg"
+  "msg/JointCommand.msg"
+  "msg/GripperCommand.msg"
+  "msg/GripperStatus.msg"
+  "msg/HoleDetection.msg"
+  "msg/HoleDetections.msg"
+  "msg/TactileStatus.msg"
+  "srv/SetNamedPose.srv"
+  "srv/GetArmState.srv"
+  "srv/GripperExecute.srv"
+  "action/MoveToPose.action"
+  "action/FollowJointTrajectory.action"
+  DEPENDENCIES std_msgs geometry_msgs builtin_interfaces sensor_msgs
+)
+
+ament_export_dependencies(rosidl_default_runtime)
+ament_package()

src/arm_msgs/action/FollowJointTrajectory.action

@@ -0,0 +1,16 @@
+# Simplified joint-space trajectory used by mock / named-pose stack.
+# MoveIt / ros2_control use control_msgs/FollowJointTrajectory; a bridge
+# converts when backend:=moveit or backend:=real.
+string[] joint_names
+float64[] positions             # flattened: num_points * num_joints
+uint32 num_points
+float64[] time_from_start       # length = num_points, seconds
+float64 velocity_scale
+---
+bool success
+string message
+float64[] final_positions
+---
+uint32 current_point
+float64 progress
+string status

src/arm_msgs/action/MoveToPose.action

@@ -0,0 +1,13 @@
+# Cartesian goal for tcp / tool0 (implemented by MoveIt backend)
+geometry_msgs/PoseStamped target_pose
+float64 velocity_scale
+float64 acceleration_scale
+bool avoid_collisions
+---
+bool success
+string message
+float64[] final_joint_positions
+---
+geometry_msgs/PoseStamped current_pose
+float64 progress
+string status

src/arm_msgs/msg/ArmStatus.msg

@@ -0,0 +1,9 @@
+# High-level arm status for monitoring / HMI
+std_msgs/Header header
+string mode                     # idle | moving | error | estop
+bool is_moving
+bool is_homed
+float64[] joint_positions       # rad
+float64[] joint_velocities      # rad/s
+geometry_msgs/PoseStamped ee_pose
+string error_message

src/arm_msgs/msg/GripperCommand.msg

@@ -0,0 +1,16 @@
+std_msgs/Header header
+
+# init|init_full|connect|open|close|stop|move|rotate|rotate_to|rotate_by|rotate_revolutions|home_rotation|set_force|set_speed|set_finger_force|set_finger_speed
+string command
+
+# command=move: 平行夹爪行程 mm；command=rotate/rotate_by: 角度 deg；command=rotate_revolutions: 圈数
+float64 position
+
+# 速度百分比（1~100）
+float64 speed
+
+# 力/力矩百分比（DH 一般 20~100）
+float64 force
+
+bool wait_complete
+float64 timeout

src/arm_msgs/msg/GripperStatus.msg

@@ -0,0 +1,25 @@
+std_msgs/Header header
+
+string name
+string gripper_type      # parallel|rotary
+string state             # IDLE|MOVING|GRIPPING|RELEASING|ERROR
+
+bool connected
+bool initialized
+bool is_moving
+bool is_gripped
+
+# 平行夹爪：当前行程 mm；旋转夹爪：当前旋转角度 deg
+float64 position
+
+# RGI 旋转夹爪额外反馈；平行夹爪为 0
+float64 finger_position_per_mille
+float64 rotation_deg
+
+# DH 原始状态字；未读到为 -1
+int32 gripper_state      # 0 moving, 1 reached, 2 object caught, 3 object dropped
+int32 rotation_state     # RGI: 0 moving, 1 reached, 2 blocking, 3 had been blocked
+
+float64 velocity         # 最近一次命令速度 %
+float64 force            # 最近一次命令力/力矩 %
+string error_msg

src/arm_msgs/msg/HoleDetection.msg

@@ -0,0 +1,6 @@
+float32 u
+float32 v
+float32 radius_px
+float32 confidence
+string label
+int32[] bbox

src/arm_msgs/msg/HoleDetections.msg

@@ -0,0 +1,4 @@
+std_msgs/Header header
+bool ok
+string message
+arm_msgs/HoleDetection[] holes

src/arm_msgs/msg/JointCommand.msg

@@ -0,0 +1,7 @@
+# Single-shot joint command (position or velocity)
+std_msgs/Header header
+string[] joint_names
+float64[] positions
+float64[] velocities
+float64[] accelerations
+float64 time_from_start         # seconds

src/arm_msgs/msg/TactileStatus.msg

@@ -0,0 +1,11 @@
+std_msgs/Header header
+string side
+bool connected
+bool contact
+float32 fnormal
+float32 fshearx
+float32 fsheary
+float32 fps
+float32 centroid_u
+float32 centroid_v
+string error_msg

src/arm_msgs/package.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>arm_msgs</name>
+  <version>0.1.0</version>
+  <description>Custom messages, services and actions for the robotic arm stack.</description>
+  <maintainer email="dev@example.com">arm_dev</maintainer>
+  <license>Apache-2.0</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <buildtool_depend>rosidl_default_generators</buildtool_depend>
+
+  <depend>std_msgs</depend>
+  <depend>geometry_msgs</depend>
+  <depend>builtin_interfaces</depend>
+  <depend>sensor_msgs</depend>
+
+  <exec_depend>rosidl_default_runtime</exec_depend>
+  <member_of_group>rosidl_interface_packages</member_of_group>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

src/arm_msgs/srv/GetArmState.srv

@@ -0,0 +1,6 @@
+---
+bool success
+string mode
+float64[] joint_positions
+geometry_msgs/PoseStamped ee_pose
+string message

src/arm_msgs/srv/GripperExecute.srv

@@ -0,0 +1,5 @@
+arm_msgs/GripperCommand command
+---
+bool success
+string message
+arm_msgs/GripperStatus status

src/arm_msgs/srv/SetNamedPose.srv

@@ -0,0 +1,7 @@
+# Move to a named pose defined in config (home, ready, inspect, pos_left, ...)
+string pose_name
+float64 velocity_scale          # (0, 1], 1 = full speed
+float64 acceleration_scale
+---
+bool success
+string message