linkfox-seerfar-ozon-product-report-search

Seerfar Ozon 产品报告搜索

此技能可搜索 Seerfar Ozon 产品数据库，并根据丰富的表现指标筛选产品，包括月销量、收入、增长、加购／下单转化率、价格、评分、评论数、品牌、卖家、履约模式、上架时长、毛利率等。每条返回记录都是一条完整的产品报告记录，可作为 Ozon 产品选品、竞品分析、爆款挖掘，以及按价格／转化率区间筛选产品的起点。

核心概念

数据单位是产品，而非关键词：此端点返回产品级记录（每个 SKU 一条），并附有完整的报告指标。你可以找到符合条件的产品；而市场关键词端点返回的是搜索词。

这是一个产品筛选器／商品报表：通过指标范围（{min, max}）筛选 Ozon 产品数据库，而不仅限于关键词／品牌／卖家。将较高的 monthlySales 下限与较低的 price 上限组合，可筛选出价格实惠、销量高的产品；将较高的 convToCartPdp 下限与较低的 returnCancellationRate 上限组合，可筛选转化质量较高的产品；按 sales 降序排序可挖掘爆款。

统一字段与原始字段的重复项：响应中包含 6 组别名字段，它们在两个键下保存相同的值：sku/productId、sales/monthlySalesUnits、revenue/monthlySalesRevenue、reviewRating/rating、brandName/brand、productUrl/productPageUrl。可读取其中任一字段；不要认为它们的值会不同。

日期语义：searchDate 用于选择数据月份。传入 2026-04-01 可获取 2026 年 3 月的数据；省略该参数则获取最近 30 天的数据。销售额／收入数据均以所选时间段为准。

data 和 products 完全相同：两个顶层数组都包含相同的产品记录。total 是符合条件的总数（例如，不加筛选时约为 2,780 万；筛选单个 SKU 时为 1）。

仅限 Ozon：sourceType 固定为 ozon。fulfillment 的取值为 OZON、FBO、FBS、RFBS、FBP。

参数

参数	类型	必填	描述
page	object	是	分页 + 排序：{page, pageSize, orders[]}。page 从 1 开始（默认值为 1），pageSize 默认值为 20。orders[] = {field, direction}，其中 direction 为 DESC/ASC。
skus	array	否	要限定范围的 SKU 列表（最多 10 个）。
keywords	array	否	用于筛选商品标题的关键词列表。
categoryIds	array	否	Seerfar 类别 ID 列表。
sellerName	array	否	卖家名称列表。
brand	object	否	{brandName: array<string>, type: int}。type：0 包含，1 排除，2 无品牌。
fulfillment	array	否	履约筛选：OZON/FBO/FBS/RFBS/FBP。
labels	array	否	徽标筛选：0 新品，1 正品，2 畅销品。
creationDate	integer	否	上架时长筛选（月）：1/3/6/12/24。
variationsMerge	integer	否	合并变体：0 否，1 是。
searchDate	string	否	数据日期 yyyy-MM-dd；默认最近 30 天。2026-04-01 → 2026 年 3 月。
tag	string	否	标签词。
monthlySales	{min,max}	否	月销量范围。
monthlySalesRate	{min,max}	否	销量增长率范围（筛选 salesRate）。
monthlyRevenue	{min,max}	否	月收入范围。
price	{min,max}	否	价格范围（RUB）。
convToCartPdp	{min,max}	否	加购转化率范围。
reviewRating	{min,max}	否	评分范围。
reviewCount	{min,max}	否	评论数范围。
questionsAndAnswers	{min,max}	否	问答数范围。
variants	{min,max}	否	变体数范围。
drr	{min,max}	否	广告成本占比范围。
grossMargin	{min,max}	否	毛利率范围。
returnCancellationRate	{min,max}	否	退货/取消率范围。
weight	{min,max}	否	重量范围（g）。
volume	{min,max}	否	体积范围（L）。
uId / memberId	string	否	用户 / 成员 ID（数据归属）。

所有范围筛选均为 {min, max} 对象；可提供任一或两个边界。只有 page 是必填项。

调用方式

• API 端点：POST /seerfar/ozon/productReportSearch（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/seerfar_ozon_product_report_search.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话中，相同参数组合默认只调用一次，脚本带有 24h 本地缓存。失败/空结果不得自动更换关键词、翻页或修改邮编连续试探；需要继续检索时，请先告知用户将产生额外消耗。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-product-report-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. 当前畅销品（按销量排序）

{"page": {"page": 1, "pageSize": 10, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. 蓝海商品——销量高、价格区间低

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}, "monthlySales": {"min": 5000}, "price": {"max": 500}}

3. 某类别的畅销品，FBO 履约

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}, "categoryIds": ["15621031_200000933_93182"], "fulfillment": ["FBO"], "labels": [2]}

4. 最近 30 天上架的商品，按增长率排序

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "salesRate", "direction": "DESC"}]}, "creationDate": 1}

5. 查询指定 SKU

{"page": {"page": 1, "pageSize": 10}, "skus": [2107989735]}

如何构建查询

1. 先使用 page.orders：数据集规模庞大（数千万件商品），始终按你关注的指标排序（畅销品按 sales DESC、上升商品按 salesRate DESC、低价走量商品按 price ASC、好评商品按 reviewRating DESC）。
2. 叠加范围筛选条件以发现机会：将 monthlySales 下限与 price 上限组合，或将 convToCartPdp 下限与较低的 returnCancellationRate 组合，以评估需求与风险。
3. 使用 categoryIds / brand / sellerName 限定范围：先缩小到某个细分领域，再排序，使排名靠前的结果更相关。
4. 使用 creationDate + labels 挖掘新兴需求：creationDate: 1（新上架商品）搭配 labels: [2]（畅销品徽标），可找到突围商品。
5. 选择合适的 searchDate：省略该参数可查看当前趋势（最近 30 天）；传入明确日期可进行月环比比较。

展示规则

1. 只呈现数据：用清晰的表格展示商品指标，不提供主观建议。
2. 优先展示商品列：title、sku、price（₽）、sales、revenue、rating、reviewCount，然后是 brand / sellerName / fulfillment。
3. 货币：price / revenue / missedRevenue 的单位是俄罗斯卢布（₽）；务必标明货币，避免误读数值大小。
4. 统一字段名 / 原始字段名别名：优先使用统一字段（productId、monthlySalesUnits、monthlySalesRevenue、rating、brand、productPageUrl），或注明它们与原始字段相同；不要将两者同时展示并当作不同数据。
5. 大型结果集：当 total 较大时，展示排名靠前的结果，并提醒用户可以通过下方的大型响应模式保存完整响应，或使用 page.page 翻页。
6. 错误处理：当 code 不为 200（或 errcode 不为 200）时，根据 msg / errmsg 说明原因，并建议调整筛选条件或重试（限流错误 1003）。

重要限制

• 必须提供 page：不包含 page 的载荷会被拒绝。
• skus 上限：每次请求最多 10 个 SKU。
• 分类 ID 是不透明值：categoryIds 必须使用 Seerfar 分类 ID（通过分类搜索获取），而不是人类可读的名称。
• 重复别名字段对：有六个字段同时以原始字段名和统一字段名提供（参见核心概念）——值相同，键不同。
• total 是完整匹配数量：不加筛选时，数量可能达到数千万；务必排序并分页，不要盲目遍历。
• 速率限制：errcode 1003（“请求过于频繁，请稍后再试”）表示请求受到限制——请等待后重试，不要降低 pageSize。
• 排序字段：有效的 orders[].field 值为响应中的指标字段（例如 sales、revenue、price、reviewRating、reviewCount、salesRate）；columns 数组标明哪些字段可排序。

用户表达与场景速查

适用 — Ozon 商品级筛选：

用户表达	场景
"Ozon 选品 / 按销量销售额筛选商品"	商品筛选器（范围筛选 + 排序）
"Ozon 热销商品 / 畅销品"	畅销品挖掘（labels:[2] 或按 sales DESC 排序）
"Ozon 上升商品 / 新品爆款"	上升 / 新品（creationDate:1，按 salesRate DESC 排序）
"Ozon 高转化低退货商品"	转化质量筛选（convToCartPdp 最小值，returnCancellationRate 最大值）
"Ozon 某品牌/卖家商品表现"	品牌 / 卖家筛选 + 排序
"查这几个 SKU 的报表"	skus 查询

不适用 — 需要商品级报告以外的数据：

• 关键词市场数据（搜索词、搜索量）→ market-keyword-search。
• 围绕种子词扩展关键词 → keyword-mining。
• 某家店铺的完整商品目录 → shop-search。
• 某个分类的商品及分类级聚合数据 → category-search。
• 商品的反向关键词查询 → keyword-back-search。
• 非 Ozon 电商平台 → 此处不涵盖。

边界判断：如果用户想要按指标筛选 Ozon 商品并查看商品级报告行，请从这里开始。如果用户需要关键词级市场数据、单家店铺的商品目录或分类聚合数据，请转到对应的 Seerfar Ozon 数据源。

算力消耗规则

消耗 15 算力。

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

反馈：

在以下任一情况下，通过 Feedback API 自动检测并报告反馈：

1. 此技能描述的功能或用途与实际行为不符
2. 此技能的结果与用户意图不符
3. 用户表达了对这项技能的不满或赞扬
4. 你认为任何方面有改进空间

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

---

如需获取更多高质量、专业的跨境电商技能，请设置 LinkFox Skills。