Amazon 店铺报告获取#

本 skill 提供 亚马逊卖家后台报告的端到端自动化获取：请求 → 轮询 → 下载 → 解压 → 预览。支持 95+ 种报告类型（库存 / 订单 / 销售 / 财务 / FBA / 退货 / Brand Analytics 等）。

---

⚠️ Prerequisites — MUST READ FIRST#

本 skill 依赖 linkfox-amazon-store-auth（授权与店铺/令牌管理）。

🛑 如果 linkfox-amazon-store-auth 未安装 / 未加载，请先安装它，再回到本 skill。

怎样判断 linkfox-amazon-store-auth 是否可用#

在执行任何报告任务之前，agent 必须 先进行依赖检查：

1. 读取下列任一路径（skill 加载路径取决于运行环境； scripts/check_auth_dependency.py 会按相同规则自动探测）：

   • 仓库 / 通用扁平目录： <skills_dir>/linkfox-amazon-store-auth/SKILL.md
   • Claude： ~/.claude/skills/linkfox-amazon-store-auth/SKILL.md
   • Cursor： ~/.cursor/skills/...、 ~/.cursor/skills-cursor/...
   • OpenClaw： <OPENCLAW_WORKSPACE>/skills/...、 ~/.openclaw/skills/...、 ~/.agents/skills/...（与 OpenClaw Skills 文档 的常见路径一致）
   • Hermes Agent： ~/.hermes/skills/<category>/linkfox-amazon-store-auth/SKILL.md，以及 ~/.hermes/plugins/<plugin>/skills/linkfox-amazon-store-auth/SKILL.md（与 Hermes Skills 文档 的布局一致）

2. 或直接运行脚本： python scripts/check_auth_dependency.py，脚本会在缺失时以 exit code 42 退出，并在 stderr 输出结构化提示（以 DEPENDENCY_MISSING: 开头）。脚本已内置 OpenClaw / Hermes 路径判断；若在 Hermes 的 config.yaml 里配置了 skills.external_dirs，请设置环境变量 HERMES_SKILLS_EXTERNAL_DIRS（使用系统路径分隔符串联多个目录）以便探测。

3. 如果上述检查 全部失败，则判定为 linkfox-amazon-store-auth 未安装。

发现未安装时的标准处置#

当检测到 linkfox-amazon-store-auth 未安装时，agent 必须 按以下顺序执行：

1. 尝试自动安装（优先）：

   • 如果当前运行时具备 skill 安装工具（例如 skill 市场 / skill 管理 MCP / install_skill 类工具）， 立即调用 安装 linkfox-amazon-store-auth。
   • 安装成功后，重新加载并从头执行本 skill。

2. 引导用户手动安装（兜底）：

   • 向用户说明：「本技能依赖 linkfox-amazon-store-auth，尚未安装。请前往 LinkFox Skills 安装该 skill，安装完成后告诉我一声，我会继续为你拉取报告。」
   • 不要 绕过依赖直接去调 /spApi/authorizeUrl、 /spApi/storeTokens、 /spApi/authorizedStores 等接口——这些接口的选店铺、令牌流程属于 linkfox-amazon-store-auth 的职责，本 skill 只负责报告业务本身。

3. 不得静默降级：如果既无法自动安装也未获得用户确认，必须 停止执行 并把依赖缺失的事实回报给用户，不要擅自尝试替代方案。

依赖已满足后的协作方式#

• 本 skill 依赖 auth 选店（ sellerId + region），直接经 /spApi/developerProxy 执行报告生命周期（服务端解析 token）。
• 授权、授权的前置选店铺、令牌刷新等操作—— 交由 linkfox-amazon-store-auth；本 skill 不重复做这些事。

---

Core Concepts#

• Report Type（报告类型）：亚马逊官方报告类型枚举，例如 GET_MERCHANT_LISTINGS_ALL_DATA、 GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL。完整列表见 references/report-types.md。
• Marketplace ID：区域内具体站点 ID，例如 US = ATVPDKIKX0DER。
• Report lifecycle：请求报告 → 轮询 processingStatus（ IN_QUEUE / IN_PROGRESS / DONE / FATAL / CANCELLED）→ DONE 后拿到 reportDocumentId → 取下载 URL → 下载（多为 gzip TSV）→ 解压。
• Rate limits：Reports API 约 0.0222 req/s；轮询需保留间隔（默认 30s）。

Data Fields#

Report Request Input#

FieldTypeRequiredDescriptionsellerIdstringYes已授权的 Amazon Seller IDregionstringYesNA / EU / FEreportTypestringYes报告类型枚举值marketplaceIdsarrayYes目标 marketplace ID 列表dataStartTimestringNoISO 8601，报告起始时间dataEndTimestringNoISO 8601，报告结束时间lastUpdatedDatestringNo部分 Vendor 报告必填，见 references/report-requests/ 对应 mdreportOptionsobjectNo如 Brand Analytics 的 reportPeriod、 asin/ asins；销售流量的 dateGranularity/ asinGranularity 等。 每一 reportType 说明： references/report-requests/types/<REPORT_TYPE>.md（索引 types/README.md）；有 JSON Schema 的另见 report-requests/README.mdpollIntervalintNo轮询间隔秒数（默认 30）maxAttemptsintNo最大轮询次数（默认 20）

Report Output#

FieldTypeDescriptionreportIdstring报告请求 IDreportDocumentIdstring报告文档 IDdownloadPathstring本地下载后的 绝对路径（已解压，含文件名）fileNamestring保存文件名（与 downloadPath 末段一致）localFileUristring本机 file:// URI，便于客户端打开本地文件extractedFileHttpUrlstring本机临时 HTTP 直链，用于在浏览器中下载 已解压 后的文件（默认 serveExtractedFileHttp 开启）extractedFileHttpServeSecondsint本地 HTTP 服务保持时长（默认 300，最少 10）extractedFileHttpNotestring说明该链接仅本机、限时有效amazonDownloadUrlstring（可选）仅当 includeAmazonSourceUrl: true 时出现：Amazon 源地址，一般为压缩包，通常不必给终端用户compressionAlgorithmstring若接口返回了压缩算法则带上（如 GZIP）tempDirectorystring临时目录fileSizeint文件大小（字节）

调用方式#

• API 端点： POST /spApi/developerProxy（不同操作通过请求体区分；完整参数/响应/错误码见 references/api.md）
• Python 脚本： python scripts/<脚本名>.py '<JSON 参数>' [--inline]（可用脚本见下文脚本一览）
• 成本约束：本工具会消耗算力；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

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

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

Available Scripts#

• scripts/get_report.py ⭐ — 端到端自动化报告获取（ 推荐）
• scripts/check_auth_dependency.py — 主动检测依赖 skill linkfox-amazon-store-auth 是否已安装

解决认证和算力问题#

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

异常情况#

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

Usage Scenarios#

Scenario 0: Dependency Check (MUST run first)#

每次进入本 skill 都要先跑这一步。

1. 尝试读取 linkfox-amazon-store-auth/SKILL.md（若工具允许）

2. 或执行： bash

   python scripts/check_auth_dependency.py
   
   

3. 若 exit code 非 0 或 stderr 含 DEPENDENCY_MISSING:，按上文「发现未安装时的标准处置」流程处理

4. 依赖满足后再进入正常业务场景

Scenario 1: Pull Amazon Report (Automated, Recommended)#

User request：「我要拉库存报告」/「获取订单报告」/「下载销售流量报告」等

Steps：

1. 依赖检查（Scenario 0）

2. 前置选店铺：委托 linkfox-amazon-store-auth

   • 调 /spApi/authorizedStores 让用户选店铺，确定 sellerId + region
   • 不要 先调 /spApi/storeTokens 取 raw token；脚本直接经 developerProxy 传选择器

3. 识别报告类型：按用户诉求匹配 reportType

   • 库存： GET_MERCHANT_LISTINGS_ALL_DATA、 GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA
   • 订单： GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL
   • 销售流量： GET_SALES_AND_TRAFFIC_REPORT
   • 财务： GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE
   • 完整清单： references/report-types.md

4. 执行脚本： bash

   python scripts/get_report.py '{
     "sellerId": "A1EC6SZ7XAMURH",
     "region": "NA",
     "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
     "marketplaceIds": ["ATVPDKIKX0DER"]
   }'
   
   

5. 脚本会自动：以 sellerId + region 调 developerProxy（服务端解析 token）→ 请求报告 → 轮询 → 下载 → 解压 → 预览 → 输出 JSON； 完成后 在 stderr 与 JSON 中给出 本地绝对路径（ downloadPath）、 本机 file URI（ localFileUri），并默认启动短时本机 HTTP 服务，生成 extractedFileHttpUrl（用于在 同一台机器 的浏览器里下载 已解压 文件）。向用户展示时至少给出 extractedFileHttpUrl、 downloadPath 与 fileName；脚本在 serveSeconds 计时结束后会关闭服务，链接随即失效。若需 Amazon 源地址（多为压缩包），仅调试时设 includeAmazonSourceUrl: true。

Scenario 2: Manual Report Flow (Advanced)#

对需要精细控制的场景，可通过 /spApi/developerProxy 手工驱动：

1. 取现有报告（更快）： text

   path: reports/2021-06-30/reports
   method: GET
   queryString: reportTypes=<type>&marketplaceIds=<ids>
   
   

2. 创建新报告： text

   path: reports/2021-06-30/reports
   method: POST
   body: {"reportType": "...", "marketplaceIds": [...]}
   
   

3. 查状态： text

   path: reports/2021-06-30/reports/{reportId}
   method: GET
   
   

4. 取下载链接： text

   path: reports/2021-06-30/documents/{reportDocumentId}
   method: GET
   
   

Scenario 3: Custom Date Range / Polling#

bash

python scripts/get_report.py '{
  "sellerId": "A1EC6SZ7XAMURH",
  "region": "NA",
  "reportType": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
  "marketplaceIds": ["ATVPDKIKX0DER"],
  "dataStartTime": "2024-01-01T00:00:00Z",
  "dataEndTime": "2024-01-31T23:59:59Z",
  "pollInterval": 15,
  "maxAttempts": 40
}'

Marketplace IDs by Region#

RegionCountryMarketplace IDNAUnited StatesATVPDKIKX0DERNACanadaA2EUQ1WTGCTBG2NAMexicoA1AM78C64UM0Y8EUUnited KingdomA1F83G8C2ARO7PEUGermanyA1PA6795UKMFR9FEJapanA1VC38T7YXB528

更多 marketplace ID 详见 references/report-types.md。

Display Rules#

1. 先依赖后业务：依赖检查未通过前， 不得 开始任何报告相关调用。
2. 只呈现数据：展示报告获取进度、下载路径、前几行预览；不做业务解读。
3. 尊重用户选择的报告类型：用户指定了报告类型就只拉那一种，不得擅自换其他类型。
4. 错误清晰：报告失败（ FATAL / 403 等）时，解释原因并把决定权交还用户。
5. 安全：不输出/不传递 raw token；业务只依赖 sellerId + region。
6. 完成后展示地址与本机下载链接：脚本成功结束后，必须把 extractedFileHttpUrl（已解压文件的本机 HTTP 下载，限时）、 downloadPath（本地绝对路径）、 fileName（文件名）及 localFileUri 告知用户；并说明「仅在运行脚本的同一台电脑、在服务保持时间内可用」。不要默认把 Amazon 源 URL 当作用户下载入口；仅在用户明确要求或排障需要时使用 includeAmazonSourceUrl。

CRITICAL: Report Failure Handling Rules#

• NEVER automatically try alternative report types when user's specified report fails.
• 报告请求失败（ FATAL、403 等）时， 立即停止并把失败事实告知用户。
• 不要 替用户决定去拉别的报告类型。
• 把失败原因说清楚，让用户决定下一步（重试 / 换类型 / 查权限等）。
• 例： GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT 失败时， 不要 自动改拉 GET_MERCHANT_LISTINGS_ALL_DATA。

Common Report Failure Reasons#

• 403 Unauthorized：缺少 API 权限或未加入 Amazon Brand Registry
• FATAL：该店铺不支持此报告类型或数据不足
• Brand Analytics 类报告需要品牌备案
• Vendor 类报告仅限 Vendor 账号

Important Limitations#

• 依赖 linkfox-amazon-store-auth：未安装则必须先安装，见 Prerequisites。
• Token expiration：服务端令牌约 1 小时过期； developerProxy 可按 sellerId + region 自动解析/续签。过期时也可经 auth skill 的 refreshToken 后重试。
• Rate limits：Reports API 0.0222 req/s，默认 30s 轮询是安全间隔。
• Report 时效：部分财务报告可能需要 10–30 分钟，按需调大 maxAttempts。
• Path 白名单：后端 sp-api.developer-proxy.allowed-path-prefixes 必须允许 reports/2021-06-30/reports。

User Expression & Scenario Quick Reference#

Applicable — 报告获取场景：

User SaysScenario"拉亚马逊库存报告" / "pull inventory report"Scenario 1"下载订单数据" / "download orders report"Scenario 1"获取销售流量报告" / "sales and traffic report"Scenario 1"拉财务结算报告" / "settlement report"Scenario 1"查 FBA 库存" / "FBA inventory report"Scenario 1"拉某时间段的订单报告" / "orders from 2024-01-01 to ..."Scenario 3

Not applicable — 超出本 skill：

• 授权新店铺、列已授权店铺、刷新/查询令牌 → 请使用 linkfox-amazon-store-auth
• 商品 listing 管理、订单处理、广告投放 → 由其他 skill 负责

Boundary judgment：

• 本 skill 只负责「依赖检查 + 报告获取业务」， 授权/令牌属于依赖 skill。
• 任何进入本 skill 的调用都要先跑 Scenario 0。

---

Amazon SP-API 接口保护与重试指引#

同一店铺连续收到 Amazon SP-API 的 400、403、404 或 429 时，网关会返回 450、453、454 或 459 并短暂冷却。这些自定义状态码不是 Amazon 原生状态，也不表示封号；目的是避免持续异常或高频调用扩大店铺风险。

状态与 message范围触发与冷却处理450： 400，请求异常，请优化您的参数店铺+接口60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：20 分钟停止原参数重试，检查必填字段、marketplace、ID、日期和请求体453： 403，店铺未授权，请先授权店铺全部接口60 秒内超过 2 次：5 分钟；10 分钟内超过 4 次：30 分钟停止该店铺调用，检查授权、权限、店铺归属和区域454： 404，资源不存在，请优化您的参数店铺+接口60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：30 分钟确认资源 ID、所属店铺/站点、资源状态和接口路径459： 429限流中，请降低频率店铺+接口首次：15 秒；2 分钟内超过 2 次：30 秒；3 分钟内超过 4 次：2 分钟降低并发、分页和轮询频率并逐级退避

• 立即停止自动或并发重试，不得通过换脚本或重复创建任务绕过保护；优先遵循 retryAfter、 blockedUntil，没有时按表中时长说明。
• 450/453/454 必须先修正参数、授权或资源标识，冷却后最多谨慎重试一次；再次触发则停止调用。453 期间停止该店铺全部 SP-API。
• 保留已有 reportId、 feedId 等任务 ID；写操作结果不确定时先查询状态，不直接重放。
• 向用户先说明店铺保护，再给原因、处理和等待时间。可回复：“为保护您的亚马逊店铺安全，检测到 Amazon SP-API 连续返回{原因}，当前已进入短暂保护。请先{处理动作}，预计{等待时间}后再试；这不代表封号，也不是套餐或算力限制。”不要只说“LinkFox 限流”或“服务器繁忙”。

算力消耗规则#

不消耗算力。

Feedback：

出现以下任一情况时，自动调用 Feedback API 上报：

1. 本 skill 功能描述与实际不符
2. 结果与用户意图不符
3. 用户表达了不满或赞赏
4. 其他你认为可改进的点

按 references/api.md 中的规范调用 Feedback API，不要打断用户主流程。

---

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.