linkfox-seerfar-ozon-shop-search

Seerfar Ozon 店铺搜索

此技能从 Seerfar 分析数据库中列出指定 Ozon 店铺（卖家）的商品。提供店铺 id 后，会返回每件商品的 30 天销量、价格、评分、重量、履约模式（FBO/FBS）、卖家类型（本土／跨境）以及退货／取消率，并提供店铺 30 天总销量，是分析竞品店铺商品、挖掘畅销商品和拆解卖家商品目录的起点。

核心概念

数据单位为商品，范围限定为一个店铺：传入单个店铺 id，即可获取该店铺的商品目录及业绩指标。这是店铺级视图，而非关键词或类目视图。

店铺 id 的来源：id 是 Seerfar 的卖家／店铺标识符，与其他 Seerfar Ozon 工具（例如商品报告／商品详情搜索）返回的 sellerId 相同。负数 ID（例如 -2 Ozon Express、-4 Ozon Fresh）表示 Ozon 自营平台卖家；正数 ID 表示第三方卖家。如果用户只有店铺名称或商品，应先从 Seerfar Ozon 商品级数据源获取 sellerId，再调用此技能。

卖家类型：每件商品都带有 sellerType——0 表示本土，1 表示跨境。一个店铺通常全部属于同一类型；可据此判断竞品是本土卖家还是跨境卖家。

销量和价格币种：sales / monthlySalesUnits 表示 30 天销量；price 的单位是俄罗斯卢布（₽），由 currency 标明。

参数

参数	类型	必填	说明
id	integer	是	店铺（卖家）ID——其他 Seerfar Ozon 工具返回的 sellerId。负数表示 Ozon 平台卖家。
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、reviewRating、upTime。
uId	string	否	用户 ID。
memberId	string	否	会员 ID（数据归属）。

仅 id 和 page 为必填项。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-shop-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 天销量排序）

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. 店铺最新上架商品（按上传时间排序）

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "upTime", "direction": "DESC"}]}}

3. 店铺价格最高的商品

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. 深入查看店铺商品目录的后续页面

{"id": 1362816, "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

如何构建查询

1. 始终传入 page.orders：商品目录可能很大，请按你关注的指标排序（畅销商品使用 sales DESC，新品使用 upTime DESC，高端 SKU 使用 price DESC）。
2. 将 pageSize 控制在 ≤ 20：网关将页面大小限制为 20。使用 page.page 翻页；查看 hasNextPage，确认是否还有更多页面。
3. 先获取店铺 id：如果用户提供的是店铺/商品名称而非 id，请先从商品级 Seerfar Ozon 数据源获取 sellerId，再调用此技能。
4. 使用店铺级汇总数据提供背景信息：totalSales / totalRevenue / dailySales 是店铺整体数据（不受当前页面影响），productCount 是完整商品目录的商品数，rating 是店铺评分，顶层的 fulfillment 显示 FBO/FBS 分布——这些都是快速判断整个店铺状况的指标。

显示规则

1. 仅展示数据：使用清晰的表格展示店铺的商品指标，不提供主观建议。
2. 先展示店铺背景信息，再展示商品列：首先列出店铺级汇总数据——totalSales（30 天总销量）、totalRevenue（总收入，₽）、productCount（商品目录大小）、dailySales、rating 和 fulfillment 分布（例如 FBO 72 / FBS 4）——然后展示包含 sku、price、sales、reviewRating、weight、sellerType、fulfillment、returnCancellationRate 的表格。
3. 卖家类型标签：将 sellerType 显示为 本土/跨境 (0/1)，方便用户一目了然。
4. 履约方式：fulfillment 是一个数组（例如 ["FBO"]）；多个值用 / 连接。
5. 缺少 returnCancellationRate：对于 Ozon 平台卖家（负数 id），此字段通常不存在——显示 -，不要报错。
6. 分页说明：当 hasNextPage 为 true 时，告知用户可以通过 page.page 查看更多页面；提醒用户 pageSize 上限为 20。
7. 空店铺：不存在的 id 会返回成功，且 total=0、无数据——告知用户 id 可能有误，而不是报告系统错误。
8. 错误处理：当 code 不为 "200"（或 errcode 不为 200）时，根据 msg / errmsg 说明原因并建议解决方法（添加 page、减小 pageSize、遇到速率限制时重试）。

重要限制

• id 和 page 均为必填项；缺少任一项都会返回 errcode 400。
• pageSize 最大为 20：超过上限会返回 errcode 1002。
• total 是当前页面的行数，而非店铺完整商品目录的大小——使用 hasNextPage 判断是否需要获取更多页面。
• 不支持文本/关键词筛选：此端点只能按店铺筛选；要按名称查找店铺，请先使用其他 Seerfar Ozon 数据源。
• 字段因卖家类型而异：第三方卖家会提供 returnCancellationRate，但 Ozon 平台卖家（负数 id）通常没有此字段。Schema 中定义的 productPageUrl、monthlySalesRevenue、brand 不会返回（上游没有对应数据源，因此会省略，而非返回 null）。

用户表达与场景速查

适用——分析一个 Ozon 店铺／卖家的商品目录：

用户表达	场景
“分析下这个 Ozon 店铺的商品”／“这个卖家在卖什么”	店铺商品目录
“这家店最畅销的商品是什么”	畅销商品挖掘（按销量排序）
“这家店最近上了哪些新品”	新品（按 upTime 排序）
“这个竞品店铺的价格带／客单价”	价格区间分析（按价格排序）
“这家店是本土还是跨境卖家”	卖家类型检查（sellerType）
“这个店铺总销量多少”	店铺健康度（totalSales）

不适用——需求超出单个店铺的商品目录：

• 按市场指标发掘 Ozon 关键词 → 使用 Seerfar Ozon 市场关键词搜索技能。
• 查询单个商品的完整详情 → 使用商品级 Seerfar Ozon 数据源（此技能仅返回目录级字段）。
• 浏览类目树 → 使用类目级 Seerfar Ozon 数据源。
• 查找哪个店铺在售某个商品 → 先使用商品级 Seerfar Ozon 数据源获取 sellerId。

边界判断：如果用户已有店铺／卖家 ID（或通过商品查询获取了 sellerId），并希望枚举该店铺的商品或按销量／价格／评分排序，请从这里开始。如果用户想要发掘市场级关键词或深入了解单个商品详情，请转到相应的 Seerfar Ozon 技能。

算力消耗规则

消耗 15 算力。

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

反馈：

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

1. 此技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户对这项技能表示不满或赞赏
4. 任何你认为可以改进的地方

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

---

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