video-product-finder/README.md

video-product-snapshot — 视频商品以图搜图

从视频中提取最佳商品帧，以图搜图在 1688 找同款。

工作原理

1. ffmpeg 按 0.5s 间隔抽帧（最多 60 帧）
2. 视觉质量预过滤（亮度/方差剔除模糊帧）
3. 容器/架子类产品检测 → 自动选择空载帧
4. 视觉模型多帧对比排序，选出最佳商品帧
5. 裁剪商品区域 → 上传 → 1688 图搜
6. 后置过滤（视觉模型判断结果是否同款）→ rerank 排序

安装

./install.sh          # 安装 auth-rt + 依赖
bun install
bun run build         # 输出到 dist/run.js

使用方法

bun dist/run.js <command> [options]

命令

命令	说明
detect-best-and-search <video>	推荐。 最佳帧 → 图搜 → rerank
detect-best <video>	只提取最佳商品帧，不搜图
detect-and-search <video>	两阶段过滤后图搜（较慢）
detect <video>	抽帧并逐帧检测商品
search <image>	用已有图片搜同款
rerank	关键词对图搜结果交叉过滤
session	获取当前认证会话 token

选项（detect-best / detect-best-and-search）

参数	默认值	说明
--interval=<秒>	0.5	帧采样间隔
--max-frames=<n>	60	最大分析帧数
--output-dir=<目录>	视频同目录	截图保存目录
--session-id=<id>	自动生成	Langfuse session ID
--dry-run	—	解析参数，不实际执行

输出

所有命令输出 JSON 到 stdout，包含 sessionId 字段用于 Langfuse 追踪。

{
  "sessionId": "skill-20260426-184345-lb06",
  "status": "success",
  "command": "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": "..." }
    ]
  }
}

鉴权架构

~/.openclaw/.env
  CLIENT_KEY ──→ auth-rt ──→ 业务系统
                              ├── /session          → access_token
                              └── /client-config    → provider.api_key
                                                       provider.base_url
                                                       provider.model

仅需配置 CLIENT_KEY，LLM 凭据和端点均由业务系统下发。

环境变量

变量	说明
CLIENT_KEY	必需。 在 ~/.openclaw/.env 中配置
VISION_MODEL	覆盖模型名称（默认来自 client config）
SKILL_SESSION_ID	Langfuse session ID（自动生成，格式 skill-YYYYMMDD-HHMMSS-xxxx）
AUTH_RT_BIN	覆盖 auth-rt 二进制路径
TELEMETRY_ENDPOINT	遥测上报接口

前置依赖

• Bun 运行时
• 系统 PATH 中包含 ffmpeg / ffprobe（帧提取）
• auth-rt CLI（鉴权/API 调用，install.sh 自动安装）