悬停一次走完后下降会漂几毫米，这一保存点把观察高补交、接触门控和厂家 MoveL 接到能插进去的状态，后面好对照锁 XY 纯 Z。

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

docs/HANDBOOK.md

@@ -72,7 +72,7 @@ bash ~/ros2/scripts/run_all.sh --arm 89 --init-z 0.35 --hover-z 0.34
 一阶段默认 **D405 实时推理**，D435 待命。YOLO-pose 这一路不关。连续
 `D405_MISS_BEFORE_D435_S`（0.5 s）没有 conf≥`perception.wrist_handoff_conf`（0.5）
 的目标，才用顶视 D435 **拍一张**，把点用眼在手外 T 变到基座（不再乘法兰）。
-这一段运动是厂家 `MoveL`：脚本先停真机控制栈（感知不停），XY 对准该点，
+这一段运动是厂家 `MoveL`（SDK `vel` 0.3 m/s、`acc` 1.5 m/s²）：脚本先停真机控制栈（感知不停），XY 对准该点，
 工具尖高度保持当前，再冷启动 `run_real.sh --no-stop`。冷启动回来之后才开始计
 `servo.d435_handback_sec`（3 s）。赶路和杀栈期间不下发 D405。
 停稳之后改回 D405，跟踪点是工件框的矩形中心，不追 k0。
@@ -80,7 +80,10 @@ bash ~/ros2/scripts/run_all.sh --arm 89 --init-z 0.35 --hover-z 0.34
 会让工具尖进入工件、或超出工作盒的值直接拒绝，不会改成另一个高度再往下走。
 不写则一阶段锁高仍按 site，对孔悬停仍是 `hole_hover_z_m`（89 为 0.320）。
 框心对准连续 `servo.wrist_align_sec`（0.5 s）→ `/visual_servo/locked`。
-二阶段粗居中工件框，再多拍 k1/k2 闭环对准，轻降后在观测高度补一次 XY。
+本分支（`exp/hole-keypoint-once`）二阶段是**单次精拍**：悬停拍一次 k1/k2，
+把框心到目标孔一次走完（步长上限 40mm，不再截成 12mm），先降到观察高约 15mm 再交孔，斜线一步把 XY 补偿（≤3mm）和剩余 Z 收到贴面。轻降接触门控是 `final_gap+4mm`。
+`hole_detect.stage2.hole_keypoint_once: true`。看 `/tmp/stage2_result.json` 的 `snaps`。
+`main` 保存点仍是多走多拍。
 孔坐标把关键点像素交到 `workpiece_surface_z_m`，不读深度图。下臂停在
 `tool10120938` 的 TCP 长度（0.2245 m）加上 `final_gap_mm` 之上，不按旧 tool1 的 0.223 m。
 只测 D435 这一段位移时加 `--d435-only`：不交 D405、不进二阶段，并且要求先停 `run_real.sh`。

docs/HOLE_DETECT.md

@@ -99,8 +99,15 @@ 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`）→ 锁定保持。
+像素射线交到 `workpiece_surface_z_m`（不读深度图）+ 内参 + 手眼换算基座坐标 →
+移动**规尖**到目标孔正上方。
+
+本分支 `hole_keypoint_once: true`：悬停拍一次，把框心到 k1 的半孔距（约 30mm）
+一次走完（不再用多走多拍的 12mm 封顶），走后核验只记账。轻降先到观察高约 15mm
+（单步 20mm，约 3 步），再交孔测补偿，斜线一步把 XY（≤3mm）和剩余 Z 收到 `final_gap_mm`。
+规尖沿用悬停冻结值，不在近距重测。两孔间距掉出 50–70mm 或要补超过 8mm 则不动、
+也不贴面。轻降力接触门控是 `final_gap_mm + 4mm`（贴面 2mm 时 = 6mm）。看
+`/tmp/stage2_result.json` 的 `snaps[]`。`main` 保存点是多走多拍闭环。
 
 > **对的是"规尖"，不是"法兰轴线"**（2026-10-08 定稿）。通止规夹在爪里，相对法兰轴线
 > 可以整体偏出若干毫米；旧写法把**法兰**对到孔上，规尖就偏着压在孔沿上，轻降一压