Linkfox Wb Amazon Front Data

[!IMPORTANT] 本 Skill 必须依赖 MCP “LinkFox”。如未安装该MCP，请明确通知用户： 请先安装 LinkFox 连接器：

• 在 WorkBuddy 左侧找到 “专家·技能·连接器” → “连接器”；
• 搜索关键词 “LinkFox”，并安装连接器 “LinkFox”（注意：是 linkfox，不是 linkfox-product-selection），按指引完成登录授权；
• 返回 WorkBuddy 重试。

LinkFox 亚马逊前台数据（LinkFox Amazon Front Data）

本能力用于完成亚马逊前台的实时数据工作：从搜索结果页发现商品和排位，从 ASIN 页面读取 Listing 详情，从评论中提取买家反馈，从公开图片发现视觉相似商品，或让 Alexa 购物助手回答自然语言购物问题。结果可包含商品标题、ASIN、价格、币种、评分、评论数、图片、链接、配送、赞助标记、评论文本、变体、Keepa 补充字段、Alexa 回答和追问建议。

本能力覆盖 5 个子能力和 5 个下游工具路由。所有业务查询都通过 Linkfox MCP 唯一工具 proxy_call 调用；本地脚本只保留预签名 URL 的 OSS 文件 PUT 辅助。每个子能力的完整参数、响应字段、错误码、成本和特殊规则见 references/。

能力边界

能力范围

• 关键词搜索与前台排位：使用 proxy_call 路由到 amazon/search 模拟指定站点的前台搜索，返回关键词、页码、位置、ASIN、标题、价格、评分、评论数、品牌、配送、FBA、赞助标记和上架信息。适用于竞品发现、SERP 快照、价格比较、赞助商品识别和指定 ASIN 排位核对。
• ASIN 商品详情：使用 proxy_call 路由到 amazon/product/detail 获取最多 40 个 ASIN 的当前商品页数据，包括标题、图片、五点、规格、描述、A+ 内容、价格、优惠、评分分布、Prime、库存、配送、变体，以及按需返回的经常一起购买、相关商品和作者评论。
• 评论读取与反馈分析：使用 proxy_call 路由到 amazon/reviews/list 按单个 ASIN、星级、排序、关键词、认证购买和媒体条件读取评论，支持按 1—5 星分别设定数量，并据此整理常见痛点和受好评特征。
• 图片找相似商品：使用 proxy_call 路由到 amazon/searchByImage 对可公开访问的图片 URL 进行视觉商品搜索，支持 8 个站点、价格/评分/评论数排序、站内或跨境配送，以及可选的 Keepa 销售排名、月销量、FBA 费用和规格字段。本地图片先用 proxy_call 路由到 oss/file/presignedPut 取得预签名 URL，再使用 scripts/upload_image.py 上传。
• Alexa 对话式导购：使用 proxy_call 路由到 amazon/alexaSearch 发送一条自然语言购物问题，获得 Alexa 回答、分组商品推荐、ASIN、商品链接、价格、评分和可继续追问的问题；可用具体的分类页、搜索结果页或商品详情页 URL 提供页面上下文。
• 可追溯与去重：保留本次 toolName、arguments、MCP 返回和下游响应中的 taskId/costToken 等追踪字段。不声称 MCP 会自动落盘或提供 24 小时本地缓存；同一任务内不得以完全相同的 toolName + arguments 重复发起收费调用。

边界与限制

• 实时快照而非历史分析：搜索、商品详情和评论反映调用时的前台数据；不等同于历史搜索量、关键词趋势、历史排名、历史价格或销量预测。
• 站点与输入限制：搜索和详情使用 amazonDomain，评论使用 domainCode；各自支持范围见对应 reference。图片搜索必须使用可公开访问的图片 URL，印度站不支持 countryOrAreaCode；不可用本地路径直接查询。
• 单请求限制：评论接口一次只支持一个 ASIN，多个 ASIN 必须分开调用；Alexa 每次只能传一个 prompts 元素，跨轮追问必须由 Agent 总结上一轮后重新发起调用；详情一次最多 40 个 ASIN；评论每个星级最多 100 条。
• 参数约束：图片搜索的 deliveryZip 与 countryOrAreaCode 不能同时传；图片搜索的排序值仅限其 reference 列出的 7 种；搜索排序值仅限其 reference 列出的 6 种；Alexa 的 url 只用于具体页面，不要传普通亚马逊首页。
• 图片与评论语义：图片搜索是视觉相似商品发现，不是文字关键词搜索；评论返回原始发布语言，评论分析应标注这是从返回文本归纳的主题，不应伪装成供应商字段。
• 数据能力边界：不提供 ABA 历史搜索词分析、广告创建或竞价、店铺订单/库存、FBA 财务核算、Listing 文案创作、图片编辑、销售额预测、数据库 SQL 二次处理或侵权法律结论。
• 认证与消耗：Authorization 由 WorkBuddy 自动注入，不放入 MCP 配置或业务参数。业务调用可能消耗积分；失败或空结果不得自动重试，也不得自动换词、换图、翻页、换邮编或改参数连续试探；需要继续调用时先说明额外消耗并由用户决定。
• 数据缺失：字段为空、0 或 -1 可能表示供应商没有提供该值；不得把不可用字段当成真实价格、尺寸、销量或排名。

工具选择指南

选择时先判断用户要的是“搜索页列表”“已知 ASIN 页面”“评论文本”“图片相似结果”还是“自然语言回答”，再核对站点、输入形态、分页/批量限制和预计消耗。相近需求同时满足时，默认推荐上表工具，并把需要改用其他工具的原因和额外调用成本讲清楚，由用户决定是否继续。

业务需求路由速查

MCP 调用方式

• 唯一调用入口：MCP server 名为 LinkFox，地址为 https://mcp-tool-gateway.linkfox.com/mcp/any-tool，唯一工具为 proxy_call。外层必须同时传当前 allowlist 中的精确 toolName 与 arguments；arguments 始终是 JSON 对象，即使下游工具无业务参数也必须传 {}。不要再包裹 body、params 或 data。
• 严格 allowlist：toolName 只允许 amazon/search、amazon/product/detail、amazon/reviews/list、amazon/searchByImage、amazon/alexaSearch、oss/file/presignedPut。值为原网关 endpoint 去掉前导 / 后的精确字符串，区分大小写；不得猜测、转换为 snake_case 或用 skill slug 代替。
• 禁止直连和回退：不得使用 curl、urllib、requests 或其他 HTTP 客户端直连 tool-gateway.linkfox.com，不得静默回退到旧 API 或查询脚本。MCP 或 proxy_call 不存在时，立即停止业务调用并读取 references/onboarding.md。
• 错误分层：先检查 MCP 传输/工具层是否失败（包括 isError=true、工具不存在、参数 schema 错误和代理调用失败）；只有代理层成功后才解析下游 JSON 的 errcode/errorCode/code、errmsg/msg。proxy_call 若返回 text 形式的 JSON，只解析一次；不循环解码字符串化 JSON。
• 不自动重试：所有业务路由都可能收费。MCP 错误、下游错误或空结果都不得触发自动重试；同一任务内对完全相同的 toolName + arguments 只调用一次。若需改参数或再试，先说明可能的额外消耗并由用户决定。
• 本地图片两阶段流程：本地路径不可直接作为 imageUrl。先调用 proxy_call，传 {"toolName":"oss/file/presignedPut","arguments":{"contentType":"<MIME>","fileExtension":"<ext>"}}；再将下游返回的预签名 URL 与本地路径交给 scripts/upload_image.py 执行 OSS PUT。检查其输出的公开 url 后作为 amazon/searchByImage 的 imageUrl。公开 URL 有效期为 24 小时，支持 jpg、jpeg、png、gif、webp、heic。
• 响应追溯：保留当次 toolName、完整 arguments、代理错误与下游返回中的总数、失败明细、costToken、taskId 等字段。不声称会自动保存原始响应或命中 24 小时本地缓存；向用户输出结论和必要证据，不直接倾倒大段原始 JSON。
• 完整参数位置：参数、默认值、站点/排序枚举、响应字段、错误码、成本和反馈接口分别见 references/linkfox-amazon-product-detail.md、references/linkfox-amazon-reviews-list.md、references/linkfox-amazon-search.md、references/linkfox-amazon-search-by-image.md、references/linkfox-amazon-alexa-search.md。MCP 安装、WorkBuddy 自动授权异常和 402 分流见 references/onboarding.md。
• 反馈：当能力与用户意图不匹配、结果错误、用户明确表扬/不满或提出改进意见时，按相应 reference 中的 Feedback API 规则上报；反馈接口 https://skill-api.linkfox.com/api/v1/public/feedback 与 MCP 业务路由分离，不要混用，且不要中断用户当前流程。

使用示例

以下示例均是传入 proxy_call.arguments 的业务参数对象；应与路由表中的 toolName 组合调用。真实调用前确认目标站点、输入约束和积分消耗；不要因结果为空自动扩大范围。

1. 关键词前台搜索

{
  "keyword": "wireless earbuds",
  "amazonDomain": "amazon.com",
  "language": "en_US",
  "sort": "review-rank",
  "page": 1,
  "deliveryZip": "10001",
  "device": "desktop"
}

读取 products[] 的 position、asin、title、price、currency、rating、ratings、brand、sponsored 和 asinUrl，并报告 total、keyword、costToken。page 从 1 开始，每页约 20 条；这是调用时的前台排位，不是历史排名。排序只能使用 reference 中的支持值。

2. ASIN 商品详情

{
  "asins": "B072MQ5BRX,B08N5WRWNW",
  "amazonDomain": "amazon.co.jp",
  "language": "ja_JP",
  "deliveryZip": "100-0001",
  "device": "mobile",
  "returnBoughtTogether": true,
  "returnRelatedProducts": true,
  "returnAuthorsReviews": true
}

读取 products[] 中的标题、图片、aboutItem、productDescription、价格/原价/币种、rating/ratings、variants、itemSpecifications、Prime、库存和配送；按需读取 boughtTogether、relatedProducts 和 authorsReviews。一次最多 40 个 ASIN，按 ASIN 分隔展示；这是当前商品页快照，按成功返回商品数计费，批量前应先确认范围。

3. 按条件读取评论

{
  "asin": "B08N5WRWNW",
  "domainCode": "com",
  "star1Num": 30,
  "star2Num": 30,
  "star3Num": 0,
  "star4Num": 0,
  "star5Num": 0,
  "sortBy": "recent",
  "reviewerType": "avp_only_reviews",
  "mediaType": "all_contents",
  "formatType": "all_formats",
  "filterByKeyword": "battery"
}

按 rating 分组展示 title、text、date、verified、vine、numberOfHelpful、图片/视频链接，并先给出重复痛点或受好评特征。一次只查一个 ASIN；若传入任意星级数量，未传的星级按 0 处理，每个星级最多 100 条。按计划抓取页数计费，调用前说明预计范围。

4. 图片视觉搜索与 Keepa 补充

{
  "imageUrl": "https://example.com/product-image.jpg",
  "amazonDomain": "amazon.de",
  "sort": "price-asc-rank",
  "deliveryZip": "10115",
  "aggregateByKeepaData": true
}

读取 products[] 的 asin、title、asinUrl、price、oldPrice、currency、rating、ratings、brand，以及启用后存在的 salesRank、monthlySalesUnits、fbaFees、fulfillment、sellerNum、variationNum、尺寸和 lastUpdate；报告 total/totalCount 与 costToken。imageUrl 必须公开可访问；deliveryZip 与 countryOrAreaCode 互斥；Keepa 补充会增加消耗，应按用户要求启用。

5. Alexa 自然语言导购

{
  "prompts": ["best wireless earbuds for running on Amazon US under $100"],
  "format": "json",
  "url": "https://www.amazon.com/s?k=wireless+earbuds"
}

成功时读取 data[] 的 content、products[].title、商品 asin/title/url/cover/price/originalPrice/score/ratingsCount/describe、followUpQuestions 和 screenshot，并报告 resultsNum、costToken。每次 prompts 只能有 1 个元素且长度不超过 255 字符；后续问题须把上一轮要点和新问题拼成新的 prompts[0]。需要用户可读报告时省略 format 或使用 markdown；只在有具体页面上下文时传 url。

展示规则

1. 按结果类型呈现：关键词搜索用表格展示位置、ASIN、标题、价格、评分、评论数、品牌和赞助状态；商品详情按 ASIN 分块，五点用列表、规格和价格用表格、变体按维度展示；评论按星级分组并先总结主题；图片搜索用商品对比表；Alexa 的 markdown 结果直接保留其问答、商品分组和追问结构。
2. 标注实时性和来源：说明数据来自亚马逊前台以及对应的搜索、详情、评论、图片或 Alexa 数据路径，并在用户关心时间时指出这是调用时快照；不要把 Alexa 推荐或视觉相似度描述为确定性结论。
3. 处理价格和站点：价格必须带币种代码或符号；同时展示原价时明确折扣；明确 amazonDomain 或 domainCode，不要跨站点混淆价格、评论和配送。
4. 展示图片与链接：详情和图片搜索中的图片 URL 可作为内嵌图片或可点击链接；搜索结果默认展示链接，不主动渲染图片；Alexa 展示商品详情 URL，截图 URL 作为补充链接。
5. 展示扩展字段：详情有 customerReviews 时展示 5—1 星分布；详情存在变体、关联商品或作者评论时分别标注其返回条件；图片搜索启用 Keepa 且字段存在时补充销售排名、月销量、FBA 费用、配送方式和更新时间；评论明确标注 Vine、认证购买、媒体和有用票数。
6. 保持字段客观：0、-1、空字符串或缺失字段按 N/A/不可用展示或省略，不将它们解释为零销量、零费用或已确认的属性；rating、价格、币种和评论数按原始响应归一化展示。
7. 报告数量和错误：始终报告 total/totalCount、resultsNum 或可用的结果数量；若 resultsNum=0 或列表为空，说明没有可用结果并建议改写 Alexa 问题或检查输入；非 200 业务状态展示 errmsg/msg，根据错误建议检查 ASIN、站点、图片 URL、排序值、邮编或参数范围。
8. 尊重不支持的操作：用户要求不支持的排序、站点、批量方式或 SQL 二次处理时，直接说明可用选项和限制，不用其他工具绕过；评论多 ASIN 分开调用，Alexa 追问遵守单 prompt 规则。
9. 说明分析性质：评论痛点、竞品比较和推荐排序是基于返回数据的整理；视觉结果是相似商品列表；不把这些结果扩展为销售预测、广告效果、历史趋势或法律判断。

解决认证和积分问题

发生以下异常情况时，读取 references/onboarding.md，按其中的 MCP 安装、WorkBuddy 自动授权异常或充值分流处理。不得把“MCP 未安装”误判为下游 401，也不得在 skill 内自行安装或热加载 MCP。

异常情况

• MCP 或 proxy_call 缺失：这是客户端配置问题。读取 onboarding，给出配置示例并停止业务调用；不尝试 HTTP 回退。
• MCP/代理层失败：isError=true、连接中断、工具不存在或 toolName 不可路由时，展示 MCP 层错误并停止。不将其当作下游业务错误，不猜测新 toolName。
• 下游响应 401：代理成功后的业务 errcode/errorCode/code=401，或消息包含 authorized error、鉴权失败、未授权、unauthorized。按 onboarding 检查 WorkBuddy 登录与自动授权状态，重启或重载连接；不得要求用户配置 MCP header，也不把凭证放入 arguments。
• 下游响应 402：代理成功后的业务状态为 402，或消息含“积分余额不足”“计费不足”“余额不足”“quota exceeded”“insufficient balance”“套餐到期”“需充值”“请充值”等同义表达时，引导用户访问 https://agent.linkfox.com/ 查看余额和充值。不得自动下单、自动选套餐或轮询支付结果，也不要把 402 当成参数错误。
• 其他下游错误：403 等非认证/计费错误不归入上述两类；透传业务错误信息，并按对应 reference 的参数和站点建议修正，不自动重试。

积分消耗说明

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