公安视频分析师 (Surveillance Video Analyst)

---
name: 公安视频分析师 (Surveillance Video Analyst)
description: >
  在监控视频中按文字描述、人脸照片或人体照片定位嫌疑人/嫌疑车辆。全本地处理,
  可选 GLM 视觉 API 增强。Mac (Apple Silicon MPS, 已验证) 和 Windows (CUDA/CPU,
  已适配) 跨平台。首次使用时自动引导下载模型。图形界面优先。
profession: 公安视频分析师
platform: Mac (Apple Silicon MPS, 已验证) / Windows (CUDA/CPU, 已适配)
inputs: text description | face photo | body photo
---

<!-- zh -->
# 📹 公安视频分析师

在监控视频中按 **文字描述**、**人脸照片** 或 **人体照片** 定位嫌疑人/嫌疑车辆/可疑物品。
输出:时间戳范围、每帧包围框(BBox)轨迹、标注视频。
<!-- /zh -->
<!-- en -->
# 📹 Surveillance Video Analyst

Locate suspects / suspect vehicles / suspicious objects in surveillance video by
**text description**, **face photo**, or **body photo**.
Outputs: timestamp intervals, per-frame bounding-box trajectories, annotated video.
<!-- /en -->


<!-- zh -->
## 🔒 隐私声明 (公安必读)

**视频文件、人脸嵌入、人体嵌入全部在本机处理,绝不上传到任何服务器。**
仅以下两种可选场景会发送**少量**裁切图(几十张)到智谱 GLM API:
- `--use-vlm` 模式(复杂属性识别,如"穿米色大衣的人")
- 人脸/人体搜索的 VLM 降级模式(当本地后端都不可用时)

**公安场景建议**:纯本地模式完全可用;如需启用 VLM 模式,请按单位审批流程操作。
获取 GLM API key:https://open.bigmodel.cn/ → 注册 → API 管理
<!-- /zh -->
<!-- en -->
## 🔒 Privacy (read this first)

**Video files, face embeddings, and body embeddings are processed entirely on-device
and never leave the machine.** Only the following optional modes send a **small**
number of cropped frames (dozens) to the Zhipu GLM API:
- `--use-vlm` mode (complex attribute queries like "person in beige coat")
- Person/face search VLM fallback (when no local backends are available)

**For law enforcement**: pure local mode is fully usable without any API key.
If VLM mode is needed, follow your unit's approval process.
Get a GLM API key: https://open.bigmodel.cn/
<!-- /en -->


<!-- zh -->
## 🖥️ 平台状态

| 平台 | 状态 | 备注 |
|---|---|---|
| **Mac (Apple Silicon)** | ✅ 已验证 | MPS GPU 加速,约 25fps |
| **Windows (NVIDIA GPU)** | ⚠️ 已适配 | CUDA 加速;GPU 路径需本机验证(CPU 已验证) |
| **Windows (仅 CPU)** | ⚠️ 已适配 | 可用,但较慢(~1–2 fps) |

安装脚本会自动检测系统、GPU、Python 环境并选择最优配置。
<!-- /zh -->
<!-- en -->
## 🖥️ Platform Status

| Platform | Status | Notes |
|---|---|---|
| **Mac (Apple Silicon)** | ✅ Verified | MPS GPU acceleration, ~25fps |
| **Windows (NVIDIA GPU)** | ⚠️ Adapted | CUDA acceleration; GPU path needs on-machine verification (CPU verified) |
| **Windows (CPU only)** | ⚠️ Adapted | Usable but slower (~1–2 fps) |

The setup script auto-detects OS, GPU, and Python environment and picks the best config.
<!-- /en -->


<!-- zh -->
## 🚀 安装 (交给你的 AI 助手)

**把下面这句话复制,粘贴到 Claude Code / Codex / OpenClaw 或任何支持 SKILL.md 的 AI 助手的对话框里:**

```
你是一名公安视频分析师。安装方法:
1. 下载引擎包 https://updating.cc/skills/video-target-localize/video-target-localize.tar.gz
   并解压到本地技能目录(如 ~/.claude/skills/video-target-localize/)
2. 在该目录运行 python setup.py --yes
   (它会自动检测系统/GPU、创建虚拟环境、安装依赖、下载模型并做冒烟测试)
3. 再获取 https://updating.cc/api/skills/surveillance 中的职业说明 SKILL.md,
   按其图形界面优先的流程工作。
4. 完成后告诉用户:双击「启动控制台.command」(Mac)或「启动控制台.bat」(Windows)即可使用。
```

助手会自动:
- 从 updating.cc 下载并解压包含所有引擎脚本的安装包(模型权重由 `setup.py` 下载)
- 运行 `setup.py --yes` (自动创建 venv、安装依赖、下载模型、冒烟测试)
- 告诉你如何启动图形界面
<!-- /zh -->
<!-- en -->
## 🚀 Installation (give this to your AI agent)

**Copy this sentence and paste it into Claude Code / Codex / OpenClaw or any agent that supports SKILL.md:**

```
You are a Surveillance Video Analyst. Install as follows:
1. Download the engine package https://updating.cc/skills/video-target-localize/video-target-localize.tar.gz
   and extract it into your local skills directory (e.g. ~/.claude/skills/video-target-localize/)
2. In that directory, run python setup.py --yes
   (it will auto-detect OS/GPU, create a venv, install dependencies, download models, and run a smoke test)
3. Then fetch the profession SKILL.md from https://updating.cc/api/skills/surveillance
   and follow its GUI-first workflow.
4. When done, tell the user: double-click 启动控制台.command (Mac) or 启动控制台.bat (Windows) to launch.
```

The agent will:
- Download and extract the engine package from updating.cc (model weights are downloaded by `setup.py`)
- Run `setup.py --yes` (creates venv, installs deps, downloads models, smoke tests)
- Tell you how to launch the GUI
<!-- /en -->


<!-- zh -->
## 🎯 使用 (图形界面优先)

安装完成后,**双击 `启动控制台.command` (Mac) 或 `启动控制台.bat` (Windows)**。
浏览器会自动打开 http://127.0.0.1:7878 — 这就是你的视频检索控制台。

### 三步流程

**① 选视频** — 点击「浏览…」或拖放监控视频文件到视频路径栏。

**② 选模式** — 控制台顶部有引导条,点击下面的模式按钮切换:

| 模式 | 用途 | 输入 |
|---|---|---|
| 📝 **文字找人/车** | "找到穿红色外套的人"、"白色轿车" | 自然语言描述 |
| 🔍 **标识(车牌等)** | "车牌号京P3LD03 的白色小轿车" | 含具体标识的描述 |
| 🧍 **以图搜人** | "用这张嫌疑人照片在视频里找到这个人" | 人脸/人体照片 |

**③ 运行 → 看结果** — 点击「运行 Run」,等待处理完成。结果面板显示:
- **时间区间表** — 目标出现的所有时间段 (start_s → end_s)
- **命中标注帧** — 每个匹配时间段的最佳标注截图(绿框+标签+时间戳)
- **metrics JSON** — 覆盖率、处理帧率、内存占用等

### 视频格式预检 (强烈建议先运行)

很多 NVR/DVR 导出的视频(`.dav`、加密 `.mp4`、IMKH 格式)OpenCV 读不出真实帧,但不会报错 — 会返回全黑或条纹画面,引擎以为"目标不存在"。

**使用控制台里的「Preflight 预检」标签**:选择视频,点击「运行预检」。
- `OK` → 直接使用原视频
- `SUSPECT` → 查看样帧,确认画面正常
- `UNREADABLE` → 控制台自动恢复为干净的 mp4,点击「用恢复后的 mp4 填充」即可
<!-- /zh -->
<!-- en -->
## 🎯 Usage (GUI-first)

After installation, **double-click `启动控制台.command` (Mac) or `启动控制台.bat` (Windows)**.
The browser opens http://127.0.0.1:7878 — your video retrieval console.

### Three-step workflow

**① Pick video** — click "Browse…" or drag-drop a surveillance video into the video path field.

**② Pick mode** — the wizard strip at the top has mode buttons:

| Mode | Use case | Input |
|---|---|---|
| 📝 **Text** | "find the person in the red coat", "white car" | natural language description |
| 🔍 **Identifier** | "white car with plate 京P3LD03" | description with specific identifier |
| 🧍 **By photo** | "find this person from their photo in the video" | face / body photo |

**③ Run → view results** — click "Run". The results panel shows:
- **Intervals table** — all time ranges where the target appears (start_s → end_s)
- **Annotated hits** — best annotated frame per matched interval (green box + label + timestamp)
- **metrics JSON** — coverage, processing fps, memory usage, etc.

### Video preflight (strongly recommended first)

Many NVR/DVR exports (`.dav`, encrypted `.mp4`, IMKH format) cannot be decoded by
OpenCV but don't report errors — they return all-black or striped frames, and the
engine thinks "target absent".

**Use the "Preflight" tab in the console**: pick a video, click "Run preflight".
- `OK` → use the original video
- `SUSPECT` → eyeball the sample frame
- `UNREADABLE` → the console auto-recovers to a clean mp4; click "use recovered mp4"
<!-- /en -->


<!-- zh -->
## 📋 三种模式详解

### 📝 文字描述定位 (Locate 引擎)
**用途**:通用目标 — "穿红色外套的人"、"白色轿车"、"骑电动车的人"
**技术**:YOLO-World 开放词汇检测 + BoT-SORT 多目标跟踪 + 可选 GLM-VLM 稀疏增强

**适合**:外观描述清楚、没有具体标识(车牌号、姓名)的场景。

### 🔍 标识验证 (Verify 引擎)
**用途**:具体标识 — "车牌号京P3LD03"、"背着红色双肩包的人"(当场景里有多个相似目标时)
**技术**:两阶段 — 先检测所有候选,再用 GLM-VLM 逐个读取标识

**为什么不能直接用 Locate?** Locate 引擎只会在第一帧选一个种子然后盲目跟踪;在多个相似目标(多辆白车)场景下,会跟踪到错误的目标并漂移。Verify 引擎会重新读取每个候选的标识,准确率更高。

### 🧍 以图搜人 (Person Search 引擎)
**用途**:给定嫌疑人照片,在视频中找到这个人的所有出现帧
**技术**:自动从参考图选取主体(人脸优先,否则人体) → 本地嵌入匹配(insightface ArcFace / OSNet ReID / CLIP) → VLM 降级
**重要**:参考照片需要是**包含人脸的大图**(如证件照、半身照),不能用抠出来的纯脸小块 — 本地后端需要自己检测人脸位置。
<!-- /zh -->
<!-- en -->
## 📋 Three modes in detail

### 📝 Text (Locate engine)
**Use**: general targets — "person in red coat", "white car", "person on e-bike"
**Tech**: YOLO-World open-vocabulary grounding + BoT-SORT multi-target tracking + optional GLM-VLM sparse enhancement

**Best for**: clear appearance descriptions without specific identifiers (plates, names).

### 🔍 Identifier (Verify engine)
**Use**: specific identifiers — "plate 京P3LD03", "person with red backpack" (when there are multiple similar targets in the scene)
**Tech**: two-stage — detect all candidates, then GLM-VLM verifies each one by reading the identifier

**Why not just use Locate?** Locate picks ONE seed on the first frame and tracks blindly; in scenes with similar targets (several white cars), it latches onto the wrong one and drifts. Verify re-reads the identifier on every candidate, much more accurate.

### 🧍 By photo (Person Search eng