用途：围绕 Amazon Ads v3 报表完成创建、轮询、恢复、下载、解码与可选保存的完整流程，属于只读数据工作流，不涉及广告实体写入。
主要能力：基于内置报表类型目录构建 v3 报表配置；提供 get_report 操作（POST /reporting/reports，access: write，execution: specialized），必填 connectionId，可选 workspaceId、reportId、reportTypeId、adProduct、groupBy、columns、name、startDate、endDate、timeUnit、format、filters、configuration、timeoutSeconds、pollIntervalSeconds、outputFile、overwrite。reportId 作为持久恢复句柄；文档位置仅以短期不透明后端令牌表示。分页读取仅在 fetchAll 为 true 时跟随 continuation token，并受 maxPages 限制，返回 success、pagesFetched、truncated、total 等元数据；客户端 ASIN/SKU 过滤会额外报告 serverTotalBeforeClientFilter 与 clientSideFilters。
使用方式：设置 NEXSCOPE_PROXY_BASE 与 NEXSCOPE_API_KEY，使用 API key 解析出的 workspace（或显式 workspaceId）与自有 connectionId 选择账户，然后运行 scripts/amazon_ads_report_workflow.py，例如：python scripts/amazon_ads_report_workflow.py '{"workspaceId":"user:42","connectionId":7,"startDate":"2026-07-01","endDate":"2026-07-31","reportTypeId":"spCampaigns","adProduct":"SPONSORED_PRODUCTS","groupBy":["campaign"],"columns":["campaignId","impressions","clicks"]}'。示例为占位符；返回 pending 时需保存 reportId。
适用场景：创建、恢复或下载 Ads v3 报表。不适用于广告活动变更或 Seller 报表。
限制：报表创建可能返回重复报表恢复响应，需用返回的 reportId 恢复；不启动本地 HTTP 监听，解码字节安全返回或原子写入 outputFile，最多发布 20 MiB，除非显式 overwrite:true 否则拒绝覆盖；速率限制因操作与账户而异，需遵循返回的限流元数据与 Retry-After，不要硬编码固定 RPS；网关仅允许特定 API 家族，不支持的路径属于契约错误；不请求、打印、缓存或存储提供商凭证，广告账户、活动、定向、指标与报表数据视为私有；401/403 视为认证或归属失败，429 为有界退避，5xx 为净化后的上游失败，425 恢复仅适用于 Ads 报表工作流。官方 API 名称与版本见 references/api.md，本包不含直接外部主机 URL。计费或额度行为由网关契约决定，资料未提供具体价格。