video-product-finder/SKILL.md

---
name: video-product-snapshot
description: "Detect ecommerce products in video frames using Claude Vision, extract the best product snapshot, and optionally search via image-search API. Use when the user provides a video and wants to find/identify products shown in it. / 检测视频中的商品，提取最佳商品截图，并通过图片搜索在1688找同款。当用户提供视频想找商品时使用。"
---

# Video Product Snapshot — 视频商品截图

从视频中提取最佳商品画面，通过 Claude Vision 检测并截取，然后在 1688 上以图搜图 + 关键词重排序找到同款商品。

## 运行

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

## 命令列表

| 命令 | 使用场景 |
|------|---------|
| `detect-video-and-search <video>` | **推荐。** 直接上传视频到 API 识别商品主体，然后 1688 关键词搜索。跳过本地抽帧，无需 Vision API。 |
| `detect-best-and-search <video>` | 旧版。抽帧 + Vision 排名 + 搜图。需要 Vision API key。 |
| `detect-video <video>` | 只识别商品描述和生成关键词，不搜图。 |
| `detect-best <video>` | 旧版。只提取最佳画面，不搜图。 |
| `search <image-path>` | 已经有商品截图了，跳过检测直接搜图。 |
| `detect-and-search <video>` | 旧版。**不推荐。** |
| `session` | 获取当前认证会话 token。 |

## `detect-video` / `detect-video-and-search`

上传视频到 API 直接识别商品主体，不走本地抽帧。

流程：
1. 上传视频 → 获取公开 URL（复用现有上传接口）
2. 调用 LiteLLM（Chat Completions + `video_url`）分析视频内容
3. 识别商品名称、材质、颜色、功能
4. 生成中文搜索关键词
5. 1688 关键词搜索（`detect-video-and-search`）

依赖：
- `auth-rt` client key（自动，无需额外配置）
- LiteLLM 代理支持 `video_url` 内容类型
- 上传接口返回公开 URL

## `detect-best` / `detect-best-and-search` 选项

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--interval=<秒>` | `0.5` | 抽帧间隔（秒） |
| `--max-frames=<数量>` | `60` | 最多抽帧数 |
| `--output-dir=<目录>` | 视频同目录 | 帧图片保存目录 |

## 画面选择原理

两轮 Vision 流水线：

1. **过滤轮**（仅 `detect` / `detect-and-search`）—— 每帧二分类：保留/丢弃。可能过于严格返回空。
2. **排名轮** —— 所有候选帧一起发给模型，从中选出最清晰、最完整、最突出的一张商品图。

`detect-best` 跳过第一轮，所有帧直接进排名轮。超过 20 帧时会均匀采样到 20 帧再调用。**只要视频能出帧，就一定返回结果。**

## 输出格式

```json
{
  "bestSnapshot": {
    "frameIndex": 4,
    "timestampSeconds": 2,
    "imagePath": "/path/to/frame_0004.jpg",
    "croppedImagePath": "/path/to/frame_0004_cropped.jpg",
    "confidence": 0.95,
    "description": "White sneaker with blue logo, left side view",
    "boundingHint": "Product fully visible, centered, no hands"
  },
  "rerank": {
    "results": [...]
  }
}
```

## 结果展示格式

CLI 执行完成后，将 `rerank.results` 格式化为 markdown 表格，**每页 5 行**（如不足 5 行则全显示）。

| # | 商品名称 | 价格 | 销量 | 链接 |
|---|----------|------|------|------|
| 1 | {title}  | ¥{promotion_price \|\| price} | {sales ?? —}件 | [查看](https://detail.1688.com/offer/{num_iid}.html) |

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

## 执行规则

### 视频命令（慢 — 用 sub-agent 执行）

涉及命令：`detect-video-and-search`、`detect-best-and-search`、`detect-best`、`detect-and-search`、`detect-video`

使用 `sessions_spawn` 创建 sub-agent 执行，**不要直接运行**。

```
sessions_spawn(
  task: "Run this command and return the raw JSON output:\n\nbun dist/run.js <完整命令>\n\nCopy the entire JSON output as your reply.",
  label: "video-product-snapshot",
  runTimeoutSeconds: 300,
)
```

- 通知用户处理已开始，告知 `runId`
- 等待 sub-agent 返回结果，然后解析并展示

### `search` 和 `session`（快 — 直接运行）

直接在本会话中运行，不需要 sub-agent。

### 通用规则

1. **视频输入 → 优先用 `detect-video-and-search`。** 比抽帧方案更可靠。如果没配视频模型，降级到 `detect-best-and-search`。不要用 `detect-and-search`。
2. **不要重试。** 命令失败就直接报错。
3. **信任工具输出。** CLI 内部已处理 session 管理和错误格式化。