# Auto Vision

> 边缘 AI 视觉开发统一框架，覆盖 K230 / MaixCAM-Pro / MaixCAM2 / RK3588 / Jetson Orin Nano Super 五平台。包含模型转换（ONNX→kmodel/cvimodel/axmodel/rknn/engine）、INT8/FP16 量化、SSH/串口/SD 部署、自适应调度、benchmark、OTA、19 个经典 CV 模块（IPM 逆透视/车道线/ArUco/HDR/光流/立体）+ YOLO/BoxMOT/PaddleOCR。触发：K230、CanMV、MaixCAM、RK3588、Jetson、NPU、KPU、TensorRT、RKNN、kmodel、cvimodel、axmodel、nncase、rknn-toolkit2、trtexec、DeepStream、Savant、YOLO、ByteTrack、PaddleOCR、目标检测、跟踪、OCR、IPM 逆透视、车道线、立体视觉、ArUco、HDR、超分、模型转换、量化、部署、采图、benchmark、OTA。

- Skill: `duncanyoung-1/auto-vision` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add duncanyoung-1/auto-vision`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duncanyoung-1/auto-vision/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: duncanyoung-1 (https://skillmd.com/u/duncanyoung-1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/duncanyoung-1/auto-vision

---


# auto-vison — 边缘 AI 视觉模块统一开发 skill

> 目标：**降低 4 类 AI 视觉模块的开发门槛 + 提升从训练到上板的迭代效率**。
> 原则：**复用 > 改良 > 自研**，最大化复用 Ultralytics、官方 model zoo、上游 SDK，自己只写胶水。

---

## 1. 何时使用本 skill

触发条件（命中任一即用）：

- 用户提到目标硬件：K230、CanMV、MaixCAM、MaixCAM-Pro、MaixCAM2、RK3588（含 RK3576/RK3568）、Jetson Orin Nano Super
- 任务：模型转换（PyTorch/ONNX → 平台格式）、上板部署、摄像头采图/标定、推理性能调优、量化校准、OTA / 远程日志、模型加密
- 报错关键字：`nncase`、`kmodel`、`rknn-toolkit2`、`tpu-mlir`、`pulsar2`、`trtexec`、`cvimodel`、`axmodel`、MaixPy `nn.YOLO11`、CanMV `aicube`/`aidemo`

**不用本 skill 的场景**：纯 PC 推理（直接 Ultralytics）、单纯模型训练（用原生 PyTorch）、非视觉任务（音频/LLM 单独走 rknn-llm 或 jetson-containers）。

### 1.1 与其他 skill 的边界（避免冲突）

| 任务边界 | 用本 skill | 用其他 skill |
|---|---|---|
| AI 视觉模型转换 / 部署 / 调优 / 摄像头 ISP | ✅ auto-vision | — |
| 通用 MCU 外设驱动（STM32 寄存器、IIC 设备初始化） | — | `peripheral-driver` / `stm32-hal-development` |
| 嵌入式 RIPER-5 流程编排（多阶段大任务） | — | `embedded-dev` |
| 板端 SSH 通信 / 文件传输 | 调用 | `ssh-skill` |
| K230 串口日志解析 | 调用 | `serial-monitor` |
| K230 SDK 编译 / Linux 镜像构建 | — | `build-cmake` / `build-makefile` |
| 板端 GDB 调试（非 AI 推理崩溃） | — | `debug-gdb-openocd` / `debug-jlink` |
| 视觉模型推理崩溃 / 内存溢出诊断 | ✅ auto-vision（recipes/debug_workflow.md） | — |

---

## 2. 平台支持矩阵（务必先看）

### 2.1 硬件 / 工具链矩阵

| 平台 | 上层 API | 转换工具链 | 板端运行时 | 模型格式 | 主力代码语言 |
|---|---|---|---|---|---|
| **K230 裸 SDK** | CanMV-MicroPython / Linux C | `nncase` ≥ 2.9 + `nncase-kpu` | KPU runtime | `.kmodel` | Python (CanMV) / C |
| **MaixCAM / MaixCAM-Pro** | MaixPy v4 / MaixCDK | `tpu-mlir` (Docker) | MaixCAM runtime | `.cvimodel` + `.mud` | Python |
| **MaixCAM2** | MaixPy v4 / MaixCDK | `pulsar2` (Docker, AX620E) | MaixCAM2 runtime | `.axmodel` + `.mud` | Python |
| **RK3588 / RK3576** | rknn-toolkit-lite2 / rknpu2 C | `rknn-toolkit2` ≥ 2.3 (x86 Linux) | rknpu2 | `.rknn` | Python (Lite2) / C++ |
| **Jetson Orin Nano Super 8GB** | PyTorch + TensorRT / DeepStream | `trtexec` / `ultralytics export` | TensorRT 10 (JetPack 6.x) | `.engine` / `.plan` | Python (+ CUDA C++) |

### 2.2 任务 × 平台支持等级

> 🟢 **可跑通**（templates 内有完整脚手架，5 分钟跑起）
> 🟡 **半自动**（有官方 example 但需要手动调整，详见 platforms/*.md）
> 🔵 **仅指导**（仅提供配方与上游链接，需要用户自行实现）
> ⚫ **不支持**（硬件或工具链限制）

| 任务 | K230 | MaixCAM/Pro | MaixCAM2 | RK3588 | Jetson Orin Nano Super |
|---|---|---|---|---|---|
| 目标检测 (YOLO11/v8/v5) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| 图像分类 (MobileNet/ResNet) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| 语义分割 (YOLO-seg/DeepLab) ★P1 | 🟡 | 🟡 | 🟢 | 🟢 | 🟢 |
| 关键点姿态 (YOLO-pose/HRNet) ★P1 | 🟡 | 🟡 | 🟢 | 🟢 | 🟢 |
| 人脸检测 (RetinaFace/YuNet) | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| 人脸识别 (ArcFace/FaceNet) ★P1 | 🔵 | 🟡 | 🟢 | 🟢 | 🟢 |
| OCR (PP-OCR / CRNN) | 🔵 | 🟡 | 🟡 | 🟢 | 🟢 |
| 多目标跟踪 (ByteTrack/SORT) | ⚫ | 🔵 | 🟡 | 🟡 | 🟢 |
| ReID 行人再识别 | ⚫ | 🔵 | 🔵 | 🟡 | 🟢 |
| 车牌识别 (LPRNet) | 🔵 | 🟡 | 🟡 | 🟢 | 🟢 |
| 多模型 pipeline（detect+track+reid） | ⚫ | 🔵 | 🔵 | 🟡 | 🟢 (DeepStream) |
| Open-Vocab 检测 (NanoOWL/Grounding) | ⚫ | ⚫ | 🔵 | 🔵 | 🟢 |
| VLM 多模态 (Live Llava / VILA) | ⚫ | ⚫ | ⚫ | 🔵 | 🟢 |

**说明**：
- 🔵→🟡 升级路径：需求高的任务请优先选 RK3588 / Jetson；K230/MaixCAM 适合单模型轻量场景
- 多模型 pipeline 在 Jetson 上用 DeepStream，在 RK3588 上手写 GStreamer pipeline
- VLM / Live Llava 需要 ≥ 8GB 内存，目前只 Jetson Orin Nano Super 满足

> **MaixCAM 注意**：MaixCAM 和 MaixCAM-Pro 用 `.cvimodel`（tpu-mlir），MaixCAM2 用 `.axmodel`（pulsar2）。两者**不通用**，模型转换工具链完全不同。本 skill 把它们合并在 `platforms\maixcam.md` 内部分章讲解。
> **Jetson**：本 skill 只针对 **Orin Nano Super 8GB**（67 TOPS, JetPack 6.x, TensorRT 10）。注意 TensorRT 10 的 INT8 在某些算子上有兼容问题，量化默认走 FP16。
> **MaixCAM 与 K230 关系**：MaixCAM-Pro/MaixCAM2 用的就是 K230 芯片，但上层固件是 MaixPy，**不能直接用 CanMV/K230 SDK 的 kmodel**。

---

## 3. PC 侧 vs 板端分工（核心心智模型）

```
┌─────────────────────────────────────────┐    ┌─────────────────────────────────┐
│           PC 侧（训练 + 转换）          │    │       板端（仅推理）            │
│  通用 Python / GPU                      │    │  受限算力 / 专用 NPU            │
├─────────────────────────────────────────┤    ├─────────────────────────────────┤
│ • PyTorch / Ultralytics（训练）         │    │ • CanMV-MicroPython (K230)      │
│ • OpenCV / PIL（数据集预处理）          │    │ • MaixPy v4 (MaixCAM/Pro/2)     │
│ • onnx / onnxsim（中间格式）            │ →  │ • rknn-toolkit-lite2 (RK3588)   │
│ • nncase / tpu-mlir / pulsar2 /         │    │ • TensorRT runtime (Jetson)     │
│   rknn-toolkit2 / trtexec（转换器）     │    │ • cv2 板端 wheel（可选）        │
│ • Docker（隔离工具链版本）              │    │                                 │
│ • 大显存 / 大磁盘                        │    │ • RAM 通常 ≤ 8GB                │
└─────────────────────────────────────────┘    └─────────────────────────────────┘
            ↑                                            ↓
       完整 Python 生态                             仅平台特定 API
       通用算法库随便用                        + 量化后的 .kmodel/.rknn/.engine
```

**关键边界**：
- ✅ **PC 侧**：用 Ultralytics / OpenCV / PyTorch / 任何 pip 包，不受任何限制
- ✅ **板端**：只用平台官方 SDK（CanMV / MaixPy / rknnlite / TensorRT），通用 Python 库**未必有 ARM/RISC-V wheel**
- ❌ **不要**：试图在板端 `pip install ultralytics` 跑训练
- ❌ **不要**：试图在板端 `pip install torch` 做完整推理（用量化模型走 NPU 才高效）
- ⚠️ **特例**：Jetson Orin Nano Super 可以装 PyTorch（NVIDIA 提供 ARM wheel），但仍推荐用 TRT engine

### 3.1 "一键转换" vs "二段式转换"（**新手最易踩坑**）

通用框架自带的模型导出 ≠ 覆盖所有平台。**只有 Jetson / RK3588 能 Ultralytics 一键直达**，其余 3 个平台**必须走 ONNX 中间态**：

| 目标平台 | Ultralytics `yolo export` 一键？ | 必走路径 |
|---|---|---|
| **Jetson** (.engine) | ✅ `format=engine half=True` | 板上一行命令 |
| **RK3588** (.rknn) | ✅ `format=rknn name=rk3588 int8=True` | PC x86 Linux 一行命令 |
| **K230** (.kmodel) | ❌ | `yolo export onnx` → `nncase` 二段 |
| **MaixCAM/Pro** (.cvimodel) | ❌ | `yolo export onnx` → `tpu-mlir` (Docker) 二段 |
| **MaixCAM2** (.axmodel) | ❌ | `yolo export onnx` → `pulsar2` (Docker) 二段 |

**本 skill 把"二段式"封装到 `scripts\convert.py`**，你只需：

```bash
yolo export model=best.pt format=onnx opset=12 simplify=True imgsz=640 dynamic=False
python scripts\convert.py --target k230    --onnx best.onnx --calib data\calib\ --mode run
python scripts\convert.py --target maixcam --onnx best.onnx --calib data\calib\ --mode run
```

`--mode plan` 仅打印命令（默认，安全），`--mode run` 真跑（拉 Docker / 调 Python API）。

### 3.2 板端语言：Python 原型，C++ 量产

**模型工件与板端推理语言无关**——同一个 `.rknn` / `.engine` 在 Python 和 C++ 都能加载，不需要重转。

| 平台 | 模型工件 | Python binding | C/C++ binding（量产推荐） |
|---|---|---|---|
| K230 | `.kmodel` | CanMV `nncase_runtime` | K230 SDK C API |
| MaixCAM/Pro/MaixCAM2 | `.cvimodel`/`.axmodel` | MaixPy `maix.nn` | **MaixCDK**（API 与 MaixPy 几乎一致） |
| RK3588 | `.rknn` | `rknn-toolkit-lite2` | **rknpu2 C API**（延迟更低、易集成） |
| Jetson Orin Nano Super | `.engine` | `tensorrt` Python | **TensorRT C++ API**（量产标配 / DeepStream） |

**推荐路径**：原型用 Python（本 skill 的 templates 默认 Python）→ 上量产时用 C++ 重写推理 loop（**模型工件保持不变**）。各平台 C++ 集成示例：
- K230: `github.com/kendryte/k230_sdk` 内的 `src\big\nncase\...`
- MaixCAM: https://github.com/sipeed/MaixCDK
- RK3588: `airockchip/rknn_model_zoo/examples/yolo11/cpp/`
- Jetson: DeepStream-Yolo / 自写 TRT C++ inference loop

---

## 4. 工作流（5 步标准化）

```
[1] 平台探测 ──> [2] 环境检查 ──> [3] 模型转换 ──> [4] 部署上板 ──> [5] 板端验证
    detect.py     env_check.py    convert.py      deploy.py        camera_probe.py
                                                                   benchmark.py
```

每一步都对应一个 `scripts\*.py`，可独立运行也可串联。串联调用例（**通过 ssh-skill 别名，免记 IP**）：

```bash
# 一次性注册板子
python scripts\detect.py --host 192.168.1.30 --user rock --password rock \
    --register-as rk3588-lab           # 同时探测 + 写入 ssh-skill

# 之后所有操作只用别名
python scripts\env_check.py --target rk3588
python scripts\convert.py --target rk3588 --onnx yolo11n.onnx --calib data\calib\
python scripts\deploy.py --alias rk3588-lab --model yolo11n.rknn --remote /home/rock/
python scripts\camera_probe.py --alias rk3588-lab --target rk3588 --output probe.jpg
python scripts\benchmark.py --alias rk3588-lab --target rk3588 \
    --model /home/rock/yolo11n.rknn --imgsz 640 --iters 100
```

---

## 4. 推荐执行路径（按用户意图分流）

### 4.1 "我要把 YOLO 跑到 X 平台"（最常见）
1. 读取 `recipes\yolo_workflow.md`
2. 按 `platforms\<target>.md` 的转换章节执行
3. 用 `templates\<target>_yolo\` 脚手架启动板端代码
4. 出问题查 `knowledge\errors.md`

### 4.2 "模型转换报错了"
1. `grep` 报错关键字 → `knowledge\errors.md`
2. 不命中则查 `references\op_support.md`（算子兼容速查）
3. 仍未解决：参考 `references\upstream.md` 找上游 issue

### 4.3 "我要自定义训练再上板"
1. 训练侧用 Ultralytics 官方流程（`templates\` 内有 `train.md` 引导）
2. 导出 ONNX：`yolo export model=best.pt format=onnx opset=12 simplify=True`
3. 之后接 4.1 流程

### 4.4 "我要选型，对比 4 个平台"
1. 看 `references\version_matrix.md`（成本/性能/语言生态）
2. 跑 `scripts\benchmark.py` 在你已有的板子上自测
3. 4 个 templates 都用相同 YOLO11n 320×320 测，便于横评

### 4.5 "我要做非 YOLO 任务"（分类/分割/姿态/人脸）
1. 看 `recipes\yolo_workflow.md` 章末"非 YOLO 任务索引"
2. K230/MaixCAM：MaixHub 模型库直接拉
3. RK3588：`airockchip\rknn_model_zoo` 已覆盖检测/分割/OCR/人脸/车牌
4. Jetson：`dusty-nv\jetson-inference` Hello AI World

---

## 5. 自适应视觉框架（R3 — codex accept）

> 上面 1-4 节是"YOLO 部署脚手架"层，本节是"成熟视觉框架"层。
> 三轮擂台辩论记录见 `.iter\R1_proposal.md` / `R2_proposal.md` / `R3_proposal_final.md`。

### 5.1 三层自适应引擎

```
[L1 静态] policies/device_profile.yaml      → 5 平台硬件画像（出厂常量）
[L2 默认] policies/task_policy.yaml         → 3 任务 × 5 平台 → model/imgsz/quant/tracker
[L3 实测] tools/benchmark_tuner.py          → 候选剪枝≤6, early-stop → auto_tuned.yaml
                                              ↓
[运行时] runtime/scheduler.py                → FPS/温度/imgsz/跳帧/ROI 三动作
```

### 5.2 R3+R4 模块清单（含经典 CV 子包）

| 路径 | 作用 | 关键 |
|---|---|---|
| `algo/` | 统一插件（**对齐 supervision.Detections**） | `Detector` / `Tracker`(BoxMOT) / `OCRPipeline`(PaddleOCR) |
| **`algo/cv_classical/`** ★ | **经典 CV 算法库（18 模块 60+ 算法）** | **IPM 逆透视 / 车道线 / Hough / 形态学 / 光流 / 立体 / ArUco / HDR / 全景 / 标定 / 配准 / HOG**（详见 `algo/cv_classical/README.md`） |
| `adapters/` | 平台 pipeline 翻译器 | `k230_canmv` / `maixcam_maixpy` / `rk3588_gst` / `jetson_savant`(走 Savant 不重写) |
| `policies/` | 自适应核心配置 | device_profile + task_policy（schema 校验） |
| `model_zoo/manifest.yaml` | 模型 × 平台 × imgsz × mAP × 延迟矩阵 | |
| `runtime/scheduler.py` | AdaptiveScheduler | FPS EWMA → imgsz/skip/ROI |
| `tools/` | 离线 tuner | budget_pruner（理论≤18，启发式≤6）+ benchmark_tuner |
| `image_quality/` | 策略型增强 | isp_autotune（v4l2/nvargus）+ lowlight（gamma+CLAHE，无模型） |
| `eval/` | 评测 | COCO mAP + MOT（py-motmetrics optional） |
| `schema/pipeline_config.py` | dataclass 校验 | 6 字段，无 DSL |
| `apps/` | 完整闭环 demo | `traffic_count` + `ocr_meter` |

### 5.3 典型自适应工作流

```bash
# Step 1：默认配置（不需要 tuner，直接读 task_policy.yaml）
python schema/pipeline_config.py --validate policies/task_policy.yaml

# Step 2：看候选剪枝（codex 验收"可解释"）
python tools/budget_pruner.py --profile policies/device_profile.yaml \
    --platform rk3588 --task detection
# → 输出 12 候选 + 每个的 rationale（"NPU 6 TOPS → model yolo11s ..."）

# Step 3：实测 tune（需有板子）
python tools/benchmark_tuner.py --alias rk3588-lab --platform rk3588 \
    --task detection --target-fps 30
# → 生成 policies/rk3588_lab_auto_tuned.yaml（含可解释字段 + audit_trail）

# Step 4：跑 demo app（自适应 scheduler 在线运行）
python apps/traffic_count/main.py --platform rk3588 --source 11 \
    --model /home/rock/yolo11s.rknn --show
```

### 5.4 codex R3 验收标准（已通过）

> "同 task_policy.yaml 在 RK3588/Jetson/Maix 至少两平台生成不同执行路径，benchmark 选出可解释配置"

实际验证：同 `detection` task 对三平台产物：
- **RK3588**: `main.py` (cv2/GST 三线程) + `postprocess.py` + `labels.txt`
- **Jetson**: `main.py` (Ultralytics) + `savant.yml` (生产 pipeline)
- **K230**: `main.py` (CanMV MicroPython) + `model/` + `labels.txt`

三种完全不同的执行路径，由同一份配置驱动。

---

## 6. 目录速查（含 R3 新模块）

```
auto-vision\
├── SKILL.md                     ← 你正在看
├── algo\                        ★ R3 视觉算法插件（对齐 sv.Detections）
│   ├── base.py                  AlgoBase / DetectorBase / TrackerBase / OCRBase
│   ├── detection.py             YOLO 统一（ultralytics + rknnlite）
│   ├── tracking.py              BoxMOT (ByteTrack/BoT-SORT/OC-SORT) + ROI lite fallback
│   ├── ocr.py                   PP-OCR 两阶段
│   └── cv_classical\            ★ R4 经典 CV 18 模块 60+ 算法（含 IPM 逆透视）
│       ├── _utils.py            validate_image / capability_gate / has_cv_feature / make_result
│       ├── geometry.py          ★ IPM / homography / PnP / 文档矫正
│       ├── calibration.py       棋盘标定 / Undistorter / stereo / triangulate
│       ├── lane.py              ★ HLS+Sobel+IPM+滑动窗口+二次拟合 (gated)
│       ├── motion.py            LK / Farneback(gated) / DIS / MOG2 / Kalman2D
│       ├── stereo.py            BM / SGBM(gated→BM) / disparity_to_depth
│       ├── markers.py           ArUco / AprilTag 检测+生成+姿态
│       ├── stitching.py         Stitcher / HDR / triangulate / 白平衡 (gated)
│       ├── registration.py      findTransformECC / phaseCorrelate
│       ├── pyramid.py           pyrDown/Up / Laplacian / OF 金字塔
│       ├── filters.py / edges.py / morphology.py / shape.py
│       ├── features.py          Harris/FAST/ORB/AKAZE/SIFT/HOG/cornerSubPix
│       ├── matching.py          template/BF/FLANN/RANSAC
│       ├── segmentation_classical.py  watershed/GrabCut/颜色分割
│       └── quality.py           Laplacian variance/BRISQUE/亮度/对比度
├── adapters\                    ★ R3 平台 pipeline 翻译器
│   ├── maix_base.py             公共：MUD 生成 / 模型推送
│   ├── k230_canmv.py            K230 CanMV (MicroPython) 模板
│   ├── maixcam_maixpy.py        MaixCAM/Pro/2 MaixPy 模板
│   ├── rk3588_gst.py            RK3588 三线程 cv2/GST
│   └── jetson_savant.py         Jetson 走 Savant YAML + fallback main.py
├── policies\                    ★ R3 自适应配置
│   ├── device_profile.yaml      5 平台硬件画像
│   ├── task_policy.yaml         3 任务 × 5 平台
│   └── <device>_auto_tuned.yaml 由 tuner 自动生成
├── model_zoo\manifest.yaml      ★ R3 模型×平台 性能矩阵
├── runtime\scheduler.py         ★ R3 AdaptiveScheduler (FPS/imgsz/skip/ROI)
├── tools\                       ★ R3
│   ├── budget_pruner.py         候选剪枝（理论≤18，实际≤6）
│   └── benchmark_tuner.py       离线 tune + 可解释输出
├── image_quality\               ★ R3
│   ├── isp_autotune.py          v4l2-ctl / nvargus ISP 参数
│   └── lowlight.py              gamma + CLAHE（无模型）
├── eval\                        ★ R3
│   ├── eval_detection.py        COCO mAP
│   └── eval_mot.py              MOTA/IDF1（motmetrics optional）
├── schema\pipeline_config.py    ★ R3 dataclass 校验
├── apps\                        ★ R3 完整闭环 demo
│   ├── traffic_count\           detection + tracker + LineZone
│   └── ocr_meter\               YOLO ROI + PP-OCR 两阶段
├── platforms\                   平台专属文档（4 个）
│   ├── k230.md                  K230 + CanMV
│   ├── maixcam.md               MaixCAM-Pro + MaixCAM2 合并
│   ├── rk3588.md                RK3588 / RK3576
│   └── jetson.md                Orin Nano Super 8GB
├── scripts\                     可执行工具（Python 3.10+）
│   ├── detect.py                平台自动探测
│   ├── env_check.py             SDK 版本兼容矩阵校验
│   ├── convert.py               统一前端：dispatch 到平台
│   ├── deploy.py                SSH 部署 + 启动
│   ├── camera_probe.py          板端摄像头自检
│   └── benchmark.py             统一性能采集
├── recipes\                     高级配方
│   ├── yolo_workflow.md         端到端 YOLO 流程
│   ├── quantization.md          PTQ 校准实操
│   └── debug_workflow.md        通用调试方法
├── templates\                   项目脚手架（每平台一套，5 分钟跑通）
│   ├── k230_canmv_yolo\
│   ├── maixpy_yolo\
│   ├── rk3588_yolo\
│   └── jetson_yolo\
├── references\                  长查询文档（按需 Read）
│   ├── upstream.md              ★ 所有上游开源 repo 索引
│   ├── version_matrix.md        SDK / 工具链 / 固件版本对应
│   └── op_support.md            4 平台算子兼容速查
└── knowledge\
    └── errors.md                报错→根因→修复
```

---

## 6. 与本仓库其他 skill 的协作关系（★ 强制约束）

**所有 SSH 操作必须走 `ssh-skill`**，不直接用 `ssh` / `scp` / `paramiko`。
本 skill 内的 `scripts\deploy.py / camera_probe.py / benchmark.py` 已经按这个原则封装：

| 场景 | 必须调用的 skill / 命令 |
|---|---|
| **首次发现板子 → 注册别名** | `scripts\detect.py --host <ip> --register-as <alias>` → 内部调 `ssh-skill\scripts\ssh_config_manager_v3.py create` |
| **远端执行命令** | `ssh-skill\scripts\ssh_execute.py <alias> "<cmd>"` |
| **上传文件 / 目录** | `ssh-skill\scripts\ssh_upload.py <alias> <local> <remote>`（路径前缀 `MSYS_NO_PATHCONV=1`） |
| **下载文件** | `ssh-skill\scripts\ssh_download.py <alias> <remote> <local>` |
| **多板批量** | `ssh-skill\scripts\ssh_cluster.py "<cmd>" --tags ai-vision-board --parallel` |
| **隧道访问板上 web (DeepStream / MaixVision)** | `ssh-skill\scripts\ssh_tunnel.py start <alias> --remote-port 8080` |
| K230 串口日志抓取 | `serial-monitor` |
| 板端摄像头 / I2C 外设驱动 | `peripheral-driver` |
| K230 SDK 重新编译（很少需要） | `build-cmake` |
| 通用流程编排 | `embedded-dev`（仅当多 skill 协作时） |

**为什么强制走 ssh-skill**：
- 守护进程长连接（~0.12s vs paramiko 直连 ~0.45s），跑 benchmark / 多次部署效率提升数倍
- 自动重连、心跳检测、跳板机支持
- 多板别名管理统一（`k230-01` / `maixcam2-lab` / `rk3588-prod` / `jetson-dev`），免记 IP
- 按 tags 批量操作：`--tags rk3588` 一次跑遍所有 RK3588 板

**典型首次接入流程**：
```bash
# 1. 探测并注册到 ssh-skill
python scripts\detect.py --host 192.168.1.30 --user rock --password rock \
    --register-as rk3588-lab

# 2. 之后所有操作走别名
python scripts\camera_probe.py --alias rk3588-lab --target rk3588 --output probe.jpg
python scripts\deploy.py --alias rk3588-lab --model yolo11n.rknn --remote /home/rock/
python scripts\benchmark.py --alias rk3588-lab --target rk3588 --model /home/rock/yolo11n.rknn
```

---

## 7. 复用 vs 自研边界（务必遵守）

**✅ 必须复用（不要重写）**：
- `ultralytics` 训练 / export 流程
- 官方转换工具：`nncase` / `nncase-kpu` / `tpu-mlir` / `pulsar2` / `rknn-toolkit2` / `trtexec`
- 官方 model zoo：`airockchip\rknn_model_zoo`、`kendryte\K230_training_scripts`、MaixHub、`dusty-nv\jetson-inference`
- 容器：`dustynv\*` Jetson 容器、官方 docker 镜像

**✏️ 本 skill 自研（胶水层）**：
- 平台探测脚本、版本矩阵 yaml
- 校准数据集组织 + 精度对比报告
- SSH 部署器（薄包装 paramiko）
- benchmark 报告模板
- 错误根因知识库

**❌ 不要做**：
- 重写推理 runtime
- 改 ONNX/PyTorch 模型结构（除非平台明确要求）
- 隐藏量化精度损失
- 跨平台运行时抽象（坑大于收益）

---

## 8. PC 端推荐环境（本机已验证）

本机推荐使用 conda 环境 **`yolo_env`** 作为 PC 训练 / 转换默认环境：

```bash
conda activate yolo_env       # 已装 PyTorch 2.6+CUDA 12.4 / Ultralytics 8.4 / ONNX / onnxsim / paramiko
```

完整路径：`C:\ProgramData\miniconda3\envs\yolo_env\python.exe`（Python 3.10.19）

若需直接调用（如 Windows cmd 没 `conda activate`）：
```bash
& "C:\ProgramData\miniconda3\envs\yolo_env\python.exe" scripts\convert.py ...
```

或在 VSCode `.vscode\settings.json` 中：
```json
{"python.defaultInterpreterPath": "C:\\ProgramData\\miniconda3\\envs\\yolo_env\\python.exe"}
```

`env_check.py` 会自动检测当前是否在 yolo_env，不在则给出切换提示。

---

## 9. 快速开始（新手 5 分钟）

```bash
# 0. 切到推荐环境
conda activate yolo_env

# 1. 探测你手头的板子
python scripts\detect.py

# 2. 假设探测到 rk3588，看专属文档
# → 阅读 platforms\rk3588.md

# 3. 跑脚手架（已自带 yolo11n.rknn 预转模型 + 板端推理脚本）
# → 阅读 templates\rk3588_yolo\README.md

# 4. 想自己训练并上板
# → 阅读 recipes\yolo_workflow.md
```

---

## 9. 版本声明

- skill 版本：0.1.0
- 基线工具链版本（2026-05）：
  - `nncase` 2.9.x / 2.10.x（K230）
  - `tpu-mlir` 最新 dev（MaixCAM）
  - `pulsar2` 最新 dev（MaixCAM2）
  - `rknn-toolkit2` 2.3.x（RK3588）
  - JetPack 6.1 / 6.2 + TensorRT 10.x（Orin Nano Super）
  - `ultralytics` ≥ 8.3
- 详细版本对应见 `references\version_matrix.md`