需要按图片在亚马逊多站点找同款或视觉相似商品时使用

通过公网图片 URL 在 8 个亚马逊站点做以图搜图，返回 ASIN、标题、图片、价格、评分、评论数、品牌等商品数据，用于竞品分析、找同款、货源替代与选品发现。

适用场景

解决思路

1. 调用 API 端点 POST /amazon/searchByImage，或运行 Python 脚本 python scripts/amazon_search_by_image.py '<JSON 参数>' [--inline]（完整参数/响应/错误码见 references/api.md）。
2. 必填参数 imageUrl 传一个有效且可公开访问的图片 URL；amazonDomain 传亚马逊站点域名（如 amazon.com、amazon.de），未指定时默认 amazon.com（美国站）。
3. 可选参数 sort 控制排序，支持 default、price-asc-rank、price-desc-rank、rating-asc-rank、rating-desc-rank、ratings-asc-rank、ratings-desc-rank；若用户要求的排序不在该列表内，直接告知可用的排序选项，不要用其他工具或变通方式替代。
4. 可选参数 deliveryZip 传站点所在国的配送邮编，未指定则使用站点默认邮编（US 10001、UK EC1A 1BB、DE 10115、FR 75001、IT 00100、ES 28001、JP 100-0001、IN 110034）。
5. 可选参数 countryOrAreaCode 传跨境配送的国家/地区代码（如 CN、JP、KR），不能与 deliveryZip 同时使用；注意印度站不支持跨境配送。
6. 可选参数 aggregateByKeepaData 控制是否用 Keepa 数据增强结果（销售排名、月销量、FBA 费用、尺寸等）。
7. 若用户给的是本地图片文件路径（如 C:\Users\...\photo.png、/home/.../image.jpg），先运行 python scripts/upload_image.py /path/to/local/image.png 上传，拿到有效期 24 小时的公网 URL 再作为 imageUrl 使用。
8. 遵守成本约束：同一会话同一参数组合默认只调用一次，脚本自带 24h 本地缓存；失败或空结果时不得自动换关键词、翻页或改邮编连续试探，需要继续检索前先向用户说明会产生额外消耗。
9. 输出落盘：始终把完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-search-by-image-<timestamp>.json（<cwd> 为脚本执行时的工作目录，<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错）。
10. 响应体 ≤ 8 KB 时落盘后把完整 JSON 打印到 stdout；> 8 KB 时落盘后 stdout 只输出摘要（顶层字段、total/costToken 等常见计数、最大列表字段的长度 + 前 3 条样本）；加 --inline 可强制全量打印到 stdout（同样落盘）。
11. 读数据时先看摘要判断是否足够，需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
12. 遇到未配置 API Key（环境变量 LINKFOX_AGENT_API_KEY 与 LINKFOXAGENT_API_KEY 均未配置）、响应 401 或 402、或响应提示算力/余额不足（含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”等含义）时，按 references/onboarding.md 引导用户解决。
13. 展示结果时用结构化表格，优先列：商品图片、标题、ASIN、价格、评分、评论数、品牌；响应含 imageUrl 时内联展示图片便于视觉对比。
14. 价格始终带货币代码（如 $29.99 USD、24.99 EUR）；启用 aggregateByKeepaData 且存在 Keepa 字段时，在展开区或额外列展示月销量、销售排名、FBA 费用等补充数据。
15. 始终告知用户找到的结果总数（total / totalCount）；查询失败时说明原因并建议检查图片 URL 是否有效且可公开访问。
16. 说明该工具结果不存数据库，无法做二次 SQL 处理。
17. 计费按动态规则：消耗算力 = 15 + 0.045 × 本次商品详情查询消耗的 Keepa token，Keepa 部分单价 90 × 本次商品详情查询消耗的 Keepa token，未触发 Keepa 聚合则为 0；因按倍数动态计算可能一次性消耗大量算力，必须提醒用户并由用户决定是否继续。
18. 当出现功能与实际行为不符、结果与用户意图不符、用户表达不满或称赞、或其他可改进之处时，按 references/api.md 调用 Feedback API 上报，不要打断用户流程。
19. 适用场景包括：以图找相似商品、以图搜图/反向图片搜索、按外观找竞品同款、发现亚马逊上外观相似的商品、找外观相同但更便宜的替代品、跨站点（JP/DE/UK 等）以图搜索、带 Keepa 数据的相似商品搜索、按评分等排序的以图搜索。
20. 边界判断：用户说“找相似商品”或“竞品分析”且提供了图片 URL、意图是找视觉相似的亚马逊商品时适用；若用户要的是关键词搜索、销售数据分析或无图片的选品调研，则不适用。

适用边界 · 注意事项

• 需要基于文本关键词的亚马逊搜索（应改用关键词搜索工具）。
• ABA 搜索词数据分析、商品评论分析、Listing 优化、无源图片的销量估算、图片编辑或图片生成。
• 直接用本地图片文件路径搜索（本工具要求公网可访问的 URL，需先上传）。