linkfox-mpstats-ozon-product-search

用途

本技能在 MPSTATS 分析数据库中按俄语关键词或 Ozon SKU 列表检索 Ozon（俄罗斯）商品，是 Ozon 商品发现与竞品反查的入口。后续的品牌、类目、卖家、详情、趋势等下钻操作，通常都从本技能返回的商品 ID 开始。

主要能力

• 关键词搜索：按俄语关键词检索 Ozon 商品。
• SKU 批量反查：传入 Ozon SKU 列表，批量获取对应商品信息。
• 日期窗口：可指定统计窗口的起止日期，用于特定周期的检索。

返回字段为 10 个身份字段：productId、title、productPageUrl、imageUrl、brand、brandId、sellerName、sellerId，以及 sourceType、sourceTool。

使用方式

参数：

• keyword（字符串，条件必填）：俄语搜索关键词，例如 кроссовки（运动鞋）。
• productIds（整数或字符串数组，条件必填）：Ozon SKU 列表。
• startDate（字符串，可选）：统计窗口开始日期，格式 YYYY-MM-DD，默认一年前。
• endDate（字符串，可选）：统计窗口结束日期，格式 YYYY-MM-DD，默认昨天，不能为今天或未来日期。

keyword 与 productIds 至少需提供一个，两者可组合以缩小结果。

调用方式：

• API 端点：POST /mpstats/ozon/productSearch（完整参数、响应与错误码见 references/api.md）。
• Python 脚本：python scripts/mpstats_ozon_product_search.py '<JSON 参数>' [--inline]。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-search-<timestamp>.json；<cwd> 为脚本执行时的工作目录，<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错。
• 响应体 ≤ 8 KB：落盘后将完整 JSON 打印到 stdout。
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度加前 3 条样本）。
• 加 --inline 可强制全量打印到 stdout（同样落盘）。

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。

使用示例：

1. 关键词搜索：{"keyword": "кроссовки"}
2. SKU 批量反查：{"productIds": [1786874757, 151623766, 142257239]}
3. 指定日期窗口：{"keyword": "футболка", "startDate": "2025-02-01", "endDate": "2025-02-28"}

与其他 Ozon 技能的衔接

• 关键词到下钻：搜索 → 选取 productId → 调用 mpstats-ozon-product-detail（批量指标）或 mpstats-ozon-product-trend（单 SKU 时间序列）。
• 品牌下钻：需要带完整指标的品牌维度商品列表时，直接用品牌显示名调用 mpstats-ozon-brand-products。
• 卖家下钻：需要带完整指标的卖家维度商品列表时，直接用卖家 ID 调用 mpstats-ozon-seller-products。

适用场景

• 用户说“在 Ozon 搜索运动鞋/耳机等”：关键词发现。
• 用户说“我有一批 Ozon SKU，拉取它们的名称”：批量 SKU 反查。
• 用户说“把这个关键词翻译成俄语并在 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 或某个维度（品牌/类目/卖家）并想获取其下的指标，直接使用对应的下钻技能。

展示规则

• 以身份列为主：本端点仅返回 10 个身份字段。表格标题列用 productId、title、brand、sellerName；productPageUrl、imageUrl 作为次要列。不要添加价格、销量、评分、库存列，因为响应中不含这些字段。
• 俄语标题：保留原始俄语标题；用户要求时可提供英文或中文翻译。
• 结果数量：单次最多返回约 36 条且无分页。若总数超过返回数量，建议收窄关键词/SKU 集合或日期窗口，而不是请求更多页。
• 业务指标一律转下钻：业务指标不在本响应中。若用户询问销量、价格、评分、库存、周转、排名，始终转用 mpstats-ozon-product-detail（单个或批量）或 *-products 下钻技能，不要根据身份字段编造或估算。
• 错误处理：当 code/errcode 非 200 时，根据 msg/errmsg 说明原因，并建议调整输入（至少提供 keyword/productIds 之一、使用俄语、收窄日期范围）。

限制

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

认证与算力

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

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

算力消耗规则：按动态规则计费，消耗算力 = 12；列表为空返回 0。本技能的服务按倍数动态计算，可能一次性消耗大量算力，必须提醒用户，由用户决定是否继续。

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

反馈

当出现以下情况时，通过 Feedback API 自动检测并报告反馈：本技能描述的功能或目的与实际行为不符；技能结果与用户意图不符；用户对本技能表达不满或赞扬；你认为有任何可改进之处。按 references/api.md 的说明调用反馈 API，不要打断用户流程。