Amazon Ads 广告管理#

Amazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作；经 developerProxy 传 profileId，由服务端解析 token（勿先 storeTokens 取 raw token）。自动处理分页、过滤字段规范化。

广告产品覆盖实体脚本子目录详细参数SP (Sponsored Products) v3campaigns / adGroups / keywords / negativeKeywords / productAds / targetsscripts/sp/references/api/sp.mdSB V3 Legacy + V4V3 campaigns/keywords/targets；V4 campaigns/adGroups/ads/keywords/targets/creativesscripts/sb/v3/、 scripts/sb/v4/references/api/sb.mdSD (Sponsored Display) v3campaigns / adGroups / productAds / targets / negativeTargets / creativesscripts/sd/references/api/sd.md

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

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

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

1. 先调 linkfox-amazon-ads-auth 的 authorized_stores.py 拉出用户已授权的账号 × 站点清单。

2. 根据用户提到的站点（映射到 countryCode，如 美国→ US）匹配候选 profile：

   • 只有 1 个候选 → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。
   • ≥ 2 个候选（同站点下多个授权账号） → 必须向用户澄清，用 accountName 问："你在美国站授权了 A 和 B 两个账号，这次用哪个？"
   • 0 个候选 → 告知用户该站点未授权，引导去 linkfox-amazon-ads-auth 做授权。

3. 严禁 让用户直接报 profileId 数字。

4. 严禁 在歧义下"挑第一个"或"选默认"绕过澄清。

完整决策表见 linkfox-amazon-ads-auth SKILL.md 的 Usage Scenarios 第 4 节。

Core Concepts#

• 自动分页： fetchAll=true（默认）跟随分页到结束或 maxPages=50 兜底；SP/SB V4/Target 用 nextToken，SB V3 GET 与 SD 用 startIndex + count
• 过滤器结构不统一：不同字段需要不同写法（详见下方"过滤器结构速查"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入
• 只给 metadata，不含指标：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 linkfox-amazon-ads-report，按 id join
• 支持 create / update：各模块下 create_*.py / update_*.py 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式
• SB V3/V4 共存：默认使用 scripts/sb/v4/；只有确认是 Legacy 或用户明确要求 V3 时使用 scripts/sb/v3/。不自动执行 V4→V3 回落；已知 Multi-Ad-Group Campaign 必须拒绝 V3
• SB 共享 Targeting：Amazon 的 Keyword/Target 仍使用 sb/keywords、 sb/targets[/list]，没有伪造的 /sb/v4/keywords；V3/V4 脚本入口隔离，但底层共享官方 targeting 资源
• SD 接口形态：Sponsored Display 是 v3 REST endpoint， GET /sd/<entity> + querystring，分页用 startIndex + count；state / id 类过滤为逗号分隔字符串； includeExtendedDataFields:true 时请求 /sd/<entity>/extended 路径。所有过滤字段统一支持 {"include":[...]} 入参

可用脚本#

SP（28 个）#

脚本业务实体操作sp/list_campaigns.py广告活动查询sp/create_campaigns.py广告活动创建sp/update_campaigns.py广告活动修改（预算/策略/状态/名称等）sp/list_ad_groups.py广告组查询sp/create_ad_groups.py广告组创建sp/update_ad_groups.py广告组修改（默认出价/状态/名称等）sp/list_keywords.py关键词查询sp/create_keywords.py关键词创建sp/update_keywords.py关键词修改（出价/状态等）sp/list_negative_keywords.py否定关键词查询sp/create_negative_keywords.py否定关键词创建sp/update_negative_keywords.py否定关键词修改（状态等）sp/list_product_ads.py商品广告查询sp/create_product_ads.py商品广告创建sp/update_product_ads.py商品广告修改（状态等）sp/list_targets.py商品定向查询sp/create_targets.py商品定向创建sp/update_targets.py商品定向修改（出价/状态等）sp/create_campaign_negative_keywords.py活动级否定关键词创建sp/update_campaign_negative_keywords.py活动级否定关键词修改（状态等）sp/create_campaign_negative_targets.py活动级否定定向创建sp/update_campaign_negative_targets.py活动级否定定向修改（状态等）sp/create_negative_targets.py广告组级否定定向创建sp/update_negative_targets.py广告组级否定定向修改（状态等）sp/list_budget_rules.py预算规则查询sp/create_budget_rules.py预算规则创建sp/update_budget_rules.py预算规则修改sp/create_budget_rules_association.py预算规则关联关联规则到活动

SB V3 Legacy（10 个）#

脚本组业务实体操作sb/v3/list/create/update_campaigns.pyLegacy 广告活动（Creative 内嵌）查询/创建/修改sb/v3/list_ad_groups.pyLegacy 广告组查询sb/v3/list/create/update_keywords.py关键词查询/创建/修改sb/v3/list/create/update_targets.py商品定向查询/创建/修改

V3 仅兼容 Legacy。若参数包含 campaignStructure:"MULTI_AD_GROUP" 或 isMultiAdGroupsEnabled:true，脚本返回 SB_V4_CAMPAIGN_NOT_SUPPORTED。脚本没有本地 Campaign 数据库，因此调用前应先用 V4 Campaign list 确认结构。

SB V4（20 个）#

脚本组业务实体操作sb/v4/list/create/update_campaigns.py广告活动查询/创建/修改sb/v4/list/create/update_ad_groups.py广告组查询/创建/修改sb/v4/list/create/update_ads.py广告查询/创建/修改sb/v4/list/create/update_keywords.py关键词（Amazon 共享 V3 transport）查询/创建/修改sb/v4/list/create/update_targets.py商品定向（Amazon 共享 V3/V3.2 transport）查询/创建/修改sb/v4/list_creatives.py、 create_creatives.py独立 Creative Version查询/创建新版本sb/v4/list/create/update_budget_rules.py预算规则查询/创建/修改

原 scripts/sb/*.py 继续作为既有 V4 操作的兼容入口（薄封装转发到 scripts/sb/v4/）；新调用统一使用带版本目录。完整规则见 references/api/sb-coexistence.md。

SD（21 个）#

脚本业务实体操作sd/list_campaigns.py广告活动查询sd/create_campaigns.py广告活动创建sd/update_campaigns.py广告活动修改（预算/状态/名称等）sd/list_ad_groups.py广告组查询sd/create_ad_groups.py广告组创建sd/update_ad_groups.py广告组修改（出价/状态等）sd/list_product_ads.py商品广告查询sd/create_product_ads.py商品广告创建sd/update_product_ads.py商品广告修改（状态等）sd/list_targets.py定向子句查询sd/create_targets.py定向子句创建sd/update_targets.py定向子句修改（出价/状态等）sd/list_negative_targets.py否定定向子句查询sd/create_negative_targets.py否定定向子句创建sd/update_negative_targets.py否定定向子句修改（状态等）sd/list_creatives.py创意素材查询sd/create_creatives.py创意素材创建sd/update_creatives.py创意素材修改（素材/状态等）sd/list_budget_rules.py预算规则查询sd/create_budget_rules.py预算规则创建sd/update_budget_rules.py预算规则修改详细过滤器、枚举值、返回字段见 references/api/sp.md / references/api/sb.md / references/api/sd.md。

调用方式#

• API 端点： POST /amazonAds/developerProxy（不同操作通过请求体区分；完整参数/响应/错误码见 references/api.md）
• Python 脚本： python scripts/<脚本名>.py '<JSON 参数>' [--inline]；SB 新调用必须显式使用 scripts/sb/v3/ 或 scripts/sb/v4/
• 成本约束：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

• 始终 将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-ads-manager-<timestamp>.json（ <cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录； <session> 取自环境变量 SESSION_ID，按用户任务自动聚合； 禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/ costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和积分问题#

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况#

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

Financial Safety Guidance#

创建和更新操作可能直接影响广告花费，立即生效且无法撤回。

决策规则：

用户状态Agent 行为已授权（说过"自动调价"/"按你判断来"/"不用问我"/"确认"等）直接执行 → 输出操作回执未授权（首次交互、未明确表态）先输出确认摘要 → 等用户确认后执行

确认摘要模板（未授权时，执行前输出）：

text

📋 即将执行：
- 操作：[创建/修改] [N 个] [实体类型]
- 变更：[关键字段变化，如 bid $1.0→$1.5 / budget $50→$100]
- 影响：[花费变化预估，引用日预算作为上限]
确认执行？后续如需自动处理，告诉我即可。

操作回执模板（每次写操作执行后必须输出）：

text

✅ 已执行：[简短描述]
- 范围：[实体数量、名称或 ID]
- 变化：[具体变更内容]
- 结果：[成功 N 个 / 失败 M 个]

共用参数（SP + SB + SD 均适用）#

字段类型说明profileIdnumber必填，从 ads-auth 获取regionstring必填， NA / EU / FE``fetchAllbool默认 true；SP/SB V4/Target 用 nextToken，SB V3 GET 与 SD 用 startIndex + count``maxResultsint1-100，默认 100；对应 Sponsored Display 端 count``includeExtendedDataFieldsbool返回扩展字段（部分实体）；SD 通过路径切换为 /sd/<entity>/extended 实现localestring本地化（SP keywords 支持）

过滤器结构速查（最易错）#

结构示例适用字段Object{"include":[...]} / {"exclude":[...]}全部 id/状态类：campaignIdFilter、adGroupIdFilter、keywordIdFilter、stateFilter、portfolioIdFilter、expressionTypeFilter、adIdFilterArray["EXACT","BROAD"]matchTypeFilter（SP keywords/negativeKeywords）Scalar"AUTO"campaignTargetingTypeFilter（SP adGroups）Text{"queryTermMatchType":"BROAD_MATCH","include":["..."]}nameFilter、keywordTextFilterClient任意形式，本 skill 本地过滤asinFilter、skuFilter（SP productAds）

易错点：

• SP matchTypeFilter 是 裸数组 ["EXACT"]（传错本 skill 自动规范化）
• expressionTypeFilter 反而是 Object（与 matchType 不同）
• asinFilter / skuFilter 客户端过滤，建议同时传 campaignIdFilter / adGroupIdFilter 收窄

响应格式#

json

{
  "success": true,
  "apiVersion": "V3 | V4",
  "amazonResourceVersion": "V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED",
  "<entityKey>": [ /* 实体数组，字段原样 */ ],
  "total": 157,
  "pagesFetched": 2,
  "truncated": false
}

SB 的 apiVersion 表示调用入口/结构意图， amazonResourceVersion 表示实际 Amazon 资源版本；两者不同不代表发生自动回落。SP productAds 客户端过滤时额外带： serverTotalBeforeClientFilter + clientSideFilters。

使用示例#

1. 列活跃 SP 广告活动#

bash

python scripts/sp/list_campaigns.py '{"profileId":1234567890,"region":"NA",
  "stateFilter":{"include":["ENABLED"]}}'

2. 看某 SP campaign 下的广告组#

bash

python scripts/sp/list_ad_groups.py '{"profileId":1234567890,"region":"NA",
  "campaignIdFilter":{"include":["998877665544"]}}'

3. 按 ASIN 反查 SP 投放（客户端过滤）#

bash

python scripts/sp/list_product_ads.py '{"profileId":1234567890,"region":"NA",
  "asinFilter":{"include":["B01ABCDEFG"]},
  "campaignIdFilter":{"include":["998877665544"]}}'

4. 列 SB V4 广告活动（默认）#

bash

python scripts/sb/v4/list_campaigns.py '{"profileId":1234567890,"region":"NA",
  "stateFilter":{"include":["ENABLED"]}}'

5. 列某 SB V4 campaign 下的 adGroups / ads#

bash

python scripts/sb/v4/list_ad_groups.py '{"profileId":1234567890,"region":"NA",
  "campaignIdFilter":{"include":["1122334455"]}}'

python scripts/sb/v4/list_ads.py '{"profileId":1234567890,"region":"NA",
  "adGroupIdFilter":{"include":["5566778899"]}}'

6. 管理 SB V4 campaign 的关键词（共享 targeting 路径）#

bash

python scripts/sb/v4/list_keywords.py '{"profileId":1234567890,"region":"NA",
  "campaignIdFilter":["1122334455"],"adGroupIdFilter":["5566778899"]}'

7. 查询已确认的 V3 Legacy campaign#

bash

python scripts/sb/v3/list_campaigns.py '{"profileId":1234567890,"region":"NA",
  "campaignStructure":"LEGACY","stateFilter":["enabled","paused"]}'

8. 列活跃 SD 广告活动#

bash

python scripts/sd/list_campaigns.py '{"profileId":1234567890,"region":"NA",
  "stateFilter":{"include":["ENABLED"]}}'

9. 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）#

bash

python scripts/sd/list_product_ads.py '{"profileId":1234567890,"region":"NA",
  "asinFilter":{"include":["B01ABCDEFG"]},
  "campaignIdFilter":{"include":["998877665544"]}}'

10. 与 report 配合分析指标#

本 skill 返回实体 元数据（id、名称、状态、匹配类型等）；指标（曝光、点击、花费、转化）交给 linkfox-amazon-ads-report（ reportTypeId: "spTargeting" / "sbCampaigns" / "sdCampaigns" 等），按 id join。

调用原则#

• 返回字段原样保留；不改名、不翻译、不补算派生指标
• 非 2xx 不自动重试；保留 httpStatus + body 告知用户
• truncated=true 时明确提示数据未取完

常见错误#

状态含义建议HTTP 401accessToken 过期调 ads-auth 的 refresh_token.py 后重试HTTP 403profileId 无权限核对 profileId 归属HTTP 400入参结构错先核对"过滤器结构速查"表HTTP 429限流等 2-5s 重试exit 42依赖 skill 未安装先装 linkfox-amazon-ads-auth

Not Applicable#

• 删除 / 归档 → 本 skill 不支持 DELETE（可通过 update state 为 ARCHIVED 实现归档，但归档不可逆）
• SB 不支持把 V4 Multi-Ad-Group Campaign 降级成 V3；V3 独立 Creative CRUD 不存在，Legacy Creative 通过 Campaign payload 管理
• SB negativeKeywords / negativeTargets / themes / recommendations 与 Legacy→V4 Migration 暂不在本次 A+B+C 范围
• SD 的按 id 单查 / brandSafety / recommendations / forecasts / optimizationRules / locations 等"非基础实体"接口 → 不在本 skill
• DSP / ST 实体 → 不在本 skill
• 指标报表 → linkfox-amazon-ads-report
• 授权 / token / profile → linkfox-amazon-ads-auth

积分消耗规则#

不消耗积分。

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

1. The functionality or purpose described in this skill does not match actual behavior
2. The skill's results do not match the user's intent
3. The user expresses dissatisfaction or praise about this skill
4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

---

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.