---
name: video-product-snapshot
description: "Upload video to API for product analysis and 1688 keyword search. / 上传视频直接识别商品并在1688搜索同款。当用户提供视频想找商品时使用。"
---

# Video Product Snapshot — 视频商品截图

上传视频到 API，由多模态模型识别商品主体，生成中文关键词在 1688 上搜索找到同款商品。

## 运行

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

## 命令列表

| 命令 | 使用场景 |
|------|---------|
| `detect-video-and-search <video>` | **推荐。** 上传视频到 API 识别商品，然后 1688 关键词搜索。 |
| `detect-video <video>` | 只识别商品描述和生成关键词，不搜图。 |
| `search <image-path>` | 已经有商品截图了，跳过检测直接搜图。 |
| `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-video-and-search`

```json
{
  "videoUrl": "https://...",
  "description": "白色帆布收纳盒，带提手，可折叠",
  "keyword": "帆布收纳盒",
  "searchResults": [
    { "num_iid": 123, "title": "...", "price": "15.00", "promotion_price": "12.00", "sales": 500, "detail_url": "..." }
  ]
}
```

## 结果展示格式

将 `searchResults` 格式化为 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-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. **不要重试。** 命令失败就直接报错。
2. **信任工具输出。** CLI 内部已处理 session 管理和错误格式化。