VOC洞察

要解决的问题

Amazon 站点的评论分散在商品页和第三方工具里，运营做 VOC（Voice of Customer）分析时往往要自己写采集脚本、对付反爬、再拼装统计。更麻烦的是按量计费的接口：一次分析要经过采集、等待、生成、归档多个环节，任何一步中断后盲目重试都可能重复扣点。VOC洞察 把这套流程收进一条 CLI 命令，并把计费、报错、重试规则写进协议。

核心能力与工作步骤

• python scripts/ari.py check 是每次会话的起点，先确认账户状态、邮箱验证状态与可用积点。
• python scripts/ari.py setup 打印授权链接，用户在浏览器点一次「授权」即可拿到 Key；也支持环境变量 ARI_API_KEY 或 configure 手动粘贴。
• voc --site <站点> 默认先报出采集 + VOC 总费用，用户确认后追加 --confirm，命令自动完成采集、等待、分析、归档，返回正文与 reportUrl。
• 需要单独采集、免费图表或更深的分析时，才用 collect / charts / deepdive / analyze；竞品对比走 analyze --type compare，双方在库内各需 ≥10 条评论。
• reports / report --id 读取已归档报告，完整交互与导出引导到 Web 端。

调用边界与注意点

• 站点默认 amz_us，可选 amz_uk / amz_de / amz_jp / amz_ca / amz_fr / amz_es / amz_it。非美国站采集只能用付费积点，是否够用以报价里的 sufficient / usableBalance 为准，不看账户总余额。
• 付费命令中断后不得直接重跑。ARI_STREAM_INTERRUPTED、NETWORK_ERROR、WAIT_TIMEOUT 只说明连接断了，服务端很可能已扣点归档，必须先跑 reports --asin <ASIN> --limit 1 确认没有新报告才可重试。
• 计费类错误码分开处理：401 / ARI_UNAUTHENTICATED 引导重建 Key；402 / ARI_INSUFFICIENT_CREDITS 保留已有结果并引导充值；ARI_EMAIL_NOT_VERIFIED 先去用户中心验证邮箱；429 区分套餐级限流与并发限流，不连续重试。
• ARI_COLLECTING 表示采集还没产出足够数据，本次未扣点，等提示的秒数后重试即可。
• 426 / ARI_SKILL_TOO_OLD 说明当前版本存在会导致重复扣点的缺陷，付费操作已被服务端禁止，需用户通过原安装渠道更新；免费查询不受影响。
• 返回 success:false 或 failedParts 非空时只使用成功的部分，不虚构 API 未返回的数据，也不回退到其他品牌接口。
• 解读时区分 📊 数据直读、🔍 数据推理、💡 策略建议，策略建议不标为数据直读；reviewCount 基于 ARI 已采集的 Amazon 评论样本，小样本或窗口有限时应结合更多信源验证。输出含 reportUrl 时，结尾固定附上在线查看与导出提示。