主界面一屏要同时看臂、夹爪、相机和触觉，按钮再被拉高就会叠到画面上。相机按原分辨率走回调取最新帧，场景一动不再等红外齐帧把彩色丢掉。模型和相机都留在工位窗口里，启动默认不再弹 RViz。

验收：test_listed_arms 与 test_camera_preview 共 20 项通过。D435 1280×720 发布约 29 帧/秒。

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

docs/ENVIRONMENT.md

@@ -38,16 +38,16 @@
 
 ## 2. 新机器先对齐的路径
 
-下面这些路径被脚本写死为用户 `cc` 的家目录。新机器用**同一个用户名** `cc`（家目录 `/home/cc`）时，后面的命令可以原样复制。
+脚本跟**当前用户的家目录**走，不写死 `/home/cc`。用户名可以不是 `cc`。只支持 Linux。
 
 | 路径 | 谁在用 |
 |------|--------|
-| `/home/cc/anaconda3` | `scripts/run_real.sh`、`scripts/run_mock_demo.sh` 直接 `source` 这个 `conda.sh`。`scripts/env.sh` 用的是 `$HOME/anaconda3`，两边要是同一个目录 |
-| `/home/cc/rdk_py310/bin/python` | `run_real.sh`、`test_rdk_python.sh`、`rdk_switch_tool.sh`、`scripts/lib/real_preflight.py` 的默认 `RDK_PYTHON` |
-| `/home/cc/flexiv_install` | `run_real.sh` 用 `$HOME/flexiv_install`（随用户走） |
-| `/home/cc/ros2` | 工作区。`colcon build` 必须在这条 ASCII 路径下，不要在中文目录里编 |
+| `$HOME/anaconda3` 或 `$HOME/miniconda3` | `scripts/lib/dev_tools.sh`。环境名默认 `ros_flexiv`，可用 `REAL_ENV_NAME` 改 |
+| `$HOME/rdk_py310/bin/python` | 默认的 RDK 解释器。已经在别的目录时，启动前 `export RDK_PYTHON=...` |
+| `$HOME/flexiv_install` | `run_real.sh` / `env.sh` 的 `LD_LIBRARY_PATH` |
+| 仓库目录 | 克隆到哪就从哪启动。`colcon build` 必须在 ASCII 路径下，不要在中文目录里编 |
 
-用户名不是 `cc` 时，至少要改 `scripts/run_real.sh` 里的 conda 路径，并在启动前 `export RDK_PYTHON=$HOME/rdk_py310/bin/python`。否则真机入口会去找 `/home/cc`。
+机械臂、相机、夹爪、网卡和 IP 只写在 `config/site.yaml`。臂号是序列号末两位，换一台臂改 SN，不要改程序里的 89/91。工位窗口的显示器跟当前登录会话（`who` 里的 `:0` / `:1`），不写死某一块屏。
 
 建议磁盘空闲 **40GB 以上**（两个 conda 环境加下载缓存）。
 
@@ -82,7 +82,7 @@ ACTION=="add|bind", SUBSYSTEM=="usb", ATTR{idVendor}=="1bcf", ATTR{idProduct}=="
 
 ## 4. Anaconda
 
-装到 **`$HOME/anaconda3`**（安装器里选 Just Me、路径填这个）。不要装成 `~/miniconda3` 或其他目录：`run_real.sh` 写死了 `/home/cc/anaconda3/etc/profile.d/conda.sh`。
+装到 **`$HOME/anaconda3`**（安装器里选 Just Me、路径填这个）。`$HOME/miniconda3` 也能被 `scripts/lib/dev_tools.sh` 找到。不要装到这两个目录以外的路径，除非自己改 `dev_source_conda`。
 
 本机 conda 版本是 25.11.1。装完新开一个终端：
 

docs/GRIPPER.md

@@ -30,6 +30,8 @@ bash ~/ros2/scripts/run_gripper.sh --arm 91 --cli revolutions 2
 
 PGEA 力/速：`gripper.force_pct`（最低 20）`speed_pct` `open_position` `close_position`。RGI 不要 `auto_init: true`（`robots[]` 里已关）。
 
+平行爪的 `--cli` 在驱动没跑时会先把节点拉起来，再把命令发到 `/gripper/ctrl`。`auto_init` 仍用这一臂在 `site.yaml` 里的值（现场 `false`，不写 `0xA5`，不回零）。串口被别的进程占着时，报的是占用。
+
 ## ROS 节点
 
 单爪：

docs/HANDBOOK.md

@@ -34,7 +34,7 @@
 
 ### 1.3 一次完整任务分几步
 
-代码里用 **stage1 / stage2 / stage3** 三段串起来，一条命令跑完：
+代码里跟踪和对孔串成一条命令。搜孔轻压已取消，`run_all.sh` 不会再进入那一步，也不能用参数打开。旋入是单独的 `run_stage3_search.sh --screw`。
 
 ```
 run_all.sh
@@ -46,18 +46,13 @@ run_all.sh
   │                  YOLO 找工件外框 → Hough 找左右两个孔心 →
   │                  深度 + 内参 + 手眼 → 换算出孔的基座坐标 →
   │                  移动夹爪轴线到目标孔正上方 → 复拍验证 → 锁定
-  │
-  └─ stage3_search   柔顺搜孔：力闭环下的螺旋搜索，直到规的尖端"掉进"孔里，
-                     再十字微扫定心，最后在力限内下压（可选按螺距旋入）
 ```
 
-三段之间**在同一个进程里交接**，所以相机、触觉、手眼 TF 只初始化一次。
-盯日志就能知道跑到哪了 —— 三行关键输出：
+跟踪和对孔在同一个进程里交接。盯日志：
 
 ```
 [pipeline] === stage1_track ===      → 在等跟踪锁定
 [pipeline] === stage2_locate ===     → 在拍照对孔
-[pipeline] === stage3_search ===     → 触面 → ★ 入孔 → 轻压到位
 ```
 
 日常入口（三个终端，**必须同一个 `--arm`**）：
@@ -65,7 +60,7 @@ run_all.sh
 ```bash
 bash ~/ros2/scripts/run_real.sh --arm 89                    # T1 控制栈，一直开着
 bash ~/ros2/scripts/run_camera_d405.sh --arm 89 --preview   # T2 相机预览，一直开着
-bash ~/ros2/scripts/run_all.sh --arm 89                     # T3 三段串联（默认不拧入）
+bash ~/ros2/scripts/run_all.sh --arm 89                     # T3 跟踪 + 对孔（不含搜孔、不含旋入）
 bash ~/ros2/scripts/run_all.sh --arm 89 --init-z 0.35 --hover-z 0.34
 ```
 
@@ -112,8 +107,8 @@ bash ~/ros2/scripts/run_visual_servo_rt.sh --arm 89 --control
 
 | 能力 | 状态 | 怎么自己确认 |
 |------|------|--------------|
-| 三段串联（跟踪 → 对孔 → 搜孔轻压） | ✅ 真机跑通 | `run_all.sh --arm 89` |
-| 按螺距旋入（螺纹规） | ✅ 有参数，`--depth`/`--pitch` 控制 | `run_stage3_search.sh --arm 89 --depth 6 --pitch 1.0` |
+| 跟踪 → 对孔 | ✅ 真机跑通过。搜孔轻压已取消，这条命令不再下压搜孔 | `run_all.sh --arm 89` |
+| 按螺距旋入（螺纹规） | ✅ 单独阶段。不带 `--screw` 的旧搜孔命令会直接拒绝 | `run_stage3_search.sh --arm 89 --screw` |
 | Orisys 双指触觉（法向 + 两路切向） | ⚠️ 能读，但**轴向映射尚未实测确认** | 见 [`TACTILE.md`](TACTILE.md) |
 | Orisys 的深度图 / 力矢量图 | ⚠️ 消息结构与话题已在，真机值待确认 | 同上 |
 | D435 手外相机（一阶段一次性 + S03） | ⚠️ 89 已按 `tool10120938` 重标（24 视角，10-09 旧结果在 `results/backup/`）；S03 粗定位真机未对过 | `handeye/results/89_d435_eye_to_hand.yaml` |
@@ -510,7 +505,7 @@ bash scripts/run_unit_tests.sh -k gauge              # 只跑名字带 gauge 的
 | **89 / 91** | 左臂 / 右臂的现场编号，**各有独立的手眼、相机、夹爪、锁高，禁止混用** |
 | **法兰** | 机械臂末端安装面；手眼 `T_4x4` 仍是相机→法兰。左臂 89 现行按 Studio `tool10120938` 的 TCP 求解，再折回法兰 |
 | **eye-in-hand / eye-to-hand** | 相机装在手上 / 装在手上之外（D405 在手上，D435 在外部） |
-| **stage1/2/3** | 跟踪 / 对孔 / 搜孔，见 1.3 |
+| **stage1/2** | 跟踪 / 对孔，见 1.3。搜孔轻压已取消 |
 | **S03 / S04 / S07 / S08** | 整体装配任务书里的阶段编号（S03 粗定位、S04 跟踪、S07 柔顺下压、S08 夹爪旋转循环）。代码里对应的是 stage1/2/3 的拆分实现，**没有一一对应**，别硬套 |
 | **基线** | 触觉静止时的读数均值。力的语义是"相对基线的增量"，不是绝对牛顿值 |
 | **R1.1 / M1 …** | [`FRAMEWORK_RULES.md`](FRAMEWORK_RULES.md) 里的规则编号，文档和提交信息里直接引用 |

docs/HOLE_DETECT.md

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