linkfox-mpstats-ozon-product-search

MPSTATS Ozon 商品搜索

此技能可通过俄语关键词或 SKU 列表，在 MPSTATS 分析数据库中搜索 Ozon（俄罗斯）商品。它是 Ozon 商品发现和竞品查询的入口——后续的深入查询（品牌／类目／卖家／详情／趋势）通常从此处返回的 ID 开始。

核心概念

MPSTATS 的 Ozon 覆盖范围：Ozon 是俄罗斯最大的综合类目电商平台。MPSTATS 对 Ozon 商品列表和销售历史进行索引。此端点仅返回基本身份卡片——10 个字段：productId / title / productPageUrl / imageUrl / brand / brandId / sellerName / sellerId，以及 sourceType / sourceTool。此处不返回每个 SKU 的价格／销量／评分／库存／营业额／排名——后端的 OzonProductSearchItem DTO 有意限定为较少字段。要获取这些指标，请接着调用 mpstats-ozon-product-detail（批量完整卡片，36 个字段），或使用 brand/category/seller-products 深入查询（39 个字段）。

语言要求：关键词必须使用俄语（西里尔字母），或使用 Ozon 商城实际采用的拉丁字母形式。如果用户提供英语或中文关键词，请先将其翻译成俄语，并注明译文。

至少提供一个输入：输入架构将两个筛选条件都标记为可选，但工具的业务规则要求至少提供 keyword / productIds 其中之一。两者可以组合使用以缩小结果范围。若要按品牌或卖家限定范围进行商品发现，请改用 mpstats-ozon-brand-products / mpstats-ozon-seller-products。

参数

参数	类型	必填	说明
keyword	string	有条件必填	俄语搜索关键词，例如 кроссовки（运动鞋）
productIds	array<integer|string>	有条件必填	Ozon SKU 列表
startDate	string	否	统计窗口开始日期，YYYY-MM-DD；默认为一年前
endDate	string	否	统计窗口结束日期，YYYY-MM-DD；默认为昨天，不能是今天或未来日期

必须提供 keyword / productIds 中的至少一项。单次调用最多返回约 36 条记录（上游确认的上限），且没有分页／排序／筛选输入——请通过关键词／SKU 和日期窗口缩小范围。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-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. 关键词搜索——用俄语搜索运动鞋

{"keyword": "кроссовки"}

2. SKU 批量反向查询

{"productIds": [1786874757, 151623766, 142257239]}

3. 按指定时间段进行搜索

{"keyword": "футболка", "startDate": "2025-02-01", "endDate": "2025-02-28"}

如何与其他 Ozon 技能串联使用

1. 关键词 → 深入查询：搜索 → 选取 productId → 调用 mpstats-ozon-product-detail（批量指标）或 mpstats-ozon-product-trend（单 SKU 时间序列）。
2. 品牌深入查询：若要获取包含完整指标的品牌限定商品列表，请直接使用品牌展示名称调用 mpstats-ozon-brand-products。
3. 卖家深入查询：若要获取包含完整指标的卖家限定商品列表，请直接使用卖家 ID 调用 mpstats-ozon-seller-products。

显示规则

1. 优先展示身份字段 — 此端点仅返回 10 个身份字段。表格应以 productId、title、brand、sellerName 为主要列；将 productPageUrl / imageUrl 作为次要列。不要添加价格 / 销量 / 评分 / 库存列——响应中不包含这些字段。
2. 俄语标题 — 保留原始俄语标题；可根据用户请求提供英文或中文翻译。
3. 结果数量 — 此端点最多返回约 36 条记录，且不支持分页。如果 total 大于实际返回的数量，应建议缩小关键词 / SKU 集合或日期范围，而不是要求获取更多页面。
4. 业务指标一律转到下钻工具 — 此响应中不包含业务指标。如果用户询问销量 / 价格 / 评分 / 库存 / 周转率 / 排名，务必转到 mpstats-ozon-product-detail（单个或批量）或 *-products 下钻工具。不要根据身份字段编造或估算。
5. 错误处理 — 当 code / errcode 不为 200 时，根据 msg / errmsg 说明原因，并建议调整输入（至少提供 keyword / productIds 之一，使用俄语，缩小日期范围）。

重要限制

• 至少需要提供 keyword / productIds 之一 — 即使 inputSchema 中的 required 为空，空载荷也会被工具的业务规则拒绝。
• 仅支持俄语 / 拉丁字母 — 非俄语关键词通常不会返回结果。
• 日期范围 — endDate 不能是今天或未来的日期；数据截至 T-1。
• 结果数量硬性上限 — 上游每次最多返回约 36 条记录，且不提供分页 / 排序 / 筛选功能。无法绕过；请缩小查询范围。
• 不包含业务指标 — 此端点的响应中完全不包含价格 / 销量 / 评分 / 库存 / 周转率 / 排名。后端 OzonProductSearchItem DTO 明确只包含 10 个身份字段。这是硬性约定，不是稀疏载荷——不要以为改用不同日期重新调用就能补全缺失的指标字段。

用户表达与场景速查

适用 — Ozon 商品发现 / 身份确认：

用户表达	场景
"Search Ozon for sneakers / headphones / ..."	关键词发现
"I have a list of Ozon SKUs, pull their names"	批量 SKU 反向查询
"Translate this keyword to Russian and search Ozon"	跨语言发现

不适用 — 需求超出发现范围：

• 可靠的单个 SKU 销量 / 收入 / 库存 / 评分指标 → 使用 mpstats-ozon-product-detail（批量商品卡）或 *-products 下钻技能。
• 按品牌筛选商品列表 → 直接使用 mpstats-ozon-brand-products。
• 按卖家筛选商品列表 → 直接使用 mpstats-ozon-seller-products。
• 单个 SKU 的时间序列趋势 → 使用 mpstats-ozon-product-trend。
• Wildberries 或其他非 Ozon 俄罗斯电商平台 → 不在此工具范围内。
• 类目树导航 / 俄语类目路径查询 → 使用 mpstats-ozon-category-products，并提供已知路径。

边界判断：如果用户想要查找或确认 Ozon 商品，请从此处开始。如果用户已有 ID 或维度（品牌 / 类目 / 卖家），并希望获取对应的指标，则直接使用相应的下钻技能。

算力消耗规则

按动态规则计费：消耗算力 = 12。列表为空返回 0

重要：本技能的服务按倍数动态计算，可能一次性消耗大量算力，必须提醒用户，由用户决定是否继续。

反馈：

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

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

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

---

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