linkfox-keepa-product-request

Keepa 产品数据请求

本技能将指导你如何通过 Keepa 产品请求 API 获取 Amazon 产品详情，帮助 Amazon 卖家和分析师获取一个或多个 ASIN 在多个 Amazon 站点的结构化产品数据。

核心概念

Keepa 产品请求 API 会返回 Amazon 商品详情页的详细数据，数据由 Keepa 提供。提供一个或多个 ASIN 和站点后，API 会返回全面的产品信息：价格、标题、商品亮点（itemHighlights，如有）、主图、上架日期、材质、重量、尺寸、销售排名、月销量（当前数据及最多 12 个月的历史数据）、FBA 费用、评分、评论数、类目树等。

要点：

• 单次请求最多可查询 5 个 ASIN，多个 ASIN 之间用逗号分隔。
• domain 参数是数字形式的站点 ID（例如，1 = Amazon.com 美国站），不是国家代码。
• 将 history 设为 1 可包含历史销售数据（月销量的历史数据最多追溯至之前 12 个月，以及过去 30/90/180 天的平均销售排名）。设为 0 时只返回当前产品信息。
• products[].itemHighlights 是与 title 分开的单条简短产品信息；其值可能为 null、空白或不存在。无需额外请求参数即可返回，且可在 history=0 时返回。
• 响应不包含完整的产品描述或评论内容。商品亮点与要点列表（features）或完整描述不同。

参数指南

domain（必填）

数字形式的 Amazon 站点 ID。对应关系如下：

站点 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（美国）。

asin（必填）

一个或多个 Amazon 标准识别码。多个 ASIN 之间用逗号分隔。每次请求最多 5 个 ASIN，总字符串长度不得超过 300 个字符。

history（可选）

是否包含历史数据，例如过去 12 个月的月销量以及过去 30/90/180 天的平均销售排名。设为 1 可包含历史数据；设为 0（默认值）则仅返回基本信息。

使用示例

1. 查询单个 ASIN（美国站点，基本信息）

{"asin": "B0088PUEPK", "domain": "1"}

2. 查询单个 ASIN，并包含历史销售数据

{"asin": "B0088PUEPK", "domain": "1", "history": 1}

3. 批量查询多个 ASIN（德国）

{"asin": "B0088PUEPK,B00U26V4VQ,B07M68S376", "domain": "3", "history": 1}

4. 查询 Amazon 日本站的产品

{"asin": "B09V3KXJPB", "domain": "5", "history": 0}

5. 对比多个 ASIN 的竞品（美国，包含销售历史）

{"asin": "B0CXYZ1234,B0CXYZ5678,B0CXYZ9012,B0CXYZABCD", "domain": "1", "history": 1}

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-keepa-product-request-<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. 清晰呈现数据：使用结构清晰的表格展示产品详情。将相关字段分组（例如，将尺寸放在一起、销售数据放在一起），以便于阅读。
2. 价格和货币：始终同时显示价格和货币（例如，“$29.99 USD”）。响应中的 currency 字段表示当地货币。
3. 销售趋势：如果包含历史数据，请用表格展示 12 个月的销售趋势，或描述其走势（增长、下降、稳定），帮助用户快速评估销售势头。
4. 尺寸和重量：在适当的情况下，将毫米值换算为更直观的单位（例如，同时显示 mm 和英寸，或 mm 和 cm）。请注意，重量单位为克。
5. 不可用的数据：值为 0 或 -1 的字段表示数据不可用。不要将其显示为实际测量值；请改为标注“N/A”或省略。
6. 图片展示：如果存在 imageUrl，请显示产品图片，帮助用户直观识别产品。
7. 错误处理：查询失败时，根据响应说明问题并建议修正方法（例如，ASIN 格式无效、市场不受支持）。
8. 大量批量查询结果：对于包含多个 ASIN 的批量查询，请先展示汇总表，并告知用户可按需查看各个产品的详情。
9. 商品亮点：从完整响应中的 products[].itemHighlights 读取内容，而不是只读取 stdout 摘要或 columns。将原始值与 title 分开显示。如果该字段缺失、为 null 或为空，请标注“未返回/不可用”；不要据此推断 Amazon 商品详情页上没有该内容，也不要根据标题、要点或描述重新构造内容。

重要限制

• 不提供完整产品描述或评论：API 可以返回简短的商品亮点，但无法返回完整的产品描述文本或评论内容。
• 商品亮点的可用性：需要后端部署透传 itemHighlights，且上游数据可用。不要承诺每个 ASIN 都会返回该字段。
• 每次请求最多 5 个 ASIN：批量查询上限为 5 个 ASIN。
• ASIN 字符串长度限制：asin 参数的最大长度为 300 个字符。
• 历史数据为可选项：只有在 history 设为 1 时，才会返回月度销售历史。
• 数据新鲜度：lastUpdate 字段表示产品数据上次刷新的时间。

用户表达与场景速查

适用 —— 按 ASIN 检索商品数据：

用户表达	场景
“查询这个 ASIN”、“获取 B0XXXXXXXX 的商品详情”	查询单个 ASIN
“查询这个 ASIN 的 Item Highlights”、“标题之外的商品亮点/补充信息”	单独检索现有的 itemHighlights，与 title 分开
“这个商品在 Amazon 上的价格是多少”	价格查询
“这个商品每月销量是多少”	月销量查询
“比较这些 ASIN”、“批量查询这些商品”	多个 ASIN 对比
“显示这个 ASIN 的销售趋势”	历史销售分析
“这个商品属于什么类别”	类别／分类查询
“商品尺寸”、“重量是多少”	物理规格查询
“这个商品的 FBA 费用”	费用估算
“这个商品是什么时候上架的”、“上架日期”	上架时长／发布日期
“这个商品是 FBA 还是 FBM”	配送方式查询

不适用 —— 需求超出 ASIN 级商品数据范围：

• 搜索词／关键词分析（请改用 ABA 数据工具）
• 完整商品描述、评论文本或生成新的商品文案（支持检索现有的 title 和 itemHighlights）
• 广告／PPC 活动数据
• 卖家账户或店铺级分析
• 未指定具体 ASIN 的商品调研（例如，“查找厨房类别中的热门商品”）
• 价格历史图表或 Buy Box 历史记录（仅提供当前数据和平均排名数据）

适用范围判断：用户提到“商品调研”或“竞品分析”时，如果他们提供了具体 ASIN，并希望获取结构化商品数据（价格、销量、尺寸、类别），则适用此技能。如果他们需要关键词级分析、没有具体 ASIN 的全市场趋势或广告指标，则此技能不适用。

算力消耗规则

按动态规则计费：消耗算力 = 0.045 × 本次商品详情查询消耗的 Keepa token。

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

反馈：

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

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

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

---

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