获取亚马逊 SP/SB/SD…

当用户需要拉取 Amazon Ads 的 SP/SB/SD 广告活动、关键词、搜索词、投放商品、购买商品、广告组、流量异常、Prompt 扩展等报告时使用。

适用场景

解决思路

1. 先安装并确保依赖 linkfox-amazon-ads-auth 可用；脚本启动会自动检查，未安装时 exit 42 且 stderr 输出 DEPENDENCY_MISSING。
2. 多账号调用前必须解析 profileId：先调 linkfox-amazon-ads-auth 的 authorized_stores.py 拉出用户已授权的账号 × 站点清单。
3. 根据用户提到的站点映射到 countryCode（如 美国→US）匹配候选 profile：只有 1 个候选时静默取对应 profileId 并继续调用，不要把 profileId 数字播报给用户。
4. 若同站点下有 ≥ 2 个候选，必须向用户澄清，用 accountName 问，例如：你在美国站授权了 A 和 B 两个账号，这次用哪个？
5. 若 0 个候选，告知用户该站点未授权，并引导去 linkfox-amazon-ads-auth 做授权。
6. 严禁让用户直接报 profileId 数字。
7. 严禁在歧义下挑第一个或选默认绕过澄清。
8. 完整决策表见 linkfox-amazon-ads-auth SKILL.md 的 Usage Scenarios 第 4 节。
9. API 调用使用端点 POST /amazonAds/developerProxy，不同操作通过请求体区分；完整参数、响应、错误码见 references/api.md。
10. Python 脚本调用格式：python scripts/<脚本名>.py '<JSON 参数>' [--inline]；可用脚本见脚本一览。
11. 遵守成本约束：本工具会消耗算力；失败或空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。
12. 输出策略：始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json，<cwd> 为脚本执行时工作目录，<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错。
13. 响应体 ≤ 8 KB 时：落盘后把完整 JSON 打印到 stdout。
14. 响应体 > 8 KB 时：落盘后 stdout 只输出摘要，包括顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本。
15. 加 --inline 可强制全量打印到 stdout，同样落盘。
16. 读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
17. 认证和算力异常：未配置 API Key，即环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
18. 认证和算力异常：响应 401 或 402 状态码。
19. 认证和算力异常：响应提示算力或余额不足，消息含算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值或类似含义。
20. 发生认证和算力异常时，采用 references/onboarding.md 引导解决问题。
21. Core Concepts 覆盖：SP / SB / SD 全部报告类型，以 references/report-types/ 下存在的 .md 为准；ST / DSP 暂未覆盖。
22. Core Concepts 一站式：脚本内部自动完成报告创建 → 等待生成（约 2–10 分钟）→ 下载 → 解压，调用方只需等最终结果。
23. Core Concepts 单脚本：get_report.py 覆盖 SP / SB 全部 adProduct。
24. Core Concepts 元数据 vs 运行参数：每个报告类型的可用字段（timeUnit / groupBy / filters / 全部列名）集中在 references/report-types/<adProduct-dir>/<reportTypeId>.md；脚本运行参数（等待间隔、访问链接时效等）见本文件和 references/api.md。
25. 可用脚本 get_report.py：一站式执行；必填 adProduct / groupBy / columns，由 agent 从 report-types/ 提取后传入。
26. 可用脚本 check_auth_dependency.py：检测 linkfox-amazon-ads-auth 是否安装。
27. 完整脚本参数、响应结构见 references/api.md。
28. Agent 调用流程第 1 步：定 reportTypeId，按用户意图挑选，如上周花费→spCampaigns；哪个商品卖得好→spAdvertisedProduct / sbPurchasedProduct；用户搜什么词找到我→spSearchTerm。
29. Agent 调用流程第 2 步：查 reference，打开 references/report-types/<adProduct-dir>/<reportTypeId>.md。
30. Agent 调用流程第 2 步：读取 frontmatter，给出 adProduct / groupBy（Configuration 表推荐的） / timeUnit（可枚举） / format / dateRange / filters。
31. Agent 调用流程第 2 步：读取 Base metrics 表，得到此报告类型允许的全部列名。
32. Agent 调用流程第 3 步：向用户咨询可定制条件，用户答默认/随便时跳过，进入第 4 步的默认选择。
33. Agent 调用流程第 3 步咨询 timeUnit：DAILY（按日拆分）还是 SUMMARY（汇总）。
34. Agent 调用流程第 3 步咨询 columns 扩展：是否要归因列（sales7d / purchases7d / acosClicks7d / roasClicks7d）、视频指标、newToBrand 等。
35. Agent 调用流程第 3 步咨询 filters：是否过滤 campaignStatus / keywordType / adStatus 等。
36. Agent 调用流程第 4 步：按用户回复或默认构造 columns，默认条件见下节。
37. Agent 调用流程第 5 步：调脚本，adProduct / groupBy / columns 三个必填字段必须显式传入。
38. 默认条件 timeUnit：日期跨度 ≤ 7 天→DAILY；> 7 天→SUMMARY。
39. 默认条件 columns 身份维度：DAILY 时必含 date；SUMMARY 时必含 startDate + endDate。
40. 默认条件 columns 身份维度：再追加该报告的主键字段，参考 frontmatter 中 groupBy 对应的主键，如 campaignId+campaignName / advertisedAsin+advertisedSku / searchTerm / keyword 等。
41. 默认条件 columns 基础指标：impressions / clicks / cost，以该报告 Base metrics 存在的为准。
42. 默认条件 columns 归因指标：仅当用户提到销售/转化/ROI/ACOS 等意图时追加 sales7d / purchases7d / acosClicks7d / roasClicks7d，以 Base metrics 存在者为准。
43. 默认条件 filters：不加，全量返回。
44. 默认条件 groupBy：取 frontmatter groupBy 数组的第一个值，即 Configuration 表里 Amazon 官方推荐的主维度。
45. 请求示例 1 SP 广告活动报告：调用 python scripts/get_report.py，传入 profileId: 1234567890、region: NA、reportTypeId: spCampaigns、adProduct: SPONSORED_PRODUCTS、groupBy: [campaign]、columns: [date, campaignId, campaignName, impressions, clicks, cost]、startDate: 2026-04-27、endDate: 2026-05-03、timeUnit: DAILY。
46. 请求示例 2 SP 搜索词报告（含归因）：调用 python scripts/get_report.py，传入 profileId: 1234567890、region: NA、reportTypeId: spSearchTerm、adProduct: SPONSORED_PRODUCTS、groupBy: [searchTerm]、columns: [searchTerm, keyword, matchType, impressions, clicks, cost, sales7d, sales14d, purchases7d, acosClicks14d, roasClicks14d, startDate, endDate]、startDate: 2026-04-01、endDate: 2026-04-30、timeUnit: SUMMARY、filters: [{field: keywordType, values: [BROAD, PHRASE, EXACT]}]。
47. 请求示例 3 SB 广告组报告：调用 python scripts/get_report.py，传入 profileId: 1234567890、region: NA、reportTypeId: sbAdGroup、adProduct: SPONSORED_BRANDS、groupBy: [adGroup]、columns: [adGroupId, adGroupName, impressions, clicks, cost, purchases, sales, startDate, endDate]、startDate: 2026-04-01、endDate: 2026-04-30。
48. 请求示例 4 SD 广告活动报告：调用 python scripts/get_report.py，传入 profileId: 1234567890、region: NA、reportTypeId: sdCampaigns、adProduct: SPONSORED_DISPLAY、groupBy: [campaign]、columns: [date, campaignId, campaignName, impressions, clicks, cost, purchases, sales]、startDate: 2026-04-27、endDate: 2026-05-03、timeUnit: DAILY。
49. 请求示例 5 轮询一个已有 reportId（救回上次超时 / 手工恢复）：当上次因客户端轮询窗口太短退出但报告在 Amazon 侧仍在跑时，直接传入 reportId 跳过创建，继续轮询并下载；此模式只需 profileId / region / reportId，其余字段不必填。
50. 请求示例 5 命令：python scripts/get_report.py，传入 profileId: 1234567890、region: NA、reportId: 7df1ef5d-45ba-40cc-b607-ff2148cf4f5e、maxAttempts: 60、pollInterval: 30。
51. 自动恢复：如果调用方未传 reportId、且 Amazon 对同参数请求触发去重（返回 HTTP 425 duplicate of <uuid>），脚本会自动解析出老 reportId 并转为轮询该老报告，无需重试。
52. 成功响应格式包含 success: true、reportId、reportTypeId、startDate、endDate、downloadPath、extractedFileHttpUrl、extractedFileHttpServeSeconds。
53. 失败响应格式包含 error、httpStatus、body；例如 Upstream HTTP 400、httpStatus: 400、body 含 code、detail。
54. 调用原则：用户指定了 reportTypeId 就只拉那一种，不擅自替换。
55. 调用原则：报告失败（非 2xx 或 status=FAILED）时如实告知错误原因，不盲目重试。
56. 调用原则：成功后把报告的本地文件路径和访问链接完整展示给用户，并提醒访问链接有时效，默认 5 分钟内有效，过期需重新拉取。
57. 调用原则：超时不是失败，当脚本返回 status=STILL_PROCESSING（exit code=2），说明客户端已等满默认约 7.5 分钟但报告仍在 Amazon 侧生成。
58. 遇到 STILL_PROCESSING 时必须向用户说明情况并询问是否继续等待，绝不能当成失败处理。
59. 参考回复：报告还在 Amazon 侧生成中（已等约 7.5 分钟），要继续等吗？可以选：A. 再等 ~30 分钟（maxAttempts=60）、B. 再等 ~1 小时（maxAttempts=120）、C. 先停，我稍后用 reportId 回来。
60. 用户选 A/B 时，用 resumeHint.params 切到仅轮询模式续跑。
61. 常见错误 Missing required parameters: adProduct/groupBy/columns：调用方未显式传入三必填；回到 Agent 调用流程第 2 步，从 references/report-types/<adProduct-dir>/<reportTypeId>.md 读出并补上。
62. 常见错误 HTTP 401：accessToken 过期；调 ads-auth 的 refresh_token.py 后重试。
63. 常见错误 HTTP 403：未关联广告账户或权限不足；到 Amazon Ads 后台检查经理账户/广告账户关联。
64. 常见错误 HTTP 400 must not exceed maximum range：日期跨度超限，多数 31 天；拆分拉取后本地合并，具体上限看对应 .md frontmatter dateRange.maxSpanDays。
65. 常见错误 HTTP 400 含 columns/groupBy 校验错：列名拼写错 / 与 reportTypeId 不匹配 / 超出 Base metrics；对照 .md 文件 Base metrics 表核对。
66. 常见错误 status=FAILED 含 failureReason：上游生成失败；多为日期窗口或权限问题，按 failureReason 具体处理。
67. 常见错误 status=STILL_PROCESSING (exit 2)：客户端轮询窗口耗尽但报告仍在生成；不是失败，stdout 已含 reportId 与 resumeHint.params；询问用户是否继续等，用该 params（带 reportId + 更大 maxAttempts）切到仅轮询模式续跑。
68. 常见错误 HTTP 425 duplicate of：同参数已有在跑的报告；脚本自动解析并转为轮询该老 reportId，正常情况下调用方无需干预。
69. 常见错误 exit 42：依赖 skill 未安装；先装 linkfox-amazon-ads-auth。
70. 日期与数据：日期跨度上限多数报告 31 天；sbPurchasedProduct 是 731 天；spGrossAndInvalids / sbGrossAndInvalids / sdGrossAndInvalids 是 365 天，以 frontmatter 为准。
71. 日期与数据：回溯窗口 SP 默认 95 天、SB 60 天、GrossAndInvalids 365 天；具体以 frontmatter dateRange.dataRetentionDays 为准。
72. 日期与数据：数据延迟约 12 小时；endDate >= 今天脚本 stderr 警告但不拦截。
73. 日期与数据：空数据不等于报错；账号当期无投放时报告会成功生成，JSON 可能为 [] 或指标全 0。
74. Amazon Ads API 接口保护：同一广告账号/profile 连续收到 Amazon Ads API 的 400、403、404 或 429 时，网关会返回 450、453、454 或 459 并短暂冷却；这些自定义状态码不是 Amazon 原生状态，也不表示封号。
75. 450：400，请求异常，请优化您的参数；范围广告账号/profile+接口；60 秒内超过 3 次→5 分钟，10 分钟内超过 4 次→20 分钟；处理：停止原参数重试，检查 profileId、region、实体/报告 ID、日期和请求体。
76. 453：403，店铺未授权，请先授权；范围广告账号/profile 全部接口；60 秒内超过 2 次→5 分钟，10 分钟内超过 4 次→30 分钟；处理：停止该广告账号调用，检查 Ads 授权、应用权限、profile 归属和区域。
77. 454：404，资源不存在，请优化您的参数；范围广告账号/profile+接口；60 秒内超过 3 次→5 分钟，10 分钟内超过 4 次→30 分钟；处理：确认资源 ID、所属 profile/区域、资源状态和接口路径。
78. 459：429 限流中，请降低频率；范围广告账号/profile+接口；首次→15 秒，2 分钟内超过 2 次→30 秒，3 分钟内超过 4 次→2 分钟；处理：降低并发、分页和轮询频率并逐级退避。
79. 接口保护处理：立即停止自动或并发重试，不得通过换脚本或重复创建任务绕过保护；优先遵循 retryAfter、blockedUntil，没有时按表中时长说明。
80. 450/453/454 必须先修正参数、授权或资源标识，冷却后最多谨慎重试一次；再次触发则停止调用；453 期间停止该广告账号/profile 全部 Ads API。
81. 保留已有 reportId 等任务 ID；写操作结果不确定时先查询状态，不直接重放。
82. 向用户先说明广告账号保护，再给原因、处理和等待时间。可回复：为保护您的亚马逊广告账号安全，检测到 Amazon Ads API 连续返回{原因}，当前已进入短暂保护。请先{处理动作}，预计{等待时间}后再试；这不代表封号，也不是套餐或积分限制。不要只说 LinkFox 限流或服务器繁忙。
83. 算力消耗规则：不消耗算力。
84. Feedback：当功能或目的与实际行为不符、结果不符合用户意图、用户表达不满意或表扬、有任何可改进项时，通过 Feedback API 自动检测并报告。
85. Feedback：按 references/api.md 调用 Feedback API，不要打断用户流程。

适用边界 · 注意事项

• 不适合 Brand Analytics / Retail Analytics / Attribution 报告，也不适合报告删除/修改/定时任务。
• 不适合获取实体元数据（campaign 名、keyword 匹配类型等），应使用 linkfox-amazon-ads-manager。
• 不适合处理授权/token，应使用 linkfox-amazon-ads-auth。