video-product-finder/SKILL.md

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

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

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

运行

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

{
  "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 ?? —}件	查看

• 有 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,
)