linkfox-amazon-search-by-image

Amazon 图片搜索

此技能将指导你如何使用图片 URL 在 Amazon 上进行视觉商品搜索，帮助 Amazon 卖家和研究人员跨多个市场寻找外观相似的商品。

核心概念

Amazon 图片搜索（视觉搜索）允许你提交商品图片 URL，并检索外观相似的 Amazon 商品列表。这对竞品分析、寻找替代货源、识别仿冒品，以及根据商品外观发现市场机会都非常有用。

此工具会搜索 8 个 Amazon 市场，并返回 Amazon 店铺数据，包括 ASIN、标题、图片、价格、评分、评论数和品牌。Keepa 数据会按 ASIN 单独查询，因此 Keepa 服务中断或配额等待不会导致图片搜索请求失败。

支持的市场

市场	域名	默认邮政编码
美国	amazon.com	10001
英国	amazon.co.uk	EC1A 1BB
德国	amazon.de	10115
法国	amazon.fr	75001
意大利	amazon.it	00100
西班牙	amazon.es	28001
日本	amazon.co.jp	100-0001
印度	amazon.in	110034

默认市场为 amazon.com（美国）。用户未指定市场时，请使用 amazon.com。

参数指南

参数	必填	说明
imageUrl	是	用于搜索的有效、可公开访问的图片 URL
amazonDomain	是	Amazon 市场域名（例如：amazon.com、amazon.de）。默认为 amazon.com
sort	否	结果排序方式。支持的值：default、price-asc-rank、price-desc-rank、rating-asc-rank、rating-desc-rank、ratings-asc-rank、ratings-desc-rank
deliveryZip	否	市场所在国家/地区内的配送地址邮政编码。未指定时使用市场默认值
countryOrAreaCode	否	跨境配送的国家/地区代码（例如：CN、JP、KR）。不可与 deliveryZip 同时使用。注意：印度市场不支持跨境配送

aggregateByKeepaData 已弃用。请勿传入此参数。如果用户需要月销量、BSR、FBA 费用、尺寸或当前商品详情，请在图片搜索后使用 linkfox-keepa-product-request 查询选定的 ASIN。若需查看价格或 BSR 历史记录，请使用 linkfox-keepa-product-series。

排序选项

值	说明
default	默认相关性排序
price-asc-rank	价格：从低到高
price-desc-rank	价格：从高到低
rating-asc-rank	评分：从低到高
rating-desc-rank	评分：从高到低
ratings-asc-rank	评论数：从少到多
ratings-desc-rank	评论数：从多到少

重要：如果请求的排序方式不在上述支持列表中，不要尝试使用其他工具或变通方法来满足要求。请告知用户支持的排序选项。

调用方式

• API 端点：POST /amazon/searchByImage（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/amazon_search_by_image.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-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/套餐到期/需充值/请充值”，或类似含义的内容。

本地图片上传

此工具需要可公开访问的图片 URL。如果用户提供本地图片文件路径（例如，C:\Users\...\photo.png、/home/.../image.jpg），必须先上传图片以获取公开 URL。

运行上传脚本：

python scripts/upload_image.py /path/to/local/image.png

脚本会返回一个公开 URL（有效期为 24 小时），可将其用作图片 URL 参数。

使用示例

1. 在美国站点进行基本图片搜索

Search Amazon US for products that look similar to this image:
https://m.media-amazon.com/images/I/61pAlIX8SZL._AC_SY575_.jpg

2. 在指定站点查找相似商品

Search Amazon Germany (amazon.de) for products visually similar to this image:
https://example.com/product-photo.jpg

3. 按价格从低到高排序的图片搜索

Find similar products on Amazon US for this image, sorted by price from low to high:
https://example.com/my-product.jpg

4. 跨境配送搜索

Search Amazon Japan for similar products to this image, with delivery to China:
https://example.com/item.jpg

5. 发现外观相似的竞品

I found this product image on a competitor's listing. Find me all similar-looking products on Amazon UK:
https://example.com/competitor.jpg

显示规则

1. 清晰呈现数据：使用结构清晰的表格展示搜索结果。优先显示的关键列：商品图片、标题、ASIN、价格、评分、评论数和品牌
2. 图片显示：当响应中包含商品的 imageUrl 时，内嵌显示图片，方便用户直观比较结果
3. 价格和货币：始终同时显示价格和货币代码（例如，$29.99 USD、24.99 EUR）
4. Keepa 后续查询：遵循顶层的 message。对于月销量、BSR、FBA 费用、尺寸或当前商品详情，可为用户选定的 ASIN 提供 linkfox-keepa-product-request。仅当用户请求价格或 BSR 历史记录时，才提及 linkfox-keepa-product-series。不要传递 aggregateByKeepaData
5. 结果数量：始终告知用户找到的结果总数（total / totalCount）
6. 错误处理：查询失败时，说明问题并建议检查图片 URL 是否有效且可公开访问
7. 排序限制：如果用户请求的排序方式不在支持列表中，应明确说明可用的排序选项，而不是尝试不受支持的替代方法
8. 不进行二次处理：此工具的结果不会存储在数据库中，因此无法进行二次 SQL 处理

用户表达与场景快速参考

适用 —— Amazon 上的视觉商品搜索场景：

用户表达	场景
“查找与这张图片相似的商品”	基本图片搜索
“按图片搜索”、“在 Amazon 上反向图片搜索”	视觉搜索
“查找外观相似的竞品”、“查找同风格商品”	按外观进行竞品分析
“Amazon 上有哪些商品看起来像这个”	商品发现
“查找外观相同但价格更低的替代商品”	基于价格的视觉比较
“在 Amazon JP/DE/UK 搜索这张商品图片”	跨站点视觉搜索
“显示相似商品的 Keepa 数据”	先运行图片搜索，然后使用相应的 Keepa 技能查询用户选定的 ASIN
“查找与这张照片相似且按评分排序的商品”	排序后的视觉搜索

不适用 —— 超出基于图片的商品搜索范围：

• 在 Amazon 上进行基于文本关键词的搜索（改用关键词搜索工具）
• ABA 搜索词数据分析
• 商品评论分析或商品详情页优化
• 不提供源图片的销量估算
• 图片编辑或图片生成
• 使用本地图片文件进行搜索（此工具需要可公开访问的 URL）

适用边界：用户提到“查找相似商品”或“竞品分析”时，如果他们提供了图片 URL，且目的是查找 Amazon 上外观相似的商品详情页，则适用此技能。如果他们要进行基于关键词的搜索、销量数据分析，或不带图片的商品研究，则不适用。

算力消耗规则

图搜本身消耗 15 算力。Keepa 查询与图搜分开计费；只有在用户确认需要查询具体 ASIN 后，才按对应 Keepa skill 的算力规则执行。

重要：本技能的服务按倍数动态计费，可能一次性消耗大量算力，必须提醒用户，并由用户决定是否继续。

反馈：

出现以下任一情况时，通过 Feedback API 自动检测并报告反馈：

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

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

---

如需更多高质量、专业的跨境电商技能，请设置 LinkFox Skills。