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

@@ -0,0 +1,52 @@
+# devices/grippers/ —— 夹爪
+
+## 厂商物料放置要求
+
+| 项 | 要求 |
+|----|------|
+| 格式 | 厂商原始发布的驱动/SDK/协议文档，不要转换 |
+| 命名 | 保持原文件名。若厂商只提供 PDF 协议手册，把它放进来即可（适配器按手册实现） |
+| 通讯参数 | **不要写在这里**。串口、波特率、从站号、行程全部在 `config/site.yaml` |
+| 生效 | 放好物料 → 改 `devices/registry.yaml` 选型 → 改 `site.yaml` 里的串口与行程 → 重启 `scripts/run_gripper.sh` |
+
+## 目录结构
+
+```
+grippers/
+├── README.md
+├── dh_pgea/                     # 大寰（当前在用）
+│   ├── manifest.yaml
+│   ├── protocol/                # 厂商协议手册 / 寄存器表
+│   └── driver/
+└── <新品牌>/
+```
+
+## 适配器必须实现的接口契约
+
+夹爪的接口刻意做成和机械臂对称 —— 上层只调接口，不关心是哪个品牌、走 Modbus 还是走 RDK。
+
+| 能力 | 用途 |
+|------|------|
+| `open` | 张开 |
+| `close` | 夹紧（可带力/速度参数） |
+| `move` | 移动到指定开度 |
+| `rotate` | 旋转到指定角度（旋转爪） |
+| `get_status` | 读开度、力、是否夹持到位 |
+
+**关键设计：`rotate` 与 `open/close` 解耦。** 通止规装配的 S08 循环是
+「转 180° → 松爪 → 快回转 → 夹紧」四步反复，这四步必须是四个独立可调用的原语，
+不能封装成一个「拧螺丝」复合动作 —— 否则中途掉件时无法精确恢复。
+
+## 当前状态（迁移参考）
+
+大寰现有实现有两套互不复用的 Modbus 栈，P1 之后会合并到 `dh_pgea/driver/` 下：
+
+| 文件 | 内容 | 处置 |
+|------|------|------|
+| `src/arm_application/arm_application/dh_pgea.py` | PGEA Modbus 客户端 + 自带 CRC 表 + CLI | 保留，收敛为驱动 |
+| `src/arm_application/arm_application/dh_official.py` | 另一份寄存器级客户端（含 RGI 旋转寄存器） | 合并进来，消除重复 |
+| `src/arm_application/arm_application/dual_gripper.py` | PGEA/RGI 统一抽象 | 改为调用新驱动接口 |
+| `src/arm_application/arm_application/dh_pgea_node.py` | ROS 节点封装 | 改为通用夹爪节点的品牌无关实现 |
+
+**注意**：`site.yaml` 里 `gripper.backend: rdk` 这条路径已被 `run_gripper.sh` 明确拒绝，
+`scripts/rdk_gripper.py` 是孤儿脚本。这条「走控制器 RS485」的分支在 P2 会被清理。

devices/grippers/dh_pgea/manifest.yaml

@@ -0,0 +1,135 @@
+# =============================================================================
+# devices/grippers/dh_pgea/manifest.yaml
+#
+# 大寰（DH）夹爪驱动清单。覆盖两种型号：
+#   PGEA —— 平行夹爪（左臂 89 使用）
+#   RGI  —— 旋转夹爪（右臂 91 使用）
+#
+# 这里【不放现场数值】。串口 / 波特率 / 从站号 / 行程一律在 config/site.yaml。
+# =============================================================================
+
+id: dh_pgea
+label: 大寰 PGEA 平行爪 / RGI 旋转爪
+kind: gripper
+vendor: dh
+version: "Modbus RTU（工控机 USB-RS485 直连）"
+
+# 从哪里读出「当前用哪个型号」。值是 config_schema 里的 field key。
+# RGI 型号会在此基础上叠加 rotate 能力。
+model_selector: model
+
+description: >
+  大寰夹爪。PGEA 提供开合，RGI 在开合之外提供绕轴旋转。
+  通讯走工控机 USB 转 RS485，不经过机械臂控制器。
+
+# --- 厂商物料放置要求 ------------------------------------------------------
+assets:
+  - path: protocol
+    required: false
+    what: 大寰 Modbus 协议手册与寄存器表
+    format: 厂商原始 PDF / 文档
+    naming: 保持原文件名
+    where_used: 适配器实现寄存器读写时的依据
+    notes: >
+      寄存器表已固化进驱动代码（见 driver/）。此目录只作为排查时的对照资料，
+      缺失不影响运行。
+
+# --- 适配器 ----------------------------------------------------------------
+driver:
+  package: arm_driver_dh_gripper
+  executable: dh_gripper_driver
+  build: colcon
+
+# --- 能力声明 --------------------------------------------------------------
+capabilities:
+  - open
+  - close
+  - move
+  - get_status
+
+# RGI 型号额外支持旋转。框架按 manifest 的型号分支决定是否暴露 rotate。
+models:
+  - id: PGEA-100-20-W
+    label: PGEA 平行爪（左臂）
+    capabilities: [open, close, move, get_status]
+    stroke_mm: 20.0
+
+  - id: RGI-100-30-O-S-M1
+    label: RGI 旋转爪（右臂）
+    capabilities: [open, close, move, rotate, get_status]
+    stroke_mm: 30.0
+    notes: >
+      rotate 是通止规装配 S08 循环的核心原语，必须可独立调用且可随时中止。
+      单次转角默认 180°（配置项 system.screw_step_deg），因为不确定基于工具系
+      能转多少度是极限。
+
+# --- 配置项声明 ------------------------------------------------------------
+config_schema:
+  - key: model
+    site_path: robot.robots[].gripper.model
+    type: str
+    required: true
+    doc: >
+      当前使用的夹爪型号。必须与上面 models 列表里的某个 id 一致。
+      型号决定是否具备 rotate 能力（PGEA 没有，RGI 有）。
+
+  - key: port
+    site_path: robot.robots[].gripper.port
+    type: str
+    required: true
+    doc: 串口设备路径（如 /dev/ttyUSB0）。建议用 /dev/serial/by-id/ 下的稳定路径，
+         因为 ttyUSB 编号会随插拔漂移。
+
+  - key: baud
+    site_path: gripper.baud
+    type: int
+    required: false
+    default: 115200
+    doc: 波特率。
+
+  - key: slave_id
+    site_path: gripper.slave_id
+    type: int
+    required: false
+    default: 1
+    doc: Modbus 从站号。
+
+  - key: stroke_mm
+    site_path: robot.robots[].gripper.stroke_mm
+    type: float
+    unit: mm
+    required: true
+    doc: 该爪的总行程。用于把 0–1000‰ 开度换算成毫米。
+
+  - key: force_pct
+    site_path: gripper.force_pct
+    type: int
+    unit: '%'
+    required: false
+    default: 20
+    doc: 夹紧力百分比。低于 20 会被硬件钳位到 20。
+
+  - key: speed_pct
+    site_path: gripper.speed_pct
+    type: int
+    unit: '%'
+    required: false
+    default: 50
+    doc: 动作速度百分比。
+
+  - key: open_position
+    site_path: gripper.open_position
+    type: int
+    unit: 千分比
+    required: false
+    default: 1000
+    doc: 「张开」对应的开度。1000 = 全开。
+
+  - key: close_position
+    site_path: gripper.close_position
+    type: int
+    unit: 千分比
+    required: false
+    default: 0
+    doc: 「夹紧」对应的开度。0 = 全合。
+         注意：通止规是异形件，全合可能压不到，实际夹紧位需要按件标定后填这里。

devices/grippers/dh_pgea/protocol/README.md

@@ -0,0 +1,31 @@
+# devices/grippers/dh_pgea/protocol/ —— 大寰 Modbus 协议资料
+
+## 放什么
+
+大寰（DH）夹爪的 Modbus RTU 协议手册、寄存器表、型号规格书。
+
+## 格式与命名要求
+
+| 项 | 要求 |
+|----|------|
+| 格式 | 厂商原始 PDF / 文档，不要转换 |
+| 命名 | 保持原文件名，或改为 `<型号>_<文档类型>.pdf`，如 `PGEA-100-20-W_寄存器表.pdf` |
+| 是否必需 | **不必需**。寄存器表已固化进驱动代码，此目录仅供人工排查时对照 |
+
+## 为什么放这里
+
+驱动里硬编码了寄存器地址与 CRC 表。当现场出现「某个动作没反应」时，
+需要拿手册逐条核对寄存器定义与从站号，所以把手册放在驱动旁边最方便。
+
+## 已知的两处不一致（迁移时要处理）
+
+1. 现在代码里有**两套独立的 Modbus 实现**，各自定义了一份寄存器常量：
+   - `src/arm_application/arm_application/dh_pgea.py`（PGEA，自带 CRC 表）
+   - `src/arm_application/arm_application/dh_official.py`（含 RGI 旋转寄存器）
+
+   两份功能重叠，P1 之后合并成一份。
+
+2. `site.yaml` 里 `gripper.backend: rdk` 这条「走机械臂控制器 RS485」的分支
+   已被 `run_gripper.sh` 明确拒绝，对应的 `scripts/rdk_gripper.py` 是孤儿脚本。
+   如果你其实需要走控制器 RS485（而不是工控机 USB），请明确告知 ——
+   这会影响驱动是挂在 `devices/grippers/` 还是 `devices/robots/flexiv/` 下。