Amazon product review intelligence analysis tool for global e-commerce sellers. Core capabilities:fetch Amazon reviews, AI-powered negative review analysis,...
---
name: amazon-review-insights
description: Amazon product review intelligence analysis tool for global e-commerce sellers. Core capabilities:fetch Amazon reviews, AI-powered negative review analysis, quantify high-frequency issues, discover hidden negative feedback in 5-star reviews, generate improvement suggestions, track review trends, incremental updates.
metadata:
openclaw:
requires:
env:
- CUSTOMER_INSIGHTS_API_KEY
dependencies:
python:
- requests>=2.28.0
---
# AstrMap Review Insights Skill
## Language
- Reply in **English** if user input is in English or non-Chinese (as this is the unified language)
- Reply in **中文** if user input is in Chinese
## Configuration
### API Key
All API calls require an API Key for authentication.
**Note**: The API endpoint is fixed at `https://api.astrmap.com` and is not configurable.
**Recommended**: Set the environment variable in `~/.zshrc` or `~/.bashrc`:
```bash
export CUSTOMER_INSIGHTS_API_KEY="your-api-key-here"
```
> To obtain an API Key: Download and install the AstrMap desktop client from https://www.astrmap.com/, log in, click **User Menu (bottom-left)** → **API Keys**, create and copy your API Key.
**Important**: If `CUSTOMER_INSIGHTS_API_KEY` is not set or no API Key is provided, **ask the user first**:
> "Please provide your AstrMap API Key (download at https://www.astrmap.com/, log in, click User Menu → API Keys to create one)"
>
> Then pass it via `--api-key` parameter for all subsequent commands.
**Security Notice**: This Skill sends the API Key to AstrMap servers (api.astrmap.com) for authentication. The API Key will not be used to access other services.
### Feature Tiers
| Feature | Requires Desktop Client | Requires API Key |
|---------|------------------------|-----------------|
| Query completed analysis results | No | Yes |
| Create collection-only task | Yes (online) | Yes |
| Create auto-analysis task | Yes (online) | Yes |
| Incremental fetch | Yes (online) | Yes |
| Manual trigger analysis | No | Yes |
> Tip: If you only need to query completed analysis results, you can use the API Key directly without downloading the desktop client.
### Desktop Client
Creating tasks requires the AstrMap desktop client running online.
**When device is offline** (`check_device` returns 1001 error):
1. **Ask the user**: "The desktop client is not running. Have you installed it?"
2. **If not installed**: Ask if you should help download, then guide through extraction and startup
3. **If installed but not running**: Prompt user to start the desktop client, then re-check online status
### Desktop Client Download & Installation
#### 1. Get Download Links
```bash
python scripts/api_client.py --action get_download_links
```
#### 2. Extraction Notes
> Important: Do not use Windows built-in extraction tools (may cause issues). Use 7-Zip, WPS Extraction, or similar tools instead.
#### 3. Startup Guide
**macOS**: Move the folder to "Applications" directory, right-click Astrmap.app → "Open", if blocked go to "System Settings → Privacy & Security → General" → "Still open".
**Windows**: Right-click "launch.vbs" → "Run with PowerShell" or double-click to start.
#### 4. Initial Setup
After launching:
1. Log in to your AstrMap account
2. Log in to your Amazon buyer account (do not use your seller account)
3. Ensure Amazon access is working
### Security & Verification
For detailed security verification, privacy risk statement, Amazon account security, and API Key safety guidelines, **read** `{baseDir}/references/security.md`.
### Dependency Installation
```bash
pip install -r requirements.txt
```
## Important Notes
### Points System
- **Create task (auto mode)**: Free review collection, AI analysis deducts points
- **Create task (collection-only mode)**: Free review collection, no point deduction
- **Incremental fetch**: Fetch latest reviews and re-analyze, deducts points
- **Query results**: View completed results, no point deduction
### Prerequisites (only for creating tasks)
1. AstrMap desktop client is logged in
2. Desktop client is logged in to Amazon buyer account
3. Amazon access is working
> Querying completed task results has no restrictions and can be called directly.
## Workflow
### Invocation
```bash
python scripts/api_client.py --action <action> [--params...]
```
### 1. Check Device Online
```bash
python scripts/api_client.py --action check_device --api-key "your-key"
```
Response: `{online: true, device_id: "xxx", status: "idle"}`
### 2. Create Task
> Note: Creating a task deducts points. Before executing, inform the user and wait for confirmation:
> "About to create task. Current points: {points}. This will deduct points. Continue?"
**Create Task Flow**:
1. `--action check_device` → Check device online status
2. `--action get_points` → Check account points
3. **Inform user of point consumption, wait for confirmation**
4. Confirm prerequisites, then `--action create_task --asin <ASIN> --site <site> [--is-auto false]`
**Run Mode**:
| Parameter | Description |
|-----------|-------------|
| `--is-auto true` (default) | Auto mode: automatically trigger AI analysis after collection |
| `--is-auto false` | Collection-only mode: stops at "pending analysis" status |
**Site Mapping**: US/CA/UK(English), DE(German), FR(French), IT(Italian), ES(Spanish), JP(Japanese)
**Command Examples**:
```bash
python scripts/api_client.py --action create_task --api-key "your-key" --asin "B09V3KXJPB" --site US
```
### 3. Poll Task Status
After submission, poll every **6 minutes**:
```bash
python scripts/api_client.py --action get_task_detail --api-key "your-key" --task-id "TSK_xxx"
```
**Status Flow**:
**Auto Mode** (`is_auto=true`): `PENDING` → `DISPATCHING` → `COLLECTING` → `PROCESSING` → `ANALYZING` → `SUCCESS/FAILED/CANCELLED`
**Collection-only Mode** (`is_auto=false`): `PENDING` → `DISPATCHING` → `COLLECTING` → `COLLECTED`
**Status Prompts**:
| Status | User Message |
|--------|-------------|
| PENDING | "Task submitted, waiting for scheduling..." |
| DISPATCHING | "Allocating device..." |
| COLLECTING | "Fetching Amazon review data, please wait (usually 20~120 seconds)" |
| PROCESSING | "Review data fetched, processing..." |
| ANALYZING | "Data processing complete, AI analyzing..." |
| SUCCESS | "Analysis complete! Fetching results..." |
| FAILED | "Task failed. Please check device status and network connection." |
| CANCELLED | "Task cancelled" |
| COLLECTED | "Collection complete! In pending analysis state." |
> If task does not complete after a long time (over 18 minutes), prompt user to check if desktop client is online.
### 4. Get Analysis Results
```bash
# AI Insights Summary
python scripts/api_client.py --action get_ai_insights --api-key "your-key" --task-id "TSK_xxx"
# Category-Tag Distribution
python scripts/api_client.py --action get_category_tag_distribution --api-key "your-key" --task-id "TSK_xxx"
# Basic Statistics
python scripts/api_client.py --action get_basic_statistics --api-key "your-key" --task-id "TSK_xxx"
# Negative Reviews List
python scripts/api_client.py --action get_negative_reviews --api-key "your-key" --task-id "TSK_xxx" --page 1 --page-size 20
```
> Note: Querying completed task results does not deduct points and has no prerequisites.
### 5. Incremental Fetch
> Note: Incremental fetch deducts points. Before executing, inform user and wait for confirmation.
**Incremental Fetch Flow**:
1. Check device and points
2. Inform user of point consumption, wait for confirmation
3. `--action create_incremental --task-id <task_id>`
4. Poll status (same as create task)
### 6. Manual Trigger Analysis (Collection-only Mode)
Tasks in collection-only mode (`is_auto=false`) stop at COLLECTED status, requiring manual AI analysis trigger:
```bash
python scripts/api_client.py --action trigger_analysis --api-key "your-key" --task-id "TSK_xxx"
```
Status flow: `COLLECTED` → `PROCESSING` → `ANALYZING` → `SUCCESS`
## All Available Actions
| action | Description | Required Parameters |
|--------|-------------|-------------------|
| get_download_links | Get desktop client download links | - |
| check_device | Check if device is online | - |
| create_task | Create task | --asin, --site |
| create_incremental | Incremental fetch | --task-id |
| trigger_analysis | Manual trigger analysis | --task-id |
| get_task_detail | Query task details | --task-id |
| get_task_list | Get task list | - |
| get_ai_insights | Get AI insights | --task-id |
| get_basic_statistics | Get basic statistics | --task-id |
| get_representative_reviews | Get representative reviews | --task-id |
| get_category_tag_distribution | Get category-tag distribution | --task-id |
| get_negative_reviews | Get negative reviews list | --task-id |
| get_trend | Get review trends | --task-id |
| get_related_comments | Get comments associated with tag/category | --task-id, --association-type |
| get_comments | Get raw comments | --task-id |
| get_comments_overview | Get comments overview | --task-id |
| get_points | Query points balance | - |
## Error Handling
| Error Code | Description | Handling |
|-----------|-------------|----------|
| 1001 | Device offline | Desktop client not running. Ask if installed; if not, provide download guide |
| 1002 | Insufficient points | Prompt user to recharge at https://www.astrmap.com/ |
| 2001 | Invalid API Key | Check if API Key is correct |
| 2002 | API Key disabled | Prompt user to create new API Key |
| 2003 | API Key expired | Prompt user to create new API Key |
| 2004 | Insufficient permissions | Check API Key permission configuration |
| 2005 | Request rate exceeded | Prompt user to retry later |
| InvalidTaskStatus | Task status is not COLLECTED | Only collection-only tasks with COLLECTED status can trigger analysis |
## Detailed API Documentation
For detailed API endpoint documentation, request parameters, and response formats, see [API Reference](references/api_reference.md).
## Usage Examples
### Scenario 1: Create New Task
```
User: Help me get and analyze reviews for B09V3KXJPB
AI Agent:
1. Check API Key → if not configured, ask user to provide
2. Check device and points
3. Inform point consumption, wait for confirmation
4. Create task
5. Poll status every 6 minutes, provide real-time progress
6. After analysis complete, get results
```
### Scenario 2: Collection-only Mode + Manual Trigger Analysis
```
User: Help me collect reviews only, don't analyze for now
AI Agent:
1. Check API Key and device
2. Create task with --is-auto false
3. Poll status until COLLECTED
4. After user confirms analysis, run trigger_analysis (API Key only, no desktop client required)
```
### Scenario 3: Query Completed Task
```
User: View analysis results for TSK_xxx
AI Agent:
1. Check API Key
2. Get analysis results directly (no device or prerequisites required)
```
don't have the plugin yet? install it then click "run inline in claude" again.