用途
本技能用于按 ASIN 获取并分析亚马逊商品评论，帮助卖家从买家反馈中提取可执行的洞察。适用于直接查询某 ASIN 的评论、按站点查询（如美国站）、差评分析、好评分析、痛点挖掘、关键词筛选评论、含图片/视频评论、仅已验证购买评论、竞品评论研究，以及从评论中提取产品改良建议等场景。
不适用于：ABA 搜索词数据/关键词研究、销量估算或营收分析、Listing 文案或 A+ 内容创作、广告/PPC 策略、定价策略或利润计算。若“产品研究”或“竞品分析”最终落到读取特定 ASIN 的客户评论，则适用；若涉及搜索量、关键词排名、销量估算或市场规模，则不适用。
主要能力
- 按 ASIN 获取真实客户评论，覆盖 15 个站点。
- 可按 1~5 星分别控制抓取数量，每星级最多 100 条。
- 排序方式：recent（最新）或 helpful（最有帮助）。
- 筛选：按关键词（最长 1000 字符）、reviewerType（all_reviews 或 avp_only_reviews 仅已验证购买）、mediaType（all_contents 或 media_reviews_only）。
- 评论以发布时的原始语言返回，实时抓取，无历史快照。
使用方式
调用采用异步流程：
- 异步提交端点：POST /amazon/reviews/async/submit
- 轮询查询端点：POST /amazon/reviews/async/result
- Python 脚本：python scripts/amazon_reviews.py '<JSON 参数>' [--inline]；每次只提交或查询一次并立即返回。
首次执行脚本只调用提交端点，保存并立即返回 taskId，不在同一次脚本调用内等待结果。需要结果时，使用原参数再次执行脚本，或传入 {"taskId":"..."}。每次执行只调用一次查询端点并立即返回，不在脚本内部循环或休眠。
根据实测经验，Pango 通常约 10~30 秒、Apify 通常约 15~60 秒返回，这不是 SLA。脚本会返回 estimatedReadyInSeconds 和 suggestedNextCheckAfterSeconds，建议先继续其他工作，到建议时间再查询，不要按最小轮询间隔忙轮询。
从任务创建时间起最多观察 200 秒。窗口内若为 PENDING 或 RUNNING，保留原 taskId，继续其他工作，约 10~20 秒后再查询；SUCCEEDED 读取 result；FAILED 向用户说明 error 并停止；CANCELLED 说明当前评论服务可能请求较多、任务在等待执行资源时已自动取消且未产生费用，建议稍后重新提交。超过 200 秒仍为 PENDING 或 RUNNING 时返回 POLL_TIMEOUT 并停止自动查询，让用户选择继续查询同一 taskId 或停止放弃，不得自动提交新任务。
未读取任务从提交起最多保留 4 小时；首次读取到终态后后端立即删除任务。脚本将成功结果保存到本地文件，24 小时本地缓存有效期内再次执行会返回 ALREADY_RECEIVED、resultFile 和本次 costToken: 0，应读取该文件，不再查后端或重新提交。
输出策略：始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-reviews-list-<timestamp>.json；响应体 ≤ 8 KB 时落盘后把完整 JSON 打印到 stdout；> 8 KB 时只输出摘要；加 --inline 强制全量打印。读数据建议先看摘要，需要具体字段时用 jq 或 ConvertFrom-Json 从保存的 json 文件按需抽取。
参数
- taskId（string，必填，异步结果）：异步提交返回的任务 ID。
- asin（string，必填，异步提交）：亚马逊商品 ASIN。
- star1Num ~ star5Num（integer，可选，异步提交）：各星级抓取数量（0-100），默认 10。
- sortBy（string，可选）：recent 或 helpful，默认 recent。
- formatType（string，可选）：all_formats 或 current_format，默认 all_formats。
- domainCode（string，可选，异步提交）：站点代码，美国站用 com，默认 com。
- filterByKeyword（string，可选，异步提交）：按关键词筛选评论（最长 1000 字符）。
- reviewerType（string，可选，异步提交）：all_reviews 或 avp_only_reviews（仅已验证），默认 all_reviews。
- mediaType（string，可选，异步提交）：all_contents 或 media_reviews_only，默认 all_contents。
星级数量默认规则：未传任何星级数量时，1~5 星默认各 10 条；传入任意星级数量后，未传星级默认 0。
支持站点
美国 com、加拿大 ca、英国 co.uk、德国 de、法国 fr、意大利 it、西班牙 es、日本 co.jp、印度 in、澳大利亚 com.au、巴西 com.br、墨西哥 com.mx、荷兰 nl、瑞典 se、阿联酋 ae。所有站点均使用 domainCode，使用前应确认用户目标站点。
使用示例
- 获取美国站评论：{"asin": "B08N5WRWNW", "domainCode": "com", "star1Num": 10, "star2Num": 10, "star3Num": 10, "star4Num": 10, "star5Num": 10, "sortBy": "recent"}
- 德国站带关键词的差评：{"asin": "B08N5WRWNW", "domainCode": "de", "star1Num": 30, "star2Num": 30, "filterByKeyword": "quality", "reviewerType": "avp_only_reviews"}
- 日本站含媒体的 5 星评论：{"asin": "B08N5WRWNW", "domainCode": "co.jp", "star5Num": 50, "star1Num": 0, "star2Num": 0, "star3Num": 0, "star4Num": 0, "sortBy": "helpful", "mediaType": "media_reviews_only"}
- 仅 3 星评论：{"asin": "B0FP5C63HZ", "domainCode": "com", "star3Num": 100}
展示规则
按星级分组展示评论，关键字段包括：评分、标题、正文、日期、验证状态、有帮助数。评论较多时先给出主题/痛点摘要再列单条。突出可执行洞察：指出差评中反复出现的抱怨，记录好评中被称赞的功能。明确标注 Vine Voice 与已验证购买状态，注明评论是否含图片或视频。原始响应使用站点特定文本格式时，对评分与有帮助数做归一化展示。查询失败时根据响应消息说明原因并建议调整参数。用户询问多个 ASIN 时，需分别请求。
限制
- 每次请求仅支持一个 ASIN。
- 每星级每次最多返回 100 条评论。
- filterByKeyword、reviewerType、mediaType 在异步提交时可用，包括 domainCode: "com"。
- 无历史快照，评论为实时抓取。
- 评论以原始语言返回。
算力消耗
按计划抓取页数动态计费。设 P = Σ min(ceil(各星级请求评论数 / 10), 10)，则计费 Token：21000 × P；实际消耗算力 = ceil((21000 × P) / 2000) = ceil(10.5 × P)，按每次请求分别向上取整。未传任何星级数量时，1~5 星默认各 10 条，P = 5，消耗 53 算力。传入任意星级数量后，未传星级按 0；五个星级均显式传 0 时，P = 0，不调用供应商且消耗 0 算力。请求成功但结果为空，或经关键词、认证购买、媒体筛选后为空，仍按计划页数计费；部分子任务失败但整体成功时仍按全部计划页数计费；调用完全失败不计费。常见消耗：1 页 11 算力，2 页 21 算力，5 页 53 算力，10 页 105 算力。费用按请求的抓取页数计算，而不是按最终返回评论数计算；请求多个星级或大量评论前必须向用户说明预计页数和算力消耗。上述公式只用于调用前预估，实际是否扣费及扣费数额只以首次成功领取结果时返回的 X-Cost-Token/costToken 为准。
认证与算力问题
发生以下异常时，采用 references/onboarding.md 引导解决：未配置 API Key（环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY）；响应 401 或 402 状态码；响应提示算力或余额不足（消息含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义）。
反馈
当技能功能或用途与实际行为不符、结果与用户意图不符、用户表达不满或赞扬、或有可改进之处时，自动通过 Feedback API 检测并上报反馈，不打断用户流程。