@optima-chat/optima-agent 0.9.7 → 0.9.8

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

@@ -1,462 +1,462 @@
----
-name: scout
-description: "Interactive Amazon product research consultant with 1688 supplier sourcing. Search products, analyze markets, find suppliers (by keyword or image), and generate professional reports. ALWAYS use when user asks about: selling products (卖/开店), product ideas (产品/商品), market research (市场/竞品), suppliers (供应商/厂家), sourcing (采购/进货/货源), image search (图片找货/以图搜货/找同款), evaluating business opportunities (生意/创业). Start with conversational exploration, then suggest comprehensive report generation. Uses 'scout search', 'scout product', 'scout supplier-search', and 'scout supplier-search-image' commands."
----
-
-# Optima Scout - AI Product Research
-
-## When to Use This Skill
-
-Use this skill when:
-- User wants to research products or validate product ideas (e.g., "我想开店卖钛合金杯子", "帮我搜索一下XX")
-- User needs market analysis or competitive research
-- User asks about product pricing, ratings, sales data, or market trends
-- User wants to evaluate business opportunities or find products to sell
-- User needs detailed competitor analysis or listing quality assessment
-- User needs to find suppliers or manufacturers (e.g., "帮我找咖啡机供应商", "哪里进货")
-- User wants to source products from 1688/Alibaba China
-- User asks about wholesale prices, bulk purchasing costs, or profit margins (e.g., "成本多少", "批发价", "利润空间")
-- User wants to find suppliers by product image (e.g., "这个图片能找到货源吗", "帮我找同款", "看图找货", "Amazon这个能在1688找到吗")
-- User shares an Amazon product link (e.g., amazon.com/dp/XXXX, amzn.to/XXXX)
-
-## Interaction Style: Conversational → Report
-
-**Default approach: Interactive & Consultative**
-- Start with quick scans, share findings, ask clarifying questions
-- Iterate based on user feedback and interests
-- **Proactively suggest report generation** after sufficient data gathering
-- Don't assume what user wants - ask and discuss first
-
-**When to suggest full report:**
-- After sufficient exploration (typically 3+ searches, 3-5 product analyses)
-- User signals readiness: "所以你觉得呢？" "值得做吗？" "总结一下"
-- Clear insights emerged that warrant documentation
-- **Always ask permission first** - never assume user wants a long report
-
-**Exception - Direct report mode:**
-- User explicitly requests: "给我一份XX市场分析报告"
-- In this case, skip conversation and generate report directly
-
-## URL 解析 - Amazon 链接处理
-
-用户贴 Amazon 链接时，**不要用 WebFetch**（会被反爬拦截），提取 ASIN 后用 `scout product`：
-
-| URL 格式 | ASIN 位置 |
-|----------|----------|
-| `amazon.com/dp/XXXXXXXXXX` | `/dp/` 后 10 位 |
-| `amazon.com/gp/product/XXXXXXXXXX` | `/gp/product/` 后 10 位 |
-| `amzn.to/XXXX` (短链) | 用 `curl -sI "https://amzn.to/XXXX"` 从 Location header 获取完整 URL → 提取 ASIN |
-
-```bash
-# 1. 提取 ASIN → 获取产品详情
-scout product B08BHXG144
-
-# 2. 如果用户想了解市场竞争
-scout search "产品关键词" --limit 15
-
-# 3. 如果用户想找供应商
-scout supplier-search "中文关键词"
-```
-
-## Quick Start - First Step
-
-When user asks about product opportunities or market research:
-1. **IMMEDIATELY run `scout search`** with 1-2 relevant keywords
-2. Get real Amazon market data before providing any advice
-3. **Share initial findings conversationally** - don't overwhelm with full report
-4. **Ask clarifying questions** based on what you found
-5. Iterate and deepen analysis based on user responses
-
-Example: If user asks "我想开店卖钛合金杯子", your FIRST actions should be:
-```bash
-scout search "titanium cup" --limit 15
-scout search "titanium mug" --limit 10
-```
-
-Then share findings and ask:
-- "我发现市场价格区间是 $15-90，你的目标价位是多少？"
-- "看起来高端保温款竞争少，要不要深入看看？"
-
-**Critical First Steps:**
-- ✅ Always get data before giving advice - run searches immediately
-- ✅ Share findings conversationally - don't dump raw data
-- ✅ Ask clarifying questions - understand user's goals before deep diving
-
-## Available Commands
-
-### 1. Search Products: `scout search`
-
-Search for products on Amazon to analyze market opportunities.
-
-**Syntax:**
-```bash
-scout search "QUERY" --limit NUMBER
-```
-
-**Parameters:**
-- `QUERY`: Product keywords (e.g., "wireless mouse", "titanium water bottle")
-- `--limit`: Number of results (1-50, default: 10)
-- `--domain`: Amazon domain (default: amazon.com)
-
-**Returns:**
-- Product list with ASIN, title, price, rating, reviews, recent sales
-- Market overview data for competitive analysis
-
-**Key metrics to analyze:**
-- Price range and distribution
-- Recent sales ("10K+ bought in past month" = high demand)
-- Ratings_total (review count indicates market maturity)
-- Average rating (competitive quality baseline)
-
-### 2. Get Product Details: `scout product`
-
-Get comprehensive details about a specific product by ASIN.
-
-**Syntax:**
-```bash
-scout product ASIN
-```
-
-**Parameters:**
-- `ASIN`: 10-character Amazon product ID (e.g., B01GJOMWVA)
-- `--domain`: Amazon domain (default: amazon.com)
-
-**Returns:**
-- Complete product data: pricing, sales, reviews, specifications
-- Rating breakdown, BSR, listing quality indicators
-- Feature bullets, images, description, categories
-
-**Key data to extract:**
-- **BSR (Best Seller Rank)** - Sales volume indicator (lower = better)
-  - BSR < 1,000 = very high sales
-  - BSR 1,000-10,000 = good sales
-  - BSR > 50,000 = low sales
-- **Rating breakdown** - Five-star/one-star percentages
-  - 70%+ five-star = excellent satisfaction
-  - 10%+ one-star = quality issues
-- **Top reviews** - User pain points and satisfaction drivers
-- **Feature bullets** - Competitive selling points
-- **Images count** - 7 is standard, fewer = poor optimization
-- **Specifications** - May include BSR in multiple categories
-
-### 3. Search 1688 Suppliers (Keyword): `scout supplier-search`
-
-Search for suppliers on 1688.com using keywords.
-
-**Syntax:**
-```bash
-scout supplier-search "KEYWORD" --limit NUMBER
-```
-
-**Parameters:**
-- `KEYWORD`: Product keywords in Chinese (e.g., "咖啡机", "蓝牙耳机", "钛合金杯子")
-- `--limit`: Number of results (1-100, default: 20)
-- `--format`: Output format - `text` or `json`
-
-**Returns:**
-- Supplier list with product info, pricing, MOQ, supplier ratings
-- Price tiers for bulk ordering (e.g., "2~49台: ¥599", "≥100台: ¥429")
-- Supplier details: location, years in business, seller type
-- Tags: shipping policies (退货包运费), payment terms (先采后付), certifications (实力商家)
-
-**Key analysis:**
-- MOQ constraints (minimum order quantity)
-- Supplier type: 生产加工 (manufacturer) vs. 经销批发 (trader)
-- Years in business (8+ years = established)
-- Return rate (lower = better, typical: 30-50%)
-
-### 4. 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.
-
-**Syntax:**
-```bash
-scout supplier-search-image "IMAGE_URL" --limit NUMBER
-```
-
-**Parameters:**
-- `IMAGE_URL`: Product image URL (Amazon, Alibaba, or any accessible image URL)
-- `--limit`: Number of results (1-100, default: 20)
-- `--format`: Output format - `text` or `json`
-
-**Returns:** Same as `supplier-search` (supplier list, pricing, MOQ, ratings)
-
-**Use cases:**
-- Finding 1688 alternatives for Amazon/Shopify products
-- "找同款" / "看图找货" scenarios
-- Visual products where images are more descriptive than keywords
-- When user provides product image URL
-
-**Important notes:**
-- Works with images from any platform (Amazon, Alibaba, direct URLs)
-- Non-Alibaba images are automatically converted for 1688 search
-- If image is inaccessible (404, expired, auth-required), will return helpful error message
-- **Best practice**: Try both image and keyword search for comprehensive results
-
-## Research Workflow
-
-### Interactive Research Flow (Recommended):
-
-**Phase 1: Initial Discovery & Discussion**
-1. **Quick Market Scan** → Run 1-2 searches with key terms
-2. **Share Initial Findings** → Present key metrics (price range, competition level, demand signals)
-3. **Discuss with User** → Ask clarifying questions about target price, market segment, priorities
-
-**Phase 2: Deep Dive & Refinement**
-4. **Targeted Analysis** → Based on user feedback, run `scout product` on relevant ASINs
-5. **Extract Insights** → Share key findings (BSR, reviews, pain points)
-6. **Iterate & Explore** → User may request different keywords, specific competitor analysis, or alternative product categories
-
-**Phase 2.5: Supplier Sourcing (Optional but Recommended)**
-7. **Trigger**: User shows interest in costs/sourcing, or after market validation
-   - "成本大概多少？" "批发价怎么样？" "利润空间大吗？"
-   - "哪里进货？" "供应商怎么找？"
-   - "这个图片能找到货源吗？" "Amazon这个能在1688找到吗？"
-
-8. **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
-
-9. **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)
-
-10. **Ask**: "要不要我详细分析几个供应商？" or proceed to report
-
-**Phase 3: Report Generation (Proactive Suggestion)**
-11. **Gauge Completion** → After sufficient data, suggest: "要不要我整理成一份完整的市场分析报告？"
-12. **Generate Report** → Create comprehensive markdown report with all findings
-13. **Save & Iterate** → Offer to save report and refine based on feedback
-
----
-
-### Alternative: Quick Research Flow
-
-When user explicitly requests a report upfront:
-1. Run 3-4 diverse keyword searches
-2. Analyze top 3-5 products with `scout product`
-3. Search 1688 suppliers (image + keyword)
-4. Generate comprehensive report directly
-
-### Multi-Keyword Research Strategy
-
-**Example: Researching titanium cups**
-```bash
-scout search "titanium cup" --limit 15
-scout search "titanium mug" --limit 15
-scout search "titanium tumbler" --limit 10
-```
-
-**Why multiple keywords:**
-- Different keywords reveal different market segments
-- Find niche opportunities
-- Cross-validate market size
-- Discover related products
-
-## Usage Examples
-
-### Example 1: Interactive Research (Keyword-based)
-
-**User**: "我想开个店卖钛合金杯子，你觉得合适吗"
-
-**Flow:**
-1. Run `scout search "titanium cup"` + `scout search "titanium mug"`
-2. Share: "市场有50+竞品，价格$15-90，主要在$20-30。头部产品月销约200件。两个方向：低价位($15-25)竞争激烈，高端保温款($60-90)产品很少。你更倾向哪个？"
-3. User: "中高端的，质量好的"
-4. Run `scout product` on 3 representative ASINs (B0CTKWJDXX, B0DNCMN3NX, B083NLR6BF)
-5. Share: "TOAKS中端爆款BSR#530，月销250件，87%五星。用户最爱：超轻、品质好、无金属味。主要抱怨：散热快（无保温）。KOYASU高端保温$89.99，评论少但4.8分。保温款市场几乎空白！"
-6. User: "好的，你看看"
-7. Run `scout search "titanium tumbler"`
-8. Share: "titanium tumbler竞品只5-6个，$60-110。现在查供应商成本？"
-9. Run `scout supplier-search "钛合金保温杯"`
-10. Share: "批发价区间：¥180-450（约$25-65），起订量多数50-100个。头部供应商：8年工厂，¥280批发价。**利润分析**：Amazon售价$70-90，1688成本¥280（约$40），运费+关税约$15，总成本约$55，**毛利率25-40%**。"
-11. Suggest report generation
-
-### Example 2: Image-Based Supplier Search
-
-**User**: "我在Amazon看到这个蓝牙耳机很火，帮我找1688供应商 https://m.media-amazon.com/images/..."
-
-**Flow:**
-```bash
-scout supplier-search-image "https://m.media-amazon.com/images/..." --limit 20
-```
-
-**Response**: "通过图片搜索找到15个供应商：
-
-**TOP 3 推荐：**
-1. 深圳某电子厂（8年工厂）
-   - 批发价：¥45-68 | Amazon售价：$89.99
-   - 起订量：50件 | 评分：4.8★
-   - **利润空间：~40-50%**
-
-2. 东莞某科技（5年工厂）
-   - 批发价：¥38-55 | 起订量：100件
-   - 标签：退货包运费、7天包换
-
-3. [...]
-
-要详细对比这几个供应商吗？"
-
-### Example 3: Competitor Analysis
-
-**User**: "帮我分析这个产品 B0788F3R8X"
-
-**Action:**
-```bash
-scout product B0788F3R8X
-```
-
-**Analysis Checklist:**
-- ✅ **BSR & Market Position**
-  - Check BSR in specifications → estimate sales volume
-  - Compare with category averages
-- ✅ **Customer Satisfaction**
-  - Rating breakdown (five-star %, one-star %)
-  - Total reviews count (market maturity indicator)
-  - Review trends over time
-- ✅ **Listing Quality**
-  - Images count (7 is standard, fewer = poor optimization)
-  - Feature bullets count and quality
-  - 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
-- ✅ **Competitive Advantages**
-  - Unique selling points in feature_bullets
-  - Price positioning vs. competitors
-  - Brand strength and trust signals
-  - Differentiation factors
-
-## Analysis Framework
-
-### Market Viability Quick Reference
-
-| 指标 | 优秀市场 | 正常市场 | 风险市场 |
-|------|---------|---------|---------|
-| 竞品数量 | 10-50 | 5-10 或 50-100 | <5 或 >100 |
-| 头部评论数 | 100-1000 | 50-100 或 1K-5K | <50 或 >5K |
-| 价格区间 | 宽（差异化） | 中等 | 窄（价格战） |
-| BSR范围 | 1K-10K | 10K-50K | >50K |
-| 进入难度 | 适中 | 需差异化 | 很难或需求不明 |
-
-### Key Metrics
-
-**BSR (Best Seller Rank):**
-- <1K = 月销500+件 | 1K-10K = 100-500件 | 10K-50K = 20-100件 | >50K = <20件
-
-**Rating Breakdown:**
-- 70%+ five-star = 优秀 | 60-70% = 正常 | <60% = 质量问题 | 10%+ one-star = 严重问题
-
-**Market Maturity:**
-- ratings_total >1000 = 成熟 | 100-1000 = 发展中 | <100 = 新兴/小众
-
-**Demand Signals:**
-
-High Demand:
-- ✅ "10K+ bought in past month"
-- ✅ 多个产品 ratings_total >500
-- ✅ BSR <10K
-- ✅ 搜索结果超过 30 个相关产品
-
-Low Demand:
-- ⚠️ 少于 10 个搜索结果
-- ⚠️ 头部产品 ratings_total < 50
-- ⚠️ BSR > 100,000
-- ⚠️ 没有 "bought in past month" 标签
-
-**Entry Difficulty Assessment:**
-
-| 维度 | 容易进入 | 中等难度 | 困难进入 |
-|------|---------|---------|---------|
-| 头部产品评论数 | <200 | 200-2000 | >2000 |
-| 品牌集中度 | 无知名品牌 | 少数品牌 | 大品牌垄断 |
-| 价格竞争 | 差异化定价 | 价格区间宽 | 价格战 |
-| 评分分布 | <4.5 平均分 | 4.5-4.7 | >4.7（难超越） |
-
-### Report Generation
-
-**When to suggest:**
-- 3+ searches + 3-5 product analyses completed
-- User asks: "所以你觉得呢？" "值得做吗？" "总结一下"
-- Clear opportunity/risk identified that should be documented
-
-**How to suggest (use this natural template):**
-```
-"我已经分析了 X 个搜索和 Y 个竞品，发现了一些有意思的模式。
-
-核心发现：
-- [1-2 句话总结主要发现]
-- [机会或风险点]
-
-要不要我把这些整理成一份完整的市场分析报告？可以包括：
-- 市场规模和竞争格局
-- 头部产品深度分析
-- 差异化机会点
-- 进入策略建议
-- 财务预测（如果你需要的话）
-
-报告会保存为 markdown 文件，方便你后续参考和分享。"
-```
-
-**If user declines:**
-- Respect decision: "好的，有需要随时告诉我"
-- Continue exploration or answer follow-up questions
-- Offer report again later if more data gathered
-
-**Report must include:**
-- Executive Summary（核心结论前置：适合进入？风险是什么？）
-- Market Analysis（基于搜索数据的市场概况）
-- Competitor Deep-Dive（基于product details的竞品分析：BSR, rating breakdown, top reviews insights）
-- Opportunity Assessment（SWOT 或机会/挑战分析）
-- Entry Strategy（产品定位、定价、差异化策略）
-- Supplier Analysis (if Phase 2.5 completed)（1688供应商、成本、利润空间）
-
-**Report naming:** `{产品类型}市场分析报告.md`
-
-## Cross-Skill Integration
-
-**TikTok/Instagram → Scout → Supplier 完整链路：**
-
-1. **Discover** (TikTok/Instagram) → Find trending products
-2. **Validate** (Scout Amazon) → Verify market demand
-   ```bash
-   scout search "product name" --limit 15
-   scout product <top_asin>
-   ```
-3. **Source** (Scout 1688) → Find suppliers and cost
-   ```bash
-   # Method A: Image search (recommended for visual match)
-   scout supplier-search-image "https://amazon-image-url"
-
-   # Method B: Keyword search
-   scout supplier-search "产品关键词"
-
-   # Best: Try both
-   ```
-4. **Decide** →综合分析三者数据，都通过→值得做
-
-**Shein → Scout → Supplier 价格验证链路：**
-
-1. **Discover** (Shein) → Find low-price trending products
-   ```bash
-   scout shein-search "product keyword" --limit 20
-   ```
-2. **Validate** (Scout Amazon) → Compare pricing and demand in broader market
-   ```bash
-   scout search "product name" --limit 15
-   scout product <top_asin>
-   ```
-3. **Source** (Scout 1688) → Find suppliers and calculate margins
-   ```bash
-   scout supplier-search "产品关键词"
-   ```
-4. **Analyze** → Shein 低价（$X） vs Amazon 中高价（$Y） vs 1688 成本（¥Z）→ 找到最佳销售渠道和利润空间
-
-**Proactive suggestion after cross-skill analysis:**
-"我已经分析了TikTok热度、Amazon市场需求、Shein价格定位、1688供应商成本。要不要生成一份完整的产品机会分析报告？"
+---
+name: scout
+description: "Interactive Amazon product research consultant with 1688 supplier sourcing. Search products, analyze markets, find suppliers (by keyword or image), and generate professional reports. ALWAYS use when user asks about: selling products (卖/开店), product ideas (产品/商品), market research (市场/竞品), suppliers (供应商/厂家), sourcing (采购/进货/货源), image search (图片找货/以图搜货/找同款), evaluating business opportunities (生意/创业). Start with conversational exploration, then suggest comprehensive report generation. Uses 'scout search', 'scout product', 'scout supplier-search', and 'scout supplier-search-image' commands."
+---
+
+# Optima Scout - AI Product Research
+
+## When to Use This Skill
+
+Use this skill when:
+- User wants to research products or validate product ideas (e.g., "我想开店卖钛合金杯子", "帮我搜索一下XX")
+- User needs market analysis or competitive research
+- User asks about product pricing, ratings, sales data, or market trends
+- User wants to evaluate business opportunities or find products to sell
+- User needs detailed competitor analysis or listing quality assessment
+- User needs to find suppliers or manufacturers (e.g., "帮我找咖啡机供应商", "哪里进货")
+- User wants to source products from 1688/Alibaba China
+- User asks about wholesale prices, bulk purchasing costs, or profit margins (e.g., "成本多少", "批发价", "利润空间")
+- User wants to find suppliers by product image (e.g., "这个图片能找到货源吗", "帮我找同款", "看图找货", "Amazon这个能在1688找到吗")
+- User shares an Amazon product link (e.g., amazon.com/dp/XXXX, amzn.to/XXXX)
+
+## Interaction Style: Conversational → Report
+
+**Default approach: Interactive & Consultative**
+- Start with quick scans, share findings, ask clarifying questions
+- Iterate based on user feedback and interests
+- **Proactively suggest report generation** after sufficient data gathering
+- Don't assume what user wants - ask and discuss first
+
+**When to suggest full report:**
+- After sufficient exploration (typically 3+ searches, 3-5 product analyses)
+- User signals readiness: "所以你觉得呢？" "值得做吗？" "总结一下"
+- Clear insights emerged that warrant documentation
+- **Always ask permission first** - never assume user wants a long report
+
+**Exception - Direct report mode:**
+- User explicitly requests: "给我一份XX市场分析报告"
+- In this case, skip conversation and generate report directly
+
+## URL 解析 - Amazon 链接处理
+
+用户贴 Amazon 链接时，**不要用 WebFetch**（会被反爬拦截），提取 ASIN 后用 `scout product`：
+
+| URL 格式 | ASIN 位置 |
+|----------|----------|
+| `amazon.com/dp/XXXXXXXXXX` | `/dp/` 后 10 位 |
+| `amazon.com/gp/product/XXXXXXXXXX` | `/gp/product/` 后 10 位 |
+| `amzn.to/XXXX` (短链) | 用 `curl -sI "https://amzn.to/XXXX"` 从 Location header 获取完整 URL → 提取 ASIN |
+
+```bash
+# 1. 提取 ASIN → 获取产品详情
+scout product B08BHXG144
+
+# 2. 如果用户想了解市场竞争
+scout search "产品关键词" --limit 15
+
+# 3. 如果用户想找供应商
+scout supplier-search "中文关键词"
+```
+
+## Quick Start - First Step
+
+When user asks about product opportunities or market research:
+1. **IMMEDIATELY run `scout search`** with 1-2 relevant keywords
+2. Get real Amazon market data before providing any advice
+3. **Share initial findings conversationally** - don't overwhelm with full report
+4. **Ask clarifying questions** based on what you found
+5. Iterate and deepen analysis based on user responses
+
+Example: If user asks "我想开店卖钛合金杯子", your FIRST actions should be:
+```bash
+scout search "titanium cup" --limit 15
+scout search "titanium mug" --limit 10
+```
+
+Then share findings and ask:
+- "我发现市场价格区间是 $15-90，你的目标价位是多少？"
+- "看起来高端保温款竞争少，要不要深入看看？"
+
+**Critical First Steps:**
+- ✅ Always get data before giving advice - run searches immediately
+- ✅ Share findings conversationally - don't dump raw data
+- ✅ Ask clarifying questions - understand user's goals before deep diving
+
+## Available Commands
+
+### 1. Search Products: `scout search`
+
+Search for products on Amazon to analyze market opportunities.
+
+**Syntax:**
+```bash
+scout search "QUERY" --limit NUMBER
+```
+
+**Parameters:**
+- `QUERY`: Product keywords (e.g., "wireless mouse", "titanium water bottle")
+- `--limit`: Number of results (1-50, default: 10)
+- `--domain`: Amazon domain (default: amazon.com)
+
+**Returns:**
+- Product list with ASIN, title, price, rating, reviews, recent sales
+- Market overview data for competitive analysis
+
+**Key metrics to analyze:**
+- Price range and distribution
+- Recent sales ("10K+ bought in past month" = high demand)
+- Ratings_total (review count indicates market maturity)
+- Average rating (competitive quality baseline)
+
+### 2. Get Product Details: `scout product`
+
+Get comprehensive details about a specific product by ASIN.
+
+**Syntax:**
+```bash
+scout product ASIN
+```
+
+**Parameters:**
+- `ASIN`: 10-character Amazon product ID (e.g., B01GJOMWVA)
+- `--domain`: Amazon domain (default: amazon.com)
+
+**Returns:**
+- Complete product data: pricing, sales, reviews, specifications
+- Rating breakdown, BSR, listing quality indicators
+- Feature bullets, images, description, categories
+
+**Key data to extract:**
+- **BSR (Best Seller Rank)** - Sales volume indicator (lower = better)
+  - BSR < 1,000 = very high sales
+  - BSR 1,000-10,000 = good sales
+  - BSR > 50,000 = low sales
+- **Rating breakdown** - Five-star/one-star percentages
+  - 70%+ five-star = excellent satisfaction
+  - 10%+ one-star = quality issues
+- **Top reviews** - User pain points and satisfaction drivers
+- **Feature bullets** - Competitive selling points
+- **Images count** - 7 is standard, fewer = poor optimization
+- **Specifications** - May include BSR in multiple categories
+
+### 3. Search 1688 Suppliers (Keyword): `scout supplier-search`
+
+Search for suppliers on 1688.com using keywords.
+
+**Syntax:**
+```bash
+scout supplier-search "KEYWORD" --limit NUMBER
+```
+
+**Parameters:**
+- `KEYWORD`: Product keywords in Chinese (e.g., "咖啡机", "蓝牙耳机", "钛合金杯子")
+- `--limit`: Number of results (1-100, default: 20)
+- `--format`: Output format - `text` or `json`
+
+**Returns:**
+- Supplier list with product info, pricing, MOQ, supplier ratings
+- Price tiers for bulk ordering (e.g., "2~49台: ¥599", "≥100台: ¥429")
+- Supplier details: location, years in business, seller type
+- Tags: shipping policies (退货包运费), payment terms (先采后付), certifications (实力商家)
+
+**Key analysis:**
+- MOQ constraints (minimum order quantity)
+- Supplier type: 生产加工 (manufacturer) vs. 经销批发 (trader)
+- Years in business (8+ years = established)
+- Return rate (lower = better, typical: 30-50%)
+
+### 4. 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.
+
+**Syntax:**
+```bash
+scout supplier-search-image "IMAGE_URL" --limit NUMBER
+```
+
+**Parameters:**
+- `IMAGE_URL`: Product image URL (Amazon, Alibaba, or any accessible image URL)
+- `--limit`: Number of results (1-100, default: 20)
+- `--format`: Output format - `text` or `json`
+
+**Returns:** Same as `supplier-search` (supplier list, pricing, MOQ, ratings)
+
+**Use cases:**
+- Finding 1688 alternatives for Amazon/Shopify products
+- "找同款" / "看图找货" scenarios
+- Visual products where images are more descriptive than keywords
+- When user provides product image URL
+
+**Important notes:**
+- Works with images from any platform (Amazon, Alibaba, direct URLs)
+- Non-Alibaba images are automatically converted for 1688 search
+- If image is inaccessible (404, expired, auth-required), will return helpful error message
+- **Best practice**: Try both image and keyword search for comprehensive results
+
+## Research Workflow
+
+### Interactive Research Flow (Recommended):
+
+**Phase 1: Initial Discovery & Discussion**
+1. **Quick Market Scan** → Run 1-2 searches with key terms
+2. **Share Initial Findings** → Present key metrics (price range, competition level, demand signals)
+3. **Discuss with User** → Ask clarifying questions about target price, market segment, priorities
+
+**Phase 2: Deep Dive & Refinement**
+4. **Targeted Analysis** → Based on user feedback, run `scout product` on relevant ASINs
+5. **Extract Insights** → Share key findings (BSR, reviews, pain points)
+6. **Iterate & Explore** → User may request different keywords, specific competitor analysis, or alternative product categories
+
+**Phase 2.5: Supplier Sourcing (Optional but Recommended)**
+7. **Trigger**: User shows interest in costs/sourcing, or after market validation
+   - "成本大概多少？" "批发价怎么样？" "利润空间大吗？"
+   - "哪里进货？" "供应商怎么找？"
+   - "这个图片能找到货源吗？" "Amazon这个能在1688找到吗？"
+
+8. **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
+
+9. **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)
+
+10. **Ask**: "要不要我详细分析几个供应商？" or proceed to report
+
+**Phase 3: Report Generation (Proactive Suggestion)**
+11. **Gauge Completion** → After sufficient data, suggest: "要不要我整理成一份完整的市场分析报告？"
+12. **Generate Report** → Create comprehensive markdown report with all findings
+13. **Save & Iterate** → Offer to save report and refine based on feedback
+
+---
+
+### Alternative: Quick Research Flow
+
+When user explicitly requests a report upfront:
+1. Run 3-4 diverse keyword searches
+2. Analyze top 3-5 products with `scout product`
+3. Search 1688 suppliers (image + keyword)
+4. Generate comprehensive report directly
+
+### Multi-Keyword Research Strategy
+
+**Example: Researching titanium cups**
+```bash
+scout search "titanium cup" --limit 15
+scout search "titanium mug" --limit 15
+scout search "titanium tumbler" --limit 10
+```
+
+**Why multiple keywords:**
+- Different keywords reveal different market segments
+- Find niche opportunities
+- Cross-validate market size
+- Discover related products
+
+## Usage Examples
+
+### Example 1: Interactive Research (Keyword-based)
+
+**User**: "我想开个店卖钛合金杯子，你觉得合适吗"
+
+**Flow:**
+1. Run `scout search "titanium cup"` + `scout search "titanium mug"`
+2. Share: "市场有50+竞品，价格$15-90，主要在$20-30。头部产品月销约200件。两个方向：低价位($15-25)竞争激烈，高端保温款($60-90)产品很少。你更倾向哪个？"
+3. User: "中高端的，质量好的"
+4. Run `scout product` on 3 representative ASINs (B0CTKWJDXX, B0DNCMN3NX, B083NLR6BF)
+5. Share: "TOAKS中端爆款BSR#530，月销250件，87%五星。用户最爱：超轻、品质好、无金属味。主要抱怨：散热快（无保温）。KOYASU高端保温$89.99，评论少但4.8分。保温款市场几乎空白！"
+6. User: "好的，你看看"
+7. Run `scout search "titanium tumbler"`
+8. Share: "titanium tumbler竞品只5-6个，$60-110。现在查供应商成本？"
+9. Run `scout supplier-search "钛合金保温杯"`
+10. Share: "批发价区间：¥180-450（约$25-65），起订量多数50-100个。头部供应商：8年工厂，¥280批发价。**利润分析**：Amazon售价$70-90，1688成本¥280（约$40），运费+关税约$15，总成本约$55，**毛利率25-40%**。"
+11. Suggest report generation
+
+### Example 2: Image-Based Supplier Search
+
+**User**: "我在Amazon看到这个蓝牙耳机很火，帮我找1688供应商 https://m.media-amazon.com/images/..."
+
+**Flow:**
+```bash
+scout supplier-search-image "https://m.media-amazon.com/images/..." --limit 20
+```
+
+**Response**: "通过图片搜索找到15个供应商：
+
+**TOP 3 推荐：**
+1. 深圳某电子厂（8年工厂）
+   - 批发价：¥45-68 | Amazon售价：$89.99
+   - 起订量：50件 | 评分：4.8★
+   - **利润空间：~40-50%**
+
+2. 东莞某科技（5年工厂）
+   - 批发价：¥38-55 | 起订量：100件
+   - 标签：退货包运费、7天包换
+
+3. [...]
+
+要详细对比这几个供应商吗？"
+
+### Example 3: Competitor Analysis
+
+**User**: "帮我分析这个产品 B0788F3R8X"
+
+**Action:**
+```bash
+scout product B0788F3R8X
+```
+
+**Analysis Checklist:**
+- ✅ **BSR & Market Position**
+  - Check BSR in specifications → estimate sales volume
+  - Compare with category averages
+- ✅ **Customer Satisfaction**
+  - Rating breakdown (five-star %, one-star %)
+  - Total reviews count (market maturity indicator)
+  - Review trends over time
+- ✅ **Listing Quality**
+  - Images count (7 is standard, fewer = poor optimization)
+  - Feature bullets count and quality
+  - 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
+- ✅ **Competitive Advantages**
+  - Unique selling points in feature_bullets
+  - Price positioning vs. competitors
+  - Brand strength and trust signals
+  - Differentiation factors
+
+## Analysis Framework
+
+### Market Viability Quick Reference
+
+| 指标 | 优秀市场 | 正常市场 | 风险市场 |
+|------|---------|---------|---------|
+| 竞品数量 | 10-50 | 5-10 或 50-100 | <5 或 >100 |
+| 头部评论数 | 100-1000 | 50-100 或 1K-5K | <50 或 >5K |
+| 价格区间 | 宽（差异化） | 中等 | 窄（价格战） |
+| BSR范围 | 1K-10K | 10K-50K | >50K |
+| 进入难度 | 适中 | 需差异化 | 很难或需求不明 |
+
+### Key Metrics
+
+**BSR (Best Seller Rank):**
+- <1K = 月销500+件 | 1K-10K = 100-500件 | 10K-50K = 20-100件 | >50K = <20件
+
+**Rating Breakdown:**
+- 70%+ five-star = 优秀 | 60-70% = 正常 | <60% = 质量问题 | 10%+ one-star = 严重问题
+
+**Market Maturity:**
+- ratings_total >1000 = 成熟 | 100-1000 = 发展中 | <100 = 新兴/小众
+
+**Demand Signals:**
+
+High Demand:
+- ✅ "10K+ bought in past month"
+- ✅ 多个产品 ratings_total >500
+- ✅ BSR <10K
+- ✅ 搜索结果超过 30 个相关产品
+
+Low Demand:
+- ⚠️ 少于 10 个搜索结果
+- ⚠️ 头部产品 ratings_total < 50
+- ⚠️ BSR > 100,000
+- ⚠️ 没有 "bought in past month" 标签
+
+**Entry Difficulty Assessment:**
+
+| 维度 | 容易进入 | 中等难度 | 困难进入 |
+|------|---------|---------|---------|
+| 头部产品评论数 | <200 | 200-2000 | >2000 |
+| 品牌集中度 | 无知名品牌 | 少数品牌 | 大品牌垄断 |
+| 价格竞争 | 差异化定价 | 价格区间宽 | 价格战 |
+| 评分分布 | <4.5 平均分 | 4.5-4.7 | >4.7（难超越） |
+
+### Report Generation
+
+**When to suggest:**
+- 3+ searches + 3-5 product analyses completed
+- User asks: "所以你觉得呢？" "值得做吗？" "总结一下"
+- Clear opportunity/risk identified that should be documented
+
+**How to suggest (use this natural template):**
+```
+"我已经分析了 X 个搜索和 Y 个竞品，发现了一些有意思的模式。
+
+核心发现：
+- [1-2 句话总结主要发现]
+- [机会或风险点]
+
+要不要我把这些整理成一份完整的市场分析报告？可以包括：
+- 市场规模和竞争格局
+- 头部产品深度分析
+- 差异化机会点
+- 进入策略建议
+- 财务预测（如果你需要的话）
+
+报告会保存为 markdown 文件，方便你后续参考和分享。"
+```
+
+**If user declines:**
+- Respect decision: "好的，有需要随时告诉我"
+- Continue exploration or answer follow-up questions
+- Offer report again later if more data gathered
+
+**Report must include:**
+- Executive Summary（核心结论前置：适合进入？风险是什么？）
+- Market Analysis（基于搜索数据的市场概况）
+- Competitor Deep-Dive（基于product details的竞品分析：BSR, rating breakdown, top reviews insights）
+- Opportunity Assessment（SWOT 或机会/挑战分析）
+- Entry Strategy（产品定位、定价、差异化策略）
+- Supplier Analysis (if Phase 2.5 completed)（1688供应商、成本、利润空间）
+
+**Report naming:** `{产品类型}市场分析报告.md`
+
+## Cross-Skill Integration
+
+**TikTok/Instagram → Scout → Supplier 完整链路：**
+
+1. **Discover** (TikTok/Instagram) → Find trending products
+2. **Validate** (Scout Amazon) → Verify market demand
+   ```bash
+   scout search "product name" --limit 15
+   scout product <top_asin>
+   ```
+3. **Source** (Scout 1688) → Find suppliers and cost
+   ```bash
+   # Method A: Image search (recommended for visual match)
+   scout supplier-search-image "https://amazon-image-url"
+
+   # Method B: Keyword search
+   scout supplier-search "产品关键词"
+
+   # Best: Try both
+   ```
+4. **Decide** →综合分析三者数据，都通过→值得做
+
+**Shein → Scout → Supplier 价格验证链路：**
+
+1. **Discover** (Shein) → Find low-price trending products
+   ```bash
+   scout shein-search "product keyword" --limit 20
+   ```
+2. **Validate** (Scout Amazon) → Compare pricing and demand in broader market
+   ```bash
+   scout search "product name" --limit 15
+   scout product <top_asin>
+   ```
+3. **Source** (Scout 1688) → Find suppliers and calculate margins
+   ```bash
+   scout supplier-search "产品关键词"
+   ```
+4. **Analyze** → Shein 低价（$X） vs Amazon 中高价（$Y） vs 1688 成本（¥Z）→ 找到最佳销售渠道和利润空间
+
+**Proactive suggestion after cross-skill analysis:**
+"我已经分析了TikTok热度、Amazon市场需求、Shein价格定位、1688供应商成本。要不要生成一份完整的产品机会分析报告？"