linkfox-multimodal-product-similarity

多模态产品图片相似度分析

此技能将指导你如何根据产品主图的视觉相似度分析并归类产品。它可以帮助亚马逊卖家识别相同风格的产品、发现外观相似的竞品，并将产品列表整理为视觉上协调的分组。

核心概念

产品图片相似度分析使用多模态 AI 比较产品主图，并根据外观、颜色、构图和材质等视觉特征自动分组。这是一种后处理工具——它处理的是前序步骤（例如产品搜索、产品推荐）已检索到的产品数据。

相似度阈值：similarityThreshold 参数控制两个产品的视觉相似度必须达到多高才会被归入同一组。该参数为 0 到 100 之间的整数，表示百分比。数值越高，匹配条件越严格（只有几乎完全相同的图片才会被归为一组）；数值越低，匹配条件越宽松（形成更广泛的视觉分组）。默认值为 60。

单品牌分组筛选：includeSingleBrandGroups 标志（默认值为 true）控制结果中是否包含仅含单一品牌产品的分组。设为 false 会筛除单品牌分组，适用于用户希望关注跨品牌视觉重合的情况（例如竞品相似外观分析）。

输入数据要求

此工具需要前序步骤提供的 products 列表。它无法自行获取产品数据。典型工作流如下：

1. 运行产品搜索或推荐工具，获取产品列表。
2. 通过 refResultData 将该产品列表传入此工具，以便进行视觉相似度分组。

输入数据必须是包含 products 数组的 JSON 对象。

参数

参数	类型	必填	描述
similarityThreshold	integer	否	相似度阈值（0-100），默认值为 60。数值越高，匹配条件越严格。
includeSingleBrandGroups	boolean	否	是否包含仅有一个品牌的分组，默认值为 true。设为 false 可聚焦于跨品牌相似度。
refResultData	string	否	包含产品列表的前序工具结果数据的 JSON 字符串。
userInput	string	否	用户的原始查询或指令文本。

响应字段

字段	类型	描述
groups	array	相似度分组列表。每个分组包含 groupNumber、reason、brandCount，以及由产品详情组成的 asins 数组。
analysisInfo	object	摘要：totalProductsAnalyzed、totalGroupsFound、similarityThreshold、analysisTimestamp。
tables	array	表格结果数据，每个元素包含 data、columns 和 name。
total	integer	结果项总数。
title	string	结果标题。
type	string	渲染样式提示。
costToken	integer	消耗的 LLM Token 总数（输入 + 输出）。

分组项（asins 数组元素）

字段	类型	描述
asin	string	产品 ASIN
productId	string	产品 ID
brand	string	品牌名称
price	number	价格
rating	number	评分
ratings	integer	评分数量
monthlySalesUnits	integer	月销量
monthlySalesRevenue	number	月销售额
monthlySalesUnitsGrowthRate	number	月销量增长率
imageUrl	string	主图 URL
productImageUrls	array	所有产品图片 URL
imagePrompt	string	AI 生成的图片描述
asinUrl	string	产品详情页 URL
availableDate	string	上架日期
color	string	颜色
material	string	材质

调用方式

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

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

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

使用示例

1. 按视觉相似度对搜索结果分组（默认阈值） 使用搜索工具获取产品列表后，将结果传入此工具，对视觉上相似的商品进行聚类：

User: "Group these products by how similar they look."
Action: Call the API with refResultData set to the preceding product list JSON, using the default similarityThreshold of 60.

2. 查找近乎相同的商品（严格匹配）

User: "Which of these products have almost the same main image?"
Action: Call the API with similarityThreshold set to 85 or higher for strict visual matching.

3. 跨品牌竞品相似商品检测

User: "Show me groups where different brands have similar-looking products."
Action: Call the API with includeSingleBrandGroups set to false to filter out single-brand clusters.

4. 大范围视觉聚类（宽松阈值）

User: "Roughly categorize these products by appearance."
Action: Call the API with similarityThreshold set to 40 for broad grouping.

5. 组合：跨品牌严格相似度

User: "Find products from different brands that look nearly identical."
Action: Call the API with similarityThreshold set to 80 and includeSingleBrandGroups set to false.

显示规则

1. 清晰呈现分组结果：展示每个相似组及其组编号、分组原因、品牌数量，以及组内商品表格。
2. 尽可能显示商品图片：如果有图片 URL，请一并提供，帮助用户直观核验分组结果。
3. 突出跨品牌分组：当用户关注竞品分析时，重点展示包含多个品牌的分组。
4. 分析摘要：始终展示分析摘要（分析的商品总数、找到的分组总数、使用的相似度阈值、时间戳）。
5. 不提供主观建议：客观呈现分组数据。除非用户提出要求，否则不要加入业务建议。
6. 结果集较大时：分组较多时，优先展示最重要的分组（例如商品数量或品牌数量最多的分组），并告知用户还有其他分组。
7. 错误处理：请求失败时，根据响应消息说明原因，并建议调整方式（例如检查输入的商品数据是否有效、调整阈值）。

重要限制

• 仅支持后处理：此工具无法自行获取商品数据，必须接收前序步骤提供的商品数据。
• 不存储数据库：结果不会存储在数据库中。不要使用数据库查询工具对输出进行二次分析。
• 输入格式：输入必须是包含 products 数组的 JSON 对象。
• 直接进入摘要阶段：此工具执行完成后，直接将结果传入摘要阶段。不要进行其他中间数据计算。

用户表达与场景速查

适用——对商品列表进行视觉相似度分析：

用户说	场景
“按外观为这些商品分组”	视觉聚类
“查找外观相似的商品”“找出相似款”	相似度检测
“哪些商品看起来一样”	图片去重
“展示仿冒竞品的商品”	跨品牌相似款分析
“按外观／颜色／风格聚类”	视觉分类
“这个列表里有重复商品吗”	基于图片的去重
“不同品牌的同风格商品”	跨品牌相似度分析

不适用——需求超出图片相似度分析范围：

• 基于文本的商品比较（标题、描述、关键词）
• 不涉及视觉因素的价格或销量分组
• 商品搜索或发现（此工具仅对现有列表进行后处理）
• 评论分析、商品信息优化、广告策略

算力消耗规则

按动态规则计费：消耗算力 = sum(每个商品主图提示词生成调用的(输入消耗的算力 + 输出结果消耗的算力))。

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

反馈：

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

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

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

---

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