{"id":"68f15ecb-ffe5-4b17-9ef3-9c0fa8b31a57","entityType":"agent","slug":"clawhub-funewa-amazon-variant-analysis","name":"Amazon Voc","canonicalUrl":"https://www.xpersona.co/agent/clawhub-funewa-amazon-variant-analysis","canonicalPath":"/agent/clawhub-funewa-amazon-variant-analysis","generatedAt":"2026-10-10T10:42:45.953Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:39:26.640Z","emptyReason":null},"description":"亚马逊买家之声：评论采集 + VOC 洞察报告","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17ddkyn6xqtz4f83y2v0marjh89xqb5:amazon-variant-analysis","sourceUrl":"https://clawhub.ai/funewa/amazon-variant-analysis","homepage":"https://clawhub.ai/funewa/skills/amazon-variant-analysis","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/funewa/amazon-variant-analysis","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/funewa/skills/amazon-variant-analysis","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Amazon Voc technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:39:26.640Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:39:26.640Z","emptyReason":null},"stars":null,"forks":null,"downloads":1585,"packageName":null,"latestVersion":"0.1.4","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:39:26.639Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T07:39:26.640Z","lastCrawledAt":"2026-10-10T07:39:26.639Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T07:39:26.639Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.4","createdAt":"2026-09-14T09:36:41.752Z","changelog":"**Skill renamed and expanded from \"amazon-variant-analysis\" to \"amazon-voc\"; major scope upgrade with full VOC analytics and workflow support.** - Renamed skill from “亚马逊变体分析” (amazon-variant-analysis) to “Amazon-VOC”. - Expanded from variant-level comparison to full Amazon VOC (Voice of Customer) analysis, covering feedback insights, pain points, buyer personas, trend analysis, and actionable recommendations. - Added end-to-end workflow: comments collection, VOC reports, competitor comparison, automated monitoring, alerts, and detailed operational guidance. - Updated documentation and usage instructions to reflect new features, workflow steps, and command-line/API changes. - Introduced stricter security, confirmation, and billing protocols according to ARI’s latest requirements. - Provided an added CHANGELOG.md and removed redundant skill-card.md.","fileCount":12,"zipByteSize":61587},{"version":"0.1.3","createdAt":"2026-09-14T01:34:32.444Z","changelog":"- Removed the file skill-card.md. - No other functional or user-facing changes.","fileCount":11,"zipByteSize":35775},{"version":"0.1.2","createdAt":"2026-09-03T13:49:05.470Z","changelog":"amazon-variant-analysis 0.1.2 - Major SKILL.md simplification: removed detailed advanced workflows, product monitoring, and operational flows for a much more concise documentation. - Updated metadata version to 1.3.0. - File structure improvement: added subfolders (agents, references, scripts). - Added references/reference.md and scripts/ari.py; removed obsolete skill-card.md. - Documentation updates in README.md and 使用说明.md.","fileCount":11,"zipByteSize":35913},{"version":"0.1.1","createdAt":"2026-08-31T08:00:13.111Z","changelog":"- Removed sample files: \"agents\", \"references\", \"scripts\", and \"skill-card.md\" directories/files. - SKILL.md updated with new metadata fields, revised workflow, and expanded usage and workflow details. - Version updated to 1.4.3 with enhanced instructions for scheduled reports, monitoring workflow, and compliance checks. - No code or API changes—only documentation and structural updates; some directory/file content now omitted.","fileCount":8,"zipByteSize":50529},{"version":"0.1.0","createdAt":"2026-08-12T13:03:03.526Z","changelog":"Initial release of amazon-variant-analysis skill: - Provides Amazon variant comparison (color, size, specification) and opinion analysis for parent-child ASINs. - Identifies problematic variants lowering overall ratings and high-performing variants. - Requires ARI API key; setup instructions and key management included. - Handles authentication, billing, and error protocols strictly. - Follows clear reporting structure with data sourcing and command traceability. - Free and paid analysis flows are clearly distinguished; safeguards to prevent duplicate charges.","fileCount":11,"zipByteSize":35928}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ddkyn6xqtz4f83y2v0marjh89xqb5:amazon-variant-analysis","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17ddkyn6xqtz4f83y2v0marjh89xqb5:amazon-variant-analysis` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/funewa/amazon-variant-analysis before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T10:42:45.949Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-funewa-amazon-variant-analysis/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:39:26.640Z","emptyReason":null},"readme":"Skill: Amazon Voc\n\nOwner: funewa\n\nSummary: 亚马逊买家之声：评论采集 + VOC 洞察报告\n\nTags: latest:0.1.4\n\nVersion history:\n\nv0.1.4 | 2026-09-14T09:36:41.752Z | auto\n\n**Skill renamed and expanded from \"amazon-variant-analysis\" to \"amazon-voc\"; major scope upgrade with full VOC analytics and workflow support.**\n\n- Renamed skill from “亚马逊变体分析” (amazon-variant-analysis) to “Amazon-VOC”.\n- Expanded from variant-level comparison to full Amazon VOC (Voice of Customer) analysis, covering feedback insights, pain points, buyer personas, trend analysis, and actionable recommendations.\n- Added end-to-end workflow: comments collection, VOC reports, competitor comparison, automated monitoring, alerts, and detailed operational guidance.\n- Updated documentation and usage instructions to reflect new features, workflow steps, and command-line/API changes.\n- Introduced stricter security, confirmation, and billing protocols according to ARI’s latest requirements.\n- Provided an added CHANGELOG.md and removed redundant skill-card.md.\n\nv0.1.3 | 2026-09-14T01:34:32.444Z | auto\n\n- Removed the file skill-card.md.\n- No other functional or user-facing changes.\n\nv0.1.2 | 2026-09-03T13:49:05.470Z | auto\n\namazon-variant-analysis 0.1.2\n\n- Major SKILL.md simplification: removed detailed advanced workflows, product monitoring, and operational flows for a much more concise documentation.\n- Updated metadata version to 1.3.0.\n- File structure improvement: added subfolders (agents, references, scripts).\n- Added references/reference.md and scripts/ari.py; removed obsolete skill-card.md.\n- Documentation updates in README.md and 使用说明.md.\n\nv0.1.1 | 2026-08-31T08:00:13.111Z | user\n\n- Removed sample files: \"agents\", \"references\", \"scripts\", and \"skill-card.md\" directories/files.\n- SKILL.md updated with new metadata fields, revised workflow, and expanded usage and workflow details.\n- Version updated to 1.4.3 with enhanced instructions for scheduled reports, monitoring workflow, and compliance checks.\n- No code or API changes—only documentation and structural updates; some directory/file content now omitted.\n\nv0.1.0 | 2026-08-12T13:03:03.526Z | auto\n\nInitial release of amazon-variant-analysis skill:\n\n- Provides Amazon variant comparison (color, size, specification) and opinion analysis for parent-child ASINs.\n- Identifies problematic variants lowering overall ratings and high-performing variants.\n- Requires ARI API key; setup instructions and key management included.\n- Handles authentication, billing, and error protocols strictly.\n- Follows clear reporting structure with data sourcing and command traceability.\n- Free and paid analysis flows are clearly distinguished; safeguards to prevent duplicate charges.\n\nArchive index:\n\nArchive v0.1.4: 12 files, 61587 bytes\n\nFiles: _meta.json (142b), agents (0b), agents/openai.yaml (207b), CHANGELOG.md (3517b), README.md (3367b), references (0b), references/reference.md (18437b), scripts (0b), scripts/ari.py (90386b), skill-card.md (2860b), SKILL.md (20013b), 使用说明.md (17427b)\n\nFile v0.1.4:SKILL.md\n\n---\r\nname: amazon-voc\r\ndisplay_name: Amazon-VOC\r\ndescription: >\r\n Amazon VOC（买家之声）评论分析 Skill：采集亚马逊评论并生成 VOC 洞察报告，\r\n 提炼差评痛点、购买动因、用户画像、使用场景与 Listing 优化建议，\r\n 支持竞品对比与趋势分析。\r\n 本包同时提供 ARI 完整评论分析能力：订阅 ASIN 并采集评论、浏览与筛选评论、\r\n 查看星级/关键词/趋势与雷达图表、生成 VOC 与深度洞察等分析报告、\r\n 运行商品运营工作流、商品变化监控（watch）、差评预警与差评工作台、\r\n 行业对标与类目排行，并导出评论 CSV 与报告 Markdown/HTML。\r\n Use when the user asks about Amazon VOC, voice of customer,\r\n buyer feedback, review mining, 买家之声、客户之声、VOC 分析、评论挖掘、评论采集、\r\n 消费者反馈、差评分析。\r\n Requires an ARI API key (ari_live_*).\r\nallowed-tools: Bash\r\nauthor: ARI (funewa)\r\nagent_created: true\r\nslug: amazon-voc\r\ndisplayName: Amazon-VOC\r\nversion: 1.4.10\r\nsummary: 亚马逊买家之声：评论采集 + VOC 洞察报告\r\nlicense: MIT\r\n---\r\n\r\n# Amazon-VOC 买家之声\r\n\r\n## 自然语言入口与输出\r\n\r\n- 用户只需表达商品和目标，例如“分析美国站 B0XXXXXXXX 的评论，简要说说主要问题和趋势”。\r\n 从对话中提取 ASIN、站点、范围和输出长度，复用已明确的信息；不要要求用户填写命令、\r\n workflow/focus 或默认页数。无站点信息时默认美国站并说明。\r\n- 用户只问简析时先查看已有评论、图表和历史报告；足够回答就直接简析。数据不足时说明缺口，\r\n 按后续工作流处理必要采集或分析。专用 Skill 以固定入口为准，不转成通用 VOC。\r\n- 没有显式变体采集开关时，不要让用户选择工具无法执行的范围，也不要承诺“只含当前子体”\r\n 或“包含全部变体”。按接口实际返回范围说明限制；范围影响结论时再澄清。\r\n- 简短问题优先输出：数据范围、主要问题与评论依据、趋势判断。样本或时间跨度不足时明确说明，\r\n 不把新入库的旧评论说成新发生的趋势；不强制展开完整报告。\r\n- 安装授权步骤见“使用说明.md”；字段和高级命令按需读取 references/reference.md。\r\n 用户未要求技术细节时，不展示内部任务标识、参数清单或命令日志。\r\n- 费用按下方协议和服务端规则处理；用户明确说“只报价，不执行”时，仅调用免费的 quote\r\n 和必要的 collect 报价，不运行可能免确认执行的 voc/analyze，也不擅自修改账户确认设置。\r\n\r\n## 工具与入口\r\n\r\n- CLI：本 Skill 目录下的 `scripts/ari.py`。在 Skill 根目录执行，例如\r\n `python scripts/ari.py check`；每次会话先跑一次 `check`。\r\n- API 参考：需要字段、命令或错误码时读取 `references/reference.md`。\r\n- API Key：首次使用运行 `python scripts/ari.py setup`——它会给出一个授权链接，\r\n 用户在浏览器登录（或注册）后点一下「授权」，Key 自动获取并保存到本机，无需复制粘贴。\r\n 也可用环境变量 `ARI_API_KEY`，或 `python scripts/ari.py configure` 手动粘贴。\r\n `setup` 期间把命令打印的授权链接原样转告用户，等待命令自行完成；**不要**替用户注册或登录。\r\n- 申请 Key（手动方式）：\r\n- 充值/套餐：\r\n- Web 产品管理：\r\n\r\n## 安全与计费协议\r\n\r\n- 所有 API 请求和授权入口仅支持 `https://ari.funewa.com`，禁止重定向。\r\n `ARI_ENDPOINT_BLOCKED` / `ARI_REDIRECT_BLOCKED` 时停止操作；不要设置其他端点、\r\n 开启旧 `ARI_ALLOW_CUSTOM_BASE` 或关闭 TLS 校验来绕过。详见 references/reference.md。\r\n\r\n- 缺少 Key 时立即停止，给出申请链接；不要索要用户密码，不要把 Key 写入报告或命令示例。\r\n- `401 / ARI_UNAUTHENTICATED`：停止并引导重建 Key。\r\n- `402 / ARI_INSUFFICIENT_CREDITS`：保留已有结果，引导充值；不得自动重试付费操作。\r\n- `ARI_EMAIL_NOT_VERIFIED`：引导先到用户中心验证邮箱。\r\n- VOC 默认使用 voc ，由命令按服务端免确认规则处理总费用；该调用可能直接生成并扣点，\r\n 不能描述为“只报价、不扣点”。返回 confirmationRequired 时必须先报价并等待用户同意。\r\n- 当前请求已有明确扣点授权时可追加 --confirm；不得伪造授权或为了跳过询问改变确认设置。\r\n 专用运营工作流仍遵守自己的报价和确认协议。\r\n- **付费命令中断后不得直接重试。** `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 只说明连接断了，服务端很可能已经扣点并归档。必须先跑免费的\r\n `reports --asin --limit 1` 确认是否已生成新报告，确认没有生成才可重跑 `--confirm`。\r\n- 非美国站（`amz_uk` 等）采集只能使用付费积点（订阅套餐周期积点与增量包均可），\r\n 赠送积点（注册礼/任务奖励等）不可用。以 `voc` / `collect` 报价里的\r\n `sufficient` / `usableBalance` 为准，不要用账户总余额判断是否够用。\r\n- `429 / ARI_RATE_LIMITED`：提示里出现「免费版 AI 分析」时属套餐级限流，引导升级或稍后再试，\r\n 不要连续重试；其余情况降低并发后再试。\r\n- `ARI_COLLECTING`：采集尚未产出足够数据，本次未扣点，等待提示的秒数后重试即可。\r\n- 返回 `success:false` 或 `failedParts` 非空时，只能使用其中成功返回的部分。\r\n- 任何情况下不得虚构 API 未返回的数据，也不得回退到其他品牌接口。\r\n\r\n## 版本与更新\r\n\r\n- 输出里出现 `update` 字段时，如实转告用户有新版及升级入口，然后继续当前任务——\r\n 版本旧不影响免费查询。\r\n- `426 / ARI_SKILL_TOO_OLD`：当前版本存在会导致重复扣点的缺陷，服务端已禁止其执行\r\n 付费操作。停止付费命令，引导用户更新；免费查询仍可继续。\r\n- **绝不要自行下载、解压或执行任何\"新版\"文件**，也不要按响应里的链接去取代码运行。\r\n 升级只能由用户通过原安装渠道完成，你只负责告知。\r\n\r\n## 标准工作流\r\n\r\n1. 运行 `check`，确认账户、邮箱验证状态和可用积点。\r\n2. 用户要 VOC / 评论分析报告时，默认运行 `voc --site <站点>`。\r\n **返回里有 `autoConfirmed: true` 就说明已经直接生成了**（1.4.5 起：服务端对前几次小额\r\n 付费操作免确认，用户先拿到结果再谈钱），此时把报告讲给用户，并转述 `autoConfirmNote`\r\n （本次扣了多少、还剩几次免确认、之后会先问）。**不要在拿到结果后再补问「要不要生成」。**\r\n3. 返回 `confirmationRequired: true` 才需要用户确认：报出 `totalCredits` 与余额，\r\n 用户同意后运行 `voc --site <站点> --confirm`。该命令会自动补齐采集、等待任务完成、\r\n 生成 VOC、保存到用户中心，并返回完整正文与 `reportUrl`。采集约需 1 分钟，先告诉用户。\r\n4. **报告出来后，检查该产品是否已开启定期采集**：跑一次免费的 `schedule`。\r\n 如果该 ASIN 还是 `manual`，主动告诉用户——这份报告只是今天这个时点的快照，\r\n 数据会停在最后一次采集那天；开启 `weekly` 后新评论持续进库，下次生成报告时\r\n 还能给出「相比上一份：哪些问题解决了、哪些是新冒出来的、哪些还在恶化」。\r\n **报出月成本**（`schedule --set` 的返回里带 `_costNote`）让用户自己决定，\r\n 得到明确同意后才执行 `schedule --set weekly --asin `。不要替用户默认开启。\r\n5. 只有用户明确要单独采集、免费图表或其他分析类型时，才使用\r\n `collect` / `charts` / `deepdive` / `analyze`。\r\n6. 竞品对比同样先报价后确认，双方在库内各需 ≥10 条评论：先运行\r\n `analyze --type compare --asin <目标> --competitor <竞品>` 取价，用户确认后再追加 `--confirm`。\r\n 竞品用 `competitors --id <产品id> --add <竞品ASIN>` 绑定后会按周自动采集，\r\n 攒够几周就可以用免费的 `radar --id <产品id>` 看本品 vs 竞品的走势对比。\r\n7. 使用 `reports` / `report --id` 读取已归档报告；**`report --id` 返回 `deltaMd` 时\r\n 必须先讲环比再讲正文**——用户最想知道的是「跟上次比变了什么」。\r\n `_deltaStatus=generating` 表示还在后台算，等十几秒重跑即可，不是失败。\r\n `export --report-id ` 可导出 Markdown/HTML，`export --asin ` 导出评论 CSV\r\n （付费套餐功能，不扣积点）。\r\n8. 会话开始跑 `check` 之后顺手跑一次 `alerts`：有未读差评预警时主动告诉用户，\r\n 并提议用 `workbench` 定位差评、`advise --review-id ` 生成回复建议（付费，\r\n 同样先报价、用户确认后才 `--confirm`）。\r\n `workbench` 默认按严重度排序，返回里的 `stats` 给出「待处理 / 本周新增 /\r\n 本月已处理」——**汇报时先说这三个数字再说具体条目**，让用户看见自己在推进。\r\n9. 用户问「哪几条差评最伤转化」用 `reviews --asin --stars negative --sort helpful`\r\n （高赞差评榜，免费）：买家在商品页最先看到的就是这几条。带图差评加 `--with-images`。\r\n10. 用户问「行业/类目里表现如何」用免费的 `benchmark --asin `；要看类目排行\r\n （`leaderboard`）时先报价，确认后 `--confirm`（类目无数据不收费）。\r\n11. 用户问「广告投什么词」「Search Terms 怎么写」「否定词」「买家怎么称呼这个产品」时，\r\n 用 `analyze --type keywords --asin `（1.4.4，先报价、确认后 `--confirm`）。\r\n 报告直接给出核心搜索词、长尾/场景词、否定词候选、竞品品牌词和一条 ≤250 字节的\r\n 后台 Search Terms 字串，关键词保持站点搜索语言。**VOC 报告出来之后主动提一句**：\r\n 评论里买家的用词就是最好的关键词来源，多数卖家没意识到这份数据可以直接投广告。\r\n12. 用户问「大家都在抱怨什么」「某个问题有多少人提」「这个问题最近是不是变多了」\r\n 「竞品在这一点上比我好还是差」时，先用免费的 `topics --id <产品id>`（1.4.7）：\r\n 每条评论入库后已自动打上「维度 + 话题 + 原句」，这里给出每个话题的提及数、\r\n 4~5 星 / 1~3 星拆分、近 30 天新增。追问某个话题用 `topics --id <产品id> --key <话题key>`，\r\n 返回近 12 个月趋势、常见原句、本品 vs 竞品的提及率与差评占比、以及一段标签洞察摘要。\r\n 要看原始评论用 `reviews --asin --topic <话题key>`，返回行的 `tags[].sentence`\r\n 就是支撑该标签的原句，引用时直接用它，不要自己改写。\r\n `progress.tagged < progress.total` 表示还在后台打标，告诉用户几分钟后再看，不要当成没数据。\r\n 这一整套不扣积点；它和付费的 VOC / 深度洞察的区别是：这里是全量精确计数，报告是抽样加解读。\r\n\r\n## 新手与老手都在这里把事做完（1.4.5）\r\n\r\n我们的用户是运营人员，不是技术人员。**不要让他们记命令、不要让他们配置**——所有判断由你做，\r\n用户只说自然语言。网页是补充视图（图表、分享链接、海报），不是把人送走的地方。\r\n\r\n**确认与扣点**\r\n- 报价返回 `autoConfirm: true` 时直接生成，不要再问「要不要」。生成后一句话交代：本次扣了多少、\r\n 还剩几次免确认（或「免费版小额不问」）。策略由服务端决定：免费版小额不问；付费版前几次不问，之后先问。\r\n- 用户说「以后别问了 / 50 以内直接做」→ 运行 `autoconfirm 50`；说「以后每次先问我」→ `autoconfirm off`；\r\n 说「恢复默认」→ `autoconfirm default`。这是唯一需要你代用户设置的东西，设完复述一句当前规则。\r\n- 报价需要确认时，只说两个数：这次多少积点、余额多少，然后等用户一个「好」。采集是**固定单价**：直接说「15 积点/页 × 3 页 = 45 积点」，不要说成「预计 / 最多」——价格不会浮动；商品评论不够这么多页时只收实际采到的页数，差额自动退回（`pricingNote` 已写好这句）。不要罗列参数。\r\n\r\n**新手（`check` 返回 `autoConfirm.mode` 为 `first_runs` / `free_small`，或问\"然后呢\"）**\r\n- 报告讲完只推一个下一步，附接口返回的成本，不写死月费用。用户同意再 `schedule --set weekly`。\r\n- 不解释命令名，不列功能清单。用户问「还能做什么」时按他的产品状态给一条建议，不超过三句。\r\n\r\n**老手（主动说 ASIN、站点、要什么报告）**\r\n- 直接执行，输出用 `--compact`，多 ASIN 逐个跑完再汇总，不逐条请示。\r\n\r\n**网页链接的用法**\r\n- 每份报告末尾附 `web.report`，措辞是「网页版有健康度图表和频次表，可生成分享链接与海报」——是补充，不是「建议你去网页」。\r\n- 用户要把报告发给同事/发群：指向网页报告页的「分享」按钮，不要把整篇 Markdown 贴给他转发。\r\n- 用户要接群机器人提醒：给 `links.notify`（用户中心 → 通知渠道），这一步只能在网页做。\r\n- 询价后用户没回应，不要追问。下次对话 `products` 里看到该 ASIN 仍是 `idle`，提一句\r\n 「上次的 X 还没生成，我现在直接给你出」即可（免确认命中会直接生成）。\r\n\r\n## 商品运营工作流（1.4.1）\r\n\r\n- 用户要求 ASIN 运营体检、Listing 健康检查、商品页审查、评论转行动或运营周报时，\r\n 使用 `operations` 命令；不得把旧 VOC、alerts 或普通 reports 冒充商品运营结果。\r\n- 先运行 `operations capabilities`，只使用服务端返回的 workflow/focus；专属变体包\r\n 还会在包根目录固定 workflow/focus 并禁止接收任意 prompt；本包是通用入口，不受此限制。\r\n- 用 `operations profile` 检查商品字段，再运行 `operations quote`。评论不足时只建议\r\n 用户使用现有 `collect`，不得隐式采集；商品关键字段不足时不得生成或扣点。\r\n- 未得到用户明确扣点授权时，只返回 quote。授权后使用 quote 返回的完整 request 和同一\r\n `requestId` 执行 `operations run --confirm`，不得换 requestId 或修改 workflow/focus。\r\n- 流中断或超时后绝不直接重跑。必须运行\r\n `operations status --request-id <原requestId>` 精确查询；completed 时使用其 reportId，\r\n quoted/running/frozen 时继续等待，released/failed 时说明错误并请求用户决定下一步。\r\n\r\n## 商品变化监控工作流（1.4.1）\r\n\r\n- `watch` 是独立的确定性监控管理入口，不是付费 `operations` workflow。使用前先运行\r\n `operations capabilities`，确认当前账户的 `watchEnabled` 为 `true`；开关或灰度未开放时\r\n 必须停止并提示用户，不得回退到其他工作流。\r\n- 本节是 1.4.1 的 CLI 契约说明；对应 Wave E 候选仍为 `planned`，未表示已公开上架或所有账户可用。\r\n- `watch create` 只接受当前账户已订阅的主 ASIN。可选 `--competitor` 仅在该竞品已通过当前用户\r\n 的主品/竞品关系绑定、且站点与主品相同后才允许创建竞品 watch；不得用临时 ASIN、全局商品资料\r\n 或其他参数绕过归属校验。Wave E 的 `competitor-change` listing 仍为 planned，未公开上架。\r\n- `watch list`、`watch digest` 和 `watch events` 是只读操作，可按用户问题直接读取；不得把读取\r\n 结果当成用户同意变更监控。\r\n- `watch create`、`watch pause`、`watch resume` 和 `watch delete` 都是管理动作，只有用户明确\r\n 要求对应动作时才执行；“持续监控指定 ASIN + 周期”可视为明确的 `create` 意图，但“帮我看看”\r\n 或“有什么变化”等表述仍按只读处理。执行 `delete` 前必须向用户复述并核对准确的 `watch-id`；\r\n ID 不明确或目标不唯一时先停止询问。删除只移除该用户的监控关系，不删除共享商品资料、快照、\r\n 评论或历史报告。\r\n- 固定 CLI 入口如下：\r\n\r\n ```bash\r\n python scripts/ari.py watch list\r\n python scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\r\n python scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\r\n python scripts/ari.py watch pause --watch-id \r\n python scripts/ari.py watch resume --watch-id \r\n python scripts/ari.py watch delete --watch-id \r\n python scripts/ari.py watch digest --watch-id --period 7d\r\n python scripts/ari.py watch events --watch-id \r\n ```\r\n\r\n- `create`/`resume` 只使用服务端支持的 `weekly` 或 `daily`；`daily` 受套餐\r\n `dailyProductWatch` 权益限制，Free 不开放自动日扫描。修改周期前先向用户说明套餐额度和\r\n 扫描成本，不能默认开启监控。\r\n- `digest` 只汇总商品快照、确定性 Diff 和已有评论计数，返回 `creditsUsed: 0`；自动扫描和\r\n 事件读取不调用付费 LLM、不扣 AI 积点。它不提供小时级或实时价格、销量、库存、广告、订单\r\n 或真实退货率数据。\r\n- AI 周报仍使用 `operations` 的 `weekly` workflow，必须先报价，只有用户明确确认后才可\r\n `operations run --confirm`；不得把周报混入免费的 `watch digest`。\r\n\r\n站点默认 `amz_us`；可选 `amz_uk/amz_de/amz_jp/amz_ca/amz_fr/amz_es/amz_it`。\r\n`charts` / `deepdive` 的 `--days` 默认 0（全部历史）；传非 0 时图表只覆盖该窗口，\r\n解读占比和趋势必须带上这个窗口说明。\r\n\r\n## 解读纪律\r\n\r\n- 把 API 数字、由数字推导的判断、行动建议明确区分：`📊 数据直读`、`🔍 数据推理`、\r\n `💡 策略建议`。策略建议不得标为数据直读。\r\n- `reviewCount < 50` 时在报告顶部标注小样本提示；单次提及只能作为方向性线索。\r\n- 痛点优先级同时考虑提及频率、低星程度、近期趋势和已验证购买，不凭单条评论下结论。\r\n- 用好评高频表达提炼 Listing 语言，但引用评论原话时保持短句并注明来自评论样本。\r\n- 竞品对比只比较双方 API 均有数据的指标；一方样本不足时明确写“不可比”。\r\n- 报告语言跟随用户；ASIN、VOC、Listing 等术语保留原文。非中文回复时记得传\r\n `--language en` 等，CLI 默认是 `zh`。\r\n\r\n## 完整报告结构（简析按用户要求缩短）\r\n\r\n按有数据的部分输出：数据概览 → 痛点与低星原因 → 好评与购买动因 → 用户画像与场景 →\r\n趋势 → 竞品差异 → Listing 建议 → 产品改进优先级 → 数据来源与积点用量。\r\n\r\n报告顶部加入：\r\n\r\n> 数据基于 ARI 已采集的 Amazon 评论样本（截至当前查询时间），仅供经营决策参考；\r\n> 小样本或采集窗口有限时应结合更多信源验证。\r\n\r\n结尾简要列出 ASIN/站点、样本量、统计窗口（`_window.days`）、报告返回的\r\n`reportId` 与 `creditsUsed`，以及当前余额。**输出含 `reportUrl` 时必须在结尾附上**，\r\n固定文案：「在线查看图表版完整报告 / 导出：」（需登录报告所属账户）。\r\n\r\nCLI 命令仅在用户要求或排障需要时展示；用户要求简短时仍保留数据范围与实际用量。\n\nFile v0.1.4:README.md\n\n# Amazon-VOC\n\n亚马逊买家之声：评论采集 + VOC 洞察报告\n\n## 一句话开始\n\n安装授权后，把下面这句话发到 AI 客户端对话框，替换示例 ASIN 即可：\n\n~~~text\n分析评论，简要说明主要问题和趋势。商品 B0XXXXXXXX（美国站）。\n~~~\n\n示例 ASIN 是占位符。AI 会识别商品、站点和目标，无需填写接口参数。\n客户端未选中时，在问题前加“使用 $amazon-voc”。\n缺少必要资料或目标不唯一时，AI 会说明需要补充什么；专用 Skill 只处理本页对应场景。\n\n## 第一次使用：安装并授权\n\n1. 通过市场安装本 Skill，或使用 ARI 用户中心的安装指令交给 AI 客户端安装。\n2. 对 AI 说：“帮我完成 ARI 授权并检查是否可用。”\n3. 打开 AI 返回的链接，自己登录或注册并授权；无需在聊天中粘贴 API Key。\n4. AI 确认连接、余额和扣点规则后，直接发送你的问题。\n\n需要支持 Skill 和本地 Python 3 的 AI 客户端。安装检查不采集评论、不生成付费报告、不开启监控。\n\n## 会得到什么\n\n- 先回答你提出的问题，附样本范围和评论依据；你说“简短”时先给摘要。\n- 评论分析可提炼痛点、购买动机、场景和改进建议，支持竞品对比及趋势分析。\n- 生成报告后附在线查看链接；已采集评论可导出 CSV，报告可导出 Markdown / HTML，受套餐权益限制。\n- 样本或时间跨度不足时会说明无法判断趋势，不把缺失数据补成结论。\n\n## 费用与数据范围\n\n采集和 AI 分析消耗积点。VOC 等支持免确认的流程命中账户规则时可能直接执行并扣点；\n其余情况先报价、等你同意。免确认不是免费，具体规则与余额可让 AI 查询。\n\n可以直接说“以后每次扣点前先问我”，或“只报价，不执行”。\n持续监控需要单独确认周期和后续采集成本。非美国站采集不能使用赠送积点。\n\n分析与导出基于 ARI 已采集的数据，不保证覆盖 Amazon 上全部评论或全部变体。\n免费读取已有评论、图表和历史报告不扣分析积点。\n执行中断时先查询已有任务或报告，避免重复生成和扣点。\n\n## 高级：手动安装、授权与命令\n\n找到解压后同时包含 SKILL.md 和 scripts/ari.py 的目录，以 SKILL.md 顶部的 name\n作为安装目录名。当前包的 name 是 amazon-voc，WorkBuddy 用户级目录为\n~/.workbuddy/skills/amazon-voc/。版本压缩包的外层目录名不是固定 Skill 名。\n更新已有同名安装时保留本地配置。\n\n在安装目录执行：\n\n~~~bash\npython scripts/ari.py setup\npython scripts/ari.py check\n~~~\n\n日常使用只需自然语言。完整命令、计费规则和故障处理见\n[使用说明](使用说明.md)；集成参数见 [API 参考](references/reference.md)。\n\n- [账号与授权管理](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [积点与套餐](https://ari.funewa.com/zh/billing)\n- [在线报告](https://ari.funewa.com/zh/reports)\n\n## 连接安全\n\nAPI 与授权入口固定为 https://ari.funewa.com，禁止重定向。生产包不支持自定义端点，ARI_ALLOW_CUSTOM_BASE 不再生效。遇到 ARI_ENDPOINT_BLOCKED 或 ARI_REDIRECT_BLOCKED 时停止操作，清除自定义地址或联系 ARI 支持，不能绕过校验。\n\nFile v0.1.4:_meta.json\n\n{\n \"ownerId\": \"kn7d4ekgxgbth42fthnftjf1tn89w6df\",\n \"slug\": \"amazon-variant-analysis\",\n \"version\": \"0.1.4\",\n \"publishedAt\": 1789378601752\n}\n\nFile v0.1.4:references/reference.md\n\n# ARI CLI 与 API 参考\n\n仅在需要命令参数、响应字段或错误处理时读取本文件。\n\nAPI 固定地址：`https://ari.funewa.com`，只允许 HTTPS 官方域名与默认端口 443。\n生产发行包不支持自建端点；`ARI_BASE_URL` 设置为其他地址时，在读取 Key 和联网前\n返回 `ARI_ENDPOINT_BLOCKED`。旧 `ARI_ALLOW_CUSTOM_BASE` 不再生效，`ARI_WEB_URL`\n不再改变网页链接。JSON、SSE、下载和设备授权均禁止重定向，返回 `ARI_REDIRECT_BLOCKED`。\n遇到这两类错误应停止操作并清除自定义地址或联系 ARI 支持，不能尝试关闭校验。\n开发测试使用 mock 传输和虚构凭据，不向其他端点发送生产 Key。\n域名严格匹配与系统默认 TLS 证书/主机名校验共同保护连接，不使用 DNS 预查代替 TLS 校验。\n认证头示意：`Authorization: Bearer `，占位符不是可用凭据。统一 JSON 信封为\n`{success, code, message, data, error, meta}`；SSE 分析由 CLI 聚合为同类 JSON。\n\n`--compact` 输出单行 JSON，放在子命令前后都可以\n（`ari.py --compact check` 与 `ari.py check --compact` 等价）。\n\n## 版本与更新\n\nCLI 在 User-Agent 里带自身版本（`ARI-Review-Skill/`，与 `_meta.json` 一致）。\n服务端在每个 API Key 响应上回 `X-ARI-Skill-Latest` / `X-ARI-Skill-Update-Url`；\n本地版本更旧时，**任意命令**的输出都会多出一个顶层 `update` 字段：\n\n```json\n{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}\n```\n\n`check` 还会额外读取免认证的 `/api/v1/public/config`，把完整的\n`release: {latest, minSupported, url, notes}` 一并返回——Key 失效时也能拿到升级入口。\n\n升级一律由用户通过原安装渠道完成。**CLI 不会下载或执行任何远端代码**，\n也不要让 agent 代劳去取\"新版文件\"运行。\n\n## 用户入口\n\n- API Key：\n- 充值/套餐：\n- 产品管理：\n- 报告中心：\n\n## CLI 命令\n\n1.4.5 的 voc / analyze 可能根据账户免确认规则直接执行并扣点，不能将“不带 --confirm”\n一概解释为“只报价”。用户明确只询价时用免费的 quote；必要的采集费用用 collect\n不带 --confirm 查询。不要为这一次询价修改用户长期确认设置。\n\n\n| 命令 | API | 是否可能扣点 |\n|---|---|---|\n| `setup` | auth/device/start + poll（免认证），浏览器授权后自动保存 Key | 否 |\n| `configure` | 本地保存 Key | 否 |\n| `check` | user/me + credits/balance | 否 |\n| `products` | asins | 否 |\n| `schedule` | asins（`--set`: asins/{id}/schedule） | 否（设置免费；采集本身按页扣点） |\n| `competitors` | asins/{id}/competitors（GET/POST/DELETE） | 否（竞品加入后按周自动采集，那部分按页扣点） |\n| `radar` | asins/{id}/radar | 否（纯 SQL；套餐未开放时 403） |\n| `voc` | pricing + balance + collection/submit/status + analysis/voc + reports | 是；`--confirm` 或服务端免确认规则命中 |\n| `collect` | billing/pricing + credits/balance + collection/submit | 是；必须 `--confirm` |\n| `status` | collection/status/{taskId} | 否 |\n| `reviews` | reviews | 否 |\n| `charts` | charts/stars·trend·keywords·flow | 否 |\n| `quote` | analysis/quote | 否 |\n| `operations capabilities` | product-operations/capabilities | 否 |\n| `operations profile` | product-operations/profile | 否 |\n| `operations quote` | product-operations/quote | 否 |\n| `operations run` | product-operations/quote + run（SSE） | 是；必须 `--confirm` |\n| `operations status` | product-operations/runs/{requestId} | 否 |\n| `watch list` | product-operations/watches（GET） | 否 |\n| `watch create` | product-operations/watches（POST） | 否；受 watch 灰度与套餐额度限制 |\n| `watch pause` / `watch resume` | product-operations/watches/{id}（PUT） | 否；只改变监控状态 |\n| `watch delete` | product-operations/watches/{id}（DELETE） | 否；不删除商品资料、评论或历史报告 |\n| `watch digest` | product-operations/watch-digest（GET） | 否；确定性摘要，`creditsUsed: 0` |\n| `watch events` | product-operations/events（GET） | 否；读取确定性变化事件 |\n| `analyze` | analysis/voc·keywords·insight·trend·variant·compare | 是；`--confirm` 或服务端 autoConfirm 命中 |\n| `autoconfirm [N\\|off\\|default]` | user/autoconfirm（GET/PUT） | 否；设置免确认阈值（1.4.5） |\n| `deepdive` | products + charts + reviews + reports + VOC quote/analysis | 默认否；`--confirm` 才分析 |\n| `reports` / `report` | reports | 否 |\n| `alerts` | alerts（`--mark-read` 时 alerts/read） | 否 |\n| `benchmark` | benchmark | 否 |\n| `leaderboard` | billing/pricing + leaderboard | 是；必须 `--confirm`，类目无数据不收费 |\n| `workbench` | workbench/reviews（`--history`: advices；`--set-status`: 状态更新） | 否 |\n| `advise` | analysis/quote + workbench/advise（SSE） | 是；必须 `--confirm` |\n| `export` | export/reviews 或 export/reports/{id}，落盘本地文件 | 否（限付费套餐） |\n| `version` | 无网络请求 | 否 |\n\n运行 `python ari.py <命令> --help` 查看完整参数。\n\n## 持续监控（1.4.1 新增，ARI 的价值主线）\n\nARI 不是一次性查询工具：**开着定期采集，历史才会积累，趋势判断、差评归因和报告环比\n才有意义。** 报告出来后请检查该产品的采集计划，仍是 `manual` 时主动提示用户。\n\n- `schedule`：不带参数=列出全部产品的采集计划，附 `_monitorSummary`\n （monitored / manual / paused 计数）。\n- `schedule --set weekly --asin B0...`（或 `--id <产品id>`）：设为每周自动采集。\n 返回带 `_costNote`：每轮单价是固定的，月成本是按 4.3 周折算的估值——**先把成本告诉用户再执行**。\n `daily` 适合大促期/新品；`weekly` 是长期跟踪的默认；`manual` 只在手动触发时更新。\n- 套餐未开放每日采集时 `--set daily` 返回 403，改用 `weekly`（每周不受任何套餐限制）。\n- 竞品：`competitors --id <产品id> --add B0...` 绑定后按周自动采集；\n `--remove <竞品行id>` 解绑。**竞品只在其主品仍在监控时才会采集**——主品改成\n `manual` 会一并停掉竞品的采集（也就不再产生费用）。\n- `radar --id <产品id> [--weeks 12]`：本品 vs 竞品的周走势（均分 / 新评论量 / 差评量）。\n 免费。曲线随监控时间变长，攒满一个季度才看得出谁在往上走。\n\n## 商品变化监控（watch）\n\n`watch` 使用独立的确定性商品快照和 Diff 管理，不调用付费 LLM。`watch create` 只接受\n属于当前账户且已订阅的主 ASIN；可选 `--competitor` 仅在该竞品已绑定到该主 ASIN、且站点\n相同时创建竞品 watch。不得用临时 ASIN 或全局商品资料绕过归属。Wave E listing 仍为 planned。\n开始前运行：\n\n```bash\npython scripts/ari.py operations capabilities\npython scripts/ari.py watch list\n```\n\n只有返回 `watchEnabled: true` 且账户通过当前灰度/套餐检查时才可继续；否则停止，不要回退到\n`operations` 或用临时 ASIN 绕过权限。\n\n本节是 1.4.1 的 CLI 契约说明；对应 Wave E 候选仍为 `planned`，尚未公开上架，不代表所有账户当前可用。\n\n固定命令与参数：\n\n```bash\npython scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\npython scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\npython scripts/ari.py watch pause --watch-id \npython scripts/ari.py watch resume --watch-id \npython scripts/ari.py watch delete --watch-id \npython scripts/ari.py watch digest --watch-id --period 7d\npython scripts/ari.py watch events --watch-id \n```\n\n`create`/`resume` 的周期只支持 `weekly|daily`；`daily` 由套餐 `dailyProductWatch` 控制，\nFree 不开放自动日扫描。`digest` 只聚合快照、确定性 Diff 和已有评论计数，返回\n`creditsUsed: 0`；自动扫描不调用付费 LLM、不扣 AI 积点。`period` 只支持服务端白名单中的\n`7d|30d`。watch 不承诺小时级或实时价格、销量、库存、广告、订单或真实退货率。\n\nAI 周报是另一条 `weekly` 付费 workflow：必须先 `operations quote`，再由用户明确确认后使用\n同一 `requestId` 执行 `operations run --confirm`。不要把 `watch digest` 当作 AI 周报或反向触发\n付费调用。\n\n## 报告环比\n\n`report --id N` 的返回里：\n\n- `deltaMd`：相比上一份同类型报告的差异摘要（已解决 / 新出现 / 持续存在 / 一句话结论）。\n- `prevReportId` / `prevCreatedAt` / `prevHealthScore`：被对比的那一份。\n- `series`：该序列最近若干份的健康度轨迹（画走势用）。\n- `_deltaStatus`：`ready` 有环比；`generating` 还在后台算（等十几秒重跑，**不是失败**）；\n `none` 这是第一份，没有可比对象。\n\n环比由服务端异步生成，平台承担成本，**不扣用户积点**；套餐权益 `reportDiff` 控制是否开启。\n有 `deltaMd` 时汇报要先讲环比再讲正文——用户最关心的是「跟上次比变了什么」。\n\n## 评论切片（免费）\n\n`reviews` 除了 `--star` / `--query` 还支持：\n\n- `--stars negative|positive`：差评（1-3★）/ 好评（4-5★）分组。\n- `--sort recent|helpful|star_asc|oldest`：`helpful` = 按点赞数排。\n **`--stars negative --sort helpful` 就是高赞差评榜**——买家在商品页最先看到的\n 就是这几条，对转化伤害最大，也是最该优先处理的。\n- `--with-images` / `--vine` / `--purchased`：只看带图 / Vine / 已验证购买。\n\n## 预警、对标与差评工作台\n\n- `alerts [--limit N]`：未读情感预警（差评突增、星级下滑）。`--mark-read` 全部置已读。\n- `benchmark --asin B0...`：免费类目对标概览（本品星级/差评率在类目内的相对位置）。\n- `leaderboard --category <类目> [--by new30|neg_rate|avg_star]`：付费类目排行。\n 无服务端报价握手，CLI 先读 `billing/pricing` 的 `leaderboard` 单价报出，确认后\n `--confirm` 执行；`ARI_INSUFFICIENT_REVIEWS`（类目无数据）不收费。\n- `workbench [--asin] [--site] [--status ...] [--sort severity|recent|arrived] [--new-only]`：\n 免费列差评（返回 `reviewId`）。**默认 `--sort severity`**（高赞与低星优先，\n 最伤转化的排前面）；`--new-only` 只看近 7 天新入库的差评。\n 返回的 `stats` 给出 `pending` / `newThisWeek` / `doneMonth` / `doneTotal`——\n 汇报时先说这几个数字，让用户看见自己在推进而不是面对一个没有尽头的列表。\n 条目上的 `isNew` / `hasImages` / `helpful` 用于判定优先级。\n `--history [--query]` 看 AI 建议存档；`--review-id N --set-status <状态>` 更新处理状态。\n- `advise --review-id N`：为单条差评生成回复/申诉/改进建议（SSE，`data.content` 为\n Markdown）。先按 `quote type=advise` 报价，确认后 `--confirm`。流中断处理同 VOC。\n- `export --asin B0...`（评论 CSV）或 `export --report-id N [--format md|html]`（报告）：\n 文件写到本地，返回 `savedTo/bytes`。Free 套餐会收到 403「导出为付费功能」。\n\n## 采集\n\nvoc B0... --site amz_us 是完整 VOC 的入口：先取得报价，已有足够评论时使用当前分析价格；\n数据不足时合并采集与分析费用。符合服务端免确认规则且总额不超过上限时可能直接生成，\n返回 autoConfirmed。否则返回 confirmationRequired，取得用户同意后追加 --confirm，\n自动完成必要采集、等待、分析和归档。只读询价应使用 quote / collect 报价入口。\n\n`collect --asin B0... --site amz_us --pages 3` 只返回报价；确认后追加\n`--confirm --wait`。请求字段：`asin, site, pageCount, filterByStar, sortBy, alias`。\n\n- `pages`: 1–10，每页约 10 条。\n- 报价字段：`credits`（本次费用）= `pricePerPage` × `pages`，固定单价不浮动；`approxReviews` 是估的条数。\n 商品评论不够这么多页时，服务端只按实际采到的页数结算、差额自动退回（`pricingNote` 直接转述给用户即可）。\n- `filterByStar`: `all_stars|critical|positive|one_star|two_star|three_star|four_star|five_star`。\n- `sortBy`: `recent|helpful`。\n- **US 以外站点只能使用付费积点**（订阅套餐周期积点与增量包均可），赠送积点\n （注册礼/任务奖励等）被排除。报价字段 `usableBalance` 已按站点算好，\n `sufficient=false` 时不要确认——服务端会直接 402（`ARI_GIFT_CREDITS_US_ONLY`\n 表示总余额够但可用部分是赠送积点）。报价还返回 `planCredits` / `addonCredits` /\n `siteNote` 供解释。\n- `--wait` 轮询 `collection/status`，任务状态只有 `queued|running|done|failed`。\n 瞬时错误会自动重试 3 次；仍失败或超时返回 `WAIT_TIMEOUT`，此时任务仍在后台，\n 用 `status --task ` 查询，**不要重新提交采集**。\n\n## 分析\n\n先调用 `quote --type ...`。报价字段：\n`type, basePrice, price, sampledReviews, totalReviews, balance, sufficient`，\n另有（1.4.5）：`autoConfirm`（true = 服务端首次体验策略允许免确认直接生成）、\n`autoConfirmMaxCredits`（免确认单次上限，采集 + 报告合计）、`autoConfirmRemaining`（还剩几次）、\n`autoConfirmNote`、`webUrl`（该产品的网页报告页）。`sampleCap` / `degraded` 表示 Free 样本封顶与轻量模型。\n`voc` / `analyze` 在 autoConfirm 命中时会直接生成，返回 `autoConfirmed: true` 与 `autoConfirmNote`，\n并附 `web.report` / `web.product` 网页链接。\n\n- `voc`: Markdown VOC 报告，SSE 聚合后在 `data.content`，并归档。\n- `keywords`（1.4.4）: PPC 关键词报告——从评论用词提炼核心搜索词、长尾/场景词、否定词、\n 竞品品牌词与一条 ≤250 字节的后台 Search Terms 字串；关键词保持站点语言。SSE，同 voc 分档计费，归档 `report_type=keywords`。\n- `insight`: 结构化消费者洞察，`data.result`，同时可能含流式说明 `content`。\n- `trend`: 情感趋势解读，普通 JSON。\n- `variant`: 颜色/尺寸等变体归因，普通 JSON；需足量变体评论。\n- `compare`: 目标与竞品对比，**双方在库内各需 ≥10 条评论**（订阅关系不作强制校验，\n 但 charts/reviews 等 0 积点端点仍要求订阅）。必须传 `--competitor`。\n\nSSE 聚合结果字段：`meta, content, result, reportId, creditsUsed`。\nVOC 服务端在归档后直接于 `done` 事件返回本次 `reportId`；CLI 据此生成\n`reportUrl`。兼容旧服务端时才回查报告列表，并标记 `reportIdSource: \"reports-lookup\"`。\n\nFree 套餐的 AI 分析被强制降级到轻量模型，且受全局限流保护——报告深度与付费档不同，\n必要时说明这一点。\n\n## 免费数据字段\n\n- `products`: `asins[], count, limit`；元素含 `asin, site, alias, collectionStatus,\n lastCollectedAt, reviewCount, variantCount`。**只包含主品**，作为竞品添加的 ASIN\n 不在其中（但它们的 charts/reviews 依然可读）。\n- `reviews`: `reviews[], total, page, pageSize`；每条含标题、正文、星级、日期、\n verifiedPurchase、helpfulCount、attributes。\n- `charts stars`: `stars[1★..5★], total, avgStar`。\n- `charts trend`: 按月评论数、平均星级、低星数。\n- `charts keywords`: `keywords[]`。\n- `charts flow`: 场景/问题等流向结构；为空时不要补造。\n- `charts` / `deepdive` 额外返回 `_window: {days, note}`，`days=0` 表示全部历史；\n 非 0 时所有图表只统计最近 N 天，解读必须带上该窗口。\n\n## 聚合命令的失败语义\n\n`charts` 和 `deepdive` 会并发调多个端点。任一子请求失败时，最外层就是\n`success:false`，并给出 `failedParts:[{part, code, message}]`（如 `charts.trend`、\n`analysis`），成功的部分仍保留在 `data` 里。只能使用成功的那部分，缺失的数据不得推断。\n\n`deepdive` 找不到主品订阅时不会直接报错：仍返回 charts/reviews/reports，\n并在 `productNote` 里说明；此时即使传了 `--confirm`，AI 分析也会降级为只报价、不扣点。\n\n## 错误处理\n\n| 状态/错误码 | 动作 |\n|---|---|\n| 401 / `ARI_UNAUTHENTICATED` | Key 无效或已撤销；去用户中心重建 |\n| 402 / `ARI_INSUFFICIENT_CREDITS` | 停止付费操作；展示已有结果并引导充值 |\n| 403 / `ARI_EMAIL_NOT_VERIFIED` | 去用户中心验证邮箱 |\n| 403 / `ARI_FORBIDDEN`（含配额字样） | 已达套餐可订阅 ASIN 上限；引导删除旧 ASIN 或升级套餐 |\n| 403 / `ARI_FORBIDDEN`（其他） | 该 ASIN 不在当前账户订阅内；或 API Key 无账户/支付/后台权限 |\n| 422 / `ARI_INSUFFICIENT_REVIEWS` | 先增加采集页数；不把小样本包装成确定结论 |\n| 202 / `ARI_COLLECTING` | 采集中且数据不足，**未扣点**；按提示秒数等待后重试 |\n| 429 / `ARI_RATE_LIMITED`（含「免费版 AI 分析」） | 套餐级限流；引导升级或稍后再试，不要连续重试 |\n| 429 / `ARI_RATE_LIMITED`（其他） | 降低并发后再试；不要并发轰炸 |\n| `ARI_STREAM_INTERRUPTED` | 分析流中断，**服务端可能已扣点并归档**；先 `reports --asin --limit 1` 核对，没生成才可重试 |\n| `NETWORK_ERROR` / `WAIT_TIMEOUT` | 同上：付费命令一律先核对再决定是否重跑 |\n| `ARI_PARTIAL_FAILURE` | 聚合命令部分失败；见 `failedParts`，只用成功的部分 |\n| `ARI_ENDPOINT_BLOCKED` | 非官方地址或非法 URL；停止操作，清除自定义地址，不能开启旧开关绕过 |\n| `ARI_REDIRECT_BLOCKED` | 官方请求返回重定向；停止操作并联系 ARI 支持，不跟随跳转、不自动重试付费请求 |\n| 426 / `ARI_SKILL_TOO_OLD` | 当前版本低于服务端最低支持版本，付费操作被禁止；引导用户更新，免费查询不受影响 |\n\nCLI 网络错误和 HTTP 错误均返回结构化 JSON，不应从报错文本臆测业务数据。\n\nFile v0.1.4:CHANGELOG.md\n\n# v1.4.10\r\n\r\n- 修复「声明范围小于实际能力」：44 个专属运营包改为窄版文档，只保留本包固定的\r\n workflow/focus 入口；29 个全功能包改为如实声明完整能力集。不再出现「窄声明配全功能正文」\r\n 或「只声明单点能力、正文却含全部能力」的自相矛盾。\r\n- 全部 73 个包补齐 `allowed-tools: Bash`：本系列只运行 `python scripts/ari.py`，\r\n 不写用户文件、不发任意网络请求、不修改商品页，明确最小工具权限。\r\n- 专属包的自然语言示例改为本场景专属文案，不再复用通用 VOC 提问。\r\n- 清理包内悬空引用：母版正文不再提及仅专属包才生成的约束文件，静态分析不再报\r\n 「引用了包内不存在的产物」。\r\n- 构建期新增三条硬闸：专属包不得出现母版全功能词汇、全功能包必须声明完整能力集、\r\n 文档提到的包内相对路径必须真实存在。命令、字段与计费规则一律不变，不提高最低支持版本。\r\n\r\n# v1.4.9\r\n\r\n- API 请求固定到官方 HTTPS 域名；移除自定义端点双变量绕过，读取 Key 前校验最终地址。\r\n- JSON、SSE、下载与设备授权统一拒绝重定向，安全错误在本地返回且不回显可疑 URL。\r\n- 网页入口固定为官方地址，设备授权链接必须通过域名校验；安全错误中止授权轮询。\r\n- 分发构建增加完整 ARI Key 检查，格式前缀与占位符允许保留，命中时只输出文件位置。\r\n- 新增离线安全回归测试；保留现有报价、扣点确认和报告恢复行为。\n- 通用入口文档不再引用仅专属包才生成的约束文件，避免指向包内不存在的产物。\r\n\r\n# v1.4.8\r\n\r\n- 采集报价改成固定单价口径：报价字段 `credits` = `pricePerPage` × `pages`，附 `pricingNote`；\r\n 不再用 `estimatedCredits` / `estimatedReviews` 这类「预计」措辞（对应字段改为 `credits` / `approxReviews`）。\r\n- `voc --confirm` 的合计字段 `estimatedTotalCredits` 改名 `totalCredits`；余额不足提示去掉「最多」。\r\n- `schedule` 的 `_costNote`：每轮单价写「=」不写「≈」，并说明只按实际采到的页数收费。\r\n- CLI 命令与计费规则不变，不提高最低支持版本。\r\n\r\n# v1.4.7\r\n\r\n- 新增 `topics` 命令：逐条评论话题标签的汇总与单话题详情（趋势 / 原句 / 本品 vs 竞品 / 标签洞察），免费。\r\n- `reviews` 新增 `--topic` 按话题筛，返回行带 `tags[]`（维度 / 话题 / 原句），引用原句不再靠模型复述。\r\n- 标准工作流第 12 条：用户问「抱怨最多的是什么 / 某问题最近变多了吗 / 竞品在这点上如何」先走 `topics`。\r\n- CLI 接口与计费规则延续 v1.4.6，不提高最低支持版本。\r\n\r\n# v1.4.6\r\n\r\n- 用一句自然语言发起评论简析、竞品比较、Listing 优化等任务，优先复用对话中的商品与目标。\r\n- 简短请求优先返回数据范围、问题与评论依据、趋势判断；不强制展示技术日志或完整报告。\r\n- 优先读取已有数据；不追问接口没有提供的变体范围选项，不将新入库的历史评论当成近期趋势。\r\n- 安装说明明确浏览器授权、目录识别、配置保留与连接检查；增加可复制的使用示例。\r\n- 写清账户免确认策略、只报价不执行及单独开启持续监控的边界。\r\n- 延续 v1.4.5 的 CLI 接口和计费规则，本次不提高最低支持版本。\n\nFile v0.1.4:skill-card.md\n\n## Description:\n\nAmazon VOC helps agents collect and analyze Amazon reviews through ARI, producing buyer feedback insights on pain points, purchase motives, personas, scenarios, trends, competitors, listing improvements, monitoring, alerts, and exports.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[funewa](https://clawhub.ai/user/funewa)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal marketplace operators and ecommerce teams use this skill to analyze Amazon ASIN reviews, compare competitors, monitor review changes, and turn buyer feedback into VOC reports and listing or product-improvement guidance.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Paid VOC or analysis flows can spend ARI credits under server-side auto-confirm rules without a fresh chat confirmation.\n\nMitigation: Before paid analysis, ask for quote-only mode or require confirmation before every credit-spending action.\n\nRisk: The skill requires an ARI API key and sends ASINs, review queries, account checks, and report requests to ari.funewa.com.\n\nMitigation: Install only if that data sharing is acceptable, and keep API keys out of chat messages, reports, and examples.\n\nRisk: Review reports depend on ARI-collected samples and may not cover every Amazon review or variant.\n\nMitigation: Check the reported sample range and time span, and treat small-sample trends as directional.\n\nRisk: Interrupted paid operations may already have consumed credits and produced a report.\n\nMitigation: Check existing reports or operation status before retrying a paid command.\n\n## Reference(s):\n\n- [Server-resolved GitHub source](https://github.com/funewa/Amazon-variant-analysis)\n- [ARI CLI and API Reference](references/reference.md)\n- [Amazon-VOC README](README.md)\n- [ARI Amazon Review Assistant User Guide](使用说明.md)\n- [ARI Account and Authorization](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [ARI Billing](https://ari.funewa.com/zh/billing)\n- [ARI Reports](https://ari.funewa.com/zh/reports)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown reports, concise text summaries, JSON/CSV/HTML exports, and shell command or configuration guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include ARI web report links; paid analysis or collection can consume ARI credits.]\n\n## Skill Version(s):\n\n0.1.4 (source: ClawHub release metadata); artifact package declares 1.4.10 (source: SKILL.md frontmatter and _meta.json)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.4:使用说明.md\n\n# ARI Amazon 评论智能助手使用指南\n\n**一句话分析亚马逊评论，找出买家不满、购买动机和产品改进机会。**\n\n安装并完成浏览器授权后，在支持 Skill 的 AI 客户端里直接说需求即可。通常只需商品 ASIN、\n站点和你想知道的问题；ASIN 是商品链接中 /dp/ 后面的 10 位字母数字编码。\n无需填写接口参数，也不用自己执行采集和分析命令。\n\n## 一、复制一句话，换成自己的商品\n\n下列 ASIN 都是占位符，发送前请替换。未说明站点且没有其他上下文时按美国站处理。\n\n| 你想做什么 | 可以直接发给 AI 的话 |\n|---|---|\n| 简单了解问题 | 分析美国站 B0XXXXXXXX 的评论，简要说说 3 个主要问题和近期趋势。 |\n| 找出差评原因 | 看看美国站 B0XXXXXXXX 的低星评论，哪些问题被反复提到？附几条评论依据。 |\n| 比较竞品 | 对比美国站 B0AAAAAAAA 和 B0BBBBBBBB 的评论，找出竞品短板和改进机会。 |\n| 改进文案 | 根据美国站 B0XXXXXXXX 的评论，帮我优化五点描述，并说明依据。 |\n| 查看已有预警 | 看看我有哪些未读差评预警，先列出最需要处理的几条。 |\n| 准备持续监控 | 我想每周跟踪美国站 B0XXXXXXXX 的新评论，先告诉我费用和当前限制。 |\n| 导出数据 | 导出美国站 B0XXXXXXXX 已采集的评论为 CSV。 |\n\n如果客户端没有选中 ARI，在问题前加“使用 $amazon-voc”；\n安装的是专用 Skill 时，用它实际显示的名称。专用 Skill 聚焦各自场景，无需手填内部工作流。\n\n### 提问后会发生什么\n\nAI 会识别商品和需求，检查已有数据，再按所选分析流程处理。生成 VOC 报告时，\n必要的采集、等待和归档可自动衔接；其他专用工具如果缺少资料，会说明需要补什么。\n需要确认费用时，你只需回复同意或取消。已有扣点授权或命中账户免确认规则时，可能直接执行。\n\n简析会先给出主要问题、评论依据和趋势判断；完整报告还会包含相应的洞察与建议，\n生成后附在线报告链接。用户要求“简短”时不会强制输出长报告或命令清单。\n\n例如，“3 个主要问题和近期趋势”的结果会按以下形式呈现（格式说明，非真实分析）：\n\n- 数据范围：已采集样本数量、评论日期范围、最后采集时间。\n- 主要问题：问题主题、样本中出现情况、代表性评论依据。\n- 趋势判断：同口径时间段内的变化；样本或时间跨度不足时明确说明无法判断。\n- 下一步：有证据支持的改进建议；生成完整报告时附在线链接及本次用量。\n\n结果基于 ARI 已采集的评论，不保证覆盖 Amazon 上全部评论。\n变体分析不等于已采集全部变体；如果数据不能区分具体变体，结果会说明范围限制。\n\n## 二、第一次使用：安装并在浏览器授权\n\n1. 在 [ARI 用户中心](https://ari.funewa.com/zh/account) 复制“安装与授权指令”，\n 发到支持 Skill 的 AI 客户端对话框。市场安装用户可直接安装对应 Skill。\n2. 对已安装的 Skill 说：“帮我完成 ARI 授权并检查是否可用。”\n3. 打开 AI 返回的授权链接，自己登录或注册、完成邮箱验证，并点击授权。\n4. AI 确认连接、余额和扣点规则后，就可以发送上面的提问。首次授权通常只需做一次。\n\n授权会在本机保存专用 API Key，无需把密钥粘贴到聊天中。安装检查不会自动采集、\n生成付费报告或开启监控。客户端如果尚未发现 Skill，按该客户端的提示重新加载。\n\n### 怎么收费，能否每次先问我\n\n- 采集和 AI 分析消耗积点，费用由本次报价和账户权益决定；免确认不等于免费。\n- VOC 等支持免确认的流程，命中账户当前规则时可能直接执行并报告扣点；\n 其余情况先报费用，等你同意。专用运营报告仍按自己的报价确认规则执行。\n- 想每次确认，可以说：“以后每次扣点前先问我。”想设置额度，可以说：\n “以后单次不超过 50 积点的分析直接做，超过先问我。”AI 会设置并复述适用规则。\n- 只想询价时说“只报价，不要执行”；想恢复账户默认规则时说“恢复默认扣点确认规则”。\n- 持续监控会产生后续采集费用，需要单独说明周期和成本并取得同意。\n- 读取已采集评论、免费图表和历史报告不扣 ARI 分析积点；导出受套餐权益限制。\n\n非美国站采集不能使用赠送积点，具体以该站点可用余额为准。已有历史评论并不意味着\n接下来会自动更新，是否持续更新取决于采集和监控设置。\n\n## 三、高级用法：手动授权与命令行\n\n下面供需要手动安装、排障或集成的用户参考；日常使用直接在对话框提出需求即可。\n\n### 手动安装与授权\n\n解压官方安装包，找到同时包含 SKILL.md 和 scripts/ari.py 的目录，读取 SKILL.md\n顶部的 name；以该名称作为安装文件夹名，放入当前客户端的 skills 目录。\nzip 的版本目录名不是固定的 Skill 名。更新已有同名安装时保留本地配置。\n\n在安装后的 Skill 目录执行：\n\n~~~bash\npython scripts/ari.py setup\npython scripts/ari.py check\n~~~\n\nsetup 会打印授权链接，由你自己在浏览器登录并授权。授权链接不可用时，可从\n[用户中心](https://ari.funewa.com/zh/account?ui=d47626f#api-keys) 创建 Key，再运行\npython scripts/ari.py configure，通过本机终端的隐藏输入完成配置。不要把 Key 发到聊天中。\n\n### 1. 一键生成 VOC 报告（推荐）\n\n```bash\npython scripts/ari.py voc B0XXXXXXXX --site amz_us\n```\n\n该命令会先检查采集 + VOC 总费用；命中账户免确认规则时可能直接生成并扣点。\n仅当返回 confirmationRequired 时，取得用户同意后执行：\n\n```bash\npython scripts/ari.py voc B0XXXXXXXX --site amz_us --confirm\n```\n\n它会自动完成：检查现有评论 → 必要时采集并等待 → 生成 VOC →\n保存到用户中心 → 返回完整报告正文、`reportId` 和 `reportUrl`。\n默认采集 3 页，可用 `--pages 1..10` 调整。\n\n### 2. 单独采集或查看免费数据（高级）\n\n只需采集时：\n\n```bash\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3 --confirm --wait\n```\n\n查看免费数据：\n\n```bash\npython scripts/ari.py reviews --asin B0XXXXXXXX --site amz_us\npython scripts/ari.py charts --asin B0XXXXXXXX --site amz_us\n```\n\n`charts` 会一次返回星级、趋势、关键词和评论流向数据。默认 `--days 0`（全部历史）；\n传 `--days 90` 则所有图表都只统计最近 90 天，看数时请注意这个窗口。\n\n**高赞差评榜**（免费）——按点赞数量查看低星评论，帮助确定优先阅读的反馈：\n\n```bash\npython scripts/ari.py reviews --asin B0XXXXXXXX --stars negative --sort helpful\npython scripts/ari.py reviews --asin B0XXXXXXXX --stars negative --sort helpful --with-images\n```\n\n### 2.5 按需开启定期监控\n\n开启监控后按周期采集新评论，便于与历史数据比较；也可以按需手动更新。\n趋势判断仍取决于采集覆盖、样本量和时间跨度，不能仅凭运行时间长就认定更准确。\n\n```bash\npython scripts/ari.py schedule # 看看哪些产品还没在监控\npython scripts/ari.py schedule --set weekly --asin B0XXXXXXXX # 设为每周自动采集\npython scripts/ari.py schedule --set manual --asin B0XXXXXXXX # 随时改回手动，不再产生费用\n```\n\n设置本身免费，采集按实际采到的页数扣点（单价固定）。返回里的 `_costNote` 会给出该频率折算的月成本。\n`weekly` 是长期跟踪的默认选择；`daily` 适合大促期或刚上新的款（部分套餐不开放每日）。\n\n开着监控一段时间后，同一个产品再生成报告，`report --id` 会多出一段环比：\n「相比上一份：哪些问题解决了、哪些是新冒出来的、哪些还在恶化」。\n\n### 3. 其他分析类型（高级）\n\n```bash\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us\n```\n\n确认后生成分析：\n\n```bash\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us --confirm\n```\n\n支持的分析类型：\n\n- `voc`：消费者之声综合报告\n- `insight`：痛点、购买动机、画像和场景\n- `trend`：评论与情绪趋势\n- `variant`：颜色、尺寸等变体分析\n- `compare`：目标产品和竞品对比\n\n竞品对比同样是先报价、后确认。先看价：\n\n```bash\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us\n```\n\n确认价格后再加 `--confirm`：\n\n```bash\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us --confirm\n```\n\n两个 ASIN 都需要先完成评论采集，各自至少 10 条评论。\n\n### 4. 商品运营体检与行动报告\n\n先确认账户是否开放运营能力，再检查商品资料：\n\n```bash\npython scripts/ari.py operations capabilities\npython scripts/ari.py operations profile --asin B0XXXXXXXX --site amz_us\n```\n\n通用母版需显式选择服务端支持的 workflow/focus。先报价，不扣点：\n\n```bash\npython scripts/ari.py operations quote --workflow audit --focus full --asin B0XXXXXXXX --site amz_us\n```\n\n用户确认后，复用报价返回的 `requestId` 执行：\n\n```bash\npython scripts/ari.py operations run --workflow audit --focus full --asin B0XXXXXXXX --site amz_us --request-id <原requestId> --confirm\n```\n\n若流中断，不要直接重跑，按原 requestId 免费查询：\n\n```bash\npython scripts/ari.py operations status --request-id <原requestId>\n```\n\n专属运营 Skill 会在包根目录固定 workflow/focus，无需也不得自由改写内部 prompt；本包是通用入口，不受此限制。\n评论不足时仍使用独立的 `collect` 流程；运营命令不会隐式采集。\n\n### 5. 商品变化监控（watch）\n\n`watch` 是独立的确定性商品快照监控，不是付费 AI 分析。`watch create` 只接受账户已订阅\n且仍归属账户的主 ASIN；可选 `--competitor` 仅在该竞品已绑定到该主 ASIN、且站点相同时生效。\n先查看当前账户是否处于 watch 灰度：\n\n```bash\npython scripts/ari.py operations capabilities # 确认返回 watchEnabled: true\npython scripts/ari.py watch list\n```\n\n如果 `watchEnabled` 为 `false`，说明功能开关、套餐或灰度尚未开放；请停止，不要改用其他命令\n冒充监控，也不要用临时 ASIN 或未绑定竞品绕过归属校验。竞品 watch 必须带 `--competitor`，\n且该竞品已绑定到当前用户的主 ASIN、站点相同；Wave E 的 `competitor-change` listing 仍为 planned。\n\n本节记录 1.4.1 的 CLI 契约；对应 Wave E 候选仍为 `planned`，尚未公开上架，不代表所有账户当前可用。\n\n创建和管理监控：\n\n```bash\npython scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\npython scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\npython scripts/ari.py watch pause --watch-id \npython scripts/ari.py watch resume --watch-id \npython scripts/ari.py watch delete --watch-id \n```\n\n周期只支持 `weekly` 和 `daily`。`daily` 受套餐 `dailyProductWatch` 权益限制，Free 不开放\n自动日扫描；创建或修改前先向用户说明套餐额度和扫描成本。暂停后不再调度，删除监控关系不会\n删除商品资料、评论或历史报告。\n\n读取确定性摘要和事件：\n\n```bash\npython scripts/ari.py watch digest --watch-id --period 7d\npython scripts/ari.py watch events --watch-id \n```\n\n`digest` 只基于商品快照、确定性 Diff 和已有评论计数，返回 `creditsUsed: 0`；自动扫描和\n事件读取不调用付费 LLM、不扣 AI 积点。它不承诺小时级或实时价格、销量、库存、广告、订单或\n真实退货率。若需要 AI 解读，仍使用 `operations` 的 `weekly` 工作流，先运行 `operations quote`，\n得到用户明确确认后才用同一 `requestId` 执行 `operations run --confirm`，不要把 AI 周报当成\n免费的 watch digest。\n\n### 6. 差评预警与差评工作台\n\n订阅 ASIN 后服务端会自动监控差评突增、星级下滑，查看预警（免费）：\n\n```bash\npython scripts/ari.py alerts\n```\n\n列出待处理差评（免费，返回每条差评的 reviewId）：\n\n```bash\npython scripts/ari.py workbench --asin B0XXXXXXXX\n```\n\n为某条差评生成 AI 回复/申诉/改进建议（付费，先报价、确认后加 `--confirm`）：\n\n```bash\npython scripts/ari.py advise --review-id 12345 --confirm\n```\n\n### 7. 行业对标与类目排行\n\n免费查看本品在类目里的星级/差评率位置：\n\n```bash\npython scripts/ari.py benchmark --asin B0XXXXXXXX\n```\n\n类目排行为付费查询（先报价，确认后加 `--confirm`；类目无数据不收费）：\n\n```bash\npython scripts/ari.py leaderboard --category \"Kitchen\" --by neg_rate --confirm\n```\n\n**类目雷达**（免费）：把本品和竞品放在同一条时间轴上比走势。先绑定竞品，\n系统会按周自动采集它们的评论，攒几周后走势就出来了：\n\n```bash\npython scripts/ari.py schedule # 拿到本品的产品 id\npython scripts/ari.py competitors --id 123 --add B0COMPETITOR # 绑定竞品（按周自动采集）\npython scripts/ari.py radar --id 123 --weeks 12 # 看 12 周走势对比\n```\n\n竞品只在其主品仍在监控时才会采集——把主品改成 `manual`，竞品的采集和费用一起停。\n### 8. 导出评论与报告（付费套餐功能，不扣积点）\n\n```bash\npython scripts/ari.py export --asin B0XXXXXXXX\npython scripts/ari.py export --report-id 报告ID --format md\n```\n\n评论导出为 CSV，报告可导出 Markdown / HTML，文件保存在当前目录（可用 `--out` 指定路径）。\n\n### 9. 查看历史报告\n\n```bash\npython scripts/ari.py reports\npython scripts/ari.py report --id 报告ID\n```\n\n## 四、常用入口\n\n- 每份生成的报告都带 `reportUrl` 在线链接：登录后可看**图表版完整报告**并导出，\n 比终端里的纯文本丰富得多，推荐收藏。\n- [申请或撤销 API Key](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [充值与套餐](https://ari.funewa.com/zh/billing)\n- [产品管理](https://ari.funewa.com/zh/products)\n- [报告中心](https://ari.funewa.com/zh/reports)\n\n## 五、常见问题\n\n### 提示 API Key 无效\n\nKey 可能被撤销、复制不完整或属于其他账户。前往 ARI 用户中心重新创建，然后再次运行 `configure`。\n\n### 提示邮箱未验证\n\n先在 ARI 用户中心完成邮箱验证，再重新执行命令。\n\n### 提示积点不足\n\n已有的免费数据仍可查看，但不能继续付费采集或分析。前往“充值与套餐”补充积点。\n\n### 余额明明够，采集非美国站却说积点不足\n\n赠送的积点（注册礼、任务奖励、Free 版每月自动发放的那部分）**只能用于美国站**。\n采集 `amz_uk`、`amz_de`、`amz_jp` 等站点需使用付费积点——订阅套餐的周期积点和\n增量包都算。报价里的 `usableBalance` 就是该站点实际可用的数量，`sufficient` 为\n`false` 时请先订阅套餐或购买增量包。\n\n### 提示有新版本 / 提示版本过旧\n\n运行任意命令时，如果输出里出现 `update` 字段，说明服务端有更新的 Skill 版本。\n按提示里的链接，通过你当初安装本 Skill 的渠道更新即可。查看当前版本：\n\n```bash\npython scripts/ari.py check\n```\n\n返回的 `skillVersion` 是本地版本，`release.latest` 是服务端最新版。\n\n如果提示 `ARI_SKILL_TOO_OLD`，说明你的版本存在会导致**重复扣点**的问题，\n服务端已禁止它执行采集和 AI 分析（免费的查询不受影响）。请务必更新后再继续付费操作。\n\n> 出于安全考虑，本 CLI 不会自行下载或运行任何远端文件，更新必须由你手动完成。\n\n### 分析到一半提示“分析流中断”\n\n说明连接断开了，但服务端很可能已经生成完并扣了点。**不要直接重跑**，先查一下：\n\n```bash\npython scripts/ari.py reports --asin B0XXXXXXXX --limit 1\n```\n\n如果最新报告已经出现，直接用 `report --id` 读取即可；确认没有生成，再重新执行分析。\n\n### 为什么命令没有直接执行采集或分析\n\n是否需要确认取决于命令及账户规则。VOC 和部分分析命令可能按免确认规则直接执行；\n返回 confirmationRequired 时才需要用户确认。只需免费询价可使用 quote；单独 collect\n不带确认参数时返回采集报价。旧版本可能只支持逐次确认，通过原安装渠道更新后再检查规则。\n\n### 如何查看某个命令的全部参数\n\n```bash\npython scripts/ari.py --help\npython scripts/ari.py collect --help\npython scripts/ari.py analyze --help\n```\n\n默认站点为美国站 `amz_us`，还支持 `amz_uk`、`amz_de`、`amz_jp`、`amz_ca`、`amz_fr`、`amz_es` 和 `amz_it`。\n\nFile v0.1.4:agents/openai.yaml\n\ninterface:\n display_name: \"Amazon-VOC\"\n short_description: \"亚马逊买家之声：评论采集 + VOC 洞察报告\"\n default_prompt: \"使用 $amazon-voc 为一个 Amazon ASIN 一键生成 VOC 报告。\"\n\nArchive v0.1.3: 11 files, 35775 bytes\n\nFiles: _meta.json (142b), agents (0b), agents/openai.yaml (286b), README.md (5348b), references (0b), references/reference.md (9530b), scripts (0b), scripts/ari.py (58007b), skill-card.md (2700b), SKILL.md (7234b), 使用说明.md (8725b)\n\nFile v0.1.3:SKILL.md\n\n---\r\nname: amazon-variant-analysis\r\ndisplay_name: 亚马逊变体分析 · 颜色尺寸口碑对比\r\ndescription: >\r\n 亚马逊变体分析 Skill：对比同一父体下不同颜色、尺寸、规格的口碑差异，\r\n 找出拖累整体评分的问题变体与真正跑量的优势变体，\r\n 为砍变体、调库存、换主推提供依据。Use when the user asks about variant comparison,\r\n size or color issues, parent-child ASIN analysis, 变体分析、颜色尺寸对比、\r\n 子体表现、变体口碑、SKU 对比、问题变体。Requires an ARI API key (ari_live_*).\r\nauthor: ARI (funewa)\r\nversion: \"1.3.0\"\r\nagent_created: true\r\n---\r\n\r\n# 亚马逊变体分析\r\n\r\n## 工具与入口\r\n\r\n- CLI：本 Skill 目录下的 `scripts/ari.py`。在 Skill 根目录执行，例如\r\n `python scripts/ari.py check`；每次会话先跑一次 `check`。\r\n- API 参考：需要字段、命令或错误码时读取 `references/reference.md`。\r\n- API Key：首次使用运行 `python scripts/ari.py setup`——它会给出一个授权链接，\r\n 用户在浏览器登录（或注册）后点一下「授权」，Key 自动获取并保存到本机，无需复制粘贴。\r\n 也可用环境变量 `ARI_API_KEY`，或 `python scripts/ari.py configure` 手动粘贴。\r\n `setup` 期间把命令打印的授权链接原样转告用户，等待命令自行完成；**不要**替用户注册或登录。\r\n- 申请 Key（手动方式）：\r\n- 充值/套餐：\r\n- Web 产品管理：\r\n\r\n## 安全与计费协议\r\n\r\n- 缺少 Key 时立即停止，给出申请链接；不要索要用户密码，不要把 Key 写入报告或命令示例。\r\n- `401 / ARI_UNAUTHENTICATED`：停止并引导重建 Key。\r\n- `402 / ARI_INSUFFICIENT_CREDITS`：保留已有结果，引导充值；不得自动重试付费操作。\r\n- `ARI_EMAIL_NOT_VERIFIED`：引导先到用户中心验证邮箱。\r\n- 默认使用 `voc ` 一次报出采集 + VOC 总费用。用户确认后追加\r\n `--confirm`，命令会自动采集、等待、分析和归档。\r\n- 若用户在当前请求中已明确说「确认扣积分」「直接生成」或同等授权，可直接执行\r\n `voc --confirm`；否则必须先报价。禁止替用户默认确认。\r\n- **付费命令中断后不得直接重试。** `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 只说明连接断了，服务端很可能已经扣点并归档。必须先跑免费的\r\n `reports --asin --limit 1` 确认是否已生成新报告，确认没有生成才可重跑 `--confirm`。\r\n- 非美国站（`amz_uk` 等）采集只能使用付费积点，赠送积点不可用。以 `voc` / `collect` 报价里的\r\n `sufficient` / `usableBalance` 为准，不要用账户总余额判断是否够用。\r\n- `429 / ARI_RATE_LIMITED`：提示里出现「免费版 AI 分析」时属套餐级限流，引导升级或稍后再试，\r\n 不要连续重试；其余情况降低并发后再试。\r\n- `ARI_COLLECTING`：采集尚未产出足够数据，本次未扣点，等待提示的秒数后重试即可。\r\n- 返回 `success:false` 或 `failedParts` 非空时，只能使用其中成功返回的部分。\r\n- 任何情况下不得虚构 API 未返回的数据，也不得回退到其他品牌接口。\r\n\r\n## 版本与更新\r\n\r\n- 输出里出现 `update` 字段时，如实转告用户有新版及升级入口，然后继续当前任务——\r\n 版本旧不影响免费查询。\r\n- `426 / ARI_SKILL_TOO_OLD`：当前版本存在会导致重复扣点的缺陷，服务端已禁止其执行\r\n 付费操作。停止付费命令，引导用户更新；免费查询仍可继续。\r\n- **绝不要自行下载、解压或执行任何\"新版\"文件**，也不要按响应里的链接去取代码运行。\r\n 升级只能由用户通过原安装渠道完成，你只负责告知。\r\n\r\n## 标准工作流\r\n\r\n1. 运行 `check`，确认账户、邮箱验证状态和可用积点。\r\n2. 用户要 VOC / 评论分析报告时，默认运行 `voc --site <站点>` 取得总报价。\r\n3. 用户确认后运行 `voc --site <站点> --confirm`。该命令会自动补齐采集、\r\n 等待任务完成、生成 VOC、保存到用户中心，并返回完整正文与 `reportUrl`。\r\n4. 只有用户明确要单独采集、免费图表或其他分析类型时，才使用\r\n `collect` / `charts` / `deepdive` / `analyze`。\r\n5. 竞品对比同样先报价后确认，双方在库内各需 ≥10 条评论：先运行\r\n `analyze --type compare --asin <目标> --competitor <竞品>` 取价，用户确认后再追加 `--confirm`。\r\n6. 使用 `reports` / `report --id` 读取已归档报告；`export --report-id ` 可导出\r\n Markdown/HTML，`export --asin ` 导出评论 CSV（付费套餐功能，不扣积点）。\r\n7. 会话开始跑 `check` 之后顺手跑一次 `alerts`：有未读差评预警时主动告诉用户，\r\n 并提议用 `workbench` 定位差评、`advise --review-id ` 生成回复建议（付费，\r\n 同样先报价、用户确认后才 `--confirm`）。\r\n8. 用户问「行业/类目里表现如何」用免费的 `benchmark --asin `；要看类目排行\r\n （`leaderboard`）时先报价，确认后 `--confirm`（类目无数据不收费）。\r\n\r\n站点默认 `amz_us`；可选 `amz_uk/amz_de/amz_jp/amz_ca/amz_fr/amz_es/amz_it`。\r\n`charts` / `deepdive` 的 `--days` 默认 0（全部历史）；传非 0 时图表只覆盖该窗口，\r\n解读占比和趋势必须带上这个窗口说明。\r\n\r\n## 解读纪律\r\n\r\n- 把 API 数字、由数字推导的判断、行动建议明确区分：`📊 数据直读`、`🔍 数据推理`、\r\n `💡 策略建议`。策略建议不得标为数据直读。\r\n- `reviewCount < 50` 时在报告顶部标注小样本提示；单次提及只能作为方向性线索。\r\n- 痛点优先级同时考虑提及频率、低星程度、近期趋势和已验证购买，不凭单条评论下结论。\r\n- 用好评高频表达提炼 Listing 语言，但引用评论原话时保持短句并注明来自评论样本。\r\n- 竞品对比只比较双方 API 均有数据的指标；一方样本不足时明确写“不可比”。\r\n- 报告语言跟随用户；ASIN、VOC、Listing 等术语保留原文。非中文回复时记得传\r\n `--language en` 等，CLI 默认是 `zh`。\r\n\r\n## 报告结构\r\n\r\n按有数据的部分输出：数据概览 → 痛点与低星原因 → 好评与购买动因 → 用户画像与场景 →\r\n趋势 → 竞品差异 → Listing 建议 → 产品改进优先级 → 数据来源与积点用量。\r\n\r\n报告顶部加入：\r\n\r\n> 数据基于 ARI 已采集的 Amazon 评论样本（截至当前查询时间），仅供经营决策参考；\r\n> 小样本或采集窗口有限时应结合更多信源验证。\r\n\r\n结尾列出使用的 CLI 命令、ASIN/站点、样本量、统计窗口（`_window.days`）、报告返回的\r\n`reportId` 与 `creditsUsed`，以及当前余额。**输出含 `reportUrl` 时必须在结尾附上**，\r\n固定文案：「在线查看图表版完整报告 / 导出：」（需登录报告所属账户）。\n\nFile v0.1.3:README.md\n\n# 亚马逊变体分析 · 颜色尺寸口碑对比\r\n\r\n颜色尺寸规格口碑对比，揪出拖分变体\r\n\r\n> **亚马逊变体分析 · 颜色尺寸口碑对比**\r\n> 技术名 `amazon-variant-analysis`，ARI 官方出品的 Amazon 评论采集与消费者洞察 Skill，已适配 WorkBuddy。\r\n> 安装后直接用中文描述需求即可，无需理解 API 或编写代码；所有付费操作都会先报价，\r\n> 只有你明确确认后才会扣除积点。\r\n\r\n## 能做什么\r\n\r\n- 订阅 ASIN、采集评论，查看星级 / 关键词 / 趋势 / 流向等免费图表数据。\r\n- 生成 **VOC**、**深度洞察**、**趋势**、**变体**、**竞品对比** 五类 AI 分析报告。\r\n- 输出痛点、购买动因、用户画像、使用场景、改进机会与 Listing 建议。\r\n- **差评预警**（差评突增自动提醒）与**差评工作台**（AI 生成回复/申诉建议）。\r\n- **行业对标**（类目星级/差评率位置）与付费**类目排行**。\r\n- 评论一键导出 **CSV**，报告导出 **Markdown / HTML**（付费套餐功能）。\r\n\r\n安装后直接以自然语言提需求：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 为 ASIN B0XXXXXXXX 生成 VOC 报告，站点 amz_us，我确认扣积分。\r\n```\r\n\r\n## 前置条件\r\n\r\n- **Python 3**（只用标准库，无第三方依赖）。\r\n- 一个 **ARI API Key**（`ari_live_` 开头）。首次使用运行\r\n `python scripts/ari.py setup`，在浏览器登录或注册后点一下「授权」，\r\n Key 会自动写入本机，无需手工复制粘贴。\r\n 也可在 手动创建。\r\n\r\n## 安装到 WorkBuddy\r\n\r\n保持文件夹名 `amazon-variant-analysis`，整个放进对应作用域即可：\r\n\r\n| 作用域 | 路径 |\r\n|---|---|\r\n| 用户级（推荐） | `~/.workbuddy/skills/amazon-variant-analysis/` |\r\n| 项目级 | `<项目目录>/.workbuddy/skills/amazon-variant-analysis/` |\r\n\r\n装好后验证账户与积点余额：\r\n\r\n```bash\r\npython /scripts/ari.py check\r\n```\r\n\r\n> `` 是 WorkBuddy 加载 Skill 时自动替换的目录占位符；直接在终端跑时，\r\n> 请先进入 Skill 目录，或把它换成实际路径。\r\n\r\nKey 运行时从 `ARI_API_KEY` 或 `~/.ari/config.json` 读取——**切勿**提交进仓库，\r\n也不要把 Key 贴进公开文档或发给他人。\r\n\r\n## 命令一览\r\n\r\n| Command | 作用 | 扣积点 |\r\n|---|---|---|\r\n| `setup` / `configure` | 部署 API Key | 否 |\r\n| `check` | 账户与余额 | 否 |\r\n| `products` | 已订阅 ASIN 列表 | 否 |\r\n| `voc` | 自动采集 + VOC + 归档 + 报告链接 | **是，需 `--confirm`** |\r\n| `collect` | 提交采集任务 | **是，需 `--confirm`** |\r\n| `status` | 采集任务进度 | 否 |\r\n| `reviews` | 读取已采集评论 | 否 |\r\n| `charts` | 星级 / 趋势 / 关键词 / 流向 | 否 |\r\n| `quote` | 分析报价 | 否 |\r\n| `analyze` | voc / insight / trend / variant / compare | **是，需 `--confirm`** |\r\n| `deepdive` | 产品 + 图表 + 评论 + 报告 + VOC 报价 | 默认否，`--confirm` 才分析 |\r\n| `reports` / `report` | 历史报告列表 / 详情 | 否 |\r\n| `alerts` | 差评/星级预警 | 否 |\r\n| `benchmark` | 类目对标概览 | 否 |\r\n| `leaderboard` | 类目排行 | **是，需 `--confirm`** |\r\n| `workbench` | 差评列表 / 建议存档 / 状态流转 | 否 |\r\n| `advise` | 单条差评 AI 回复建议 | **是，需 `--confirm`** |\r\n| `export` | 评论 CSV / 报告 MD·HTML 导出 | 否（限付费套餐） |\r\n\r\n`python scripts/ari.py --help` 看完整参数。默认站点 `amz_us`，\r\n另支持 `amz_uk / amz_de / amz_jp / amz_ca / amz_fr / amz_es / amz_it`。\r\n\r\n## 扣费保护\r\n\r\n采集与 AI 分析消耗积点。付费命令（`voc`、`collect`、`analyze`、付费 `deepdive`）**必须**\r\n显式追加 `--confirm` 才真正执行，不带时只返回报价。\r\n\r\n- **非美国站只能用付费积点。** 采集 `amz_uk` / `amz_de` 等站点时赠送积点不可用，\r\n 以 `collect` 报价里的 `usableBalance` / `sufficient` 为准，别看账户总余额。\r\n- **付费命令中断后不要直接重跑。** 出现 `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 时服务端可能已扣点并归档，先用免费的\r\n `reports --asin --limit 1` 核对，确认没生成再重试。\r\n- **聚合命令部分失败体现在最外层。** `charts` / `deepdive` 任一子请求失败时返回\r\n `success:false` 并附 `failedParts`，成功的部分仍在 `data` 里，只能用这部分。\r\n\r\n## 目录结构\r\n\r\n```\r\nSKILL.md # Skill 清单 + 操作指令（WorkBuddy 规范）\r\nREADME.md # 本文件\r\n使用说明.md # 中文终端用户指南\r\nscripts/ari.py # 仅依赖标准库的 CLI\r\nreferences/reference.md# CLI 与 API 参考（命令 / 字段 / 错误码）\r\nagents/openai.yaml # 其他客户端的接口元数据（WorkBuddy 不使用，保留以兼容多端）\r\n```\r\n\r\n## 常用入口\r\n\r\n- API Key：\r\n- 充值套餐：\r\n- 产品管理：\r\n- 报告中心：\r\n- 新用户注册即赠积点，免费额度可通过任务中心持续解锁：\r\n \n\nFile v0.1.3:_meta.json\n\n{\n \"ownerId\": \"kn7d4ekgxgbth42fthnftjf1tn89w6df\",\n \"slug\": \"amazon-variant-analysis\",\n \"version\": \"0.1.3\",\n \"publishedAt\": 1789349672444\n}\n\nFile v0.1.3:references/reference.md\n\n# ARI CLI 与 API 参考\r\n\r\n仅在需要命令参数、响应字段或错误处理时读取本文件。\r\n\r\nAPI 默认地址：`https://ari.funewa.com`（开发环境可用 `ARI_BASE_URL` 覆盖）。\r\n认证头：`Authorization: Bearer ari_live_...`。统一 JSON 信封为\r\n`{success, code, message, data, error, meta}`；SSE 分析由 CLI 聚合为同类 JSON。\r\n\r\n`--compact` 输出单行 JSON，放在子命令前后都可以\r\n（`ari.py --compact check` 与 `ari.py check --compact` 等价）。\r\n\r\n## 版本与更新\r\n\r\nCLI 在 User-Agent 里带自身版本（`ARI-Review-Skill/`，与 `_meta.json` 一致）。\r\n服务端在每个 API Key 响应上回 `X-ARI-Skill-Latest` / `X-ARI-Skill-Update-Url`；\r\n本地版本更旧时，**任意命令**的输出都会多出一个顶层 `update` 字段：\r\n\r\n```json\r\n{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}\r\n```\r\n\r\n`check` 还会额外读取免认证的 `/api/v1/public/config`，把完整的\r\n`release: {latest, minSupported, url, notes}` 一并返回——Key 失效时也能拿到升级入口。\r\n\r\n升级一律由用户通过原安装渠道完成。**CLI 不会下载或执行任何远端代码**，\r\n也不要让 agent 代劳去取\"新版文件\"运行。\r\n\r\n## 用户入口\r\n\r\n- API Key：\r\n- 充值/套餐：\r\n- 产品管理：\r\n- 报告中心：\r\n\r\n## CLI 命令\r\n\r\n| 命令 | API | 是否可能扣点 |\r\n|---|---|---|\r\n| `setup` | auth/device/start + poll（免认证），浏览器授权后自动保存 Key | 否 |\r\n| `configure` | 本地保存 Key | 否 |\r\n| `check` | user/me + credits/balance | 否 |\r\n| `products` | asins | 否 |\r\n| `voc` | pricing + balance + collection/submit/status + analysis/voc + reports | 是；必须 `--confirm` |\r\n| `collect` | billing/pricing + credits/balance + collection/submit | 是；必须 `--confirm` |\r\n| `status` | collection/status/{taskId} | 否 |\r\n| `reviews` | reviews | 否 |\r\n| `charts` | charts/stars·trend·keywords·flow | 否 |\r\n| `quote` | analysis/quote | 否 |\r\n| `analyze` | analysis/voc·insight·trend·variant·compare | 是；必须 `--confirm` |\r\n| `deepdive` | products + charts + reviews + reports + VOC quote/analysis | 默认否；`--confirm` 才分析 |\r\n| `reports` / `report` | reports | 否 |\r\n| `alerts` | alerts（`--mark-read` 时 alerts/read） | 否 |\r\n| `benchmark` | benchmark | 否 |\r\n| `leaderboard` | billing/pricing + leaderboard | 是；必须 `--confirm`，类目无数据不收费 |\r\n| `workbench` | workbench/reviews（`--history`: advices；`--set-status`: 状态更新） | 否 |\r\n| `advise` | analysis/quote + workbench/advise（SSE） | 是；必须 `--confirm` |\r\n| `export` | export/reviews 或 export/reports/{id}，落盘本地文件 | 否（限付费套餐） |\r\n| `version` | 无网络请求 | 否 |\r\n\r\n运行 `python ari.py <命令> --help` 查看完整参数。\r\n\r\n## 预警、对标与差评工作台\r\n\r\n- `alerts [--limit N]`：未读情感预警（差评突增、星级下滑）。`--mark-read` 全部置已读。\r\n- `benchmark --asin B0...`：免费类目对标概览（本品星级/差评率在类目内的相对位置）。\r\n- `leaderboard --category <类目> [--by new30|neg_rate|avg_star]`：付费类目排行。\r\n 无服务端报价握手，CLI 先读 `billing/pricing` 的 `leaderboard` 单价报出，确认后\r\n `--confirm` 执行；`ARI_INSUFFICIENT_REVIEWS`（类目无数据）不收费。\r\n- `workbench [--asin] [--site] [--status pending|contacted|appealed|improving|archived]`：\r\n 免费列差评（返回 `reviewId`）；`--history [--query]` 看 AI 建议存档；\r\n `--review-id N --set-status <状态>` 更新处理状态。\r\n- `advise --review-id N`：为单条差评生成回复/申诉/改进建议（SSE，`data.content` 为\r\n Markdown）。先按 `quote type=advise` 报价，确认后 `--confirm`。流中断处理同 VOC。\r\n- `export --asin B0...`（评论 CSV）或 `export --report-id N [--format md|html]`（报告）：\r\n 文件写到本地，返回 `savedTo/bytes`。Free 套餐会收到 403「导出为付费功能」。\r\n\r\n## 采集\r\n\r\n`voc B0... --site amz_us` 是默认的用户入口：已有 ≥10 条评论时直接报 VOC 价；\r\n数据不足时合并报出默认 3 页采集与 VOC 的最大总费用。追加 `--confirm`\r\n后自动采集、等待、分析、归档，最外层返回 `report.content / reportId / reportUrl`。\r\n\r\n`collect --asin B0... --site amz_us --pages 3` 只返回报价；确认后追加\r\n`--confirm --wait`。请求字段：`asin, site, pageCount, filterByStar, sortBy, alias`。\r\n\r\n- `pages`: 1–10，每页约 10 条。\r\n- `filterByStar`: `all_stars|critical|positive|one_star|two_star|three_star|four_star|five_star`。\r\n- `sortBy`: `recent|helpful`。\r\n- **US 以外站点只能使用付费（addon）积点**，赠送的 plan 积点被排除。报价字段\r\n `usableBalance` 已按站点算好，`sufficient=false` 时不要确认——服务端会直接 402。\r\n 报价还返回 `planCredits` / `addonCredits` / `siteNote` 供解释。\r\n- `--wait` 轮询 `collection/status`，任务状态只有 `queued|running|done|failed`。\r\n 瞬时错误会自动重试 3 次；仍失败或超时返回 `WAIT_TIMEOUT`，此时任务仍在后台，\r\n 用 `status --task ` 查询，**不要重新提交采集**。\r\n\r\n## 分析\r\n\r\n先调用 `quote --type ...`。报价字段：\r\n`type, basePrice, price, sampledReviews, totalReviews, balance, sufficient`。\r\n\r\n- `voc`: Markdown VOC 报告，SSE 聚合后在 `data.content`，并归档。\r\n- `insight`: 结构化消费者洞察，`data.result`，同时可能含流式说明 `content`。\r\n- `trend`: 情感趋势解读，普通 JSON。\r\n- `variant`: 颜色/尺寸等变体归因，普通 JSON；需足量变体评论。\r\n- `compare`: 目标与竞品对比，**双方在库内各需 ≥10 条评论**（订阅关系不作强制校验，\r\n 但 charts/reviews 等 0 积点端点仍要求订阅）。必须传 `--competitor`。\r\n\r\nSSE 聚合结果字段：`meta, content, result, reportId, creditsUsed`。\r\nVOC 服务端在归档后直接于 `done` 事件返回本次 `reportId`；CLI 据此生成\r\n`reportUrl`。兼容旧服务端时才回查报告列表，并标记 `reportIdSource: \"reports-lookup\"`。\r\n\r\nFree 套餐的 AI 分析被强制降级到轻量模型，且受全局限流保护——报告深度与付费档不同，\r\n必要时说明这一点。\r\n\r\n## 免费数据字段\r\n\r\n- `products`: `asins[], count, limit`；元素含 `asin, site, alias, collectionStatus,\r\n lastCollectedAt, reviewCount, variantCount`。**只包含主品**，作为竞品添加的 ASIN\r\n 不在其中（但它们的 charts/reviews 依然可读）。\r\n- `reviews`: `reviews[], total, page, pageSize`；每条含标题、正文、星级、日期、\r\n verifiedPurchase、helpfulCount、attributes。\r\n- `charts stars`: `stars[1★..5★], total, avgStar`。\r\n- `charts trend`: 按月评论数、平均星级、低星数。\r\n- `charts keywords`: `keywords[]`。\r\n- `charts flow`: 场景/问题等流向结构；为空时不要补造。\r\n- `charts` / `deepdive` 额外返回 `_window: {days, note}`，`days=0` 表示全部历史；\r\n 非 0 时所有图表只统计最近 N 天，解读必须带上该窗口。\r\n\r\n## 聚合命令的失败语义\r\n\r\n`charts` 和 `deepdive` 会并发调多个端点。任一子请求失败时，最外层就是\r\n`success:false`，并给出 `failedParts:[{part, code, message}]`（如 `charts.trend`、\r\n`analysis`），成功的部分仍保留在 `data` 里。只能使用成功的那部分，缺失的数据不得推断。\r\n\r\n`deepdive` 找不到主品订阅时不会直接报错：仍返回 charts/reviews/reports，\r\n并在 `productNote` 里说明；此时即使传了 `--confirm`，AI 分析也会降级为只报价、不扣点。\r\n\r\n## 错误处理\r\n\r\n| 状态/错误码 | 动作 |\r\n|---|---|\r\n| 401 / `ARI_UNAUTHENTICATED` | Key 无效或已撤销；去用户中心重建 |\r\n| 402 / `ARI_INSUFFICIENT_CREDITS` | 停止付费操作；展示已有结果并引导充值 |\r\n| 403 / `ARI_EMAIL_NOT_VERIFIED` | 去用户中心验证邮箱 |\r\n| 403 / `ARI_FORBIDDEN`（含配额字样） | 已达套餐可订阅 ASIN 上限；引导删除旧 ASIN 或升级套餐 |\r\n| 403 / `ARI_FORBIDDEN`（其他） | 该 ASIN 不在当前账户订阅内；或 API Key 无账户/支付/后台权限 |\r\n| 422 / `ARI_INSUFFICIENT_REVIEWS` | 先增加采集页数；不把小样本包装成确定结论 |\r\n| 202 / `ARI_COLLECTING` | 采集中且数据不足，**未扣点**；按提示秒数等待后重试 |\r\n| 429 / `ARI_RATE_LIMITED`（含「免费版 AI 分析」） | 套餐级限流；引导升级或稍后再试，不要连续重试 |\r\n| 429 / `ARI_RATE_LIMITED`（其他） | 降低并发后再试；不要并发轰炸 |\r\n| `ARI_STREAM_INTERRUPTED` | 分析流中断，**服务端可能已扣点并归档**；先 `reports --asin --limit 1` 核对，没生成才可重试 |\r\n| `NETWORK_ERROR` / `WAIT_TIMEOUT` | 同上：付费命令一律先核对再决定是否重跑 |\r\n| `ARI_PARTIAL_FAILURE` | 聚合命令部分失败；见 `failedParts`，只用成功的部分 |\r\n| 426 / `ARI_SKILL_TOO_OLD` | 当前版本低于服务端最低支持版本，付费操作被禁止；引导用户更新，免费查询不受影响 |\r\n\r\nCLI 网络错误和 HTTP 错误均返回结构化 JSON，不应从报错文本臆测业务数据。\n\nFile v0.1.3:skill-card.md\n\n## Description:\n\nHelps Amazon sellers compare review sentiment across color, size, and other variants to identify weak variants, strong performers, and listing or product improvement opportunities.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[funewa](https://clawhub.ai/user/funewa)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal Amazon sellers and operators use this skill to collect and analyze Amazon review data by ASIN, compare variants or competitors, monitor negative review alerts, and produce VOC, trend, insight, and listing-improvement reports.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill contacts ARI account, balance, alert, review, and analysis endpoints and may send the user's ARI API key to an environment-configured server.\n\nMitigation: Review before installing, run only in an environment you control, leave ARI_BASE_URL unset unless it points to a trusted endpoint, and use an API key appropriate for the account access involved.\n\nRisk: Paid or state-changing workflows can consume credits, update workbench status, or write export files to user-selected paths.\n\nMitigation: Require explicit user confirmation before --confirm actions, review quotes before paid commands, verify archived reports before retrying interrupted paid commands, and choose export --out paths carefully.\n\n## Reference(s):\n\n- [Server-resolved GitHub source](https://github.com/funewa/Amazon-variant-analysis)\n- [ClawHub skill page](https://clawhub.ai/funewa/skills/amazon-variant-analysis)\n- [ARI CLI and API Reference](references/reference.md)\n- [ARI user center](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [ARI billing](https://ari.funewa.com/zh/billing)\n- [ARI product management](https://ari.funewa.com/zh/products)\n- [ARI report center](https://ari.funewa.com/zh/reports)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown reports and structured JSON from ARI CLI responses, with optional CSV, Markdown, or HTML exports.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include ASIN, site, sample size, statistical window, reportId, reportUrl, creditsUsed, current balance, savedTo, and byte count fields when returned by ARI.]\n\n## Skill Version(s):\n\n0.1.3 (source: ClawHub release metadata; artifact frontmatter reports 1.3.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.3:使用说明.md\n\n# ARI Amazon 评论智能助手使用指南\r\n\r\nARI Amazon 评论智能助手可以帮助卖家采集和分析 Amazon 评论，快速发现消费者痛点、购买动机、使用场景、竞品差异与 Listing 优化机会。\r\n\r\n你可以直接用中文提出需求，不需要理解 API，也不需要编写代码。系统会在付费操作前展示所需积点，只有得到你的明确确认后才会执行。\r\n\r\n## 一、直接告诉 AI 你要做什么\r\n\r\n在已安装本 Skill 的 AI 客户端中直接输入：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 分析 ASIN B0XXXXXXXX，站点 amz_us，先告诉我需要多少积点，不要直接扣点。\r\n```\r\n\r\n也可以这样说：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 采集 B0XXXXXXXX 的 3 页美国站评论，先报价，等我确认后再执行。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 对比 B0AAAAAAAA 和 B0BBBBBBBB，找出竞品差评、购买动机和 Listing 改进机会。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 看看我有没有差评预警，帮我列出待处理差评并给最严重的一条写回复建议。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 对 B0XXXXXXXX 做类目对标，看它在行业里的星级和差评率位置。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 导出 B0XXXXXXXX 的全部评论为 CSV。\r\n```\r\n\r\n付费采集或 AI 分析都会先报价，只有你明确确认后才会扣除 ARI 积点。\r\n\r\n## 二、第一次使用：申请并配置 API Key\r\n\r\n**推荐方式（一键授权，无需复制粘贴）**：在 Skill 目录打开终端运行\r\n\r\n```bash\r\npython scripts/ari.py setup\r\n```\r\n\r\n命令会打印一个授权链接。用浏览器打开它，登录（没有账号就先注册并完成邮箱验证），\r\n点一下「授权」，回到终端等几秒——Key 自动获取并保存，完成。\r\n\r\n**手动方式**（授权链接打不开时备用）：\r\n\r\n1. 登录 [ARI 用户中心](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)。\r\n2. 完成邮箱验证。\r\n3. 在“API Key”区域创建密钥，并立即复制以 `ari_live_` 开头的完整 Key。\r\n4. 如客户端要求手动配置，请在 Skill 目录打开终端并运行：\r\n\r\n```bash\r\npython scripts/ari.py configure\r\n```\r\n\r\n5. 按提示粘贴 API Key。输入过程不会显示字符，这是正常的。\r\n6. 验证账户和余额：\r\n\r\n```bash\r\npython scripts/ari.py check\r\n```\r\n\r\nKey 只保存在你的本机用户配置中。请勿把 Key 发给他人、写进截图或放进公开文档。\r\n\r\n## 三、命令行完整流程\r\n\r\n### 1. 一键生成 VOC 报告（推荐）\r\n\r\n```bash\r\npython scripts/ari.py voc B0XXXXXXXX --site amz_us\r\n```\r\n\r\n该命令一次返回采集 + VOC 的总报价，不扣积点。确认后运行：\r\n\r\n```bash\r\npython scripts/ari.py voc B0XXXXXXXX --site amz_us --confirm\r\n```\r\n\r\n它会自动完成：检查现有评论 → 必要时采集并等待 → 生成 VOC →\r\n保存到用户中心 → 返回完整报告正文、`reportId` 和 `reportUrl`。\r\n默认采集 3 页，可用 `--pages 1..10` 调整。\r\n\r\n### 2. 单独采集或查看免费数据（高级）\r\n\r\n只需采集时：\r\n\r\n```bash\r\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3\r\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3 --confirm --wait\r\n```\r\n\r\n查看免费数据：\r\n\r\n```bash\r\npython scripts/ari.py reviews --asin B0XXXXXXXX --site amz_us\r\npython scripts/ari.py charts --asin B0XXXXXXXX --site amz_us\r\n```\r\n\r\n`charts` 会一次返回星级、趋势、关键词和评论流向数据。默认 `--days 0`（全部历史）；\r\n传 `--days 90` 则所有图表都只统计最近 90 天，看数时请注意这个窗口。\r\n\r\n### 3. 其他分析类型（高级）\r\n\r\n```bash\r\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us\r\n```\r\n\r\n确认后生成分析：\r\n\r\n```bash\r\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us --confirm\r\n```\r\n\r\n支持的分析类型：\r\n\r\n- `voc`：消费者之声综合报告\r\n- `insight`：痛点、购买动机、画像和场景\r\n- `trend`：评论与情绪趋势\r\n- `variant`：颜色、尺寸等变体分析\r\n- `compare`：目标产品和竞品对比\r\n\r\n竞品对比同样是先报价、后确认。先看价：\r\n\r\n```bash\r\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us\r\n```\r\n\r\n确认价格后再加 `--confirm`：\r\n\r\n```bash\r\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us --confirm\r\n```\r\n\r\n两个 ASIN 都需要先完成评论采集，各自至少 10 条评论。\r\n\r\n### 4. 差评预警与差评工作台\r\n\r\n订阅 ASIN 后服务端会自动监控差评突增、星级下滑，查看预警（免费）：\r\n\r\n```bash\r\npython scripts/ari.py alerts\r\n```\r\n\r\n列出待处理差评（免费，返回每条差评的 reviewId）：\r\n\r\n```bash\r\npython scripts/ari.py workbench --asin B0XXXXXXXX\r\n```\r\n\r\n为某条差评生成 AI 回复/申诉/改进建议（付费，先报价、确认后加 `--confirm`）：\r\n\r\n```bash\r\npython scripts/ari.py advise --review-id 12345 --confirm\r\n```\r\n\r\n### 5. 行业对标与类目排行\r\n\r\n免费查看本品在类目里的星级/差评率位置：\r\n\r\n```bash\r\npython scripts/ari.py benchmark --asin B0XXXXXXXX\r\n```\r\n\r\n类目排行为付费查询（先报价，确认后加 `--confirm`；类目无数据不收费）：\r\n\r\n```bash\r\npython scripts/ari.py leaderboard --category \"Kitchen\" --by neg_rate --confirm\r\n```\r\n\r\n### 6. 导出评论与报告（付费套餐功能，不扣积点）\r\n\r\n```bash\r\npython scripts/ari.py export --asin B0XXXXXXXX\r\npython scripts/ari.py export --report-id 报告ID --format md\r\n```\r\n\r\n评论导出为 CSV，报告可导出 Markdown / HTML，文件保存在当前目录（可用 `--out` 指定路径）。\r\n\r\n### 7. 查看历史报告\r\n\r\n```bash\r\npython scripts/ari.py reports\r\npython scripts/ari.py report --id 报告ID\r\n```\r\n\r\n## 四、常用入口\r\n\r\n- 每份生成的报告都带 `reportUrl` 在线链接：登录后可看**图表版完整报告**并导出，\r\n 比终端里的纯文本丰富得多，推荐收藏。\r\n- [申请或撤销 API Key](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\r\n- [充值与套餐](https://ari.funewa.com/zh/billing)\r\n- [产品管理](https://ari.funewa.com/zh/products)\r\n- [报告中心](https://ari.funewa.com/zh/reports)\r\n\r\n## 五、常见问题\r\n\r\n### 提示 API Key 无效\r\n\r\nKey 可能被撤销、复制不完整或属于其他账户。前往 ARI 用户中心重新创建，然后再次运行 `configure`。\r\n\r\n### 提示邮箱未验证\r\n\r\n先在 ARI 用户中心完成邮箱验证，再重新执行命令。\r\n\r\n### 提示积点不足\r\n\r\n已有的免费数据仍可查看，但不能继续付费采集或分析。前往“充值与套餐”补充积点。\r\n\r\n### 余额明明够，采集非美国站却说积点不足\r\n\r\n赠送的积点（每月自动发放的那部分）**只能用于美国站**。采集 `amz_uk`、`amz_de`、\r\n`amz_jp` 等站点只能使用充值获得的付费积点。报价里的 `usableBalance` 就是该站点实际\r\n可用的数量，`sufficient` 为 `false` 时请先充值。\r\n\r\n### 提示有新版本 / 提示版本过旧\r\n\r\n运行任意命令时，如果输出里出现 `update` 字段，说明服务端有更新的 Skill 版本。\r\n按提示里的链接，通过你当初安装本 Skill 的渠道更新即可。查看当前版本：\r\n\r\n```bash\r\npython scripts/ari.py check\r\n```\r\n\r\n返回的 `skillVersion` 是本地版本，`release.latest` 是服务端最新版。\r\n\r\n如果提示 `ARI_SKILL_TOO_OLD`，说明你的版本存在会导致**重复扣点**的问题，\r\n服务端已禁止它执行采集和 AI 分析（免费的查询不受影响）。请务必更新后再继续付费操作。\r\n\r\n> 出于安全考虑，本 CLI 不会自行下载或运行任何远端文件，更新必须由你手动完成。\r\n\r\n### 分析到一半提示“分析流中断”\r\n\r\n说明连接断开了，但服务端很可能已经生成完并扣了点。**不要直接重跑**，先查一下：\r\n\r\n```bash\r\npython scripts/ari.py reports --asin B0XXXXXXXX --limit 1\r\n```\r\n\r\n如果最新报告已经出现，直接用 `report --id` 读取即可；确认没有生成，再重新执行分析。\r\n\r\n### 为什么命令没有直接执行采集或分析\r\n\r\n这是扣费保护。`collect`、`analyze` 和付费 `deepdive` 必须增加 `--confirm` 才会真正执行。\r\n\r\n### 如何查看某个命令的全部参数\r\n\r\n```bash\r\npython scripts/ari.py --help\r\npython scripts/ari.py collect --help\r\npython scripts/ari.py analyze --help\r\n```\r\n\r\n默认站点为美国站 `amz_us`，还支持 `amz_uk`、`amz_de`、`amz_jp`、`amz_ca`、`amz_fr`、`amz_es` 和 `amz_it`。\n\nFile v0.1.3:agents/openai.yaml\n\ninterface:\n display_name: \"亚马逊变体分析 · 颜色尺寸口碑对比\"\n short_description: \"颜色尺寸规格口碑对比，揪出拖分变体\"\n default_prompt: \"使用 $amazon-variant-analysis 对一个 Amazon ASIN 做变体归因，找出表现最好与最差的变体。\"\n\nArchive v0.1.2: 11 files, 35913 bytes\n\nFiles: _meta.json (142b), agents (0b), agents/openai.yaml (286b), README.md (5348b), references (0b), references/reference.md (9530b), scripts (0b), scripts/ari.py (58007b), skill-card.md (2921b), SKILL.md (7234b), 使用说明.md (8725b)\n\nFile v0.1.2:SKILL.md\n\n---\r\nname: amazon-variant-analysis\r\ndisplay_name: 亚马逊变体分析 · 颜色尺寸口碑对比\r\ndescription: >\r\n 亚马逊变体分析 Skill：对比同一父体下不同颜色、尺寸、规格的口碑差异，\r\n 找出拖累整体评分的问题变体与真正跑量的优势变体，\r\n 为砍变体、调库存、换主推提供依据。Use when the user asks about variant comparison,\r\n size or color issues, parent-child ASIN analysis, 变体分析、颜色尺寸对比、\r\n 子体表现、变体口碑、SKU 对比、问题变体。Requires an ARI API key (ari_live_*).\r\nauthor: ARI (funewa)\r\nversion: \"1.3.0\"\r\nagent_created: true\r\n---\r\n\r\n# 亚马逊变体分析\r\n\r\n## 工具与入口\r\n\r\n- CLI：本 Skill 目录下的 `scripts/ari.py`。在 Skill 根目录执行，例如\r\n `python scripts/ari.py check`；每次会话先跑一次 `check`。\r\n- API 参考：需要字段、命令或错误码时读取 `references/reference.md`。\r\n- API Key：首次使用运行 `python scripts/ari.py setup`——它会给出一个授权链接，\r\n 用户在浏览器登录（或注册）后点一下「授权」，Key 自动获取并保存到本机，无需复制粘贴。\r\n 也可用环境变量 `ARI_API_KEY`，或 `python scripts/ari.py configure` 手动粘贴。\r\n `setup` 期间把命令打印的授权链接原样转告用户，等待命令自行完成；**不要**替用户注册或登录。\r\n- 申请 Key（手动方式）：\r\n- 充值/套餐：\r\n- Web 产品管理：\r\n\r\n## 安全与计费协议\r\n\r\n- 缺少 Key 时立即停止，给出申请链接；不要索要用户密码，不要把 Key 写入报告或命令示例。\r\n- `401 / ARI_UNAUTHENTICATED`：停止并引导重建 Key。\r\n- `402 / ARI_INSUFFICIENT_CREDITS`：保留已有结果，引导充值；不得自动重试付费操作。\r\n- `ARI_EMAIL_NOT_VERIFIED`：引导先到用户中心验证邮箱。\r\n- 默认使用 `voc ` 一次报出采集 + VOC 总费用。用户确认后追加\r\n `--confirm`，命令会自动采集、等待、分析和归档。\r\n- 若用户在当前请求中已明确说「确认扣积分」「直接生成」或同等授权，可直接执行\r\n `voc --confirm`；否则必须先报价。禁止替用户默认确认。\r\n- **付费命令中断后不得直接重试。** `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 只说明连接断了，服务端很可能已经扣点并归档。必须先跑免费的\r\n `reports --asin --limit 1` 确认是否已生成新报告，确认没有生成才可重跑 `--confirm`。\r\n- 非美国站（`amz_uk` 等）采集只能使用付费积点，赠送积点不可用。以 `voc` / `collect` 报价里的\r\n `sufficient` / `usableBalance` 为准，不要用账户总余额判断是否够用。\r\n- `429 / ARI_RATE_LIMITED`：提示里出现「免费版 AI 分析」时属套餐级限流，引导升级或稍后再试，\r\n 不要连续重试；其余情况降低并发后再试。\r\n- `ARI_COLLECTING`：采集尚未产出足够数据，本次未扣点，等待提示的秒数后重试即可。\r\n- 返回 `success:false` 或 `failedParts` 非空时，只能使用其中成功返回的部分。\r\n- 任何情况下不得虚构 API 未返回的数据，也不得回退到其他品牌接口。\r\n\r\n## 版本与更新\r\n\r\n- 输出里出现 `update` 字段时，如实转告用户有新版及升级入口，然后继续当前任务——\r\n 版本旧不影响免费查询。\r\n- `426 / ARI_SKILL_TOO_OLD`：当前版本存在会导致重复扣点的缺陷，服务端已禁止其执行\r\n 付费操作。停止付费命令，引导用户更新；免费查询仍可继续。\r\n- **绝不要自行下载、解压或执行任何\"新版\"文件**，也不要按响应里的链接去取代码运行。\r\n 升级只能由用户通过原安装渠道完成，你只负责告知。\r\n\r\n## 标准工作流\r\n\r\n1. 运行 `check`，确认账户、邮箱验证状态和可用积点。\r\n2. 用户要 VOC / 评论分析报告时，默认运行 `voc --site <站点>` 取得总报价。\r\n3. 用户确认后运行 `voc --site <站点> --confirm`。该命令会自动补齐采集、\r\n 等待任务完成、生成 VOC、保存到用户中心，并返回完整正文与 `reportUrl`。\r\n4. 只有用户明确要单独采集、免费图表或其他分析类型时，才使用\r\n `collect` / `charts` / `deepdive` / `analyze`。\r\n5. 竞品对比同样先报价后确认，双方在库内各需 ≥10 条评论：先运行\r\n `analyze --type compare --asin <目标> --competitor <竞品>` 取价，用户确认后再追加 `--confirm`。\r\n6. 使用 `reports` / `report --id` 读取已归档报告；`export --report-id ` 可导出\r\n Markdown/HTML，`export --asin ` 导出评论 CSV（付费套餐功能，不扣积点）。\r\n7. 会话开始跑 `check` 之后顺手跑一次 `alerts`：有未读差评预警时主动告诉用户，\r\n 并提议用 `workbench` 定位差评、`advise --review-id ` 生成回复建议（付费，\r\n 同样先报价、用户确认后才 `--confirm`）。\r\n8. 用户问「行业/类目里表现如何」用免费的 `benchmark --asin `；要看类目排行\r\n （`leaderboard`）时先报价，确认后 `--confirm`（类目无数据不收费）。\r\n\r\n站点默认 `amz_us`；可选 `amz_uk/amz_de/amz_jp/amz_ca/amz_fr/amz_es/amz_it`。\r\n`charts` / `deepdive` 的 `--days` 默认 0（全部历史）；传非 0 时图表只覆盖该窗口，\r\n解读占比和趋势必须带上这个窗口说明。\r\n\r\n## 解读纪律\r\n\r\n- 把 API 数字、由数字推导的判断、行动建议明确区分：`📊 数据直读`、`🔍 数据推理`、\r\n `💡 策略建议`。策略建议不得标为数据直读。\r\n- `reviewCount < 50` 时在报告顶部标注小样本提示；单次提及只能作为方向性线索。\r\n- 痛点优先级同时考虑提及频率、低星程度、近期趋势和已验证购买，不凭单条评论下结论。\r\n- 用好评高频表达提炼 Listing 语言，但引用评论原话时保持短句并注明来自评论样本。\r\n- 竞品对比只比较双方 API 均有数据的指标；一方样本不足时明确写“不可比”。\r\n- 报告语言跟随用户；ASIN、VOC、Listing 等术语保留原文。非中文回复时记得传\r\n `--language en` 等，CLI 默认是 `zh`。\r\n\r\n## 报告结构\r\n\r\n按有数据的部分输出：数据概览 → 痛点与低星原因 → 好评与购买动因 → 用户画像与场景 →\r\n趋势 → 竞品差异 → Listing 建议 → 产品改进优先级 → 数据来源与积点用量。\r\n\r\n报告顶部加入：\r\n\r\n> 数据基于 ARI 已采集的 Amazon 评论样本（截至当前查询时间），仅供经营决策参考；\r\n> 小样本或采集窗口有限时应结合更多信源验证。\r\n\r\n结尾列出使用的 CLI 命令、ASIN/站点、样本量、统计窗口（`_window.days`）、报告返回的\r\n`reportId` 与 `creditsUsed`，以及当前余额。**输出含 `reportUrl` 时必须在结尾附上**，\r\n固定文案：「在线查看图表版完整报告 / 导出：」（需登录报告所属账户）。\n\nFile v0.1.2:README.md\n\n# 亚马逊变体分析 · 颜色尺寸口碑对比\r\n\r\n颜色尺寸规格口碑对比，揪出拖分变体\r\n\r\n> **亚马逊变体分析 · 颜色尺寸口碑对比**\r\n> 技术名 `amazon-variant-analysis`，ARI 官方出品的 Amazon 评论采集与消费者洞察 Skill，已适配 WorkBuddy。\r\n> 安装后直接用中文描述需求即可，无需理解 API 或编写代码；所有付费操作都会先报价，\r\n> 只有你明确确认后才会扣除积点。\r\n\r\n## 能做什么\r\n\r\n- 订阅 ASIN、采集评论，查看星级 / 关键词 / 趋势 / 流向等免费图表数据。\r\n- 生成 **VOC**、**深度洞察**、**趋势**、**变体**、**竞品对比** 五类 AI 分析报告。\r\n- 输出痛点、购买动因、用户画像、使用场景、改进机会与 Listing 建议。\r\n- **差评预警**（差评突增自动提醒）与**差评工作台**（AI 生成回复/申诉建议）。\r\n- **行业对标**（类目星级/差评率位置）与付费**类目排行**。\r\n- 评论一键导出 **CSV**，报告导出 **Markdown / HTML**（付费套餐功能）。\r\n\r\n安装后直接以自然语言提需求：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 为 ASIN B0XXXXXXXX 生成 VOC 报告，站点 amz_us，我确认扣积分。\r\n```\r\n\r\n## 前置条件\r\n\r\n- **Python 3**（只用标准库，无第三方依赖）。\r\n- 一个 **ARI API Key**（`ari_live_` 开头）。首次使用运行\r\n `python scripts/ari.py setup`，在浏览器登录或注册后点一下「授权」，\r\n Key 会自动写入本机，无需手工复制粘贴。\r\n 也可在 手动创建。\r\n\r\n## 安装到 WorkBuddy\r\n\r\n保持文件夹名 `amazon-variant-analysis`，整个放进对应作用域即可：\r\n\r\n| 作用域 | 路径 |\r\n|---|---|\r\n| 用户级（推荐） | `~/.workbuddy/skills/amazon-variant-analysis/` |\r\n| 项目级 | `<项目目录>/.workbuddy/skills/amazon-variant-analysis/` |\r\n\r\n装好后验证账户与积点余额：\r\n\r\n```bash\r\npython /scripts/ari.py check\r\n```\r\n\r\n> `` 是 WorkBuddy 加载 Skill 时自动替换的目录占位符；直接在终端跑时，\r\n> 请先进入 Skill 目录，或把它换成实际路径。\r\n\r\nKey 运行时从 `ARI_API_KEY` 或 `~/.ari/config.json` 读取——**切勿**提交进仓库，\r\n也不要把 Key 贴进公开文档或发给他人。\r\n\r\n## 命令一览\r\n\r\n| Command | 作用 | 扣积点 |\r\n|---|---|---|\r\n| `setup` / `configure` | 部署 API Key | 否 |\r\n| `check` | 账户与余额 | 否 |\r\n| `products` | 已订阅 ASIN 列表 | 否 |\r\n| `voc` | 自动采集 + VOC + 归档 + 报告链接 | **是，需 `--confirm`** |\r\n| `collect` | 提交采集任务 | **是，需 `--confirm`** |\r\n| `status` | 采集任务进度 | 否 |\r\n| `reviews` | 读取已采集评论 | 否 |\r\n| `charts` | 星级 / 趋势 / 关键词 / 流向 | 否 |\r\n| `quote` | 分析报价 | 否 |\r\n| `analyze` | voc / insight / trend / variant / compare | **是，需 `--confirm`** |\r\n| `deepdive` | 产品 + 图表 + 评论 + 报告 + VOC 报价 | 默认否，`--confirm` 才分析 |\r\n| `reports` / `report` | 历史报告列表 / 详情 | 否 |\r\n| `alerts` | 差评/星级预警 | 否 |\r\n| `benchmark` | 类目对标概览 | 否 |\r\n| `leaderboard` | 类目排行 | **是，需 `--confirm`** |\r\n| `workbench` | 差评列表 / 建议存档 / 状态流转 | 否 |\r\n| `advise` | 单条差评 AI 回复建议 | **是，需 `--confirm`** |\r\n| `export` | 评论 CSV / 报告 MD·HTML 导出 | 否（限付费套餐） |\r\n\r\n`python scripts/ari.py --help` 看完整参数。默认站点 `amz_us`，\r\n另支持 `amz_uk / amz_de / amz_jp / amz_ca / amz_fr / amz_es / amz_it`。\r\n\r\n## 扣费保护\r\n\r\n采集与 AI 分析消耗积点。付费命令（`voc`、`collect`、`analyze`、付费 `deepdive`）**必须**\r\n显式追加 `--confirm` 才真正执行，不带时只返回报价。\r\n\r\n- **非美国站只能用付费积点。** 采集 `amz_uk` / `amz_de` 等站点时赠送积点不可用，\r\n 以 `collect` 报价里的 `usableBalance` / `sufficient` 为准，别看账户总余额。\r\n- **付费命令中断后不要直接重跑。** 出现 `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 时服务端可能已扣点并归档，先用免费的\r\n `reports --asin --limit 1` 核对，确认没生成再重试。\r\n- **聚合命令部分失败体现在最外层。** `charts` / `deepdive` 任一子请求失败时返回\r\n `success:false` 并附 `failedParts`，成功的部分仍在 `data` 里，只能用这部分。\r\n\r\n## 目录结构\r\n\r\n```\r\nSKILL.md # Skill 清单 + 操作指令（WorkBuddy 规范）\r\nREADME.md # 本文件\r\n使用说明.md # 中文终端用户指南\r\nscripts/ari.py # 仅依赖标准库的 CLI\r\nreferences/reference.md# CLI 与 API 参考（命令 / 字段 / 错误码）\r\nagents/openai.yaml # 其他客户端的接口元数据（WorkBuddy 不使用，保留以兼容多端）\r\n```\r\n\r\n## 常用入口\r\n\r\n- API Key：\r\n- 充值套餐：\r\n- 产品管理：\r\n- 报告中心：\r\n- 新用户注册即赠积点，免费额度可通过任务中心持续解锁：\r\n \n\nFile v0.1.2:_meta.json\n\n{\n \"ownerId\": \"kn7d4ekgxgbth42fthnftjf1tn89w6df\",\n \"slug\": \"amazon-variant-analysis\",\n \"version\": \"0.1.2\",\n \"publishedAt\": 1788443345470\n}\n\nFile v0.1.2:references/reference.md\n\n# ARI CLI 与 API 参考\r\n\r\n仅在需要命令参数、响应字段或错误处理时读取本文件。\r\n\r\nAPI 默认地址：`https://ari.funewa.com`（开发环境可用 `ARI_BASE_URL` 覆盖）。\r\n认证头：`Authorization: Bearer ari_live_...`。统一 JSON 信封为\r\n`{success, code, message, data, error, meta}`；SSE 分析由 CLI 聚合为同类 JSON。\r\n\r\n`--compact` 输出单行 JSON，放在子命令前后都可以\r\n（`ari.py --compact check` 与 `ari.py check --compact` 等价）。\r\n\r\n## 版本与更新\r\n\r\nCLI 在 User-Agent 里带自身版本（`ARI-Review-Skill/`，与 `_meta.json` 一致）。\r\n服务端在每个 API Key 响应上回 `X-ARI-Skill-Latest` / `X-ARI-Skill-Update-Url`；\r\n本地版本更旧时，**任意命令**的输出都会多出一个顶层 `update` 字段：\r\n\r\n```json\r\n{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}\r\n```\r\n\r\n`check` 还会额外读取免认证的 `/api/v1/public/config`，把完整的\r\n`release: {latest, minSupported, url, notes}` 一并返回——Key 失效时也能拿到升级入口。\r\n\r\n升级一律由用户通过原安装渠道完成。**CLI 不会下载或执行任何远端代码**，\r\n也不要让 agent 代劳去取\"新版文件\"运行。\r\n\r\n## 用户入口\r\n\r\n- API Key：\r\n- 充值/套餐：\r\n- 产品管理：\r\n- 报告中心：\r\n\r\n## CLI 命令\r\n\r\n| 命令 | API | 是否可能扣点 |\r\n|---|---|---|\r\n| `setup` | auth/device/start + poll（免认证），浏览器授权后自动保存 Key | 否 |\r\n| `configure` | 本地保存 Key | 否 |\r\n| `check` | user/me + credits/balance | 否 |\r\n| `products` | asins | 否 |\r\n| `voc` | pricing + balance + collection/submit/status + analysis/voc + reports | 是；必须 `--confirm` |\r\n| `collect` | billing/pricing + credits/balance + collection/submit | 是；必须 `--confirm` |\r\n| `status` | collection/status/{taskId} | 否 |\r\n| `reviews` | reviews | 否 |\r\n| `charts` | charts/stars·trend·keywords·flow | 否 |\r\n| `quote` | analysis/quote | 否 |\r\n| `analyze` | analysis/voc·insight·trend·variant·compare | 是；必须 `--confirm` |\r\n| `deepdive` | products + charts + reviews + reports + VOC quote/analysis | 默认否；`--confirm` 才分析 |\r\n| `reports` / `report` | reports | 否 |\r\n| `alerts` | alerts（`--mark-read` 时 alerts/read） | 否 |\r\n| `benchmark` | benchmark | 否 |\r\n| `leaderboard` | billing/pricing + leaderboard | 是；必须 `--confirm`，类目无数据不收费 |\r\n| `workbench` | workbench/reviews（`--history`: advices；`--set-status`: 状态更新） | 否 |\r\n| `advise` | analysis/quote + workbench/advise（SSE） | 是；必须 `--confirm` |\r\n| `export` | export/reviews 或 export/reports/{id}，落盘本地文件 | 否（限付费套餐） |\r\n| `version` | 无网络请求 | 否 |\r\n\r\n运行 `python ari.py <命令> --help` 查看完整参数。\r\n\r\n## 预警、对标与差评工作台\r\n\r\n- `alerts [--limit N]`：未读情感预警（差评突增、星级下滑）。`--mark-read` 全部置已读。\r\n- `benchmark --asin B0...`：免费类目对标概览（本品星级/差评率在类目内的相对位置）。\r\n- `leaderboard --category <类目> [--by new30|neg_rate|avg_star]`：付费类目排行。\r\n 无服务端报价握手，CLI 先读 `billing/pricing` 的 `leaderboard` 单价报出，确认后\r\n `--confirm` 执行；`ARI_INSUFFICIENT_REVIEWS`（类目无数据）不收费。\r\n- `workbench [--asin] [--site] [--status pending|contacted|appealed|improving|archived]`：\r\n 免费列差评（返回 `reviewId`）；`--history [--query]` 看 AI 建议存档；\r\n `--review-id N --set-status <状态>` 更新处理状态。\r\n- `advise --review-id N`：为单条差评生成回复/申诉/改进建议（SSE，`data.content` 为\r\n Markdown）。先按 `quote type=advise` 报价，确认后 `--confirm`。流中断处理同 VOC。\r\n- `export --asin B0...`（评论 CSV）或 `export --report-id N [--format md|html]`（报告）：\r\n 文件写到本地，返回 `savedTo/bytes`。Free 套餐会收到 403「导出为付费功能」。\r\n\r\n## 采集\r\n\r\n`voc B0... --site amz_us` 是默认的用户入口：已有 ≥10 条评论时直接报 VOC 价；\r\n数据不足时合并报出默认 3 页采集与 VOC 的最大总费用。追加 `--confirm`\r\n后自动采集、等待、分析、归档，最外层返回 `report.content / reportId / reportUrl`。\r\n\r\n`collect --asin B0... --site amz_us --pages 3` 只返回报价；确认后追加\r\n`--confirm --wait`。请求字段：`asin, site, pageCount, filterByStar, sortBy, alias`。\r\n\r\n- `pages`: 1–10，每页约 10 条。\r\n- `filterByStar`: `all_stars|critical|positive|one_star|two_star|three_star|four_star|five_star`。\r\n- `sortBy`: `recent|helpful`。\r\n- **US 以外站点只能使用付费（addon）积点**，赠送的 plan 积点被排除。报价字段\r\n `usableBalance` 已按站点算好，`sufficient=false` 时不要确认——服务端会直接 402。\r\n 报价还返回 `planCredits` / `addonCredits` / `siteNote` 供解释。\r\n- `--wait` 轮询 `collection/status`，任务状态只有 `queued|running|done|failed`。\r\n 瞬时错误会自动重试 3 次；仍失败或超时返回 `WAIT_TIMEOUT`，此时任务仍在后台，\r\n 用 `status --task ` 查询，**不要重新提交采集**。\r\n\r\n## 分析\r\n\r\n先调用 `quote --type ...`。报价字段：\r\n`type, basePrice, price, sampledReviews, totalReviews, balance, sufficient`。\r\n\r\n- `voc`: Markdown VOC 报告，SSE 聚合后在 `data.content`，并归档。\r\n- `insight`: 结构化消费者洞察，`data.result`，同时可能含流式说明 `content`。\r\n- `trend`: 情感趋势解读，普通 JSON。\r\n- `variant`: 颜色/尺寸等变体归因，普通 JSON；需足量变体评论。\r\n- `compare`: 目标与竞品对比，**双方在库内各需 ≥10 条评论**（订阅关系不作强制校验，\r\n 但 charts/reviews 等 0 积点端点仍要求订阅）。必须传 `--competitor`。\r\n\r\nSSE 聚合结果字段：`meta, content, result, reportId, creditsUsed`。\r\nVOC 服务端在归档后直接于 `done` 事件返回本次 `reportId`；CLI 据此生成\r\n`reportUrl`。兼容旧服务端时才回查报告列表，并标记 `reportIdSource: \"reports-lookup\"`。\r\n\r\nFree 套餐的 AI 分析被强制降级到轻量模型，且受全局限流保护——报告深度与付费档不同，\r\n必要时说明这一点。\r\n\r\n## 免费数据字段\r\n\r\n- `products`: `asins[], count, limit`；元素含 `asin, site, alias, collectionStatus,\r\n lastCollectedAt, reviewCount, variantCount`。**只包含主品**，作为竞品添加的 ASIN\r\n 不在其中（但它们的 charts/reviews 依然可读）。\r\n- `reviews`: `reviews[], total, page, pageSize`；每条含标题、正文、星级、日期、\r\n verifiedPurchase、helpfulCount、attributes。\r\n- `charts stars`: `stars[1★..5★], total, avgStar`。\r\n- `charts trend`: 按月评论数、平均星级、低星数。\r\n- `charts keywords`: `keywords[]`。\r\n- `charts flow`: 场景/问题等流向结构；为空时不要补造。\r\n- `charts` / `deepdive` 额外返回 `_window: {days, note}`，`days=0` 表示全部历史；\r\n 非 0 时所有图表只统计最近 N 天，解读必须带上该窗口。\r\n\r\n## 聚合命令的失败语义\r\n\r\n`charts` 和 `deepdive` 会并发调多个端点。任一子请求失败时，最外层就是\r\n`success:false`，并给出 `failedParts:[{part, code, message}]`（如 `charts.trend`、\r\n`analysis`），成功的部分仍保留在 `data` 里。只能使用成功的那部分，缺失的数据不得推断。\r\n\r\n`deepdive` 找不到主品订阅时不会直接报错：仍返回 charts/reviews/reports，\r\n并在 `productNote` 里说明；此时即使传了 `--confirm`，AI 分析也会降级为只报价、不扣点。\r\n\r\n## 错误处理\r\n\r\n| 状态/错误码 | 动作 |\r\n|---|---|\r\n| 401 / `ARI_UNAUTHENTICATED` | Key 无效或已撤销；去用户中心重建 |\r\n| 402 / `ARI_INSUFFICIENT_CREDITS` | 停止付费操作；展示已有结果并引导充值 |\r\n| 403 / `ARI_EMAIL_NOT_VERIFIED` | 去用户中心验证邮箱 |\r\n| 403 / `ARI_FORBIDDEN`（含配额字样） | 已达套餐可订阅 ASIN 上限；引导删除旧 ASIN 或升级套餐 |\r\n| 403 / `ARI_FORBIDDEN`（其他） | 该 ASIN 不在当前账户订阅内；或 API Key 无账户/支付/后台权限 |\r\n| 422 / `ARI_INSUFFICIENT_REVIEWS` | 先增加采集页数；不把小样本包装成确定结论 |\r\n| 202 / `ARI_COLLECTING` | 采集中且数据不足，**未扣点**；按提示秒数等待后重试 |\r\n| 429 / `ARI_RATE_LIMITED`（含「免费版 AI 分析」） | 套餐级限流；引导升级或稍后再试，不要连续重试 |\r\n| 429 / `ARI_RATE_LIMITED`（其他） | 降低并发后再试；不要并发轰炸 |\r\n| `ARI_STREAM_INTERRUPTED` | 分析流中断，**服务端可能已扣点并归档**；先 `reports --asin --limit 1` 核对，没生成才可重试 |\r\n| `NETWORK_ERROR` / `WAIT_TIMEOUT` | 同上：付费命令一律先核对再决定是否重跑 |\r\n| `ARI_PARTIAL_FAILURE` | 聚合命令部分失败；见 `failedParts`，只用成功的部分 |\r\n| 426 / `ARI_SKILL_TOO_OLD` | 当前版本低于服务端最低支持版本，付费操作被禁止；引导用户更新，免费查询不受影响 |\r\n\r\nCLI 网络错误和 HTTP 错误均返回结构化 JSON，不应从报错文本臆测业务数据。\n\nFile v0.1.2:skill-card.md\n\n## Description:\n\nHelps Amazon sellers compare review performance across color, size, and other child-ASIN variants to identify weak variants, strong sellers, and inventory or listing actions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[funewa](https://clawhub.ai/user/funewa)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal Amazon sellers and operators use this skill to run ARI-powered review collection and analysis, including variant, VOC, competitor, alert, benchmark, and export workflows. Paid collection or AI analysis workflows require an explicit quote and user confirmation before execution.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill handles a live ARI API key.\n\nMitigation: Treat ARI_API_KEY and the local ARI configuration as sensitive credentials; do not paste keys into reports, examples, screenshots, or public files.\n\nRisk: ARI_BASE_URL and ARI_WEB_URL can direct requests and web links to an environment-controlled host.\n\nMitigation: Leave these variables unset for normal use, or set them only when the destination is fully trusted.\n\nRisk: Some collection, analysis, leaderboard, and advice commands can consume paid ARI credits.\n\nMitigation: Run quote or preview commands first and add --confirm only after the user has checked the cost and explicitly approved it.\n\nRisk: A network or stream interruption after confirmation may still correspond to a completed, charged report.\n\nMitigation: Check the latest saved report before retrying a confirmed paid command.\n\nRisk: The skill exposes broader ARI review-management workflows than the variant-analysis name alone implies.\n\nMitigation: Install it only when broad Amazon review analytics, alerts, workbench, benchmark, and export capabilities are intended.\n\n## Reference(s):\n\n- [ARI CLI and API Reference](references/reference.md)\n- [User Guide](使用说明.md)\n- [ClawHub Skill Page](https://clawhub.ai/funewa/skills/amazon-variant-analysis)\n- [Server-Resolved GitHub Source](https://github.com/funewa/Amazon-variant-analysis)\n- [ARI Service](https://ari.funewa.com)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, CSV, HTML]\n\n**Output Format:** [Natural-language guidance plus CLI JSON responses, Markdown or HTML reports, and CSV review exports.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires an ARI API key; reports may include report IDs, report URLs, credits used, sample sizes, and analysis windows.]\n\n## Skill Version(s):\n\n0.1.2 (source: ClawHub release metadata; artifact frontmatter and _meta.json report 1.3.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.2:使用说明.md\n\n# ARI Amazon 评论智能助手使用指南\r\n\r\nARI Amazon 评论智能助手可以帮助卖家采集和分析 Amazon 评论，快速发现消费者痛点、购买动机、使用场景、竞品差异与 Listing 优化机会。\r\n\r\n你可以直接用中文提出需求，不需要理解 API，也不需要编写代码。系统会在付费操作前展示所需积点，只有得到你的明确确认后才会执行。\r\n\r\n## 一、直接告诉 AI 你要做什么\r\n\r\n在已安装本 Skill 的 AI 客户端中直接输入：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 分析 ASIN B0XXXXXXXX，站点 amz_us，先告诉我需要多少积点，不要直接扣点。\r\n```\r\n\r\n也可以这样说：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 采集 B0XXXXXXXX 的 3 页美国站评论，先报价，等我确认后再执行。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 对比 B0AAAAAAAA 和 B0BBBBBBBB，找出竞品差评、购买动机和 Listing 改进机会。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 看看我有没有差评预警，帮我列出待处理差评并给最严重的一条写回复建议。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 对 B0XXXXXXXX 做类目对标，看它在行业里的星级和差评率位置。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 导出 B0XXXXXXXX 的全部评论为 CSV。\r\n```\r\n\r\n付费采集或 AI 分析都会先报价，只有你明确确认后才会扣除 ARI 积点。\r\n\r\n## 二、第一次使用：申请并配置 API Key\r\n\r\n**推荐方式（一键授权，无需复制粘贴）**：在 Skill 目录打开终端运行\r\n\r\n```bash\r\npython scripts/ari.py setup\r\n```\r\n\r\n命令会打印一个授权链接。用浏览器打开它，登录（没有账号就先注册并完成邮箱验证），\r\n点一下「授权」，回到终端等几秒——Key 自动获取并保存，完成。\r\n\r\n**手动方式**（授权链接打不开时备用）：\r\n\r\n1. 登录 [ARI 用户中心](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)。\r\n2. 完成邮箱验证。\r\n3. 在“API Key”区域创建密钥，并立即复制以 `ari_live_` 开头的完整 Key。\r\n4. 如客户端要求手动配置，请在 Skill 目录打开终端并运行：\r\n\r\n```bash\r\npython scripts/ari.py configure\r\n```\r\n\r\n5. 按提示粘贴 API Key。输入过程不会显示字符，这是正常的。\r\n6. 验证账户和余额：\r\n\r\n```bash\r\npython scripts/ari.py check\r\n```\r\n\r\nKey 只保存在你的本机用户配置中。请勿把 Key 发给他人、写进截图或放进公开文档。\r\n\r\n## 三、命令行完整流程\r\n\r\n### 1. 一键生成 VOC 报告（推荐）\r\n\r\n```bash\r\npython scripts/ari.py voc B0XXXXXXXX --site amz_us\r\n```\r\n\r\n该命令一次返回采集 + VOC 的总报价，不扣积点。确认后运行：\r\n\r\n```bash\r\npython scripts/ari.py voc B0XXXXXXXX --site amz_us --confirm\r\n```\r\n\r\n它会自动完成：检查现有评论 → 必要时采集并等待 → 生成 VOC →\r\n保存到用户中心 → 返回完整报告正文、`reportId` 和 `reportUrl`。\r\n默认采集 3 页，可用 `--pages 1..10` 调整。\r\n\r\n### 2. 单独采集或查看免费数据（高级）\r\n\r\n只需采集时：\r\n\r\n```bash\r\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3\r\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3 --confirm --wait\r\n```\r\n\r\n查看免费数据：\r\n\r\n```bash\r\npython scripts/ari.py reviews --asin B0XXXXXXXX --site amz_us\r\npython scripts/ari.py charts --asin B0XXXXXXXX --site amz_us\r\n```\r\n\r\n`charts` 会一次返回星级、趋势、关键词和评论流向数据。默认 `--days 0`（全部历史）；\r\n传 `--days 90` 则所有图表都只统计最近 90 天，看数时请注意这个窗口。\r\n\r\n### 3. 其他分析类型（高级）\r\n\r\n```bash\r\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us\r\n```\r\n\r\n确认后生成分析：\r\n\r\n```bash\r\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us --confirm\r\n```\r\n\r\n支持的分析类型：\r\n\r\n- `voc`：消费者之声综合报告\r\n- `insight`：痛点、购买动机、画像和场景\r\n- `trend`：评论与情绪趋势\r\n- `variant`：颜色、尺寸等变体分析\r\n- `compare`：目标产品和竞品对比\r\n\r\n竞品对比同样是先报价、后确认。先看价：\r\n\r\n```bash\r\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us\r\n```\r\n\r\n确认价格后再加 `--confirm`：\r\n\r\n```bash\r\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us --confirm\r\n```\r\n\r\n两个 ASIN 都需要先完成评论采集，各自至少 10 条评论。\r\n\r\n### 4. 差评预警与差评工作台\r\n\r\n订阅 ASIN 后服务端会自动监控差评突增、星级下滑，查看预警（免费）：\r\n\r\n```bash\r\npython scripts/ari.py alerts\r\n```\r\n\r\n列出待处理差评（免费，返回每条差评的 reviewId）：\r\n\r\n```bash\r\npython scripts/ari.py workbench --asin B0XXXXXXXX\r\n```\r\n\r\n为某条差评生成 AI 回复/申诉/改进建议（付费，先报价、确认后加 `--confirm`）：\r\n\r\n```bash\r\npython scripts/ari.py advise --review-id 12345 --confirm\r\n```\r\n\r\n### 5. 行业对标与类目排行\r\n\r\n免费查看本品在类目里的星级/差评率位置：\r\n\r\n```bash\r\npython scripts/ari.py benchmark --asin B0XXXXXXXX\r\n```\r\n\r\n类目排行为付费查询（先报价，确认后加 `--confirm`；类目无数据不收费）：\r\n\r\n```bash\r\npython scripts/ari.py leaderboard --category \"Kitchen\" --by neg_rate --confirm\r\n```\r\n\r\n### 6. 导出评论与报告（付费套餐功能，不扣积点）\r\n\r\n```bash\r\npython scripts/ari.py export --asin B0XXXXXXXX\r\npython scripts/ari.py export --report-id 报告ID --format md\r\n```\r\n\r\n评论导出为 CSV，报告可导出 Markdown / HTML，文件保存在当前目录（可用 `--out` 指定路径）。\r\n\r\n### 7. 查看历史报告\r\n\r\n```bash\r\npython scripts/ari.py reports\r\npython scripts/ari.py report --id 报告ID\r\n```\r\n\r\n## 四、常用入口\r\n\r\n- 每份生成的报告都带 `reportUrl` 在线链接：登录后可看**图表版完整报告**并导出，\r\n 比终端里的纯文本丰富得多，推荐收藏。\r\n- [申请或撤销 API Key](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\r\n- [充值与套餐](https://ari.funewa.com/zh/billing)\r\n- [产品管理](https://ari.funewa.com/zh/products)\r\n- [报告中心](https://ari.funewa.com/zh/reports)\r\n\r\n## 五、常见问题\r\n\r\n### 提示 API Key 无效\r\n\r\nKey 可能被撤销、复制不完整或属于其他账户。前往 ARI 用户中心重新创建，然后再次运行 `configure`。\r\n\r\n### 提示邮箱未验证\r\n\r\n先在 ARI 用户中心完成邮箱验证，再重新执行命令。\r\n\r\n### 提示积点不足\r\n\r\n已有的免费数据仍可查看，但不能继续付费采集或分析。前往“充值与套餐”补充积点。\r\n\r\n### 余额明明够，采集非美国站却说积点不足\r\n\r\n赠送的积点（每月自动发放的那部分）**只能用于美国站**。采集 `amz_uk`、`amz_de`、\r\n`amz_jp` 等站点只能使用充值获得的付费积点。报价里的 `usableBalance` 就是该站点实际\r\n可用的数量，`sufficient` 为 `false` 时请先充值。\r\n\r\n### 提示有新版本 / 提示版本过旧\r\n\r\n运行任意命令时，如果输出里出现 `update` 字段，说明服务端有更新的 Skill 版本。\r\n按提示里的链接，通过你当初安装本 Skill 的渠道更新即可。查看当前版本：\r\n\r\n```bash\r\npython scripts/ari.py check\r\n```\r\n\r\n返回的 `skillVersion` 是本地版本，`release.latest` 是服务端最新版。\r\n\r\n如果提示 `ARI_SKILL_TOO_OLD`，说明你的版本存在会导致**重复扣点**的问题，\r\n服务端已禁止它执行采集和 AI 分析（免费的查询不受影响）。请务必更新后再继续付费操作。\r\n\r\n> 出于安全考虑，本 CLI 不会自行下载或运行任何远端文件，更新必须由你手动完成。\r\n\r\n### 分析到一半提示“分析流中断”\r\n\r\n说明连接断开了，但服务端很可能已经生成完并扣了点。**不要直接重跑**，先查一下：\r\n\r\n```bash\r\npython scripts/ari.py reports --asin B0XXXXXXXX --limit 1\r\n```\r\n\r\n如果最新报告已经出现，直接用 `report --id` 读取即可；确认没有生成，再重新执行分析。\r\n\r\n### 为什么命令没有直接执行采集或分析\r\n\r\n这是扣费保护。`collect`、`analyze` 和付费 `deepdive` 必须增加 `--confirm` 才会真正执行。\r\n\r\n### 如何查看某个命令的全部参数\r\n\r\n```bash\r\npython scripts/ari.py --help\r\npython scripts/ari.py collect --help\r\npython scripts/ari.py analyze --help\r\n```\r\n\r\n默认站点为美国站 `amz_us`，还支持 `amz_uk`、`amz_de`、`amz_jp`、`amz_ca`、`amz_fr`、`amz_es` 和 `amz_it`。\n\nFile v0.1.2:agents/openai.yaml\n\ninterface:\n display_name: \"亚马逊变体分析 · 颜色尺寸口碑对比\"\n short_description: \"颜色尺寸规格口碑对比，揪出拖分变体\"\n default_prompt: \"使用 $amazon-variant-analysis 对一个 Amazon ASIN 做变体归因，找出表现最好与最差的变体。\"\n\nArchive v0.1.1: 8 files, 50529 bytes\n\nFiles: _meta.json (142b), agents/openai.yaml (286b), README.md (5237b), references/reference.md (16202b), scripts/ari.py (79604b), skill-card.md (2694b), SKILL.md (13012b), 使用说明.md (13858b)\n\nFile v0.1.1:SKILL.md\n\n---\r\nname: amazon-variant-analysis\r\ndisplay_name: 亚马逊变体分析 · 颜色尺寸口碑对比\r\ndescription: >\r\n 亚马逊变体分析 Skill：对比同一父体下不同颜色、尺寸、规格的口碑差异，\r\n 找出拖累整体评分的问题变体与真正跑量的优势变体，\r\n 为砍变体、调库存、换主推提供依据。Use when the user asks about variant comparison,\r\n size or color issues, parent-child ASIN analysis, 变体分析、颜色尺寸对比、\r\n 子体表现、变体口碑、SKU 对比、问题变体。Requires an ARI API key (ari_live_*).\r\nauthor: ARI (funewa)\r\nagent_created: true\r\nslug: variant-analysis\r\ndisplayName: 亚马逊变体分析 · 颜色尺寸口碑对比\r\nversion: 1.4.3\r\nsummary: 颜色尺寸规格口碑对比，揪出拖分变体\r\nlicense: MIT\r\n---\r\n\r\n# 亚马逊变体分析\r\n\r\n## 工具与入口\r\n\r\n- CLI：本 Skill 目录下的 `scripts/ari.py`。在 Skill 根目录执行，例如\r\n `python scripts/ari.py check`；每次会话先跑一次 `check`。\r\n- API 参考：需要字段、命令或错误码时读取 `references/reference.md`。\r\n- API Key：首次使用运行 `python scripts/ari.py setup`——它会给出一个授权链接，\r\n 用户在浏览器登录（或注册）后点一下「授权」，Key 自动获取并保存到本机，无需复制粘贴。\r\n 也可用环境变量 `ARI_API_KEY`，或 `python scripts/ari.py configure` 手动粘贴。\r\n `setup` 期间把命令打印的授权链接原样转告用户，等待命令自行完成；**不要**替用户注册或登录。\r\n- 申请 Key（手动方式）：\r\n- 充值/套餐：\r\n- Web 产品管理：\r\n\r\n## 安全与计费协议\r\n\r\n- 缺少 Key 时立即停止，给出申请链接；不要索要用户密码，不要把 Key 写入报告或命令示例。\r\n- `401 / ARI_UNAUTHENTICATED`：停止并引导重建 Key。\r\n- `402 / ARI_INSUFFICIENT_CREDITS`：保留已有结果，引导充值；不得自动重试付费操作。\r\n- `ARI_EMAIL_NOT_VERIFIED`：引导先到用户中心验证邮箱。\r\n- 默认使用 `voc ` 一次报出采集 + VOC 总费用。用户确认后追加\r\n `--confirm`，命令会自动采集、等待、分析和归档。\r\n- 若用户在当前请求中已明确说「确认扣积分」「直接生成」或同等授权，可直接执行\r\n `voc --confirm`；否则必须先报价。禁止替用户默认确认。\r\n- **付费命令中断后不得直接重试。** `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 只说明连接断了，服务端很可能已经扣点并归档。必须先跑免费的\r\n `reports --asin --limit 1` 确认是否已生成新报告，确认没有生成才可重跑 `--confirm`。\r\n- 非美国站（`amz_uk` 等）采集只能使用付费积点（订阅套餐周期积点与增量包均可），\r\n 赠送积点（注册礼/任务奖励等）不可用。以 `voc` / `collect` 报价里的\r\n `sufficient` / `usableBalance` 为准，不要用账户总余额判断是否够用。\r\n- `429 / ARI_RATE_LIMITED`：提示里出现「免费版 AI 分析」时属套餐级限流，引导升级或稍后再试，\r\n 不要连续重试；其余情况降低并发后再试。\r\n- `ARI_COLLECTING`：采集尚未产出足够数据，本次未扣点，等待提示的秒数后重试即可。\r\n- 返回 `success:false` 或 `failedParts` 非空时，只能使用其中成功返回的部分。\r\n- 任何情况下不得虚构 API 未返回的数据，也不得回退到其他品牌接口。\r\n\r\n## 版本与更新\r\n\r\n- 输出里出现 `update` 字段时，如实转告用户有新版及升级入口，然后继续当前任务——\r\n 版本旧不影响免费查询。\r\n- `426 / ARI_SKILL_TOO_OLD`：当前版本存在会导致重复扣点的缺陷，服务端已禁止其执行\r\n 付费操作。停止付费命令，引导用户更新；免费查询仍可继续。\r\n- **绝不要自行下载、解压或执行任何\"新版\"文件**，也不要按响应里的链接去取代码运行。\r\n 升级只能由用户通过原安装渠道完成，你只负责告知。\r\n\r\n## 标准工作流\r\n\r\n1. 运行 `check`，确认账户、邮箱验证状态和可用积点。\r\n2. 用户要 VOC / 评论分析报告时，默认运行 `voc --site <站点>` 取得总报价。\r\n3. 用户确认后运行 `voc --site <站点> --confirm`。该命令会自动补齐采集、\r\n 等待任务完成、生成 VOC、保存到用户中心，并返回完整正文与 `reportUrl`。\r\n4. **报告出来后，检查该产品是否已开启定期采集**：跑一次免费的 `schedule`。\r\n 如果该 ASIN 还是 `manual`，主动告诉用户——这份报告只是今天这个时点的快照，\r\n 数据会停在最后一次采集那天；开启 `weekly` 后新评论持续进库，下次生成报告时\r\n 还能给出「相比上一份：哪些问题解决了、哪些是新冒出来的、哪些还在恶化」。\r\n **报出月成本**（`schedule --set` 的返回里带 `_costNote`）让用户自己决定，\r\n 得到明确同意后才执行 `schedule --set weekly --asin `。不要替用户默认开启。\r\n5. 只有用户明确要单独采集、免费图表或其他分析类型时，才使用\r\n `collect` / `charts` / `deepdive` / `analyze`。\r\n6. 竞品对比同样先报价后确认，双方在库内各需 ≥10 条评论：先运行\r\n `analyze --type compare --asin <目标> --competitor <竞品>` 取价，用户确认后再追加 `--confirm`。\r\n 竞品用 `competitors --id <产品id> --add <竞品ASIN>` 绑定后会按周自动采集，\r\n 攒够几周就可以用免费的 `radar --id <产品id>` 看本品 vs 竞品的走势对比。\r\n7. 使用 `reports` / `report --id` 读取已归档报告；**`report --id` 返回 `deltaMd` 时\r\n 必须先讲环比再讲正文**——用户最想知道的是「跟上次比变了什么」。\r\n `_deltaStatus=generating` 表示还在后台算，等十几秒重跑即可，不是失败。\r\n `export --report-id ` 可导出 Markdown/HTML，`export --asin ` 导出评论 CSV\r\n （付费套餐功能，不扣积点）。\r\n8. 会话开始跑 `check` 之后顺手跑一次 `alerts`：有未读差评预警时主动告诉用户，\r\n 并提议用 `workbench` 定位差评、`advise --review-id ` 生成回复建议（付费，\r\n 同样先报价、用户确认后才 `--confirm`）。\r\n `workbench` 默认按严重度排序，返回里的 `stats` 给出「待处理 / 本周新增 /\r\n 本月已处理」——**汇报时先说这三个数字再说具体条目**，让用户看见自己在推进。\r\n9. 用户问「哪几条差评最伤转化」用 `reviews --asin --stars negative --sort helpful`\r\n （高赞差评榜，免费）：买家在商品页最先看到的就是这几条。带图差评加 `--with-images`。\r\n10. 用户问「行业/类目里表现如何」用免费的 `benchmark --asin `；要看类目排行\r\n （`leaderboard`）时先报价，确认后 `--confirm`（类目无数据不收费）。\r\n\r\n## 商品运营工作流（1.4.1）\r\n\r\n- 用户要求 ASIN 运营体检、Listing 健康检查、商品页审查、评论转行动或运营周报时，\r\n 使用 `operations` 命令；不得把旧 VOC、alerts 或普通 reports 冒充商品运营结果。\r\n- 先运行 `operations capabilities`，只使用服务端返回的 workflow/focus；专属变体包\r\n 还必须遵守根目录 `skill-defaults.json` 的固定 workflow/focus，禁止接收任意 prompt。\r\n- 用 `operations profile` 检查商品字段，再运行 `operations quote`。评论不足时只建议\r\n 用户使用现有 `collect`，不得隐式采集；商品关键字段不足时不得生成或扣点。\r\n- 未得到用户明确扣点授权时，只返回 quote。授权后使用 quote 返回的完整 request 和同一\r\n `requestId` 执行 `operations run --confirm`，不得换 requestId 或修改 workflow/focus。\r\n- 流中断或超时后绝不直接重跑。必须运行\r\n `operations status --request-id <原requestId>` 精确查询；completed 时使用其 reportId，\r\n quoted/running/frozen 时继续等待，released/failed 时说明错误并请求用户决定下一步。\r\n\r\n## 商品变化监控工作流（1.4.1）\r\n\r\n- `watch` 是独立的确定性监控管理入口，不是付费 `operations` workflow。使用前先运行\r\n `operations capabilities`，确认当前账户的 `watchEnabled` 为 `true`；开关或灰度未开放时\r\n 必须停止并提示用户，不得回退到其他工作流。\r\n- 本节是 1.4.1 的 CLI 契约说明；对应 Wave E 候选仍为 `planned`，未表示已公开上架或所有账户可用。\r\n- `watch create` 只接受当前账户已订阅的主 ASIN。可选 `--competitor` 仅在该竞品已通过当前用户\r\n 的主品/竞品关系绑定、且站点与主品相同后才允许创建竞品 watch；不得用临时 ASIN、全局商品资料\r\n 或其他参数绕过归属校验。Wave E 的 `competitor-change` listing 仍为 planned，未公开上架。\r\n- `watch list`、`watch digest` 和 `watch events` 是只读操作，可按用户问题直接读取；不得把读取\r\n 结果当成用户同意变更监控。\r\n- `watch create`、`watch pause`、`watch resume` 和 `watch delete` 都是管理动作，只有用户明确\r\n 要求对应动作时才执行；“持续监控指定 ASIN + 周期”可视为明确的 `create` 意图，但“帮我看看”\r\n 或“有什么变化”等表述仍按只读处理。执行 `delete` 前必须向用户复述并核对准确的 `watch-id`；\r\n ID 不明确或目标不唯一时先停止询问。删除只移除该用户的监控关系，不删除共享商品资料、快照、\r\n 评论或历史报告。\r\n- 固定 CLI 入口如下：\r\n\r\n ```bash\r\n python scripts/ari.py watch list\r\n python scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\r\n python scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\r\n python scripts/ari.py watch pause --watch-id \r\n python scripts/ari.py watch resume --watch-id \r\n python scripts/ari.py watch delete --watch-id \r\n python scripts/ari.py watch digest --watch-id --period 7d\r\n python scripts/ari.py watch events --watch-id \r\n ```\r\n\r\n- `create`/`resume` 只使用服务端支持的 `weekly` 或 `daily`；`daily` 受套餐\r\n `dailyProductWatch` 权益限制，Free 不开放自动日扫描。修改周期前先向用户说明套餐额度和\r\n 扫描成本，不能默认开启监控。\r\n- `digest` 只汇总商品快照、确定性 Diff 和已有评论计数，返回 `creditsUsed: 0`；自动扫描和\r\n 事件读取不调用付费 LLM、不扣 AI 积点。它不提供小时级或实时价格、销量、库存、广告、订单\r\n 或真实退货率数据。\r\n- AI 周报仍使用 `operations` 的 `weekly` workflow，必须先报价，只有用户明确确认后才可\r\n `operations run --confirm`；不得把周报混入免费的 `watch digest`。\r\n\r\n站点默认 `amz_us`；可选 `amz_uk/amz_de/amz_jp/amz_ca/amz_fr/amz_es/amz_it`。\r\n`charts` / `deepdive` 的 `--days` 默认 0（全部历史）；传非 0 时图表只覆盖该窗口，\r\n解读占比和趋势必须带上这个窗口说明。\r\n\r\n## 解读纪律\r\n\r\n- 把 API 数字、由数字推导的判断、行动建议明确区分：`📊 数据直读`、`🔍 数据推理`、\r\n `💡 策略建议`。策略建议不得标为数据直读。\r\n- `reviewCount < 50` 时在报告顶部标注小样本提示；单次提及只能作为方向性线索。\r\n- 痛点优先级同时考虑提及频率、低星程度、近期趋势和已验证购买，不凭单条评论下结论。\r\n- 用好评高频表达提炼 Listing 语言，但引用评论原话时保持短句并注明来自评论样本。\r\n- 竞品对比只比较双方 API 均有数据的指标；一方样本不足时明确写“不可比”。\r\n- 报告语言跟随用户；ASIN、VOC、Listing 等术语保留原文。非中文回复时记得传\r\n `--language en` 等，CLI 默认是 `zh`。\r\n\r\n## 报告结构\r\n\r\n按有数据的部分输出：数据概览 → 痛点与低星原因 → 好评与购买动因 → 用户画像与场景 →\r\n趋势 → 竞品差异 → Listing 建议 → 产品改进优先级 → 数据来源与积点用量。\r\n\r\n报告顶部加入：\r\n\r\n> 数据基于 ARI 已采集的 Amazon 评论样本（截至当前查询时间），仅供经营决策参考；\r\n> 小样本或采集窗口有限时应结合更多信源验证。\r\n\r\n结尾列出使用的 CLI 命令、ASIN/站点、样本量、统计窗口（`_window.days`）、报告返回的\r\n`reportId` 与 `creditsUsed`，以及当前余额。**输出含 `reportUrl` 时必须在结尾附上**，\r\n固定文案：「在线查看图表版完整报告 / 导出：」（需登录报告所属账户）。\n\nFile v0.1.1:README.md\n\n# 亚马逊变体分析 · 颜色尺寸口碑对比\n\n颜色尺寸规格口碑对比，揪出拖分变体\n\n> **亚马逊变体分析 · 颜色尺寸口碑对比**\n> 技术名 `amazon-variant-analysis`，ARI 官方出品的 Amazon 评论采集与消费者洞察 Skill，已适配 WorkBuddy。\n> 安装后直接用中文描述需求即可，无需理解 API 或编写代码；所有付费操作都会先报价，\n> 只有你明确确认后才会扣除积点。\n\n## 能做什么\n\n- 订阅 ASIN、采集评论，查看星级 / 关键词 / 趋势 / 流向等免费图表数据。\n- 生成 **VOC**、**深度洞察**、**趋势**、**变体**、**竞品对比** 五类 AI 分析报告。\n- 输出痛点、购买动因、用户画像、使用场景、改进机会与 Listing 建议。\n- **差评预警**（差评突增自动提醒）与**差评工作台**（AI 生成回复/申诉建议）。\n- **行业对标**（类目星级/差评率位置）与付费**类目排行**。\n- 评论一键导出 **CSV**，报告导出 **Markdown / HTML**（付费套餐功能）。\n\n安装后直接以自然语言提需求：\n\n```text\n使用 $amazon-variant-analysis 为 ASIN B0XXXXXXXX 生成 VOC 报告，站点 amz_us，我确认扣积分。\n```\n\n## 前置条件\n\n- **Python 3**（只用标准库，无第三方依赖）。\n- 一个 **ARI API Key**（`ari_live_` 开头）。首次使用运行\n `python scripts/ari.py setup`，在浏览器登录或注册后点一下「授权」，\n Key 会自动写入本机，无需手工复制粘贴。\n 也可在 手动创建。\n\n## 安装到 WorkBuddy\n\n保持文件夹名 `amazon-variant-analysis`，整个放进对应作用域即可：\n\n| 作用域 | 路径 |\n|---|---|\n| 用户级（推荐） | `~/.workbuddy/skills/amazon-variant-analysis/` |\n| 项目级 | `<项目目录>/.workbuddy/skills/amazon-variant-analysis/` |\n\n装好后验证账户与积点余额：\n\n```bash\npython /scripts/ari.py check\n```\n\n> `` 是 WorkBuddy 加载 Skill 时自动替换的目录占位符；直接在终端跑时，\n> 请先进入 Skill 目录，或把它换成实际路径。\n\nKey 运行时从 `ARI_API_KEY` 或 `~/.ari/config.json` 读取——**切勿**提交进仓库，\n也不要把 Key 贴进公开文档或发给他人。\n\n## 命令一览\n\n| Command | 作用 | 扣积点 |\n|---|---|---|\n| `setup` / `configure` | 部署 API Key | 否 |\n| `check` | 账户与余额 | 否 |\n| `products` | 已订阅 ASIN 列表 | 否 |\n| `voc` | 自动采集 + VOC + 归档 + 报告链接 | **是，需 `--confirm`** |\n| `collect` | 提交采集任务 | **是，需 `--confirm`** |\n| `status` | 采集任务进度 | 否 |\n| `reviews` | 读取已采集评论 | 否 |\n| `charts` | 星级 / 趋势 / 关键词 / 流向 | 否 |\n| `quote` | 分析报价 | 否 |\n| `analyze` | voc / insight / trend / variant / compare | **是，需 `--confirm`** |\n| `deepdive` | 产品 + 图表 + 评论 + 报告 + VOC 报价 | 默认否，`--confirm` 才分析 |\n| `reports` / `report` | 历史报告列表 / 详情 | 否 |\n| `alerts` | 差评/星级预警 | 否 |\n| `benchmark` | 类目对标概览 | 否 |\n| `leaderboard` | 类目排行 | **是，需 `--confirm`** |\n| `workbench` | 差评列表 / 建议存档 / 状态流转 | 否 |\n| `advise` | 单条差评 AI 回复建议 | **是，需 `--confirm`** |\n| `export` | 评论 CSV / 报告 MD·HTML 导出 | 否（限付费套餐） |\n\n`python scripts/ari.py --help` 看完整参数。默认站点 `amz_us`，\n另支持 `amz_uk / amz_de / amz_jp / amz_ca / amz_fr / amz_es / amz_it`。\n\n## 扣费保护\n\n采集与 AI 分析消耗积点。付费命令（`voc`、`collect`、`analyze`、付费 `deepdive`）**必须**\n显式追加 `--confirm` 才真正执行，不带时只返回报价。\n\n- **非美国站只能用付费积点。** 采集 `amz_uk` / `amz_de` 等站点时赠送积点不可用，\n 以 `collect` 报价里的 `usableBalance` / `sufficient` 为准，别看账户总余额。\n- **付费命令中断后不要直接重跑。** 出现 `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\n `WAIT_TIMEOUT` 时服务端可能已扣点并归档，先用免费的\n `reports --asin --limit 1` 核对，确认没生成再重试。\n- **聚合命令部分失败体现在最外层。** `charts` / `deepdive` 任一子请求失败时返回\n `success:false` 并附 `failedParts`，成功的部分仍在 `data` 里，只能用这部分。\n\n## 目录结构\n\n```\nSKILL.md # Skill 清单 + 操作指令（WorkBuddy 规范）\nREADME.md # 本文件\n使用说明.md # 中文终端用户指南\nscripts/ari.py # 仅依赖标准库的 CLI\nreferences/reference.md# CLI 与 API 参考（命令 / 字段 / 错误码）\nagents/openai.yaml # 其他客户端的接口元数据（WorkBuddy 不使用，保留以兼容多端）\n```\n\n## 常用入口\n\n- API Key：\n- 充值套餐：\n- 产品管理：\n- 报告中心：\n- 新用户注册即赠积点，免费额度可通过任务中心持续解锁：\n \n\nFile v0.1.1:_meta.json\n\n{\n \"ownerId\": \"kn7d4ekgxgbth42fthnftjf1tn89w6df\",\n \"slug\": \"amazon-variant-analysis\",\n \"version\": \"0.1.1\",\n \"publishedAt\": 1788163213111\n}\n\nFile v0.1.1:references/reference.md\n\n# ARI CLI 与 API 参考\n\n仅在需要命令参数、响应字段或错误处理时读取本文件。\n\nAPI 默认地址：`https://ari.funewa.com`。开发/自建环境覆盖需同时设置\n`ARI_BASE_URL` 与 `ARI_ALLOW_CUSTOM_BASE=1`（缺后者时 CLI 报\n`ARI_CUSTOM_BASE_BLOCKED` 拒绝发请求，防止环境变量注入把带 Key 的请求\n重定向到第三方主机）；`ARI_WEB_URL` 同受此门槛约束，未确认时静默回落官方地址。\n认证头：`Authorization: Bearer ari_live_...`。统一 JSON 信封为\n`{success, code, message, data, error, meta}`；SSE 分析由 CLI 聚合为同类 JSON。\n\n`--compact` 输出单行 JSON，放在子命令前后都可以\n（`ari.py --compact check` 与 `ari.py check --compact` 等价）。\n\n## 版本与更新\n\nCLI 在 User-Agent 里带自身版本（`ARI-Review-Skill/`，与 `_meta.json` 一致）。\n服务端在每个 API Key 响应上回 `X-ARI-Skill-Latest` / `X-ARI-Skill-Update-Url`；\n本地版本更旧时，**任意命令**的输出都会多出一个顶层 `update` 字段：\n\n```json\n{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}\n```\n\n`check` 还会额外读取免认证的 `/api/v1/public/config`，把完整的\n`release: {latest, minSupported, url, notes}` 一并返回——Key 失效时也能拿到升级入口。\n\n升级一律由用户通过原安装渠道完成。**CLI 不会下载或执行任何远端代码**，\n也不要让 agent 代劳去取\"新版文件\"运行。\n\n## 用户入口\n\n- API Key：\n- 充值/套餐：\n- 产品管理：\n- 报告中心：\n\n## CLI 命令\n\n| 命令 | API | 是否可能扣点 |\n|---|---|---|\n| `setup` | auth/device/start + poll（免认证），浏览器授权后自动保存 Key | 否 |\n| `configure` | 本地保存 Key | 否 |\n| `check` | user/me + credits/balance | 否 |\n| `products` | asins | 否 |\n| `schedule` | asins（`--set`: asins/{id}/schedule） | 否（设置免费；采集本身按页扣点） |\n| `competitors` | asins/{id}/competitors（GET/POST/DELETE） | 否（竞品加入后按周自动采集，那部分按页扣点） |\n| `radar` | asins/{id}/radar | 否（纯 SQL；套餐未开放时 403） |\n| `voc` | pricing + balance + collection/submit/status + analysis/voc + reports | 是；必须 `--confirm` |\n| `collect` | billing/pricing + credits/balance + collection/submit | 是；必须 `--confirm` |\n| `status` | collection/status/{taskId} | 否 |\n| `reviews` | reviews | 否 |\n| `charts` | charts/stars·trend·keywords·flow | 否 |\n| `quote` | analysis/quote | 否 |\n| `operations capabilities` | product-operations/capabilities | 否 |\n| `operations profile` | product-operations/profile | 否 |\n| `operations quote` | product-operations/quote | 否 |\n| `operations run` | product-operations/quote + run（SSE） | 是；必须 `--confirm` |\n| `operations status` | product-operations/runs/{requestId} | 否 |\n| `watch list` | product-operations/watches（GET） | 否 |\n| `watch create` | product-operations/watches（POST） | 否；受 watch 灰度与套餐额度限制 |\n| `watch pause` / `watch resume` | product-operations/watches/{id}（PUT） | 否；只改变监控状态 |\n| `watch delete` | product-operations/watches/{id}（DELETE） | 否；不删除商品资料、评论或历史报告 |\n| `watch digest` | product-operations/watch-digest（GET） | 否；确定性摘要，`creditsUsed: 0` |\n| `watch events` | product-operations/events（GET） | 否；读取确定性变化事件 |\n| `analyze` | analysis/voc·insight·trend·variant·compare | 是；必须 `--confirm` |\n| `deepdive` | products + charts + reviews + reports + VOC quote/analysis | 默认否；`--confirm` 才分析 |\n| `reports` / `report` | reports | 否 |\n| `alerts` | alerts（`--mark-read` 时 alerts/read） | 否 |\n| `benchmark` | benchmark | 否 |\n| `leaderboard` | billing/pricing + leaderboard | 是；必须 `--confirm`，类目无数据不收费 |\n| `workbench` | workbench/reviews（`--history`: advices；`--set-status`: 状态更新） | 否 |\n| `advise` | analysis/quote + workbench/advise（SSE） | 是；必须 `--confirm` |\n| `export` | export/reviews 或 export/reports/{id}，落盘本地文件 | 否（限付费套餐） |\n| `version` | 无网络请求 | 否 |\n\n运行 `python ari.py <命令> --help` 查看完整参数。\n\n## 持续监控（1.4.1 新增，ARI 的价值主线）\n\nARI 不是一次性查询工具：**开着定期采集，历史才会积累，趋势判断、差评归因和报告环比\n才有意义。** 报告出来后请检查该产品的采集计划，仍是 `manual` 时主动提示用户。\n\n- `schedule`：不带参数=列出全部产品的采集计划，附 `_monitorSummary`\n （monitored / manual / paused 计数）。\n- `schedule --set weekly --asin B0...`（或 `--id <产品id>`）：设为每周自动采集。\n 返回带 `_costNote`，给出该频率的预估月成本——**先把成本告诉用户再执行**。\n `daily` 适合大促期/新品；`weekly` 是长期跟踪的默认；`manual` 只在手动触发时更新。\n- 套餐未开放每日采集时 `--set daily` 返回 403，改用 `weekly`（每周不受任何套餐限制）。\n- 竞品：`competitors --id <产品id> --add B0...` 绑定后按周自动采集；\n `--remove <竞品行id>` 解绑。**竞品只在其主品仍在监控时才会采集**——主品改成\n `manual` 会一并停掉竞品的采集（也就不再产生费用）。\n- `radar --id <产品id> [--weeks 12]`：本品 vs 竞品的周走势（均分 / 新评论量 / 差评量）。\n 免费。曲线随监控时间变长，攒满一个季度才看得出谁在往上走。\n\n## 商品变化监控（watch）\n\n`watch` 使用独立的确定性商品快照和 Diff 管理，不调用付费 LLM。`watch create` 只接受\n属于当前账户且已订阅的主 ASIN；可选 `--competitor` 仅在该竞品已绑定到该主 ASIN、且站点\n相同时创建竞品 watch。不得用临时 ASIN 或全局商品资料绕过归属。Wave E listing 仍为 planned。\n开始前运行：\n\n```bash\npython scripts/ari.py operations capabilities\npython scripts/ari.py watch list\n```\n\n只有返回 `watchEnabled: true` 且账户通过当前灰度/套餐检查时才可继续；否则停止，不要回退到\n`operations` 或用临时 ASIN 绕过权限。\n\n本节是 1.4.1 的 CLI 契约说明；对应 Wave E 候选仍为 `planned`，尚未公开上架，不代表所有账户当前可用。\n\n固定命令与参数：\n\n```bash\npython scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\npython scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\npython scripts/ari.py watch pause --watch-id \npython scripts/ari.py watch resume --watch-id \npython scripts/ari.py watch delete --watch-id \npython scripts/ari.py watch digest --watch-id --period 7d\npython scripts/ari.py watch events --watch-id \n```\n\n`create`/`resume` 的周期只支持 `weekly|daily`；`daily` 由套餐 `dailyProductWatch` 控制，\nFree 不开放自动日扫描。`digest` 只聚合快照、确定性 Diff 和已有评论计数，返回\n`creditsUsed: 0`；自动扫描不调用付费 LLM、不扣 AI 积点。`period` 只支持服务端白名单中的\n`7d|30d`。watch 不承诺小时级或实时价格、销量、库存、广告、订单或真实退货率。\n\nAI 周报是另一条 `weekly` 付费 workflow：必须先 `operations quote`，再由用户明确确认后使用\n同一 `requestId` 执行 `operations run --confirm`。不要把 `watch digest` 当作 AI 周报或反向触发\n付费调用。\n\n## 报告环比\n\n`report --id N` 的返回里：\n\n- `deltaMd`：相比上一份同类型报告的差异摘要（已解决 / 新出现 / 持续存在 / 一句话结论）。\n- `prevReportId` / `prevCreatedAt` / `prevHealthScore`：被对比的那一份。\n- `series`：该序列最近若干份的健康度轨迹（画走势用）。\n- `_deltaStatus`：`ready` 有环比；`generating` 还在后台算（等十几秒重跑，**不是失败**）；\n `none` 这是第一份，没有可比对象。\n\n环比由服务端异步生成，平台承担成本，**不扣用户积点**；套餐权益 `reportDiff` 控制是否开启。\n有 `deltaMd` 时汇报要先讲环比再讲正文——用户最关心的是「跟上次比变了什么」。\n\n## 评论切片（免费）\n\n`reviews` 除了 `--star` / `--query` 还支持：\n\n- `--stars negative|positive`：差评（1-3★）/ 好评（4-5★）分组。\n- `--sort recent|helpful|star_asc|oldest`：`helpful` = 按点赞数排。\n **`--stars negative --sort helpful` 就是高赞差评榜**——买家在商品页最先看到的\n 就是这几条，对转化伤害最大，也是最该优先处理的。\n- `--with-images` / `--vine` / `--purchased`：只看带图 / Vine / 已验证购买。\n\n## 预警、对标与差评工作台\n\n- `alerts [--limit N]`：未读情感预警（差评突增、星级下滑）。`--mark-read` 全部置已读。\n- `benchmark --asin B0...`：免费类目对标概览（本品星级/差评率在类目内的相对位置）。\n- `leaderboard --category <类目> [--by new30|neg_rate|avg_star]`：付费类目排行。\n 无服务端报价握手，CLI 先读 `billing/pricing` 的 `leaderboard` 单价报出，确认后\n `--confirm` 执行；`ARI_INSUFFICIENT_REVIEWS`（类目无数据）不收费。\n- `workbench [--asin] [--site] [--status ...] [--sort severity|recent|arrived] [--new-only]`：\n 免费列差评（返回 `reviewId`）。**默认 `--sort severity`**（高赞与低星优先，\n 最伤转化的排前面）；`--new-only` 只看近 7 天新入库的差评。\n 返回的 `stats` 给出 `pending` / `newThisWeek` / `doneMonth` / `doneTotal`——\n 汇报时先说这几个数字，让用户看见自己在推进而不是面对一个没有尽头的列表。\n 条目上的 `isNew` / `hasImages` / `helpful` 用于判定优先级。\n `--history [--query]` 看 AI 建议存档；`--review-id N --set-status <状态>` 更新处理状态。\n- `advise --review-id N`：为单条差评生成回复/申诉/改进建议（SSE，`data.content` 为\n Markdown）。先按 `quote type=advise` 报价，确认后 `--confirm`。流中断处理同 VOC。\n- `export --asin B0...`（评论 CSV）或 `export --report-id N [--format md|html]`（报告）：\n 文件写到本地，返回 `savedTo/bytes`。Free 套餐会收到 403「导出为付费功能」。\n\n## 采集\n\n`voc B0... --site amz_us` 是默认的用户入口：已有 ≥10 条评论时直接报 VOC 价；\n数据不足时合并报出默认 3 页采集与 VOC 的最大总费用。追加 `--confirm`\n后自动采集、等待、分析、归档，最外层返回 `report.content / reportId / reportUrl`。\n\n`collect --asin B0... --site amz_us --pages 3` 只返回报价；确认后追加\n`--confirm --wait`。请求字段：`asin, site, pageCount, filterByStar, sortBy, alias`。\n\n- `pages`: 1–10，每页约 10 条。\n- `filterByStar`: `all_stars|critical|positive|one_star|two_star|three_star|four_star|five_star`。\n- `sortBy`: `recent|helpful`。\n- **US 以外站点只能使用付费积点**（订阅套餐周期积点与增量包均可），赠送积点\n （注册礼/任务奖励等）被排除。报价字段 `usableBalance` 已按站点算好，\n `sufficient=false` 时不要确认——服务端会直接 402（`ARI_GIFT_CREDITS_US_ONLY`\n 表示总余额够但可用部分是赠送积点）。报价还返回 `planCredits` / `addonCredits` /\n `siteNote` 供解释。\n- `--wait` 轮询 `collection/status`，任务状态只有 `queued|running|done|failed`。\n 瞬时错误会自动重试 3 次；仍失败或超时返回 `WAIT_TIMEOUT`，此时任务仍在后台，\n 用 `status --task ` 查询，**不要重新提交采集**。\n\n## 分析\n\n先调用 `quote --type ...`。报价字段：\n`type, basePrice, price, sampledReviews, totalReviews, balance, sufficient`。\n\n- `voc`: Markdown VOC 报告，SSE 聚合后在 `data.content`，并归档。\n- `insight`: 结构化消费者洞察，`data.result`，同时可能含流式说明 `content`。\n- `trend`: 情感趋势解读，普通 JSON。\n- `variant`: 颜色/尺寸等变体归因，普通 JSON；需足量变体评论。\n- `compare`: 目标与竞品对比，**双方在库内各需 ≥10 条评论**（订阅关系不作强制校验，\n 但 charts/reviews 等 0 积点端点仍要求订阅）。必须传 `--competitor`。\n\nSSE 聚合结果字段：`meta, content, result, reportId, creditsUsed`。\nVOC 服务端在归档后直接于 `done` 事件返回本次 `reportId`；CLI 据此生成\n`reportUrl`。兼容旧服务端时才回查报告列表，并标记 `reportIdSource: \"reports-lookup\"`。\n\nFree 套餐的 AI 分析被强制降级到轻量模型，且受全局限流保护——报告深度与付费档不同，\n必要时说明这一点。\n\n## 免费数据字段\n\n- `products`: `asins[], count, limit`；元素含 `asin, site, alias, collectionStatus,\n lastCollectedAt, reviewCount, variantCount`。**只包含主品**，作为竞品添加的 ASIN\n 不在其中（但它们的 charts/reviews 依然可读）。\n- `reviews`: `reviews[], total, page, pageSize`；每条含标题、正文、星级、日期、\n verifiedPurchase、helpfulCount、attributes。\n- `charts stars`: `stars[1★..5★], total, avgStar`。\n- `charts trend`: 按月评论数、平均星级、低星数。\n- `charts keywords`: `keywords[]`。\n- `charts flow`: 场景/问题等流向结构；为空时不要补造。\n- `charts` / `deepdive` 额外返回 `_window: {days, note}`，`days=0` 表示全部历史；\n 非 0 时所有图表只统计最近 N 天，解读必须带上该窗口。\n\n## 聚合命令的失败语义\n\n`charts` 和 `deepdive` 会并发调多个端点。任一子请求失败时，最外层就是\n`success:false`，并给出 `failedParts:[{part, code, message}]`（如 `charts.trend`、\n`analysis`），成功的部分仍保留在 `data` 里。只能使用成功的那部分，缺失的数据不得推断。\n\n`deepdive` 找不到主品订阅时不会直接报错：仍返回 charts/reviews/reports，\n并在 `productNote` 里说明；此时即使传了 `--confirm`，AI 分析也会降级为只报价、不扣点。\n\n## 错误处理\n\n| 状态/错误码 | 动作 |\n|---|---|\n| 401 / `ARI_UNAUTHENTICATED` | Key 无效或已撤销；去用户中心重建 |\n| 402 / `ARI_INSUFFICIENT_CREDITS` | 停止付费操作；展示已有结果并引导充值 |\n| 403 / `ARI_EMAIL_NOT_VERIFIED` | 去用户中心验证邮箱 |\n| 403 / `ARI_FORBIDDEN`（含配额字样） | 已达套餐可订阅 ASIN 上限；引导删除旧 ASIN 或升级套餐 |\n| 403 / `ARI_FORBIDDEN`（其他） | 该 ASIN 不在当前账户订阅内；或 API Key 无账户/支付/后台权限 |\n| 422 / `ARI_INSUFFICIENT_REVIEWS` | 先增加采集页数；不把小样本包装成确定结论 |\n| 202 / `ARI_COLLECTING` | 采集中且数据不足，**未扣点**；按提示秒数等待后重试 |\n| 429 / `ARI_RATE_LIMITED`（含「免费版 AI 分析」） | 套餐级限流；引导升级或稍后再试，不要连续重试 |\n| 429 / `ARI_RATE_LIMITED`（其他） | 降低并发后再试；不要并发轰炸 |\n| `ARI_STREAM_INTERRUPTED` | 分析流中断，**服务端可能已扣点并归档**；先 `reports --asin --limit 1` 核对，没生成才可重试 |\n| `NETWORK_ERROR` / `WAIT_TIMEOUT` | 同上：付费命令一律先核对再决定是否重跑 |\n| `ARI_PARTIAL_FAILURE` | 聚合命令部分失败；见 `failedParts`，只用成功的部分 |\n| `ARI_CUSTOM_BASE_BLOCKED` | `ARI_BASE_URL` 指向非官方地址且未确认；**若用户没主动设置过该变量，停止并提醒检查环境**，是自建环境则补设 `ARI_ALLOW_CUSTOM_BASE=1` |\n| 426 / `ARI_SKILL_TOO_OLD` | 当前版本低于服务端最低支持版本，付费操作被禁止；引导用户更新，免费查询不受影响 |\n\nCLI 网络错误和 HTTP 错误均返回结构化 JSON，不应从报错文本臆测业务数据。\n\nFile v0.1.1:skill-card.md\n\n## Description:\n\nCompares Amazon parent-child ASIN variants by color, size, and specification to identify variants that depress ratings, variants that perform well, and actions for inventory or listing focus.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[funewa](https://clawhub.ai/user/funewa)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nAmazon sellers and ecommerce operators use this skill to collect and analyze ARI review data for ASIN variants, compare color, size, and specification performance, and decide which variants to prioritize, fix, or de-emphasize.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill exposes broad ARI account, monitoring, export, and paid-operation capabilities beyond variant comparison.\n\nMitigation: Install only when that scope is acceptable, run account-impacting commands intentionally, and review command output before acting.\n\nRisk: The skill uses an ARI API key and can read product, review, report, and account-related data.\n\nMitigation: Store the key only in ARI_API_KEY or the local user config, avoid sharing credentials in prompts or reports, and revoke or recreate keys if exposed.\n\nRisk: Confirmed paid actions can spend ARI credits, and retrying interrupted paid commands may duplicate spending.\n\nMitigation: Require an explicit quote and confirmation step, then check existing reports or operation status before retrying interrupted confirmed commands.\n\nRisk: Exports can write business review or report data to local files.\n\nMitigation: Limit exports to needed data and handle generated CSV, Markdown, or HTML files according to the user's data-handling requirements.\n\n## Reference(s):\n\n- [ARI CLI and API Reference](artifact/references/reference.md)\n- [ARI Web Application](https://ari.funewa.com)\n- [ClawHub Skill Page](https://clawhub.ai/funewa/skills/amazon-variant-analysis)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands; CLI/API responses may include JSON and exported CSV, Markdown, or HTML files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires an ARI API key; paid actions require explicit confirmation before execution.]\n\n## Skill Version(s):\n\n0.1.1 (source: ClawHub release metadata; artifact frontmatter and _meta.json report 1.4.3)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.1:使用说明.md\n\n# ARI Amazon 评论智能助手使用指南\n\nARI Amazon 评论智能助手可以帮助卖家采集和分析 Amazon 评论，快速发现消费者痛点、购买动机、使用场景、竞品差异与 Listing 优化机会。\n\n你可以直接用中文提出需求，不需要理解 API，也不需要编写代码。系统会在付费操作前展示所需积点，只有得到你的明确确认后才会执行。\n\n## 一、直接告诉 AI 你要做什么\n\n在已安装本 Skill 的 AI 客户端中直接输入：\n\n```text\n使用 $amazon-variant-analysis 分析 ASIN B0XXXXXXXX，站点 amz_us，先告诉我需要多少积点，不要直接扣点。\n```\n\n也可以这样说：\n\n```text\n使用 $amazon-variant-analysis 采集 B0XXXXXXXX 的 3 页美国站评论，先报价，等我确认后再执行。\n```\n\n```text\n使用 $amazon-variant-analysis 对比 B0AAAAAAAA 和 B0BBBBBBBB，找出竞品差评、购买动机和 Listing 改进机会。\n```\n\n```text\n使用 $amazon-variant-analysis 看看我有没有差评预警，帮我列出待处理差评并给最严重的一条写回复建议。\n```\n\n```text\n使用 $amazon-variant-analysis 对 B0XXXXXXXX 做类目对标，看它在行业里的星级和差评率位置。\n```\n\n```text\n使用 $amazon-variant-analysis 导出 B0XXXXXXXX 的全部评论为 CSV。\n```\n\n付费采集或 AI 分析都会先报价，只有你明确确认后才会扣除 ARI 积点。\n\n## 二、第一次使用：申请并配置 API Key\n\n**推荐方式（一键授权，无需复制粘贴）**：在 Skill 目录打开终端运行\n\n```bash\npython scripts/ari.py setup\n```\n\n命令会打印一个授权链接。用浏览器打开它，登录（没有账号就先注册并完成邮箱验证），\n点一下「授权」，回到终端等几秒——Key 自动获取并保存，完成。\n\n**手动方式**（授权链接打不开时备用）：\n\n1. 登录 [ARI 用户中心](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)。\n2. 完成邮箱验证。\n3. 在“API Key”区域创建密钥，并立即复制以 `ari_live_` 开头的完整 Key。\n4. 如客户端要求手动配置，请在 Skill 目录打开终端并运行：\n\n```bash\npython scripts/ari.py configure\n```\n\n5. 按提示粘贴 API Key。输入过程不会显示字符，这是正常的。\n6. 验证账户和余额：\n\n```bash\npython scripts/ari.py check\n```\n\nKey 只保存在你的本机用户配置中。请勿把 Key 发给他人、写进截图或放进公开文档。\n\n## 三、命令行完整流程\n\n### 1. 一键生成 VOC 报告（推荐）\n\n```bash\npython scripts/ari.py voc B0XXXXXXXX --site amz_us\n```\n\n该命令一次返回采集 + VOC 的总报价，不扣积点。确认后运行：\n\n```bash\npython scripts/ari.py voc B0XXXXXXXX --site amz_us --confirm\n```\n\n它会自动完成：检查现有评论 → 必要时采集并等待 → 生成 VOC →\n保存到用户中心 → 返回完整报告正文、`reportId` 和 `reportUrl`。\n默认采集 3 页，可用 `--pages 1..10` 调整。\n\n### 2. 单独采集或查看免费数据（高级）\n\n只需采集时：\n\n```bash\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3 --confirm --wait\n```\n\n查看免费数据：\n\n```bash\npython scripts/ari.py reviews --asin B0XXXXXXXX --site amz_us\npython scripts/ari.py charts --asin B0XXXXXXXX --site amz_us\n```\n\n`charts` 会一次返回星级、趋势、关键词和评论流向数据。默认 `--days 0`（全部历史）；\n传 `--days 90` 则所有图表都只统计最近 90 天，看数时请注意这个窗口。\n\n**高赞差评榜**（免费，最该先看的那几条）——买家在商品页最先看到的就是点赞最多的差评：\n\n```bash\npython scripts/ari.py reviews --asin B0XXXXXXXX --stars negative --sort helpful\npython scripts/ari.py reviews --asin B0XXXXXXXX --stars negative --sort helpful --with-images\n```\n\n### 2.5 开启定期监控（**这一步决定了 ARI 对你有多大用**）\n\n不开监控，你的数据就停在最后一次采集那天——趋势图不会往前走，报告也没有环比可比。\n开启后新评论持续进库，采得越久，趋势判断和差评归因越准。\n\n```bash\npython scripts/ari.py schedule # 看看哪些产品还没在监控\npython scripts/ari.py schedule --set weekly --asin B0XXXXXXXX # 设为每周自动采集\npython scripts/ari.py schedule --set manual --asin B0XXXXXXXX # 随时改回手动，不再产生费用\n```\n\n设置本身免费，采集按实际页数扣点。返回里的 `_costNote` 会给出该频率的预估月成本。\n`weekly` 是长期跟踪的默认选择；`daily` 适合大促期或刚上新的款（部分套餐不开放每日）。\n\n开着监控一段时间后，同一个产品再生成报告，`report --id` 会多出一段环比：\n「相比上一份：哪些问题解决了、哪些是新冒出来的、哪些还在恶化」。\n\n### 3. 其他分析类型（高级）\n\n```bash\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us\n```\n\n确认后生成分析：\n\n```bash\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us --confirm\n```\n\n支持的分析类型：\n\n- `voc`：消费者之声综合报告\n- `insight`：痛点、购买动机、画像和场景\n- `trend`：评论与情绪趋势\n- `variant`：颜色、尺寸等变体分析\n- `compare`：目标产品和竞品对比\n\n竞品对比同样是先报价、后确认。先看价：\n\n```bash\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us\n```\n\n确认价格后再加 `--confirm`：\n\n```bash\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us --confirm\n```\n\n两个 ASIN 都需要先完成评论采集，各自至少 10 条评论。\n\n### 4. 商品运营体检与行动报告\n\n先确认账户是否开放运营能力，再检查商品资料：\n\n```bash\npython scripts/ari.py operations capabilities\npython scripts/ari.py operations profile --asin B0XXXXXXXX --site amz_us\n```\n\n通用母版需显式选择服务端支持的 workflow/focus。先报价，不扣点：\n\n```bash\npython scripts/ari.py operations quote --workflow audit --focus full --asin B0XXXXXXXX --site amz_us\n```\n\n用户确认后，复用报价返回的 `requestId` 执行：\n\n```bash\npython scripts/ari.py operations run --workflow audit --focus full --asin B0XXXXXXXX --site amz_us --request-id <原requestId> --confirm\n```\n\n若流中断，不要直接重跑，按原 requestId 免费查询：\n\n```bash\npython scripts/ari.py operations status --request-id <原requestId>\n```\n\n专属运营 Skill 会在 `skill-defaults.json` 固定 workflow/focus，无需也不得自由改写内部 prompt。\n评论不足时仍使用独立的 `collect` 流程；运营命令不会隐式采集。\n\n### 5. 商品变化监控（watch）\n\n`watch` 是独立的确定性商品快照监控，不是付费 AI 分析。`watch create` 只接受账户已订阅\n且仍归属账户的主 ASIN；可选 `--competitor` 仅在该竞品已绑定到该主 ASIN、且站点相同时生效。\n先查看当前账户是否处于 watch 灰度：\n\n```bash\npython scripts/ari.py operations capabilities # 确认返回 watchEnabled: true\npython scripts/ari.py watch list\n```\n\n如果 `watchEnabled` 为 `false`，说明功能开关、套餐或灰度尚未开放；请停止，不要改用其他命令\n冒充监控，也不要用临时 ASIN 或未绑定竞品绕过归属校验。竞品 watch 必须带 `--competitor`，\n且该竞品已绑定到当前用户的主 ASIN、站点相同；Wave E 的 `competitor-change` listing 仍为 planned。\n\n本节记录 1.4.1 的 CLI 契约；对应 Wave E 候选仍为 `planned`，尚未公开上架，不代表所有账户当前可用。\n\n创建和管理监控：\n\n```bash\npython scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\npython scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\npython scripts/ari.py watch pause --watch-id \npython scripts/ari.py watch resume --watch-id \npython scripts/ari.py watch delete --watch-id \n```\n\n周期只支持 `weekly` 和 `daily`。`daily` 受套餐 `dailyProductWatch` 权益限制，Free 不开放\n自动日扫描；创建或修改前先向用户说明套餐额度和扫描成本。暂停后不再调度，删除监控关系不会\n删除商品资料、评论或历史报告。\n\n读取确定性摘要和事件：\n\n```bash\npython scripts/ari.py watch digest --watch-id --period 7d\npython scripts/ari.py watch events --watch-id \n```\n\n`digest` 只基于商品快照、确定性 Diff 和已有评论计数，返回 `creditsUsed: 0`；自动扫描和\n事件读取不调用付费 LLM、不扣 AI 积点。它不承诺小时级或实时价格、销量、库存、广告、订单或\n真实退货率。若需要 AI 解读，仍使用 `operations` 的 `weekly` 工作流，先运行 `operations quote`，\n得到用户明确确认后才用同一 `requestId` 执行 `operations run --confirm`，不要把 AI 周报当成\n免费的 watch digest。\n\n### 6. 差评预警与差评工作台\n\n订阅 ASIN 后服务端会自动监控差评突增、星级下滑，查看预警（免费）：\n\n```bash\npython scripts/ari.py alerts\n```\n\n列出待处理差评（免费，返回每条差评的 reviewId）：\n\n```bash\npython scripts/ari.py workbench --asin B0XXXXXXXX\n```\n\n为某条差评生成 AI 回复/申诉/改进建议（付费，先报价、确认后加 `--confirm`）：\n\n```bash\npython scripts/ari.py advise --review-id 12345 --confirm\n```\n\n### 7. 行业对标与类目排行\n\n免费查看本品在类目里的星级/差评率位置：\n\n```bash\npython scripts/ari.py benchmark --asin B0XXXXXXXX\n```\n\n类目排行为付费查询（先报价，确认后加 `--confirm`；类目无数据不收费）：\n\n```bash\npython scripts/ari.py leaderboard --category \"Kitchen\" --by neg_rate --confirm\n```\n\n**类目雷达**（免费）：把本品和竞品放在同一条时间轴上比走势。先绑定竞品，\n系统会按周自动采集它们的评论，攒几周后走势就出来了：\n\n```bash\npython scripts/ari.py schedule # 拿到本品的产品 id\npython scripts/ari.py competitors --id 123 --add B0COMPETITOR # 绑定竞品（按周自动采集）\npython scripts/ari.py radar --id 123 --weeks 12 # 看 12 周走势对比\n```\n\n竞品只在其主品仍在监控时才会采集——把主品改成 `manual`，竞品的采集和费用一起停。\n### 8. 导出评论与报告（付费套餐功能，不扣积点）\n\n```bash\npython scripts/ari.py export --asin B0XXXXXXXX\npython scripts/ari.py export --report-id 报告ID --format md\n```\n\n评论导出为 CSV，报告可导出 Markdown / HTML，文件保存在当前目录（可用 `--out` 指定路径）。\n\n### 9. 查看历史报告\n\n```bash\npython scripts/ari.py reports\npython scripts/ari.py report --id 报告ID\n```\n\n## 四、常用入口\n\n- 每份生成的报告都带 `reportUrl` 在线链接：登录后可看**图表版完整报告**并导出，\n 比终端里的纯文本丰富得多，推荐收藏。\n- [申请或撤销 API Key](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [充值与套餐](https://ari.funewa.com/zh/billing)\n- [产品管理](https://ari.funewa.com/zh/products)\n- [报告中心](https://ari.funewa.com/zh/reports)\n\n## 五、常见问题\n\n### 提示 API Key 无效\n\nKey 可能被撤销、复制不完整或属于其他账户。前往 ARI 用户中心重新创建，然后再次运行 `configure`。\n\n### 提示邮箱未验证\n\n先在 ARI 用户中心完成邮箱验证，再重新执行命令。\n\n### 提示积点不足\n\n已有的免费数据仍可查看，但不能继续付费采集或分析。前往“充值与套餐”补充积点。\n\n### 余额明明够，采集非美国站却说积点不足\n\n赠送的积点（注册礼、任务奖励、Free 版每月自动发放的那部分）**只能用于美国站**。\n采集 `amz_uk`、`amz_de`、`amz_jp` 等站点需使用付费积点——订阅套餐的周期积点和\n增量包都算。报价里的 `usableBalance` 就是该站点实际可用的数量，`sufficient` 为\n`false` 时请先订阅套餐或购买增量包。\n\n### 提示有新版本 / 提示版本过旧\n\n运行任意命令时，如果输出里出现 `update` 字段，说明服务端有更新的 Skill 版本。\n按提示里的链接，通过你当初安装本 Skill 的渠道更新即可。查看当前版本：\n\n```bash\npython scripts/ari.py check\n```\n\n返回的 `skillVersion` 是本地版本，`release.latest` 是服务端最新版。\n\n如果提示 `ARI_SKILL_TOO_OLD`，说明你的版本存在会导致**重复扣点**的问题，\n服务端已禁止它执行采集和 AI 分析（免费的查询不受影响）。请务必更新后再继续付费操作。\n\n> 出于安全考虑，本 CLI 不会自行下载或运行任何远端文件，更新必须由你手动完成。\n\n### 分析到一半提示“分析流中断”\n\n说明连接断开了，但服务端很可能已经生成完并扣了点。**不要直接重跑**，先查一下：\n\n```bash\npython scripts/ari.py reports --asin B0XXXXXXXX --limit 1\n```\n\n如果最新报告已经出现，直接用 `report --id` 读取即可；确认没有生成，再重新执行分析。\n\n### 为什么命令没有直接执行采集或分析\n\n这是扣费保护。`collect`、`analyze` 和付费 `deepdive` 必须增加 `--confirm` 才会真正执行。\n\n### 如何查看某个命令的全部参数\n\n```bash\npython scripts/ari.py --help\npython scripts/ari.py collect --help\npython scripts/ari.py analyze --help\n```\n\n默认站点为美国站 `amz_us`，还支持 `amz_uk`、`amz_de`、`amz_jp`、`amz_ca`、`amz_fr`、`amz_es` 和 `amz_it`。\n\nFile v0.1.1:agents/openai.yaml\n\ninterface:\n display_name: \"亚马逊变体分析 · 颜色尺寸口碑对比\"\n short_description: \"颜色尺寸规格口碑对比，揪出拖分变体\"\n default_prompt: \"使用 $amazon-variant-analysis 对一个 Amazon ASIN 做变体归因，找出表现最好与最差的变体。\"\n\nArchive v0.1.0: 11 files, 35928 bytes\n\nFiles: _meta.json (142b), agents (0b), agents/openai.yaml (286b), README.md (5348b), references (0b), references/reference.md (9530b), scripts (0b), scripts/ari.py (58007b), skill-card.md (3114b), SKILL.md (7234b), 使用说明.md (8725b)\n\nFile v0.1.0:SKILL.md\n\n---\r\nname: amazon-variant-analysis\r\ndisplay_name: 亚马逊变体分析 · 颜色尺寸口碑对比\r\ndescription: >\r\n 亚马逊变体分析 Skill：对比同一父体下不同颜色、尺寸、规格的口碑差异，\r\n 找出拖累整体评分的问题变体与真正跑量的优势变体，\r\n 为砍变体、调库存、换主推提供依据。Use when the user asks about variant comparison,\r\n size or color issues, parent-child ASIN analysis, 变体分析、颜色尺寸对比、\r\n 子体表现、变体口碑、SKU 对比、问题变体。Requires an ARI API key (ari_live_*).\r\nauthor: ARI (funewa)\r\nversion: \"1.3.0\"\r\nagent_created: true\r\n---\r\n\r\n# 亚马逊变体分析\r\n\r\n## 工具与入口\r\n\r\n- CLI：本 Skill 目录下的 `scripts/ari.py`。在 Skill 根目录执行，例如\r\n `python scripts/ari.py check`；每次会话先跑一次 `check`。\r\n- API 参考：需要字段、命令或错误码时读取 `references/reference.md`。\r\n- API Key：首次使用运行 `python scripts/ari.py setup`——它会给出一个授权链接，\r\n 用户在浏览器登录（或注册）后点一下「授权」，Key 自动获取并保存到本机，无需复制粘贴。\r\n 也可用环境变量 `ARI_API_KEY`，或 `python scripts/ari.py configure` 手动粘贴。\r\n `setup` 期间把命令打印的授权链接原样转告用户，等待命令自行完成；**不要**替用户注册或登录。\r\n- 申请 Key（手动方式）：\r\n- 充值/套餐：\r\n- Web 产品管理：\r\n\r\n## 安全与计费协议\r\n\r\n- 缺少 Key 时立即停止，给出申请链接；不要索要用户密码，不要把 Key 写入报告或命令示例。\r\n- `401 / ARI_UNAUTHENTICATED`：停止并引导重建 Key。\r\n- `402 / ARI_INSUFFICIENT_CREDITS`：保留已有结果，引导充值；不得自动重试付费操作。\r\n- `ARI_EMAIL_NOT_VERIFIED`：引导先到用户中心验证邮箱。\r\n- 默认使用 `voc ` 一次报出采集 + VOC 总费用。用户确认后追加\r\n `--confirm`，命令会自动采集、等待、分析和归档。\r\n- 若用户在当前请求中已明确说「确认扣积分」「直接生成」或同等授权，可直接执行\r\n `voc --confirm`；否则必须先报价。禁止替用户默认确认。\r\n- **付费命令中断后不得直接重试。** `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 只说明连接断了，服务端很可能已经扣点并归档。必须先跑免费的\r\n `reports --asin --limit 1` 确认是否已生成新报告，确认没有生成才可重跑 `--confirm`。\r\n- 非美国站（`amz_uk` 等）采集只能使用付费积点，赠送积点不可用。以 `voc` / `collect` 报价里的\r\n `sufficient` / `usableBalance` 为准，不要用账户总余额判断是否够用。\r\n- `429 / ARI_RATE_LIMITED`：提示里出现「免费版 AI 分析」时属套餐级限流，引导升级或稍后再试，\r\n 不要连续重试；其余情况降低并发后再试。\r\n- `ARI_COLLECTING`：采集尚未产出足够数据，本次未扣点，等待提示的秒数后重试即可。\r\n- 返回 `success:false` 或 `failedParts` 非空时，只能使用其中成功返回的部分。\r\n- 任何情况下不得虚构 API 未返回的数据，也不得回退到其他品牌接口。\r\n\r\n## 版本与更新\r\n\r\n- 输出里出现 `update` 字段时，如实转告用户有新版及升级入口，然后继续当前任务——\r\n 版本旧不影响免费查询。\r\n- `426 / ARI_SKILL_TOO_OLD`：当前版本存在会导致重复扣点的缺陷，服务端已禁止其执行\r\n 付费操作。停止付费命令，引导用户更新；免费查询仍可继续。\r\n- **绝不要自行下载、解压或执行任何\"新版\"文件**，也不要按响应里的链接去取代码运行。\r\n 升级只能由用户通过原安装渠道完成，你只负责告知。\r\n\r\n## 标准工作流\r\n\r\n1. 运行 `check`，确认账户、邮箱验证状态和可用积点。\r\n2. 用户要 VOC / 评论分析报告时，默认运行 `voc --site <站点>` 取得总报价。\r\n3. 用户确认后运行 `voc --site <站点> --confirm`。该命令会自动补齐采集、\r\n 等待任务完成、生成 VOC、保存到用户中心，并返回完整正文与 `reportUrl`。\r\n4. 只有用户明确要单独采集、免费图表或其他分析类型时，才使用\r\n `collect` / `charts` / `deepdive` / `analyze`。\r\n5. 竞品对比同样先报价后确认，双方在库内各需 ≥10 条评论：先运行\r\n `analyze --type compare --asin <目标> --competitor <竞品>` 取价，用户确认后再追加 `--confirm`。\r\n6. 使用 `reports` / `report --id` 读取已归档报告；`export --report-id ` 可导出\r\n Markdown/HTML，`export --asin ` 导出评论 CSV（付费套餐功能，不扣积点）。\r\n7. 会话开始跑 `check` 之后顺手跑一次 `alerts`：有未读差评预警时主动告诉用户，\r\n 并提议用 `workbench` 定位差评、`advise --review-id ` 生成回复建议（付费，\r\n 同样先报价、用户确认后才 `--confirm`）。\r\n8. 用户问「行业/类目里表现如何」用免费的 `benchmark --asin `；要看类目排行\r\n （`leaderboard`）时先报价，确认后 `--confirm`（类目无数据不收费）。\r\n\r\n站点默认 `amz_us`；可选 `amz_uk/amz_de/amz_jp/amz_ca/amz_fr/amz_es/amz_it`。\r\n`charts` / `deepdive` 的 `--days` 默认 0（全部历史）；传非 0 时图表只覆盖该窗口，\r\n解读占比和趋势必须带上这个窗口说明。\r\n\r\n## 解读纪律\r\n\r\n- 把 API 数字、由数字推导的判断、行动建议明确区分：`📊 数据直读`、`🔍 数据推理`、\r\n `💡 策略建议`。策略建议不得标为数据直读。\r\n- `reviewCount < 50` 时在报告顶部标注小样本提示；单次提及只能作为方向性线索。\r\n- 痛点优先级同时考虑提及频率、低星程度、近期趋势和已验证购买，不凭单条评论下结论。\r\n- 用好评高频表达提炼 Listing 语言，但引用评论原话时保持短句并注明来自评论样本。\r\n- 竞品对比只比较双方 API 均有数据的指标；一方样本不足时明确写“不可比”。\r\n- 报告语言跟随用户；ASIN、VOC、Listing 等术语保留原文。非中文回复时记得传\r\n `--language en` 等，CLI 默认是 `zh`。\r\n\r\n## 报告结构\r\n\r\n按有数据的部分输出：数据概览 → 痛点与低星原因 → 好评与购买动因 → 用户画像与场景 →\r\n趋势 → 竞品差异 → Listing 建议 → 产品改进优先级 → 数据来源与积点用量。\r\n\r\n报告顶部加入：\r\n\r\n> 数据基于 ARI 已采集的 Amazon 评论样本（截至当前查询时间），仅供经营决策参考；\r\n> 小样本或采集窗口有限时应结合更多信源验证。\r\n\r\n结尾列出使用的 CLI 命令、ASIN/站点、样本量、统计窗口（`_window.days`）、报告返回的\r\n`reportId` 与 `creditsUsed`，以及当前余额。**输出含 `reportUrl` 时必须在结尾附上**，\r\n固定文案：「在线查看图表版完整报告 / 导出：」（需登录报告所属账户）。\n\nFile v0.1.0:README.md\n\n# 亚马逊变体分析 · 颜色尺寸口碑对比\r\n\r\n颜色尺寸规格口碑对比，揪出拖分变体\r\n\r\n> **亚马逊变体分析 · 颜色尺寸口碑对比**\r\n> 技术名 `amazon-variant-analysis`，ARI 官方出品的 Amazon 评论采集与消费者洞察 Skill，已适配 WorkBuddy。\r\n> 安装后直接用中文描述需求即可，无需理解 API 或编写代码；所有付费操作都会先报价，\r\n> 只有你明确确认后才会扣除积点。\r\n\r\n## 能做什么\r\n\r\n- 订阅 ASIN、采集评论，查看星级 / 关键词 / 趋势 / 流向等免费图表数据。\r\n- 生成 **VOC**、**深度洞察**、**趋势**、**变体**、**竞品对比** 五类 AI 分析报告。\r\n- 输出痛点、购买动因、用户画像、使用场景、改进机会与 Listing 建议。\r\n- **差评预警**（差评突增自动提醒）与**差评工作台**（AI 生成回复/申诉建议）。\r\n- **行业对标**（类目星级/差评率位置）与付费**类目排行**。\r\n- 评论一键导出 **CSV**，报告导出 **Markdown / HTML**（付费套餐功能）。\r\n\r\n安装后直接以自然语言提需求：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 为 ASIN B0XXXXXXXX 生成 VOC 报告，站点 amz_us，我确认扣积分。\r\n```\r\n\r\n## 前置条件\r\n\r\n- **Python 3**（只用标准库，无第三方依赖）。\r\n- 一个 **ARI API Key**（`ari_live_` 开头）。首次使用运行\r\n `python scripts/ari.py setup`，在浏览器登录或注册后点一下「授权」，\r\n Key 会自动写入本机，无需手工复制粘贴。\r\n 也可在 手动创建。\r\n\r\n## 安装到 WorkBuddy\r\n\r\n保持文件夹名 `amazon-variant-analysis`，整个放进对应作用域即可：\r\n\r\n| 作用域 | 路径 |\r\n|---|---|\r\n| 用户级（推荐） | `~/.workbuddy/skills/amazon-variant-analysis/` |\r\n| 项目级 | `<项目目录>/.workbuddy/skills/amazon-variant-analysis/` |\r\n\r\n装好后验证账户与积点余额：\r\n\r\n```bash\r\npython /scripts/ari.py check\r\n```\r\n\r\n> `` 是 WorkBuddy 加载 Skill 时自动替换的目录占位符；直接在终端跑时，\r\n> 请先进入 Skill 目录，或把它换成实际路径。\r\n\r\nKey 运行时从 `ARI_API_KEY` 或 `~/.ari/config.json` 读取——**切勿**提交进仓库，\r\n也不要把 Key 贴进公开文档或发给他人。\r\n\r\n## 命令一览\r\n\r\n| Command | 作用 | 扣积点 |\r\n|---|---|---|\r\n| `setup` / `configure` | 部署 API Key | 否 |\r\n| `check` | 账户与余额 | 否 |\r\n| `products` | 已订阅 ASIN 列表 | 否 |\r\n| `voc` | 自动采集 + VOC + 归档 + 报告链接 | **是，需 `--confirm`** |\r\n| `collect` | 提交采集任务 | **是，需 `--confirm`** |\r\n| `status` | 采集任务进度 | 否 |\r\n| `reviews` | 读取已采集评论 | 否 |\r\n| `charts` | 星级 / 趋势 / 关键词 / 流向 | 否 |\r\n| `quote` | 分析报价 | 否 |\r\n| `analyze` | voc / insight / trend / variant / compare | **是，需 `--confirm`** |\r\n| `deepdive` | 产品 + 图表 + 评论 + 报告 + VOC 报价 | 默认否，`--confirm` 才分析 |\r\n| `reports` / `report` | 历史报告列表 / 详情 | 否 |\r\n| `alerts` | 差评/星级预警 | 否 |\r\n| `benchmark` | 类目对标概览 | 否 |\r\n| `leaderboard` | 类目排行 | **是，需 `--confirm`** |\r\n| `workbench` | 差评列表 / 建议存档 / 状态流转 | 否 |\r\n| `advise` | 单条差评 AI 回复建议 | **是，需 `--confirm`** |\r\n| `export` | 评论 CSV / 报告 MD·HTML 导出 | 否（限付费套餐） |\r\n\r\n`python scripts/ari.py --help` 看完整参数。默认站点 `amz_us`，\r\n另支持 `amz_uk / amz_de / amz_jp / amz_ca / amz_fr / amz_es / amz_it`。\r\n\r\n## 扣费保护\r\n\r\n采集与 AI 分析消耗积点。付费命令（`voc`、`collect`、`analyze`、付费 `deepdive`）**必须**\r\n显式追加 `--confirm` 才真正执行，不带时只返回报价。\r\n\r\n- **非美国站只能用付费积点。** 采集 `amz_uk` / `amz_de` 等站点时赠送积点不可用，\r\n 以 `collect` 报价里的 `usableBalance` / `sufficient` 为准，别看账户总余额。\r\n- **付费命令中断后不要直接重跑。** 出现 `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 时服务端可能已扣点并归档，先用免费的\r\n `reports --asin --limit 1` 核对，确认没生成再重试。\r\n- **聚合命令部分失败体现在最外层。** `charts` / `deepdive` 任一子请求失败时返回\r\n `success:false` 并附 `failedParts`，成功的部分仍在 `data` 里，只能用这部分。\r\n\r\n## 目录结构\r\n\r\n```\r\nSKILL.md # Skill 清单 + 操作指令（WorkBuddy 规范）\r\nREADME.md # 本文件\r\n使用说明.md # 中文终端用户指南\r\nscripts/ari.py # 仅依赖标准库的 CLI\r\nreferences/reference.md# CLI 与 API 参考（命令 / 字段 / 错误码）\r\nagents/openai.yaml # 其他客户端的接口元数据（WorkBuddy 不使用，保留以兼容多端）\r\n```\r\n\r\n## 常用入口\r\n\r\n- API Key：\r\n- 充值套餐：\r\n- 产品管理：\r\n- 报告中心：\r\n- 新用户注册即赠积点，免费额度可通过任务中心持续解锁：\r\n \n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7d4ekgxgbth42fthnftjf1tn89w6df\",\n \"slug\": \"amazon-variant-analysis\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1786539783526\n}\n\nFile v0.1.0:references/reference.md\n\n# ARI CLI 与 API 参考\r\n\r\n仅在需要命令参数、响应字段或错误处理时读取本文件。\r\n\r\nAPI 默认地址：`https://ari.funewa.com`（开发环境可用 `ARI_BASE_URL` 覆盖）。\r\n认证头：`Authorization: Bearer ari_live_...`。统一 JSON 信封为\r\n`{success, code, message, data, error, meta}`；SSE 分析由 CLI 聚合为同类 JSON。\r\n\r\n`--compact` 输出单行 JSON，放在子命令前后都可以\r\n（`ari.py --compact check` 与 `ari.py check --compact` 等价）。\r\n\r\n## 版本与更新\r\n\r\nCLI 在 User-Agent 里带自身版本（`ARI-Review-Skill/`，与 `_meta.json` 一致）。\r\n服务端在每个 API Key 响应上回 `X-ARI-Skill-Latest` / `X-ARI-Skill-Update-Url`；\r\n本地版本更旧时，**任意命令**的输出都会多出一个顶层 `update` 字段：\r\n\r\n```json\r\n{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}\r\n```\r\n\r\n`check` 还会额外读取免认证的 `/api/v1/public/config`，把完整的\r\n`release: {latest, minSupported, url, notes}` 一并返回——Key 失效时也能拿到升级入口。\r\n\r\n升级一律由用户通过原安装渠道完成。**CLI 不会下载或执行任何远端代码**，\r\n也不要让 agent 代劳去取\"新版文件\"运行。\r\n\r\n## 用户入口\r\n\r\n- API Key：\r\n- 充值/套餐：\r\n- 产品管理：\r\n- 报告中心：\r\n\r\n## CLI 命令\r\n\r\n| 命令 | API | 是否可能扣点 |\r\n|---|---|---|\r\n| `setup` | auth/device/start + poll（免认证），浏览器授权后自动保存 Key | 否 |\r\n| `configure` | 本地保存 Key | 否 |\r\n| `check` | user/me + credits/balance | 否 |\r\n| `products` | asins | 否 |\r\n| `voc` | pricing + balance + collection/submit/status + analysis/voc + reports | 是；必须 `--confirm` |\r\n| `collect` | billing/pricing + credits/balance + collection/submit | 是；必须 `--confirm` |\r\n| `status` | collection/status/{taskId} | 否 |\r\n| `reviews` | reviews | 否 |\r\n| `charts` | charts/stars·trend·keywords·flow | 否 |\r\n| `quote` | analysis/quote | 否 |\r\n| `analyze` | analysis/voc·insight·trend·variant·compare | 是；必须 `--confirm` |\r\n| `deepdive` | products + charts + reviews + reports + VOC quote/analysis | 默认否；`--confirm` 才分析 |\r\n| `reports` / `report` | reports | 否 |\r\n| `alerts` | alerts（`--mark-read` 时 alerts/read） | 否 |\r\n| `benchmark` | benchmark | 否 |\r\n| `leaderboard` | billing/pricing + leaderboard | 是；必须 `--confirm`，类目无数据不收费 |\r\n| `workbench` | workbench/reviews（`--history`: advices；`--set-status`: 状态更新） | 否 |\r\n| `advise` | analysis/quote + workbench/advise（SSE） | 是；必须 `--confirm` |\r\n| `export` | export/reviews 或 export/reports/{id}，落盘本地文件 | 否（限付费套餐） |\r\n| `version` | 无网络请求 | 否 |\r\n\r\n运行 `python ari.py <命令> --help` 查看完整参数。\r\n\r\n## 预警、对标与差评工作台\r\n\r\n- `alerts [--limit N]`：未读情感预警（差评突增、星级下滑）。`--mark-read` 全部置已读。\r\n- `benchmark --asin B0...`：免费类目对标概览（本品星级/差评率在类目内的相对位置）。\r\n- `leaderboard --category <类目> [--by new30|neg_rate|avg_star]`：付费类目排行。\r\n 无服务端报价握手，CLI 先读 `billing/pricing` 的 `leaderboard` 单价报出，确认后\r\n `--confirm` 执行；`ARI_INSUFFICIENT_REVIEWS`（类目无数据）不收费。\r\n- `workbench [--asin] [--site] [--status pending|contacted|appealed|improving|archived]`：\r\n 免费列差评（返回 `reviewId`）；`--history [--query]` 看 AI 建议存档；\r\n `--review-id N --set-status <状态>` 更新处理状态。\r\n- `advise --review-id N`：为单条差评生成回复/申诉/改进建议（SSE，`data.content` 为\r\n Markdown）。先按 `quote type=advise` 报价，确认后 `--confirm`。流中断处理同 VOC。\r\n- `export --asin B0...`（评论 CSV）或 `export --report-id N [--format md|html]`（报告）：\r\n 文件写到本地，返回 `savedTo/bytes`。Free 套餐会收到 403「导出为付费功能」。\r\n\r\n## 采集\r\n\r\n`voc B0... --site amz_us` 是默认的用户入口：已有 ≥10 条评论时直接报 VOC 价；\r\n数据不足时合并报出默认 3 页采集与 VOC 的最大总费用。追加 `--confirm`\r\n后自动采集、等待、分析、归档，最外层返回 `report.content / reportId / reportUrl`。\r\n\r\n`collect --asin B0... --site amz_us --pages 3` 只返回报价；确认后追加\r\n`--confirm --wait`。请求字段：`asin, site, pageCount, filterByStar, sortBy, alias`。\r\n\r\n- `pages`: 1–10，每页约 10 条。\r\n- `filterByStar`: `all_stars|critical|positive|one_star|two_star|three_star|four_star|five_star`。\r\n- `sortBy`: `recent|helpful`。\r\n- **US 以外站点只能使用付费（addon）积点**，赠送的 plan 积点被排除。报价字段\r\n `usableBalance` 已按站点算好，`sufficient=false` 时不要确认——服务端会直接 402。\r\n 报价还返回 `planCredits` / `addonCredits` / `siteNote` 供解释。\r\n- `--wait` 轮询 `collection/status`，任务状态只有 `queued|running|done|failed`。\r\n 瞬时错误会自动重试 3 次；仍失败或超时返回 `WAIT_TIMEOUT`，此时任务仍在后台，\r\n 用 `status --task ` 查询，**不要重新提交采集**。\r\n\r\n## 分析\r\n\r\n先调用 `quote --type ...`。报价字段：\r\n`type, basePrice, price, sampledReviews, totalReviews, balance, sufficient`。\r\n\r\n- `voc`: Markdown VOC 报告，SSE 聚合后在 `data.content`，并归档。\r\n- `insight`: 结构化消费者洞察，`data.result`，同时可能含流式说明 `content`。\r\n- `trend`: 情感趋势解读，普通 JSON。\r\n- `variant`: 颜色/尺寸等变体归因，普通 JSON；需足量变体评论。\r\n- `compare`: 目标与竞品对比，**双方在库内各需 ≥10 条评论**（订阅关系不作强制校验，\r\n 但 charts/reviews 等 0 积点端点仍要求订阅）。必须传 `--competitor`。\r\n\r\nSSE 聚合结果字段：`meta, content, result, reportId, creditsUsed`。\r\nVOC 服务端在归档后直接于 `done` 事件返回本次 `reportId`；CLI 据此生成\r\n`reportUrl`。兼容旧服务端时才回查报告列表，并标记 `reportIdSource: \"reports-lookup\"`。\r\n\r\nFree 套餐的 AI 分析被强制降级到轻量模型，且受全局限流保护——报告深度与付费档不同，\r\n必要时说明这一点。\r\n\r\n## 免费数据字段\r\n\r\n- `products`: `asins[], count, limit`；元素含 `asin, site, alias, collectionStatus,\r\n lastCollectedAt, reviewCount, variantCount`。**只包含主品**，作为竞品添加的 ASIN\r\n 不在其中（但它们的 charts/reviews 依然可读）。\r\n- `reviews`: `reviews[], total, page, pageSize`；每条含标题、正文、星级、日期、\r\n verifiedPurchase、helpfulCount、attributes。\r\n- `charts stars`: `stars[1★..5★], total, avgStar`。\r\n- `charts trend`: 按月评论数、平均星级、低星数。\r\n- `charts keywords`: `keywords[]`。\r\n- `charts flow`: 场景/问题等流向结构；为空时不要补造。\r\n- `charts` / `deepdive` 额外返回 `_window: {days, note}`，`days=0` 表示全部历史；\r\n 非 0 时所有图表只统计最近 N 天，解读必须带上该窗口。\r\n\r\n## 聚合命令的失败语义\r\n\r\n`charts` 和 `deepdive` 会并发调多个端点。任一子请求失败时，最外层就是\r\n`success:false`，并给出 `failedParts:[{part, code, message}]`（如 `charts.trend`、\r\n`analysis`），成功的部分仍保留在 `data` 里。只能使用成功的那部分，缺失的数据不得推断。\r\n\r\n`deepdive` 找不到主品订阅时不会直接报错：仍返回 charts/reviews/reports，\r\n并在 `productNote` 里说明；此时即使传了 `--confirm`，AI 分析也会降级为只报价、不扣点。\r\n\r\n## 错误处理\r\n\r\n| 状态/错误码 | 动作 |\r\n|---|---|\r\n| 401 / `ARI_UNAUTHENTICATED` | Key 无效或已撤销；去用户中心重建 |\r\n| 402 / `ARI_INSUFFICIENT_CREDITS` | 停止付费操作；展示已有结果并引导充值 |\r\n| 403 / `ARI_EMAIL_NOT_VERIFIED` | 去用户中心验证邮箱 |\r\n| 403 / `ARI_FORBIDDEN`（含配额字样） | 已达套餐可订阅 ASIN 上限；引导删除旧 ASIN 或升级套餐 |\r\n| 403 / `ARI_FORBIDDEN`（其他） | 该 ASIN 不在当前账户订阅内；或 API Key 无账户/支付/后台权限 |\r\n| 422 / `ARI_INSUFFICIENT_REVIEWS` | 先增加采集页数；不把小样本包装成确定结论 |\r\n| 202 / `ARI_COLLECTING` | 采集中且数据不足，**未扣点**；按提示秒数等待后重试 |\r\n| 429 / `ARI_RATE_LIMITED`（含「免费版 AI 分析」） | 套餐级限流；引导升级或稍后再试，不要连续重试 |\r\n| 429 / `ARI_RATE_LIMITED`（其他） | 降低并发后再试；不要并发轰炸 |\r\n| `ARI_STREAM_INTERRUPTED` | 分析流中断，**服务端可能已扣点并归档**；先 `reports --asin --limit 1` 核对，没生成才可重试 |\r\n| `NETWORK_ERROR` / `WAIT_TIMEOUT` | 同上：付费命令一律先核对再决定是否重跑 |\r\n| `ARI_PARTIAL_FAILURE` | 聚合命令部分失败；见 `failedParts`，只用成功的部分 |\r\n| 426 / `ARI_SKILL_TOO_OLD` | 当前版本低于服务端最低支持版本，付费操作被禁止；引导用户更新，免费查询不受影响 |\r\n\r\nCLI 网络错误和 HTTP 错误均返回结构化 JSON，不应从报错文本臆测业务数据。\n\nFile v0.1.0:skill-card.md\n\n## Description:\n\nThis skill uses ARI's Amazon review CLI to compare color, size, and specification variants under a parent ASIN, identify variants that hurt overall ratings, and surface high-performing variants for inventory and listing decisions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[funewa](https://clawhub.ai/user/funewa)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal Amazon sellers, ecommerce operators, and agents acting for those users use this skill to collect and analyze Amazon review data, compare variants or competitors, generate VOC and insight reports, and decide which variants to promote, fix, or de-emphasize.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill's real scope is broader than variant comparison and includes ARI account workflows, exports, alerts, and workbench status updates.\n\nMitigation: Install only when the broader ARI review-intelligence workflow is intended, and review commands such as --mark-read, --set-status, and export before execution.\n\nRisk: ARI API keys can grant access to account data and paid analysis functions.\n\nMitigation: Keep the ARI API key private, use setup/configure or ARI_API_KEY without placing keys in reports or public files, and revoke keys from the ARI account page if exposed.\n\nRisk: Paid collection, AI analysis, leaderboard, and advice commands can spend credits, and retrying interrupted paid flows can cause duplicate charges.\n\nMitigation: Run the quote or preview flow first, add --confirm only after explicit user approval, and check recent reports before retrying interrupted paid commands.\n\nRisk: Changing ARI_BASE_URL can route credentials and requests to a nonstandard endpoint.\n\nMitigation: Avoid setting ARI_BASE_URL except in a trusted development environment.\n\n## Reference(s):\n\n- [ARI CLI and API reference](artifact/references/reference.md)\n- [Server-resolved GitHub provenance](https://github.com/funewa/Amazon-variant-analysis)\n- [ClawHub skill listing](https://clawhub.ai/funewa/skills/amazon-variant-analysis)\n- [ARI API key management](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [ARI billing](https://ari.funewa.com/zh/billing)\n- [ARI reports](https://ari.funewa.com/zh/reports)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown reports, JSON CLI responses, shell command examples, configuration steps, and optional CSV, Markdown, or HTML exports.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires an ARI API key. Some commands can spend ARI credits only after explicit --confirm, and export/configuration commands may write local files.]\n\n## Skill Version(s):\n\n0.1.0 (source: server release metadata; artifact version fields report 1.3.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.0:使用说明.md\n\n# ARI Amazon 评论智能助手使用指南\r\n\r\nARI Amazon 评论智能助手可以帮助卖家采集和分析 Amazon 评论，快速发现消费者痛点、购买动机、使用场景、竞品差异与 Listing 优化机会。\r\n\r\n你可以直接用中文提出需求，不需要理解 API，也不需要编写代码。系统会在付费操作前展示所需积点，只有得到你的明确确认后才会执行。\r\n\r\n## 一、直接告诉 AI 你要做什么\r\n\r\n在已安装本 Skill 的 AI 客户端中直接输入：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 分析 ASIN B0XXXXXXXX，站点 amz_us，先告诉我需要多少积点，不要直接扣点。\r\n```\r\n\r\n也可以这样说：\r\n\r\n```text\r\n使用 $amazon-variant-analysis 采集 B0XXXXXXXX 的 3 页美国站评论，先报价，等我确认后再执行。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 对比 B0AAAAAAAA 和 B0BBBBBBBB，找出竞品差评、购买动机和 Listing 改进机会。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 看看我有没有差评预警，帮我列出待处理差评并给最严重的一条写回复建议。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 对 B0XXXXXXXX 做类目对标，看它在行业里的星级和差评率位置。\r\n```\r\n\r\n```text\r\n使用 $amazon-variant-analysis 导出 B0XXXXXXXX 的全部评论为 CSV。\r\n```\r\n\r\n付费采集或 AI 分析都会先报价，只有你明确确认后才会扣除 ARI 积点。\r\n\r\n## 二、第一次使用：申请并配置 API Key\r\n\r\n**推荐方式（一键授权，无需复制粘贴）**：在 Skill 目录打开终端运行\r\n\r\n```bash\r\npython scripts/ari.py setup\r\n```\r\n\r\n命令会打印一个授权链接。用浏览器打开它，登录（没有账号就先注册并完成邮箱验证），\r\n点一下「授权」，回到终端等几秒——Key 自动获取并保存，完成。\r\n\r\n**手动方式**（授权链接打不开时备用）：\r\n\r\n1. 登录 [ARI 用户中心](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)。\r\n2. 完成邮箱验证。\r\n3. 在“API Key”区域创建密钥，并立即复制以 `ari_live_` 开头的完整 Key。\r\n4. 如客户端要求手动配置，请在 Skill 目录打开终端并运行：\r\n\r\n```bash\r\npython scripts/ari.py configure\r\n```\r\n\r\n5. 按提示粘贴 API Key。输入过程不会显示字符，这是正常的。\r\n6. 验证账户和余额：\r\n\r\n```bash\r\npython scripts/ari.py check\r\n```\r\n\r\nKey 只保存在你的本机用户配置中。请勿把 Key 发给他人、写进截图或放进公开文档。\r\n\r\n## 三、命令行完整流程\r\n\r\n### 1. 一键生成 VOC 报告（推荐）\r\n\r\n```bash\r\npython scripts/ari.py voc B0XXXXXXXX --site amz_us\r\n```\r\n\r\n该命令一次返回采集 + VOC 的总报价，不扣积点。确认后运行：\r\n\r\n```bash\r\npython scripts/ari.py voc B0XXXXXXXX --site amz_us --confirm\r\n```\r\n\r\n它会自动完成：检查现有评论 → 必要时采集并等待 → 生成 VOC →\r\n保存到用户中心 → 返回完整报告正文、`reportId` 和 `reportUrl`。\r\n默认采集 3 页，可用 `--pages 1..10` 调整。\r\n\r\n### 2. 单独采集或查看免费数据（高级）\r\n\r\n只需采集时：\r\n\r\n```bash\r\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3\r\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3 --confirm --wait\r\n```\r\n\r\n查看免费数据：\r\n\r\n```bash\r\npython scripts/ari.py reviews --asin B0XXXXXXXX --site amz_us\r\npython scripts/ari.py charts --asin B0XXXXXXXX --site amz_us\r\n```\r\n\r\n`charts` 会一次返回星级、趋势、关键词和评论流向数据。默认 `--days 0`（全部历史）；\r\n传 `--days 90` 则所有图表都只统计最近 90 天，看数时请注意这个窗口。\r\n\r\n### 3. 其他分析类型（高级）\r\n\r\n```bash\r\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us\r\n```\r\n\r\n确认后生成分析：\r\n\r\n```bash\r\npython scripts/ari.py deepdive --asin B0XXXXXXXX --site amz_us --confirm\r\n```\r\n\r\n支持的分析类型：\r\n\r\n- `voc`：消费者之声综合报告\r\n- `insight`：痛点、购买动机、画像和场景\r\n- `trend`：评论与情绪趋势\r\n- `variant`：颜色、尺寸等变体分析\r\n- `compare`：目标产品和竞品对比\r\n\r\n竞品对比同样是先报价、后确认。先看价：\r\n\r\n```bash\r\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us\r\n```\r\n\r\n确认价格后再加 `--confirm`：\r\n\r\n```bash\r\npython scripts/ari.py analyze --type compare --asin B0AAAAAAAA --competitor B0BBBBBBBB --site amz_us --confirm\r\n```\r\n\r\n两个 ASIN 都需要先完成评论采集，各自至少 10 条评论。\r\n\r\n### 4. 差评预警与差评工作台\r\n\r\n订阅 ASIN 后服务端会自动监控差评突增、星级下滑，查看预警（免费）：\r\n\r\n```bash\r\npython scripts/ari.py alerts\r\n```\r\n\r\n列出待处理差评（免费，返回每条差评的 reviewId）：\r\n\r\n```bash\r\npython scripts/ari.py workbench --asin B0XXXXXXXX\r\n```\r\n\r\n为某条差评生成 AI 回复/申诉/改进建议（付费，先报价、确认后加 `--confirm`）：\r\n\r\n```bash\r\npython scripts/ari.py advise --review-id 12345 --confirm\r\n```\r\n\r\n### 5. 行业对标与类目排行\r\n\r\n免费查看本品在类目里的星级/差评率位置：\r\n\r\n```bash\r\npython scripts/ari.py benchmark --asin B0XXXXXXXX\r\n```\r\n\r\n类目排行为付费查询（先报价，确认后加 `--confirm`；类目无数据不收费）：\r\n\r\n```bash\r\npython scripts/ari.py leaderboard --category \"Kitchen\" --by neg_rate --confirm\r\n```\r\n\r\n### 6. 导出评论与报告（付费套餐功能，不扣积点）\r\n\r\n```bash\r\npython scripts/ari.py export --asin B0XXXXXXXX\r\npython scripts/ari.py export --report-id 报告ID --format md\r\n```\r\n\r\n评论导出为 CSV，报告可导出 Markdown / HTML，文件保存在当前目录（可用 `--out` 指定路径）。\r\n\r\n### 7. 查看历史报告\r\n\r\n```bash\r\npython scripts/ari.py reports\r\npython scripts/ari.py report --id 报告ID\r\n```\r\n\r\n## 四、常用入口\r\n\r\n- 每份生成的报告都带 `reportUrl` 在线链接：登录后可看**图表版完整报告**并导出，\r\n 比终端里的纯文本丰富得多，推荐收藏。\r\n- [申请或撤销 API Key](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\r\n- [充值与套餐](https://ari.funewa.com/zh/billing)\r\n- [产品管理](https://ari.funewa.com/zh/products)\r\n- [报告中心](https://ari.funewa.com/zh/reports)\r\n\r\n## 五、常见问题\r\n\r\n### 提示 API Key 无效\r\n\r\nKey 可能被撤销、复制不完整或属于其他账户。前往 ARI 用户中心重新创建，然后再次运行 `configure`。\r\n\r\n### 提示邮箱未验证\r\n\r\n先在 ARI 用户中心完成邮箱验证，再重新执行命令。\r\n\r\n### 提示积点不足\r\n\r\n已有的免费数据仍可查看，但不能继续付费采集或分析。前往“充值与套餐”补充积点。\r\n\r\n### 余额明明够，采集非美国站却说积点不足\r\n\r\n赠送的积点（每月自动发放的那部分）**只能用于美国站**。采集 `amz_uk`、`amz_de`、\r\n`amz_jp` 等站点只能使用充值获得的付费积点。报价里的 `usableBalance` 就是该站点实际\r\n可用的数量，`sufficient` 为 `false` 时请先充值。\r\n\r\n### 提示有新版本 / 提示版本过旧\r\n\r\n运行任意命令时，如果输出里出现 `update` 字段，说明服务端有更新的 Skill 版本。\r\n按提示里的链接，通过你当初安装本 Skill 的渠道更新即可。查看当前版本：\r\n\r\n```bash\r\npython scripts/ari.py check\r\n```\r\n\r\n返回的 `skillVersion` 是本地版本，`release.latest` 是服务端最新版。\r\n\r\n如果提示 `ARI_SKILL_TOO_OLD`，说明你的版本存在会导致**重复扣点**的问题，\r\n服务端已禁止它执行采集和 AI 分析（免费的查询不受影响）。请务必更新后再继续付费操作。\r\n\r\n> 出于安全考虑，本 CLI 不会自行下载或运行任何远端文件，更新必须由你手动完成。\r\n\r\n### 分析到一半提示“分析流中断”\r\n\r\n说明连接断开了，但服务端很可能已经生成完并扣了点。**不要直接重跑**，先查一下：\r\n\r\n```bash\r\npython scripts/ari.py reports --asin B0XXXXXXXX --limit 1\r\n```\r\n\r\n如果最新报告已经出现，直接用 `report --id` 读取即可；确认没有生成，再重新执行分析。\r\n\r\n### 为什么命令没有直接执行采集或分析\r\n\r\n这是扣费保护。`collect`、`analyze` 和付费 `deepdive` 必须增加 `--confirm` 才会真正执行。\r\n\r\n### 如何查看某个命令的全部参数\r\n\r\n```bash\r\npython scripts/ari.py --help\r\npython scripts/ari.py collect --help\r\npython scripts/ari.py analyze --help\r\n```\r\n\r\n默认站点为美国站 `amz_us`，还支持 `amz_uk`、`amz_de`、`amz_jp`、`amz_ca`、`amz_fr`、`amz_es` 和 `amz_it`。\n\nFile v0.1.0:agents/openai.yaml\n\ninterface:\n display_name: \"亚马逊变体分析 · 颜色尺寸口碑对比\"\n short_description: \"颜色尺寸规格口碑对比，揪出拖分变体\"\n default_prompt: \"使用 $amazon-variant-analysis 对一个 Amazon ASIN 做变体归因，找出表现最好与最差的变体。\"","readmeExcerpt":"Skill: Amazon Voc Owner: funewa Summary: 亚马逊买家之声：评论采集 + VOC 洞察报告 Tags: latest:0.1.4 Version history: v0.1.4 | 2026-09-14T09:36:41.752Z | auto **Skill renamed and expanded from \"amazon-variant-analysis\" to \"amazon-voc\"; major scope upgrade with full VOC analytics and workflow support.** - Renamed skill from “亚马逊变体分析” (amazon-variant-analysis) to “Amazon-VOC”. - Expanded from variant-level comparison to full Amazon VOC","codeSnippets":[],"executableExamples":[{"language":"json","snippet":"{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}"},{"language":"bash","snippet":"python scripts/ari.py operations capabilities\npython scripts/ari.py watch list"},{"language":"bash","snippet":"python scripts/ari.py watch create --asin B0XXXXXXXX --site amz_us --schedule weekly\npython scripts/ari.py watch create --asin B0XXXXXXXX --competitor B0YYYYYYYY --site amz_us --schedule weekly\npython scripts/ari.py watch pause --watch-id \npython scripts/ari.py watch resume --watch-id \npython scripts/ari.py watch delete --watch-id \npython scripts/ari.py watch digest --watch-id --period 7d\npython scripts/ari.py watch events --watch-id "},{"language":"bash","snippet":"python scripts/ari.py voc B0XXXXXXXX --site amz_us"},{"language":"bash","snippet":"python scripts/ari.py voc B0XXXXXXXX --site amz_us --confirm"},{"language":"bash","snippet":"python scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3\npython scripts/ari.py collect --asin B0XXXXXXXX --site amz_us --pages 3 --confirm --wait"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: amazon-voc\r\ndisplay_name: Amazon-VOC\r\ndescription: >\r\n Amazon VOC（买家之声）评论分析 Skill：采集亚马逊评论并生成 VOC 洞察报告，\r\n 提炼差评痛点、购买动因、用户画像、使用场景与 Listing 优化建议，\r\n 支持竞品对比与趋势分析。\r\n 本包同时提供 ARI 完整评论分析能力：订阅 ASIN 并采集评论、浏览与筛选评论、\r\n 查看星级/关键词/趋势与雷达图表、生成 VOC 与深度洞察等分析报告、\r\n 运行商品运营工作流、商品变化监控（watch）、差评预警与差评工作台、\r\n 行业对标与类目排行，并导出评论 CSV 与报告 Markdown/HTML。\r\n Use when the user asks about Amazon VOC, voice of customer,\r\n buyer feedback, review mining, 买家之声、客户之声、VOC 分析、评论挖掘、评论采集、\r\n 消费者反馈、差评分析。\r\n Requires an ARI API key (ari_live_*).\r\nallowed-tools: Bash\r\nauthor: ARI (funewa)\r\nagent_created: true\r\nslug: amazon-voc\r\ndisplayName: Amazon-VOC\r\nversion: 1.4.10\r\nsummary: 亚马逊买家之声：评论采集 + VOC 洞察报告\r\nlicense: MIT\r\n---\r\n\r\n# Amazon-VOC 买家之声\r\n\r\n## 自然语言入口与输出\r\n\r\n- 用户只需表达商品和目标，例如“分析美国站 B0XXXXXXXX 的评论，简要说说主要问题和趋势”。\r\n 从对话中提取 ASIN、站点、范围和输出长度，复用已明确的信息；不要要求用户填写命令、\r\n workflow/focus 或默认页数。无站点信息时默认美国站并说明。\r\n- 用户只问简析时先查看已有评论、图表和历史报告；足够回答就直接简析。数据不足时说明缺口，\r\n 按后续工作流处理必要采集或分析。专用 Skill 以固定入口为准，不转成通用 VOC。\r\n- 没有显式变体采集开关时，不要让用户选择工具无法执行的范围，也不要承诺“只含当前子体”\r\n 或“包含全部变体”。按接口实际返回范围说明限制；范围影响结论时再澄清。\r\n- 简短问题优先输出：数据范围、主要问题与评论依据、趋势判断。样本或时间跨度不足时明确说明，\r\n 不把新入库的旧评论说成新发生的趋势；不强制展开完整报告。\r\n- 安装授权步骤见“使用说明.md”；字段和高级命令按需读取 references/reference.md。\r\n 用户未要求技术细节时，不展示内部任务标识、参数清单或命令日志。\r\n- 费用按下方协议和服务端规则处理；用户明确说“只报价，不执行”时，仅调用免费的 quote\r\n 和必要的 collect 报价，不运行可能免确认执行的 voc/analyze，也不擅自修改账户确认设置。\r\n\r\n## 工具与入口\r\n\r\n- CLI：本 Skill 目录下的 `scripts/ari.py`。在 Skill 根目录执行，例如\r\n `python scripts/ari.py check`；每次会话先跑一次 `check`。\r\n- API 参考：需要字段、命令或错误码时读取 `references/reference.md`。\r\n- API Key：首次使用运行 `python scripts/ari.py setup`——它会给出一个授权链接，\r\n 用户在浏览器登录（或注册）后点一下「授权」，Key 自动获取并保存到本机，无需复制粘贴。\r\n 也可用环境变量 `ARI_API_KEY`，或 `python scripts/ari.py configure` 手动粘贴。\r\n `setup` 期间把命令打印的授权链接原样转告用户，等待命令自行完成；**不要**替用户注册或登录。\r\n- 申请 Key（手动方式）：\r\n- 充值/套餐：\r\n- Web 产品管理：\r\n\r\n## 安全与计费协议\r\n\r\n- 所有 API 请求和授权入口仅支持 `https://ari.funewa.com`，禁止重定向。\r\n `ARI_ENDPOINT_BLOCKED` / `ARI_REDIRECT_BLOCKED` 时停止操作；不要设置其他端点、\r\n 开启旧 `ARI_ALLOW_CUSTOM_BASE` 或关闭 TLS 校验来绕过。详见 references/reference.md。\r\n\r\n- 缺少 Key 时立即停止，给出申请链接；不要索要用户密码，不要把 Key 写入报告或命令示例。\r\n- `401 / ARI_UNAUTHENTICATED`：停止并引导重建 Key。\r\n- `402 / ARI_INSUFFICIENT_CREDITS`：保留已有结果，引导充值；不得自动重试付费操作。\r\n- `ARI_EMAIL_NOT_VERIFIED`：引导先到用户中心验证邮箱。\r\n- VOC 默认使用 voc ，由命令按服务端免确认规则处理总费用；该调用可能直接生成并扣点，\r\n 不能描述为“只报价、不扣点”。返回 confirmationRequired 时必须先报价并等待用户同意。\r\n- 当前请求已有明确扣点授权时可追加 --confirm；不得伪造授权或为了跳过询问改变确认设置。\r\n 专用运营工作流仍遵守自己的报价和确认协议。\r\n- **付费命令中断后不得直接重试。** `ARI_STREAM_INTERRUPTED` / `NETWORK_ERROR` /\r\n `WAIT_TIMEOUT` 只说明连接断了，服务端很可能已经扣点并归档。必须先跑免费的\r\n `reports --asin --limit 1` 确认是否已生成新报告，确认没有生成才可重跑 `--confirm`。\r\n- 非美国站（`amz_uk` 等）采集只能使用付费积点（订阅套餐周期积点与增量包均可），\r\n 赠送积点（注册礼/任务奖励等）不可用。以 `voc` / `collect` 报价里的\r\n `sufficient` / `usableBalance` 为准，不要用账户总余额判断是否够用。\r\n- `429 / ARI_RATE_LIMITED`：提示里出现「免费版 AI 分析」时属套餐级限流，引导升级或稍后再试，\r\n 不要连续重试；其余情况降低并发后再试。\r\n- `ARI_COLLECTING`：采集尚未产出足够数据，本次未扣点，等待提示的秒数后重试即可。\r\n- 返回 `success:false` 或 `failedPart"},{"path":"README.md","content":"# Amazon-VOC\n\n亚马逊买家之声：评论采集 + VOC 洞察报告\n\n## 一句话开始\n\n安装授权后，把下面这句话发到 AI 客户端对话框，替换示例 ASIN 即可：\n\n~~~text\n分析评论，简要说明主要问题和趋势。商品 B0XXXXXXXX（美国站）。\n~~~\n\n示例 ASIN 是占位符。AI 会识别商品、站点和目标，无需填写接口参数。\n客户端未选中时，在问题前加“使用 $amazon-voc”。\n缺少必要资料或目标不唯一时，AI 会说明需要补充什么；专用 Skill 只处理本页对应场景。\n\n## 第一次使用：安装并授权\n\n1. 通过市场安装本 Skill，或使用 ARI 用户中心的安装指令交给 AI 客户端安装。\n2. 对 AI 说：“帮我完成 ARI 授权并检查是否可用。”\n3. 打开 AI 返回的链接，自己登录或注册并授权；无需在聊天中粘贴 API Key。\n4. AI 确认连接、余额和扣点规则后，直接发送你的问题。\n\n需要支持 Skill 和本地 Python 3 的 AI 客户端。安装检查不采集评论、不生成付费报告、不开启监控。\n\n## 会得到什么\n\n- 先回答你提出的问题，附样本范围和评论依据；你说“简短”时先给摘要。\n- 评论分析可提炼痛点、购买动机、场景和改进建议，支持竞品对比及趋势分析。\n- 生成报告后附在线查看链接；已采集评论可导出 CSV，报告可导出 Markdown / HTML，受套餐权益限制。\n- 样本或时间跨度不足时会说明无法判断趋势，不把缺失数据补成结论。\n\n## 费用与数据范围\n\n采集和 AI 分析消耗积点。VOC 等支持免确认的流程命中账户规则时可能直接执行并扣点；\n其余情况先报价、等你同意。免确认不是免费，具体规则与余额可让 AI 查询。\n\n可以直接说“以后每次扣点前先问我”，或“只报价，不执行”。\n持续监控需要单独确认周期和后续采集成本。非美国站采集不能使用赠送积点。\n\n分析与导出基于 ARI 已采集的数据，不保证覆盖 Amazon 上全部评论或全部变体。\n免费读取已有评论、图表和历史报告不扣分析积点。\n执行中断时先查询已有任务或报告，避免重复生成和扣点。\n\n## 高级：手动安装、授权与命令\n\n找到解压后同时包含 SKILL.md 和 scripts/ari.py 的目录，以 SKILL.md 顶部的 name\n作为安装目录名。当前包的 name 是 amazon-voc，WorkBuddy 用户级目录为\n~/.workbuddy/skills/amazon-voc/。版本压缩包的外层目录名不是固定 Skill 名。\n更新已有同名安装时保留本地配置。\n\n在安装目录执行：\n\n~~~bash\npython scripts/ari.py setup\npython scripts/ari.py check\n~~~\n\n日常使用只需自然语言。完整命令、计费规则和故障处理见\n[使用说明](使用说明.md)；集成参数见 [API 参考](references/reference.md)。\n\n- [账号与授权管理](https://ari.funewa.com/zh/account?ui=d47626f#api-keys)\n- [积点与套餐](https://ari.funewa.com/zh/billing)\n- [在线报告](https://ari.funewa.com/zh/reports)\n\n## 连接安全\n\nAPI 与授权入口固定为 https://ari.funewa.com，禁止重定向。生产包不支持自定义端点，ARI_ALLOW_CUSTOM_BASE 不再生效。遇到 ARI_ENDPOINT_BLOCKED 或 ARI_REDIRECT_BLOCKED 时停止操作，清除自定义地址或联系 ARI 支持，不能绕过校验。"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7d4ekgxgbth42fthnftjf1tn89w6df\",\n \"slug\": \"amazon-variant-analysis\",\n \"version\": \"0.1.4\",\n \"publishedAt\": 1789378601752\n}"},{"path":"references/reference.md","content":"# ARI CLI 与 API 参考\n\n仅在需要命令参数、响应字段或错误处理时读取本文件。\n\nAPI 固定地址：`https://ari.funewa.com`，只允许 HTTPS 官方域名与默认端口 443。\n生产发行包不支持自建端点；`ARI_BASE_URL` 设置为其他地址时，在读取 Key 和联网前\n返回 `ARI_ENDPOINT_BLOCKED`。旧 `ARI_ALLOW_CUSTOM_BASE` 不再生效，`ARI_WEB_URL`\n不再改变网页链接。JSON、SSE、下载和设备授权均禁止重定向，返回 `ARI_REDIRECT_BLOCKED`。\n遇到这两类错误应停止操作并清除自定义地址或联系 ARI 支持，不能尝试关闭校验。\n开发测试使用 mock 传输和虚构凭据，不向其他端点发送生产 Key。\n域名严格匹配与系统默认 TLS 证书/主机名校验共同保护连接，不使用 DNS 预查代替 TLS 校验。\n认证头示意：`Authorization: Bearer `，占位符不是可用凭据。统一 JSON 信封为\n`{success, code, message, data, error, meta}`；SSE 分析由 CLI 聚合为同类 JSON。\n\n`--compact` 输出单行 JSON，放在子命令前后都可以\n（`ari.py --compact check` 与 `ari.py check --compact` 等价）。\n\n## 版本与更新\n\nCLI 在 User-Agent 里带自身版本（`ARI-Review-Skill/`，与 `_meta.json` 一致）。\n服务端在每个 API Key 响应上回 `X-ARI-Skill-Latest` / `X-ARI-Skill-Update-Url`；\n本地版本更旧时，**任意命令**的输出都会多出一个顶层 `update` 字段：\n\n```json\n{\"update\": {\"current\": \"1.0.4\", \"latest\": \"1.0.6\", \"url\": \"...\", \"message\": \"...\"}}\n```\n\n`check` 还会额外读取免认证的 `/api/v1/public/config`，把完整的\n`release: {latest, minSupported, url, notes}` 一并返回——Key 失效时也能拿到升级入口。\n\n升级一律由用户通过原安装渠道完成。**CLI 不会下载或执行任何远端代码**，\n也不要让 agent 代劳去取\"新版文件\"运行。\n\n## 用户入口\n\n- API Key：\n- 充值/套餐：\n- 产品管理：\n- 报告中心：\n\n## CLI 命令\n\n1.4.5 的 voc / analyze 可能根据账户免确认规则直接执行并扣点，不能将“不带 --confirm”\n一概解释为“只报价”。用户明确只询价时用免费的 quote；必要的采集费用用 collect\n不带 --confirm 查询。不要为这一次询价修改用户长期确认设置。\n\n\n| 命令 | API | 是否可能扣点 |\n|---|---|---|\n| `setup` | auth/device/start + poll（免认证），浏览器授权后自动保存 Key | 否 |\n| `configure` | 本地保存 Key | 否 |\n| `check` | user/me + credits/balance | 否 |\n| `products` | asins | 否 |\n| `schedule` | asins（`--set`: asins/{id}/schedule） | 否（设置免费；采集本身按页扣点） |\n| `competitors` | asins/{id}/competitors（GET/POST/DELETE） | 否（竞品加入后按周自动采集，那部分按页扣点） |\n| `radar` | asins/{id}/radar | 否（纯 SQL；套餐未开放时 403） |\n| `voc` | pricing + balance + collection/submit/status + analysis/voc + reports | 是；`--confirm` 或服务端免确认规则命中 |\n| `collect` | billing/pricing + credits/balance + collection/submit | 是；必须 `--confirm` |\n| `status` | collection/status/{taskId} | 否 |\n| `reviews` | reviews | 否 |\n| `charts` | charts/stars·trend·keywords·flow | 否 |\n| `quote` | analysis/quote | 否 |\n| `operations capabilities` | product-operations/capabilities | 否 |\n| `operations profile` | product-operations/profile | 否 |\n| `operations quote` | product-operations/quote | 否 |\n| `operations run` | product-operations/quote + run（SSE） | 是；必须 `--confirm` |\n| `operations status` | product-operations/runs/{requestId} | 否 |\n| `watch list` | product-operations/watches（GET） | 否 |\n| `watch create` | product-operations/watches（POST） | 否；受 watch 灰度与套餐额度限制 |\n| `watch pause` / `watch resume` | product-operations/watches/{id}（PUT） | 否；只改变监控状态 |\n| `watch delete` | product-operations/watches/{id}（DELETE） | 否；不删除商品资料、评论或历史报告 |\n| `watch digest` | product-operations/watch-digest（GET） | 否；确定性摘要，`creditsUsed: 0` |\n| `watch events` | product-operations/"},{"path":"CHANGELOG.md","content":"# v1.4.10\r\n\r\n- 修复「声明范围小于实际能力」：44 个专属运营包改为窄版文档，只保留本包固定的\r\n workflow/focus 入口；29 个全功能包改为如实声明完整能力集。不再出现「窄声明配全功能正文」\r\n 或「只声明单点能力、正文却含全部能力」的自相矛盾。\r\n- 全部 73 个包补齐 `allowed-tools: Bash`：本系列只运行 `python scripts/ari.py`，\r\n 不写用户文件、不发任意网络请求、不修改商品页，明确最小工具权限。\r\n- 专属包的自然语言示例改为本场景专属文案，不再复用通用 VOC 提问。\r\n- 清理包内悬空引用：母版正文不再提及仅专属包才生成的约束文件，静态分析不再报\r\n 「引用了包内不存在的产物」。\r\n- 构建期新增三条硬闸：专属包不得出现母版全功能词汇、全功能包必须声明完整能力集、\r\n 文档提到的包内相对路径必须真实存在。命令、字段与计费规则一律不变，不提高最低支持版本。\r\n\r\n# v1.4.9\r\n\r\n- API 请求固定到官方 HTTPS 域名；移除自定义端点双变量绕过，读取 Key 前校验最终地址。\r\n- JSON、SSE、下载与设备授权统一拒绝重定向，安全错误在本地返回且不回显可疑 URL。\r\n- 网页入口固定为官方地址，设备授权链接必须通过域名校验；安全错误中止授权轮询。\r\n- 分发构建增加完整 ARI Key 检查，格式前缀与占位符允许保留，命中时只输出文件位置。\r\n- 新增离线安全回归测试；保留现有报价、扣点确认和报告恢复行为。\n- 通用入口文档不再引用仅专属包才生成的约束文件，避免指向包内不存在的产物。\r\n\r\n# v1.4.8\r\n\r\n- 采集报价改成固定单价口径：报价字段 `credits` = `pricePerPage` × `pages`，附 `pricingNote`；\r\n 不再用 `estimatedCredits` / `estimatedReviews` 这类「预计」措辞（对应字段改为 `credits` / `approxReviews`）。\r\n- `voc --confirm` 的合计字段 `estimatedTotalCredits` 改名 `totalCredits`；余额不足提示去掉「最多」。\r\n- `schedule` 的 `_costNote`：每轮单价写「=」不写「≈」，并说明只按实际采到的页数收费。\r\n- CLI 命令与计费规则不变，不提高最低支持版本。\r\n\r\n# v1.4.7\r\n\r\n- 新增 `topics` 命令：逐条评论话题标签的汇总与单话题详情（趋势 / 原句 / 本品 vs 竞品 / 标签洞察），免费。\r\n- `reviews` 新增 `--topic` 按话题筛，返回行带 `tags[]`（维度 / 话题 / 原句），引用原句不再靠模型复述。\r\n- 标准工作流第 12 条：用户问「抱怨最多的是什么 / 某问题最近变多了吗 / 竞品在这点上如何」先走 `topics`。\r\n- CLI 接口与计费规则延续 v1.4.6，不提高最低支持版本。\r\n\r\n# v1.4.6\r\n\r\n- 用一句自然语言发起评论简析、竞品比较、Listing 优化等任务，优先复用对话中的商品与目标。\r\n- 简短请求优先返回数据范围、问题与评论依据、趋势判断；不强制展示技术日志或完整报告。\r\n- 优先读取已有数据；不追问接口没有提供的变体范围选项，不将新入库的历史评论当成近期趋势。\r\n- 安装说明明确浏览器授权、目录识别、配置保留与连接检查；增加可复制的使用示例。\r\n- 写清账户免确认策略、只报价不执行及单独开启持续监控的边界。\r\n- 延续 v1.4.5 的 CLI 接口和计费规则，本次不提高最低支持版本。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1281,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:39:26.640Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:39:26.640Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T10:42:45.953Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}