| name | vipshop-img-product |
| description | 唯品会（vip.com）图片搜索商品技能。当用户想通过图片搜索相似商品时触发，包括但不限于：以图搜图、拍照搜商品、图片搜索、找同款等。返回商品名称、价格、品牌、图片、链接等结构化信息。 |
唯品会图片搜索商品
⚠️ 重要规范：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",
"商品名称": "商品名称",
"品牌":
...
字段说明：
- 特卖价：
price.salePrice
- 划线价：
price.marketPrice
- 折扣：
price.saleDiscount
- 卖点：从
labels 字段提取所有 value 值
- 下一页token：用于分页，有值时可通过
--page-token 参数获取下一页
输出格式示例
用户展示格式：
🔍 图片搜索结果
📸 图片分类：上装
| 序号 | 商品图片 | 商品名 | 品牌 | 特卖价 | 划线价 | 折扣 | 卖点 |
|:---:|:---:|:---|:---|:---:|:---:|:---:|:---|
| 1 |  | [耐克运动T恤](商品链接) | 耐克 | ¥99.00 | ¥199.00 | 5折 | 透气舒适、运动休闲 |
| 2 |  | [商品名称](商品链接) | 品牌 | ¥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 必须：
- 立即自动触发登录流程
- 登录成功后自动继续执行搜索
禁止行为
- ❌ 不要只返回错误信息让用户自己处理
- ❌ 不要等待用户再次请求登录
- ❌ 不要使用
原始数据 字段进行二次整理展示
正确行为
- ✅ 检测到未登录时立即自动触发登录流程
- ✅ 登录成功后自动继续执行搜索
- ✅ 严格按照 Python 脚本返回的
商品分析 字段内容进行展示
实现要求
脚本位置
scripts/img_search.py（使用 Python 标准库，无外部依赖）
图片验证
接口调用
-
图片上传接口
- 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(文件)
-
分类识别接口
- 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 等
-
商品搜索接口
- 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) 等
注意事项
- 登录要求：必须先通过
vipshop-user-login skill 登录
- 图片格式：仅支持 jpg、jpeg、png、gif、bmp、webp 格式
- 网络要求：需要正常网络连接
- 依赖库：仅 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: 不支持，仅支持本地图片文件上传方式。
