贴面后不再抬回悬高；MoveL 切回关节后不再把整段位移当前进速度。

搜孔开局会抬到悬高再落回 hole_hover_z_m，螺纹还没咬合臂就离开孔口。没有接触传感器，到位只认 final_gap 算出的法兰高度，贴面后停在这个 Z。09:25 厂家 MoveL 切回 NRT_JOINT_POSITION 的第一拍把整段关节差算成 1.686 rad/s，前瞻再推 0.07 rad，光心从 5 mm 冲到 276 mm 后急停。切回后钉住结束瞬间的关节角并清零速度，JTC 还指着出发前的关节时不放行。

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

docs/HOLE_DETECT.md

@@ -57,7 +57,8 @@ hole_detect:
 
 ## 三阶段串联（推荐日常入口）
 
-一条命令跑完：**视觉跟踪锁定 → 拍照对孔**。搜孔轻压已取消，这条命令不再下压，也不能用参数重新打开。旋入是后面的单独命令。
+一条命令跑完：**视觉跟踪锁定 → 拍照对孔 → 搜孔并轻轻按压**。默认**不拧入**
+（拧入是后面单独阶段）。三个阶段在同一个节点里交接，相机 / 触觉 / 手眼 TF 只起一次。
 
 ```bash
 # 终端 1 —— 控制栈（一直开着）
@@ -66,12 +67,12 @@ bash ~/ros2/scripts/run_real.sh --arm 89
 # 终端 2 —— 相机预览（一直开着，看跟踪画面）
 bash ~/ros2/scripts/run_camera_d405.sh --arm 89 --preview
 
-# 终端 3 —— 跟踪 + 对孔（到这里停，不搜孔）
-bash ~/ros2/scripts/run_all.sh --arm 89                  # 跟踪 + 对孔
+# 终端 3 —— 串联（搜到孔后轻压保持，不拧）
+bash ~/ros2/scripts/run_all.sh --arm 89                  # 跟踪 + 对孔 + 搜孔轻压
 bash ~/ros2/scripts/run_all.sh --arm 89 --hole k2        # 换 k2
 bash ~/ros2/scripts/run_all.sh --arm 89 --skip-stage1    # 臂已在工件上方，跳过跟踪
-# 旋入不写在这条命令里：
-bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --screw
+# 若这一次就要拧入（一般留给后续阶段）：
+bash ~/ros2/scripts/run_all.sh --arm 89 --depth 6 --pitch 1.0
 ```
 
 `run_pipeline.sh` 是 `run_all.sh` 的别名。
@@ -84,9 +85,9 @@ bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --screw
 1. `[pipeline] === stage1_track ===` → 等跟踪锁定
 2. `一阶段已锁定 — 停跟踪、钉住当前关节，直接进二阶段`
 3. `[pipeline] === stage2_locate ===` → 降到孔悬停高，拍照对准
-对孔结束后臂停在当前高度。搜孔轻压不再接着跑。
+4. `[pipeline] === stage3_search ===` → `触面` → `★ 入孔` → `轻压到位`（不拧入）
 
-急停：终端 3 Ctrl-C。失败时臂保持当前位姿，看
+急停：终端 3 Ctrl-C。搜孔中会先抬 5mm。失败时臂保持当前位姿，看
 `/tmp/pipeline_stage1.log`、`/tmp/stage2_result.json`、`/tmp/stage3_result.json`。
 
 高度接口：`robots[89].servo.ee_z_m`（跟踪锁高）、
@@ -148,10 +149,7 @@ bash ~/ros2/scripts/run_all.sh --arm 89 --final-gap 8            # 锁 XY，规
 | `/stage2/result` | `std_msgs/String` JSON：k1/k2 基座坐标、残差、悬停高 |
 | `/stage2/overlay` | `sensor_msgs/Image` 标注图（同时落盘 /tmp/stage2_overlay.png） |
 
-## 旋转装配（原三阶段节点；搜孔轻压入口已取消）
-
-不带 `--screw` 时 `run_stage3_search.sh` 直接退出，不会触面，也不会螺旋搜孔。
-下面是这个节点在旋入时仍会走的力控步骤，不是一条还能单独打开的搜孔命令。
+## 三阶段柔顺搜孔（stage3，Orisys 触觉 + 力闭环螺旋）
 
 前置：二阶段刚跑完（臂悬停在目标孔上方、垂直朝下、夹持通止规）。流程：
 
@@ -169,9 +167,12 @@ bash ~/ros2/scripts/run_all.sh --arm 89 --final-gap 8            # 锁 XY，规
 7. **hold** — 锁定关节，发布结果
 
 ```bash
-# 前置：T1 run_real.sh --arm 89；对孔已完成（臂保持不动）
-# 不带 --screw 会直接退出，不会搜孔。
-bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --screw
+# 前置：T1 run_real.sh --arm 89；二阶段已完成（臂保持不动）
+bash ~/ros2/scripts/run_stage3_search.sh --arm 89                 # 搜孔+落座
+bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --depth 0      # 只搜孔定心，不插入
+bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --depth 6 --pitch 1.0  # M6 螺纹规旋入
+bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --r-max 5      # 临时改搜索半径
+bash ~/ros2/scripts/run_stage3_search.sh --arm 89 --resnap       # 搜前用 D405 复拍对准一次
 ```
 
 **力阈值是「相对静止均值的增量」，不用标定牛顿**：Orisys 读数是形变任意单位且