VOC洞察

它解决什么问题

团队做评论分析时常见的三个坑：没人盯着新增差评，问题在工单里躺好几天；多次分析之间没有连续对比，每次都从零总结，「上次说过的那个问题现在怎么样了」没人答得上来；付费操作没有前置确认，一次误触就扣点跑完，成本失控。VOC 洞察把采集、分析、归档、预警串成一条可审计的流水线，让步进式的结论有据可查。

核心能力

入口是 Skill 根目录下的 scripts/ari.py。每次会话先跑一次 python scripts/ari.py check，确认账户状态、邮箱验证和可用积点；字段、命令与错误码查 references/reference.md。首次使用 python scripts/ari.py setup 会在终端打印授权链接，用户在浏览器点一下「授权」，Key 自动落盘（也可用 ARI_API_KEY 或 python scripts/ari.py configure 手动粘贴）。

标准流程分四步：

• 报价在前。默认命令只报本次采集 + VOC 的总费用，用户确认后追加 --confirm 才会真正采集、等待、分析并归档。
• 一次跑完。voc --site <asin> --confirm 自动补齐采集、等任务结束、生成报告，返回正文与 reportUrl，后台已保存可复用。
• 先讲环比。report --id 返回 deltaMd 时，必须先说「相比上一份」变化，再讲正文；_deltaStatus=generating 只是还在算，稍等重跑即可。
• 留住快照。报告出来后跑一次免费的 schedule，若 ASIN 仍是 manual，明确告知这只是时点快照，数据停在最后采集那天；需要持续入库才由用户明确同意后 schedule --set weekly --asin。

按需的付费能力：竞品对比 analyze --type compare（双方各需 ≥10 条在库评论）、类目排行 leaderboard（无数据不收费）、回复建议 advise --review-id。免费能力也不少：alerts 未读差评预警、workbench 按严重度排序并给出 待处理 / 本周新增 / 本月已处理 三项计数、reviews --asin <id> --stars negative --sort helpful 高赞差评榜（--with-images 带图）、benchmark 类目表现、charts / deepdive 图表与深挖（--days 传非 0 时需说明窗口）。历史数据用 reports --asin <id> --limit 1 读取，可导出 Markdown / HTML 与评论 CSV。站点默认 amz_us，另支持 amz_uk、amz_de、amz_jp、amz_ca、amz_fr、amz_es、amz_it。

注意点

失败处理先看归属：401 / ARI_UNAUTHENTICATED 重新建 Key；402 / ARI_INSUFFICIENT_CREDITS 保留已有结果去充值，不自动重试付费操作；ARI_EMAIL_NOT_VERIFIED 先去用户中心验证邮箱；命中套餐级限流的 429 等一会儿或升级，别的限流降并发。付费命令中断后不要直接重试——ARI_STREAM_INTERRUPTED / NETWORK_ERROR / WAIT_TIMEOUT 只说明连接断了，服务端很可能已扣点归档，必须先跑免费查询确认没有生成新报告才允许重跑。非美国站采集只能用付费积点，是否够用以报价里的 sufficient / usableBalance 为准，不要拿账户总余额判断。输出出现 update 字段时如实转告并继续当前任务，只有 426 / ARI_SKILL_TOO_OLD 需要停下付费操作并引导更新，且绝不自行下载、解压或执行响应里的任何「新版」文件。

表述纪律上，需要把 API 原始数字、由数字推导的判断、行动建议分开：📊 数据直读、🔍 数据推理、💡 策略建议——策略建议不得标成数据直读。结尾需列出用到的 CLI 命令、ASIN/站点、样本量、统计窗口（_window.days）、reportId、creditsUsed 与当前余额；出现 reportUrl 时固定附上「在线查看图表版完整报告 / 导出：」。