仿真夹爪适配器：服务接口对齐真机，开口按正运动学换算成真毫米

为什么
------
应用层只认 arm_msgs/srv/GripperExecute（开口毫米），真机与仿真必须同一套接口。
但 GN01 的 URDF 里 <mimic> 是**线性近似**：直接按线性系数下发 finger_width_joint，
"命令开 20 mm"在 Gazebo 里量出来是 21.75 mm —— 抓不住工件，而且看起来像算法问题。

实测（2026-09-24，Gazebo 内量两指尖间距）：
  线性下发 20 mm → 实际 21.74 mm（偏差 1.74 mm，超 2 mm 抓取容差的前半步）
  走 FK 反解     → 实际 20.00 mm（≤0.5 mm）

怎么改
------
- 新增 sim_gripper_kin.py：解析 URDF 正运动学，算出"主关节值 ↔ 真实开口 mm"的
  单调曲线，反解用二分。曲线非单调/零行程时**主动报错**，不静默退化成线性。
- sim_gripper.py：开口换算全部走该曲线；容差统一改成毫米。
- sim_gripper_adapter.py：反馈改取**从动关节**（见下）；is_gripped 按毫米判定。
- 新增 check_sim_gripper.py：三层验收（服务/开口一致/指尖真实几何行程 + 对称性）。

踩到的坑
--------
- finger_width_joint 挂在无质量的 unused_finger_width_link 上，与手指**没有机械
  连接**：命令到 0.100，它的 /joint_states 恒为 1.4e-08，6 个从动关节才准到
  0.7854。反馈若取它，/gripper/status 会永远报"开口 0 mm"。
- 残留进程会伪造出"代码写错了"的现场：旧 sim_gripper_adapter 与新实例抢话题，
  验收读到"指尖间距 0.03 mm"（真实 127 mm）；孤儿 static_transform_publisher
  用 latched /tf_static 把旧相机外参按在新仿真上。
  → 新增 scripts/lib/sim_procs.sh；run_sim_gz.sh 用 setsid 独立进程组，
    PGID 记进 log_sim/sim.pgid，stop 时整组 kill；启动前预检拒绝带病启动。
- 验收脚本自己也错过两次（把 TF 的米当毫米比 → 127 mm 显示成 0.13 mm；
  用会转动指垫的中点漂移判对称 → 必然位移 16 mm）。判据改成"两侧各走多远"，
  单位只在 _dist_mm 里换算一次。

验证
----
  python3 -m pytest src/arm_sim_gazebo/test/ -q          → 307 passed
  python3 scripts/check_sim_gripper.py                   → 三层全过
     第 2 层：请求/反馈开口最大偏差 < 0.5 mm
     第 3 层：期望行程 vs 实际行程、左右行程差，均 < 1.5 mm
  bash scripts/stop_sim_gz.sh --list                     → 整组列出（含 static tf）

文档
----
- 仿真手册：新增 §4.4（开口 mm 怎么换算）、坑 12（宽度关节不动、
  反馈必须取从动关节）；停止一节改写成进程组语义。
- FRAMEWORK_RULES：新增 R4.11（残留进程会伪造现场）、R4.12（验收判据要挑
  与实现无关的物理量）；R4.9 表补夹爪；清单补 13/14 两条。
- HANDBOOK：新增 §3.4「在仿真里开合夹爪」，补 §4.4 的两条新教训。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/HANDBOOK.md

@@ -170,6 +170,7 @@ D405        YOLO              手眼 T              伺服             ros2_cont
 | 触觉灵敏度 | `site.yaml` → `hole_detect.stage3:` 的 `*_delta` | 看启动日志打印的派生阈值 | [`TACTILE.md`](TACTILE.md) |
 | 相机曝光 / 图幅 / 视场 | `site.yaml` → `cameras:`（真机） | `list_realsense.sh` | [`SITE_CONFIG.md`](SITE_CONFIG.md) |
 | 仿真场景里放什么、放哪 | `devices/sim/gazebo/config/scene.yaml` | `python3 scripts/check_sim_scene.py` | [仿真手册 §4.1](../devices/sim/gazebo/README.md) |
+| 仿真里开合夹爪（开口 mm） | 服务 `/gripper/{open,close,move}`，与真机同一套 | `python3 scripts/check_sim_gripper.py` | [仿真手册 §4.4](../devices/sim/gazebo/README.md) |
 | 仿真相机视场/图幅 | 仿真手册 §4.3，**三处要同时改** | `python3 scripts/check_sim_cameras.py` | 同上 §4.3 |
 | 算法权重（换模型） | `models/<分组>/` + `site.yaml` 的路径 | `scripts/weights.sh list` | [`models/README.md`](../models/README.md) |
 | 接一个新品牌设备 | `devices/<类别>/<品牌>/` + `registry.yaml` 一行 | `ros2 run arm_interfaces device_check` | [`devices/README.md`](../devices/README.md) |
@@ -212,7 +213,25 @@ source scripts/sim_env.sh
 python3 scripts/check_sim_scene.py     # 悬空 / 穿模 / 出界 / 互相嵌入 / 像素几何
 ```
 
-### 3.4 加一个算法权重
+### 3.4 在仿真里开合夹爪
+
+服务名与真机一致，所以脚本两边通用：
+
+```bash
+source scripts/sim_env.sh
+ros2 service call /gripper/move arm_msgs/srv/GripperExecute \
+    "{command: {command: move, position: 20.0}}"   # 开口 20 mm（真的 20 mm）
+ros2 topic echo /gripper/status --once             # 开口 / 是否夹住 / 是否在动
+python3 scripts/check_sim_gripper.py               # ★ 验收：拿两指尖的实际间距说话
+```
+
+`position` 是**开口毫米**，仿真里由 URDF 正运动学反解保证是真的毫米
+（上游的线性 mimic 近似会让"开 20 mm"变成 21.75 mm，抓不住工件 ——
+见[仿真手册 §4.4](../devices/sim/gazebo/README.md)）。
+
+如果启动日志说行程是 **99.93 mm**：那是对的，是实测值，不是名义的 100.0。
+
+### 3.5 加一个算法权重
 
 放进去 → 打标签 → 改路径 → 体检。TensorRT 转换也在这条链上：
 
@@ -225,7 +244,7 @@ bash scripts/weights.sh doctor --check-engines          # 查版本不匹配这
 布局是 `models/<分组>/<模型名>.{pt,onnx,engine}` + 旁挂 `<模型名>.labels.yaml`。
 **二进制不进 git**，标签文件进。规则见 [`models/README.md`](../models/README.md)。
 
-### 3.5 接一个新品牌设备
+### 3.6 接一个新品牌设备
 
 四步（完整说明在 [`devices/README.md`](../devices/README.md)，这里只给顺序）：
 
@@ -248,13 +267,13 @@ ros2 run arm_interfaces device_check --list-brands      # 看每类现在有哪
 > `required: true` 的配置键在 `site.yaml` 里有没有值。
 > 任何一项不满足**立即报错并指出该去哪个文件补什么**，不静默降级。
 
-### 3.6 改相机分辨率（最容易漏改）
+### 3.7 改相机分辨率（最容易漏改）
 
 真机改 `site.yaml` 就行。**仿真要改三处**，因为像素门槛是绑在图幅上的 ——
 改完不算清楚，孔检测在仿真里会"根本不可能通过"，而看起来像算法不行。
 详见[仿真手册 §4.3](../devices/sim/gazebo/README.md)。
 
-### 3.6.1 换一台机械臂（最容易漏改，而且很难查）
+### 3.7.1 换一台机械臂（最容易漏改，而且很难查）
 
 `site.yaml` 里写的是**哪台臂**，但有一批一级配置文件里写死了**臂的关节名**
 （Flexiv 官方把 SN 编进关节名：`Rizon4-063989_joint1`）。这些文件必须跟着改：
@@ -284,7 +303,7 @@ bash scripts/build.sh               # 4. 让 install/ 同步
 > 排查提示：`ROBOT_SN` / `ROBOT_ARM` 环境变量会**覆盖** `site.yaml` 的 `robot.sn`。
 > "明明改了配置却没生效"时先 `echo $ROBOT_SN`，或看 `--list` 打印的"来源"。
 
-### 3.7 改完必须做的一件事
+### 3.8 改完必须做的一件事
 
 **问自己：我故意弄坏它，哪个检查会红？**
 
@@ -324,6 +343,7 @@ python3 scripts/check_arm_prefixes.py                # 含臂名的配置是否
 # —— 仿真验收（★ 必做，别靠肉眼）——
 python3 scripts/check_sim_cameras.py                 # 深度反投影命中已知平面才算过
 python3 scripts/check_sim_scene.py                   # 摆放 / 像素门槛漂移 / 成像几何 / 可见性
+python3 scripts/check_sim_gripper.py                 # 夹爪：命令开口 mm == 两指实际张开 mm
 
 # —— 只改文字时自证 ——
 python3 scripts/check_text_only.py
@@ -372,9 +392,19 @@ python3 -m pytest src/arm_sim_gazebo/test -q
   于是"没检查"被伪装成"通过"（R5.3、R5.4）。
 - `bash -n` 说脚本语法 OK，脚本却**跑不起来** —— CRLF 行尾会漏报，
   只有真跑 `--help` 才暴露（R6.6）。
+- 验收脚本自己**算错了单位** —— `check_sim_gripper.py` 把 TF 的"米"当成"毫米"
+  去比阈值，于是 127 mm 被显示成 0.13 mm，**恰好看起来像夹爪没张开**，
+  让人跑去查夹爪代码（R4.12）。
+- 上一轮的**残留进程**伪造出"代码写错了"的现场 —— 两个同名适配器抢话题/服务，
+  残留的 `static_transform_publisher` 把旧外参按在新仿真上，读数全是乱的（R4.11）。
 
-**所以**：写完校验，先故意弄坏被校验的对象，确认检查真的会红；
-负向测试和正向测试一样重要（R5.2）。
+**所以**：
+
+1. 写完校验，先故意弄坏被校验的对象，确认检查真的会红（负向测试和正向测试
+   一样重要，R5.2）；
+2. 判据要挑**与被测实现无关的物理量**，单位只在一处换算；
+3. 结论不对时，先怀疑**判据和环境**，再怀疑被测对象 —— 上面后两条都是
+   "先怀疑了代码，结果是自己错"（R4.12）。
 
 ---
 
@@ -407,8 +437,8 @@ python3 -m pytest src/arm_sim_gazebo/test -q
 | 校验代码永远通过 | `sdformat` 用 `__default__` / `__default_topic__` 假值填了缺失字段 | 仿真手册坑 9 |
 | 脚本报 `$'\r': 未找到命令` | 脚本是 CRLF 行尾 | R6.6 |
 | 改了参数不生效 | 改的是包内 yaml，被 `site.yaml` 覆盖了 | 3.2 |
-| MoveIt 说规划成功、机械臂不动 | SRDF / controllers 里还是**旧臂**的关节名 | 3.6.1、R1.1.1 |
-| 控制器报 `Joint 'Rizon4-xxxxxx_joint1' not found` | 换了臂但一级配置没跟着改（或改了两处漏一处） | 3.6.1 |
+| MoveIt 说规划成功、机械臂不动 | SRDF / controllers 里还是**旧臂**的关节名 | 3.7.1、R1.1.1 |
+| 控制器报 `Joint 'Rizon4-xxxxxx_joint1' not found` | 换了臂但一级配置没跟着改（或改了两处漏一处） | 3.7.1 |
 | 仿真镜头位置不对、只看得见地面 | 相机 `rpy` 复合顺序 | 仿真手册坑 5 |
 | 脚本说"已停止"，进程还在 | 进程模式表漏项 | R4.10 |
 | 孔检测在仿真里怎么都不过 | 图幅与真机不同，像素门槛失效 | 仿真手册 §4.3 |