唯品会图片搜索商品

> ⚠️ 重要规范：AI 必须先加载本 skill 规范（use_skill），再执行任何脚本或返回结果，不得绕过 skill 规范自行处理数据。

概述

唯品会（vip.com）图片搜索商品技能。当用户想通过图片搜索相似商品时触发，包括但不限于：以图搜图、拍照搜商品、图片搜索、找同款等。返回商品名称、价格、品牌、图片、链接等结构化信息。

功能特性：本地图片上传、智能分类识别、相似商品搜索、结构化输出

重要提示：需要用户先通过 vipshop-user-login skill 登录唯品会账户。

使用场景

• 用户想通过本地图片搜索相似商品时
• 用户想找同款商品时
• 用户上传本地图片询问商品信息时
• 拍照搜商品时

触发示例

用户输入以下内容可触发本 skill：

• "帮我用这张图片搜索相似商品"
• "以图搜图"
• "这个图片帮我找同款"
• "帮我搜一下这张图片里的商品"
• "拍照搜商品"
• "上传图片搜索"
• "找同款"
• "图片搜商品"

工作流程

步骤 1：检测登录状态

在执行搜索前，AI 必须先检测登录状态：

• 检查 ~/.vipshop-user-login/tokens.json 是否存在且有效
• 如果已登录：直接执行步骤2
• 如果未登录：自动触发 vipshop-user-login skill 完成登录流程

步骤 2：接收输入

需要用户提供本地图片文件路径。

步骤 3：执行脚本

首次搜索（使用本地图片文件）

python3 scripts/img_search.py --image /path/to/image.jpg

获取下一页

用户回复"下一页"时，AI 应缓存图片URL、分类类型、检测区域，并使用上一次请求返回的 pageToken 直接调用第3步接口：

python3 scripts/img_search.py --image-url "图片URL" --category-type "分类类型" --rect "检测区域" --page-token "上一次返回的pageToken"

分页参数说明：

• --image-url：首次搜索返回的 图片URL 字段
• --category-type：首次搜索返回的 识别分类.类型 字段
• --rect：首次搜索返回的 识别分类.检测区域 字段
• --page-token：上一次请求返回的 商品分析.下一页token 字段

支持的图片格式：jpg、jpeg、png、gif、bmp、webp

步骤 4：展示结果

解析 JSON 数据并格式化输出，展示搜索结果。

⚠️ 重要规则：

• 必须完整展示 Python 脚本返回的所有数据，不得对数据进行截断、省略或选择性隐藏
• 显示字段：商品ID、商品名称、品牌、特卖价、划线价、折扣、卖点、图片、商品链接
• 如果返回了多条商品记录，必须全部展示，不能只展示前几条

输出格式

{
  "code": 1,
  "msg": "success",
  "图片URL": "/xupload.vip.com/xxx.jpg",
  "识别分类": {
    "类型": "UPPERBODY",
    "名称": "上装",
    "检测区域": "109,306,548,768",
    "所有分类": [...]
  },
  "商品分析": {
    "总计": 10,
    "下一页token": "xxx",
    "商品列表": [
      {
        "商品ID": "xxx",
        "商品名称": "商品名称",
        "品牌": "品牌名",
        "特卖价": "99.00",
        "划线价": "199.00",
        "折扣": "5折",
        "卖点": ["卖点1", "卖点2"],
        "图片": "https://...",
        "商品链接": "https://passport.vip.com/exchangeTokenFromApp?..."
      }
    ]
  },
  "原始数据": {...}
}

字段说明：

• 特卖价：price.salePrice
• 划线价：price.marketPrice
• 折扣：price.saleDiscount
• 卖点：从 labels 字段提取所有 value 值
• 下一页token：用于分页，有值时可通过 --page-token 参数获取下一页

输出格式示例

用户展示格式：

🔍 图片搜索结果

📸 图片分类：上装

| 序号 | 商品图片 | 商品名 | 品牌 | 特卖价 | 划线价 | 折扣 | 卖点 |
|:---:|:---:|:---|:---|:---:|:---:|:---:|:---|
| 1 | ![商品图](图片URL) | [耐克运动T恤](商品链接) | 耐克 | ¥99.00 | ¥199.00 | 5折 | 透气舒适、运动休闲 |
| 2 | ![商品图](图片URL) | [商品名称](商品链接) | 品牌 | ¥XX.XX | ¥XX.XX | X折 | 卖点1、卖点2 |
| ... |

💡 可回复"查询第X个商品"查看任意商品详细信息！
📄 想看更多商品？可以回复"下一页"查看

商品名超链接说明：

• 商品名必须使用 Markdown 链接格式：商品名
• 商品链接从脚本返回的 商品链接 字段获取

示例

示例 1：通过本地图片搜索商品

用户输入： "帮我用这张图片搜索相似商品 /path/to/image.jpg"

执行： python3 scripts/img_search.py --image /path/to/image.jpg

输出：

{
  "code": 1,
  "msg": "success",
  "识别分类": {...},
  "商品分析": {...}
}

示例 2：未登录

用户输入： "帮我搜索图片"

执行： python3 scripts/img_search.py --image /path/to/image.jpg

输出：

{
  "code": -1,
  "msg": "login_required",
  "message": "需要登录唯品会账户",
  "action": "请先登录唯品会账户后再使用图片搜索"
}

AI 行为规范

未登录处理

当检测到用户未登录时，AI 必须：

1. 立即自动触发登录流程
2. 登录成功后自动继续执行搜索

禁止行为

• ❌ 不要只返回错误信息让用户自己处理
• ❌ 不要等待用户再次请求登录
• ❌ 不要使用 原始数据 字段进行二次整理展示

正确行为

• ✅ 检测到未登录时立即自动触发登录流程
• ✅ 登录成功后自动继续执行搜索
• ✅ 严格按照 Python 脚本返回的 商品分析 字段内容进行展示

实现要求

脚本位置

scripts/img_search.py（使用 Python 标准库，无外部依赖）

图片验证

• 检查文件是否存在
• 检查文件格式是否支持

接口调用

1. 图片上传接口
• URL: https://mapi-file-tx.vip.com/xupload/picture/new_upload_inner_applet.jsps
• 方式: POST (multipart/form-data)
• 参数: app_name, client, source_app, api_key, app_version, mobile_platform, union_mark, mobile_channel, mars_cid, warehouse, fdc_area_id, province_id, wap_consumer, picture(文件)

1. 分类识别接口
• URL: https://mapi-pc.vip.com/vips-mobile/rest/shopping/skill/search/img/category/v1
• 方式: GET
• 参数: api_key, app_name, app_version, client, imgUrl, mars_cid 等

1. 商品搜索接口
• URL: https://mapi-pc.vip.com/vips-mobile/rest/shopping/skill/image/product/list/v1
• 方式: POST
• 参数: api_key, app_name, categoryType, imgUrl, rect, mars_cid, pageToken(可选，用于分页), limit(固定为10) 等

注意事项

1. 登录要求：必须先通过 vipshop-user-login skill 登录
2. 图片格式：仅支持 jpg、jpeg、png、gif、bmp、webp 格式
3. 网络要求：需要正常网络连接
4. 依赖库：仅 Python 标准库（urllib、json、os）

技术细节

• 实现语言：Python 3
• 数据格式：JSON（脚本输出）→ 格式化文本（AI 展示）
• 编码支持：UTF-8，支持中文
• 异常处理：完整的网络异常和 API 错误处理
• 依赖库：仅使用 Python 标准库

常见问题

Q: 支持哪些图片格式？

A: 支持 jpg、jpeg、png、gif、bmp、webp 格式。

Q: 需要登录才能使用吗？

A: 是的，必须先通过 vipshop-user-login skill 登录。

Q: 搜索结果有多少个商品？

A: 每页返回最多10个相似商品，可通过 pageToken 获取更多。

Q: 如何获取更多商品？

A: 使用返回的 下一页token，通过 --page-token 参数获取下一页数据。

Q: 支持直接传入图片URL吗？

A: 不支持，仅支持本地图片文件上传方式。