把当前控制栈收成一份可克隆的源码：腕部看不见时用顶视一次定到基座，二阶段对孔和手外标定跟着进同一份树。

现场 site.yaml、权重和编译产物仍不入库；模板只留占位符。

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

docs/HOLE_DETECT.md

@@ -99,15 +99,26 @@ bash ~/ros2/scripts/run_all.sh --arm 89 --depth 6 --pitch 1.0
 ## 二阶段一次性拍照定位（stage2，与一阶段跟踪分开跑）
 
 先悬停垂直朝下 → 拍一张照 → `detect_best_1.onnx` 框工件 → Hough 解 k1/k2 孔心 →
-深度（孔外工作面中值）+ 内参 + 手眼换算基座坐标 → 移动夹爪/通止规轴线到目标孔正上方 →
+深度（孔外工作面中值）+ 内参 + 手眼换算基座坐标 → 移动**规尖**到目标孔正上方 →
 复拍验证（≤`align_max_iters` 次，收敛判据 `align_tol_m`）→ 锁定保持。
 
+> **对的是"规尖"，不是"法兰轴线"**（2026-10-08 定稿）。通止规夹在爪里，相对法兰轴线
+> 可以整体偏出若干毫米；旧写法把**法兰**对到孔上，规尖就偏着压在孔沿上，轻降一压
+> 腕力蹦到 63N。现在每一帧同时解「规尖基座 XY」和「孔基座 XY」——两者走同一条手眼
+> 链，链路误差与装夹变动一起抵消。规尖偏移是**刚体量**，量准一份（`tip_calib_n` 拍
+> 一致）就冻结。
+> 真机验证（arm 89，独立重测那一帧）：规尖到 k1 **0.34mm**、到 k2 61.15mm、
+> 反投影工具长 222mm（与 site 的 223mm 一致），偏移冻结值 (2.6, −1.0)mm。
+> 相关开关在 `site.yaml → hole_detect.stage2:`（`align_tip_vision` / `tip_*`）。
+> 量不到规尖偏移时二阶段**判失败**（exit 8），不会拿"法兰对上了"冒充成功。
+
 ```bash
 # 前置：T1 run_real.sh --arm 89；T3 run_camera_d405.sh --arm 89 --preview
 bash ~/ros2/scripts/run_stage2_locate.sh --arm 89                # 完整流程（自动拉起触觉服务，仅左臂）
 bash ~/ros2/scripts/run_stage2_locate.sh --arm 89 --hover-only   # 只垂直+悬停锁定，用来调高度
 bash ~/ros2/scripts/run_stage2_locate.sh --arm 89 --hole k2      # 对准 k2（默认 k1）
 bash ~/ros2/scripts/run_stage2_locate.sh --arm 89 --hover-z 0.28 # 临时改悬停高，不动 yaml
+bash ~/ros2/scripts/run_all.sh --arm 89 --no-descent             # 只验证精对准、不轻降
 ```
 
 悬停锁高接口：`site.yaml → robots[89].servo.hole_hover_z_m`（91 在同名段）。