amazon-ads-manager

面向实时广告活动管理的 Amazon Advertising API 封装工具 — 支持读取效果报告、调整出价、暂停关键词、添加否定词等操作。

初始化配置（仅需一次）

在技能根目录（与本 SKILL.md 文件同级）创建一个 .env 文件：

AMAZON_ADS_CLIENT_ID=amzn1.application-oa2-client.xxx
AMAZON_ADS_CLIENT_SECRET=xxx
AMAZON_ADS_REFRESH_TOKEN=Atzr|xxx
AMAZON_ADS_PROFILE_ID=          # 通过 `ads.py profiles` 获取
AMAZON_ADS_REGION=NA            # NA | EU | FE

如何获取凭证：

1. 访问 Amazon Ads Developer Console → 创建应用 → 获取 client_id 和 client_secret
2. 完成 OAuth 流程 → 获取 refresh_token（使用您的 Seller Central 账户登录）
3. 运行 ads.py profiles 查找您的 AMAZON_ADS_PROFILE_ID（每个站点市场对应一个）

若尚未配置凭证：请向该技能的所有者（即安装此技能的人员）索取 Amazon Ads API 凭证，并将其保存至上方列出的 .env 文件中。缺少任一凭证，所有命令均会失败，并明确提示缺失的具体环境变量名称。

命令

列出 profile（查找您的 PROFILE_ID）

uv run /scripts/ads.py profiles

返回所有已关联广告账户的信息，包括 profileId、站点市场（marketplace）、币种（currency）。 请将 AMAZON_ADS_PROFILE_ID 设置为后续调用所需的正确 profileId。

查看广告活动（campaigns）

# 仅显示启用中的广告活动
uv run ... campaigns

# 显示全部（含已暂停）
uv run ... campaigns --state all

返回字段：campaignId、name、state、budget、bidding strategy。

查看广告组（ad groups）

uv run ... adgroups 

查看关键词（keywords）

uv run ... keywords 

返回字段：keywordId、keywordText、matchType、state、bid。

效果报告（异步执行，耗时约 30–90 秒）

# 广告活动层级 ACOS/ROAS 汇总（最近 30 天）
uv run ... report campaigns --days 30

# 关键词层级效果数据
uv run ... report keywords --days 30

# 搜索词报告（用于词源挖掘与否定词添加）
uv run ... report searchterms --days 30

# 限定至单个广告活动
uv run ... report keywords --days 30 --campaign-id 12345678

输出字段（增强版）：impressions、clicks、cost、attributedSales7d、attributedUnitsOrdered7d、acos_pct、roas、ctr_pct、cpc

结果按花费（spend）降序排列。

更新关键词出价

uv run ... set-bid  
# 示例：
uv run ... set-bid 987654321 0.85

暂停 / 启用 / 存档关键词

uv run ... set-state  paused
uv run ... set-state  enabled

添加广告活动级否定关键词

# 否定精确匹配（默认）
uv run ... add-negative  "bad search term"

# 否定短语匹配
uv run ... add-negative  "irrelevant" --match phrase

优化工作流

步骤 1 — 获取整体概览

uv run ... report campaigns --days 30

标记 acos_pct > 50% 的广告活动，作为深度分析对象。

步骤 2 — 深入分析问题广告活动

uv run ... report keywords --days 30 --campaign-id 

对每个关键词进行如下分类：

目标 ACOS 基准参考值：SP 手动 25–35% · SP 自动 35–45% · SB 40–55%

步骤 3 — 挖掘搜索词（Search Term Harvesting）

uv run ... report searchterms --days 30

针对自动广告活动（Auto Campaigns）：

• acos_pct < 目标值 AND 点击数 ≥ 5 AND 销售额 > 0 → 以当前自动出价的 80% 添加至手动广告活动的精确匹配关键词
• 花费 > $3 AND 销售额 = 0 AND 点击数 ≥ 8 → 添加为否定精确匹配词

步骤 4 — 执行变更

对识别出的每一项操作，运行对应命令（set-bid、set-state、add-negative），并提供变更摘要及预期影响说明。

输出格式

完成分析后，请按如下格式呈现结果：

## 广告优化报告

### 账户概览 (最近 N 天)
| 总花费 | 总销售额 | ACOS | ROAS | 点击数 | 平均 CPC |
|--------|---------|------|------|--------|---------|

### 🔴 高优先级 — 建议暂停 (X 个词，节省 $X/月)
| Campaign | Ad Group | Keyword | 花费 | 点击 | 销售 | 操作 |

### 🟠 降价建议 (X 个词)
| Keyword | 当前 bid | 建议 bid | 当前 ACOS | 目标 ACOS |

### 🟢 收割词 — 建议加入 Manual (X 个词)
| 搜索词 | Auto 花费 | ACOS | 建议 bid |

### 执行摘要
已执行 / 等待确认 X 项操作

除非用户明确指示“直接执行”或“just do it”，否则在执行任何出价调整或暂停操作前，必须主动请求确认。