video-product-finder/README.md

# video-product-snapshot — 视频商品截图

检测视频中的电商商品，提取最佳商品画面，并通过图片搜索在 1688 找同款。

## 工作原理

1. 使用 `ffmpeg` 按配置间隔从视频抽帧
2. 将每帧发给视觉模型，检测是否有商品并评分
3. 选出置信度最高的帧作为最佳商品截图
4. 可选：用这张截图调用图片搜索 API 找同款商品

## 安装

```bash
bun install
bun run build        # 输出到 dist/run.js
```

## 使用方法

```bash
bun dist/run.js <command> [options]
```

### 命令

| 命令 | 说明 |
|------|------|
| `detect <video>` | 抽帧并检测商品画面 |
| `search <image>` | 用图片搜同款 |
| `detect-and-search <video>` | 完整流程：检测最佳画面 → 搜图 |
| `session` | 打印当前认证 session token |

### 选项（`detect` / `detect-and-search`）

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--interval=<秒>` | `1` | 抽帧间隔（秒） |
| `--max-frames=<数量>` | `60` | 最多分析帧数 |
| `--output-dir=<目录>` | 视频所在目录 | 抽帧图片保存目录 |
| `--min-confidence=<0-1>` | `0.7` | 最低检测置信度 |
| `--dry-run` | — | 解析参数并打印配置，不实际执行 |

### 示例

```bash
# 检测商品，每 3 秒抽一帧
bun dist/run.js detect ./demo.mp4 --interval=3

# 完整流程 + 更高置信度门槛
bun dist/run.js detect-and-search ./demo.mp4 --interval=5 --min-confidence=0.85

# 用已有截图搜同款
bun dist/run.js search ./snapshot.jpg
```

## 输出

所有命令输出 JSON 到 stdout。

```json
{
  "bestSnapshot": {
    "frameIndex": 4,
    "timestampSeconds": 9,
    "imagePath": "/path/to/frame_0004.jpg",
    "confidence": 0.92,
    "description": "White sneaker with blue logo, left side view",
    "boundingHint": "centered"
  },
  "productFrames": [...],
  "searchBody": { ... }
}
```

- `productFrames` — 所有检测到的画面，按置信度排序（最高在前）
- `bestSnapshot` — 排名第一的画面
- `searchBody` — 图片搜索 API 的返回（仅 `search` / `detect-and-search`）

## 环境变量

唯一必需配置是 `~/.openclaw/.env` 中的 `CLIENT_KEY`：

```
CLIENT_KEY=sk_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx
```

所有凭据和接口地址通过 `auth-rt` 从客户端配置自动获取，无需额外配置。

### 可选覆盖

| 变量 | 说明 |
|------|------|
| `VISION_MODEL` | 覆盖模型名称（默认：`aliyun-cp-multimodal`） |
| `AUTH_RT_BIN` | 覆盖 `auth-rt` 二进制路径 |
| `TELEMETRY_ENDPOINT` | 上报执行结果到遥测接口 |

## 前置依赖

- [Bun](https://bun.sh) 运行时
- 系统 PATH 中包含 `ffmpeg` 和 `ffprobe`
- 系统 PATH 中包含 `auth-rt` CLI（`search` / `detect-and-search` 需要）