@optima-chat/optima-agent 0.9.16 → 0.9.17

package/.claude/skills/scout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scout
-description: "Interactive Amazon product research consultant with 1688 supplier sourcing and Keepa historical data. Search products, analyze markets, find suppliers (by keyword or image), track price/BSR history, and generate professional reports. ALWAYS use when user asks about: selling products (卖/开店), product ideas (产品/商品), market research (市场/竞品), suppliers (供应商/厂家), sourcing (采购/进货/货源), image search (图片找货/以图搜货/找同款), evaluating business opportunities (生意/创业), product trends (趋势/走势), price history (价格历史/价格变化), BSR ranking (排名/销量排名), product lifecycle (生命周期/增长期/衰退期). Uses 'scout search', 'scout product', 'scout keepa *', 'scout supplier-search', and 'scout supplier-search-image' commands."
+description: "Interactive Amazon product research consultant with 1688 supplier sourcing and Keepa historical data. Search products, analyze markets, deep-dive reviews for pain points, find suppliers (by keyword or image), track price/BSR history, and generate professional reports. ALWAYS use when user asks about: selling products (卖/开店), product ideas (产品/商品), market research (市场/竞品), reviews/pain points (评论/差评/痛点/用户反馈), suppliers (供应商/厂家), sourcing (采购/进货/货源), image search (图片找货/以图搜货/找同款), evaluating business opportunities (生意/创业), product trends (趋势/走势), price history (价格历史/价格变化), BSR ranking (排名/销量排名), product lifecycle (生命周期/增长期/衰退期). Uses 'scout search', 'scout product', 'scout reviews', 'scout keepa *', 'scout supplier-search', and 'scout supplier-search-image' commands."
 ---
 
 # Optima Scout - AI Product Research
@@ -139,7 +139,43 @@ scout product ASIN
 - **Images count** - 7 is standard, fewer = poor optimization
 - **Specifications** - May include BSR in multiple categories
 
-### 3. Search 1688 Suppliers (Keyword): `scout supplier-search`
+### 3. Get Product Reviews: `scout reviews`
+
+Fetch Amazon product reviews with pagination. Use for deep pain-point analysis beyond the 8-13 top_reviews returned by `scout product`.
+
+**Syntax:**
+```bash
+scout reviews ASIN                              # 默认 3 页 (~30 条)
+scout reviews ASIN --pages 10                   # 最多 10 页 (~100 条)
+scout reviews ASIN --star one_star              # 只看 1 星差评
+scout reviews ASIN --all-stars --pages 5        # 每个星级各 5 页 (~250 条)
+scout reviews ASIN --verified                   # 只看 verified purchase
+scout reviews ASIN --sort helpful               # 按 helpful 排序
+```
+
+**Parameters:**
+- `ASIN`: 10-character Amazon product ID
+- `--pages`: Number of pages per request (1-10, default: 3, ~10 reviews/page)
+- `--sort`: `recent` (default) or `helpful`
+- `--star`: Filter by star rating (`one_star` ~ `five_star`)
+- `--all-stars`: Fetch all 5 star ratings in one batch (max ~500 reviews)
+- `--verified`: Only verified purchase reviews
+- `--domain`: Amazon domain code (default: com)
+- `--format`: `json` (default) or `text`
+
+**Returns:**
+- Review list: id, title, body, rating, date, verified, helpful_votes, images
+- Product summary: title, rating, total_ratings, rating_breakdown (percentages)
+
+**When to use:**
+- `scout product` gives 8-13 top_reviews — enough for quick scan
+- `scout reviews` gives 30-500 reviews — use for **deep pain-point analysis**, sentiment clustering, and improvement opportunity identification
+- **痛点分析**：`scout reviews ASIN --star one_star --pages 5` 拉差评做聚类
+- **竞品评论对比**：分别拉两个竞品的差评，找差异化机会
+
+**Cost awareness:** Each page costs ~$0.0075 Apify credits. `--all-stars --pages 10` (~500 reviews) costs ~$0.38.
+
+### 4. Search 1688 Suppliers (Keyword): `scout supplier-search`
 
 Search for suppliers on 1688.com using keywords.
 
@@ -165,7 +201,7 @@ scout supplier-search "KEYWORD" --limit NUMBER
 - Years in business (8+ years = established)
 - Return rate (lower = better, typical: 30-50%)
 
-### 4. Search 1688 Suppliers (Image): `scout supplier-search-image`
+### 5. Search 1688 Suppliers (Image): `scout supplier-search-image`
 
 Search for suppliers on 1688.com using product images - perfect for finding sources for products you see on Amazon, Shopify, or other platforms.
 
@@ -293,37 +329,40 @@ scout keepa tokens
 
 **Phase 2: Deep Dive & Refinement**
 4. **Targeted Analysis** → Based on user feedback, run `scout product` on relevant ASINs
-5. **Historical Trend Analysis** → Run `scout keepa product ASIN1,ASIN2,ASIN3 --stats 180` to get historical data
-6. **Extract Insights** → Combine realtime + historical data:
+5. **Deep Review Analysis** → Run `scout reviews ASIN --star one_star --pages 5` to extract pain points, then `scout reviews ASIN --sort helpful --pages 3` to see most impactful reviews
+6. **Historical Trend Analysis** → Run `scout keepa product ASIN1,ASIN2,ASIN3 --stats 180` to get historical data
+7. **Extract Insights** → Combine realtime + historical + review data:
    - BSR trend → 增长期/成熟期/衰退期？
    - `salesRankDrops30/90` → 估算月销量
    - 价格历史 → 利润空间稳定吗？有价格战吗？
    - 卖家数量变化 → 竞争在加剧吗？
-7. **Iterate & Explore** → User may request different keywords, specific competitor analysis, or alternative product categories
+   - 差评聚类 → 用户核心痛点是什么？能改进吗？
+   - 好评亮点 → 用户最看重什么功能？
+8. **Iterate & Explore** → User may request different keywords, specific competitor analysis, or alternative product categories
 
 **Phase 2.5: Supplier Sourcing (Optional but Recommended)**
-8. **Trigger**: User shows interest in costs/sourcing, or after market validation
+9. **Trigger**: User shows interest in costs/sourcing, or after market validation
    - "成本大概多少？" "批发价怎么样？" "利润空间大吗？"
    - "哪里进货？" "供应商怎么找？"
    - "这个图片能找到货源吗？" "Amazon这个能在1688找到吗？"
 
-9. **Choose search method**:
+10. **Choose search method**:
    - **With image**: `scout supplier-search-image "https://..."` ← More accurate for visual products
    - **With keyword**: `scout supplier-search "产品关键词"`
    - **Best practice**: Try both and compare results
 
-10. **Share Findings**:
+11. **Share Findings**:
     - Wholesale price range (e.g., ¥429-599)
     - MOQ (minimum order quantity)
     - Profit margin calculation: Amazon price ($60-80) - 1688 cost (¥429 ≈ $60) - shipping ($10-15)
     - Supplier quality indicators (years in business, certifications)
 
-11. **Ask**: "要不要我详细分析几个供应商？" or proceed to report
+12. **Ask**: "要不要我详细分析几个供应商？" or proceed to report
 
 **Phase 3: Report Generation (Proactive Suggestion)**
-12. **Gauge Completion** → After sufficient data, suggest: "要不要我整理成一份完整的市场分析报告？"
-13. **Generate Report** → Create comprehensive markdown report with all findings
-14. **Save & Iterate** → Offer to save report and refine based on feedback
+13. **Gauge Completion** → After sufficient data, suggest: "要不要我整理成一份完整的市场分析报告？"
+14. **Generate Report** → Create comprehensive markdown report with all findings
+15. **Save & Iterate** → Offer to save report and refine based on feedback
 
 ---
 
@@ -332,9 +371,10 @@ scout keepa tokens
 When user explicitly requests a report upfront:
 1. Run 3-4 diverse keyword searches
 2. Analyze top 3-5 products with `scout product`
-3. Pull historical trends with `scout keepa product` (batch ASINs)
-4. Search 1688 suppliers (image + keyword)
-5. Generate comprehensive report directly
+3. Deep review analysis: `scout reviews ASIN --star one_star --pages 5` on top competitors
+4. Pull historical trends with `scout keepa product` (batch ASINs)
+5. Search 1688 suppliers (image + keyword)
+6. Generate comprehensive report directly
 
 ### Multi-Keyword Research Strategy
 
@@ -420,10 +460,10 @@ scout product B0788F3R8X
   - Product description completeness
   - A+ content presence
 - ✅ **User Feedback Deep-Dive**
-  - Top 3 positive mentions (from top_reviews)
-  - Top 3 complaints/pain points (from top_reviews)
-  - Improvement opportunities
-  - Common feature requests
+  - Quick scan: `scout product` top_reviews (8-13 条精选)
+  - Deep dive: `scout reviews ASIN --star one_star --pages 5` (差评痛点聚类)
+  - Top 3 positive mentions and top 3 complaints
+  - Improvement opportunities and common feature requests
 - ✅ **Competitive Advantages**
   - Unique selling points in feature_bullets
   - Price positioning vs. competitors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.9.16",
+  "version": "0.9.17",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",