linkfox-1688-search-by-image

1688 图片商品搜索

此技能通过图片 URL 在 1688 平台上进行商品视觉搜索，帮助跨境卖家找到外观相似的供应商商品进行采购。

核心概念

1688 图片搜索使用视觉识别功能，在 1688 批发市场中查找外观相似的商品。它会返回供应商商品数据，包括标题、价格、最小起订量、月销量、复购率、交易评分和卖家身份徽章。

数据字段

字段	描述
offerId	1688 商品 ID
title	商品标题
imageUrl	商品主图
price	批发价（人民币）
consignPrice	一件代发价格（人民币）
salesQuantity	月销量
estimatedSalesAmount	预计月销售额
quantityBegin	最小起订量
repurchaseRate	复购率
tradeScore	商品交易评分
compositeServiceScore	综合服务体验评分
sellerIdentities	卖家身份（超级工厂/实力商家/诚信通会员）
offerIdentities	商品徽章（严选）
sendGoodsAddressText	发货地
deliveryTime	发货时间（24/48 小时）
isOnePsale	是否支持一件代发（是/否）
isJxhy	是否为优质货源（是/否）
hasPromotion	是否有促销活动（是/否）
isPatentProduct	是否为专利商品（是/否）

参数指南

图片规则：

1. JPEG 和 PNG 图片将原样传递。系统会根据文件实际字节检测 WebP 图片，并在调用 1688 前自动转换为 JPEG。
2. Base64 字符串必须是纯编码内容，不得包含 data:image/jpeg;base64, 前缀。
3. 图片来源必须提供 imageUrl、imageBase64 或 imageId 中的至少一个。

参数	必填	默认值	描述
imageUrl	有条件必填	-	公开图片 URL（最多 1000 个字符）。JPEG/PNG 原样传递；WebP 自动转换
imageBase64	有条件必填	-	不含 data URL 前缀的纯 Base64。JPEG/PNG 原样传递；WebP 自动转换
imageId	有条件必填	-	之前搜索结果中的 1688 图片 ID（可加快分页）
page	否	1	页码，从 1 开始
pageSize	否	20	每页结果数（1-50）
priceStart	否	-	最低价格筛选（人民币）
priceEnd	否	-	最高价格筛选（人民币）
filter	否	-	筛选条件，以逗号分隔（参见下方支持的筛选条件）
sort	否	{"monthSold":"desc"}	JSON 格式的排序条件：{field: direction}（参见下方支持的排序字段）
keyword	否	-	用于进一步筛选结果的关键词
productCollectionId	否	-	商品集合 ID（参见下方支持的 ID）

支持的筛选条件

多个筛选条件可用逗号组合（例如：1688Selection,totalEpScoreLv1,qrr0）。

筛选值	描述
1688Selection	1688 严选
certifiedFactory	认证工厂
totalEpScoreLv1	综合体验分 5 星
totalEpScoreLv2	综合体验分 4 星
totalEpScoreLv3	综合体验分 3 星
totalEpScoreLv4	综合体验分 2 星
qrr0	无品质退款
qrr1	品质退款率<1%
qrr5	品质退款率<5%
qrr10	品质退款率<10%
shipInToday	当日发货
shipIn24Hours	24 小时发货
shipIn48Hours	48 小时发货
noReason7DReturn	7 天无理由退货
isOnePsale	一件代发
isOnePsaleFreePost	一件代发包邮
new7	7 天内新品
new30	30 天内新品
isQqyx	全球严选
JPFL	日本专线
USFL	美国专线
KRFL	韩国专线
VNFL	越南专线
SAFL	沙特专线
RUFL	俄罗斯专线
KZFL	哈萨克斯坦专线
HKFL	香港专线
MOFL	澳门专线
TWFL	台湾专线

支持的排序字段

字段	方向	描述
price	asc/desc	价格升序/降序
monthSold	asc/desc	月销量升序/降序
rePurchaseRate	asc/desc	复购率升序/降序

排序格式示例：{"price":"asc"} 表示价格从低到高排序。

Supported Product Collection IDs

ID	Usage
262105288	跨境货盘
262105286	跨境货盘
262105253	跨境货盘
262105281	跨境货盘
262105280	跨境货盘
262105277	跨境货盘
262105276	跨境货盘
262105274	跨境货盘
262105269	跨境货盘
262185282	跨境货盘

调用方式

• API 端点：POST /alibaba1688/imageSearch（完整参数/响应/错误码见 references/api.md）
• Python 解释器选择：调用前先选择一个真实可用的 Python 命令并在本次任务中始终复用，记为 <PYTHON>。Windows 按 py -3、python、python3 的顺序尝试，其他系统按 python3、python 的顺序尝试；候选命令必须执行 <候选命令> -c "import sys; print(sys.executable)" 后退出码为 0 且 stdout 含非空解释器路径，否则视为不可用（WindowsApps 的空输出占位命令不得选用）。
• Python 脚本：<PYTHON> scripts/alibaba1688_image_search.py '<JSON 参数>' [--inline]
• 无感图片预处理：必须通过上述脚本调用。JPEG/PNG 保持原逻辑；WebP 由 Agent 使用 Pillow 转成 JPEG 后再按原逻辑调用，不要求用户手工转换。
• Pillow 首次初始化：在当前运行环境第一次调用本 Skill 前，Agent 必须用 <PYTHON> 执行 <PYTHON> -c "from PIL import features; ok=features.check('webp'); print('WEBP_OK' if ok else 'WEBP_MISSING'); raise SystemExit(0 if ok else 1)"。只有退出码为 0 且 stdout 包含 WEBP_OK 才算检查通过。如果检查失败，静默执行 <PYTHON> -m pip install --disable-pip-version-check "Pillow>=10.4,<13"，然后用同一 <PYTHON> 重新检查一次。检查通过后再运行图搜脚本；第二次仍失败时停止并报告依赖初始化失败，不得进入收费接口，也不得循环安装或要求用户手工处理。后续调用检查通过即可直接执行，不重复安装。
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-search-by-image-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

Local Image Upload

This tool requires a publicly accessible image URL. If the user provides a local image file path, you must upload it first to obtain a public URL.

Run the upload script:

<PYTHON> scripts/upload_image.py /path/to/local/image.png

The script will return a public URL (valid for 24 hours) that can be used as the imageUrl parameter.

Usage Examples

1. Basic image search

在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg

2. Search with filters

在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg，查询第1页，筛选1688严选，并按价格从高到低排序

3. Search with sorting

在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，按价格从高到低排序

4. Paginated search

在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，查询第2页，每页50条

5. Price range filter

在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，价格区间10-100元

Display Rules

1. Present data clearly: Show results in a structured table with key columns: product image, title, price, dropship price, monthly sales, minimum order quantity, repurchase rate, and seller identity
2. Image display: When the response includes imageUrl for products, display them inline for visual comparison
3. Price display: Always show price in CNY (¥) format
4. Seller badges: Display seller identity badges (超级工厂/实力商家/诚信通会员) and product badges (严选) prominently
5. Result count: Always inform the user of total results and current page/total pages
6. Pagination hint: When more pages are available, suggest the user can request the next page
7. Filter/sort limitation: If the user requests a sort or filter not in the supported list, do NOT attempt any workaround. Inform the user of the supported options
8. No secondary processing: Results are real-time and not stored in a database, so secondary SQL/data processing is not available

重要限制

1. 数据实时性：结果为实时搜索，不会存储在任何数据库中。不能使用 _dataQuery_executeDynamicQuery 进行二次处理。
2. 逻辑约束：如果用户要求的排序或筛选条件不在预设的支持列表中，不要调用其他工具或逻辑进行补偿。
3. 图像输入：必须提供 imageUrl、imageBase64 或 imageId 之一。对于第 2 页及之后的页面，建议传入第 1 页结果中的 imageId，以加快查询速度。
4. 图像格式：JPEG/PNG 按原路径处理。捆绑脚本会在调用 1688 前自动将 WebP 转换为 JPEG。GIF 和其他格式保持原有处理方式。
5. Base64 格式：imageBase64 值必须仅包含原始 Base64 字符串——不要包含 data:image/jpeg;base64, 前缀。
6. 每页结果数：每页最多 50 条结果。

用户表达与场景速查

适用——1688 的视觉商品找货源场景：

用户说法	场景
"1688以图搜图" / "用图片找1688货源"	基础图像搜索
"帮我在1688找这个图片的同款"	查找同款商品
"跨境找工厂，图片是..."	跨境供应商找货源
"这个Amazon产品在1688有没有货源"	根据 Amazon 图片反向找货源
"筛选1688严选的相似商品"	筛选图像搜索结果
"按月销量排序找相似货源"	排序图像搜索结果
"查看第2页结果"	分页

不适用——需求超出 1688 图像搜索范围：

• 基于文本/关键词的 1688 搜索（使用店雷达-1688选品库）
• 1688 商品排名/趋势（使用店雷达-1688商品榜单）
• Amazon 图像搜索（使用亚马逊前端-以图搜图）
• 图像生成或编辑
• 商品评价分析
• 价格历史或趋势分析

边界判断：用户说“找货源”或“找同款”时，如果提供了图片 URL，且意图是在 1688 上查找视觉上相似的商品，则适用此技能。如果用户想在 1688 上进行关键词搜索或查看排名数据，请改用店雷达工具。

算力消耗规则

消耗 5 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

在以下任一情况下，通过 Feedback API 自动检测并提交反馈：

1. 此技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户表达对该技能的不满或赞扬
4. 你认为有任何可以改进之处

请按照 references/api.md 中的说明调用反馈 API。不要中断用户的操作流程。

---

如需了解更多优质、专业的跨境电商技能，请访问 LinkFox Skills。