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/ 下载并安装 AstrMap 桌面客户端，登录后点击左下角 用户菜单 → API 密钥，创建并复制您的 API 密钥。

重要：若未设置 CUSTOMER_INSIGHTS_API_KEY 或未提供 API 密钥，请先向用户询问：

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

然后通过 --api-key 参数传递给后续所有命令。

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

功能等级

提示：若您仅需查询已完成的分析结果，可直接使用 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：将文件夹移动到“应用程序”目录，右键点击 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"

返回结果示例：{online: true, device_id: "xxx", status: "idle"}

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. 手动触发分析（仅采集模式）

在仅采集模式下（is_auto=false）的任务会在 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)。

使用示例

场景 1：创建新任务

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

场景 2：仅采集模式 + 手动触发分析

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

场景 3：查询已完成任务

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