P4s：模型审计 —— 移出零引用模型，修掉代码里三处悬空 best.pt

先回答"这些模型到底有没有人用"，用全仓库引用扫描判定，不靠猜：

  在用   yolo/detect_best_0.onnx + .engine   ← paths.yolo_weights
  在用   hole_insert/detect_best_1.onnx      ← hole_detect.weights / workpiece_weights
  零引用 detect_hc90（pt/onnx/engine）       ← 只剩注释里的历史说明
  零引用 detect_yolo26_gongjian.pt
  零引用 detect_best（onnx/engine）          ← 仅代码兜底候选，而那个候选是 .pt，不存在

所以 detect_hc90 不需要修复，是不用的东西：连同另两个一起移出仓库。
注意**二进制权重被 gitignore**，删掉就找不回来了，因此是移出到
~/ros2-models-unused-20260923/ 而非 rm。搬回 models/ 即可被 list 重新发现。

顺手挖出并修掉三处悬空引用（和之前 site.yaml 里那个 best.pt 同一类问题）：
- hole_detector.weights_from_site：兜底路径写死 models/hole_insert/best.pt（不存在）
- hole_detector._default_model_path：三个候选路径**全都不存在**，函数却
  `return candidates[0]`，于是永远返回不存在的 best.pt；报错路径看着很合理，
  极易被误判成"文件被误删"。现改为以 site.yaml 为准，再退到规范模型。
- config/hole_insert.yaml 顶部注释同样写的是 best.pt

新增 test_hole_detector.py（8 项）锁住这个回归。测试刻意**不断言文件存在**
——二进制不进 git，新克隆的仓库里 models/ 是空的——只断言解析结果指向规范模型名。

体检从 4 处问题降到 0：bash scripts/weights.sh doctor --check-engines → "没有发现问题"

测试 233 项通过；18 个包构建通过。

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

models/hole_insert/README.md

@@ -9,22 +9,21 @@
 
 ## 现状
 
-- `detect_best_1.onnx` —— 工件检测模型，被 `hole_detect.workpiece_weights` 使用。
+- `detect_best_1.onnx` —— 被 `hole_detect.workpiece_weights` 使用（`two_stage` 后端）。
+  这是本目录唯一在用的模型。
 
-## 历史遗留（已知问题）
+## 已修掉的悬空引用
 
-`config/site.yaml` 的这两处仍指向一个**不存在**的文件 `models/hole_insert/best.pt`：
+`config/site.yaml` 的 `paths.hole_weights` 与 `hole_detect.weights` 原先都指向
+**不存在**的文件 `models/hole_insert/best.pt`。`backend: two_stage` 时这两处不被读取，
+所以一直没暴露；一旦切成 `backend: yolo` 就会启动失败。
 
-```yaml
-paths:
-  hole_weights: ".../models/hole_insert/best.pt"     # ← 文件不存在
-hole_detect:
-  weights: ".../models/hole_insert/best.pt"          # ← 文件不存在
-```
+现已改为实际存在的 `detect_best_1.onnx`。同一个悬空的 `best.pt` 还藏在代码里
+（`hole_detector.py` 的 `weights_from_site` / `_default_model_path`，那里三个候选
+路径全都不存在，函数却总会返回第一个），也一并修成了以 site.yaml 为准、
+再退到实际存在的模型。
 
-`backend: two_stage` 时这两处不会被读，所以现在不影响运行；但一旦切成
-`backend: yolo` 就会启动失败。用 `bash ~/ros2/scripts/weights.sh doctor`
-能查出来。要么把真实权重按命名规则放进本目录，要么把这两处配置删掉。
+改权重相关路径后，用 `bash ~/ros2/scripts/weights.sh doctor` 复查悬空引用。
 
 ## 加新模型 / 看标签