Linkfox Amazon Ads Sp Insights Report

Amazon Ads SP 洞察报告获取

两类 Sponsored Products 专项报告一站式获取：脚本经 developerProxy 传 profileId（服务端解析 token），自动完成 advertiser account 映射、报告创建、等待（通常约 2–10 分钟）、多分片 CSV 下载和落盘。 脚本使用 Amazon Reporting API v1 beta 允许的固定字段组合，不接受调用方自由拼接字段。Audience 与 Search Term Impression Share/Rank 的完整字段依据分别见 references/sp-audience-reporting-v1.md 和 references/sp-search-impression-share-v1.md。

依赖 linkfox-amazon-ads-auth（脚本启动自动检查；未安装时 exit 42，stderr 打 DEPENDENCY_MISSING）。

⚠️ 多账号场景：调用前必须解析好 profileId

用户经常只说自然语言（“美国站”“日本站”“我的店铺”），本 Skill 的所有入口都必须拿到数字 profileId 才能调用。按下列顺序处理，不要跳过：

1. 先调 linkfox-amazon-ads-auth 的 authorized_stores.py，拉出用户已授权的账号 × 站点清单。
2. 根据用户提到的站点匹配 countryCode：
   • 只有 1 个候选 → 静默使用对应 profileId；不要向用户播报该数字。
   • ≥ 2 个候选 → 必须用 accountName 向用户确认，禁止默认选择第一个。
   • 0 个候选 → 告知用户该站点未授权，引导使用 linkfox-amazon-ads-auth 完成授权。
3. 严禁要求用户直接提供 profileId 数字。
4. 严禁在账号有歧义时自行选择默认账号。

完整决策表见 linkfox-amazon-ads-auth SKILL.md 的多账号场景说明。

调用方式

• API 端点：POST /amazonAds/developerProxy（脚本内部按顺序调用三个 Ads v1 路径；完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/<脚本名>.py '<JSON 参数>' [--inline] [--no-cache]（可用脚本见下文）
• 成本约束：本工具不消耗算力；同一会话、同一报告类型和同一参数组合默认只调用一次，成功结果缓存 24 小时。失败、未完成或空报告不得自动换日期、切换账号或连续试探。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-ads-sp-insights-report-<timestamp>.json（<cwd> 为脚本执行时的工作目录；<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错）
• 报告 CSV 分片写入同一会话的 data/；最终响应不暴露 Amazon 预签名 URL
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要
• 加 --inline 强制全量打印到 stdout（同样落盘）；加 --no-cache 强制重新获取

读数据建议：先看摘要和 preview；响应 JSON 用 jq / ConvertFrom-Json 按需抽取，完整报告行从 dataFiles[].path 指向的文件用 CSV 工具或 Import-Csv 读取，避免整份报告进入上下文。

解决认证和算力问题

发生以下情况时，按 references/onboarding.md 引导解决：

异常情况

• 未配置 API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY
• 响应 401 或 402 状态码
• 响应提示算力、余额、套餐或额度不足

Core Concepts

• 覆盖范围：只覆盖 Sponsored Products Audience 和 Search Term Impression Share/Rank 两类 Reporting API v1 beta 报告
• 一站式：自动完成 advertiser account 映射 → 创建报告 → 等待生成 → 下载全部 CSV/gzip 分片 → 返回预览与文件路径
• 双入口、共享流程：两个公开入口分别固定报告类型，共用 reporting_v1_workflow.py；不要直接执行共享模块
• 固定字段：Agent 不选择 fields、groupBy 或自由过滤条件；脚本按对应 reference 构造 Amazon 官方兼容字段组合
• 账号标识分工：profileId 用于后端选择当前用户授权；advertiserAccountId 默认由脚本查询并映射
• v1 与 v3 边界：普通曝光、点击、花费、转化类 SP 搜索词报告使用 linkfox-amazon-ads-report 的 spSearchTerm，不是本 Skill
• Beta 约束：Amazon 当前将 Reporting API v1 标为 open beta；账号开放范围、字段和限流可能变化

可用脚本

完整参数、内部调用链和响应结构见 references/api.md。选择 Audience 时读 references/sp-audience-reporting-v1.md；选择 Search Impression Share 时读 references/sp-search-impression-share-v1.md。

Agent 调用流程

Agent 收到“SP 受众”或“SP 搜索词展示份额”需求时，必须按下列顺序：

1. 定报告类型：Audience 使用 get_sp_audience_report.py；展示份额/排名使用 get_sp_search_impression_share.py。一次只调用一个入口。
2. 查 reference：读取对应报告 reference，确认字段含义、限制和展示重点。
3. 解析账号：通过 Ads Auth Skill 按站点得到唯一 profileId 和 region；多候选时先向用户确认账号。
4. 确认日期与粒度：创建模式必须有 startDate / endDate。未指定 timeUnit 时使用 DAILY；Audience 未指定 detailLevel 时使用 ACCOUNT。
5. 告知等待时间并调用：说明 Amazon 通常需要约 2–10 分钟，然后运行选定入口。脚本会自动映射账号、创建、轮询和下载，不要手工拆成三次业务调用。
6. 处理结果：success=true 时展示报告类型、日期、总行数、预览和全部文件路径；totalRows=0 是合法空报告。
7. 处理未完成：status=STILL_PROCESSING 不是失败。先向用户确认是否继续，再使用 resumeHint.params 和 --no-cache 轮询同一 reportId，禁止创建重复报告。

默认条件（用户未指定时使用）

请求示例

1. SP Audience 报告

python scripts/get_sp_audience_report.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY", "detailLevel": "ACCOUNT"
}'

2. SP Search Term Impression Share/Rank 报告

python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY"
}'

3. 轮询已有 reportId（救回上次未完成报告）

根据原报告类型继续使用原入口；仅传 profileId、region、reportId 和轮询参数：

python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "reportId": "REPORT_ID",
  "pollInterval": 60, "maxAttempts": 20
}' --no-cache

响应格式

成功：

{
  "success": true,
  "status": "COMPLETED",
  "reportId": "report-id",
  "reportKind": "audience",
  "totalRows": 42,
  "dataFiles": [{"part": 1, "path": "C:/.../part-01.csv", "rowCount": 42}],
  "preview": [{"audienceSegment.name": "In-market ..."}],
  "pollAttempts": 2,
  "elapsedSeconds": 60.2
}

• 失败：success=false，并包含 error、脱敏后的 details 和 _cacheable=false。
• 未完成：status=STILL_PROCESSING，并包含原 reportId、resumeHint.mode=poll-only、resumeHint.params 和 _cacheable=false。

调用原则

• 用户明确指定报告类型时只调用该类型，不擅自替换或同时生成另一份报告
• Search Impression Share 不得追加 campaign、adGroup、target、keyword、groupBy 或自定义 fields
• 参数中不得出现 access token、refresh token、LWA 密钥或自定义 Amazon 请求头；脚本会在联网前递归拒绝
• 报告失败时如实展示 Amazon 错误，不盲目换参数重建
• 报告仍在生成时复用同一 reportId；禁止因为等待较久创建重复报告
• 成功后展示 CSV 文件路径和必要预览，不展示完整 Token、内部授权记录或 Amazon 预签名 URL
• 客观呈现报告数据；除非用户要求，不主动扩展成商业决策建议