video-product-finder/README.md

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

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

工作原理

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

安装

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

使用方法

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	—	解析参数并打印配置，不实际执行

示例

# 检测商品，每 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。

{
  "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 运行时
• 系统 PATH 中包含 ffmpeg 和 ffprobe
• 系统 PATH 中包含 auth-rt CLI（search / detect-and-search 需要）