linkfox-seerfar-ozon-category-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Seerfar Ozon Category Search

Seerfar Ozon 类目搜索

This skill lists the products of a specific Ozon category from the Seerfar analytics database. Given a

categoryId

, it returns category-level aggregates (total sales, total revenue, average price, average rating, seasonality) plus each product's sales, price, rating, review count, brand and seller — the starting point for category selection analysis, best-seller mining within a category, and category capacity / price-band analysis.

本技能从Seerfar分析数据库中列出特定Ozon类目的商品。给定

categoryId

后，返回类目级聚合数据（总销量、总销售额、平均价格、平均评分、季节性）以及每个商品的销量、价格、评分、评论数、品牌和卖家信息——这是类目选品分析、类目爆品挖掘、类目容量与价格带分析的起点。

Core Concepts

核心概念

Unit of data is the product, scoped to one category: pass a single

categoryId

and receive that category's product list with performance metrics, alongside category-level aggregates. This is a category-level view, not a shop or keyword view.

Where the
categoryId
comes from:

categoryId

is the Ozon category identifier — a hierarchical path joined by

(e.g.

15621032_15621049_115951147

), obtained from the Ozon category document or from other Seerfar Ozon tools. If the user only has a category name, first resolve it to a

categoryId

from an upstream Seerfar Ozon source before calling this skill.

Category aggregates vs product rows: the response carries both category-level totals (

totalSales

totalRevenue

avgPrice

rating

seasonalityAmplitude

seasonalityCoef

startDate

endDate

) and a paginated product list (

data

products

). Use the aggregates for category sizing and the rows for individual product analysis.

Sales & price currency:

sales

monthlySalesUnits

are units;

price

revenue

are in Russian rubles (₽), indicated by

currency

Time window: by default the data covers the last 30 days (

startDate

endDate

show the actual range). Pass

date

yyyy-MM

(e.g.

2026-02

) to query a historical month snapshot.

数据单位为商品，限定单个类目：传入一个

categoryId

，即可获取该类目的商品列表及性能指标，同时返回类目级聚合数据。这是类目级视图，而非店铺或关键词视图。

categoryId
的来源：

categoryId

是Ozon的类目标识符——由

连接的层级路径（例如

15621032_15621049_115951147

），可从Ozon类目文档或其他Seerfar Ozon工具获取。如果用户只有类目名称，需先通过上游Seerfar Ozon源将其解析为

categoryId

，再调用本技能。

类目聚合数据 vs 商品行数据：响应结果同时包含类目级汇总数据（

totalSales

、

totalRevenue

、

avgPrice

、

rating

、

seasonalityAmplitude

、

seasonalityCoef

、

startDate

endDate

）和分页商品列表（

data

products

）。类目聚合数据用于评估类目规模，商品行数据用于单个商品分析。

销量与价格货币：

sales

monthlySalesUnits

为商品数量；

price

revenue

以俄罗斯卢布（₽）计价，由

currency

字段标识。

时间范围：默认数据覆盖最近30天（

startDate

endDate

显示实际范围）。传入

date

参数为

yyyy-MM

格式（例如

2026-02

）可查询历史月份的快照数据。

Parameters

参数

Parameter	Type	Required	Description
categoryId	string	yes	Ozon category ID, e.g. `15621032_15621049_115951147` (levels joined by `_` ).
page	object	yes	Pagination `{page, pageSize, orders[]}` .
page.page	integer	no	Page number, from 1 (default 1).
page.pageSize	integer	no	Page size, default 20. Max 20 — larger values are rejected ( `errcode 1002` ).
page.orders	array	no	Sort rules, elements `{field, direction}` (both required); `direction` `DESC` / `ASC` . Common fields: `sales` , `price` , `revenue` , `reviewRating` .
date	string	no	Historical month `yyyy-MM` (e.g. `2026-02` ); omit for last 30 days.
fulfillment	string	no	Fulfillment filter, one of `FBO` / `FBS` / `RFBS` / `FBP` / `OZON` ; omit to query all. Single string, not an array.
uId	string	no	User ID.
memberId	string	no	Member ID (data attribution).

Only

categoryId

and

page

are required.

参数	类型	是否必填	描述
categoryId	string	是	Ozon类目ID，例如 `15621032_15621049_115951147` （层级用 `_` 连接）。
page	object	是	分页参数 `{page, pageSize, orders[]}` 。
page.page	integer	否	页码，从1开始（默认值为1）。
page.pageSize	integer	否	每页条数，默认20。最大20——超过该值会被拒绝（错误码 `1002` ）。
page.orders	array	否	排序规则，元素为 `{field, direction}` （两者均为必填）； `direction` 可选 `DESC` / `ASC` 。常用字段： `sales` 、 `price` 、 `revenue` 、 `reviewRating` 。
date	string	否	历史月份，格式为 `yyyy-MM` （例如 `2026-02` ）；省略则查询最近30天数据。
fulfillment	string	否	配送方式筛选，可选值为 `FBO` / `FBS` / `RFBS` / `FBP` / `OZON` ；省略则查询所有配送方式。仅支持单个字符串，不可为数组。
uId	string	否	用户ID。
memberId	string	否	会员ID（数据归属）。

仅

categoryId

和

page

为必填参数。

调用方式

API 端点：
```
POST /seerfar/ozon/categorySearch
```
（完整参数/响应/错误码见
```
references/api.md
```
）

Python 脚本：

python scripts/seerfar_ozon_category_search.py '<JSON 参数>' [--inline]

成本约束：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

始终将完整响应写入
```
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-category-search-<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 进入上下文。

API 端点：
```
POST /seerfar/ozon/categorySearch
```
（完整参数/响应/错误码详见
```
references/api.md
```
）

Python 脚本：

python scripts/seerfar_ozon_category_search.py '<JSON 参数>' [--inline]

成本约束：本工具会消耗积分；同一会话同一参数组合默认仅调用一次，脚本带有24小时本地缓存。失败/空结果不得自动更换关键词、翻页或修改邮编连续试探；如需继续检索，需先向用户说明会产生额外消耗，再由用户决定是否继续。

输出策略（脚本默认行为）：

始终将完整响应写入
```
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-category-search-<timestamp>.json
```
（
```
<cwd>
```
为脚本执行时的工作目录，在Claude Code中即当前项目目录；
```
<session>
```
取自环境变量
```
SESSION_ID
```
，按用户任务自动聚合；禁止写入/tmp目录，若当前目录不可写则报错）
响应体 ≤ 8 KB：落盘后将完整JSON打印到标准输出（stdout）
响应体 > 8 KB：落盘后标准输出仅打印摘要信息（顶层字段、常见计数如
```
total
```
/
```
costToken
```
、最大列表字段的长度 + 前3条样本）
添加
```
--inline
```
参数可强制将全量数据打印到标准输出（同样会落盘）

读数据建议：先查看摘要判断数据是否足够；如需具体字段，优先使用

jq

或

ConvertFrom-Json

从保存的JSON文件中按需抽取，避免整份JSON进入上下文。

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

出现以下异常情况时，参考

references/onboarding.md

引导解决：

异常情况

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息包含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"或类似含义的内容。

Usage Examples

使用示例

1. Category best-sellers (sort by 30-day sales)

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. Category top-revenue products

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}}

3. Category premium price band (highest-priced)

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. Historical month snapshot

json

{"categoryId": "15621032_15621049_115951147", "date": "2026-02", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

5. Filter to FBO-fulfilled products only

json

{"categoryId": "15621032_15621049_115951147", "fulfillment": "FBO", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

6. Page deeper into the category

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

1. 类目畅销商品（按30天销量排序）

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. 类目销售额最高的商品

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}}

3. 类目高端价格带（最高价商品）

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. 历史月份快照

json

{"categoryId": "15621032_15621049_115951147", "date": "2026-02", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

5. 仅筛选FBO配送的商品

json

{"categoryId": "15621032_15621049_115951147", "fulfillment": "FBO", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

6. 查看类目下更多分页数据

json

{"categoryId": "15621032_15621049_115951147", "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

How to Build Queries

如何构建查询

Always pass
page.orders
: categories can contain many products — sort by the metric you care about (
```
sales
```
DESC for best-sellers,
```
revenue
```
DESC for top revenue,
```
price
```
DESC for the premium band,
```
reviewRating
```
DESC for best-reviewed).
Keep
pageSize
≤ 20: the gateway caps page size at 20. Use
```
page.page
```
to paginate; check
```
hasNextPage
```
to know whether more pages exist.
Resolve the
categoryId
first: if the user gives a category name rather than an id, obtain the
```
categoryId
```
from an upstream Seerfar Ozon source before calling this skill.
Use category aggregates for sizing:
```
totalSales
```
,
```
totalRevenue
```
,
```
avgPrice
```
and
```
rating
```
describe the whole category at a glance — use them for capacity and price-band assessment before drilling into rows.
Use
date
for historical comparison: pass
```
date
```
as
```
yyyy-MM
```
to compare a past month against the current 30-day window.
fulfillment
is a single string: pass one of
```
FBO
```
/
```
FBS
```
/
```
RFBS
```
/
```
FBP
```
/
```
OZON
```
, not an array.

务必传入
page.orders
：类目可能包含大量商品——按你关注的指标排序（
```
sales
```
DESC用于畅销商品、
```
revenue
```
DESC用于最高销售额商品、
```
price
```
DESC用于高端价格带商品、
```
reviewRating
```
DESC用于评分最高商品）。
保持
pageSize
≤ 20：网关限制每页最大条数为20。使用
```
page.page
```
进行分页；通过
```
hasNextPage
```
判断是否存在更多分页数据。
先解析
categoryId
：如果用户提供的是类目名称而非ID，需先通过上游Seerfar Ozon源获取
```
categoryId
```
，再调用本技能。
使用类目聚合数据评估规模：
```
totalSales
```
、
```
totalRevenue
```
、
```
avgPrice
```
和
```
rating
```
可快速描述整个类目的情况——在深入分析商品行数据之前，先用这些数据评估类目容量和价格带。
使用
date
进行历史对比：传入
```
date
```
参数为
```
yyyy-MM
```
格式，可将过去月份的数据与当前30天窗口的数据进行对比。
fulfillment
为单个字符串：传入
```
FBO
```
/
```
FBS
```
/
```
RFBS
```
/
```
FBP
```
/
```
OZON
```
中的一个值，不可为数组。

Display Rules

展示规则

Present data only: show the category aggregates and product metrics in a clear table without subjective advice.
Lead with category context, then product columns: state the category name (from
```
categoryInfo.cnTitlePath
```
/
```
enTitlePath
```
— confirms the right category), then
```
totalSales
```
,
```
totalRevenue
```
,
```
avgPrice
```
,
```
rating
```
, seasonality (
```
seasonalityAmplitude
```
/
```
seasonalityCoef
```
) and date range, plus the fulfillment distribution (
```
sellerType
```
map) as a one-line FBO/FBS/RFBS/... split; then a table of
```
sku
```
,
```
title
```
,
```
price
```
,
```
sales
```
,
```
revenue
```
,
```
reviewRating
```
,
```
reviewCount
```
,
```
brandName
```
,
```
sellerName
```
.
Currency:
```
price
```
/
```
revenue
```
are in rubles (₽); render with the
```
currency
```
symbol.
Fulfillment:
```
fulfillment
```
is an array (e.g.
```
["FBO"]
```
); join multiple values with
```
/
```
.

Unified vs original fields:

productId

rating

brand

monthlySalesUnits

monthlySalesRevenue

productPageUrl

mirror

sku

reviewRating

brandName

sales

revenue

productUrl

— show one set, prefer the originals.

Pagination guidance: when
```
hasNextPage
```
is true, tell the user more pages are available via
```
page.page
```
; remind them
```
pageSize
```
is capped at 20.
Empty category: a non-existent
```
categoryId
```
returns success with
```
total=0
```
and no data — tell the user the id may be wrong rather than reporting a system error.
Error handling: when
```
code
```
is not
```
"200"
```
(or
```
errcode
```
is not
```
200
```
), explain the reason from
```
msg
```
/
```
errmsg
```
and suggest fixes (add
```
page
```
, lower
```
pageSize
```
, retry on rate-limit).

仅展示数据：以清晰的表格形式展示类目聚合数据和商品指标，不添加主观建议。
先展示类目上下文，再展示商品列：先说明类目名称（取自
```
categoryInfo.cnTitlePath
```
/
```
enTitlePath
```
——确认类目正确），然后展示
```
totalSales
```
、
```
totalRevenue
```
、
```
avgPrice
```
、
```
rating
```
、季节性数据（
```
seasonalityAmplitude
```
/
```
seasonalityCoef
```
）和日期范围，以及配送方式分布（
```
sellerType
```
映射）的单行拆分信息（如FBO/FBS/RFBS/...）；之后展示包含
```
sku
```
、
```
title
```
、
```
price
```
、
```
sales
```
、
```
revenue
```
、
```
reviewRating
```
、
```
reviewCount
```
、
```
brandName
```
、
```
sellerName
```
的表格。
货币：
```
price
```
/
```
revenue
```
以卢布（₽）计价；显示时带上货币符号。
配送方式：
```
fulfillment
```
为数组（例如
```
["FBO"]
```
）；多个值用
```
/
```
连接。

统一字段 vs 原始字段：

productId

rating

brand

monthlySalesUnits

monthlySalesRevenue

productPageUrl

与

sku

reviewRating

brandName

sales

revenue

productUrl

对应——仅展示一组字段，优先选择原始字段。

分页指引：当
```
hasNextPage
```
为true时，告知用户可通过
```
page.page
```
获取更多分页数据；提醒用户
```
pageSize
```
上限为20。
空类目：若
```
categoryId
```
不存在，返回成功但
```
total=0
```
且无数据——告知用户该ID可能有误，而非报告系统错误。
错误处理：当
```
code
```
不为
```
"200"
```
（或
```
errcode
```
不为
```
200
```
）时，根据
```
msg
```
/
```
errmsg
```
解释原因并建议修复方案（添加
```
page
```
参数、降低
```
pageSize
```
、限流时重试）。

Important Limitations

重要限制

categoryId
and
page
are both required; omitting either returns
```
errcode 400
```
.
pageSize
max 20: exceeding it returns
```
errcode 1002
```
.
No text/keyword filter within a category: this endpoint filters by category (plus optional
```
fulfillment
```
and
```
date
```
) only; to find products by keyword, use the Seerfar Ozon market keyword search skill.
total
is the page row count, not the category's total product count — use
```
hasNextPage
```
to decide whether to fetch more pages.
sellerType
is a fulfillment distribution, not seller type: despite the name, the top-level
```
sellerType
```
is a map of fulfillment model → product count (
```
{FBO, RFBS, FBP, FBS, OZON}
```
); it does not carry 本土/跨境 (local/cross-border) info.
```
categoryInfo
```
carries the category name path (CN/EN/RU) and
```
crossBorderSellable
```
.

categoryId
和
page
均为必填；省略任意一个会返回错误码
```
400
```
。
pageSize
最大为20：超过该值会返回错误码
```
1002
```
。
类目内无文本/关键词筛选：本端点仅按类目（可选加上
```
fulfillment
```
和
```
date
```
）筛选；如需按关键词查找商品，请使用Seerfar Ozon市场关键词搜索技能。
total
为当前页行数，而非类目商品总数——使用
```
hasNextPage
```
决定是否获取更多分页数据。
sellerType
是配送方式分布，而非卖家类型：尽管名称如此，顶层
```
sellerType
```
是配送模式→商品数量的映射（
```
{FBO, RFBS, FBP, FBS, OZON}
```
）；不包含本土/跨境信息。
```
categoryInfo
```
包含类目名称路径（中/英/俄）和
```
crossBorderSellable
```
字段。

User Expression & Scenario Quick Reference

用户表达与场景速查

Applicable — analyzing one Ozon category's products and aggregates:

User Says	Scenario
"分析下这个 Ozon 类目的商品" / "这个类目有多大"	Category sizing (totalSales / totalRevenue / avgPrice)
"这个类目最畅销的商品是什么"	Best-seller mining (sort by sales)
"这个类目销售额最高的商品"	Top-revenue products (sort by revenue)
"这个类目的价格带/客单价"	Price-band analysis (sort by price)
"这个类目评分最高的商品"	Best-reviewed (sort by reviewRating)
"这个类目上个月的数据"	Historical month snapshot (date)
"这个类目 FBO 的商品"	Fulfillment filter

Not applicable — Needs beyond one category's product list:

One shop/seller's catalog → use the Seerfar Ozon shop search skill.
Market-level keyword discovery → use the Seerfar Ozon market keyword search skill.
Keyword mining → use the Seerfar Ozon keyword mining skill.
A single product's full detail → use a product-level Seerfar Ozon source (this skill returns category-level fields only).

Boundary judgment: if the user already has a

categoryId

(or one resolved from an upstream source) and wants to enumerate, rank, or size that category's products by sales/price/rating, start here. If they want a shop's catalog, keyword discovery, or a single product's deep detail, route to the corresponding Seerfar Ozon skill.

适用场景——分析单个Ozon类目的商品及聚合数据：

用户表述	场景
"分析下这个Ozon类目的商品" / "这个类目有多大"	类目规模评估（totalSales / totalRevenue / avgPrice）
"这个类目最畅销的商品是什么"	爆品挖掘（按销量排序）
"这个类目销售额最高的商品"	最高销售额商品（按销售额排序）
"这个类目的价格带/客单价"	价格带分析（按价格排序）
"这个类目评分最高的商品"	最高评分商品（按评分排序）
"这个类目上个月的数据"	历史月份快照（使用date参数）
"这个类目FBO的商品"	配送方式筛选

不适用场景——超出单个类目商品列表的需求：

单个店铺/卖家的商品目录 → 使用Seerfar Ozon店铺搜索技能。
市场级关键词发现 → 使用Seerfar Ozon市场关键词搜索技能。
关键词挖掘 → 使用Seerfar Ozon关键词挖掘技能。
单个商品的详细信息 → 使用Seerfar Ozon的商品级数据源（本技能仅返回类目级字段）。

边界判断：如果用户已有

categoryId

（或通过上游源解析得到），并希望按销量/价格/评分枚举、排序或评估该类目的商品，则使用本技能。如果用户需要店铺目录、关键词发现或单个商品的详细信息，则路由到对应的Seerfar Ozon技能。

积分消耗规则

消耗 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.

消耗12积分。

用户会因积分消耗产生费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

当出现以下任意情况时，通过反馈API自动检测并上报：

本技能描述的功能或用途与实际行为不符
技能结果与用户意图不符
用户表达了对本技能的不满或赞扬
任何你认为可以改进的内容

按照

references/api.md

中的指定方式调用反馈API，请勿中断用户流程。

如需更多高质量、专业的跨境电商技能，请访问LinkFox Skills。