P4：权重/标签模块 —— 旁挂标签文件 + PT→ONNX→TRT 转换工具 + 归档归位

痛点：TensorRT 10.13 的 Python API 没有元数据读写，engine 一转就把类名丢了；
推理侧只能退化成 str(cid)（"0"、"1"），界面上看不出是什么类，属于静默失效。
同时旧的 export_yolo_trt.sh 只能手工搬文件、手工改 site.yaml、标签无处安放。

标签子系统（model_labels.py）
- 旁挂标签文件 <模型名>.labels.yaml，放在权重旁边，文本、可手改、进 git
  （二进制权重不进 git，标签是配置所以进）
- 读取优先级：旁挂文件 > ONNX 元数据 > 模型元数据 > 占位符 class_N
  占位符是故意的：缺标签时要一眼看出来，而不是悄悄退回 cid
- 解析器容忍多种写法：dict / list / 逗号串 / 逐行文本 / Python repr 串

布局与转换（weights_layout.py + weights.py + weights.sh）
- models/<分组>/<模型名>.{pt,onnx,engine} + 同名 .labels.yaml
- convert：PT→ONNX→TensorRT，支持自定义名字、自动归位、固化标签
- staging/：非标准格式先进这里，转换后源文件归档到 staging/done/
- list / labels / doctor / show 四个子命令
- doctor --check-engines 能查出 engine 与 TensorRT 版本不匹配（反序列化返回空）

推理侧接入
- yolo_detector / onnx_workpiece / hole_detect_hough 统一走 read_labels()
- 画框标签不再硬编码 "gongjian"，改用实际类名

顺手修掉的真实问题
- setup.py 撞上断掉的符号链接会让整包构建失败，报错还指向 build/ 里的幽灵文件
  （源文件被挪走后 build/ 里留下的断链被 os.walk 列出来）。加 _existing() 过滤。
- P3 遗漏：site.yaml / export_site_env.py / run_handeye.sh / handeye_teach.py /
  handeye_calibrate.py 里的 handeye 工作目录仍是 /tmp/handeye_calib*，
  与已迁到 handeye/ 的其余路径不一致。统一到 handeye/tmp/<臂号>。
- site.yaml 的 hole_weights / hole_detect.weights 原指向不存在的 best.pt，
  改为实际存在的 detect_best_1.onnx；active.pt 符号链接已废弃并清理。
- weights.sh labels 原先不接受 "分组/模型名" 写法，而 list 输出正是这个形式，
  照着敲会报"找不到模型"。补上，并让报错直接给出可复制的全名。

测试：225 项通过（新增 test_model_labels.py / test_weights_layout.py）。
真实 ONNX→engine 端到端转换已验过。

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

scripts/export_yolo_trt.sh

@@ -1,90 +1,47 @@
 #!/usr/bin/env bash
-# Export YOLO .pt/.onnx → TensorRT .engine (FP16).
+# 【旧命令，已改为转发壳】YOLO 权重 → TensorRT engine。
 #
+# 请改用新命令（多了改名、归位、标签固化、staging 等功能）：
+#
+#   bash ~/ros2/scripts/weights.sh convert <文件> --name <模型名>
+#   bash ~/ros2/scripts/weights.sh list
+#   bash ~/ros2/scripts/weights.sh labels <模型名>
+#
+# 本脚本保留只为兼容旧文档/旧习惯，行为等价于：
+#   weights.sh convert <weights> --name <同名主干> --to engine [--imgsz N]
+#
+# 原用法（仍然可用）：
 #   bash ~/ros2/scripts/export_yolo_trt.sh
-#   bash ~/ros2/scripts/export_yolo_trt.sh /home/cc/ros2/models/yolo/detect_best.onnx 640
-#
-# Needs: tensorrt-cu12 + onnx + onnxslim in ros_flexiv (do NOT pip install
-# the meta package `tensorrt`, it pulls CUDA 13 wheels).
-# Then set yolo.backend: tensorrt in site.yaml and restart visual servo.
+#   bash ~/ros2/scripts/export_yolo_trt.sh /path/to/xxx.onnx 640
 
 set -eo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
 # shellcheck disable=SC1091
-source "${ROOT}/scripts/lib/load_site_config.sh"
+source "${ROOT}/scripts/lib/load_site_config.sh" >/dev/null 2>&1 || true
 
-PT="${1:-${SITE_YOLO_WEIGHTS:-${ROOT}/models/yolo/detect_best.onnx}}"
+WEIGHTS="${1:-${SITE_YOLO_WEIGHTS:-${ROOT}/models/yolo/detect_best.onnx}}"
 IMGSZ="${2:-${SITE_YOLO_IMGSZ:-640}}"
-PY="${HOME}/anaconda3/envs/ros_flexiv/bin/python"
 
-if [[ ! -f "${PT}" ]]; then
-  echo "ERROR: weights not found: ${PT}" >&2
+if [[ ! -f "${WEIGHTS}" ]]; then
+  echo "ERROR: weights not found: ${WEIGHTS}" >&2
   exit 1
 fi
 
-# Pip TensorRT shared libs (needed at export + runtime).
-TRT_LIBS="$("${PY}" - <<'PY'
-import pathlib, tensorrt
-p = pathlib.Path(tensorrt.__file__).resolve().parent
-cands = [p, p.parent / "tensorrt_libs", p.parent / "nvidia" / "tensorrt" / "lib"]
-print(":".join(str(x) for x in cands if x.exists()))
-PY
-)"
-export LD_LIBRARY_PATH="${TRT_LIBS}${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
-export YOLO_AUTOINSTALL=false
+# 取文件名主干做模型名：xxx.onnx → xxx
+BASE="$(basename "${WEIGHTS}")"
+NAME="${BASE%.*}"
+DIR="$(dirname "${WEIGHTS}")"
+# 分组 = 权重所在目录名（相对 models/ 的那一层）
+GROUP="$(basename "${DIR}")"
 
-echo "Export TensorRT engine from ${PT}  imgsz=${IMGSZ}"
-"${PY}" - <<PY
-from pathlib import Path
-import tensorrt as trt
+echo "提示: export_yolo_trt.sh 已改为转发壳，建议直接用："
+echo "      bash ~/ros2/scripts/weights.sh convert ${WEIGHTS} --name ${NAME}"
+echo
 
-src = Path("${PT}").expanduser()
-print("tensorrt", trt.__version__)
-print("source", src)
-engine_path = src.with_suffix(".engine")
-
-if src.suffix.lower() == ".onnx":
-    logger = trt.Logger(trt.Logger.INFO)
-    flag = 1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH)
-    builder = trt.Builder(logger)
-    network = builder.create_network(flag)
-    parser = trt.OnnxParser(network, logger)
-    raw = src.read_bytes()
-    if not parser.parse(raw):
-        for i in range(parser.num_errors):
-            print("ONNX parse error:", parser.get_error(i))
-        raise SystemExit("ONNX parse failed")
-    config = builder.create_builder_config()
-    config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 4 << 30)
-    if builder.platform_has_fast_fp16:
-        config.set_flag(trt.BuilderFlag.FP16)
-        print("FP16 enabled")
-    serialized = builder.build_serialized_network(network, config)
-    if serialized is None:
-        raise SystemExit("TensorRT build failed")
-    engine_path.write_bytes(bytes(serialized))
-    print("wrote", engine_path)
-else:
-    from ultralytics import YOLO
-    m = YOLO(str(src))
-    try:
-        out = m.export(
-            format="engine",
-            imgsz=int("${IMGSZ}"),
-            device=0,
-            quantize=16,
-            simplify=True,
-            workspace=4,
-        )
-    except TypeError:
-        out = m.export(
-            format="engine",
-            imgsz=int("${IMGSZ}"),
-            device=0,
-            half=True,
-            simplify=True,
-            workspace=4,
-        )
-    print("wrote", out)
-PY
-echo "Done. Restart: bash ~/ros2/scripts/run_visual_servo_rt.sh --control"
+exec bash "${ROOT}/scripts/weights.sh" convert "${WEIGHTS}" \
+  --name "${NAME}" \
+  --group "${GROUP}" \
+  --to engine \
+  --imgsz "${IMGSZ}" \
+  --force