| name | linkfox-seerfar-ozon-keyword-mining |
| description | Seerfar Ozon 关键词挖掘：围绕一个种子关键词挖掘 Ozon（及 Wildberries）相关关键词，并按搜索热度、增长、商品数、卖家数、竞品数、价格、相关度、标题密度、加购转化等多维指标筛选，返回每个挖掘词的月搜热度、增长、市场空间、竞品/卖家数、均价、加购转化、Top 商品等市场画像，用于 Ozon 选词拓展、长尾词挖掘与种子词机会分析。当用户提到 Ozon 关键词挖掘、Ozon 选词拓展、Ozon 长尾词挖掘、围绕某词找相关词、Ozon 蓝海词挖掘、Seerfar Ozon、Ozon keyword mining, Ozon keyword expansion, Ozon related keywords, mine Ozon keywords 时触发此技能。即使用户未明确提到"Seerfar"，只要其意图是围绕一个种子词挖掘 Ozon 相关关键词并查看市场画像，也应触发此技能。 |
Seerfar Ozon Keyword Mining
This skill mines Ozon marketplace keywords around a seed keyword in the Seerfar analytics database and filters the discovered terms by rich performance metrics — search volume, 30-day growth, product/seller/competitor counts, average price, relevancy, title density, cart-add conversion, and more. Each mined keyword carries a full market profile (market space, return/cancellation rate, top products, Chinese translation), making it the starting point for Ozon keyword expansion, long-tail discovery, and seed-term opportunity analysis.
Core Concepts
Seed-driven, not market-browse: unlike a market keyword search, this endpoint requires a keyword (the seed) and returns terms related to that seed, each enriched with market metrics. You expand outward from a term you already have in mind.
Relevancy is the mining signal: relevancy scores how closely a mined term relates to the seed (the seed term itself returns at relevancy: 100, related terms rank lower); titleDensity reflects how densely the term appears in product titles. Both are populated on every row — sort by relevancy DESC to keep expansions on-topic.
Platform coverage: each keyword record carries a platform field (0 = Ozon, 1 = Wildberries). The dataset is Ozon-centric; Wildberries rows appear where available. There is no input to restrict the platform — filter client-side if needed.
Match mode: matchType controls how the seed keyword (and includeKeywords) are matched — 0 exact, 1 fuzzy. Choose fuzzy to broaden the expansion, exact to stay tight.
No date or category selectors: this endpoint does not accept searchDate or categories. If you need month-over-month or category-scoped browsing, use the market keyword search skill instead.
Parameters
| Parameter | Type | Required | Description |
|---|
| keyword | string | yes | Seed keyword; mining expands around it (maxLength 1000). |
| page | object | yes | Pagination {page, pageSize, orders[]}. page from 1 (default 1), pageSize default 20. orders[] = {field, direction} with direction DESC/ASC. |
| matchType | integer | no | Keyword match mode: 0 exact, 1 fuzzy. |
| includeKeywords | array | no | Terms that must appear (max 1000); narrows the expansion. |
| excludeKeywords | array | no | Terms to exclude (max 1000); removes irrelevant expansions. |
| wordCount | {min,max} | no | Keyword word/char count range. |
| searchVolume | {min,max} | no | Monthly search volume range. |
| searchChange30 | {min,max} | no | 30-day search change range. |
| productViews | {min,max} | no | Product view range. |
| products | {min,max} | no | Product count range. |
| sellers | {min,max} | no | Seller count range. |
| price | {min,max} | no | Average price range. |
| marketSpace | {min,max} | no | Market space range. |
| conversionSharing | {min,max} | no | Conversion concentration range. |
| relevancy | {min,max} | no | Relevancy-to-seed range. |
| uniqQueriesWCa | {min,max} | no | Cart-add count range. |
| ca | {min,max} | no | Cart-add conversion rate range. |
| titleDensity |
All range filters are {min, max} objects; supply either or both bounds. keyword and page are both required.
调用方式
- API 端点：
POST /seerfar/ozon/keywordMining（完整参数/响应/错误码见 references/api.md）
- Python 脚本：
python scripts/seerfar_ozon_keyword_mining.py '<JSON 参数>' [--inline]
- 成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。
输出策略（脚本默认行为）：
- 始终将完整响应写入
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-keyword-mining-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如
total/costToken、最大列表字段的长度 + 前 3 条样本）
- 加
--inline 强制全量打印到 stdout（同样落盘）
读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
解决认证和积分问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：
异常情况
- 未配置API Key：环境变量未配置
LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
- 响应401或402状态码
- 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。
Usage Examples
1. Expand around a seed term (sort by search volume)
{"keyword": "платье", "page": {"page": 1, "pageSize": 10, "orders": [{"field": "searchVolume", "direction": "DESC"}]}}
2. Blue-ocean expansions — high volume, few sellers
{"keyword": "телефон", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "searchVolume", "direction": "DESC"}]}, "searchVolume": {"min": 10000}, "sellers": {"max": 50}}
3. Keep expansions on-topic with relevancy + title density
{"keyword": "наушники", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "relevancy", "direction": "DESC"}]}, "relevancy": {"min": 50}}
4. Narrow with include / exclude lists
{"keyword": "часы", "page": {"page": 1, "pageSize": 20}, "includeKeywords": ["женские"], "excludeKeywords": ["ремень"], "matchType": 1}
How to Build Queries
- Always lead with the seed
keyword: it is required and defines the expansion center. Pass it in Russian for Ozon.
- Lead with
page.orders: sort by the metric you care about (searchVolume DESC for popularity, relevancy DESC for on-topic, sellers ASC for low competition).
- Stack range filters to find opportunities: combine a high
searchVolume floor with a low sellers ceiling to surface blue-ocean expansions; add relevancy / titleDensity bounds to keep them relevant to the seed.
- Use
includeKeywords / excludeKeywords to steer the expansion: force in must-have modifiers and strip noise without running a second query.
Display Rules
- Present data only: show mined-keyword metrics in a clear table without subjective advice.
- Lead with keyword columns:
query / queryCn (Chinese translation), then searchVolume, count30GrowthRate, productCount, sellers, avgPrice; show relevancy to convey closeness to the seed (the seed term itself is 100).
- Russian keywords: preserve the original
query; the queryCn field provides a Chinese translation when available.
- Platform tag: when both Ozon and Wildberries rows are present, show
platform (0/1) so the user can distinguish them.
- Large result sets: when
total is large, show the top rows and remind the user they can persist the full response via the large-response pattern below, or page further with page.page.
- Error handling: when
code is not 200 (or errcode is not 200), explain the reason from msg / errmsg and suggest adjusting the seed keyword or filters.
Important Limitations
keyword + page required: a payload missing either is rejected.- No date selector: there is no
searchDate; you cannot pick a data month here. Use the market keyword search skill for month-scoped data.
- No category selector:
categories is not accepted as input; each returned keyword carries a categories ID array you can group or filter client-side.
dimension / categoryInfos not returned: both are defined in the schema and appear as columns, but real data[*] rows do not populate them on this endpoint. (categoryInfos IS populated on the sibling market-keyword-search endpoint — don't assume parity.)- Nested fields:
products[*] (Top 商品) is structured and decision-useful — see references/api.md for sub-fields. (categoryInfos[*] is documented there for schema completeness but is not returned on this endpoint; dimension / columns are opaque or partially populated.)
User Expression & Scenario Quick Reference
Applicable — seed-driven Ozon keyword expansion:
| User Says | Scenario |
|---|
| "围绕 XX 词挖一下 Ozon 相关词" | Seed-keyword expansion |
| "Ozon 长尾词挖掘 / 拓展某个词的长尾" | Long-tail mining around a seed |
| "Ozon 某词的蓝海拓展词、低竞争高搜索" | Blue-ocean expansion (high volume, few sellers) |
| "Ozon 跟 XX 相关的词有哪些、相关度高的" | Relevancy-ranked expansion |
| "Ozon 某词拓展，但排除/必须包含某些词" | Include/exclude steered expansion |
Not applicable — Needs beyond seed-driven keyword mining:
- Browse/rank the whole market's hot keywords without a seed → use the Seerfar Ozon market keyword search skill.
- A specific SKU's price/sales/stock → use a product-level Seerfar Ozon data source.
- A specific seller's catalog → use a seller/shop-level Seerfar Ozon data source.
- Month-over-month or category-scoped keyword browsing → use the market keyword search skill (supports
searchDate / categories).
Boundary judgment: if the user wants to expand outward from a seed term and rank the related terms by market metrics, start here. If they want to browse the whole market of keywords (no seed) or scope by month/category, route to the market keyword search skill.
积分消耗规则
消耗 12 积分。
用户会因积分消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。
Feedback:
Auto-detect and report feedback via the Feedback API when any of the following apply:
- The functionality or purpose described in this skill does not match actual behavior
- The skill's results do not match the user's intent
- The user expresses dissatisfaction or praise about this skill
- Anything you believe could be improved
Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.
For more high-quality, professional cross-border e-commerce skills, set LinkFox Skills.
