amazon-ads-report.md

# 亚马逊广告报告（Amazon Ads Reporting）

本说明供 **linkfoxagent** 编排使用，内容与仓库内独立 skill **`linkfox-amazon-ads-report`** 保持一致。通过脚本完成 **Sponsored Products (SP) / Sponsored Brands (SB)** 全量报告类型的创建、轮询、下载与解压；**Sponsored Display (SD) / Sponsored Television (ST) / Amazon DSP 暂未覆盖**。

当前 LinkFoxAgent 内置 `@` 工具列表（以网关 `listEnabledTool` 为准）中**无**单独的「Amazon Ads 报告」工具名时，任务侧通过 **独立 skill 脚本** 调用。本 skill 内已同步 **`references/amazon-ads-report-types/`**（与 `linkfox-amazon-ads-report/references/report-types/` 同构；上游变更时请两边对齐）。脚本与 `api.md` 仍在独立 skill 目录。

## 何时使用

- 用户要下载 **Amazon Ads 报表**、**SP/SB 广告活动 / 关键词 / 搜索词 / 投放商品 / 购买商品 / 广告组 / GrossAndInvalids / Prompt 扩展** 等任意已支持的 `reportTypeId`。
- 需要 **曝光、点击、花费、归因销售、ACOS、ROAS** 等指标；若仅需活动名、关键词列表等**元数据**而无报表指标，可配合独立 skill **`linkfox-amazon-ads-entity`**。

## 依赖

- **`linkfox-amazon-ads-auth`**：授权、`profileId`、`region`、令牌刷新。脚本启动会检查该 skill 是否已安装（缺失时 exit 42，`DEPENDENCY_MISSING`）。
- 下游实体清单见 **`linkfox-amazon-ads-entity`**；报表指标始终走本报告的 `get_report.py`。

## 规格唯一真相源（禁止臆造列名）

每个 `reportTypeId` 的 **adProduct、groupBy、允许的 columns / filters / timeUnit、日期跨度上限** 以本 skill 下 **`references/amazon-ads-report-types/`** 为准（入口 **`references/amazon-ads-report-types/index.md`**，子目录 **`sp/`**、**`sb/`**）。

编排前先打开对应 **`references/amazon-ads-report-types/<adProduct-dir>/<reportTypeId>.md`**：其 **YAML frontmatter** 给出 `adProduct`、`groupBy`（及推荐主维度）、`timeUnit` 枚举、`dateRange`；**Base metrics** 表列出该类型允许的**全部列名**。调用脚本时 **`adProduct` / `groupBy` / `columns` 必填且须与该文件一致**。

## profileId 与多账号（调用前必做）

用户常以自然语言描述站点（如「美国站」）。**必须先**按 `linkfox-amazon-ads-auth` 拉取已授权店铺 × 站点，解析出数字 **`profileId`**（及 **`region`**：`NA` / `EU` / `FE`）：

- 单候选 → 静默使用对应 profileId，勿向用户播报数字 ID。
- 同站点多账号 → **必须澄清**用哪一个（可用 `accountName` 展示）。
- 无候选 → 引导用户完成 `linkfox-amazon-ads-auth` 授权。
- **禁止**让用户直接报 profileId；**禁止**在歧义下默认选第一个。

完整决策表见 **`skills/linkfox-amazon-ads-auth/SKILL.md`** 中 Usage Scenarios。

## 脚本与参数概要

- **脚本**：`skills/linkfox-amazon-ads-report/scripts/get_report.py`
- **运行时细则、成功/失败 JSON、`STILL_PROCESSING`（exit 2）与 `resumeHint.params` 续跑**：见 **`skills/linkfox-amazon-ads-report/references/api.md`**

**全链路模式（默认）** 必填：`profileId`、`region`、`reportTypeId`、`adProduct`、`groupBy`、`columns`、`startDate`、`endDate`（`YYYY-MM-DD`）。

**仅轮询模式**：入参含 **`reportId`** 时跳过创建，只需 `profileId`、`region` + `reportId`（用于客户端曾超时但 Amazon 侧仍在生成的报告）。HTTP 425 duplicate 时脚本可自动解析已有 `reportId` 并续跑。

### 默认构造规则（用户未指定时）

| 条件 | 默认 |
|------|------|
| `timeUnit` | 跨度 ≤7 天 → `DAILY`；>7 天 → `SUMMARY` |
| `columns` 日期维度 | `DAILY` 含 `date`；`SUMMARY` 含 `startDate`+`endDate`；并含该报告主键字段（见对应 `.md` 与 `groupBy`） |
| `columns` 基础指标 | `impressions`、`clicks`、`cost`（以该类型 Base metrics 存在为准） |
| 归因类列 | 仅当用户意图涉及销售/转化/ROI/ACOS 等时追加 `sales7d`、`purchases7d`、`acosClicks7d`、`roasClicks7d` 等（以 Base metrics 为准） |
| `filters` | 默认不加 |
| `groupBy` | 取 frontmatter 中 `groupBy` 数组的**第一个**（官方推荐主维度） |

### 常见错误与处理（摘要）

| 现象 | 处理 |
|------|------|
| 缺 `adProduct`/`groupBy`/`columns` | 回到 **`references/amazon-ads-report-types/`** 下对应 `.md` 补齐 |
| HTTP 401 | `linkfox-amazon-ads-auth` 刷新 token 后重试 |
| 日期跨度超限 | 按该类型 `maxSpanDays` 拆段拉取再合并 |
| `columns`/`groupBy` 校验失败 | 核对 Base metrics 拼写与 reportTypeId 匹配 |
| `status=STILL_PROCESSING`（exit 2） | **非失败**；将 stdout 中 `resumeHint.params` 作为仅轮询模式续调 |
| exit 42 | 先安装 **`linkfox-amazon-ads-auth`** |

## 与 LinkFoxAgent 的协作方式

- 长耗时任务遵守本 skill **`SKILL.md`** 中的 **`sessions_spawn`**、`linkfox.py --wait` 等约定。
- 子会话执行 `get_report.py` 时，任务描述中应写清 **工作目录** 与 **脚本路径**（相对仓库根或绝对路径），避免 cwd 错误。
- 报告生成常需 **数分钟**；向用户说明等待时长与可续跑方式。

## 与 @智能数据查询

解压后的报告为 **结构化 JSON** 时，可通过 **`@Python沙箱`** 或后续本地脚本做聚合；若未来网关在 `listEnabledTool` 中启用专用工具并在返回体中暴露统一字段名，再在 **`references/sandbox.md`** 的 `@智能数据查询` 映射中追加维度/指标条目。