Ecomseer

• Chinese → use Chinese labels: 商品名称, 销量, 销售额, 达人数, 评分
• English → use English labels: Product Name, Sales, Revenue, Influencers, Rating

API Access

Base URL: https://www.ecomseer.com Auth header: X-API-Key: $ECOMSEER_API_KEY

All endpoints are GET requests:

curl -s "https://www.ecomseer.com/api/open/{endpoint}?{params}" \
  -H "X-API-Key: $ECOMSEER_API_KEY"

Key conventions:

• All endpoints start with /api/open/
• region param defaults to US. Other markets: GB, ID, TH, VN, MY, PH, SG, etc.
• Range filters use "min,max" format, -1 means no limit (e.g. sold_count=100,-1 means sales ≥ 100)
• Sort param order format: "field_number,direction", 2=desc (e.g. order=2,2)
• Pagination: page (starts at 1), pagesize (default 10-20, max 50)

Interaction Flow

Step 1: Check API Key

Before any query, run: [ -n "$ECOMSEER_API_KEY" ] && echo "ok" || echo "missing"

Never print the key value.

If missing — show setup guide

Reply with EXACTLY this (Chinese user):

🔑 需要先配置 EcomSeer API Key 才能使用：

1. 打开 https://www.ecomseer.com 注册账号
2. 登录后在控制台找到 API Keys，创建一个 Key
3. 拿到 Key 后回来找我，我帮你配置 ✅

Reply with EXACTLY this (English user):

🔑 You need an EcomSeer API Key to get started:

1. Go to https://www.ecomseer.com and sign up
2. After signing in, find API Keys in your dashboard and create one
3. Come back with your key and I'll set it up for you ✅

Then STOP. Wait for the user to return with their key.

❌ DO NOT just say "please provide your API key" without the registration link.

Auto-detect: if the user pastes an API key directly in chat (e.g. fmk_xxxxx)

1. Run this command (replace {KEY} with the actual key):

openclaw config set skills.entries.ecomseer.apiKey "{KEY}"

2. Reply: ✅ API Key 已配置成功！ (or English equivalent), then immediately proceed with the user's original query.

❌ DO NOT echo/print the key value back.

Step 1.5: Complexity Classification — 复杂度分类

Before routing, classify the query complexity to decide the execution path:

Classification rule — count the API calls needed:

Simple (exactly 1 API call):

• Single search: "搜一下蓝牙耳机" → 1× goods/search
• Single ranking: "US销量榜Top10" → 1× goods/sale-rank
• Single detail: "这个商品的评分" → 1× goods/detail
• Filter options: "有哪些品类" → 1× goods/filters

Deep (2+ API calls):

• Any query requiring entity lookup + data fetch: "XX达人带了什么货" needs search→detail = 2 calls → Deep
• Any analysis: "分析XX" → always multi-call → Deep
• Any comparison: "对比XX和YY" → always multi-call → Deep
• Any market overview: "XX品类市场分析" → always multi-call → Deep
• Any trend: "XX趋势" → always multi-call → Deep

Default: If unsure, classify as Deep (prefer thorough over incomplete).

Execution paths:

→ Simple path: Continue to Step 2 (existing routing logic). At the end of the response, append a hint in the user's language:

• Chinese: 💡 需要更深入的分析？试试说"深度分析{topic}"
• English: 💡 Want deeper analysis? Try "deep research on {topic}"

→ Deep path: Call the EcomSeer Deep Research service.

This is a 4-step process. Do NOT use [[reply_to_current]] until the final step.

Step 0 — Validate API key before submitting:

Run this command first to verify the API key is valid:

curl -s -o /dev/null -w "%{http_code}" "https://www.ecomseer.com/api/open/goods/filters?region=US" -H "X-API-Key: $ECOMSEER_API_KEY"

• If it returns 200 → key is valid, proceed to Step 1.
• If it returns 401 or 403 → key is invalid. Show this message and STOP:
  • Chinese: ❌ API Key 无效，请检查你的 Key 是否正确。前往 https://www.ecomseer.com 重新获取。
  • English: ❌ API Key is invalid. Please check your key at https://www.ecomseer.com
• Do NOT submit to deep research if validation fails.

Step 1 — Submit the research task (returns instantly):

Run this exact command (only replace {user_query} and {additional_context}):

curl -s -X POST "https://deepresearch.ecomseer.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-local-token-2026" \
  -d '{"project": "ecomseer", "query": "{user_query}", "context": "{additional_context}", "api_key": "'"$ECOMSEER_API_KEY"'"}'

• project is always "ecomseer" — do NOT change this.
• query is the user's research question (in the user's language).
• context is optional — add useful context if relevant. Omit or set to null if not needed.
• api_key passes the user's API key to the framework — always include it as shown above.

This returns immediately with:

{"task_id": "dr_xxxx-xxxx-xxxx", "status": "pending", "created_at": "..."}

Extract the task_id value for Step 2.

Step 2 — Poll until done (use this exact script, do NOT modify):

Run this exact command, only replacing {task_id}:

while true; do r=$(curl -s "https://deepresearch.ecomseer.com/research/{task_id}" -H "Authorization: Bearer test-local-token-2026"); s=$(echo "$r" | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4); echo "status=$s"; if [ "$s" = "completed" ] || [ "$s" = "failed" ]; then echo "$r"; break; fi; sleep 15; done

This script polls every 15 seconds and exits only when the task is done. It may take 1-5 minutes. Do NOT interrupt it, do NOT add a loop limit, do NOT abandon it.

Step 3 — Format and reply to the user with the framework's report.

CRITICAL RULES:

• Do NOT send [[reply_to_current]] before Step 2 completes — it will stop execution.
• NEVER fall back to manual analysis. The framework WILL complete — just wait for it.
• NEVER write your own polling loop. Use the exact script above.

Processing the response JSON:

The completed response has this structure:

{
  "task_id": "dr_xxxx",
  "status": "completed",
  "output": {
    "format": "html",
    "files": [{"name": "report.html", "url": "https://pub-a760a2c961554a558faba40a40ac9e08.r2.dev/deep-research/{task_id}/report.html", ...}],
    "summary": "- 核心发现1\n- 核心发现2\n- ..."
  },
  "usage": {"model": "gpt-5.4", "total_tokens": 286599, "research_time_seconds": 187.7}
}

Do NOT paste the full report into the chat. Instead:

1. Take output.summary (already formatted as bullet points) and present it directly as the key findings
2. Append the report link from output.files[0].url: [📊 查看完整报告]({url})
3. Add follow-up hints based on the summary content

If the task failed (status="failed"):

• The response will contain "error": {"message": "..."} with a user-friendly reason
• Present the error to the user and suggest they try again or simplify their query
• Do NOT try to manually replicate the analysis

Example output (Chinese):

📊 深度分析完成！

**核心发现：**
- 美国美妆个护TOP10爆品以化妆刷具和面部护肤为主
- Tarte化妆刷近28天销量6.53万，客单价$39，显著高于均值
- 视频带货贡献明显：28天关联视频212条、带货达人185人
- 运营建议：优先布局"高视觉效果+强使用演示+中高客单"品类

👉 [查看完整报告](https://pub-a760a2c961554a558faba40a40ac9e08.r2.dev/deep-research/dr_xxxx/report.html)

💡 试试："看看达人榜" | "搜一下蓝牙耳机" | "东南亚市场对比"

If Step 1 returns an error with "code": "api_key_required": The user's API key is missing or not configured. Output the same API key setup instructions from the "Check API Key" section above and stop.

If the framework is unreachable (connection refused/timeout on Step 1): Fall back to the existing routing logic (Step 2 → route by intent).

Step 2: Route — Classify Intent & Load Reference

Read the user's request and classify into one of these intent groups. Then read only the reference file(s) needed before executing.

Rules:

• If uncertain, default to Product Search (most common use case).
• For Deep Dive, read reference files incrementally as each step requires them.
• Always check region context — default is US unless the user specifies otherwise.

Step 3: Classify Action Mode

Default for Product Search / Rankings: Browse.

Step 4: Plan & Execute

Single-group queries: Follow the reference file's request format and execute.

Cross-group orchestration (Deep Dive): Chain multiple endpoints. Common patterns:

Pattern A: "分析 {品类} 的爆品趋势" — Category Trend Analysis

1. GET /api/open/goods/filters → get category IDs
2. GET /api/open/goods/sale-rank?l1_cid={cid}&region=US → top sellers
3. GET /api/open/goods/detail?product_id={id} → detail for each top product
4. GET /api/open/product/overview?product_id={id} → sales trends
5. GET /api/open/product/authors?product_id={id} → influencer data

Pattern B: "对比 {达人A} 和 {达人B}" — Influencer Comparison

1. GET /api/open/influencers/search?words={name} → find each influencer
2. GET /api/open/influencers/detail?uid={uid} → profile for each
3. GET /api/open/influencers/detail/goods?uid={uid} → product portfolio for each
4. GET /api/open/influencers/detail/cargo-summary?uid={uid} → sales summary for each

Pattern C: "{市场} 机会分析" — Market Opportunity

1. GET /api/open/goods/sale-rank?region={region} → top sellers in market
2. GET /api/open/goods/new-product?region={region} → new entrants
3. GET /api/open/influencers/commerce-rank?region={region} → top commerce influencers
4. GET /api/open/shops/search?region={region} → top shops

Pattern D: "{店铺} 经营分析" — Shop Performance

1. GET /api/open/shops/search?words={name} → find shop
2. GET /api/open/shops/detail?id={id} → shop info
3. GET /api/open/shops/products?id={id} → product lineup
4. GET /api/open/shops/authors?seller_id={seller_id} → influencer partnerships

Execution rules:

• Execute all planned queries autonomously — do not ask for confirmation on each sub-query.
• Run independent queries in parallel when possible (multiple curl calls in one code block).
• If a step fails with 401/403, check API key validity — do not abort the entire analysis.
• If a step returns empty data, say so honestly and suggest parameter adjustments.

Step 5: Output Results

Browse Mode

Chinese template:

🛒 共找到 {total} 条"{keyword}"相关商品

| # | 商品 | 价格 | 近7天销量 | 销售额 | 达人数 |
|---|------|------|-----------|--------|--------|
| 1 | {title} | ${price} | {sold} | ${amount} | {authors} |
| ... |

💡 试试："分析Top3" | "看看达人" | "切换到东南亚"

English template:

🛒 Found {total} products for "{keyword}"

| # | Product | Price | 7d Sales | Revenue | Influencers |
|---|---------|-------|----------|---------|-------------|
| 1 | {title} | ${price} | {sold} | ${amount} | {authors} |
| ... |

💡 Try: "analyze top 3" | "show influencers" | "switch to Southeast Asia"

Analyze Mode

Adapt output format to the question. Use tables for rankings, bullet points for insights. Always end with Key findings section.

Compare Mode

Side-by-side table + differential insights.

Deep Dive Mode

Structured report with sections. Adapt language to user.

Step 6: Follow-up Handling

Maintain full context. Handle follow-ups intelligently:

Reuse data: If the user asks follow-up questions about already-fetched data, analyze existing results first. Only make new API calls when needed.

Output Guidelines

1. Language consistency — ALL output must match the user's detected language.
2. Route-appropriate output — Don't dump tables for browsing; don't skip data for analysis.
3. Markdown links — All URLs in [text](url) format.
4. Humanize numbers — English: >10K → "x.xK" / >1M → "x.xM". Chinese: >1万 → "x.x万" / >1亿 → "x.x亿".
5. End with next-step hints — Contextual suggestions in matching language.
6. Data-driven — All conclusions based on actual API data, never fabricate.
7. Honest about gaps — If data is insufficient, say so and suggest alternatives.
8. No credential leakage — Never output API key values or internal implementation details.
9. Region awareness — Always mention which market (region) the data is from.

Error Handling