uniprofit-trade-search（单一盈利贸易搜索）

UniProfit Trade Search

Use this skill to query UniProfit trade data from the OpenClaw runtime.

Quick Start

Required environment variables:

• UNIPROFIT_API_BASE_URL
• UNIPROFIT_TRADE_SEARCH_KEY

Credential format:

X-UniProfit-Key: {UNIPROFIT_TRADE_SEARCH_KEY}

Read only what you need:

• Read references/api.md for request and response formats.
• Read references/query-patterns.md when the user's search intent is vague.
• Read references/error-handling.md when an API call fails or returns no data.

Protocol Contract

For runtime execution, follow this protocol exactly.

Use only these runtime endpoints:

• GET {UNIPROFIT_API_BASE_URL}/openclaw/credential/me
• POST {UNIPROFIT_API_BASE_URL}/openclaw/search/query

Execution checklist:

• send authentication with X-UniProfit-Key
• send search requests as POST
• send search requests with a JSON body
• keep source, filters, page, and page_size in the request body

Do not replace this skill with generic supplier-search or buyer-search endpoints.

Canonical runtime pattern:

1. validate the credential if needed with GET /openclaw/credential/me
2. build a query plan
3. execute search with POST /openclaw/search/query
4. summarize the current result window

Run scripts/check_credential.py if the credential may be missing or invalid.

Use This Skill When

• the user wants overseas buyer or importer leads
• the user wants exhibition lead records
• the user wants procurement or sourcing requirement records
• the user wants structured trade search against UniProfit-owned datasets

Do not use this skill for:

• sending emails
• generating email drafts
• general web research outside UniProfit data

Planning Rules

Prefer structured filters over broad searches.

Use a two-step workflow:

1. build an internal query plan
2. execute the query only if the plan is reliable enough

Do not turn every natural-language request directly into an API call.

Choose one source first:

• importers for importers or buyers
• exhibition for exhibition leads
• requirements for procurement demand

Use only supported filters for the chosen source:

• importers: company_name, country_code, hs_code, hs_codes, date_period, is_verified
• exhibition: fair_name, state, company_name, procurement_category, contact_person
• requirements: country, purchase_title, purchasing_unit, keyword, min_amount, max_amount, currency

Important:

• importers does not support keyword
• product keyword search should usually use requirements
• if the user wants buyer search by product on importers, prefer HS code first

Language strategy:

• first query with the user's original wording
• if the first query returns no result, allow one language-aware fallback that better matches the likely storage language of the chosen source
• do not immediately translate everything into English by default
• do not chain many multilingual retries

Do not send unsupported filters. The backend rejects them with 400.

If the user does not specify a source, choose the best fit and state it briefly.

Before calling the API, decide these four items internally:

• recommended source
• recommended filters
• confidence level
• whether one critical field is still missing

If confidence is low, ask the user one short clarifying question instead of querying immediately.

If confidence is medium or high, query once with the best structured plan.

For product-style requests:

• product keyword + buyer intent: prefer requirements first unless the user already has HS code
• product keyword + explicit HS code: use importers
• company lookup: use importers
• fair or exhibitor lookup: use exhibition

Execution Flow

1. Read the user request and infer buyer search, exhibition search, or demand search intent.
2. Build a query plan:

- source - filters - confidence - missing critical field, if any

1. If one critical field is missing and the plan is weak, ask one short question.
2. Otherwise run scripts/search_trade.py, or make the same protocol call to POST /openclaw/search/query with X-UniProfit-Key and a JSON body.
3. If the first query returns no result, allow one fallback retry using the same source with a closer language match for that source.
4. Summarize the search source, filters, current window size, whether more results may exist, and the best leads.
5. If there are still no results, suggest one narrower or broader retry based on the same plan.

Planning Heuristics

Prefer these planning rules:

• If the user says buyer / importer / customer and gives company-like terms, choose importers.
• If the user gives a fair name, exhibitor context, or exhibition lead request, choose exhibition.
• If the user gives product words without HS code, especially for demand discovery, choose requirements.
• If the user asks for buyers by product but only gives a plain product phrase, do not send keyword to importers.
• If the user asks for buyers by product and also gives HS code, use importers with hs_code or hs_codes.
• If the user gives only country + generic product phrase and no HS code, prefer one short clarifying question over a blind importers query.
• For requirements, keep the user's original country and product wording on the first attempt when the database is likely to store those fields in the same language.
• Use at most one language fallback after a zero-result first attempt. Example: keep 哈萨克斯坦 + 家居用品 first, then try one closer storage-language fallback such as household if needed.

Output Style

Start with:

• source searched
• filters applied
• current window result count
• whether more results may exist

Then present the most actionable rows. Prioritize company name, geography, contact clues, and product relevance.

For requirements results, prefer showing:

• purchase_title
• purchasing_unit
• email when present
• country
• deadline
• amount and currency when present

Describe results as a current query window rather than a complete database count. If the runtime response includes has_more, explain that more matching results may exist and guide the user to narrow the filters for a more focused next step.

Preferred wording pattern:

• This query returned {returned_count} results from {source}.
• if has_more = true: More matching results may be available beyond the current window. Narrow the filters to continue with a more focused search.
• if query_hint exists: restate it as the next best search refinement suggestion

Do not dump raw JSON unless the user asks for it.