linkfox-keepa-product-series

Keepa 商品时间序列数据探索器

本技能将指导你查询和分析 Amazon 商品历史时间序列数据，帮助 Amazon 卖家跟踪价格变动、BSR 趋势、评分变化及其他关键商品指标随时间的变化。

核心概念

此工具提供由 Keepa 支持的 Amazon 单个商品（ASIN）历史时间序列数据。它会返回各种指标带时间戳的数据点，支持在可配置的时间范围内（最长 365 天）进行趋势分析。每次查询都针对特定 Amazon 市场中的单个 ASIN。

时间序列格式：所有数据系列均以 {time, value} 对象数组的形式返回，其中 time 是时间戳，value 是该时间点的指标值。BSR 数据包含 categoryName 字段以及 points 数组。请直接分析保存的 JSON 中的这些字段。_dataQuery_executeDynamicQuery 读取的是存储在 SLS 中的 Linkfox 会话数据，而非任意 JSON 文件；其支持的数据映射并不决定这些时间序列是否可以分析。

BSR 逻辑：BSR 数值越小，销售排名越好。排名第 1 的商品是其类别中的畅销商品。用户说“BSR 提升”时，表示数值下降；说“BSR 下滑”时，表示数值上升。

可用数据系列

系列	参数	说明
Buy Box 价格	（始终返回）	Buy Box 价格随时间的变化
最低新品价格	showPrice=1	市场上最低的新品价格
标价	showPriceList=1	删除线价格／标价
优惠价格	showPriceDeal=1	限时秒杀价格
Prime 专享价格	showPricePrime=1	Prime 专享新品价格
FBA 价格	showPriceFba=1	第三方 FBA 新品价格
FBM 价格	showPriceFbm=1	第三方 FBM 新品价格
优惠券价格	showPriceCoupon=1	使用优惠券后的 Buy Box 价格
主类别 BSR	showBsrMain=1	主类别（根类别）中的畅销排名
卖家数量	showSellerCount=1	活跃卖家数量
评分	（始终返回）	商品星级评分随时间的变化
评分数量	（始终返回）	评分数量随时间的变化
月销量	（始终返回）	月度商品销量
子类别 BSR	（始终返回）	子类别中的畅销排名

支持的市场

域名 ID	市场
1	Amazon.com（美国）
2	Amazon.co.uk（英国）
3	Amazon.de（德国）
4	Amazon.fr（法国）
5	Amazon.co.jp（日本）
6	Amazon.ca（加拿大）
8	Amazon.it（意大利）
9	Amazon.es（西班牙）
10	Amazon.in（印度）
11	Amazon.com.mx（墨西哥）
12	Amazon.com.br（巴西）

默认市场为 1（美国）。用户未指定市场时，请使用 domain=1。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-series-<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／套餐到期／需充值／请充值”，或具有类似含义的内容。

参数指南

必需参数

• asin：要查询的 Amazon Standard Identification Number。每次请求仅支持一个 ASIN。
• domain：Amazon 市场的域 ID（见上表）。始终将用户提到的市场映射到正确的数字 ID。

可选参数

• days：要检索的历史天数（1-365，默认值为 90）。短期分析使用 30 天，中期分析使用 90 天，长期分析使用 365 天。
• show* 标志：将任意 show* 参数设为 1，即可包含对应的数据系列。默认情况下，仅返回核心系列（Buy Box 价格、评分、评分数量、月销量、子类别 BSR）。

如何选择参数

1. 价格分析：根据用户想要进行的具体价格比较，启用 showPrice、showPriceList、showPriceDeal、showPriceCoupon。
2. FBA 与 FBM 比较：同时启用 showPriceFba 和 showPriceFbm。
3. 深入分析 BSR：启用 showBsrMain，以获取根类别 BSR，同时也会返回始终包含的子类别 BSR。
4. 竞争格局：启用 showSellerCount，查看参与竞争的卖家数量。
5. 完整商品概览：启用所有 show 标志，获取全面的历史快照。

使用示例

1. 美国商品的基本价格历史

asin: B0XXXXXXXX, domain: 1, days: 90

2. 德国市场的长期 BSR 趋势（1 年）

asin: B0XXXXXXXX, domain: 3, days: 365, showBsrMain: 1

3. 不同配送渠道的价格比较

asin: B0XXXXXXXX, domain: 1, days: 30, showPriceFba: 1, showPriceFbm: 1, showPrice: 1

4. 促销和优惠券价格跟踪

asin: B0XXXXXXXX, domain: 1, days: 90, showPriceDeal: 1, showPriceCoupon: 1

5. 商品全面健康检查

asin: B0XXXXXXXX, domain: 1, days: 90, showPrice: 1, showPriceList: 1, showPriceDeal: 1, showPricePrime: 1, showPriceFba: 1, showPriceFbm: 1, showPriceCoupon: 1, showBsrMain: 1, showSellerCount: 1

展示规则

1. 清晰呈现数据：使用表格展示时间序列数据或描述趋势；除非用户明确要求，否则避免提供主观的商业建议。
2. 说明 BSR：展示 BSR 数据时，提醒用户数值越低，销售排名越高。
3. 价格格式：根据市场使用相应的货币符号显示价格（美国使用 $，德国、法国、西班牙和意大利使用 EUR，英国使用 GBP，日本使用 JPY 等）。
4. 时间格式：以易读的日期格式显示时间戳。
5. 趋势总结：数据系列较长时，总结整体趋势（例如，“价格在 90 天内从 $29.99 降至 $24.99”），并突出显示价格下跌、BSR 激增或评分变化等显著变化。
6. 错误处理：查询失败时，说明原因并建议修正方法（例如，验证 ASIN 是否有效，检查市场域 ID）。
7. 单个 ASIN 限制：如果用户询问多个 ASIN，告知他们必须逐个 ASIN 查询，并依次发起多次调用。

重要限制

• 每次查询仅限一个 ASIN：每次只能查询一个 ASIN。比较多个 ASIN 时，请分别发起请求。
• 最多 365 天：历史数据最多可追溯 365 天。
• 数据粒度：数据点的间隔不固定，具体取决于 Keepa 捕获变更的时间，而非固定的每日间隔。

用户表达与场景速查

适用 —— Amazon 上的产品级历史数据查询：

用户表达	场景
“这个 ASIN 的历史价格是多少？”	价格趋势分析
“显示 BSR 趋势”，“排名情况如何？”	BSR 跟踪
“最近降价了吗”，“有优惠吗？”	降价／优惠检测
“这个商品有多少个卖家？”	卖家数量趋势
“评分趋势如何”，“评论数量随时间如何变化？”	评分／评论跟踪
“FBA 与 FBM 的价格”，“谁获得了 Buy Box？”	配送价格对比
“这个产品的月销量”	销量趋势
“这个 ASIN 是否发生过价格战？”	竞争性定价分析
“显示 Keepa 图表”，“Keepa 数据”	明确请求 Keepa 数据

不适用 —— 需求超出产品级历史数据范围：

• 搜索词／关键词分析（请改用 ABA 数据）
• 广告／PPC 广告活动数据
• 商品信息文案撰写或内容优化
• 全品类或市场级汇总趋势（此工具仅针对单个 ASIN）
• 实时库存或库存水平查询
• 商品评论文本或情感分析

边界判断：当用户提到“产品调研”或“竞品分析”时，如果需求归结为查看特定 ASIN 的历史价格、BSR 或销量数据，则适用此技能。如果需要关键词数据、全市场趋势或广告指标，则不适用。

算力消耗规则

按动态规则计费：消耗算力 = 0.045 × 本次历史趋势查询消耗的 Keepa token。

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

反馈：

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

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

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

---

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