前言¶
做亚马逊选品或改款时，评论往往散落在后台和表格里：人工翻差评耗时间，抽样统计又容易漏掉高星里的隐性不满。星图AI·评论洞察把「拉评论 → AI 结构化分析 → 量化问题与趋势」封装成通用 Skill，让 Cursor、Claude Code 等支持 SKILL.md 的 Agent 通过 AstrMap 开放 API 调用同一套能力，而不是每次手写脚本或复制网页结果。
下面介绍这个 Skill 的定位、能力与安装方式；命令与参数以 Skill 包内说明为准。
这是什么¶
星图AI·评论洞察（Skill 标识 astrmap-voc）属于星图AI·客户洞察（VOC）产品线，面向全球电商卖家，用于产品改进、新品开发与市场调研。
在 Agent 侧，它通过 Python 脚本 scripts/api_client.py 调用固定端点 https://api.astrmap.com（不可改配），完成：创建亚马逊评论采集任务、轮询任务状态、拉取 AI 洞察、差评/好评列表、标签分布、代表性评论与趋势统计等。维护者在 SkillHub 上的发布者为 sparkbayes；在 SkillHub 分类为 business-ops，当前公开页显示版本 1.0.6（MIT-0）。
官方 Skill 页：https://api.skillhub.cn/user_ad1cad5b/astrmap-voc。
核心功能¶
以下能力与 Skill 公开说明一致，按「是否需要 Chrome 采集扩展」分层理解。
| 能力 | 需要 Chrome 浏览器扩展在线 | 需要 API Key |
|---|---|---|
| 查询已完成任务的分析结果 | 否 | 是 |
| 创建仅采集任务 | 是 | 是 |
| 创建自动分析任务 | 是 | 是 |
| 增量获取 | 是 | 是 |
| 手动触发分析 | 否 | 是 |
产品侧强调的能力包括：获取亚马逊评论、AI 深度分析差评、精准量化高频问题、挖掘高星隐性差评、生成改进建议、追踪评论趋势、增量更新。Skill 实现上对应多类 api_client.py 动作，例如 get_ai_insights、get_category_tag_distribution、get_basic_statistics、get_negative_reviews、get_trend，以及好评侧 polarity="positive" 的查询。
积分规则（创建/分析类操作前 Skill 要求向用户确认）：自动模式采集后 AI 分析会扣积分；仅采集模式不扣分析积分；增量获取扣积分；查询已完成结果不扣积分。
安装与启用¶
1. 安装 Skill¶
SkillHub（与官方页 user_ad1cad5b/astrmap-voc 对应）
星图官网 Agent 接入说明指向 SkillHub 安装文档。先确保本机有 skillhub CLI（见 https://skillhub.cn/install/skillhub.md），再安装到当前 Agent 的 skills 目录。在 Cursor 中目录一般为 ~/.cursor/skills/：
command -v skillhub && skillhub --version
skillhub install @user_ad1cad5b/astrmap-voc --dir ~/.cursor/skills/
安装后若 Agent 未自动加载新 Skill，按你所用客户端说明重启或刷新技能列表。
secure-skills-cli（Skill 镜像页提供的另一种入口）
npx secure-skills-cli add astrmap-voc
或按 360 安全技能中心页提示：npx secure-skills-cli add sparkbayes/astrmap-voc。不同安装器落盘路径不同，以各 CLI 文档为准。
2. 配置 API Key¶
所有 API 调用需 CUSTOMER_INSIGHTS_API_KEY。推荐写入 shell 配置：
export CUSTOMER_INSIGHTS_API_KEY="your-api-key-here"
在 https://app.astrmap.com/ 登录后，于左下角用户菜单 →「接口密钥」创建并复制 Key。未配置时，Agent 应按 Skill 指引向用户索取，并通过 --api-key 传入后续命令。
3. Python 依赖¶
Skill 元数据要求 Python 包 requests>=2.28.0。在 Skill 目录内通常执行：
pip install -r requirements.txt
典型用法¶
只查已有任务结果（无需采集扩展）¶
适合任务已在星图 Web 或此前流程中跑完的场景：
python scripts/api_client.py --action get_ai_insights --api-key "$CUSTOMER_INSIGHTS_API_KEY" --task-id "TSK_xxx"
python scripts/api_client.py --action get_category_tag_distribution --api-key "$CUSTOMER_INSIGHTS_API_KEY" --task-id "TSK_xxx"
python scripts/api_client.py --action get_negative_reviews --api-key "$CUSTOMER_INSIGHTS_API_KEY" --task-id "TSK_xxx" --page 1 --page-size 20
在对话里可直接描述意图，例如：「查看任务 TSK_xxx 的 AI 洞察与差评 Top 问题。」Agent 按 Skill 工作流检查 Key 后调用上述动作即可。
新建 ASIN 采集并自动分析¶
创建任务前 Skill 要求：检查采集通道（check_device，is_alive=true）、查询积分（get_points）、告知扣费并等待用户确认。
python scripts/api_client.py --action check_device --api-key "$CUSTOMER_INSIGHTS_API_KEY"
python scripts/api_client.py --action create_task --api-key "$CUSTOMER_INSIGHTS_API_KEY" --asin "B09V3KXJPB" --site US
提交后约每 6 分钟轮询 get_task_detail，直至 SUCCESS 再拉取分析结果。站点参数支持 US、CA、UK、DE、FR、IT、ES、JP 等映射。
仅采集、稍后分析时使用 --is-auto false，待状态为 COLLECTED 后执行：
python scripts/api_client.py --action trigger_analysis --api-key "$CUSTOMER_INSIGHTS_API_KEY" --task-id "TSK_xxx"
采集通道未在线时¶
check_device 返回 is_alive=false 时，需安装 AstrMap Chrome 扩展：从 https://www.astrmap.com/#download 按页说明加载扩展，在 Web 端登录 AstrMap，并在 Chrome 登录亚马逊买家账号（Skill 明确建议勿用正在运营的卖家账号），再重新检测。
适用场景与注意¶
适合谁：亚马逊运营、产品经理、需要做竞品评论对照或 VOC 报告的团队；已愿意使用 AstrMap 账号与（如需新建任务）浏览器采集通道的卖家。
限制与坑
- API 仅面向
api.astrmap.com，Key 会发往该服务做认证，勿把 Key 写进公开仓库。 - 新建采集/增量依赖扩展在线；只读历史任务则仅需 Key。
- 创建任务、增量、自动分析涉及积分，Skill 要求先展示余额并确认。
- 好评分析需注意 Skill 文档中的自检项：例如
polarity="positive"结果可能混入低星，代表好评中仍可能有隐性差评表述，宜与差评侧对照阅读。
结尾¶
星图AI·评论洞察（astrmap-voc）把亚马逊评论 VOC 流程收敛为 Agent 可执行的 API 脚本与工作流：查结果轻量，建任务则需 Key、积分与采集通道配合。若你已在用 SkillHub 管理技能，可从官方页安装并配置 CUSTOMER_INSIGHTS_API_KEY 后，用自然语言指定 ASIN 或任务 ID 驱动分析。
官方地址：https://api.skillhub.cn/user_ad1cad5b/astrmap-voc
