linkfox-mpstats-ozon-product-detail

MPSTATS Ozon 商品详情（单个 SKU）

此技能通过 MPSTATS 获取一个 Ozon（俄罗斯）SKU 的完整商品卡片。返回字段包括价格、Ozon 卡价格、折扣、评分、评价、库存、月销量、月销售额、损失利润、潜在收入、首次上架日期、图片等。

核心概念

单 SKU 语义：每次调用只传入一个 productId。此技能不再接受 productIds 数组或列表；若要查询多个 SKU，只有在向用户确认额外算力成本后，才能分别调用。

每个 SKU 的履约模式：每张商品卡片都包含 deliveryScheme：

• FBO — Ozon 履约（库存位于 Ozon 仓库）
• FBS — 卖家履约（由卖家发货）

传入 includeFbs: true 可在响应中包含 FBS SKU 和 FBS 范围的指标；传入 false（或省略）则结果以 FBO 为主。此开关适用于整个请求。

与上一时期比较：卡片包含 previousSalesUnits / previousRevenue，即紧邻 [startDate, endDate] 之前、时长相同的时期内的销量和收入，可直接用于月环比 / 时期对比差值计算，无需额外调用。

收入潜力：revenuePotential 估算该 SKU 在整个时间窗口内每天都有库存时可能获得的收入；可将其与 monthlySalesRevenue 对比，量化缺货造成的影响，并结合 lostProfit / lostProfitPercent 分析。

日期窗口：startDate / endDate 定义所有按时期汇总指标的统计周期。可选择的最晚日期是昨天（T-1）；今天和未来日期将被拒绝。

参数

参数	类型	必填	说明
productId	integer|string	是	单个 Ozon SKU ID
startDate	string	否	统计周期起始日期，YYYY-MM-DD；最晚为昨天
endDate	string	否	统计周期结束日期，YYYY-MM-DD；最晚为昨天
includeFbs	boolean	否	true 表示包含 FBS 数据；false = 仅 FBO

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-detail-<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. 单 SKU 详情

{"productId": 1786874757}

2. 按时期查询单 SKU

{
  "productId": 1786874757,
  "startDate": "2025-03-01",
  "endDate": "2025-03-31",
  "includeFbs": true
}

3. 仅 FBO 快照

{"productId": 1786874757, "includeFbs": false}

4. 上游发现的 SKU — 完整商品卡片

{"productId": <productId from mpstats-ozon-product-search>}

如何与其他 Ozon 技能串联

1. 搜索 → 详情：使用 mpstats-ozon-product-search 将关键词 / 品牌 / 卖家解析为候选 productId，选定一个 SKU 后，将该 productId 传入此处以获取完整指标。
2. 详情与趋势：此端点返回每个 SKU 的时期汇总；若要获取单个 SKU 的逐日时间序列，请使用 mpstats-ozon-product-trend。
3. 详情与下钻查询：如果输入维度是品牌 / 类目 / 卖家（而非单个 SKU），优先使用 brand-products / category-products / seller-products，它们已按该维度返回每个 SKU 的汇总指标。

展示规则

1. 紧凑表格 — 优先展示 productId、title、price、monthlySalesUnits、monthlySalesRevenue、rating、reviewCount、balance、deliveryScheme、firstDate。用户询问缺货影响时，再加入 revenuePotential / lostProfit / lostProfitPercent。
2. 货币 — Ozon 原生货币为 RUB；currency 字段包含货币符号。不要擅自更改货币标签。
3. 失败处理 — 响应包含 successCount / failedCount / failures；当 failedCount > 0 时，应向用户列出 failures 中失败的 productId，不要静默忽略。
4. 周期对比 — 如果同时存在当前字段和 previous* 字段，请并列展示或显示差值；不要把单周期数值称为“趋势”。
5. 有库存天数与所有天数 — salesPerDayWithStock / dailySalesRevenueWithStock 仅统计有库存的天数；应与普通的 salesPerDay / dailySalesRevenue 区分开。
6. 配送模式 — 优先使用每个 SKU 的 deliveryScheme 值，不要默认使用 FBO。
7. 不提供业务建议 — 展示数据；未经更全面的分析，不要推断“这个 SKU 值得销售”。

重要限制

• 仅支持单 SKU 输入 — 传入 productId，而非 productIds；数组/列表无效。对于多个 SKU，只有在确认额外的算力成本后，才能逐个 SKU 调用。
• 仅支持 Ozon — 此工具不覆盖 Wildberries 或其他俄罗斯电商平台。
• T-1 数据 — endDate 不能是今天或未来日期。
• FBS 覆盖范围 — 部分类目仅部分覆盖 FBS；如果输入中 FBS 商品占比较高，返回的数据卡片可能较少。
• 字段集与品牌/卖家接口不同 — 此接口不返回 brandId、country、category、minPrice / maxPrice / averagePrice、balanceFbs、frozenStocks、warehousesCount、daysInSite / daysInStock / turnoverDays、position / categoryPosition / revenueSharePercent、isFbs。如需这些字段，请使用 brand-products / category-products / seller-products。
• 不提供翻译 — 商品标题以俄语返回；面向中文/英文用户展示时，请按需翻译。

用户表达与场景速查

适用 — 按 SKU 查询 Ozon 商品卡片：

用户说法	场景
“查询这个 SKU 的 Ozon 详情”	查询单个商品卡片
“Ozon SKU 1786874757 的价格 / 评分 / 库存是多少？”	单 SKU 商品卡片
“查一下竞品的 Ozon 商品，给我销量和评分”	竞品商品卡片审核
“比较这个 SKU 的 FBO 与 FBO+FBS 指标”	配送模式对比

不适用 — 需求超出单 SKU 商品卡片：

• 按关键词发现商品 → 使用 mpstats-ozon-product-search
• 查询单个 SKU 逐日时间序列 → 使用 mpstats-ozon-product-trend
• 超出 URL 范围的商品文案 / 评论 / 图片分析 → 不在范围内
• 按筛选条件深入查询品牌 / 类目 / 卖家 → 使用对应的深入查询技能

适用边界：如果用户已经有一个 SKU，并想查询销量 / 价格 / 库存 / 评分，这就是对应技能。如果用户提供多个 SKU，只有在确认额外的算力成本后，才能逐个处理。如果用户还没有 SKU，请先转到搜索或深入查询技能。

算力消耗规则

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

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

反馈：

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

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

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

---

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