# PRD_05：Device 侧轻量级 Tracker 节点（可插拔）

## 1. 背景与问题

当前 Device 侧媒体服务采用“配置驱动 DAG（Graph）+ 插件节点（Node）+ SPSC 队列”的流水线架构：输入（RTSP/文件）→ 预处理 → AI 推理（检测/识别等）→ OSD/推流/告警。

在实际部署中常见三类痛点：

1) **重复报警**：同一目标在画面连续出现时，规则可能在采样频率下重复触发。
2) **重复上传（MinIO/HTTP 等）**：报警动作触发后在短时间内重复上传同类素材。
3) **推理开销过高**：虽然已有 `infer_fps` 等限频，但在低推理频率下希望仍保持事件稳定性与可解释性。

现有代码中：

- `Frame::det`（`DetectionResult`）包含 `Detection{cls_id, score, bbox, track_id}`，其中 `track_id` 当前默认 `-1`（未做追踪）。
- `alarm` 侧已有 `rules.cooldown_ms`、`min_duration_ms` 与 `actions.*.min_interval_ms` 的时间窗限流，但属于“按规则/动作的时间窗”粒度。

## 2. 目标（Goals）

提供一个 **可选、可插拔** 的 `tracker` 插件节点，用于为检测结果补充稳定的 `track_id`，以支持：

1) **按目标实例去重**（基于 `track_id`）：同一目标在持续存在期间不重复触发/上传。
2) **稳定性/精准性优先，资源占用尽可能低**：不引入 ReID/特征网络，主要使用几何与置信度关联。
3) **按类别选择性追踪**：并非所有类别都追踪，可由配置指定哪些 `cls_id` 参与追踪。
4) **架构适配**：完全符合现有 Graph/Node 插件机制，插入与否由 `configs/*.json` 决定；不插入则不改变任何行为。

## 3. 非目标（Non-Goals）

1) 不做跨摄像头/跨 Graph 的关联（不做全局 ID）。
2) 不做基于外观特征（ReID）的强一致性追踪（如 DeepSORT+ReID）。
3) 不保证对极端遮挡/快速运动/密集重叠场景达到 SOTA 跟踪指标；本 PRD 目标是“工程可用+低资源”。

## 4. 现有架构约束（必须遵守）

1) Node 单输入、多输出：Graph 当前限制每个节点 **只能有一个 input queue**。
2) Node 的 `Process(FramePtr)` 由框架线程调用（`Graph::Start()` 中的 worker loop），Tracker 节点不应引入额外线程（除非明确需求）。
3) Tracker 节点不得破坏 `Frame` 上其他元信息（尤其是 `publish` 节点可能写入 `frame->user_meta` 用于 clip）。

## 5. 功能设计

### 5.1 节点定义

- Node type：`tracker`
- role：`filter`
- 输入：`FramePtr`（读取 `frame->det`）
- 输出：同一个 `FramePtr`（仅可能修改 `frame->det->items[*].track_id`）
- 当 `frame->det == nullptr` 或 `items` 为空：直接透传。

### 5.2 追踪算法（推荐：ByteTrack-lite + IOU 关联）

在不引入外观特征的前提下，为提高稳定性，采用“两段式关联”策略：

**核心思想**：

1) 将 det 按置信度分成高置信（`score >= high_th`）与低置信（`low_th <= score < high_th`）。
2) 优先用高置信 det 去匹配已有 tracks；未匹配的 tracks 再用低置信 det 做二次匹配（减少断轨）。
3) 匹配度量使用 IOU（可加入 gating：中心点距离/面积比等轻量约束）。

**匹配策略**：

- 为降低资源占用：默认使用 greedy matching（按 IOU 从高到低选择不冲突匹配），不强制使用匈牙利算法。
- 允许后续通过配置切换到 Hungarian（可选增强项），但不作为本 PRD 必需。

**Track 生命周期**：

- 创建：未匹配到现有 track 的高置信 det → 创建新 track。
- 更新：匹配成功 → 更新 bbox、last_seen、hit_streak。
- 丢失：超过 `max_age_ms`（或 `max_age_frames`）未匹配 → 删除。

**分类策略**：

- 默认按 `cls_id` 分组匹配（避免不同类别互相抢 track）。
- 可配置 `per_class=false` 以允许跨类别匹配（默认不建议）。

### 5.3 按类别选择性追踪

支持以下配置（至少实现其一，推荐两者都实现）：

- `track_classes`: `int[]`：白名单。非空时仅追踪这些 `cls_id`。
- `ignore_classes`: `int[]`：黑名单。用于排除某些 `cls_id`。

规则：

- 若 `track_classes` 非空，则优先按白名单过滤。
- 否则按 `ignore_classes` 排除。
- 未参与追踪的 det 必须保持 `track_id = -1`。

### 5.4 按模型类型/推理类型启用（可选，但推荐）

`DetectionResult.model_name` 已存在，Tracker 支持：

- `allowed_models`: `string[]`：当非空时，仅对 `model_name` 在集合内的帧启用。

用途：同一 pipeline 可能挂多种推理节点（yolo/face_det/自定义模型），避免对不需要的输出做追踪。

### 5.5 插入位置建议（不强制）

1) 仅为“告警去重/上传去重”服务：
   - 推荐 `publish -> tracker -> alarm`
   - 原因：不影响推流；不破坏 `publish` 写入的 `frame->user_meta`（clip 仍可用）。
2) 需要 OSD 展示稳定 ID：
   - 推荐 `ai_* -> tracker -> osd -> ...`

## 6. 配置（Config Schema）

### 6.1 tracker 节点配置字段

节点 JSON 示例：

```json
{
  "id": "trk_cam1",
  "type": "tracker",
  "role": "filter",
  "enable": true,
  "mode": "bytetrack_lite",
  "per_class": true,
  "track_classes": [0, 2, 3],
  "ignore_classes": [],
  "allowed_models": ["yolov5", "yolov8"],

  "high_th": 0.5,
  "low_th": 0.1,
  "iou_th": 0.3,

  "max_age_ms": 1500,
  "min_hits": 2,
  "max_tracks": 128,

  "debug": {
    "stats": true,
    "stats_interval": 200
  }
}
```

字段说明：

- `mode`：`"off" | "bytetrack_lite"`（最少实现这两种）
- `per_class`：默认 `true`。
- `track_classes`：白名单；默认空（表示全类别）。
- `ignore_classes`：黑名单；默认空。
- `allowed_models`：默认空（表示不过滤）。
- `high_th/low_th`：置信度分段阈值。
- `iou_th`：匹配阈值。
- `max_age_ms`：track 允许丢失的时间窗口（基于 `frame->pts` 计算；若 pts 无效则可退化为帧计数）。
- `min_hits`：一个 track 连续命中次数达到后才“稳定输出”（用于减少误检带来的短暂 track）。
- `max_tracks`：上限保护，避免极端场景内存增长。

### 6.2 Graph 接入示例

在现有 graph 中插入（示例：`pub -> tracker -> alarm`）：

```json
"nodes": [
  {"id":"pub_cam1","type":"publish","role":"filter","enable":true, ...},
  {"id":"trk_cam1","type":"tracker","role":"filter","enable":true, ...},
  {"id":"alarm_cam1","type":"alarm","role":"sink","enable":true, ...}
],
"edges": [
  ["post_cam1","pub_cam1"],
  ["pub_cam1","trk_cam1"],
  ["trk_cam1","alarm_cam1"]
]
```

## 7. 对外接口与数据契约

### 7.1 输入输出契约

- 输入：`frame->det` 必须由上游检测节点填充；Tracker 不负责生成 det。
- 输出：
  - `frame` 本体不变；
  - `frame->det->items[*].track_id` 可能从 `-1` 变为 `>=0`；
  - 不修改 `frame->user_meta`、不修改 `frame->data/planes`。

### 7.2 与 alarm/http/minio 的配合

- `plugins/alarm/actions/http_action.cpp` 已会输出 `track_id` 字段（现有实现），因此 Tracker 生效后 HTTP 报警可以自然携带 `track_id`。
- MinIO 上传去重当前依赖 `actions.*.min_interval_ms`；后续可扩展为 per-track 去重（见第 10 节增强建议）。

## 8. 指标与可观测性

### 8.1 Custom Metrics

Tracker 节点建议实现 `GetCustomMetrics()` 输出：

- `tracks_active`
- `tracks_created_total`
- `tracks_removed_total`
- `matched_total`
- `unmatched_dets_total`
- `avg_process_time_ms`

### 8.2 Debug

- `debug.stats`：周期打印关键统计。
- 不输出过多 per-frame 日志，避免影响实时性。

## 9. 性能与资源约束

目标（以单路为单位，具体需实测校准）：

- `N_det <= 64` 时，每帧 Tracker 处理耗时应为毫秒级以下（通常 < 1ms，依平台不同）。
- 内存：track 状态结构固定上限 `max_tracks`，避免无界增长。

## 10. 验收标准（Acceptance Criteria）

1) **可插拔**：不配置 `tracker` 节点时，系统行为与当前版本一致。
2) **正确写入 track_id**：配置启用时，目标类别的 det `track_id` 在连续帧中稳定且可复用。
3) **按类别控制有效**：不在白名单/在黑名单的 `cls_id` 必须保持 `track_id=-1`。
4) **稳定性**：短暂漏检场景下（`max_age_ms` 内），track 不应频繁抖动创建新 ID。
5) **资源可控**：`max_tracks` 生效；极端场景不会导致内存持续增长。

## 11. 开发拆解（实现步骤）

1) 新增插件目录与编译接入：`plugins/tracker/`，更新 `plugins/CMakeLists.txt` 注册编译。
2) 实现 `TrackerNode`：
   - `Init()` 解析配置。
   - `Process()`：过滤模型/类别 → 运行 ByteTrack-lite → 写 `track_id` → 推送下游。
   - `UpdateConfig()`：支持热更新（可退化为“关键字段变更则拒绝原地更新”）。
   - `GetCustomMetrics()`：输出统计。
3) 增加一个示例配置（不强制提交到 README）：可在现有 `configs/*` 中添加一份测试 json（若产品流程允许）。

## 12. 增强建议（不属于本 PRD 必做，但推荐路线）

1) **Alarm 去重升级为 per-track**：在 `alarm` 节点内部维护 `(rule_name, track_id)` 的冷却/状态机（enter/stay/leave）。
2) **自适应推理频率**：结合最近 N 秒的命中情况动态调整 `infer_fps`（需与现有热更新机制配合）。
3) **Hungarian 可选开关**：当 det 数量大且遮挡多时提升一致性，但要评估 CPU 成本。