phone-detect-test 0.2.0__py3-none-any.whl

phone_detect_test/__init__.py

@@ -0,0 +1,12 @@
+"""phone-detect-test：考场手机检测工具。
+
+一条命令启动监控台（网页 + 推理接口，同端口）：
+    phone-detect-test web
+
+也可作为 CLI 工具，覆盖目标检测任务的完整生命周期：
+检测（detect）、训练（train）、评估（val）、数据集整理（prepare）、
+数据清洗（clean）、标签污染审计（audit）、正负样本重采样（resample）、
+离线评分（evaluate）、权重下载（download-weights）。
+"""
+
+__version__ = "0.2.0"

phone_detect_test/__main__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""支持 `python -m phone_detect_test ...`，等价于 `phone-detect-test ...`。
+
+这样即使 pip 装的 Scripts 目录不在 PATH 里，也能用：
+    python -m phone_detect_test web
+"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

phone_detect_test/audit.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""audit：标签污染审计。
+
+这是本项目论文的核心方法：用「一个独立模型」回检已有标注，找出三类可疑样本——
+  1. missing_gt    ：无标注但模型高置信检出 -> 可能漏标
+  2. gt_unmatched  ：有标注但 GT 框没有任何预测匹配 -> 可能错误标注
+  3. pred_unmatched：模型高置信检出但 GT 无对应 -> 可能漏标
+
+关键原则（来自论文结论）：审计用的模型必须「独立于」当初做标注/清洗的模型，
+否则会陷入"自己验证自己"的循环，指标失真。
+"""
+import shutil
+from pathlib import Path
+
+from .utils import IMG_EXTS, pick_device, resolve_weights
+
+
+def _compute_iou(box1, box2):
+    """box = (xc, yc, w, h) 归一化。"""
+    x1min, y1min = box1[0] - box1[2] / 2, box1[1] - box1[3] / 2
+    x1max, y1max = box1[0] + box1[2] / 2, box1[1] + box1[3] / 2
+    x2min, y2min = box2[0] - box2[2] / 2, box2[1] - box2[3] / 2
+    x2max, y2max = box2[0] + box2[2] / 2, box2[1] + box2[3] / 2
+    ix1, iy1 = max(x1min, x2min), max(y1min, y2min)
+    ix2, iy2 = min(x1max, x2max), min(y1max, y2max)
+    inter = max(0, ix2 - ix1) * max(0, iy2 - iy1)
+    a1 = (x1max - x1min) * (y1max - y1min)
+    a2 = (x2max - x2min) * (y2max - y2min)
+    union = a1 + a2 - inter
+    return inter / union if union > 0 else 0.0
+
+
+def _read_gt(label_path, class_id):
+    boxes = []
+    p = Path(label_path)
+    if not p.exists():
+        return boxes
+    for line in p.read_text(encoding="utf-8").splitlines():
+        parts = line.strip().split()
+        if len(parts) < 5:
+            continue
+        if int(parts[0]) != class_id:
+            continue
+        xc, yc, w, h = map(float, parts[1:5])
+        boxes.append((xc, yc, w, h))
+    return boxes
+
+
+def run(args):
+    from ultralytics import YOLO
+
+    images_dir = Path(args.images)
+    labels_dir = Path(args.labels)
+    out_dir = Path(args.out_dir)
+    vis_dir = out_dir / "_pred_visual"
+    if not images_dir.exists():
+        raise SystemExit(f"图片目录不存在：{images_dir}")
+    if not labels_dir.exists():
+        raise SystemExit(f"标签目录不存在：{labels_dir}")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    vis_dir.mkdir(parents=True, exist_ok=True)
+
+    weights, _ = resolve_weights(args.weights,
+                                 weights_url=getattr(args, "weights_url", None))
+    device = pick_device(args.device)
+    model = YOLO(weights)
+    print(f"[审计] 模型 {weights} | 设备 {device}")
+    print(f"[审计] 类别 id={args.class_id} | 独立回检阈值 conf>={args.conf_pred_no_gt}")
+
+    stats = {"total": 0, "missing_gt": 0, "gt_unmatched": 0, "pred_unmatched": 0}
+    records = []
+
+    for img_path in sorted(images_dir.iterdir()):
+        if img_path.suffix.lower() not in IMG_EXTS:
+            continue
+        stats["total"] += 1
+        label_path = labels_dir / f"{img_path.stem}.txt"
+
+        r = model(str(img_path), conf=args.conf, verbose=False)[0]
+        pred_boxes = []
+        for i in range(len(r.boxes)):
+            if int(r.boxes.cls[i]) != args.class_id:
+                continue
+            conf = float(r.boxes.conf[i])
+            xc, yc, w, h = r.boxes.xywhn[i].tolist()
+            pred_boxes.append((conf, xc, yc, w, h))
+
+        gt_boxes = _read_gt(label_path, args.class_id)
+        reason = None
+
+        if len(gt_boxes) == 0:
+            if any(p[0] >= args.conf_pred_no_gt for p in pred_boxes):
+                reason = "missing_gt"
+                stats["missing_gt"] += 1
+        else:
+            for gt in gt_boxes:
+                max_iou = max((_compute_iou(gt, p[1:]) for p in pred_boxes), default=0)
+                if max_iou < args.iou_gt_no_pred:
+                    reason = "gt_unmatched"
+                    stats["gt_unmatched"] += 1
+                    break
+            if reason is None:
+                for conf, box in [ (p[0], p[1:]) for p in pred_boxes ]:
+                    if conf >= args.conf_pred_no_gt:
+                        max_iou = max((_compute_iou(box, gt) for gt in gt_boxes), default=0)
+                        if max_iou < args.match_iou:
+                            reason = "pred_unmatched"
+                            stats["pred_unmatched"] += 1
+                            break
+
+        if reason is not None:
+            records.append((img_path.name, reason))
+            shutil.copy2(img_path, out_dir / img_path.name)
+            if label_path.exists():
+                shutil.copy2(label_path, out_dir / label_path.name)
+            _draw_compare(img_path, gt_boxes, pred_boxes, vis_dir)
+
+    _write_summary(stats, records, out_dir)
+    print(f"\n[完成] 总图片 {stats['total']}，可疑 {len(records)} 个")
+    print(f"  漏标 {stats['missing_gt']} | GT无法匹配 {stats['gt_unmatched']} | 预测无对应 {stats['pred_unmatched']}")
+    print(f"  输出目录：{out_dir}")
+
+
+def _draw_compare(img_path, gt_boxes, pred_boxes, vis_dir):
+    import cv2
+    img = cv2.imread(str(img_path))
+    if img is None:
+        return
+    h, w = img.shape[:2]
+    for (xc, yc, bw, bh) in gt_boxes:
+        x1, y1 = int((xc - bw / 2) * w), int((yc - bh / 2) * h)
+        x2, y2 = int((xc + bw / 2) * w), int((yc + bh / 2) * h)
+        cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
+    for (conf, xc, yc, bw, bh) in pred_boxes:
+        x1, y1 = int((xc - bw / 2) * w), int((yc - bh / 2) * h)
+        x2, y2 = int((xc + bw / 2) * w), int((yc + bh / 2) * h)
+        cv2.rectangle(img, (x1, y1), (x2, y2), (0, 0, 255), 2)
+        cv2.putText(img, f"{conf:.2f}", (x1, max(0, y1 - 5)),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 255), 1)
+    cv2.imwrite(str(vis_dir / img_path.name), img)
+
+
+def _write_summary(stats, records, out_dir):
+    p = out_dir / "audit_report.txt"
+    with open(p, "w", encoding="utf-8") as f:
+        f.write("标签污染审计报告\n" + "=" * 40 + "\n")
+        f.write(f"总图片: {stats['total']}\n")
+        f.write(f"可疑总数: {len(records)}\n")
+        f.write(f"  - 缺失标注(漏标): {stats['missing_gt']}\n")
+        f.write(f"  - GT无法匹配(错框): {stats['gt_unmatched']}\n")
+        f.write(f"  - 预测无对应(漏标): {stats['pred_unmatched']}\n\n")
+        f.write("可疑图片列表:\n")
+        for name, reason in records:
+            f.write(f"{name}\t{reason}\n")
+    print(f"[报告] {p}")

phone_detect_test/clean.py

@@ -0,0 +1,246 @@
+# -*- coding: utf-8 -*-
+"""clean：一键清洗目标检测数据集。
+
+包含：图片完整性检查、格式修正、越界裁剪、过小/异常宽高比过滤、
+去重、基于预训练模型的漏标/误标检测、可视化抽查、清洗报告。
+"""
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def _iou(box1, box2):
+    """box = [x1, y1, x2, y2]（归一化）。"""
+    x1 = max(box1[0], box2[0])
+    y1 = max(box1[1], box2[1])
+    x2 = min(box1[2], box2[2])
+    y2 = min(box1[3], box2[3])
+    inter = max(0, x2 - x1) * max(0, y2 - y1)
+    a1 = (box1[2] - box1[0]) * (box1[3] - box1[1])
+    a2 = (box2[2] - box2[0]) * (box2[3] - box2[1])
+    union = a1 + a2 - inter
+    return inter / union if union else 0.0
+
+
+def _parse_label(txt_path):
+    boxes = []
+    p = Path(txt_path)
+    if not p.exists() or p.stat().st_size == 0:
+        return boxes
+    for line in p.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split()
+        if len(parts) != 5:
+            continue
+        cls = int(parts[0])
+        cx, cy, w, h = map(float, parts[1:5])
+        boxes.append([cls, cx - w / 2, cy - h / 2, cx + w / 2, cy + h / 2])
+    return boxes
+
+
+def _save_label(txt_path, boxes):
+    with open(txt_path, "w") as f:
+        for cls, x1, y1, x2, y2 in boxes:
+            cx = min(max((x1 + x2) / 2, 0), 1)
+            cy = min(max((y1 + y2) / 2, 0), 1)
+            w = min(max(x2 - x1, 0), 1)
+            h = min(max(y2 - y1, 0), 1)
+            f.write(f"{cls} {cx:.8f} {cy:.8f} {w:.8f} {h:.8f}\n")
+
+
+def _normalize(boxes):
+    valid = []
+    for cls, x1, y1, x2, y2 in boxes:
+        if x2 <= x1 or y2 <= y1:
+            continue
+        x1 = max(0, min(x1, 1))
+        y1 = max(0, min(y1, 1))
+        x2 = max(0, min(x2, 1))
+        y2 = max(0, min(y2, 1))
+        if x2 <= x1 or y2 <= y1:
+            continue
+        valid.append([cls, x1, y1, x2, y2])
+    return valid
+
+
+def run(args):
+    from PIL import Image
+    from ultralytics import YOLO
+
+    data_dir = Path(args.data_dir)
+    output_dir = Path(args.output_dir)
+    images_dir = data_dir / "images"
+    labels_dir = data_dir / "labels"
+    out_images = output_dir / "images"
+    out_labels = output_dir / "labels"
+
+    if not images_dir.exists():
+        raise SystemExit(f"图片目录不存在：{images_dir}")
+
+    out_images.mkdir(parents=True, exist_ok=True)
+    out_labels.mkdir(parents=True, exist_ok=True)
+
+    model = YOLO(args.model_path)
+    print(f"[模型] {args.model_path}")
+
+    stats = {
+        "total": 0, "empty": 0, "non_empty": 0, "orig_boxes": 0,
+        "cleaned_boxes": 0, "removed_boxes": 0, "empty_after_clean": 0,
+        "broken": 0, "missing_candidates": 0, "false_candidates": 0,
+    }
+    missing_list, false_list, broken_list = [], [], []
+    viz_samples = []
+
+    image_files = sorted(images_dir.glob("*.jpg"))
+    stats["total"] = len(image_files)
+    print(f"[开始] 清洗 {len(image_files)} 张图片")
+
+    for idx, img_path in enumerate(image_files):
+        label_path = labels_dir / f"{img_path.stem}.txt"
+
+        # 图片完整性
+        try:
+            with Image.open(img_path) as im:
+                im.verify()
+        except Exception as e:
+            stats["broken"] += 1
+            broken_list.append(str(img_path))
+            continue
+
+        raw = _parse_label(label_path)
+        stats["orig_boxes"] += len(raw)
+        cleaned = []
+
+        if len(raw) == 0:
+            stats["empty"] += 1
+            # 负样本：检查漏标
+            if args.check_missing:
+                r = model(str(img_path), conf=args.missing_conf, verbose=False)[0]
+                for box in r.boxes:
+                    if int(box.cls[0]) == args.phone_class_id and float(box.conf[0]) >= args.missing_conf:
+                        x1, y1, x2, y2 = box.xyxy[0].tolist()
+                        with Image.open(img_path) as im:
+                            w, h = im.size
+                        missing_list.append({
+                            "image": str(img_path),
+                            "box": [x1 / w, y1 / h, x2 / w, y2 / h],
+                            "conf": float(box.conf[0]),
+                        })
+                        stats["missing_candidates"] += 1
+            shutil.copy2(img_path, out_images / img_path.name)
+            (out_labels / f"{img_path.stem}.txt").touch()
+        else:
+            stats["non_empty"] += 1
+            fixed = _normalize(raw)
+            # 过滤过小 / 异常宽高比
+            kept = []
+            for cls, x1, y1, x2, y2 in fixed:
+                w = x2 - x1
+                h = y2 - y1
+                area = w * h
+                aspect = max(w, h) / max(min(w, h), 1e-6)
+                if area < args.min_area or min(w, h) < args.min_side:
+                    continue
+                if aspect < args.aspect_min or aspect > args.aspect_max:
+                    continue
+                kept.append([cls, x1, y1, x2, y2])
+            # 去重
+            dedup = []
+            for box in kept:
+                if any(_iou(box[1:], k[1:]) > args.dedup_iou for k in dedup):
+                    continue
+                dedup.append(box)
+            # 误标检查
+            if args.check_false:
+                cleaned = _check_false(model, img_path, dedup, args.phone_class_id,
+                                       args.false_conf, false_list)
+                stats["false_candidates"] += len(false_list)
+            else:
+                cleaned = dedup
+
+            stats["removed_boxes"] += len(raw) - len(cleaned)
+            if len(cleaned) == 0:
+                stats["empty_after_clean"] += 1
+            shutil.copy2(img_path, out_images / img_path.name)
+            _save_label(out_labels / f"{img_path.stem}.txt", cleaned)
+
+        stats["cleaned_boxes"] += len(cleaned)
+        if len(viz_samples) < args.visualize_n:
+            viz_samples.append((img_path, cleaned))
+        if (idx + 1) % 1000 == 0:
+            print(f"  已处理 {idx + 1}/{len(image_files)}")
+
+    _visualize(viz_samples, output_dir)
+    _report(stats, missing_list, false_list, broken_list, output_dir)
+
+
+def _check_false(model, img_path, gt_boxes, phone_class_id, false_conf, false_list):
+    """用预训练模型检查 GT 框是否为真目标，低置信且无匹配则判误标删除。"""
+    from PIL import Image
+    r = model(str(img_path), conf=false_conf, verbose=False)[0]
+    with Image.open(img_path) as im:
+        w, h = im.size
+    pred_boxes = []
+    for box in r.boxes:
+        if int(box.cls[0]) != phone_class_id:
+            continue
+        x1, y1, x2, y2 = box.xyxy[0].tolist()
+        pred_boxes.append([x1 / w, y1 / h, x2 / w, y2 / h, float(box.conf[0])])
+
+    kept = []
+    for gt in gt_boxes:
+        gx1, gy1, gx2, gy2 = gt[1:]
+        max_iou = max((_iou([gx1, gy1, gx2, gy2], pb[:4]) for pb in pred_boxes), default=0)
+        max_conf = max((pb[4] for pb in pred_boxes if _iou([gx1, gy1, gx2, gy2], pb[:4]) > 0.5), default=0)
+        if max_iou < 0.1 and max_conf < false_conf:
+            false_list.append({"image": str(img_path), "gt_box": [gx1, gy1, gx2, gy2], "max_conf": max_conf})
+            continue
+        kept.append(gt)
+    return kept
+
+
+def _visualize(samples, output_dir):
+    if not samples:
+        return
+    from PIL import Image
+    import numpy as np
+    from ultralytics.utils.plotting import Annotator
+    viz_dir = output_dir / "visualization"
+    viz_dir.mkdir(exist_ok=True)
+    for i, (img_path, boxes) in enumerate(samples):
+        img = Image.open(img_path).convert("RGB")
+        annotator = Annotator(np.array(img))
+        for cls, x1, y1, x2, y2 in boxes:
+            w, h = img.size
+            annotator.box_label([x1 * w, y1 * h, x2 * w, y2 * h], str(cls), color=(0, 255, 0))
+        Image.fromarray(annotator.result()).save(viz_dir / f"sample_{i:03d}.jpg")
+    print(f"[可视化] 已保存 {len(samples)} 张至 {viz_dir}")
+
+
+def _report(stats, missing_list, false_list, broken_list, output_dir):
+    report = {
+        "清洗统计": {
+            "总图片数": stats["total"],
+            "空标签图片数": stats["empty"],
+            "有标注图片数": stats["non_empty"],
+            "清洗前标注框总数": stats["orig_boxes"],
+            "清洗后标注框总数": stats["cleaned_boxes"],
+            "删除标注框数": stats["removed_boxes"],
+            "清洗后变空的图片数": stats["empty_after_clean"],
+            "损坏图片数": stats["broken"],
+            "疑似漏标数": stats["missing_candidates"],
+            "疑似误标数": stats["false_candidates"],
+        },
+        "疑似漏标": missing_list[:100],
+        "疑似误标": false_list[:100],
+        "损坏图片": broken_list,
+    }
+    p = output_dir / "clean_report.json"
+    p.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"\n[报告] {p}")
+    for k, v in report["清洗统计"].items():
+        print(f"  {k}: {v}")

phone_detect_test/cli.py

@@ -0,0 +1,184 @@
+# -*- coding: utf-8 -*-
+"""phone-detect-test 命令行入口。
+
+用法示例：
+    phone-detect-test web
+    phone-detect-test download-weights
+    phone-detect-test detect --source imgs/ --output out.json
+    phone-detect-test detect --source img.jpg --draw --draw-dir vis/
+    phone-detect-test train --data data.yaml --epochs 100
+    phone-detect-test val --data data.yaml --sweep
+    phone-detect-test prepare --src raw/ --out dataset/
+    phone-detect-test clean --data-dir raw/ --output-dir cleaned/
+    phone-detect-test audit --images train/images --labels train/labels --out-dir suspicious/
+    phone-detect-test resample --data-dir dataset/ --output-dir resampled/
+    phone-detect-test evaluate --pred pred.json --images gt/images --labels gt/labels
+"""
+import argparse
+import sys
+
+# 需要模型权重的子命令都支持这两个通用参数
+_WEIGHTS_ARGS = ("--weights", "--weights-url")
+
+
+def _add_weights_args(p, url_help="覆盖权重下载地址（优先级高于环境变量与内置默认值）"):
+    """给子命令加上统一的权重相关参数。"""
+    p.add_argument("--weights", default=None, help="模型权重路径（默认自动发现/下载）")
+    p.add_argument("--weights-url", default=None, help=url_help)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="phone-detect-test",
+        description="考场手机检测 CLI 工具：检测 / 训练 / 数据清洗 / 标签审计",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ---- detect ----
+    p = sub.add_parser("detect", help="单图 / 目录批量检测")
+    p.add_argument("--source", required=True, help="图片路径或目录")
+    _add_weights_args(p)
+    p.add_argument("--output", default=None, help="输出 JSON 路径")
+    p.add_argument("--conf", type=float, default=0.25, help="置信度阈值")
+    p.add_argument("--iou", type=float, default=0.7, help="NMS IoU 阈值")
+    p.add_argument("--imgsz", type=int, default=640, help="推理分辨率")
+    p.add_argument("--device", default=None, help="设备，默认自动")
+    p.add_argument("--class-name", default=None, help="类别名（默认取模型名）")
+    p.add_argument("--draw", action="store_true", help="画框输出可视化图")
+    p.add_argument("--draw-dir", default="vis", help="可视化输出目录")
+    p.set_defaults(func="detect")
+
+    # ---- train ----
+    p = sub.add_parser("train", help="继续训练 / 微调")
+    p.add_argument("--data", required=True, help="数据集 data.yaml")
+    _add_weights_args(p, url_help="覆盖初始权重的下载地址")
+    p.add_argument("--epochs", type=int, default=100)
+    p.add_argument("--batch", type=int, default=16)
+    p.add_argument("--imgsz", type=int, default=640)
+    p.add_argument("--device", default=None)
+    p.add_argument("--workers", type=int, default=4)
+    p.add_argument("--patience", type=int, default=30)
+    p.add_argument("--optimizer", default="auto")
+    p.add_argument("--lr0", type=float, default=0.001)
+    p.add_argument("--lrf", type=float, default=0.01)
+    p.add_argument("--freeze", type=int, default=None)
+    p.add_argument("--close-mosaic", type=int, default=10)
+    p.add_argument("--cache", default="False", choices=["False", "ram", "disk"])
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--project", default="runs/detect")
+    p.add_argument("--name", default="phone_ft")
+    p.add_argument("--resume", default=None)
+    p.set_defaults(func="train")
+
+    # ---- val ----
+    p = sub.add_parser("val", help="验证集评估 + 阈值搜索")
+    p.add_argument("--data", required=True, help="数据集 data.yaml")
+    _add_weights_args(p)
+    p.add_argument("--split", default="val")
+    p.add_argument("--imgsz", type=int, default=640)
+    p.add_argument("--batch", type=int, default=16)
+    p.add_argument("--conf", type=float, default=0.25)
+    p.add_argument("--iou", type=float, default=0.7)
+    p.add_argument("--device", default=None)
+    p.add_argument("--workers", type=int, default=0)
+    p.add_argument("--sweep", action="store_true", help="搜索最优 conf 阈值")
+    p.add_argument("--conf-grid", default="0.1,0.2,0.25,0.3,0.4,0.5,0.6,0.7")
+    p.add_argument("--project", default="runs")
+    p.set_defaults(func="val")
+
+    # ---- prepare ----
+    p = sub.add_parser("prepare", help="整理数据集并生成 data.yaml")
+    p.add_argument("--src", default=None, help="图片+标签混合文件夹")
+    p.add_argument("--images", default=None)
+    p.add_argument("--labels", default=None)
+    p.add_argument("--out", required=True, help="输出数据集根目录")
+    p.add_argument("--val-ratio", type=float, default=0.1)
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--class-name", default="phone")
+    p.set_defaults(func="prepare")
+
+    # ---- clean ----
+    p = sub.add_parser("clean", help="一键清洗数据集")
+    p.add_argument("--data-dir", required=True, help="输入数据集（含 images/ labels/）")
+    p.add_argument("--output-dir", required=True, help="清洗后输出目录")
+    p.add_argument("--model-path", default="yolov8n.pt", help="清洗用预训练模型")
+    p.add_argument("--phone-class-id", type=int, default=67, help="预训练模型里手机的类别 id")
+    p.add_argument("--missing-conf", type=float, default=0.7)
+    p.add_argument("--false-conf", type=float, default=0.05)
+    p.add_argument("--min-area", type=float, default=1e-5)
+    p.add_argument("--min-side", type=float, default=0.01)
+    p.add_argument("--aspect-min", type=float, default=0.1)
+    p.add_argument("--aspect-max", type=float, default=10.0)
+    p.add_argument("--dedup-iou", type=float, default=0.8)
+    p.add_argument("--visualize-n", type=int, default=20)
+    p.add_argument("--check-missing", action="store_true", help="检查漏标")
+    p.add_argument("--check-false", action="store_true", help="检查误标")
+    p.set_defaults(func="clean")
+
+    # ---- audit ----
+    p = sub.add_parser("audit", help="标签污染审计")
+    p.add_argument("--images", required=True, help="图片目录")
+    p.add_argument("--labels", required=True, help="标签目录")
+    p.add_argument("--out-dir", default="suspicious", help="输出目录")
+    _add_weights_args(p)
+    p.add_argument("--class-id", type=int, default=0)
+    p.add_argument("--conf", type=float, default=0.25)
+    p.add_argument("--conf-pred-no-gt", type=float, default=0.5)
+    p.add_argument("--iou-gt-no-pred", type=float, default=0.1)
+    p.add_argument("--match-iou", type=float, default=0.1)
+    p.add_argument("--device", default=None)
+    p.set_defaults(func="audit")
+
+    # ---- resample ----
+    p = sub.add_parser("resample", help="正负样本重采样")
+    p.add_argument("--data-dir", required=True, help="输入数据集（含 images/ labels/）")
+    p.add_argument("--output-dir", required=True, help="输出目录")
+    p.add_argument("--pos-ratio", type=float, default=0.5, help="正样本占负样本比例（默认 0.5 即 1:2）")
+    p.add_argument("--seed", type=int, default=42)
+    p.set_defaults(func="resample")
+
+    # ---- evaluate ----
+    p = sub.add_parser("evaluate", help="离线评测（复刻赛题评分）")
+    p.add_argument("--pred", required=True, help="detect 输出的 JSON")
+    p.add_argument("--images", required=True, help="真值图片目录")
+    p.add_argument("--labels", required=True, help="真值标签目录")
+    p.add_argument("--conf", type=float, default=0.25)
+    p.add_argument("--iou", type=float, default=0.5)
+    p.set_defaults(func="evaluate")
+
+    # ---- download-weights ----
+    p = sub.add_parser(
+        "download-weights",
+        help="只下载权重并校验可用（发完 Release 后用它验证地址是否生效）")
+    # --url 与 --weights-url 等价，和其它子命令保持一致的写法
+    p.add_argument("--url", "--weights-url", dest="url", default=None,
+                   help="覆盖下载地址（优先级最高）")
+    p.add_argument("--dest", default="phone_best.pt", help="保存路径，默认 ./phone_best.pt")
+    p.add_argument("--force", action="store_true", help="即使本机已有权重也重新下载")
+    p.add_argument("--no-verify", action="store_true", help="只下载，不用模型加载校验")
+    p.set_defaults(func="download_weights")
+
+    # ---- web：一条命令启动监控台（页面 + 推理接口，同端口）----
+    p = sub.add_parser(
+        "web", help="启动监控台网页 + 推理接口，并自动打开浏览器（最常用入口）")
+    _add_weights_args(p)
+    p.add_argument("--host", default="127.0.0.1",
+                   help="监听地址；局域网访问用 0.0.0.0")
+    p.add_argument("--port", type=int, default=8080,
+                   help="端口，默认 8080（被占用会自动顺延）")
+    p.add_argument("--no-browser", action="store_true", help="不自动打开浏览器")
+    p.add_argument("--device", default=None, help="设备，如 cuda:0 / cpu")
+    p.add_argument("--imgsz", type=int, default=None, help="推理分辨率")
+    p.add_argument("--conf", type=float, default=None, help="默认置信度阈值")
+    p.add_argument("--reload", action="store_true", help="开发模式：改代码自动重启")
+    p.set_defaults(func="server")
+
+    args = parser.parse_args(argv)
+
+    # 分发到对应模块
+    module = __import__(f"phone_detect_test.{args.func}", fromlist=["run"])
+    module.run(args)
+
+
+if __name__ == "__main__":
+    main()