name: amazon-review-insights

description: 针对全球电商卖家的亚马逊产品评论智能分析工具。核心功能：抓取亚马逊评论、AI驱动的负面评论分析、量化高频问题、挖掘五星好评中的隐藏负面反馈、生成优化建议、追踪评论趋势、支持增量更新。

metadata:

openclaw:

requires:

env:

- CUSTOMER_INSIGHTS_API_KEY

dependencies:

python:

- requests>=2.28.0

AstrMap 评论洞察技能

语言设置

• 若用户输入为英文或非中文内容，回复使用 英文
• 若用户输入为中文，回复使用 中文

配置说明

API 密钥

所有 API 调用均需通过 API 密钥进行身份验证。

注意：API 端点固定为 https://api.astrmap.com，不可更改。

推荐做法：在 ~/.zshrc 或 ~/.bashrc 中设置环境变量：

export CUSTOMER_INSIGHTS_API_KEY="your-api-key-here"

获取 API 密钥方式：前往 [https://www.astrmap.com/](https://www.astrmap.com/) 下载并安装 AstrMap 桌面客户端，登录后点击左下角 用户菜单 → API Keys，创建并复制你的 API 密钥。

重要提示：若未设置 CUSTOMER_INSIGHTS_API_KEY 或未提供密钥，必须先向用户索取：

“请提供你的 AstrMap API Key（下载地址：https://www.astrmap.com/，登录后点击用户菜单 → API Keys 创建）”

后续所有命令请通过 --api-key 参数传入该密钥。

安全提醒：本技能会将 API 密钥发送至 AstrMap 服务器（api.astrmap.com）用于认证。该密钥不会用于访问其他服务。

功能权限等级

提示：若仅需查询已完成的分析结果，可直接使用 API 密钥，无需下载桌面客户端。

桌面客户端要求

创建任务需运行中的 AstrMap 桌面客户端。

当设备离线时（check_device 返回 1001 错误）：

1. 询问用户：“桌面客户端未运行，请确认是否已安装？”
2. 若未安装：询问是否需要协助下载，并引导完成解压与启动
3. 若已安装但未运行：提示用户启动桌面客户端，再重新检查在线状态

桌面客户端下载与安装

1. 获取下载链接

python scripts/api_client.py --action get_download_links

2. 解压注意事项

重要：请勿使用 Windows 自带的解压工具（可能导致异常）。建议使用 7-Zip、WPS 解压等第三方工具。

3. 启动指南

macOS：将文件夹移动至“Applications”目录，右键点击 Astrmap.app → “打开”，若被阻止，请进入“系统设置 → 隐私与安全性 → 通用” → 点击“仍要打开”。

Windows：右键点击 launch.vbs → “使用 PowerShell 运行” 或双击启动。

4. 初始设置

首次启动后：

1. 登录你的 AstrMap 账户
2. 登录你的亚马逊买家账号（不要使用卖家账号）
3. 确保亚马逊访问正常

安全与验证

有关详细的安全验证流程、隐私风险说明、亚马逊账户安全建议及 API 密钥使用安全规范，请阅读 {baseDir}/references/security.md 文件。

依赖项安装

pip install -r requirements.txt

重要说明

积分规则

• 创建任务（自动模式）：免费收集评论，AI 分析消耗积分
• 创建任务（仅收集模式）：免费收集评论，不扣除积分
• 增量获取：获取最新评论并重新分析，扣除积分
• 查询结果：查看已完成结果，不扣除积分

创建任务前提条件（仅限创建任务）

1. AstrMap 桌面客户端已登录
2. 桌面客户端已登录亚马逊买家账号
3. 亚马逊访问正常

查询已完成任务结果无任何限制，可直接调用。

工作流程

调用方式

python scripts/api_client.py --action <action> [--params...]

1. 检查设备在线状态

python scripts/api_client.py --action check_device --api-key "your-key"

返回示例：

{is_alive: true, endpoint_id: "xxx", endpoint_type: "desktop", status: "idle"}

v2.2 版本字段变更：online → is_alive，device_id → endpoint_id，新增 endpoint_type。离线时 is_alive 为 false，endpoint_id / endpoint_type 为 null。

2. 创建任务

注意：创建任务会扣除积分。执行前请告知用户并等待确认：

“即将创建任务。当前积分：{points}。此操作将扣除积分。是否继续？”

创建任务流程：

1. 执行 --action check_device 检查设备在线状态
2. 执行 --action get_points 查询账户积分
3. 告知用户积分消耗情况，等待确认
4. 确认前提条件后，执行 --action create_task --asin <ASIN> --site <site> [--is-auto false]

运行模式说明：

站点映射：US/CA/UK（英文），DE（德语），FR（法语），IT（意大利语），ES（西班牙语），JP（日语）

命令示例：

python scripts/api_client.py --action create_task --api-key "your-key" --asin "B09V3KXJPB" --site US

3. 轮询任务状态

提交任务后，每 6 分钟 轮询一次：

python scripts/api_client.py --action get_task_detail --api-key "your-key" --task-id "TSK_xxx"

状态流转路径：

自动模式（is_auto=true）：PENDING → DISPATCHING → COLLECTING → PROCESSING → ANALYZING → SUCCESS/FAILED/CANCELLED

仅收集模式（is_auto=false）：PENDING → DISPATCHING → COLLECTING → COLLECTED

状态提示信息：

若任务长时间未完成（超过 18 分钟），请提示用户检查桌面客户端是否在线。

4. 获取分析结果

# AI 洞察摘要
python scripts/api_client.py --action get_ai_insights --api-key "your-key" --task-id "TSK_xxx"
# 类别-标签分布
python scripts/api_client.py --action get_category_tag_distribution --api-key "your-key" --task-id "TSK_xxx"
# 基础统计数据
python scripts/api_client.py --action get_basic_statistics --api-key "your-key" --task-id "TSK_xxx"
# 负面评论列表
python scripts/api_client.py --action get_negative_reviews --api-key "your-key" --task-id "TSK_xxx" --page 1 --page-size 20

提示：查询已完成任务结果不消耗积分，且无需前置条件。

5. 增量获取

注意：增量获取会扣除积分。执行前请告知用户并等待确认。

增量获取流程：

1. 检查设备状态与积分余额
2. 告知用户积分消耗，等待确认
3. 执行 --action create_incremental --task-id <task_id>
4. 轮询任务状态（同创建任务流程）

6. 手动触发分析（仅收集模式）

仅收集模式的任务在 COLLECTED 状态停止，需手动触发 AI 分析：

python scripts/api_client.py --action trigger_analysis --api-key "your-key" --task-id "TSK_xxx"

状态流转：COLLECTED → PROCESSING → ANALYZING → SUCCESS

所有可用操作

错误处理

详细 API 文档

如需了解完整的 API 接口文档、请求参数及响应格式，请查阅 [API 参考文档](references/api_reference.md)。

使用示例

场景一：创建新任务

用户：帮我获取并分析 B09V3KXJPB 的评论
AI 代理：
1. 检查 API Key → 若未配置，向用户索取
2. 检查设备状态与积分
3. 告知积分消耗，等待确认
4. 创建任务
5. 每 6 分钟轮询一次状态，实时反馈进度
6. 分析完成后，获取结果

场景二：仅收集模式 + 手动触发分析

用户：帮我只收集评论，暂时不分析
AI 代理：
1. 检查 API Key 与设备状态
2. 创建任务并设置 --is-auto false
3. 轮询状态直至变为 COLLECTED
4. 用户确认后，执行 trigger_analysis（仅需 API Key，无需桌面客户端）

场景三：查询已完成任务

用户：查看 TSK_xxx 的分析结果
AI 代理：
1. 检查 API Key
2. 直接获取分析结果（无需设备或前置条件）