linkfox-seerfar-ozon-category-search

Seerfar Ozon 类目搜索

此技能会从 Seerfar 分析数据库中列出特定 Ozon 类目的商品。提供 categoryId 后，它会返回类目级汇总数据（总销量、总收入、平均价格、平均评分、季节性）以及每个商品的销量、价格、评分、评论数、品牌和卖家，是进行类目选择分析、类目内畅销商品挖掘以及类目容量／价格区间分析的起点。

核心概念

数据单位是商品，范围限定为一个类目：传入一个 categoryId，即可获取该类目的商品列表及表现指标，以及类目级汇总数据。这是类目级视图，而非店铺或关键词视图。

categoryId 的来源：categoryId 是 Ozon 类目标识符，由用 _ 连接的层级路径组成（例如 15621032_15621049_115951147），可从 Ozon 类目文档或其他 Seerfar Ozon 工具中获取。如果用户只有类目名称，请先从上游 Seerfar Ozon 数据源中将其解析为 categoryId，再调用此技能。

类目汇总数据与商品行：响应同时包含类目级汇总数据（totalSales、totalRevenue、avgPrice、rating、seasonalityAmplitude、seasonalityCoef、startDate/endDate）和分页商品列表（data / products）。使用汇总数据评估类目规模，使用商品行分析单个商品。

销量和价格的货币单位：sales / monthlySalesUnits 的单位是件；price / revenue 的单位是俄罗斯卢布（₽），由 currency 指明。

时间范围：默认数据涵盖最近 30 天（startDate / endDate 显示实际范围）。传入 date 为 yyyy-MM 格式（例如 2026-02），即可查询历史月份快照。

参数

参数	类型	必填	说明
categoryId	string	是	Ozon 类目 ID，例如 15621032_15621049_115951147（各层级以 _ 连接）。
page	object	是	分页参数 {page, pageSize, orders[]}。
page.page	integer	否	页码，从 1 开始（默认值为 1）。
page.pageSize	integer	否	每页数量，默认值为 20。最多 20——超出时会被拒绝（errcode 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 进入上下文。

解决认证和算力问题

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

异常情况

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

使用示例

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

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

2. 类目高营收商品

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

3. 类目高端价格区间（价格最高）

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

4. 历史月份快照

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

5. 仅筛选由 FBO 履约的商品

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

6. 深入浏览类目分页

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

如何构建查询

1. 始终传入 page.orders：类目可能包含许多商品——按你关注的指标排序（畅销商品按 sales DESC 排序，高营收商品按 revenue DESC 排序，高端价格区间按 price DESC 排序，评价最佳商品按 reviewRating DESC 排序）。
2. 将 pageSize 保持在 ≤ 20：网关将页面大小上限设为 20。使用 page.page 翻页；检查 hasNextPage 以确认是否还有后续页。
3. 先解析 categoryId：如果用户提供的是类目名称而非 ID，请在调用此技能前，从上游 Seerfar Ozon 来源获取 categoryId。
4. 使用类目汇总数据评估规模：totalSales、totalRevenue、avgPrice 和 rating 可让你快速了解整个类目的情况——在深入查看商品行之前，先用它们评估容量和价格区间。
5. 使用 date 进行历史对比：将 date 设为 yyyy-MM，即可将过去某个月与当前 30 天窗口进行对比。
6. fulfillment 是单个字符串：传入 FBO / FBS / RFBS / FBP / OZON 之一，不要传数组。

显示规则

1. 仅呈现数据：在清晰的表格中展示类目汇总数据和商品指标，不提供主观建议。
2. 先展示类目上下文，再展示商品列：说明类目名称（取自 categoryInfo.cnTitlePath / enTitlePath——用于确认类目正确），然后展示 totalSales、totalRevenue、avgPrice、rating、季节性（seasonalityAmplitude / seasonalityCoef）和日期范围，以及履约分布（sellerType 映射），用一行列出 FBO/FBS/RFBS/... 的拆分情况；随后展示包含 sku、title、price、sales、revenue、reviewRating、reviewCount、brandName、sellerName 的表格。
3. 货币：price / revenue 的单位为卢布（₽）；使用 currency 符号显示。
4. 履约方式：fulfillment 是数组（例如 ["FBO"]）；多个值以 / 连接。
5. 统一字段与原始字段：productId/rating/brand/monthlySalesUnits/monthlySalesRevenue/productPageUrl 分别对应 sku/reviewRating/brandName/sales/revenue/productUrl——只显示其中一组，优先使用原始字段。
6. 分页提示：当 hasNextPage 为 true 时，告知用户可通过 page.page 获取更多页面；提醒用户 pageSize 上限为 20。
7. 空类目：不存在的 categoryId 会成功返回 total=0 且无数据——告知用户 ID 可能有误，而不是报告系统错误。
8. 错误处理：当 code 不为 "200"（或 errcode 不为 200）时，根据 msg / errmsg 说明原因并建议修复方法（添加 page、调低 pageSize、遇到速率限制时重试）。

重要限制

• categoryId 和 page 均为必填项；省略任一项都会返回 errcode 400。
• pageSize 最大为 20：超过此值会返回 errcode 1002。
• 类目内不支持文本/关键词筛选：此端点仅按类目（以及可选的 fulfillment 和 date）筛选；要按关键词查找商品，请使用 Seerfar Ozon 市场关键词搜索技能。
• total 是当前页的行数，不是类目的商品总数——请使用 hasNextPage 判断是否需要获取更多页面。
• sellerType 表示履约方式分布，而非卖家类型：尽管名称如此，顶层的 sellerType 是一个从履约模式映射到商品数量的映射（{FBO, RFBS, FBP, FBS, OZON}）；它不包含本土/跨境信息。categoryInfo 包含类目名称路径（CN/EN/RU）和 crossBorderSellable。

用户表达与场景速查

适用——分析一个 Ozon 类目的商品及汇总数据：

用户表达	场景
“分析下这个 Ozon 类目的商品” / “这个类目有多大”	类目规模分析（totalSales / totalRevenue / avgPrice）
“这个类目最畅销的商品是什么”	畅销商品挖掘（按销量排序）
“这个类目销售额最高的商品”	销售额最高的商品（按销售额排序）
“这个类目的价格带/客单价”	价格区间分析（按价格排序）
“这个类目评分最高的商品”	评价最佳商品（按 reviewRating 排序）
“这个类目上个月的数据”	历史月份快照（date）
“这个类目 FBO 的商品”	履约方式筛选

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

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

边界判断：如果用户已有 categoryId（或已从上游数据源解析出该 ID），并希望按销量/价格/评分枚举、排名或评估该类目的商品规模，请从这里开始。如果用户需要店铺商品目录、关键词发现或单个商品的深度详情，请转至对应的 Seerfar Ozon 技能。

算力消耗规则

消耗 15 算力。

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

反馈：

出现以下任一情况时，通过 Feedback API 自动检测并提交反馈：

1. 本技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户表达对本技能的不满或赞赏
4. 你认为有任何可改进之处

按照 references/api.md 中的说明调用 Feedback API。不要打断用户的使用流程。

---

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