Imported from DannylydST/sorftime-seller-agent (SKILL.md). Install upstream with npx skills add DannylydST/sorftime-seller-agent. Copyright stays with the author.

Sorftime Seller Agent

One skill. Any AI agent. Instant marketplace intelligence for global sellers.

🔴 Language Rule (Mandatory)

Match the user's language. Always. If the user writes in English → respond in English. If the user writes in Chinese → respond in Chinese. Never mix. This overrides everything else in this skill.

Core Positioning

This skill is the single unified entry point for all Sorftime MCP capabilities. It integrates:

• MCP Bridge Layer: Direct access to Sorftime's full suite of data tools (current count in references/tool-matrix.md, auto-synced)
• Intelligence Layer: Product discovery engine, competitor analysis, keyword optimization, profit calculation, monitoring & alerts
• Output Adaptation Layer: Auto-formats results by seller stage (Beginner / Growing / Professional)
• Content Quality Layer: Quality guidelines for AI-generated content output
• Platform Exploration Layer: Automated discovery of Sorftime modules and fields

Users describe what they need — the skill auto-routes to the right scripts and tool chains.

⚠️ MCP Parameter Name Traps (Must Read — Highest Frequency Pitfall)

The same business concept uses DIFFERENT parameter names across different Sorftime tools. With 86+ tools, parameter naming is not consistent between product, keyword, category, and cross-platform tools.

Always verify the actual inputSchema.properties of the target tool before calling it. Never guess parameter names based on what another tool uses.

Most common parameter mismatch errors:

Typical failure scenarios:

• Using product_search's search_name parameter on keyword_detail → fails. Correct: keyword
• Using amz_site on keyword_list → fails. Correct: keyword_support_site
• Using node_id on category_search_from_top_node → fails. Correct: top_node

How to avoid:

1. Check Schema before calling: mcp_client.py has built-in parameter validation + auto-correction. Common aliases (e.g. search_name → keyword) are auto-corrected with a stderr notification
2. If it fails, check parameter names FIRST: An isError response is most likely a wrong parameter name — not a server outage
3. When adding new tools, add aliases: If new tools use different naming conventions, add a mapping in scripts/utils/mcp_client.py's PARAM_ALIASES

🌐 Sorftime International Platform

Platform URL: https://open-intl.sorftime.com — the dedicated international platform for global sellers.

Registration & Account

Product Access

This Skill is MCP-only: exposes Sorftime data tools exclusively via the MCP protocol — no CLI / API product form.

Supported Platforms

Amazon · Walmart · Shopee · TikTok · TEMU · 1688 — across 21 global sites.

🚀 Agent Onboarding Protocol (Mandatory)

Goal: When a user first says "help me find products" or provides a Key, the agent MUST auto-detect → guide → install → retry, without throwing technical errors.

Trigger Conditions (any one triggers onboarding)

1. User explicitly says configuration-related things: "configure Sorftime" / "first time" / "how to start" / "here's my key"
2. User directly provides a Key (any string that looks like an API key)
3. A data request fails with [SORFTIME_ONBOARDING_REQUIRED] or SORFTIME_MCP_KEY not set

Execution Flow (must follow order)

Step 1 — Detect

Run python3 scripts/healthcheck.py to quickly determine which is missing: Key, dependencies, or MCP connection.

Step 2 — Guide to Get Key (if Key is missing)

If the user hasn't provided a Key, proactively provide the acquisition path:

• Registration URL: https://open-intl.sorftime.com — Sorftime International (overseas) platform
• Sign up with Google account or email/password
• After registration, navigate to the MCP page at https://open-intl.sorftime.com/mcp to copy your MCP Key
• New users get free trial credits upon registration — no payment required to start
• Payment options: PayPal (credit card via PayPal)
• Suggested phrasing: "Create a free account at open-intl.sorftime.com (Google login supported), grab your MCP Key from the MCP page, and I'll set everything up. New accounts come with free trial credits."

Step 3 — Auto-Install

Once you have the Key, immediately run:

python3 scripts/install.py --unattended --key <user-provided-Key>

• --unattended ensures no interactive prompts
• Result is JSON: {"status":"ok","key_saved":true,"test_passed":true}

Step 4 — Mandatory Post-Success Action

• If onboarding was triggered by a data request (e.g. "help me find products") → MUST retry the original request and return results to the user
• If onboarding was an explicit user request → confirm success and provide a testable example (e.g. get_time or a simple product search)

Step 5 — Failure Handling

If install.py returns test_passed: false or status: error:

1. Check if the Key was copied completely (common: missing trailing characters)
2. Confirm the Sorftime account has MCP service enabled
3. Check network connectivity to open-intl.sorftime.com
4. Report the specific error to the user with next-step suggestions

First-Time User Guide (Simplified for Users)

FAQ Quick Reference

Scenario Routing Table (Mandatory)

Methodology Card Routing (v3.0)

When users mention specific tactical scenarios, route to the corresponding methodology card for the complete analysis framework. Cards located in references/methodology-cards/.

Methodology Core Principle (Differentiator vs Competitors)

Full ranking, no hard thresholds. Each methodology card uses weighted index full-ranking — a $19.99 product won't disappear because it's $0.01 below a threshold, and a 4.3-star product won't be excluded for being 0.1 above a cutoff. Sellers see the complete picture and make their own decisions.

vs Other Solutions:

🛡️ Parameter Discipline (READ BEFORE ANY TOOL CALL)

The #1 recurring failure: guessing parameters instead of checking the schema. This must stop.

Mandatory: Schema-First Protocol

Before calling ANY Sorftime MCP tool, you MUST verify exactly 3 things:

Common Parameter Traps

Quick Schema Lookup

# Dump any tool's full parameter spec in one line:
python3 -c "
import json, ast, sys
src = open('scripts/sorftime_bridge.py').read()
# Find the tool schema block
start = src.index('\"name\": \"$TOOL_NAME\"')
block = src[start:start+3000]
# Parse out required params and properties
print(block)
"

If a Tool Returns "No relevant data" or Code=10

1. DO NOT conclude "the tool is broken" or "data doesn't exist"
2. DO re-check the 3 schema checks above
3. DO test with the exact parameters from a known-working call
4. Only after verifying correct parameters 3 times → then escalate as possible data gap

Instruction Priority (v3.6.0) — Obey the Seller

The skill is a data tool that follows the seller's instructions. Risk is always advisory — never blocks, never hides (see Four-Tier Risk Advisory System below).

Precise instruction → direct execution (no routing, no cards, no reformatting)

If the request specifies ≥2 of: exact tool / ASIN / keyword / platform / site / output format → EXECUTE DIRECTLY:

• Skip router.py / persona.py stage detection, skip methodology cards, skip lens imposition
• Return exactly what was asked: raw table, sorted-by-sales, JSON, etc.

Examples:

• "product_search for 'yoga mat' US, sorted by monthly sales" → execute + return the table, no added framing
• "raw product_detail JSON for B07H9PZDQW" → return the JSON
• "compare B0X and B0Y price trends, just the numbers" → return the numbers

Ambiguous / exploratory request → guided flow

For vague requests ("find opportunities", "is this category worth it"), THEN: identify stage (persona.py), route to a methodology card, use index-based analysis, present findings + risk advisory.

Output format follows the user

• Wants a report → HTML per-product deliverable (see workspace CLAUDE.md)
• Wants raw data → --json / raw tables
• Wants analysis → analysis
• Default: structured tables (never dump raw JSON unformatted without reason)

Reference Workflow: Closed-Loop Product Selection (opt-in)

v3.6.0: REFERENCE workflow — NOT the default. Runs ONLY when the user explicitly invokes it via /goal, /loop, or says "run the full / closed-loop selection workflow". Daily queries never enter this workflow.

Trigger: /goal / /loop with the workflow, or explicit "closed-loop selection" / "完整选品工作流"

Full spec → references/workflows/closed-loop-selection.md (Phases P0→PG, 7-member Seller Review Panel, data persistence, /loop monitoring). When triggered, follow it exactly — within the workflow, phases are MANDATORY (do not skip).

Quick-start:

/goal /sorftime-seller-agent Execute Closed-Loop Product Selection for {category} on {platform}. Seller: {stage}, ${budget}, {model}, country={cn|us|uk|de|other}. Rounds: {N}.

Execution Principles

1. Obey the instruction first, guide only when ambiguous (v3.6.0): Precise requests (tool+ASIN/keyword/site/output specified) → execute directly, no routing. Only vague/exploratory requests → use router.py / persona.py to identify intent and seller stage, then route to methodology card. Never re-interpret a precise instruction.
2. Ask when information is insufficient: Never guess ASINs, keywords, or marketplaces — ask
3. Schema freshness check: At the first Sorftime usage in each session, run python3 scripts/healthcheck.py. If it reports "Schema is X days old" (>7 days), proactively notify the user: "Schema is X days old — new tools may be available on the server. Sync now?" — only sync after user confirmation (python3 tests/auto_sync.py). Never silently sync (involves file modification). If a tool call returns "not found" or "unsupported", the first step is to suggest syncing Schema
4. Cache-first: Repeated queries auto-hit SQLite cache (~/.sorftime-cache/)
5. Structure results: Raw JSON must be formatted before presenting to users — never dump raw JSON
6. Out of scope: Log unsupported requests to ~/.sorftime-cache/unsupported-requests.log and provide alternatives
7. Batch scenarios: When users say "batch/bulk/monitor/scheduled", use MCP tools with batched calls + Python scripts; space requests appropriately to avoid rate limiting

I. Data Intelligence Layer (Discovery / Competitor / Profit / Monitoring)

1.1 Discovery Engine picker.py

# Default: beginner seller profile (full pool shown + risk badges + safe shortlist highlight)
python3 scripts/picker.py --mode newbie --platform amazon --site US --keyword "kitchen storage"
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "pet supplies"

# Professional profile: same full pool, different emphasis (capital/ops de-emphasized)
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "yoga mat" --profile factory

# v3.0 advisory mode: NO products are hidden. --allow-* flags now tune warning emphasis,
# not "unhide" switches (nothing is hidden by default).
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "dress" --allow-capital

# Independent review of a shortlist (after selection, mandatory for final Go/No-Go)
python3 scripts/review_shortlist.py /path/to/shortlist.json

# View seller profile descriptions
python3 scripts/picker.py --profile-help

Auto-analysis dimensions:

• Brand monopoly (top 3 brands > 40% market share → alert)
• Amazon Basics penetration
• Low-review high-sales opportunities (reviews < 100 but high sales volume)
• Price wars (< $10 clustering → avoid)
• Beginner-friendliness (auto-apply reviews < 500, monopoly coefficient < 40%)
• Quantified risk summary: estimated return rate, initial capital requirement, inventory turnover days, brand concentration, new product survival rate, price dispersion

Four-Tier Risk Advisory System (v3.0):

v3.0 change: risk is now advisory, not blocking. Products are NEVER hidden. Every product gets a risk badge (🔴hard / 🟡capital / 🟠ops / ⚠️trap / 🟢safe) and a specific warning surfaced AFTER the results. You (or an independent review agent) make the final call — the tool informs, it does not censor. This matches the skill's own "no hard thresholds, full-set ranking" principle.

Seller Profiles (tune emphasis, never hide data — v3.6.0 adds risk folding for pros):

Other categories (advisory notes, always informational):

• Accessories (hats/scarves/gloves/socks/belts): 5-15% return rate
• Eyewear/sunglasses: 10-20% return rate, prescription/style issues
• Phone cases/screen protectors: extreme red ocean, razor-thin margins, patent minefield
• Stationery/office supplies: low ASP, thin margins, commoditized
• Holiday decorations: extremely short sales window, post-season inventory risk
• Books/CD/DVD: low margins, shrinking market

Transparent risk surfacing: Every flagged product shows its specific reason and risk level. No product is hidden — the full pool stays visible, and the Risk Advisory table explains each flag.

1.1.5 Post-Selection Independent Review (Mandatory)

Since v3.0 removed hard interception, the review burden moved to a dedicated review step that runs AFTER selection and is INDEPENDENT of the discovery model. The same engine that found the products must not be the only judge of them.

Rule: after picker.py produces a shortlist (or after Phase E of the Closed-Loop workflow), run BOTH review layers before presenting a final recommendation:

Step 0 — Reality-check candidate data (always):

# Batch-verify each candidate's REAL product_detail (picker table price ≠ actual).
# In-process call, retry+stagger, auto-unwraps the {"doc","data"} envelope.
python3 scripts/verify_candidates.py --input /path/to/asins.txt --out /path/to/verify_raw.json --brief
# asins.txt = one ASIN per line (or asins.json = list of strings / {"asin": ...} dicts)

Layer 1 — Deterministic independent review (fast, always):

# picker.py now writes the annotated shortlist to JSON:
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "yoga mat" \
    --profile newbie --json /path/to/shortlist.json

# Then run the independent reviewer (pass the original keyword for relevance check):
python3 scripts/review_shortlist.py /path/to/shortlist.json --keyword "yoga mat"

The reviewer checks dimensions the discovery model does NOT: category-relevance (flags keyword-pollution products — e.g. supplements returned for a "yoga mat" query), margin sanity, IP/trademark terms, review anomalies, seasonal windows, and compliance red flags. It emits GO / CAUTION / NO-GO per product — advice, never removal.

Layer 2 — Independent review sub-agent (rigorous, mandatory for final Go/No-Go):

1. Spawn an independent sub-agent with fresh context (do NOT reuse the conversation that found the products — fresh context is what makes the review independent).
2. Give it ONLY: the shortlist + the risk badges + the review_shortlist.py output. Do NOT feed it your reasoning.
3. Ask it to red-team the top picks: challenge the GO verdicts, check the flagged products against the seller's profile/country, and return a final per-product verdict.
4. The main agent may disagree, but must document the dissent. No product is hidden by review — the review informs the recommendation, it never deletes data.

Closed-Loop workflow: Phase D2 already implements this at scale (7 sub-agents, parallel vote). For quick picks (picker.py path), Layer 1 + a single Layer 2 sub-agent is sufficient.

1.2 Analyst Engine analyst.py

python3 scripts/analyst.py --mode competitor --platform amazon --site US --asin B07H9PZDQW
python3 scripts/analyst.py --mode keyword --platform amazon --site US --keyword "yoga mat"
python3 scripts/analyst.py --mode market --platform amazon --site US --node-id 1064954

1.3 Profit Calculator calculator.py

python3 scripts/calculator.py --platform amazon --price 29.99 --cost 8.5 --weight 1.2

Output: gross margin, break-even daily sales, return rate sensitivity. FBA fee is estimated by weight — verify with actual dimensional weight from product detail.

1.4 Monitoring Engine monitor.py

python3 scripts/monitor.py --mode add --type asin --value B07H9PZDQW --platform amazon --site US
python3 scripts/monitor.py --mode daily
python3 scripts/monitor.py --mode alert

1.5 Walmart Discovery Engine walmart_picker.py

# Walmart blue ocean discovery (default: newbie profile, strictest filtering)
python3 scripts/walmart_picker.py --mode blueocean --keyword "yoga mat"

# Walmart beginner-friendly discovery (reviews < 200, price $15-40)
python3 scripts/walmart_picker.py --mode newbie --keyword "kitchen storage"

# Growing seller profile (Hard+Capital warnings prominent, Ops de-emphasized)
python3 scripts/walmart_picker.py --mode blueocean --keyword "yoga mat" --profile grower

# Factory-direct seller profile
python3 scripts/walmart_picker.py --mode blueocean --keyword "toy" --profile factory

Walmart-specific adaptations:

• Review threshold < 200 (Amazon is < 500), reflecting Walmart's overall lower review counts
• Auto-analyzes Walmart self-operated (1P) share, WFS penetration
• Reuses the four-tier risk advisory system (v3.5.0 — never hides products)

1.6 Walmart Analyst Engine walmart_analyst.py

# Competitor analysis (detail + traffic keywords + sales/rating trends)
python3 scripts/walmart_analyst.py --mode competitor --product-id 15689567602

# Keyword analysis (detail + long-tail keywords + top products)
python3 scripts/walmart_analyst.py --mode keyword --keyword "toilet paper"

# Market analysis (category report + top product profiles + category overview)
python3 scripts/walmart_analyst.py --mode market --node-id 5438

II. Output Adaptation Layer (Seller Stage Detection & Formatting)

Must call persona.py first to identify stage:

python3 scripts/persona.py --text "I'm a beginner, looking for blue ocean products on Amazon US"

Then format by stage:

python3 scripts/stage_formatter.py --stage beginner --input /tmp/result.md

III. Content Quality Layer

When the user asks "review my content" / "quality check", follow these guidelines:

Step 1: Context-Aware Review

• Check if the content references specific data points without citing them
• Verify any competitive claims are substantiated
• Ensure tone and format match the intended audience (sellers, developers, etc.)

Step 2: Quality Dimensions

A. Factual Accuracy

Verify any data claims, statistics, or assertions against available Sorftime data.

B. Actionability

Does the content enable the reader to take a specific next step? Vague advice → flag for improvement. Concrete, data-backed guidance → passes.

C. Brand Consistency

Does the content align with Sorftime's positioning as AI-Powered Marketplace Intelligence?

D. Audience Fit

Is the technical depth appropriate for the target audience (beginner/growing/pro)?

Step 3: Output Scoring (0-100)

IV. Platform Exploration Layer (Feature Map / Field Verification)

When user says "explore Sorftime" / "what features are available" / "available fields" / "verify fields":

# Example: extract all field definitions from a page
node scripts/explorer/content-capture.js <url>

Core principles:

• One module at a time
• Existence ≠ usable — must click to verify
• Use checkbox to select data rows (5+ rows) to trigger comparison
• Save checkpoint after each tab switch
• *.sorftime.com goes DIRECT (no proxy)

V. MCP Bridge & Operations Layer

5.1 Installation

python3 scripts/install.py

Auto-completes: virtual environment creation, CC/OpenClaw detection, prompts for SORFTIME_MCP_KEY, connection test, config snippet output.

5.2 Tool Invocation

本 Skill 通过 MCP 协议对外暴露 86 个工具：sorftime_bridge.py 是 stdio MCP server，由 install.py 自动注册到 agent（mcporter.json）。agent 直接通过 MCP 协议调用工具，无需 CLI。

脚本内部（picker/analyst 等）与手动调试时，用 --one-shot 底层接口直接调单个工具（非对外交互方式）：

# Test connection（脚本内部 / 调试用）
python3 scripts/sorftime_bridge.py --one-shot get_time '{}'

# Product search
python3 scripts/sorftime_bridge.py --one-shot product_search '{"amz_site":"US","search_name":"kitchen storage"}'

# Hidden Profit Index ⭐ (Sorftime 独家方法论)
# 全品类跨排名 — 综合评分发现被忽视的高利润潜力产品。不传 search_name 即为全品类拉通排序
python3 scripts/sorftime_bridge.py --one-shot potential_product '{"amz_site":"US"}'

# Hidden Profit Index — 关键词/类目内筛选
python3 scripts/sorftime_bridge.py --one-shot potential_product '{"amz_site":"US","search_name":"yoga mat"}'

5.3 Full Test Suite

python3 tests/run_tool_tests.py

5.4 Schema Auto-Sync

When Sorftime MCP server updates tools (add/remove/modify schemas), the skill auto-detects and syncs.

# Full sync: fetch server schema → diff → generate → apply
python3 scripts/sync_manager.py full

# Detect changes only (no writes)
python3 scripts/sync_manager.py diff

# Auto-sync entry (executes when changes detected)
python3 tests/auto_sync.py

Sync scope:

• scripts/sorftime_bridge.py — update _FALLBACK_CORE_TOOLS with latest server schema
• references/tool-matrix.md — regenerate categorized tool matrix
• tests/fixtures/*.yaml — update test case parameter structures
• ~/.sorftime-cache/schema-store/ — versioned storage, supports rollback

Each sync auto-creates backup in .sync-backups/, with one-click rollback:

python3 scripts/sync_manager.py rollback YYYYMMDD_HHMMSS

5.5 Drift Detection

python3 tests/drift_detector.py

Compares local references/tool-matrix.md against scripts/sorftime_bridge.py's _FALLBACK_CORE_TOOLS. Alerts on inconsistency. Note: this checks local file consistency only, not against the server.

VI. Multi-Platform Parameter Quick Reference

Amazon parameter name traps (3 different names for "marketplace"):

• amz_site: 19 tools (product_search, product_detail, category_report, potential_product, etc.)
• keyword_support_site: 12 tools (keyword_detail, keyword_extends, keyword_search_results, keyword_list, etc.)
• site: 1 tool — product_customers_say (⚠️ exception to the Amazon convention)
• All 14 Amazon sites verified in schema; SG is NOT in the enum (contrary to older docs).

Walmart Tool Usage Guide

Walmart marketplace parameter is always site, currently supports US. All Walmart tools prefixed with walmart_.

Core Query Tools:

Favorites Tools:

Key Field Notes:

• trend_type enum values: SalesVolume / SalesAmount / Price / Rank / Reviews / Star — cannot use Chinese values
• rank_min/rank_max in walmart_keyword_list are required — server errors without them
• node_id format: Walmart category IDs may contain underscores (e.g. 1072864_8490340), type string
• Product detail's NodeTree field can reverse-lookup category: ["Category Name", "node_id", "Date", "Rank"]

Known Limitations:

• walmart_product_variation_sales_by_product_id: some products without variants return "no relevant data"
• walmart_category_report_by_node_id: invalid node_id returns "no relevant data" — extract valid IDs from NodeTree or search results
• Favorites tools return "no relevant data" when keyword list is empty

VII. Gotchas

• MCP SDK version lock: This skill requires MCP 1.x (not 2.x). requirements.txt locks to mcp>=1.0.0,<2.0.0. MCP 2.x has breaking API changes (Server → MCPServer, stdio_server signature change). If bridge startup shows "MCP 2.x is not yet supported" or AttributeError: 'Server' object..., run python3 scripts/install.py --upgrade to downgrade to 1.x.
• Schema auto-sync: healthcheck.py checks schema freshness. If it reports "Schema is X days old", run python3 tests/auto_sync.py to pull the latest tool list — the server may have added new tools. Sync updates references/tool-matrix.md, sorftime_bridge.py schemas, and tests/fixtures/. Recommended: weekly, or immediately when a tool call returns "tool not found"
• When SORFTIME_MCP_KEY is not set, the bridge raises RuntimeError — configure the env var or run install.py first
• potential_product (Hidden Profit Index ⭐ — Sorftime exclusive methodology). search_name parameter is optional: omit for all-category cross-ranking, include to filter within a keyword's search results. Returns potential_index — a composite recommendation score (relative value), not a single-dimension absolute metric. Higher scores indicate stronger overall performance across "low entry barrier, low ad spend, high profit margin" dimensions. When explaining to sellers, focus on the logic behind the index (finding overlooked high-profit products), not per-dimension breakdown calculations. ⚠️ CRITICAL: A high HPI score does NOT override category risk. Always cross-check results against the four-tier risk advisory (hard/capital/ops/trap) before presenting to sellers. Food, supplements, electronics compliance, seasonal products, and licensed/branded goods must be flagged prominently (never hidden — v3.5.0 advisory) regardless of HPI, and challenged in the independent review step. See references/methodology-cards/tactical/invisible-profit.md#risk-notes for the full advisory table
• Amazon keyword tools (keyword_detail / keyword_extends / keyword_search_results) use keyword_support_site for marketplace; all other Amazon tools use amz_site. ⚠️ Exception: product_customers_say uses site (not amz_site), the only Amazon tool to do so. See the "MCP Parameter Name Traps" section above — parameter name mismatches are the #1 cause of call failures
• TikTok Shop currently does not provide product_search; direct search needs to product_detail or category_report
• ⚠️ TikTok has NO category_tree endpoint (unlike Amazon/Shopee/TEMU). The two search tools (tiktok_category_name_search / tiktok_category_search_from_name) only discover leaf-level categories by keyword — they cannot enumerate top-level categories or traverse parent-child hierarchies. Exact-matching official top-level names (e.g. "Beauty & Personal Care") returns nothing or unrelated leaves. This is a known server-side gap. See references/tiktok-rankings.json for the pre-computed workaround.
• TikTok category discovery SOP (always tier 1 first):
  1. TIER 1 (0s, 0 API calls): Read references/tiktok-rankings.json — pre-computed rankings of 228 leaf categories with monthly sales, MoM, avg price, and heuristic parent-category aggregation. Covers the vast majority of active categories. Use for: "top categories", "what's selling", market overview questions.
  2. TIER 2 (~1min, batch API): python3 scripts/discover_tiktok.py --sweep — parallel keyword scan to refresh or expand category coverage. Use when: rankings are stale (>7 days) or searching for a niche not in the rankings. Auto-persists to references/tiktok-categories.json.
  3. TIER 3 (per-call API): python3 scripts/discover_tiktok.py <keyword> — single-keyword search. Use for: targeted lookup of one specific category name. Do NOT use for broad discovery — TIER 2 is faster and more complete. Anti-patterns: Do NOT iterate letters brute-force. Do NOT call tools without site. Do NOT expect exact-match top-level category names to work.
• Shopee trend tools return flat interleaved arrays, not [{date, value}] objects. Both shopee_category_trend and shopee_product_trend return [date1, val1, date2, val2, ...]. Parse by pairing: list(zip(data[::2], data[1::2])). Date elements are integers in YYYYMMDD format (daily) or YYYYMM (monthly), not ISO strings. shopee_product_trend accepts optional query_start / query_end (format yyyy-MM-dd) to scope the date range; omitting them defaults to ~1 year.
• Shopee shopee_category_trend has 72+ trend_index values (default: MonthlySalesVolume). Key ones: MonthlySalesVolume, MonthlySalesAmount, AveragePrice, AverageStarRating, SellerCount, BrandCount, FlagshipStoreRatio, plus time-windowed variants (Listed1Month*, Listed3Month*, Top3*, Top10*). Always check the schema enum for the full list — it's extensive and covers market concentration, new-product dynamics, and store-type breakdowns.
• Shopee shopee_keyword_search looks up the keyword index, not product listings. It accepts partial/prefix matching (e.g. "phone" finds "phone lanyard"; case-insensitive). Multi-word phrases like "phone case" may return no data if they aren't indexed as a keyword. To browse hot keywords without a search term, pass {"rank_min": 1, "rank_max": N}. For product discovery by freeform search term, use shopee_keyword_relation_results — note this returns products (with fields: title, product_id, sales_count, price, ratings, shop_name), not related keywords, despite the tool name.
• TikTok tiktok_category_report top50 products do NOT include product_id — the report is market overview only (title/brand/sales/price/seller/ratings). To get a product_id for detail/trend/video analysis, use tiktok_product_detail or discover via keyword search.
• TEMU product field is product_name (not title like Amazon/Shopee). temu_category_request returns product_id + product_name, usable for downstream temu_product_trend / temu_product_request.
• Shopee shopee_product_search shop_location parameter: 1=本土店 (local), 2=跨境店 (cross-border). Use for cross-border feasibility analysis — compare page_count between the two. Response is nested: data.products[] not data[].
• Shopee keyword favorites tools return raw arrays (not {doc, data} wrapper). shopee_favorite_keyword add returns "Favorite succeeded" in error-format JSON. shopee_get_favorite_keyword_dict returns ["dict_name", ...], shopee_get_favorite_keyword returns ["keyword", ...]. Don't expect the standard response envelope.
• Shopee site enum (8 站全部实测通过): MY, PH, VN, TH, ID, SG, TW, BR (plus UnKonw default). All 15 Shopee tools share the same site list. Always pass site explicitly — it's optional in schema but server behavior without it is inconsistent.
• 脚本内部编程调用（Python API）: 脚本（picker/analyst 等）内部通过 call_tool_json 调用 MCP 工具（底层封装 --one-shot 直连，处理所有路径/env 复杂度）：

  import sys; sys.path.insert(0, 'scripts')  # REQUIRED — utils is under scripts/
  from utils.mcp_client import call_tool, call_tool_json

  call_tool(name, args) returns str. call_tool_json(name, args) returns parsed dict. Do NOT try import MCPClient or import mcp_client — those names don't exist. Never run python3 -c "from utils..." from outside the skill root directory.
• Some Sorftime tools return Chinese narrative prefix before JSON — utils/mcp_client.py and sorftime_bridge.py handle this parsing
• Requests beyond registered tool scope: utils/mcp_client.py auto-remaps deprecated tools or intercepts with alternatives
• mcporter HTTP transport may intermittently break on large responses — complex queries prefer the bridge --one-shot direct-call path (the same path scripts use internally)
• picker.py defaults to --profile newbie (strictest filtering). Switch profiles via --profile grower/pro/factory/brand or use per-category overrides (--allow-capital / --allow-ops). Filtered products are listed in report with specific risk level and reason
• --explicit-category is backward-compatible, equivalent to --allow-capital --allow-ops
• Schema auto-sync: sorftime_bridge.py loads dynamic schema from schema_store on startup; falls back to _FALLBACK_CORE_TOOLS if never synced. Run python3 tests/auto_sync.py regularly
• Walmart trend_type must be in English: walmart_product_trend_by_product_id's trend_type uses English enum values (SalesVolume/SalesAmount/Price/Rank/Reviews/Star) — cannot use Chinese. Server returns "please enter the trend type to query" if omitted
• Walmart rank_min/rank_max required: walmart_keyword_list requires both rank_min and rank_max. Recommended range 1-100, 100 results per page
• Walmart category ID format: node_id is string, may contain underscores (e.g. 1072864_8490340). Extract from product detail's NodeTree: ["Category Name", "node_id", "Date", "Rank"]
• Walmart data scope: search results cover last 15 days of organic-ranking products, sorted by monthly sales descending. Traffic keyword data includes ShowShare (impression share) and RecentlyPosition/OrganicPosition/AdPosition (recent/organic/ad rank positions)
• CRITICAL: product_traffic_terms field trap (2026-08-04). The API returns exposure_position ("Organic"/"Ad"/"Ad,Organic"), latest_organic_position, monthly_search_volume, recommended_bid. There is NO field called organic_searched_percentage. Querying it returns null/0, falsely suggesting zero organic traffic. Use: count keywords where exposure_position contains "Organic" + check latest_organic_position for rank quality. 20/20 organic + 7/20 ad = organic-driven. 20/20 organic + 18/20 ad = buys visibility.
• product_trend returns comma-separated key=value text, NOT JSON. Format: "2024年08月=347,2024年09月=155,...". Fixed in bridge v3.4.1: run_one_shot() and call_tool_json() now auto-parse this format into {"2024年08月": 347, ...}. If you encounter {"error": true, "hint": "Server returned non-JSON"} from product_trend, update the skill (git pull) to get the fix.
• Amazon product_reviews is capped at ~100 reviews and has NO page parameter — schema is only ['amz_site','asin','review_type']. To sample more sentiment, use review_type (Both/Positive/Negative) rather than trying to paginate. May return "No reviews found" on low-volume ASINs. The tool returns rich review data (variant_attribute/review_date/star_rating/title) when available. product_traffic_terms + competitor_product_keywords confirmed working (keyword-level search volume/bid/exposure data). similar_product_feature uses product_name parameter (not asin — auto-corrected). product_customers_say uses site (not amz_site) — the only Amazon tool diverging from both amz_site and keyword_support_site. category_report_from_history and category_keywords returned no data in tests — possibly limited server-side historical/ keyword coverage.
• Amazon product_variations returns child ASINs but variant attributes may be empty — the tool returns 55+ child ASINs but attribute and month_sales_volume_range may be blank for some products. Verify data quality before using.
• Walmart walmart_product_trend_by_product_id and walmart_product_variation_sales_by_product_id return raw interleaved arrays like Shopee trend tools: [date, val, date, val...]. 730 daily data points for trends, 62 for variation sales. Parse with zip(data[::2], data[1::2]).
• 1688 tools have 5 endpoints (verified 2026-07-30): ali1688_similar_product (keyword search, returns 100 items with title/price/product_id/store_name/service_score/sales_of_30d), ali1688_product_search (multi-dimension filter with 20+ params including supplier_type:1=实力商家/2=超级工厂, repurchase_rate, rights: "1,2,3", service_score), ali1688_product_request (detail: price/moq/supplier_info, 16 fields), ali1688_product_variations (SKU breakdown: price/stock/weight/dimensions per variant), ali1688_product_search_from_image (reverse image search). ali1688_product_search params are all optional — pass none to browse, or combine filters for precision sourcing. Supplier type codes: 1=实力商家, 2=超级工厂.

VIII. Tool Matrix

Complete tool list and counts in references/tool-matrix.md (auto-sync generated, always matches server).

Core frequently-used tools: get_time, category_report, product_search, product_detail, product_reviews, product_variations, product_traffic_terms, keyword_detail, keyword_search_results, keyword_extends, potential_product, category_name_search, category_search_from_top_node, similar_product_feature, competitor_product_keywords, ali1688_similar_product, tiktok_category_report, tiktok_product_detail, sorftime_raw_call

Walmart core tools (15): walmart_keyword_search_results, walmart_keyword_detail, walmart_keyword_list, walmart_keyword_extends, walmart_keyword_search_from_name, walmart_product_detail_by_product_id, walmart_product_traffic_terms, walmart_product_trend_by_product_id, walmart_product_variation_sales_by_product_id, walmart_category_report_by_node_id, walmart_favorite_keyword, walmart_get_favorite_keyword, walmart_get_favorite_keyword_dict, walmart_change_favorite_keyword, walmart_del_favorite_keyword

Walmart is US-only: none of the 15 Walmart tools have a site parameter — the marketplace is hardcoded to US. No parameter needed.

1688 is China-only: 5 tools, no site parameter. Factory-direct sourcing only.

TEMU currently supports US + EU only (2 sites). TEMU has the richest category-level filtering (40+ optional filter params on temu_category_search).

TikTok site availability varies: 8 sites in the schema, but VN returns "No data available" for category searches. GB/JP/ID/MY/PH/TH/US confirmed working.

IX. Cross-Platform Adaptation & Migration

This skill is cross-platform compatible, supporting macOS / Linux / Windows.

Environment Variables (Optional)

Migrating to a New Device

1. Copy the skill directory to the new machine
2. Ensure Python >= 3.10 is installed
3. Run python3 scripts/install.py to rebuild the virtual environment
4. Provide SORFTIME_MCP_KEY, or manually write to the skill root .env

Auto-Detected Agent Environments

Claude Code, OpenClaw, Cowork, Claude.ai Web, and other mainstream environments are auto-detected — no manual configuration needed.

Related Files

• scripts/utils/platform_utils.py — Cross-platform utility functions
• scripts/utils/version.py — Version management
• requirements.txt — Dependency list