video-product-finder/SKILL.md

---
name: video-product-snapshot
description: "Extract product snapshot from video and search 1688 by image. / 从视频中提取最佳商品帧，以图搜图在1688找同款。当用户提供视频想找商品时使用。"
---

# Video Product Snapshot — 视频商品以图搜图

从视频中截取最清晰的商品帧（容器类产品自动选空载帧），上传图片在 1688 以图搜图找同款。

## 运行

```bash
bun dist/run.js <command> [args] [--dry-run]
```

## 命令列表

| 命令 | 使用场景 |
|------|---------|
| `detect-best-and-search <video>` | **推荐。** 提取最佳商品帧 → 图搜 → rerank 返回结果。 |
| `detect-best <video>` | 只提取最佳商品帧，不搜图。 |
| `detect-and-search <video>` | 两阶段过滤后图搜（比 detect-best 慢）。 |
| `search <image-path>` | 已有商品图，直接图搜。 |
| `rerank` | 用关键词对图搜结果交叉过滤。 |
| `session` | 获取当前认证会话 token。 |

## 主命令：`detect-best-and-search`

流程：
1. ffmpeg 按 0.5s 间隔提取帧（最多 60 帧）
2. 视觉模型检测是否为容器/架子类产品
3. 容器类：只从前 40% 帧（空载阶段）中选最佳帧
4. 非容器类：全帧中选最清晰帧
5. 裁剪商品区域
6. 上传裁剪图 → 1688 图搜
7. rerank：图搜结果与关键词搜索结果交叉过滤

## Options for `detect-best` / `detect-best-and-search`

| Flag | Default | Description |
|------|---------|-------------|
| `--interval=<sec>` | `0.5` | 帧采样间隔（秒） |
| `--max-frames=<n>` | `60` | 最大分析帧数 |
| `--output-dir=<dir>` | 视频同目录 | 截图保存目录 |

## 输出格式

### `detect-best-and-search`

```json
{
  "bestSnapshot": {
    "frameIndex": 7,
    "timestampSeconds": 3,
    "imagePath": "/path/to/frame_0007.jpg",
    "croppedImagePath": "/path/to/frame_0007_cropped.jpg",
    "description": "黑色金属床底鞋架 可折叠移动"
  },
  "rerank": {
    "keyword": "床底鞋架",
    "results": [
      { "num_iid": 123, "title": "...", "price": "44.00", "sales": 87, "detail_url": "..." }
    ]
  }
}
```

## 结果展示格式

将 `rerank.results`（优先）或 `searchBody.data.items.item` 格式化为 markdown 表格，**每页 5 行**：

| # | 商品名称 | 价格 | 销量 | 链接 |
|---|----------|------|------|------|
| 1 | {title}  | ¥{promotion_price \|\| price} | {sales ?? —}件 | [查看]({detail_url}) |

- 有 `promotion_price` 用促销价，否则用原价
- `sales` 缺失或为零时显示 `—`
- 始终用 markdown 表格展示，不要用列表

## 执行规则

1. **不要重试。** 命令失败就直接报错。
2. **信任工具输出。** CLI 内部已处理 session 管理和错误格式化。
3. **慢命令用 sub-agent**（detect-best-and-search / detect-and-search），直接运行会超时。

### sub-agent 执行模板

```
sessions_spawn(
  task: "cd /path/to/skill && Run this command and return the raw JSON output:\n\nbun dist/run.js detect-best-and-search <video-path>\n\nCopy the entire JSON output as your reply.",
  label: "video-product-snapshot",
  runTimeoutSeconds: 300,
)
```