linkfox-mpstats-ozon-product-trend

MPSTATS Ozon 商品趋势（日度时间序列）

此工具返回单个 Ozon（俄罗斯）SKU 的日度时间序列，包括销量、价格、库存、评分，以及可选的搜索排名／可见度指标。适用于验证特定商品的增长、季节性或异常情况。

核心概念

单个 SKU 范围：每次调用恰好分析 一个 productId。如需获取每个 SKU 的批量快照（周期汇总），请改用 mpstats-ozon-product-detail。

日度粒度：响应是一个日度数据点数组（顶层字段 data），覆盖 [startDate, endDate] 时间范围。每个数据点都包含一个 hasData 布尔值：若 hasData=false，表示当天没有观测数据（不同于 hasData=true 时 sales=0）。

T-1 延迟：MPSTATS 趋势数据延迟一天；可选的最晚结束日期是昨天。今天或未来日期会被拒绝。

搜索可见度附加项：设置 includeSearchStats: true 可附加搜索排名／可见度信号。某些细分类目（尤其是较小的类目）可能没有搜索统计数据覆盖；此时相关字段可能不完整或为空。

参数

参数	类型	必填	说明
productId	integer	是	Ozon SKU（数字）
startDate	string	否	时间范围起始日期，YYYY-MM-DD；最晚为昨天
endDate	string	否	时间范围结束日期，YYYY-MM-DD；最晚为昨天
includeFbs	boolean	否	除 FBO 外，是否包含 FBS 数据
includeSearchStats	boolean	否	附加搜索排名／可见度信号

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-trend-<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,
  "startDate": "2025-03-01",
  "endDate": "2025-03-31"
}

2. 包含搜索可见度的趋势

{
  "productId": 1786874757,
  "startDate": "2025-02-01",
  "endDate": "2025-02-28",
  "includeSearchStats": true
}

3. FBO+FBS 综合趋势

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

如何与其他 Ozon 工具串联

1. 发现 → 趋势：使用 mpstats-ozon-product-search 查找 SKU，然后在提交之前在此处检查其增长／波动情况。
2. 汇总与时间序列：mpstats-ozon-product-detail 提供每项指标的单一周期数值；此工具则展示这些数值背后的逐日变化。
3. 深入分析 → 趋势：brand-products／category-products／seller-products 找到热门 SKU 后，使用此工具验证热度是近期出现、具有季节性，还是持续存在。

展示规则

1. 优先使用简单表格或适合绘制迷你图的输出——每个日期占一行，包含 date、price、sales、balance、rating、comments；不要把 90 个数据点硬塞进一段文字。
2. 使用 hasData 区分数据缺失与零销量——hasData=false 表示当天没有观测数据；不要将其报告为零销量日。
3. 指出异常情况——应客观标记单日大幅波动或缺货（hasData=true 时 balance=0 的连续日期），不要给出购买建议。
4. 货币单位为 RUB，除非上游层已进行转换（每个数据点的 currency 字段包含货币符号，例如 ₽）；展示价格变动时注明货币单位。
5. 不会按天返回收入——如果用户询问每日收入，请用 sales * price 估算，并注明这是估算值。
6. includeSearchStats 数据缺失——如果没有返回搜索可见性字段，请注明“搜索位次数据在该赛道暂不可用”，不要默默省略。
7. 不提供商业建议——呈现数据趋势；“我们是否应该购买这个商品”的决定留给用户。

重要限制

• 每次调用仅支持一个 SKU——不能传入 productId 列表；如有需要，可在 Agent 层循环处理。
• T-1 数据——endDate 不能是今天或未来日期。
• 搜索统计为可选项——includeSearchStats=true 不保证覆盖所有细分赛道。
• 仅支持 Ozon——不涵盖 Wildberries 和其他俄罗斯电商平台。
• 日期缺失——数据序列可能包含空值或缺口，表示未采集到数据；不要将空值视为零销量。

用户表达与场景速查

适用——单 SKU 时序分析：

用户说	场景
“上个月 Ozon SKU 1786874757 的销量趋势如何？”	月度时间序列
“这个 Ozon 商品是季节性商品还是销量稳定？”	季节性检查
“这个 Ozon 商品最近缺货了吗？”	库存异常检测
“这个 Ozon 商品第一季度的价格走势如何？”	价格变动
“这个商品的搜索排名有提升吗？”	搜索可见性（需要 includeSearchStats）

不适用——需要超出单 SKU 时序分析的功能：

• 多个 SKU 的批量快照 → mpstats-ozon-product-detail
• 品牌／品类／卖家下钻分析 → 对应的 *-products 技能
• 已有商品 ID 的商品发现 → mpstats-ozon-product-search

边界判断：当问题以“这个单一商品随时间发生了什么变化”开头时，使用此技能。多 SKU 对比或维度筛选请使用其他技能。

算力消耗规则

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

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

反馈：

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

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

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

---

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