{"id":"a2adab44-fb8f-4695-ab2a-0d36e5f59389","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-amazon-ads-manager","name":"亚马逊-广告管理","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-amazon-ads-manager","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-amazon-ads-manager","generatedAt":"2026-10-11T00:32:19.637Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:14:04.387Z","emptyReason":null},"description":"亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-ads-manager","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"亚马逊-广告管理 technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:14:04.387Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:14:04.387Z","emptyReason":null},"stars":null,"forks":null,"downloads":1245,"packageName":null,"latestVersion":"1.1.0","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:14:04.315Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T22:14:04.387Z","lastCrawledAt":"2026-10-10T22:14:04.315Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T22:14:04.315Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.0","createdAt":"2026-08-18T11:36:47.211Z","changelog":"Update from 1.0.5 to 1.1.0","fileCount":106,"zipByteSize":125512},{"version":"1.1.1","createdAt":"2026-08-14T14:42:18.897Z","changelog":"Update from 1.0.5 to 1.1.1","fileCount":106,"zipByteSize":126316},{"version":"1.0.5","createdAt":"2026-08-07T10:38:44.236Z","changelog":"Update from 1.0.4 to 1.0.5","fileCount":72,"zipByteSize":110736},{"version":"1.0.4","createdAt":"2026-07-13T12:01:59.042Z","changelog":"Update from 1.0.3 to 1.0.4","fileCount":70,"zipByteSize":101801},{"version":"1.0.3","createdAt":"2026-07-06T11:09:33.272Z","changelog":"Update from 1.0.2 to 1.0.3","fileCount":70,"zipByteSize":101130},{"version":"1.0.2","createdAt":"2026-07-03T08:09:01.124Z","changelog":"Update from 1.0.1 to 1.0.2","fileCount":70,"zipByteSize":101258},{"version":"1.0.1","createdAt":"2026-07-03T04:33:47.920Z","changelog":"Update from 1.0.0 to 1.0.1","fileCount":69,"zipByteSize":99730},{"version":"1.0.0","createdAt":"2026-06-08T08:24:07.281Z","changelog":"Initial release","fileCount":71,"zipByteSize":102107}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-ads-manager","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-ads-manager` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/linkfox-ai/linkfox-amazon-ads-manager before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T00:32:19.630Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-ads-manager/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:14:04.387Z","emptyReason":null},"readme":"Skill: 亚马逊-广告管理\n\nOwner: linkfox-ai\n\nSummary: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。\n\nTags: latest:1.1.1\n\nVersion history:\n\nv1.1.0 | 2026-08-18T11:36:47.211Z | user\n\nUpdate from 1.0.5 to 1.1.0\n\nv1.1.1 | 2026-08-14T14:42:18.897Z | user\n\nUpdate from 1.0.5 to 1.1.1\n\nv1.0.5 | 2026-08-07T10:38:44.236Z | user\n\nUpdate from 1.0.4 to 1.0.5\n\nv1.0.4 | 2026-07-13T12:01:59.042Z | user\n\nUpdate from 1.0.3 to 1.0.4\n\nv1.0.3 | 2026-07-06T11:09:33.272Z | user\n\nUpdate from 1.0.2 to 1.0.3\n\nv1.0.2 | 2026-07-03T08:09:01.124Z | user\n\nUpdate from 1.0.1 to 1.0.2\n\nv1.0.1 | 2026-07-03T04:33:47.920Z | user\n\nUpdate from 1.0.0 to 1.0.1\n\nv1.0.0 | 2026-06-08T08:24:07.281Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.1.0: 106 files, 125512 bytes\n\nFiles: references/api.md (3633b), references/api/sb-coexistence.md (2994b), references/api/sb-v3.md (3368b), references/api/sb-v4.md (3079b), references/api/sb.md (1142b), references/api/sd.md (7696b), references/api/sp.md (5274b), references/onboarding.md (2046b), scripts/_common.py (30335b), scripts/check_auth_dependency.py (6567b), scripts/onboarding.py (24089b), scripts/sb/_sb_common.py (16293b), scripts/sb/create_ad_groups.py (250b), scripts/sb/create_ads.py (238b), scripts/sb/create_budget_rules.py (256b), scripts/sb/create_campaigns.py (250b), scripts/sb/list_ad_groups.py (246b), scripts/sb/list_ads.py (234b), scripts/sb/list_budget_rules.py (252b), scripts/sb/list_campaigns.py (246b), scripts/sb/update_ad_groups.py (250b), scripts/sb/update_ads.py (238b), scripts/sb/update_budget_rules.py (256b), scripts/sb/update_campaigns.py (250b), scripts/sb/v3/create_campaigns.py (574b), scripts/sb/v3/create_keywords.py (596b), scripts/sb/v3/create_targets.py (596b), scripts/sb/v3/list_ad_groups.py (670b), scripts/sb/v3/list_campaigns.py (674b), scripts/sb/v3/list_keywords.py (742b), scripts/sb/v3/list_targets.py (691b), scripts/sb/v3/update_campaigns.py (573b), scripts/sb/v3/update_keywords.py (595b), scripts/sb/v3/update_targets.py (595b), scripts/sb/v4/create_ad_groups.py (459b), scripts/sb/v4/create_ads.py (1082b), scripts/sb/v4/create_budget_rules.py (467b), scripts/sb/v4/create_campaigns.py (461b), scripts/sb/v4/create_creatives.py (1202b), scripts/sb/v4/create_keywords.py (596b), scripts/sb/v4/create_targets.py (596b), scripts/sb/v4/list_ad_groups.py (766b), scripts/sb/v4/list_ads.py (750b), scripts/sb/v4/list_budget_rules.py (449b), scripts/sb/v4/list_campaigns.py (770b), scripts/sb/v4/list_creatives.py (597b), scripts/sb/v4/list_keywords.py (843b), scripts/sb/v4/list_targets.py (684b), scripts/sb/v4/update_ad_groups.py (457b), scripts/sb/v4/update_ads.py (447b), scripts/sb/v4/update_budget_rules.py (466b), scripts/sb/v4/update_campaigns.py (459b), scripts/sb/v4/update_keywords.py (595b), scripts/sb/v4/update_targets.py (595b), scripts/sd/create_ad_groups.py (1696b), scripts/sd/create_budget_rules.py (1734b), scripts/sd/create_campaigns.py (1698b), scripts/sd/create_creatives.py (1742b), scripts/sd/create_negative_targets.py (1731b), scripts/sd/create_product_ads.py (1706b), scripts/sd/create_targets.py (1688b), scripts/sd/list_ad_groups.py (3091b), scripts/sd/list_budget_rules.py (2766b), scripts/sd/list_campaigns.py (3476b), scripts/sd/list_creatives.py (3280b), scripts/sd/list_negative_targets.py (3368b), scripts/sd/list_product_ads.py (5026b), scripts/sd/list_targets.py (3460b), scripts/sd/update_ad_groups.py (1710b), scripts/sd/update_budget_rules.py (1747b), scripts/sd/update_campaigns.py (1713b), scripts/sd/update_creatives.py (1715b), scripts/sd/update_negative_targets.py (1744b), scripts/sd/update_product_ads.py (1715b), scripts/sd/update_targets.py (1707b), scripts/sp/create_ad_groups.py (1725b), scripts/sp/create_budget_rules_association.py (1828b), scripts/sp/create_budget_rules.py (1800b), scripts/sp/create_campaign_negative_keywords.py (1840b), scripts/sp/create_campaign_negative_targets.py (1851b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: linkfox-amazon-ads-manager\ndescription: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。\n---\n\n# Amazon Ads 广告管理\n\nAmazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作；经 `developerProxy` 传 `profileId`，由服务端解析 token（勿先 `storeTokens` 取 raw token）。自动处理分页、过滤字段规范化。\n\n| 广告产品 | 覆盖实体 | 脚本子目录 | 详细参数 |\n|---------|---------|-----------|---------|\n| **SP** (Sponsored Products) v3 | campaigns / adGroups / keywords / negativeKeywords / productAds / targets | `scripts/sp/` | [references/api/sp.md](./references/api/sp.md) |\n| **SB** V3 Legacy + V4 | V3 campaigns/keywords/targets；V4 campaigns/adGroups/ads/keywords/targets/creatives | `scripts/sb/v3/`、`scripts/sb/v4/` | [references/api/sb.md](./references/api/sb.md) |\n| **SD** (Sponsored Display) v3 | campaigns / adGroups / productAds / targets / negativeTargets / creatives | `scripts/sd/` | [references/api/sd.md](./references/api/sd.md) |\n\n**依赖 `linkfox-amazon-ads-auth`**（脚本启动时自动检查；未安装时 exit 42，stderr 打 `DEPENDENCY_MISSING`）。\n\n### ⚠️ 多账号场景：调用前必须解析好 profileId\n\n用户经常只说自然语言（\"美国站\"、\"日本站\"、\"我的店铺\"），本 skill 的所有脚本都必须拿到数字 `profileId` 才能调。按下列顺序处理，**不要跳过**：\n\n1. 先调 `linkfox-amazon-ads-auth` 的 `authorized_stores.py` 拉出用户已授权的账号 × 站点清单。\n2. 根据用户提到的站点（映射到 `countryCode`，如 美国→`US`）匹配候选 profile：\n - **只有 1 个候选** → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。\n - **≥ 2 个候选（同站点下多个授权账号）** → **必须向用户澄清**，用 `accountName` 问：\"你在美国站授权了 A 和 B 两个账号，这次用哪个？\"\n - **0 个候选** → 告知用户该站点未授权，引导去 `linkfox-amazon-ads-auth` 做授权。\n3. **严禁**让用户直接报 profileId 数字。\n4. **严禁**在歧义下\"挑第一个\"或\"选默认\"绕过澄清。\n\n完整决策表见 `linkfox-amazon-ads-auth` SKILL.md 的 **Usage Scenarios 第 4 节**。\n\n## Core Concepts\n\n- **自动分页**：`fetchAll=true`（默认）跟随分页到结束或 `maxPages=50` 兜底；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count`\n- **过滤器结构不统一**：不同字段需要不同写法（详见下方\"过滤器结构速查\"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入\n- **只给 metadata，不含指标**：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 `linkfox-amazon-ads-report`，按 id join\n- **支持 create / update**：各模块下 `create_*.py` / `update_*.py` 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式\n- **SB V3/V4 共存**：默认使用 `scripts/sb/v4/`；只有确认是 Legacy 或用户明确要求 V3 时使用 `scripts/sb/v3/`。不自动执行 V4→V3 回落；已知 Multi-Ad-Group Campaign 必须拒绝 V3\n- **SB 共享 Targeting**：Amazon 的 Keyword/Target 仍使用 `sb/keywords`、`sb/targets[/list]`，没有伪造的 `/sb/v4/keywords`；V3/V4 脚本入口隔离，但底层共享官方 targeting 资源\n- **SD 接口形态**：Sponsored Display 是 v3 REST endpoint，`GET /sd/` + querystring，分页用 `startIndex + count`；state / id 类过滤为逗号分隔字符串；`includeExtendedDataFields:true` 时请求 `/sd//extended` 路径。所有过滤字段统一支持 `{\"include\":[...]}` 入参\n\n## 可用脚本\n\n### SP（28 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sp/list_campaigns.py` | 广告活动 | 查询 |\n| `sp/create_campaigns.py` | 广告活动 | 创建 |\n| `sp/update_campaigns.py` | 广告活动 | 修改（预算/策略/状态/名称等） |\n| `sp/list_ad_groups.py` | 广告组 | 查询 |\n| `sp/create_ad_groups.py` | 广告组 | 创建 |\n| `sp/update_ad_groups.py` | 广告组 | 修改（默认出价/状态/名称等） |\n| `sp/list_keywords.py` | 关键词 | 查询 |\n| `sp/create_keywords.py` | 关键词 | 创建 |\n| `sp/update_keywords.py` | 关键词 | 修改（出价/状态等） |\n| `sp/list_negative_keywords.py` | 否定关键词 | 查询 |\n| `sp/create_negative_keywords.py` | 否定关键词 | 创建 |\n| `sp/update_negative_keywords.py` | 否定关键词 | 修改（状态等） |\n| `sp/list_product_ads.py` | 商品广告 | 查询 |\n| `sp/create_product_ads.py` | 商品广告 | 创建 |\n| `sp/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sp/list_targets.py` | 商品定向 | 查询 |\n| `sp/create_targets.py` | 商品定向 | 创建 |\n| `sp/update_targets.py` | 商品定向 | 修改（出价/状态等） |\n| `sp/create_campaign_negative_keywords.py` | 活动级否定关键词 | 创建 |\n| `sp/update_campaign_negative_keywords.py` | 活动级否定关键词 | 修改（状态等） |\n| `sp/create_campaign_negative_targets.py` | 活动级否定定向 | 创建 |\n| `sp/update_campaign_negative_targets.py` | 活动级否定定向 | 修改（状态等） |\n| `sp/create_negative_targets.py` | 广告组级否定定向 | 创建 |\n| `sp/update_negative_targets.py` | 广告组级否定定向 | 修改（状态等） |\n| `sp/list_budget_rules.py` | 预算规则 | 查询 |\n| `sp/create_budget_rules.py` | 预算规则 | 创建 |\n| `sp/update_budget_rules.py` | 预算规则 | 修改 |\n| `sp/create_budget_rules_association.py` | 预算规则关联 | 关联规则到活动 |\n\n### SB V3 Legacy（10 个）\n| 脚本组 | 业务实体 | 操作 |\n|------|---------|------|\n| `sb/v3/list/create/update_campaigns.py` | Legacy 广告活动（Creative 内嵌） | 查询/创建/修改 |\n| `sb/v3/list_ad_groups.py` | Legacy 广告组 | 查询 |\n| `sb/v3/list/create/update_keywords.py` | 关键词 | 查询/创建/修改 |\n| `sb/v3/list/create/update_targets.py` | 商品定向 | 查询/创建/修改 |\n\nV3 仅兼容 Legacy。若参数包含 `campaignStructure:\"MULTI_AD_GROUP\"` 或 `isMultiAdGroupsEnabled:true`，脚本返回 `SB_V4_CAMPAIGN_NOT_SUPPORTED`。脚本没有本地 Campaign 数据库，因此调用前应先用 V4 Campaign list 确认结构。\n\n### SB V4（20 个）\n| 脚本组 | 业务实体 | 操作 |\n|------|---------|------|\n| `sb/v4/list/create/update_campaigns.py` | 广告活动 | 查询/创建/修改 |\n| `sb/v4/list/create/update_ad_groups.py` | 广告组 | 查询/创建/修改 |\n| `sb/v4/list/create/update_ads.py` | 广告 | 查询/创建/修改 |\n| `sb/v4/list/create/update_keywords.py` | 关键词（Amazon 共享 V3 transport） | 查询/创建/修改 |\n| `sb/v4/list/create/update_targets.py` | 商品定向（Amazon 共享 V3/V3.2 transport） | 查询/创建/修改 |\n| `sb/v4/list_creatives.py`、`create_creatives.py` | 独立 Creative Version | 查询/创建新版本 |\n| `sb/v4/list/create/update_budget_rules.py` | 预算规则 | 查询/创建/修改 |\n\n原 `scripts/sb/*.py` 继续作为既有 V4 操作的兼容入口（薄封装转发到 `scripts/sb/v4/`）；新调用统一使用带版本目录。完整规则见 [references/api/sb-coexistence.md](./references/api/sb-coexistence.md)。\n\n### SD（21 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sd/list_campaigns.py` | 广告活动 | 查询 |\n| `sd/create_campaigns.py` | 广告活动 | 创建 |\n| `sd/update_campaigns.py` | 广告活动 | 修改（预算/状态/名称等） |\n| `sd/list_ad_groups.py` | 广告组 | 查询 |\n| `sd/create_ad_groups.py` | 广告组 | 创建 |\n| `sd/update_ad_groups.py` | 广告组 | 修改（出价/状态等） |\n| `sd/list_product_ads.py` | 商品广告 | 查询 |\n| `sd/create_product_ads.py` | 商品广告 | 创建 |\n| `sd/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sd/list_targets.py` | 定向子句 | 查询 |\n| `sd/create_targets.py` | 定向子句 | 创建 |\n| `sd/update_targets.py` | 定向子句 | 修改（出价/状态等） |\n| `sd/list_negative_targets.py` | 否定定向子句 | 查询 |\n| `sd/create_negative_targets.py` | 否定定向子句 | 创建 |\n| `sd/update_negative_targets.py` | 否定定向子句 | 修改（状态等） |\n| `sd/list_creatives.py` | 创意素材 | 查询 |\n| `sd/create_creatives.py` | 创意素材 | 创建 |\n| `sd/update_creatives.py` | 创意素材 | 修改（素材/状态等） |\n| `sd/list_budget_rules.py` | 预算规则 | 查询 |\n| `sd/create_budget_rules.py` | 预算规则 | 创建 |\n| `sd/update_budget_rules.py` | 预算规则 | 修改 |\n详细过滤器、枚举值、返回字段见 [references/api/sp.md](./references/api/sp.md) / [references/api/sb.md](./references/api/sb.md) / [references/api/sd.md](./references/api/sd.md)。\n\n## 调用方式\n\n- **API 端点**：`POST /amazonAds/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`；SB 新调用必须显式使用 `scripts/sb/v3/` 或 `scripts/sb/v4/`\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-ads-manager-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## Financial Safety Guidance\n\n创建和更新操作可能直接影响广告花费，立即生效且无法撤回。\n\n**决策规则：**\n\n| 用户状态 | Agent 行为 |\n|----------|-----------|\n| 已授权（说过\"自动调价\"/\"按你判断来\"/\"不用问我\"/\"确认\"等） | 直接执行 → 输出操作回执 |\n| 未授权（首次交互、未明确表态） | 先输出确认摘要 → 等用户确认后执行 |\n\n**确认摘要模板**（未授权时，执行前输出）：\n```\n📋 即将执行：\n- 操作：[创建/修改] [N 个] [实体类型]\n- 变更：[关键字段变化，如 bid $1.0→$1.5 / budget $50→$100]\n- 影响：[花费变化预估，引用日预算作为上限]\n确认执行？后续如需自动处理，告诉我即可。\n```\n\n**操作回执模板**（每次写操作执行后必须输出）：\n```\n✅ 已执行：[简短描述]\n- 范围：[实体数量、名称或 ID]\n- 变化：[具体变更内容]\n- 结果：[成功 N 个 / 失败 M 个]\n```\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `profileId` | number | 必填，从 ads-auth 获取 |\n| `region` | string | 必填，`NA` / `EU` / `FE` |\n| `fetchAll` | bool | 默认 `true`；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count` |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count` |\n| `includeExtendedDataFields` | bool | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 本地化（SP keywords 支持） |\n\n## 过滤器结构速查（最易错）\n\n| 结构 | 示例 | 适用字段 |\n|------|------|----------|\n| **Object** | `{\"include\":[...]}` / `{\"exclude\":[...]}` | 全部 id/状态类：campaignIdFilter、adGroupIdFilter、keywordIdFilter、stateFilter、portfolioIdFilter、expressionTypeFilter、adIdFilter |\n| **Array** | `[\"EXACT\",\"BROAD\"]` | matchTypeFilter（SP keywords/negativeKeywords） |\n| **Scalar** | `\"AUTO\"` | campaignTargetingTypeFilter（SP adGroups） |\n| **Text** | `{\"queryTermMatchType\":\"BROAD_MATCH\",\"include\":[\"...\"]}` | nameFilter、keywordTextFilter |\n| **Client** | 任意形式，本 skill 本地过滤 | asinFilter、skuFilter（SP productAds） |\n\n**易错点**：\n- SP `matchTypeFilter` 是**裸数组** `[\"EXACT\"]`（传错本 skill 自动规范化）\n- `expressionTypeFilter` 反而是 **Object**（与 matchType 不同）\n- `asinFilter` / `skuFilter` 客户端过滤，建议同时传 `campaignIdFilter` / `adGroupIdFilter` 收窄\n\n## 响应格式\n\n```json\n{\n \"success\": true,\n \"apiVersion\": \"V3 | V4\",\n \"amazonResourceVersion\": \"V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED\",\n \"\": [ /* 实体数组，字段原样 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\nSB 的 `apiVersion` 表示调用入口/结构意图，`amazonResourceVersion` 表示实际 Amazon 资源版本；两者不同不代表发生自动回落。SP productAds 客户端过滤时额外带：`serverTotalBeforeClientFilter` + `clientSideFilters`。\n\n## 使用示例\n\n### 1. 列活跃 SP 广告活动\n```bash\npython scripts/sp/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 2. 看某 SP campaign 下的广告组\n```bash\npython scripts/sp/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 3. 按 ASIN 反查 SP 投放（客户端过滤）\n```bash\npython scripts/sp/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 4. 列 SB V4 广告活动（默认）\n```bash\npython scripts/sb/v4/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 5. 列某 SB V4 campaign 下的 adGroups / ads\n```bash\npython scripts/sb/v4/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\npython scripts/sb/v4/list_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n### 6. 管理 SB V4 campaign 的关键词（共享 targeting 路径）\n```bash\npython scripts/sb/v4/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":[\"1122334455\"],\"adGroupIdFilter\":[\"5566778899\"]}'\n```\n\n### 7. 查询已确认的 V3 Legacy campaign\n```bash\npython scripts/sb/v3/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignStructure\":\"LEGACY\",\"stateFilter\":[\"enabled\",\"paused\"]}'\n```\n\n### 8. 列活跃 SD 广告活动\n```bash\npython scripts/sd/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 9. 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\n```bash\npython scripts/sd/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 10. 与 report 配合分析指标\n本 skill 返回实体**元数据**（id、名称、状态、匹配类型等）；指标（曝光、点击、花费、转化）交给 `linkfox-amazon-ads-report`（`reportTypeId: \"spTargeting\"` / `\"sbCampaigns\"` / `\"sdCampaigns\"` 等），按 id join。\n\n## 调用原则\n\n- 返回字段原样保留；不改名、不翻译、不补算派生指标\n- 非 2xx 不自动重试；保留 `httpStatus` + `body` 告知用户\n- `truncated=true` 时明确提示数据未取完\n\n## 常见错误\n\n| 状态 | 含义 | 建议 |\n|------|------|------|\n| `HTTP 401` | accessToken 过期 | 调 ads-auth 的 `refresh_token.py` 后重试 |\n| `HTTP 403` | profileId 无权限 | 核对 profileId 归属 |\n| `HTTP 400` | 入参结构错 | 先核对\"过滤器结构速查\"表 |\n| `HTTP 429` | 限流 | 等 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n## Not Applicable\n\n- 删除 / 归档 → 本 skill 不支持 DELETE（可通过 update state 为 ARCHIVED 实现归档，但归档不可逆）\n- SB 不支持把 V4 Multi-Ad-Group Campaign 降级成 V3；V3 独立 Creative CRUD 不存在，Legacy Creative 通过 Campaign payload 管理\n- SB negativeKeywords / negativeTargets / themes / recommendations 与 Legacy→V4 Migration 暂不在本次 A+B+C 范围\n- SD 的按 id 单查 / brandSafety / recommendations / forecasts / optimizationRules / locations 等\"非基础实体\"接口 → 不在本 skill\n- DSP / ST 实体 → 不在本 skill\n- 指标报表 → `linkfox-amazon-ads-report`\n- 授权 / token / profile → `linkfox-amazon-ads-auth`\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback:**\n\nAuto-detect and report feedback via the Feedback API when any of the following apply:\n1. The functionality or purpose described in this skill does not match actual behavior\n2. The skill's results do not match the user's intent\n3. The user expresses dissatisfaction or praise about this skill\n4. Anything you believe could be improved\n\nCall the feedback API as specified in `references/api.md`. Do not interrupt the user's flow.\n\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-ads-manager\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1787053007211\n}\n\nFile v1.1.0:references/api.md\n\n# linkfox-amazon-ads-manager — 参数与字段参考（总览）\n\n按 Amazon Ads 广告产品分类维护。\n\n| 广告产品 | 脚本子目录 | 查询参考 |\n|---------|-----------|---------|\n| **Sponsored Products (SP)** — v3 | `scripts/sp/` | [api/sp.md](./api/sp.md) |\n| **Sponsored Brands (SB)** — V3 Legacy + V4 | `scripts/sb/v3/`、`scripts/sb/v4/` | [api/sb.md](./api/sb.md) |\n| **Sponsored Display (SD)** — v3 | `scripts/sd/` | [api/sd.md](./api/sd.md) |\n\n> Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n\n## 通用约定\n\n- 每个脚本接受一个 JSON 字符串作为唯一位置参数\n- 鉴权：环境变量 `LINKFOX_AGENT_API_KEY`（或旧名 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- API 网关地址：环境变量 `LINKFOX_TOOL_GATEWAY`（默认 `https://tool-gateway.linkfox.com`）\n- 依赖 `linkfox-amazon-ads-auth`（脚本启动自动检查；缺失时 exit 42，stderr 打 `DEPENDENCY_MISSING`）\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| `profileId` | number | ✅ | — | 从 ads-auth 获取 |\n| `region` | string | ✅ | — | `NA` / `EU` / `FE` |\n| `fetchAll` | boolean | 否 | `true` | 自动翻页；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count` |\n| `maxResults` | integer | 否 | `100` | 单页 1-100；超限上游可能静默 clamp；对应 SD 端 `count` |\n| `skipDepCheck` | boolean | 否 | `false` | 跳过依赖检查 |\n| `includeExtendedDataFields` | boolean | 否 | — | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 否 | — | 本地化（keywords 支持） |\n\n## 输出格式\n\n```json\n{\n \"success\": true,\n \"apiVersion\": \"V3 | V4\",\n \"amazonResourceVersion\": \"V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED\",\n \"\": [ /* 实体数组 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\n客户端过滤时（SP productAds 的 asinFilter/skuFilter）额外带 `serverTotalBeforeClientFilter` + `clientSideFilters`。\n\nSB 输出中的两个版本字段含义不同：`apiVersion` 表示调用入口和 Campaign 结构意图；`amazonResourceVersion` 表示实际 Amazon 资源传输版本。V4 Keyword/Target 入口使用 Amazon 共享 V3/V3.2 targeting 路径，不代表自动回落。\n\n失败：\n```json\n{\n \"error\": \"Upstream HTTP 401\",\n \"httpStatus\": 401,\n \"body\": \"...\",\n \"pagesFetched\": 0\n}\n```\n\n## 通用错误码\n\n| httpStatus / exit | 含义 | 建议 |\n|-------------------|------|------|\n| 200 | 成功 | — |\n| 400 | 入参结构错 | 核对对应 adProduct 的过滤器结构（api/sp.md / api/sb.md / api/sd.md） |\n| 401 | accessToken 过期 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 402 | 积分或余额不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 403 | profileId 无权限 | 核对 profileId 归属 |\n| 429 | 限流 | 间隔 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n---\n\n## Feedback API\n\n与上面的工具 API **base URL 不同**：\n\n```bash\ncurl -X POST https://skill-api.linkfox.com/api/v1/public/feedback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"skillName\":\"linkfox-amazon-ads-manager\",\"sentiment\":\"POSITIVE\",\n \"category\":\"OTHER\",\"content\":\"实体查询结果与预期一致\"}'\n```\n\n- `sentiment`: `POSITIVE` / `NEUTRAL` / `NEGATIVE`\n- `category`: `BUG` / `COMPLAINT` / `SUGGESTION` / `OTHER`\n\nFile v1.1.0:references/api/sb-coexistence.md\n\n# Sponsored Brands V3 / V4 共存与路由\n\n## 版本边界\n\n| 调用入口 | 适用结构 | 用途 |\n|---|---|---|\n| `scripts/sb/v4/` | `LEGACY` 或 `MULTI_AD_GROUP` | 默认入口；新建活动、多广告组、Ad/Creative 管理 |\n| `scripts/sb/v3/` | 仅 `LEGACY` | 历史活动兼容 |\n| `scripts/sb/*.py` | 同 V4 | 旧路径兼容；新调用应迁到 `scripts/sb/v4/` |\n\n新业务默认使用 V4。只有用户明确要求 V3，或已确认 Campaign 为 Legacy 时，才使用 V3。\n\n## 不自动回落\n\n脚本不执行 `V4 失败 → V3 重试`。Amazon 返回非 2xx 时，保留状态码和响应体交给调用方判断。原因：\n\n1. API 版本不等于 Campaign 结构；\n2. Multi-Ad-Group Campaign 无法无损转换成 V3；\n3. 自动回落会掩盖权限、参数或资源状态错误；\n4. V3 读取 V4 活动可能造成多 Ad Group 数据截断。\n\n当顶层参数或 `payload` 内出现 `campaignStructure=MULTI_AD_GROUP` / `isMultiAdGroupsEnabled=true`（含 `\"true\"`/`1` 等写法）时，V3 脚本会在发请求前返回：\n\n```json\n{\n \"code\": \"SB_V4_CAMPAIGN_NOT_SUPPORTED\",\n \"message\": \"This campaign uses the Sponsored Brands V4 multi-ad-group structure. Use scripts/sb/v4 instead of V3.\"\n}\n```\n\n脚本没有本地 Campaign 数据库；如果调用方未提供结构信息，无法仅凭 `campaignId` 可靠判断结构。因此 Agent 应先用 V4 `list_campaigns.py` 查询 `isMultiAdGroupsEnabled`，再决定是否允许使用 V3。\n\n## Amazon 路径与脚本版本不是一回事\n\nAmazon 的 Campaign / Ad Group / Ad 主资源有明确 V4 路径：\n\n```text\nsb/v4/campaigns/**\nsb/v4/adGroups/**\nsb/v4/ads/**\n```\n\n但 Keyword 与 Product Target 仍使用共享资源路径：\n\n```text\nsb/keywords\nsb/targets\nsb/targets/list\n```\n\n这些共享路径可以通过 `campaignId + adGroupId` 管理多广告组活动。为让调用意图明确，本 skill 在 `sb/v3/` 和 `sb/v4/` 都提供 keyword/target 入口；两者底层调用同一 Amazon 资源：\n\n- `sb/v3/*`：声明调用方已确认是 Legacy；\n- `sb/v4/*`：声明按 V4 Campaign/Ad Group 结构管理；\n- 输出中的 `amazonResourceVersion` 会标记为 `V3_SHARED_TARGETING` 或 `V3.2_SHARED_TARGETING`。\n\n这不是 V4 自动降级，也不会在失败后切换版本。\n\n## Creative 边界\n\n- V3 Legacy Campaign 的 Creative 是 Campaign payload 的组成部分，没有独立的 V3 Creative CRUD 脚本。\n- V4 使用 Ad 与独立 Creative Version：\n - `sb/v4/list_ads.py`\n - `sb/v4/create_ads.py`\n - `sb/v4/list_creatives.py`\n - `sb/v4/create_creatives.py`\n\n不要伪造不存在的 `sb/v3/creatives` 或 `sb/v4/keywords` Amazon 路径。\n\n## 决策流程\n\n```text\n新建 / 多 Ad Group / Ad / Creative\n → scripts/sb/v4/\n\n关键词或 Target\n → 默认 scripts/sb/v4/\n → 仅在已确认 Legacy 或用户明确要求 V3 时使用 scripts/sb/v3/\n\nV3 + MULTI_AD_GROUP\n → 拒绝并提示使用 V4\n\n任一版本调用失败\n → 返回原错误；不自动重试另一版本\n```\n\nFile v1.1.0:references/api/sb-v3.md\n\n# Sponsored Brands V3 Legacy API\n\nV3 仅用于历史 Legacy Campaign。共存与路由规则见 [sb-coexistence.md](./sb-coexistence.md)。\n\n## 脚本\n\n| 脚本 | Amazon 路径 | 方法 | 说明 |\n|---|---|---|---|\n| `sb/v3/list_campaigns.py` | `sb/campaigns` | GET | offset 分页查询 Legacy 活动 |\n| `sb/v3/create_campaigns.py` | `sb/campaigns` | POST | 创建 Legacy 活动；新业务不推荐 |\n| `sb/v3/update_campaigns.py` | `sb/campaigns` | PUT | 更新 Legacy 活动 |\n| `sb/v3/list_ad_groups.py` | `sb/adGroups` | GET | 查询 Legacy 活动关联的 Ad Group |\n| `sb/v3/list_keywords.py` | `sb/keywords` | GET | 查询关键词 |\n| `sb/v3/create_keywords.py` | `sb/keywords` | POST | 创建关键词，最多 100 个 |\n| `sb/v3/update_keywords.py` | `sb/keywords` | PUT | 更新关键词，最多 100 个 |\n| `sb/v3/list_targets.py` | `sb/targets/list` | POST | nextToken 分页查询商品定向 |\n| `sb/v3/create_targets.py` | `sb/targets` | POST | 创建商品定向，最多 100 个 |\n| `sb/v3/update_targets.py` | `sb/targets` | PUT | 更新商品定向 |\n\nV3 Creative 没有独立 CRUD；品牌名、标题、ASIN、素材等位于 Campaign 的 `creative` 字段中，通过 Campaign create/update 管理。\n\n## Legacy 安全参数\n\nV3 脚本额外接受：\n\n| 参数 | 作用 |\n|---|---|\n| `campaignStructure` | 传 `MULTI_AD_GROUP` 时拒绝调用 |\n| `isMultiAdGroupsEnabled` | 传 `true` 时拒绝调用 |\n\n这些字段只用于本地保护，不会发送给 Amazon。\n\n## GET list 参数\n\nCampaign：\n\n- `campaignIdFilter`\n- `stateFilter`\n- `nameFilter`\n- `portfolioIdFilter`\n- `creativeType`\n\nAd Group：\n\n- `adGroupIdFilter`\n- `campaignIdFilter`\n- `stateFilter`\n- `nameFilter`\n- `creativeType`\n\nKeyword：\n\n- `keywordIdFilter`\n- `adGroupIdFilter`\n- `campaignIdFilter`\n- `stateFilter`\n- `matchTypeFilter`\n- `keywordText`\n- `creativeType`\n- `locale`\n\nID、状态、匹配类型可传字符串、数组或 `{\"include\":[...]}`，脚本转换成 Amazon 所需的逗号分隔 query。分页参数为 `maxResults`、`fetchAll`、`maxPages`。\n\n## Target list 参数\n\nTarget list 接受 Amazon 原生 `filters`，也接受顶层 Object/Array 过滤（脚本会映射为 Amazon `filters[]`）：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"campaignIdFilter\": {\"include\": [\"1122334455\"]},\n \"stateFilter\": [\"enabled\", \"paused\"],\n \"maxResults\": 100\n}\n```\n\n等价原生写法：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"payload\": {\n \"maxResults\": 100,\n \"filters\": [\n {\"filterType\": \"CAMPAIGN_ID\", \"values\": [\"1122334455\"]},\n {\"filterType\": \"TARGETING_STATE\", \"values\": [\"enabled\", \"paused\"]}\n ]\n }\n}\n```\n\n可映射字段：`campaignIdFilter`→`CAMPAIGN_ID`，`adGroupIdFilter`→`AD_GROUP_ID`，`stateFilter`→`TARGETING_STATE`，`targetIdFilter`→`TARGET_ID`，`creativeTypeFilter`→`CREATIVE_TYPE`。\n\n## 示例\n\n```bash\npython scripts/sb/v3/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\"stateFilter\":[\"enabled\",\"paused\"]}'\n\npython scripts/sb/v3/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":[\"1122334455\"]}'\n\npython scripts/sb/v3/update_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignStructure\":\"LEGACY\",\"payload\":[{\"keywordId\":1,\"campaignId\":2,\"adGroupId\":3,\"bid\":1.2}]}'\n```\n\n写操作不会自动切换到 V4；非 2xx 原样返回。\n\nFile v1.1.0:references/api/sb-v4.md\n\n# Sponsored Brands V4 API\n\nV4 是默认版本，支持 Legacy 与 Multi-Ad-Group Campaign。共存规则见 [sb-coexistence.md](./sb-coexistence.md)。\n\n## 脚本\n\n| 资源 | 脚本 | Amazon 路径 |\n|---|---|---|\n| Campaign | `list/create/update_campaigns.py` | `sb/v4/campaigns[/list]` |\n| Ad Group | `list/create/update_ad_groups.py` | `sb/v4/adGroups[/list]` |\n| Ad | `list/create/update_ads.py` | `sb/v4/ads[/list]`、`sb/v4/ads/{adType}` |\n| Keyword | `list/create/update_keywords.py` | `sb/keywords`（共享 V3 transport） |\n| Target | `list/create/update_targets.py` | `sb/targets[/list]`（共享 V3/V3.2 transport） |\n| Creative Version | `list_creatives.py`、`create_creatives.py` | `sb/ads/creatives/...` |\n| Budget Rule | `list/create/update_budget_rules.py` | `sb/budgetRules` |\n\n所有路径都位于 `scripts/sb/v4/`。旧的 `scripts/sb/*.py` 保留为 V4 兼容入口，新调用不要继续依赖旧路径。\n\n## Campaign / Ad Group / Ad list\n\n使用 V4 Object/Text filter：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"campaignIdFilter\": {\"include\": [\"1122334455\"]},\n \"stateFilter\": {\"include\": [\"ENABLED\", \"PAUSED\"]},\n \"maxResults\": 100\n}\n```\n\n响应包含 `nextToken`，Campaign/Ad Group/Ad 原始响应还可能包含 `totalCount`；skill 自动聚合为 `total`。\n\n## Keyword / Target\n\nAmazon 没有 `/sb/v4/keywords` 或 `/sb/v4/targets` 路径。V4 脚本通过 `campaignId + adGroupId` 调用共享 targeting 资源：\n\n```bash\npython scripts/sb/v4/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":[\"1122334455\"],\"adGroupIdFilter\":[\"5566778899\"]}'\n\npython scripts/sb/v4/list_targets.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":{\"include\":[\"1122334455\"]},\"stateFilter\":[\"enabled\"]}'\n\npython scripts/sb/v4/create_targets.py '{\"profileId\":1234567890,\"region\":\"NA\",\"payload\":{\"targets\":[{\"campaignId\":1122334455,\"adGroupId\":5566778899,\"expressions\":[{\"type\":\"asinSameAs\",\"value\":\"B0EXAMPLE\"}],\"bid\":1.25}]}}'\n```\n\n`list_targets.py` 会把顶层 `campaignIdFilter` / `adGroupIdFilter` / `stateFilter` 等映射为 Amazon `filters[]`，避免按 keywords 习惯传参时静默全量拉取。这属于 Amazon 官方共享资源，并非 V4 失败后回退到 V3。\n\n## Ad 与 Creative\n\n创建 Ad 时必须传 `adType`：\n\n```text\nautoCollection\nmanualCollection\nbrandVideo\nvideo\nproductCollection\nproductCollectionExtended\nstoreSpotlight\n```\n\n创建新的 Creative Version 时，使用 `create_creatives.py`，传：\n\n```text\nproductCollection\nproductCollectionExtended\nstoreSpotlight\nvideo\nbrandVideo\n```\n\n示例：\n\n```bash\npython scripts/sb/v4/create_creatives.py '{\"profileId\":1234567890,\"region\":\"NA\",\"creativeType\":\"productCollection\",\"payload\":{\"adId\":\"998877\",\"creative\":{\"asins\":[\"B0EXAMPLE\"],\"headline\":\"Example\"}}}'\n```\n\n## 选择规则\n\n- 新建活动、多 Ad Group、Ad、独立 Creative：V4。\n- 未说明版本的关键词/定向管理：默认 V4 入口。\n- 只有确认是 Legacy 或用户明确要求 V3 时，改用 `scripts/sb/v3/`。\n- 调用失败时不自动转 V3。\n\nFile v1.1.0:references/api/sb.md\n\n# Sponsored Brands（SB）API 索引\n\n本 skill 同时提供 V3 Legacy 兼容入口和 V4 主入口：\n\n- [V3 Legacy 参数与脚本](./sb-v3.md)\n- [V4 参数与脚本](./sb-v4.md)\n- [V3/V4 共存、路由和禁止自动回落规则](./sb-coexistence.md)\n\n## 能力摘要\n\n| 入口 | Campaign | Ad Group | Ad | Keyword | Target | Creative Version |\n|---|---:|---:|---:|---:|---:|---:|\n| `scripts/sb/v3/` | ✅ Legacy | 查询 | — | ✅ | ✅ | Campaign payload 内嵌 |\n| `scripts/sb/v4/` | ✅ | ✅ | ✅ | ✅（共享路径） | ✅（共享路径） | ✅ |\n\n## 默认选择\n\n1. 新业务、新建 Campaign、多 Ad Group、Ad 和 Creative 使用 V4。\n2. Keyword / Target 未指定版本时也使用 V4 入口；底层是 Amazon 共享 targeting 路径。\n3. 只有已确认 Campaign 为 Legacy，或用户明确要求 V3 时，才调用 V3。\n4. 不执行 V4 → V3 自动回落。\n5. V3 不允许管理已知的 Multi-Ad-Group Campaign。\n\n## 兼容路径\n\n原 `scripts/sb/*.py` 保留，仍指向既有 V4 Campaign/AdGroup/Ad/BudgetRule 实现。新调用统一使用带版本的路径，避免后续新增能力时产生歧义。\n\nFile v1.1.0:references/api/sd.md\n\n# Sponsored Display (SD) 实体查询 — 参数与字段参考\n\n覆盖 SD v3 的 6 个 list 端点的查询参数与字段定义。通用约定、共用参数、错误码见 `../api.md`；写操作（create/update）通过 `scripts/sd/create_*.py` 与 `scripts/sd/update_*.py` 调用，payload 透传 Amazon 原生格式。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sd/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sd/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sd/list_product_ads.py` | 商品广告 | `productAds` |\n| `sd/list_targets.py` | 定向子句（商品/受众） | `targetingClauses` |\n| `sd/list_negative_targets.py` | 否定定向子句 | `negativeTargetingClauses` |\n| `sd/list_creatives.py` | 创意素材 | `creatives` |\n\n> **注意**：Sponsored Display **没有 keywords**（仅商品 / 受众 / 品类定向）。按 id 单查、创建、删除、归档，以及 brandSafety / forecasts / budgetRules / optimizationRules / locations 等\"非基础实体查询\"接口本技能不覆盖。\n\n## SD 接口形态\n\n| 维度 | Sponsored Display v3 |\n|------|----------------------|\n| HTTP 方法 | `GET` |\n| 参数位置 | querystring |\n| 分页方式 | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 逗号分隔小写串，如 `enabled,paused,archived` |\n| id 类过滤实参 | 逗号分隔字符串，如 `\"123,456\"` |\n| 扩展字段 | 通过路径区分：基础 `/sd/`，扩展 `/sd//extended` |\n| Content-Type | `application/json` |\n\n所有过滤字段对外统一接受 `{\"include\":[...]}`、裸数组、单值字符串三种宽容形态；脚本会将其序列化为 Sponsored Display 端所需的 querystring 参数。\n\n## 过滤器结构\n\n### Object —— `{\"include\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` / `targetIdFilter` / `portfolioIdFilter` / `creativeIdFilter` / `stateFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\":{\"include\": [\"1122334455\", \"6677889900\"]}}\n```\n\n兼容写法（自动归一）：\n- 裸数组 `[\"ENABLED\"]` → `{\"include\":[\"ENABLED\"]}`\n- 裸字符串 `\"ENABLED\"` → `{\"include\":[\"ENABLED\"]}`\n\n### Text —— `nameFilter`\n\nSponsored Display **仅支持精确匹配**，没有 `BROAD_MATCH`：\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\":\"EXACT_MATCH\",\"include\":[\"holiday\"]}}\n```\n\n传 `BROAD_MATCH` 时脚本会在 stderr 输出一次提示，并按 `include[0]` 作 `name` 精确匹配。\n\n### Client-side filter —— `asinFilter` / `skuFilter`（仅 productAds）\n\nSponsored Display 的 `/sd/productAds` 接口不支持按 ASIN / SKU 过滤；脚本会先按其他过滤条件拉取 productAds，再在本地按精确值匹配。建议同时传 `campaignIdFilter` 或 `adGroupIdFilter` 收窄上游拉取范围，否则 stderr 会输出性能提示。\n\n```json\n{\"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}\n```\n\n## 其他入参\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `fetchAll` | bool | 默认 `true`，关闭后只拉第一页 |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count`（每页大小） |\n| `includeExtendedDataFields` | bool | 默认 `false`；`true` 时请求 `/sd//extended` 路径；**`creatives` 没有 extended 路径，此入参无效** |\n| `skipDepCheck` | bool | 跳过 ads-auth 依赖检查 |\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED`（脚本提交上游时自动转为 `enabled` / `paused` / `archived`） | 全部 6 个实体 |\n| `expressionType` | `auto` / `manual` | targets |\n| `creativeType` | （Sponsored Display 各 creative 类型，由上游返回原值） | creatives |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_negative_targets.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_creatives.py` | `creativeIdFilter`、`adGroupIdFilter`（互斥，同时传时上游会按 400 / 422 返回） |\n\n## 常见实体字段\n\n| 实体 | 字段（节选；extended 路径返回更多） |\n|------|---------|\n| campaigns | `campaignId` / `name` / `state` / `tactic`（`T00020` / `T00030`）/ `costType`（`cpc` / `vcpm`）/ `budget` / `budgetType` / `startDate` / `endDate` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` / `bidOptimization` / `creativeType` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `state` / `asin` / `sku` / `landingPageURL` / `landingPageType` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expressionType`（auto / manual）/ `expression`（type ∈ `asinSameAs` / `asinCategorySameAs` / `audience` / `views` / `purchases` ...） / `bid` |\n| negativeTargetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression`（与 targets 类似，type 仅限 `asinSameAs` / `asinBrandSameAs`） |\n| creatives | `creativeId` / `adGroupId` / `name` / `creativeType` / `properties`（headline / brandLogoAssetID / video 等，按 creativeType 不同） / `moderationStatus` |\n\n## 调用示例\n\n```bash\n# 列活跃 SD campaigns\npython sd/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 SD adGroups（含扩展字段，请求 /sd/adGroups/extended）\npython sd/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"includeExtendedDataFields\":true}'\n\n# 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\npython sd/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# 列某 adGroup 下的定向子句\npython sd/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的否定定向\npython sd/list_negative_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的创意\npython sd/list_creatives.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n## 与 SP / SB 的差异速查\n\n供从 Sponsored Products / Sponsored Brands 迁移到 Sponsored Display 的开发者对照查阅。\n\n| 维度 | SP v3 | SB v4 | SD v3 |\n|------|-------|-------|-------|\n| 路径前缀 | `sp/` | `sb/v4/` | `sd/`（+ `/extended` 子路径） |\n| HTTP 方法 | POST list | POST list | GET |\n| Content-Type | `application/json` | `application/json` | `application/json` |\n| 实体数量 | 6 个 list | 3 个 list | 6 个 list（含 creatives；不含 keywords） |\n| 分页 | `nextToken` | `nextToken` + `totalCount` | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 大写 ENUM | 大写 ENUM | 接口端要求小写串，脚本会自动转换 |\n| 扩展字段 | `includeExtendedDataFields:true` 标志 | `includeExtendedDataFields:true` 标志 | 路径切换 `/sd//extended` |\n| Client-side filter | `asinFilter` / `skuFilter`（productAds） | 暂无 | `asinFilter` / `skuFilter`（productAds） |\n\nFile v1.1.0:references/api/sp.md\n\n# Sponsored Products (SP) 实体查询 — 参数与字段参考\n\n覆盖 6 个 SP v3 list 端点。通用约定、共用参数、错误码见 `../api.md`。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sp/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sp/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sp/list_keywords.py` | 关键词 | `keywords` |\n| `sp/list_negative_keywords.py` | 否定关键词 | `negativeKeywords` |\n| `sp/list_product_ads.py` | 商品广告 | `productAds` |\n| `sp/list_targets.py` | 商品定向 | `targetingClauses`（不是 `targets`）|\n\n## 过滤器结构（5 类）\n\n### 1. Object —— `{\"include\":[...]}` / `{\"exclude\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `keywordIdFilter` / `targetIdFilter` / `adIdFilter` / `negativeKeywordIdFilter` / `portfolioIdFilter` / `stateFilter` / `expressionTypeFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\": {\"include\": [\"1122334455\"]}}\n{\"expressionTypeFilter\": {\"include\": [\"AUTO\"]}}\n```\n\n### 2. Array —— 裸数组 `[\"EXACT\",\"BROAD\"]`\n\n适用：`matchTypeFilter`（keywords / negativeKeywords）\n\n```json\n{\"matchTypeFilter\": [\"EXACT\",\"PHRASE\"]}\n```\n\n兼容：传 `{\"include\":[\"EXACT\"]}` 本 skill 自动解包。\n\n### 3. Scalar —— 裸字符串 `\"AUTO\"`\n\n适用：`campaignTargetingTypeFilter`（adGroups）\n\n```json\n{\"campaignTargetingTypeFilter\": \"AUTO\"}\n```\n\n### 4. Text —— `{\"queryTermMatchType\":\"...\",\"include\":[...]}`\n\n适用：`nameFilter`（campaigns / adGroups）、`keywordTextFilter`（keywords / negativeKeywords）\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\": \"BROAD_MATCH\", \"include\": [\"holiday\"]}}\n```\n\n`queryTermMatchType`: `BROAD_MATCH` / `EXACT_MATCH`。\n\n### 5. Client —— 本 skill 在本地过滤\n\n适用：`asinFilter` / `skuFilter`（productAds）\n\n```json\n{\"asinFilter\": {\"include\": [\"B01ABCDEFG\"]}}\n{\"asinFilter\": [\"B01ABCDEFG\"]}\n{\"asinFilter\": \"B01ABCDEFG\"}\n```\n\nAmazon 原生 list 接口对这两个字段不生效，本 skill 拉取后本地精确匹配。建议同时传 `campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` 收窄拉取量；否则触发全量拉取 + stderr 性能提示。\n\n输出会多出：`serverTotalBeforeClientFilter` / `clientSideFilters`。\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED` | 全部 6 个实体 |\n| `matchType` | `BROAD` / `PHRASE` / `EXACT` | keywords |\n| `matchType` | `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` | negativeKeywords |\n| `expressionType` | `AUTO` / `MANUAL` | targets |\n| `campaignTargetingType` | `AUTO` / `MANUAL` | adGroups |\n| `queryTermMatchType` | `BROAD_MATCH` / `EXACT_MATCH` | nameFilter / keywordTextFilter |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter`、`campaignTargetingTypeFilter` |\n| `list_keywords.py` | `keywordIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`matchTypeFilter`、`keywordTextFilter` |\n| `list_negative_keywords.py` | `negativeKeywordIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`matchTypeFilter`、`keywordTextFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`expressionTypeFilter` |\n\n## 常见实体字段\n\n| 实体 | 字段 |\n|------|------|\n| campaigns | `campaignId` / `name` / `state` / `targetingType` / `budget.{budget,budgetType}` / `startDate` / `endDate` / `dynamicBidding.strategy` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` |\n| keywords | `keywordId` / `adGroupId` / `campaignId` / `keywordText` / `matchType` / `state` / `bid` |\n| negativeKeywords | 同 keywords，`matchType` ∈ `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `asin` / `sku` / `state` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression` / `expressionType` / `bid` |\n\n## 调用示例\n\n```bash\n# 列活跃 campaigns\npython sp/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 AUTO 广告组\npython sp/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"campaignTargetingTypeFilter\":\"AUTO\"}'\n\n# EXACT 关键词\npython sp/list_keywords.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]},\n \"matchTypeFilter\":[\"EXACT\"]}'\n\n# 按 ASIN 反查（client-side，带 campaign 收窄）\npython sp/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# AUTO 定向目标\npython sp/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]},\n \"expressionTypeFilter\":{\"include\":[\"AUTO\"]}}'\n```\n\nFile v1.1.0:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n - `python scripts/onboarding.py send-code ` → 展示 JSON 里的 phone/agreements\n - 收到验证码后：`python scripts/onboarding.py login `（workbuddy 宿主加 `--channel workbuddy`）\n - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"\"`\n - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"\"' >> ~/.zshrc && source ~/.zshrc`\n - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"\"' >> ~/.bashrc && source ~/.bashrc`\n - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order ` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query `，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.1.0:skill-card.md\n\n## Description:\n\n亚马逊-广告管理 helps agents query, create, and update Amazon Ads Sponsored Products, Sponsored Brands, and Sponsored Display entities, including campaigns, ad groups, keywords, targets, product ads, creatives, budget rules, bids, budgets, and states.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal Amazon Ads operators and agents use this skill to manage Sponsored Products, Sponsored Brands, and Sponsored Display advertising through LinkFox-authorized profiles. It supports listing entities and making create or update changes that can affect bids, budgets, status, and campaign structure.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Create and update actions can directly change Amazon Ads spend through bids, budgets, status, and campaign structure.\n\nMitigation: Require a clear confirmation summary before first write actions and avoid broad standing approval for budget or bid changes.\n\nRisk: The skill stores full business responses locally and may expose sensitive campaign, account, or advertising data in the workspace.\n\nMitigation: Use the skill only in trusted workspaces and delete local linkfox output files when they are no longer needed.\n\nRisk: The skill depends on LinkFox authentication and billing flows, and printed API keys or authorization data should be treated as secrets.\n\nMitigation: Keep API keys out of shared logs and rotate or revoke credentials if they are exposed.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager)\n- [Amazon Ads manager overview](artifact/SKILL.md)\n- [API parameter and field reference](artifact/references/api.md)\n- [Sponsored Products reference](artifact/references/api/sp.md)\n- [Sponsored Brands reference](artifact/references/api/sb.md)\n- [Sponsored Brands V3/V4 coexistence](artifact/references/api/sb-coexistence.md)\n- [Sponsored Display reference](artifact/references/api/sd.md)\n- [Authentication and billing onboarding](artifact/references/onboarding.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell command examples and JSON API payloads or responses]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Scripts write full responses to local linkfox output files and may print full or summarized JSON depending on response size.]\n\n## Skill Version(s):\n\n1.1.0 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.1: 106 files, 126316 bytes\n\nFiles: references/api.md (3633b), references/api/sb-coexistence.md (2994b), references/api/sb-v3.md (3368b), references/api/sb-v4.md (3079b), references/api/sb.md (1142b), references/api/sd.md (7740b), references/api/sp.md (5274b), references/onboarding.md (2046b), scripts/_common.py (30335b), scripts/check_auth_dependency.py (6567b), scripts/onboarding.py (24089b), scripts/sb/_sb_common.py (16293b), scripts/sb/create_ad_groups.py (250b), scripts/sb/create_ads.py (238b), scripts/sb/create_budget_rules.py (256b), scripts/sb/create_campaigns.py (250b), scripts/sb/list_ad_groups.py (246b), scripts/sb/list_ads.py (234b), scripts/sb/list_budget_rules.py (252b), scripts/sb/list_campaigns.py (246b), scripts/sb/update_ad_groups.py (250b), scripts/sb/update_ads.py (238b), scripts/sb/update_budget_rules.py (256b), scripts/sb/update_campaigns.py (250b), scripts/sb/v3/create_campaigns.py (592b), scripts/sb/v3/create_keywords.py (596b), scripts/sb/v3/create_targets.py (596b), scripts/sb/v3/list_ad_groups.py (670b), scripts/sb/v3/list_campaigns.py (674b), scripts/sb/v3/list_keywords.py (742b), scripts/sb/v3/list_targets.py (714b), scripts/sb/v3/update_campaigns.py (591b), scripts/sb/v3/update_keywords.py (595b), scripts/sb/v3/update_targets.py (595b), scripts/sb/v4/create_ad_groups.py (484b), scripts/sb/v4/create_ads.py (1102b), scripts/sb/v4/create_budget_rules.py (467b), scripts/sb/v4/create_campaigns.py (487b), scripts/sb/v4/create_creatives.py (1230b), scripts/sb/v4/create_keywords.py (596b), scripts/sb/v4/create_targets.py (596b), scripts/sb/v4/list_ad_groups.py (791b), scripts/sb/v4/list_ads.py (770b), scripts/sb/v4/list_budget_rules.py (449b), scripts/sb/v4/list_campaigns.py (796b), scripts/sb/v4/list_creatives.py (625b), scripts/sb/v4/list_keywords.py (843b), scripts/sb/v4/list_targets.py (707b), scripts/sb/v4/update_ad_groups.py (482b), scripts/sb/v4/update_ads.py (467b), scripts/sb/v4/update_budget_rules.py (466b), scripts/sb/v4/update_campaigns.py (485b), scripts/sb/v4/update_keywords.py (595b), scripts/sb/v4/update_targets.py (595b), scripts/sd/create_ad_groups.py (1696b), scripts/sd/create_budget_rules.py (1734b), scripts/sd/create_campaigns.py (1698b), scripts/sd/create_creatives.py (1742b), scripts/sd/create_negative_targets.py (1731b), scripts/sd/create_product_ads.py (1706b), scripts/sd/create_targets.py (1688b), scripts/sd/list_ad_groups.py (3091b), scripts/sd/list_budget_rules.py (2766b), scripts/sd/list_campaigns.py (3476b), scripts/sd/list_creatives.py (3280b), scripts/sd/list_negative_targets.py (3368b), scripts/sd/list_product_ads.py (5026b), scripts/sd/list_targets.py (3460b), scripts/sd/update_ad_groups.py (1710b), scripts/sd/update_budget_rules.py (1747b), scripts/sd/update_campaigns.py (1713b), scripts/sd/update_creatives.py (1715b), scripts/sd/update_negative_targets.py (1744b), scripts/sd/update_product_ads.py (1715b), scripts/sd/update_targets.py (1707b), scripts/sp/create_ad_groups.py (1726b), scripts/sp/create_budget_rules_association.py (1828b), scripts/sp/create_budget_rules.py (1800b), scripts/sp/create_campaign_negative_keywords.py (1841b), scripts/sp/create_campaign_negative_targets.py (1852b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: linkfox-amazon-ads-manager\ndescription: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。\n---\n\n# Amazon Ads 广告管理\n\nAmazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作；经 `developerProxy` 传 `profileId`，由服务端解析 token（勿先 `storeTokens` 取 raw token）。自动处理分页、过滤字段规范化。\n\n| 广告产品 | 覆盖实体 | 脚本子目录 | 详细参数 |\n|---------|---------|-----------|---------|\n| **SP** (Sponsored Products) v3 | campaigns / adGroups / keywords / negativeKeywords / productAds / targets | `scripts/sp/` | [references/api/sp.md](./references/api/sp.md) |\n| **SB** V3 Legacy + V4 | V3 campaigns/keywords/targets；V4 campaigns/adGroups/ads/keywords/targets/creatives | `scripts/sb/v3/`、`scripts/sb/v4/` | [references/api/sb.md](./references/api/sb.md) |\n| **SD** (Sponsored Display) v3 | campaigns / adGroups / productAds / targets / negativeTargets / creatives | `scripts/sd/` | [references/api/sd.md](./references/api/sd.md) |\n\n**依赖 `linkfox-amazon-ads-auth`**（脚本启动时自动检查；未安装时 exit 42，stderr 打 `DEPENDENCY_MISSING`）。\n\n### ⚠️ 多账号场景：调用前必须解析好 profileId\n\n用户经常只说自然语言（\"美国站\"、\"日本站\"、\"我的店铺\"），本 skill 的所有脚本都必须拿到数字 `profileId` 才能调。按下列顺序处理，**不要跳过**：\n\n1. 先调 `linkfox-amazon-ads-auth` 的 `authorized_stores.py` 拉出用户已授权的账号 × 站点清单。\n2. 根据用户提到的站点（映射到 `countryCode`，如 美国→`US`）匹配候选 profile：\n - **只有 1 个候选** → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。\n - **≥ 2 个候选（同站点下多个授权账号）** → **必须向用户澄清**，用 `accountName` 问：\"你在美国站授权了 A 和 B 两个账号，这次用哪个？\"\n - **0 个候选** → 告知用户该站点未授权，引导去 `linkfox-amazon-ads-auth` 做授权。\n3. **严禁**让用户直接报 profileId 数字。\n4. **严禁**在歧义下\"挑第一个\"或\"选默认\"绕过澄清。\n\n完整决策表见 `linkfox-amazon-ads-auth` SKILL.md 的 **Usage Scenarios 第 4 节**。\n\n## Core Concepts\n\n- **自动分页**：`fetchAll=true`（默认）跟随分页到结束或 `maxPages=50` 兜底；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count`\n- **过滤器结构不统一**：不同字段需要不同写法（详见下方\"过滤器结构速查\"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入\n- **只给 metadata，不含指标**：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 `linkfox-amazon-ads-report`，按 id join\n- **支持 create / update**：各模块下 `create_*.py` / `update_*.py` 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式\n- **SB V3/V4 共存**：默认使用 `scripts/sb/v4/`；只有确认是 Legacy 或用户明确要求 V3 时使用 `scripts/sb/v3/`。不自动执行 V4→V3 回落；已知 Multi-Ad-Group Campaign 必须拒绝 V3\n- **SB 共享 Targeting**：Amazon 的 Keyword/Target 仍使用 `sb/keywords`、`sb/targets[/list]`，没有伪造的 `/sb/v4/keywords`；V3/V4 脚本入口隔离，但底层共享官方 targeting 资源\n- **SD 接口形态**：Sponsored Display 是 v3 REST endpoint，`GET /sd/` + querystring，分页用 `startIndex + count`；state / id 类过滤为逗号分隔字符串；`includeExtendedDataFields:true` 时请求 `/sd//extended` 路径。所有过滤字段统一支持 `{\"include\":[...]}` 入参\n\n## 可用脚本\n\n### SP（28 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sp/list_campaigns.py` | 广告活动 | 查询 |\n| `sp/create_campaigns.py` | 广告活动 | 创建 |\n| `sp/update_campaigns.py` | 广告活动 | 修改（预算/策略/状态/名称等） |\n| `sp/list_ad_groups.py` | 广告组 | 查询 |\n| `sp/create_ad_groups.py` | 广告组 | 创建 |\n| `sp/update_ad_groups.py` | 广告组 | 修改（默认出价/状态/名称等） |\n| `sp/list_keywords.py` | 关键词 | 查询 |\n| `sp/create_keywords.py` | 关键词 | 创建 |\n| `sp/update_keywords.py` | 关键词 | 修改（出价/状态等） |\n| `sp/list_negative_keywords.py` | 否定关键词 | 查询 |\n| `sp/create_negative_keywords.py` | 否定关键词 | 创建 |\n| `sp/update_negative_keywords.py` | 否定关键词 | 修改（状态等） |\n| `sp/list_product_ads.py` | 商品广告 | 查询 |\n| `sp/create_product_ads.py` | 商品广告 | 创建 |\n| `sp/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sp/list_targets.py` | 商品定向 | 查询 |\n| `sp/create_targets.py` | 商品定向 | 创建 |\n| `sp/update_targets.py` | 商品定向 | 修改（出价/状态等） |\n| `sp/create_campaign_negative_keywords.py` | 活动级否定关键词 | 创建 |\n| `sp/update_campaign_negative_keywords.py` | 活动级否定关键词 | 修改（状态等） |\n| `sp/create_campaign_negative_targets.py` | 活动级否定定向 | 创建 |\n| `sp/update_campaign_negative_targets.py` | 活动级否定定向 | 修改（状态等） |\n| `sp/create_negative_targets.py` | 广告组级否定定向 | 创建 |\n| `sp/update_negative_targets.py` | 广告组级否定定向 | 修改（状态等） |\n| `sp/list_budget_rules.py` | 预算规则 | 查询 |\n| `sp/create_budget_rules.py` | 预算规则 | 创建 |\n| `sp/update_budget_rules.py` | 预算规则 | 修改 |\n| `sp/create_budget_rules_association.py` | 预算规则关联 | 关联规则到活动 |\n\n### SB V3 Legacy（10 个）\n| 脚本组 | 业务实体 | 操作 |\n|------|---------|------|\n| `sb/v3/list/create/update_campaigns.py` | Legacy 广告活动（Creative 内嵌） | 查询/创建/修改 |\n| `sb/v3/list_ad_groups.py` | Legacy 广告组 | 查询 |\n| `sb/v3/list/create/update_keywords.py` | 关键词 | 查询/创建/修改 |\n| `sb/v3/list/create/update_targets.py` | 商品定向 | 查询/创建/修改 |\n\nV3 仅兼容 Legacy。若参数包含 `campaignStructure:\"MULTI_AD_GROUP\"` 或 `isMultiAdGroupsEnabled:true`，脚本返回 `SB_V4_CAMPAIGN_NOT_SUPPORTED`。脚本没有本地 Campaign 数据库，因此调用前应先用 V4 Campaign list 确认结构。\n\n### SB V4（20 个）\n| 脚本组 | 业务实体 | 操作 |\n|------|---------|------|\n| `sb/v4/list/create/update_campaigns.py` | 广告活动 | 查询/创建/修改 |\n| `sb/v4/list/create/update_ad_groups.py` | 广告组 | 查询/创建/修改 |\n| `sb/v4/list/create/update_ads.py` | 广告 | 查询/创建/修改 |\n| `sb/v4/list/create/update_keywords.py` | 关键词（Amazon 共享 V3 transport） | 查询/创建/修改 |\n| `sb/v4/list/create/update_targets.py` | 商品定向（Amazon 共享 V3/V3.2 transport） | 查询/创建/修改 |\n| `sb/v4/list_creatives.py`、`create_creatives.py` | 独立 Creative Version | 查询/创建新版本 |\n| `sb/v4/list/create/update_budget_rules.py` | 预算规则 | 查询/创建/修改 |\n\n原 `scripts/sb/*.py` 继续作为既有 V4 操作的兼容入口（薄封装转发到 `scripts/sb/v4/`）；新调用统一使用带版本目录。完整规则见 [references/api/sb-coexistence.md](./references/api/sb-coexistence.md)。\n\n### SD（21 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sd/list_campaigns.py` | 广告活动 | 查询 |\n| `sd/create_campaigns.py` | 广告活动 | 创建 |\n| `sd/update_campaigns.py` | 广告活动 | 修改（预算/状态/名称等） |\n| `sd/list_ad_groups.py` | 广告组 | 查询 |\n| `sd/create_ad_groups.py` | 广告组 | 创建 |\n| `sd/update_ad_groups.py` | 广告组 | 修改（出价/状态等） |\n| `sd/list_product_ads.py` | 商品广告 | 查询 |\n| `sd/create_product_ads.py` | 商品广告 | 创建 |\n| `sd/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sd/list_targets.py` | 定向子句 | 查询 |\n| `sd/create_targets.py` | 定向子句 | 创建 |\n| `sd/update_targets.py` | 定向子句 | 修改（出价/状态等） |\n| `sd/list_negative_targets.py` | 否定定向子句 | 查询 |\n| `sd/create_negative_targets.py` | 否定定向子句 | 创建 |\n| `sd/update_negative_targets.py` | 否定定向子句 | 修改（状态等） |\n| `sd/list_creatives.py` | 创意素材 | 查询 |\n| `sd/create_creatives.py` | 创意素材 | 创建 |\n| `sd/update_creatives.py` | 创意素材 | 修改（素材/状态等） |\n| `sd/list_budget_rules.py` | 预算规则 | 查询 |\n| `sd/create_budget_rules.py` | 预算规则 | 创建 |\n| `sd/update_budget_rules.py` | 预算规则 | 修改 |\n详细过滤器、枚举值、返回字段见 [references/api/sp.md](./references/api/sp.md) / [references/api/sb.md](./references/api/sb.md) / [references/api/sd.md](./references/api/sd.md)。\n\n## 调用方式\n\n- **API 端点**：`POST /amazonAds/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`；SB 新调用必须显式使用 `scripts/sb/v3/` 或 `scripts/sb/v4/`\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-ads-manager-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## Financial Safety Guidance\n\n创建和更新操作可能直接影响广告花费，立即生效且无法撤回。\n\n**决策规则：**\n\n| 用户状态 | Agent 行为 |\n|----------|-----------|\n| 已授权（说过\"自动调价\"/\"按你判断来\"/\"不用问我\"/\"确认\"等） | 直接执行 → 输出操作回执 |\n| 未授权（首次交互、未明确表态） | 先输出确认摘要 → 等用户确认后执行 |\n\n**确认摘要模板**（未授权时，执行前输出）：\n```\n📋 即将执行：\n- 操作：[创建/修改] [N 个] [实体类型]\n- 变更：[关键字段变化，如 bid $1.0→$1.5 / budget $50→$100]\n- 影响：[花费变化预估，引用日预算作为上限]\n确认执行？后续如需自动处理，告诉我即可。\n```\n\n**操作回执模板**（每次写操作执行后必须输出）：\n```\n✅ 已执行：[简短描述]\n- 范围：[实体数量、名称或 ID]\n- 变化：[具体变更内容]\n- 结果：[成功 N 个 / 失败 M 个]\n```\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `profileId` | number | 必填，从 ads-auth 获取 |\n| `region` | string | 必填，`NA` / `EU` / `FE` |\n| `fetchAll` | bool | 默认 `true`；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count` |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count` |\n| `includeExtendedDataFields` | bool | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 本地化（SP keywords 支持） |\n\n## 过滤器结构速查（最易错）\n\n| 结构 | 示例 | 适用字段 |\n|------|------|----------|\n| **Object** | `{\"include\":[...]}` / `{\"exclude\":[...]}` | 全部 id/状态类：campaignIdFilter、adGroupIdFilter、keywordIdFilter、stateFilter、portfolioIdFilter、expressionTypeFilter、adIdFilter |\n| **Array** | `[\"EXACT\",\"BROAD\"]` | matchTypeFilter（SP keywords/negativeKeywords） |\n| **Scalar** | `\"AUTO\"` | campaignTargetingTypeFilter（SP adGroups） |\n| **Text** | `{\"queryTermMatchType\":\"BROAD_MATCH\",\"include\":[\"...\"]}` | nameFilter、keywordTextFilter |\n| **Client** | 任意形式，本 skill 本地过滤 | asinFilter、skuFilter（SP productAds） |\n\n**易错点**：\n- SP `matchTypeFilter` 是**裸数组** `[\"EXACT\"]`（传错本 skill 自动规范化）\n- `expressionTypeFilter` 反而是 **Object**（与 matchType 不同）\n- `asinFilter` / `skuFilter` 客户端过滤，建议同时传 `campaignIdFilter` / `adGroupIdFilter` 收窄\n\n## 响应格式\n\n```json\n{\n \"success\": true,\n \"apiVersion\": \"V3 | V4\",\n \"amazonResourceVersion\": \"V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED\",\n \"\": [ /* 实体数组，字段原样 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\nSB 的 `apiVersion` 表示调用入口/结构意图，`amazonResourceVersion` 表示实际 Amazon 资源版本；两者不同不代表发生自动回落。SP productAds 客户端过滤时额外带：`serverTotalBeforeClientFilter` + `clientSideFilters`。\n\n## 使用示例\n\n### 1. 列活跃 SP 广告活动\n```bash\npython scripts/sp/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 2. 看某 SP campaign 下的广告组\n```bash\npython scripts/sp/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 3. 按 ASIN 反查 SP 投放（客户端过滤）\n```bash\npython scripts/sp/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 4. 列 SB V4 广告活动（默认）\n```bash\npython scripts/sb/v4/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 5. 列某 SB V4 campaign 下的 adGroups / ads\n```bash\npython scripts/sb/v4/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\npython scripts/sb/v4/list_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n### 6. 管理 SB V4 campaign 的关键词（共享 targeting 路径）\n```bash\npython scripts/sb/v4/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":[\"1122334455\"],\"adGroupIdFilter\":[\"5566778899\"]}'\n```\n\n### 7. 查询已确认的 V3 Legacy campaign\n```bash\npython scripts/sb/v3/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignStructure\":\"LEGACY\",\"stateFilter\":[\"enabled\",\"paused\"]}'\n```\n\n### 8. 列活跃 SD 广告活动\n```bash\npython scripts/sd/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 9. 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\n```bash\npython scripts/sd/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 10. 与 report 配合分析指标\n本 skill 返回实体**元数据**（id、名称、状态、匹配类型等）；指标（曝光、点击、花费、转化）交给 `linkfox-amazon-ads-report`（`reportTypeId: \"spTargeting\"` / `\"sbCampaigns\"` / `\"sdCampaigns\"` 等），按 id join。\n\n## 调用原则\n\n- 返回字段原样保留；不改名、不翻译、不补算派生指标\n- 非 2xx 不自动重试；保留 `httpStatus` + `body` 告知用户\n- `truncated=true` 时明确提示数据未取完\n\n## 常见错误\n\n| 状态 | 含义 | 建议 |\n|------|------|------|\n| `HTTP 401` | accessToken 过期 | 调 ads-auth 的 `refresh_token.py` 后重试 |\n| `HTTP 403` | profileId 无权限 | 核对 profileId 归属 |\n| `HTTP 400` | 入参结构错 | 先核对\"过滤器结构速查\"表 |\n| `HTTP 429` | 限流 | 等 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n## Not Applicable\n\n- 删除 / 归档 → 本 skill 不支持 DELETE（可通过 update state 为 ARCHIVED 实现归档，但归档不可逆）\n- SB 不支持把 V4 Multi-Ad-Group Campaign 降级成 V3；V3 独立 Creative CRUD 不存在，Legacy Creative 通过 Campaign payload 管理\n- SB negativeKeywords / negativeTargets / themes / recommendations 与 Legacy→V4 Migration 暂不在本次 A+B+C 范围\n- SD 的按 id 单查 / brandSafety / recommendations / forecasts / optimizationRules / locations 等\"非基础实体\"接口 → 不在本 skill\n- DSP / ST 实体 → 不在本 skill\n- 指标报表 → `linkfox-amazon-ads-report`\n- 授权 / token / profile → `linkfox-amazon-ads-auth`\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback:**\n\nAuto-detect and report feedback via the Feedback API when any of the following apply:\n1. The functionality or purpose described in this skill does not match actual behavior\n2. The skill's results do not match the user's intent\n3. The user expresses dissatisfaction or praise about this skill\n4. Anything you believe could be improved\n\nCall the feedback API as specified in `references/api.md`. Do not interrupt the user's flow.\n\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.1.1:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-ads-manager\",\n \"version\": \"1.1.1\",\n \"publishedAt\": 1786718538897\n}\n\nFile v1.1.1:references/api.md\n\n# linkfox-amazon-ads-manager — 参数与字段参考（总览）\n\n按 Amazon Ads 广告产品分类维护。\n\n| 广告产品 | 脚本子目录 | 查询参考 |\n|---------|-----------|---------|\n| **Sponsored Products (SP)** — v3 | `scripts/sp/` | [api/sp.md](./api/sp.md) |\n| **Sponsored Brands (SB)** — V3 Legacy + V4 | `scripts/sb/v3/`、`scripts/sb/v4/` | [api/sb.md](./api/sb.md) |\n| **Sponsored Display (SD)** — v3 | `scripts/sd/` | [api/sd.md](./api/sd.md) |\n\n> Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n\n## 通用约定\n\n- 每个脚本接受一个 JSON 字符串作为唯一位置参数\n- 鉴权：环境变量 `LINKFOX_AGENT_API_KEY`（或旧名 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- API 网关地址：环境变量 `LINKFOX_TOOL_GATEWAY`（默认 `https://tool-gateway.linkfox.com`）\n- 依赖 `linkfox-amazon-ads-auth`（脚本启动自动检查；缺失时 exit 42，stderr 打 `DEPENDENCY_MISSING`）\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| `profileId` | number | ✅ | — | 从 ads-auth 获取 |\n| `region` | string | ✅ | — | `NA` / `EU` / `FE` |\n| `fetchAll` | boolean | 否 | `true` | 自动翻页；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count` |\n| `maxResults` | integer | 否 | `100` | 单页 1-100；超限上游可能静默 clamp；对应 SD 端 `count` |\n| `skipDepCheck` | boolean | 否 | `false` | 跳过依赖检查 |\n| `includeExtendedDataFields` | boolean | 否 | — | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 否 | — | 本地化（keywords 支持） |\n\n## 输出格式\n\n```json\n{\n \"success\": true,\n \"apiVersion\": \"V3 | V4\",\n \"amazonResourceVersion\": \"V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED\",\n \"\": [ /* 实体数组 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\n客户端过滤时（SP productAds 的 asinFilter/skuFilter）额外带 `serverTotalBeforeClientFilter` + `clientSideFilters`。\n\nSB 输出中的两个版本字段含义不同：`apiVersion` 表示调用入口和 Campaign 结构意图；`amazonResourceVersion` 表示实际 Amazon 资源传输版本。V4 Keyword/Target 入口使用 Amazon 共享 V3/V3.2 targeting 路径，不代表自动回落。\n\n失败：\n```json\n{\n \"error\": \"Upstream HTTP 401\",\n \"httpStatus\": 401,\n \"body\": \"...\",\n \"pagesFetched\": 0\n}\n```\n\n## 通用错误码\n\n| httpStatus / exit | 含义 | 建议 |\n|-------------------|------|------|\n| 200 | 成功 | — |\n| 400 | 入参结构错 | 核对对应 adProduct 的过滤器结构（api/sp.md / api/sb.md / api/sd.md） |\n| 401 | accessToken 过期 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 402 | 积分或余额不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 403 | profileId 无权限 | 核对 profileId 归属 |\n| 429 | 限流 | 间隔 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n---\n\n## Feedback API\n\n与上面的工具 API **base URL 不同**：\n\n```bash\ncurl -X POST https://skill-api.linkfox.com/api/v1/public/feedback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"skillName\":\"linkfox-amazon-ads-manager\",\"sentiment\":\"POSITIVE\",\n \"category\":\"OTHER\",\"content\":\"实体查询结果与预期一致\"}'\n```\n\n- `sentiment`: `POSITIVE` / `NEUTRAL` / `NEGATIVE`\n- `category`: `BUG` / `COMPLAINT` / `SUGGESTION` / `OTHER`\n\nFile v1.1.1:references/api/sb-coexistence.md\n\n# Sponsored Brands V3 / V4 共存与路由\n\n## 版本边界\n\n| 调用入口 | 适用结构 | 用途 |\n|---|---|---|\n| `scripts/sb/v4/` | `LEGACY` 或 `MULTI_AD_GROUP` | 默认入口；新建活动、多广告组、Ad/Creative 管理 |\n| `scripts/sb/v3/` | 仅 `LEGACY` | 历史活动兼容 |\n| `scripts/sb/*.py` | 同 V4 | 旧路径兼容；新调用应迁到 `scripts/sb/v4/` |\n\n新业务默认使用 V4。只有用户明确要求 V3，或已确认 Campaign 为 Legacy 时，才使用 V3。\n\n## 不自动回落\n\n脚本不执行 `V4 失败 → V3 重试`。Amazon 返回非 2xx 时，保留状态码和响应体交给调用方判断。原因：\n\n1. API 版本不等于 Campaign 结构；\n2. Multi-Ad-Group Campaign 无法无损转换成 V3；\n3. 自动回落会掩盖权限、参数或资源状态错误；\n4. V3 读取 V4 活动可能造成多 Ad Group 数据截断。\n\n当顶层参数或 `payload` 内出现 `campaignStructure=MULTI_AD_GROUP` / `isMultiAdGroupsEnabled=true`（含 `\"true\"`/`1` 等写法）时，V3 脚本会在发请求前返回：\n\n```json\n{\n \"code\": \"SB_V4_CAMPAIGN_NOT_SUPPORTED\",\n \"message\": \"This campaign uses the Sponsored Brands V4 multi-ad-group structure. Use scripts/sb/v4 instead of V3.\"\n}\n```\n\n脚本没有本地 Campaign 数据库；如果调用方未提供结构信息，无法仅凭 `campaignId` 可靠判断结构。因此 Agent 应先用 V4 `list_campaigns.py` 查询 `isMultiAdGroupsEnabled`，再决定是否允许使用 V3。\n\n## Amazon 路径与脚本版本不是一回事\n\nAmazon 的 Campaign / Ad Group / Ad 主资源有明确 V4 路径：\n\n```text\nsb/v4/campaigns/**\nsb/v4/adGroups/**\nsb/v4/ads/**\n```\n\n但 Keyword 与 Product Target 仍使用共享资源路径：\n\n```text\nsb/keywords\nsb/targets\nsb/targets/list\n```\n\n这些共享路径可以通过 `campaignId + adGroupId` 管理多广告组活动。为让调用意图明确，本 skill 在 `sb/v3/` 和 `sb/v4/` 都提供 keyword/target 入口；两者底层调用同一 Amazon 资源：\n\n- `sb/v3/*`：声明调用方已确认是 Legacy；\n- `sb/v4/*`：声明按 V4 Campaign/Ad Group 结构管理；\n- 输出中的 `amazonResourceVersion` 会标记为 `V3_SHARED_TARGETING` 或 `V3.2_SHARED_TARGETING`。\n\n这不是 V4 自动降级，也不会在失败后切换版本。\n\n## Creative 边界\n\n- V3 Legacy Campaign 的 Creative 是 Campaign payload 的组成部分，没有独立的 V3 Creative CRUD 脚本。\n- V4 使用 Ad 与独立 Creative Version：\n - `sb/v4/list_ads.py`\n - `sb/v4/create_ads.py`\n - `sb/v4/list_creatives.py`\n - `sb/v4/create_creatives.py`\n\n不要伪造不存在的 `sb/v3/creatives` 或 `sb/v4/keywords` Amazon 路径。\n\n## 决策流程\n\n```text\n新建 / 多 Ad Group / Ad / Creative\n → scripts/sb/v4/\n\n关键词或 Target\n → 默认 scripts/sb/v4/\n → 仅在已确认 Legacy 或用户明确要求 V3 时使用 scripts/sb/v3/\n\nV3 + MULTI_AD_GROUP\n → 拒绝并提示使用 V4\n\n任一版本调用失败\n → 返回原错误；不自动重试另一版本\n```\n\nFile v1.1.1:references/api/sb-v3.md\n\n# Sponsored Brands V3 Legacy API\n\nV3 仅用于历史 Legacy Campaign。共存与路由规则见 [sb-coexistence.md](./sb-coexistence.md)。\n\n## 脚本\n\n| 脚本 | Amazon 路径 | 方法 | 说明 |\n|---|---|---|---|\n| `sb/v3/list_campaigns.py` | `sb/campaigns` | GET | offset 分页查询 Legacy 活动 |\n| `sb/v3/create_campaigns.py` | `sb/campaigns` | POST | 创建 Legacy 活动；新业务不推荐 |\n| `sb/v3/update_campaigns.py` | `sb/campaigns` | PUT | 更新 Legacy 活动 |\n| `sb/v3/list_ad_groups.py` | `sb/adGroups` | GET | 查询 Legacy 活动关联的 Ad Group |\n| `sb/v3/list_keywords.py` | `sb/keywords` | GET | 查询关键词 |\n| `sb/v3/create_keywords.py` | `sb/keywords` | POST | 创建关键词，最多 100 个 |\n| `sb/v3/update_keywords.py` | `sb/keywords` | PUT | 更新关键词，最多 100 个 |\n| `sb/v3/list_targets.py` | `sb/targets/list` | POST | nextToken 分页查询商品定向 |\n| `sb/v3/create_targets.py` | `sb/targets` | POST | 创建商品定向，最多 100 个 |\n| `sb/v3/update_targets.py` | `sb/targets` | PUT | 更新商品定向 |\n\nV3 Creative 没有独立 CRUD；品牌名、标题、ASIN、素材等位于 Campaign 的 `creative` 字段中，通过 Campaign create/update 管理。\n\n## Legacy 安全参数\n\nV3 脚本额外接受：\n\n| 参数 | 作用 |\n|---|---|\n| `campaignStructure` | 传 `MULTI_AD_GROUP` 时拒绝调用 |\n| `isMultiAdGroupsEnabled` | 传 `true` 时拒绝调用 |\n\n这些字段只用于本地保护，不会发送给 Amazon。\n\n## GET list 参数\n\nCampaign：\n\n- `campaignIdFilter`\n- `stateFilter`\n- `nameFilter`\n- `portfolioIdFilter`\n- `creativeType`\n\nAd Group：\n\n- `adGroupIdFilter`\n- `campaignIdFilter`\n- `stateFilter`\n- `nameFilter`\n- `creativeType`\n\nKeyword：\n\n- `keywordIdFilter`\n- `adGroupIdFilter`\n- `campaignIdFilter`\n- `stateFilter`\n- `matchTypeFilter`\n- `keywordText`\n- `creativeType`\n- `locale`\n\nID、状态、匹配类型可传字符串、数组或 `{\"include\":[...]}`，脚本转换成 Amazon 所需的逗号分隔 query。分页参数为 `maxResults`、`fetchAll`、`maxPages`。\n\n## Target list 参数\n\nTarget list 接受 Amazon 原生 `filters`，也接受顶层 Object/Array 过滤（脚本会映射为 Amazon `filters[]`）：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"campaignIdFilter\": {\"include\": [\"1122334455\"]},\n \"stateFilter\": [\"enabled\", \"paused\"],\n \"maxResults\": 100\n}\n```\n\n等价原生写法：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"payload\": {\n \"maxResults\": 100,\n \"filters\": [\n {\"filterType\": \"CAMPAIGN_ID\", \"values\": [\"1122334455\"]},\n {\"filterType\": \"TARGETING_STATE\", \"values\": [\"enabled\", \"paused\"]}\n ]\n }\n}\n```\n\n可映射字段：`campaignIdFilter`→`CAMPAIGN_ID`，`adGroupIdFilter`→`AD_GROUP_ID`，`stateFilter`→`TARGETING_STATE`，`targetIdFilter`→`TARGET_ID`，`creativeTypeFilter`→`CREATIVE_TYPE`。\n\n## 示例\n\n```bash\npython scripts/sb/v3/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\"stateFilter\":[\"enabled\",\"paused\"]}'\n\npython scripts/sb/v3/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":[\"1122334455\"]}'\n\npython scripts/sb/v3/update_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignStructure\":\"LEGACY\",\"payload\":[{\"keywordId\":1,\"campaignId\":2,\"adGroupId\":3,\"bid\":1.2}]}'\n```\n\n写操作不会自动切换到 V4；非 2xx 原样返回。\n\nFile v1.1.1:references/api/sb-v4.md\n\n# Sponsored Brands V4 API\n\nV4 是默认版本，支持 Legacy 与 Multi-Ad-Group Campaign。共存规则见 [sb-coexistence.md](./sb-coexistence.md)。\n\n## 脚本\n\n| 资源 | 脚本 | Amazon 路径 |\n|---|---|---|\n| Campaign | `list/create/update_campaigns.py` | `sb/v4/campaigns[/list]` |\n| Ad Group | `list/create/update_ad_groups.py` | `sb/v4/adGroups[/list]` |\n| Ad | `list/create/update_ads.py` | `sb/v4/ads[/list]`、`sb/v4/ads/{adType}` |\n| Keyword | `list/create/update_keywords.py` | `sb/keywords`（共享 V3 transport） |\n| Target | `list/create/update_targets.py` | `sb/targets[/list]`（共享 V3/V3.2 transport） |\n| Creative Version | `list_creatives.py`、`create_creatives.py` | `sb/ads/creatives/...` |\n| Budget Rule | `list/create/update_budget_rules.py` | `sb/budgetRules` |\n\n所有路径都位于 `scripts/sb/v4/`。旧的 `scripts/sb/*.py` 保留为 V4 兼容入口，新调用不要继续依赖旧路径。\n\n## Campaign / Ad Group / Ad list\n\n使用 V4 Object/Text filter：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"campaignIdFilter\": {\"include\": [\"1122334455\"]},\n \"stateFilter\": {\"include\": [\"ENABLED\", \"PAUSED\"]},\n \"maxResults\": 100\n}\n```\n\n响应包含 `nextToken`，Campaign/Ad Group/Ad 原始响应还可能包含 `totalCount`；skill 自动聚合为 `total`。\n\n## Keyword / Target\n\nAmazon 没有 `/sb/v4/keywords` 或 `/sb/v4/targets` 路径。V4 脚本通过 `campaignId + adGroupId` 调用共享 targeting 资源：\n\n```bash\npython scripts/sb/v4/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":[\"1122334455\"],\"adGroupIdFilter\":[\"5566778899\"]}'\n\npython scripts/sb/v4/list_targets.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":{\"include\":[\"1122334455\"]},\"stateFilter\":[\"enabled\"]}'\n\npython scripts/sb/v4/create_targets.py '{\"profileId\":1234567890,\"region\":\"NA\",\"payload\":{\"targets\":[{\"campaignId\":1122334455,\"adGroupId\":5566778899,\"expressions\":[{\"type\":\"asinSameAs\",\"value\":\"B0EXAMPLE\"}],\"bid\":1.25}]}}'\n```\n\n`list_targets.py` 会把顶层 `campaignIdFilter` / `adGroupIdFilter` / `stateFilter` 等映射为 Amazon `filters[]`，避免按 keywords 习惯传参时静默全量拉取。这属于 Amazon 官方共享资源，并非 V4 失败后回退到 V3。\n\n## Ad 与 Creative\n\n创建 Ad 时必须传 `adType`：\n\n```text\nautoCollection\nmanualCollection\nbrandVideo\nvideo\nproductCollection\nproductCollectionExtended\nstoreSpotlight\n```\n\n创建新的 Creative Version 时，使用 `create_creatives.py`，传：\n\n```text\nproductCollection\nproductCollectionExtended\nstoreSpotlight\nvideo\nbrandVideo\n```\n\n示例：\n\n```bash\npython scripts/sb/v4/create_creatives.py '{\"profileId\":1234567890,\"region\":\"NA\",\"creativeType\":\"productCollection\",\"payload\":{\"adId\":\"998877\",\"creative\":{\"asins\":[\"B0EXAMPLE\"],\"headline\":\"Example\"}}}'\n```\n\n## 选择规则\n\n- 新建活动、多 Ad Group、Ad、独立 Creative：V4。\n- 未说明版本的关键词/定向管理：默认 V4 入口。\n- 只有确认是 Legacy 或用户明确要求 V3 时，改用 `scripts/sb/v3/`。\n- 调用失败时不自动转 V3。\n\nFile v1.1.1:references/api/sb.md\n\n# Sponsored Brands（SB）API 索引\n\n本 skill 同时提供 V3 Legacy 兼容入口和 V4 主入口：\n\n- [V3 Legacy 参数与脚本](./sb-v3.md)\n- [V4 参数与脚本](./sb-v4.md)\n- [V3/V4 共存、路由和禁止自动回落规则](./sb-coexistence.md)\n\n## 能力摘要\n\n| 入口 | Campaign | Ad Group | Ad | Keyword | Target | Creative Version |\n|---|---:|---:|---:|---:|---:|---:|\n| `scripts/sb/v3/` | ✅ Legacy | 查询 | — | ✅ | ✅ | Campaign payload 内嵌 |\n| `scripts/sb/v4/` | ✅ | ✅ | ✅ | ✅（共享路径） | ✅（共享路径） | ✅ |\n\n## 默认选择\n\n1. 新业务、新建 Campaign、多 Ad Group、Ad 和 Creative 使用 V4。\n2. Keyword / Target 未指定版本时也使用 V4 入口；底层是 Amazon 共享 targeting 路径。\n3. 只有已确认 Campaign 为 Legacy，或用户明确要求 V3 时，才调用 V3。\n4. 不执行 V4 → V3 自动回落。\n5. V3 不允许管理已知的 Multi-Ad-Group Campaign。\n\n## 兼容路径\n\n原 `scripts/sb/*.py` 保留，仍指向既有 V4 Campaign/AdGroup/Ad/BudgetRule 实现。新调用统一使用带版本的路径，避免后续新增能力时产生歧义。\n\nFile v1.1.1:references/api/sd.md\n\n# Sponsored Display (SD) 实体查询 — 参数与字段参考\n\n覆盖 SD v3 的 6 个 list 端点的查询参数与字段定义。通用约定、共用参数、错误码见 `../api.md`；写操作（create/update）通过 `scripts/sd/create_*.py` 与 `scripts/sd/update_*.py` 调用，payload 透传 Amazon 原生格式。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sd/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sd/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sd/list_product_ads.py` | 商品广告 | `productAds` |\n| `sd/list_targets.py` | 定向子句（商品/受众） | `targetingClauses` |\n| `sd/list_negative_targets.py` | 否定定向子句 | `negativeTargetingClauses` |\n| `sd/list_creatives.py` | 创意素材 | `creatives` |\n\n> **注意**：Sponsored Display **没有 keywords**（仅商品 / 受众 / 品类定向）。按 id 单查、创建、删除、归档，以及 brandSafety / forecasts / budgetRules / optimizationRules / locations 等\"非基础实体查询\"接口本技能不覆盖。\n\n## SD 接口形态\n\n| 维度 | Sponsored Display v3 |\n|------|----------------------|\n| HTTP 方法 | `GET` |\n| 参数位置 | querystring |\n| 分页方式 | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 逗号分隔小写串，如 `enabled,paused,archived` |\n| id 类过滤实参 | 逗号分隔字符串，如 `\"123,456\"` |\n| 扩展字段 | 通过路径区分：基础 `/sd/`，扩展 `/sd//extended` |\n| Content-Type | `application/json` |\n\n所有过滤字段对外统一接受 `{\"include\":[...]}`、裸数组、单值字符串三种宽容形态；脚本会将其序列化为 Sponsored Display 端所需的 querystring 参数。\n\n## 过滤器结构\n\n### Object —— `{\"include\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` / `targetIdFilter` / `portfolioIdFilter` / `creativeIdFilter` / `stateFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\":{\"include\": [\"1122334455\", \"6677889900\"]}}\n```\n\n兼容写法（自动归一）：\n- 裸数组 `[\"ENABLED\"]` → `{\"include\":[\"ENABLED\"]}`\n- 裸字符串 `\"ENABLED\"` → `{\"include\":[\"ENABLED\"]}`\n\n### Text —— `nameFilter`\n\nSponsored Display **仅支持精确匹配**，没有 `BROAD_MATCH`：\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\":\"EXACT_MATCH\",\"include\":[\"holiday\"]}}\n```\n\n传 `BROAD_MATCH` 时脚本会在 stderr 输出一次提示，并按 `include[0]` 作 `name` 精确匹配。\n\n### Client-side filter —— `asinFilter` / `skuFilter`（仅 productAds）\n\nSponsored Display 的 `/sd/productAds` 接口不支持按 ASIN / SKU 过滤；脚本会先按其他过滤条件拉取 productAds，再在本地按精确值匹配。建议同时传 `campaignIdFilter` 或 `adGroupIdFilter` 收窄上游拉取范围，否则 stderr 会输出性能提示。\n\n```json\n{\"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}\n```\n\n## 其他入参\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `fetchAll` | bool | 默认 `true`，关闭后只拉第一页 |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count`（每页大小） |\n| `includeExtendedDataFields` | bool | 默认 `false`；`true` 时请求 `/sd//extended` 路径；**`creatives` 没有 extended 路径，此入参无效** |\n| `skipDepCheck` | bool | 跳过 ads-auth 依赖检查 |\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED`（脚本提交上游时自动转为 `enabled` / `paused` / `archived`） | 全部 6 个实体 |\n| `expressionType` | `auto` / `manual` | targets |\n| `creativeType` | （Sponsored Display 各 creative 类型，由上游返回原值） | creatives |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_negative_targets.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_creatives.py` | `creativeIdFilter`、`adGroupIdFilter`（互斥，同时传时上游会按 400 / 422 返回） |\n\n## 常见实体字段\n\n| 实体 | 字段（节选；extended 路径返回更多） |\n|------|---------|\n| campaigns | `campaignId` / `name` / `state` / `tactic`（`T00020` / `T00030`）/ `costType`（`cpc` / `vcpm`）/ `budget` / `budgetType` / `startDate` / `endDate` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` / `bidOptimization` / `creativeType` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `state` / `asin` / `sku` / `landingPageURL` / `landingPageType` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expressionType`（auto / manual）/ `expression`（type ∈ `asinSameAs` / `asinCategorySameAs` / `audience` / `views` / `purchases` ...） / `bid` |\n| negativeTargetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression`（与 targets 类似，type 仅限 `asinSameAs` / `asinBrandSameAs`） |\n| creatives | `creativeId` / `adGroupId` / `name` / `creativeType` / `properties`（headline / brandLogoAssetID / video 等，按 creativeType 不同） / `moderationStatus` |\n\n## 调用示例\n\n```bash\n# 列活跃 SD campaigns\npython sd/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 SD adGroups（含扩展字段，请求 /sd/adGroups/extended）\npython sd/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"includeExtendedDataFields\":true}'\n\n# 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\npython sd/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# 列某 adGroup 下的定向子句\npython sd/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的否定定向\npython sd/list_negative_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的创意\npython sd/list_creatives.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n## 与 SP / SB 的差异速查\n\n供从 Sponsored Products / Sponsored Brands 迁移到 Sponsored Display 的开发者对照查阅。\n\n| 维度 | SP v3 | SB v4 | SD v3 |\n|------|-------|-------|-------|\n| 路径前缀 | `sp/` | `sb/v4/` | `sd/`（+ `/extended` 子路径） |\n| HTTP 方法 | POST list | POST list | GET |\n| Content-Type | `application/vnd.sp.v3+json` | `application/vnd.sbresource.v4+json` | `application/json` |\n| 实体数量 | 6 个 list | 3 个 list | 6 个 list（含 creatives；不含 keywords） |\n| 分页 | `nextToken` | `nextToken` + `totalCount` | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 大写 ENUM | 大写 ENUM | 接口端要求小写串，脚本会自动转换 |\n| 扩展字段 | `includeExtendedDataFields:true` 标志 | `includeExtendedDataFields:true` 标志 | 路径切换 `/sd//extended` |\n| Client-side filter | `asinFilter` / `skuFilter`（productAds） | 暂无 | `asinFilter` / `skuFilter`（productAds） |\n\nFile v1.1.1:references/api/sp.md\n\n# Sponsored Products (SP) 实体查询 — 参数与字段参考\n\n覆盖 6 个 SP v3 list 端点。通用约定、共用参数、错误码见 `../api.md`。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sp/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sp/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sp/list_keywords.py` | 关键词 | `keywords` |\n| `sp/list_negative_keywords.py` | 否定关键词 | `negativeKeywords` |\n| `sp/list_product_ads.py` | 商品广告 | `productAds` |\n| `sp/list_targets.py` | 商品定向 | `targetingClauses`（不是 `targets`）|\n\n## 过滤器结构（5 类）\n\n### 1. Object —— `{\"include\":[...]}` / `{\"exclude\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `keywordIdFilter` / `targetIdFilter` / `adIdFilter` / `negativeKeywordIdFilter` / `portfolioIdFilter` / `stateFilter` / `expressionTypeFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\": {\"include\": [\"1122334455\"]}}\n{\"expressionTypeFilter\": {\"include\": [\"AUTO\"]}}\n```\n\n### 2. Array —— 裸数组 `[\"EXACT\",\"BROAD\"]`\n\n适用：`matchTypeFilter`（keywords / negativeKeywords）\n\n```json\n{\"matchTypeFilter\": [\"EXACT\",\"PHRASE\"]}\n```\n\n兼容：传 `{\"include\":[\"EXACT\"]}` 本 skill 自动解包。\n\n### 3. Scalar —— 裸字符串 `\"AUTO\"`\n\n适用：`campaignTargetingTypeFilter`（adGroups）\n\n```json\n{\"campaignTargetingTypeFilter\": \"AUTO\"}\n```\n\n### 4. Text —— `{\"queryTermMatchType\":\"...\",\"include\":[...]}`\n\n适用：`nameFilter`（campaigns / adGroups）、`keywordTextFilter`（keywords / negativeKeywords）\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\": \"BROAD_MATCH\", \"include\": [\"holiday\"]}}\n```\n\n`queryTermMatchType`: `BROAD_MATCH` / `EXACT_MATCH`。\n\n### 5. Client —— 本 skill 在本地过滤\n\n适用：`asinFilter` / `skuFilter`（productAds）\n\n```json\n{\"asinFilter\": {\"include\": [\"B01ABCDEFG\"]}}\n{\"asinFilter\": [\"B01ABCDEFG\"]}\n{\"asinFilter\": \"B01ABCDEFG\"}\n```\n\nAmazon 原生 list 接口对这两个字段不生效，本 skill 拉取后本地精确匹配。建议同时传 `campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` 收窄拉取量；否则触发全量拉取 + stderr 性能提示。\n\n输出会多出：`serverTotalBeforeClientFilter` / `clientSideFilters`。\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED` | 全部 6 个实体 |\n| `matchType` | `BROAD` / `PHRASE` / `EXACT` | keywords |\n| `matchType` | `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` | negativeKeywords |\n| `expressionType` | `AUTO` / `MANUAL` | targets |\n| `campaignTargetingType` | `AUTO` / `MANUAL` | adGroups |\n| `queryTermMatchType` | `BROAD_MATCH` / `EXACT_MATCH` | nameFilter / keywordTextFilter |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter`、`campaignTargetingTypeFilter` |\n| `list_keywords.py` | `keywordIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`matchTypeFilter`、`keywordTextFilter` |\n| `list_negative_keywords.py` | `negativeKeywordIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`matchTypeFilter`、`keywordTextFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`expressionTypeFilter` |\n\n## 常见实体字段\n\n| 实体 | 字段 |\n|------|------|\n| campaigns | `campaignId` / `name` / `state` / `targetingType` / `budget.{budget,budgetType}` / `startDate` / `endDate` / `dynamicBidding.strategy` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` |\n| keywords | `keywordId` / `adGroupId` / `campaignId` / `keywordText` / `matchType` / `state` / `bid` |\n| negativeKeywords | 同 keywords，`matchType` ∈ `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `asin` / `sku` / `state` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression` / `expressionType` / `bid` |\n\n## 调用示例\n\n```bash\n# 列活跃 campaigns\npython sp/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 AUTO 广告组\npython sp/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"campaignTargetingTypeFilter\":\"AUTO\"}'\n\n# EXACT 关键词\npython sp/list_keywords.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]},\n \"matchTypeFilter\":[\"EXACT\"]}'\n\n# 按 ASIN 反查（client-side，带 campaign 收窄）\npython sp/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# AUTO 定向目标\npython sp/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]},\n \"expressionTypeFilter\":{\"include\":[\"AUTO\"]}}'\n```\n\nFile v1.1.1:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n - `python scripts/onboarding.py send-code ` → 展示 JSON 里的 phone/agreements\n - 收到验证码后：`python scripts/onboarding.py login `（workbuddy 宿主加 `--channel workbuddy`）\n - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"\"`\n - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"\"' >> ~/.zshrc && source ~/.zshrc`\n - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"\"' >> ~/.bashrc && source ~/.bashrc`\n - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order ` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query `，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.1.1:skill-card.md\n\n## Description:\n\n亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal Amazon Ads operators and developers use this skill to query, create, and update Sponsored Products, Sponsored Brands, and Sponsored Display advertising entities through LinkFox-managed Amazon Ads access. It is suited to campaign, ad group, keyword, target, product ad, creative, budget, bid, and status management, with user confirmation expected for spend-impacting changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can query and change Amazon Ads entities, including bids, budgets, and status.\n\nMitigation: Confirm the selected account, region, entity scope, and spend-impacting changes before running create or update operations.\n\nRisk: Credential handling and endpoint overrides can expose API keys, SMS codes, or route requests to an untrusted destination.\n\nMitigation: Keep LINKFOX_TOOL_GATEWAY and related overrides unset unless the destination is trusted, and avoid placing API keys or SMS codes in transcripts or logs.\n\nRisk: Full API responses are persisted locally and may contain sensitive account or advertising data.\n\nMitigation: Keep the linkfox output directory out of source control and delete retained response files when they are no longer needed.\n\nRisk: Account and payment flows may present billing decisions outside normal ad-management work.\n\nMitigation: Review payment prompts separately and require explicit user approval before starting or changing a paid plan.\n\nRisk: Automatic external feedback reporting may disclose operational context if sensitive details are included.\n\nMitigation: Do not include secrets, account identifiers, or sensitive campaign details in feedback content.\n\n## Reference(s):\n\n- [Amazon Ads Manager Skill Source](SKILL.md)\n- [Amazon Ads API Overview](references/api.md)\n- [Sponsored Products API Reference](references/api/sp.md)\n- [Sponsored Brands API Reference](references/api/sb.md)\n- [Sponsored Brands V3 Reference](references/api/sb-v3.md)\n- [Sponsored Brands V4 Reference](references/api/sb-v4.md)\n- [Sponsored Brands V3 and V4 Coexistence](references/api/sb-coexistence.md)\n- [Sponsored Display API Reference](references/api/sd.md)\n- [Authentication and Billing Onboarding](references/onboarding.md)\n- [ClawHub Skill Page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, JSON, guidance]\n\n**Output Format:** [Markdown guidance with shell commands and JSON responses]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Responses are saved locally under a linkfox data directory; large responses are summarized unless inline output is requested.]\n\n## Skill Version(s):\n\n1.1.1 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.5: 72 files, 110736 bytes\n\nFiles: references/api.md (3195b), references/api/sb.md (4135b), references/api/sd.md (7740b), references/api/sp.md (5274b), references/onboarding.md (2046b), scripts/_common.py (30334b), scripts/check_auth_dependency.py (6567b), scripts/onboarding.py (24089b), scripts/sb/create_ad_groups.py (1740b), scripts/sb/create_ads.py (2379b), scripts/sb/create_budget_rules.py (1734b), scripts/sb/create_campaigns.py (1744b), scripts/sb/list_ad_groups.py (3007b), scripts/sb/list_ads.py (3076b), scripts/sb/list_budget_rules.py (2766b), scripts/sb/list_campaigns.py (3074b), scripts/sb/update_ad_groups.py (1754b), scripts/sb/update_ads.py (1711b), scripts/sb/update_budget_rules.py (1747b), scripts/sb/update_campaigns.py (1759b), scripts/sd/create_ad_groups.py (1696b), scripts/sd/create_budget_rules.py (1734b), scripts/sd/create_campaigns.py (1698b), scripts/sd/create_creatives.py (1742b), scripts/sd/create_negative_targets.py (1731b), scripts/sd/create_product_ads.py (1706b), scripts/sd/create_targets.py (1688b), scripts/sd/list_ad_groups.py (3091b), scripts/sd/list_budget_rules.py (2766b), scripts/sd/list_campaigns.py (3476b), scripts/sd/list_creatives.py (3280b), scripts/sd/list_negative_targets.py (3368b), scripts/sd/list_product_ads.py (5026b), scripts/sd/list_targets.py (3460b), scripts/sd/update_ad_groups.py (1710b), scripts/sd/update_budget_rules.py (1747b), scripts/sd/update_campaigns.py (1713b), scripts/sd/update_creatives.py (1715b), scripts/sd/update_negative_targets.py (1744b), scripts/sd/update_product_ads.py (1715b), scripts/sd/update_targets.py (1707b), scripts/sp/create_ad_groups.py (1726b), scripts/sp/create_budget_rules_association.py (1828b), scripts/sp/create_budget_rules.py (1800b), scripts/sp/create_campaign_negative_keywords.py (1841b), scripts/sp/create_campaign_negative_targets.py (1852b), scripts/sp/create_campaigns.py (1730b), scripts/sp/create_keywords.py (1723b), scripts/sp/create_negative_keywords.py (1782b), scripts/sp/create_negative_targets.py (1793b), scripts/sp/create_product_ads.py (1740b), scripts/sp/create_targets.py (1734b), scripts/sp/list_ad_groups.py (2926b), scripts/sp/list_budget_rules.py (2766b), scripts/sp/list_campaigns.py (2911b), scripts/sp/list_keywords.py (3131b), scripts/sp/list_negative_keywords.py (3029b), scripts/sp/list_product_ads.py (5110b), scripts/sp/list_targets.py (2933b), scripts/sp/update_ad_groups.py (1740b), scripts/sp/update_budget_rules.py (1753b), scripts/sp/update_campaign_negative_keywords.py (1855b), scripts/sp/update_campaign_negative_targets.py (1865b), scripts/sp/update_campaigns.py (1745b), scripts/sp/update_keywords.py (1743b), scripts/sp/update_negative_keywords.py (1796b), scripts/sp/update_negative_targets.py (1806b), scripts/sp/update_product_ads.py (1749b), scripts/sp/update_targets.py (1753b), skill-card.md (2731b), SKILL.md (16682b), _meta.json (145b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: linkfox-amazon-ads-manager\ndescription: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 三个产品线的广告查询（list）与创建/修改（create/update）操作。查询覆盖 Sponsored Products (SP) 的广告活动/广告组/关键词/否定关键词/商品广告/定向 6 个 list、Sponsored Brands (SB v4) 的广告活动/广告组/广告 3 个 list，以及 Sponsored Display (SD v3) 的广告活动/广告组/商品广告/定向/否定定向/创意 6 个 list；写操作覆盖全部 create/update（含出价调整、预算修改、状态变更、Budget Rules）。当用户提到查询、创建、修改、调价亚马逊广告时触发。本技能依赖 linkfox-amazon-ads-auth。Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n---\n\n# Amazon Ads 广告管理\n\nAmazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作；经 `developerProxy` 传 `profileId`，由服务端解析 token（勿先 `storeTokens` 取 raw token）。自动处理分页、过滤字段规范化。\n\n| 广告产品 | 覆盖实体 | 脚本子目录 | 详细参数 |\n|---------|---------|-----------|---------|\n| **SP** (Sponsored Products) v3 | campaigns / adGroups / keywords / negativeKeywords / productAds / targets | `scripts/sp/` | [references/api/sp.md](./references/api/sp.md) |\n| **SB** (Sponsored Brands) v4 | campaigns / adGroups / ads | `scripts/sb/` | [references/api/sb.md](./references/api/sb.md) |\n| **SD** (Sponsored Display) v3 | campaigns / adGroups / productAds / targets / negativeTargets / creatives | `scripts/sd/` | [references/api/sd.md](./references/api/sd.md) |\n\n**依赖 `linkfox-amazon-ads-auth`**（脚本启动时自动检查；未安装时 exit 42，stderr 打 `DEPENDENCY_MISSING`）。\n\n### ⚠️ 多账号场景：调用前必须解析好 profileId\n\n用户经常只说自然语言（\"美国站\"、\"日本站\"、\"我的店铺\"），本 skill 的所有脚本都必须拿到数字 `profileId` 才能调。按下列顺序处理，**不要跳过**：\n\n1. 先调 `linkfox-amazon-ads-auth` 的 `authorized_stores.py` 拉出用户已授权的账号 × 站点清单。\n2. 根据用户提到的站点（映射到 `countryCode`，如 美国→`US`）匹配候选 profile：\n - **只有 1 个候选** → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。\n - **≥ 2 个候选（同站点下多个授权账号）** → **必须向用户澄清**，用 `accountName` 问：\"你在美国站授权了 A 和 B 两个账号，这次用哪个？\"\n - **0 个候选** → 告知用户该站点未授权，引导去 `linkfox-amazon-ads-auth` 做授权。\n3. **严禁**让用户直接报 profileId 数字。\n4. **严禁**在歧义下\"挑第一个\"或\"选默认\"绕过澄清。\n\n完整决策表见 `linkfox-amazon-ads-auth` SKILL.md 的 **Usage Scenarios 第 4 节**。\n\n## Core Concepts\n\n- **自动分页**：`fetchAll=true`（默认）跟随分页 token 到结束或 `maxPages=50` 兜底（约 5000 条，超出标 `truncated=true`）；SP / SB 用 `nextToken`，SD 用 `startIndex + count` 偏移分页\n- **过滤器结构不统一**：不同字段需要不同写法（详见下方\"过滤器结构速查\"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入\n- **只给 metadata，不含指标**：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 `linkfox-amazon-ads-report`，按 id join\n- **支持 create / update**：各模块下 `create_*.py` / `update_*.py` 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式\n- **SB 和 SP 的差异**：SB 只有 campaigns/adGroups/ads 三个 list；其 keywords/targets 官方未提供 list all\n- **SD 接口形态**：Sponsored Display 是 v3 REST endpoint，`GET /sd/` + querystring，分页用 `startIndex + count`；state / id 类过滤为逗号分隔字符串；`includeExtendedDataFields:true` 时请求 `/sd//extended` 路径。所有过滤字段统一支持 `{\"include\":[...]}` 入参\n\n## 可用脚本\n\n### SP（28 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sp/list_campaigns.py` | 广告活动 | 查询 |\n| `sp/create_campaigns.py` | 广告活动 | 创建 |\n| `sp/update_campaigns.py` | 广告活动 | 修改（预算/策略/状态/名称等） |\n| `sp/list_ad_groups.py` | 广告组 | 查询 |\n| `sp/create_ad_groups.py` | 广告组 | 创建 |\n| `sp/update_ad_groups.py` | 广告组 | 修改（默认出价/状态/名称等） |\n| `sp/list_keywords.py` | 关键词 | 查询 |\n| `sp/create_keywords.py` | 关键词 | 创建 |\n| `sp/update_keywords.py` | 关键词 | 修改（出价/状态等） |\n| `sp/list_negative_keywords.py` | 否定关键词 | 查询 |\n| `sp/create_negative_keywords.py` | 否定关键词 | 创建 |\n| `sp/update_negative_keywords.py` | 否定关键词 | 修改（状态等） |\n| `sp/list_product_ads.py` | 商品广告 | 查询 |\n| `sp/create_product_ads.py` | 商品广告 | 创建 |\n| `sp/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sp/list_targets.py` | 商品定向 | 查询 |\n| `sp/create_targets.py` | 商品定向 | 创建 |\n| `sp/update_targets.py` | 商品定向 | 修改（出价/状态等） |\n| `sp/create_campaign_negative_keywords.py` | 活动级否定关键词 | 创建 |\n| `sp/update_campaign_negative_keywords.py` | 活动级否定关键词 | 修改（状态等） |\n| `sp/create_campaign_negative_targets.py` | 活动级否定定向 | 创建 |\n| `sp/update_campaign_negative_targets.py` | 活动级否定定向 | 修改（状态等） |\n| `sp/create_negative_targets.py` | 广告组级否定定向 | 创建 |\n| `sp/update_negative_targets.py` | 广告组级否定定向 | 修改（状态等） |\n| `sp/list_budget_rules.py` | 预算规则 | 查询 |\n| `sp/create_budget_rules.py` | 预算规则 | 创建 |\n| `sp/update_budget_rules.py` | 预算规则 | 修改 |\n| `sp/create_budget_rules_association.py` | 预算规则关联 | 关联规则到活动 |\n\n### SB（12 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sb/list_campaigns.py` | 广告活动 | 查询 |\n| `sb/create_campaigns.py` | 广告活动 | 创建 |\n| `sb/update_campaigns.py` | 广告活动 | 修改（预算/状态/名称等） |\n| `sb/list_ad_groups.py` | 广告组 | 查询 |\n| `sb/create_ad_groups.py` | 广告组 | 创建 |\n| `sb/update_ad_groups.py` | 广告组 | 修改（出价/状态等） |\n| `sb/list_ads.py` | 广告创意 | 查询 |\n| `sb/create_ads.py` | 广告创意 | 创建（按 adType 选路径） |\n| `sb/update_ads.py` | 广告创意 | 修改（出价/状态/创意等） |\n| `sb/list_budget_rules.py` | 预算规则 | 查询 |\n| `sb/create_budget_rules.py` | 预算规则 | 创建 |\n| `sb/update_budget_rules.py` | 预算规则 | 修改 |\n\n### SD（21 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sd/list_campaigns.py` | 广告活动 | 查询 |\n| `sd/create_campaigns.py` | 广告活动 | 创建 |\n| `sd/update_campaigns.py` | 广告活动 | 修改（预算/状态/名称等） |\n| `sd/list_ad_groups.py` | 广告组 | 查询 |\n| `sd/create_ad_groups.py` | 广告组 | 创建 |\n| `sd/update_ad_groups.py` | 广告组 | 修改（出价/状态等） |\n| `sd/list_product_ads.py` | 商品广告 | 查询 |\n| `sd/create_product_ads.py` | 商品广告 | 创建 |\n| `sd/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sd/list_targets.py` | 定向子句 | 查询 |\n| `sd/create_targets.py` | 定向子句 | 创建 |\n| `sd/update_targets.py` | 定向子句 | 修改（出价/状态等） |\n| `sd/list_negative_targets.py` | 否定定向子句 | 查询 |\n| `sd/create_negative_targets.py` | 否定定向子句 | 创建 |\n| `sd/update_negative_targets.py` | 否定定向子句 | 修改（状态等） |\n| `sd/list_creatives.py` | 创意素材 | 查询 |\n| `sd/create_creatives.py` | 创意素材 | 创建 |\n| `sd/update_creatives.py` | 创意素材 | 修改（素材/状态等） |\n| `sd/list_budget_rules.py` | 预算规则 | 查询 |\n| `sd/create_budget_rules.py` | 预算规则 | 创建 |\n| `sd/update_budget_rules.py` | 预算规则 | 修改 |\n详细过滤器、枚举值、返回字段见 [references/api/sp.md](./references/api/sp.md) / [references/api/sb.md](./references/api/sb.md) / [references/api/sd.md](./references/api/sd.md)。\n\n## 调用方式\n\n- **API 端点**：`POST /amazonAds/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-ads-manager-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## Financial Safety Guidance\n\n创建和更新操作可能直接影响广告花费，立即生效且无法撤回。\n\n**决策规则：**\n\n| 用户状态 | Agent 行为 |\n|----------|-----------|\n| 已授权（说过\"自动调价\"/\"按你判断来\"/\"不用问我\"/\"确认\"等） | 直接执行 → 输出操作回执 |\n| 未授权（首次交互、未明确表态） | 先输出确认摘要 → 等用户确认后执行 |\n\n**确认摘要模板**（未授权时，执行前输出）：\n```\n📋 即将执行：\n- 操作：[创建/修改] [N 个] [实体类型]\n- 变更：[关键字段变化，如 bid $1.0→$1.5 / budget $50→$100]\n- 影响：[花费变化预估，引用日预算作为上限]\n确认执行？后续如需自动处理，告诉我即可。\n```\n\n**操作回执模板**（每次写操作执行后必须输出）：\n```\n✅ 已执行：[简短描述]\n- 范围：[实体数量、名称或 ID]\n- 变化：[具体变更内容]\n- 结果：[成功 N 个 / 失败 M 个]\n```\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `profileId` | number | 必填，从 ads-auth 获取 |\n| `region` | string | 必填，`NA` / `EU` / `FE` |\n| `fetchAll` | bool | 默认 `true`；SP / SB 用 `nextToken`，SD 用 `startIndex + count` 偏移分页 |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count` |\n| `includeExtendedDataFields` | bool | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 本地化（SP keywords 支持） |\n\n## 过滤器结构速查（最易错）\n\n| 结构 | 示例 | 适用字段 |\n|------|------|----------|\n| **Object** | `{\"include\":[...]}` / `{\"exclude\":[...]}` | 全部 id/状态类：campaignIdFilter、adGroupIdFilter、keywordIdFilter、stateFilter、portfolioIdFilter、expressionTypeFilter、adIdFilter |\n| **Array** | `[\"EXACT\",\"BROAD\"]` | matchTypeFilter（SP keywords/negativeKeywords） |\n| **Scalar** | `\"AUTO\"` | campaignTargetingTypeFilter（SP adGroups） |\n| **Text** | `{\"queryTermMatchType\":\"BROAD_MATCH\",\"include\":[\"...\"]}` | nameFilter、keywordTextFilter |\n| **Client** | 任意形式，本 skill 本地过滤 | asinFilter、skuFilter（SP productAds） |\n\n**易错点**：\n- SP `matchTypeFilter` 是**裸数组** `[\"EXACT\"]`（传错本 skill 自动规范化）\n- `expressionTypeFilter` 反而是 **Object**（与 matchType 不同）\n- `asinFilter` / `skuFilter` 客户端过滤，建议同时传 `campaignIdFilter` / `adGroupIdFilter` 收窄\n\n## 响应格式\n\n```json\n{\n \"success\": true,\n \"\": [ /* 实体数组，字段原样 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\nSP productAds 客户端过滤时额外带：`serverTotalBeforeClientFilter` + `clientSideFilters`。\n\n## 使用示例\n\n### 1. 列活跃 SP 广告活动\n```bash\npython scripts/sp/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 2. 看某 SP campaign 下的广告组\n```bash\npython scripts/sp/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 3. 按 ASIN 反查 SP 投放（客户端过滤）\n```bash\npython scripts/sp/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 4. 列 SB 广告活动\n```bash\npython scripts/sb/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 5. 列某 SB campaign 下的 adGroups / ads\n```bash\npython scripts/sb/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\npython scripts/sb/list_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n### 6. 列活跃 SD 广告活动\n```bash\npython scripts/sd/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 7. 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\n```bash\npython scripts/sd/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 8. 与 report 配合分析指标\n本 skill 返回实体**元数据**（id、名称、状态、匹配类型等）；指标（曝光、点击、花费、转化）交给 `linkfox-amazon-ads-report`（`reportTypeId: \"spTargeting\"` / `\"sbCampaigns\"` / `\"sdCampaigns\"` 等），按 id join。\n\n## 调用原则\n\n- 返回字段原样保留；不改名、不翻译、不补算派生指标\n- 非 2xx 不自动重试；保留 `httpStatus` + `body` 告知用户\n- `truncated=true` 时明确提示数据未取完\n\n## 常见错误\n\n| 状态 | 含义 | 建议 |\n|------|------|------|\n| `HTTP 401` | accessToken 过期 | 调 ads-auth 的 `refresh_token.py` 后重试 |\n| `HTTP 403` | profileId 无权限 | 核对 profileId 归属 |\n| `HTTP 400` | 入参结构错 | 先核对\"过滤器结构速查\"表 |\n| `HTTP 429` | 限流 | 等 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n## Not Applicable\n\n- 删除 / 归档 → 本 skill 不支持 DELETE（可通过 update state 为 ARCHIVED 实现归档，但归档不可逆）\n- SB 的 keywords / negativeKeywords / targets / negativeTargets 的 list all → **Amazon 官方未提供**，需按 id 单查（不在本 skill）\n- SD 的按 id 单查 / brandSafety / recommendations / forecasts / optimizationRules / locations 等\"非基础实体\"接口 → 不在本 skill\n- DSP / ST 实体 → 不在本 skill\n- 指标报表 → `linkfox-amazon-ads-report`\n- 授权 / token / profile → `linkfox-amazon-ads-auth`\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback:**\n\nAuto-detect and report feedback via the Feedback API when any of the following apply:\n1. The functionality or purpose described in this skill does not match actual behavior\n2. The skill's results do not match the user's intent\n3. The user expresses dissatisfaction or praise about this skill\n4. Anything you believe could be improved\n\nCall the feedback API as specified in `references/api.md`. Do not interrupt the user's flow.\n\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.0.5:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-ads-manager\",\n \"version\": \"1.0.5\",\n \"publishedAt\": 1786099124236\n}\n\nFile v1.0.5:references/api.md\n\n# linkfox-amazon-ads-manager — 参数与字段参考（总览）\n\n按 Amazon Ads 广告产品分类维护。\n\n| 广告产品 | 脚本子目录 | 查询参考 |\n|---------|-----------|---------|\n| **Sponsored Products (SP)** — v3 | `scripts/sp/` | [api/sp.md](./api/sp.md) |\n| **Sponsored Brands (SB)** — v4 | `scripts/sb/` | [api/sb.md](./api/sb.md) |\n| **Sponsored Display (SD)** — v3 | `scripts/sd/` | [api/sd.md](./api/sd.md) |\n\n> Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n\n## 通用约定\n\n- 每个脚本接受一个 JSON 字符串作为唯一位置参数\n- 鉴权：环境变量 `LINKFOX_AGENT_API_KEY`（或旧名 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- API 网关地址：环境变量 `LINKFOX_TOOL_GATEWAY`（默认 `https://tool-gateway.linkfox.com`）\n- 依赖 `linkfox-amazon-ads-auth`（脚本启动自动检查；缺失时 exit 42，stderr 打 `DEPENDENCY_MISSING`）\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| `profileId` | number | ✅ | — | 从 ads-auth 获取 |\n| `region` | string | ✅ | — | `NA` / `EU` / `FE` |\n| `fetchAll` | boolean | 否 | `true` | 自动翻页（SP / SB 跟 `nextToken`，SD 用 `startIndex + count`） |\n| `maxResults` | integer | 否 | `100` | 单页 1-100；超限上游可能静默 clamp；对应 SD 端 `count` |\n| `skipDepCheck` | boolean | 否 | `false` | 跳过依赖检查 |\n| `includeExtendedDataFields` | boolean | 否 | — | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 否 | — | 本地化（keywords 支持） |\n\n## 输出格式\n\n```json\n{\n \"success\": true,\n \"\": [ /* 实体数组 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\n客户端过滤时（SP productAds 的 asinFilter/skuFilter）额外带 `serverTotalBeforeClientFilter` + `clientSideFilters`。\n\n失败：\n```json\n{\n \"error\": \"Upstream HTTP 401\",\n \"httpStatus\": 401,\n \"body\": \"...\",\n \"pagesFetched\": 0\n}\n```\n\n## 通用错误码\n\n| httpStatus / exit | 含义 | 建议 |\n|-------------------|------|------|\n| 200 | 成功 | — |\n| 400 | 入参结构错 | 核对对应 adProduct 的过滤器结构（api/sp.md / api/sb.md / api/sd.md） |\n| 401 | accessToken 过期 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 402 | 积分或余额不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 403 | profileId 无权限 | 核对 profileId 归属 |\n| 429 | 限流 | 间隔 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n---\n\n## Feedback API\n\n与上面的工具 API **base URL 不同**：\n\n```bash\ncurl -X POST https://skill-api.linkfox.com/api/v1/public/feedback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"skillName\":\"linkfox-amazon-ads-manager\",\"sentiment\":\"POSITIVE\",\n \"category\":\"OTHER\",\"content\":\"实体查询结果与预期一致\"}'\n```\n\n- `sentiment`: `POSITIVE` / `NEUTRAL` / `NEGATIVE`\n- `category`: `BUG` / `COMPLAINT` / `SUGGESTION` / `OTHER`\n\nFile v1.0.5:references/api/sb.md\n\n# Sponsored Brands (SB) 实体查询 — 参数与字段参考\n\n覆盖 SB v4 的 3 个 list 端点。通用约定、共用参数、错误码见 `../api.md`。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sb/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sb/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sb/list_ads.py` | 广告创意 | `ads` |\n\n> **注意**：SB v4 仅提供 campaigns/adGroups/ads 三个 list。SB 的 keywords/negativeKeywords/targets/negativeTargets 是 v3 REST 风格（`GET /sb/xxx/{id}` 按 id 单查 / `POST /sb/xxx` 创建），**Amazon 官方没有提供\"list all\"端点**，本 skill 也不提供。\n\n## 响应额外字段\n\nSB v4 响应除 ``、`nextToken` 之外，还会带 `totalCount`：\n\n```json\n{\n \"campaigns\": [ ... ],\n \"totalCount\": 42,\n \"nextToken\": \"...\"\n}\n```\n\n本 skill 输出会自动汇总所有分页 items，`total` 字段是**最终**条数。\n\n## 过滤器结构\n\nSB v4 的 filter 体系与 SP v3 **基本一致**（复用 skill 的结构化规范）：\n\n### Object —— `{\"include\":[...]}` / `{\"exclude\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` / `portfolioIdFilter` / `stateFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\": {\"include\": [\"1122334455\"]}}\n```\n\n### Text —— `{\"queryTermMatchType\":\"...\",\"include\":[...]}`\n\n适用：`nameFilter`（campaigns / adGroups）\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\": \"BROAD_MATCH\", \"include\": [\"holiday\"]}}\n```\n\n`queryTermMatchType`: `BROAD_MATCH` / `EXACT_MATCH`。\n\n### 其他入参\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `includeExtendedDataFields` | boolean | 返回扩展字段（策略、时间戳等） |\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED` | 全部 3 个实体 |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter` |\n| `list_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n\n## 常见实体字段\n\n| 实体 | 字段 |\n|------|------|\n| campaigns | `campaignId` / `name` / `state` / `portfolioId` / `budget.{budget,budgetType}` / `brandEntityId` / `brandName` / `startDate` / `endDate` / `bidding` 等 |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `bidOptimization` 等 |\n| ads | `adId` / `adGroupId` / `campaignId` / `state` / `creativeType`（`PRODUCT_COLLECTION` / `VIDEO` / `BRAND_VIDEO` / `STORE_SPOTLIGHT` 等）/ 对应类型的创意字段 |\n\n> SB v4 的 ads 列表返回各种创意类型的元数据；若需读取创意细节，Amazon 另提供 `/sb/ads/creatives/*` 端点（本 skill 暂未覆盖）。\n\n## 调用示例\n\n```bash\n# 列活跃 SB campaigns\npython sb/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 adGroups（带名称模糊匹配）\npython sb/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"nameFilter\":{\"queryTermMatchType\":\"BROAD_MATCH\",\"include\":[\"spring\"]}}'\n\n# 列某 adGroup 下的 ads\npython sb/list_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n## 与 SP 的差异速查\n\n| 维度 | SP v3 | SB v4 |\n|------|-------|-------|\n| 路径前缀 | `sp/` | `sb/v4/` |\n| Content-Type | `application/vnd.sp.v3+json`（Amazon 严格要求小写 vendor MIME） | `application/vnd.sbresource.v4+json`（全小写；响应 MIME） |\n| 实体数量 | 6 个 list | 3 个 list（keywords/targets 等 v3 未提供 list） |\n| 过滤器 | Object / Array / Scalar / Text / Client 5 类 | 主要 Object + Text；暂未见到 Array/Scalar 需求 |\n| 响应分页 | `nextToken` | `nextToken` + `totalCount`（SB 特有） |\n| 客户端过滤 | `asinFilter` / `skuFilter`（productAds） | 暂无 |\n\nFile v1.0.5:references/api/sd.md\n\n# Sponsored Display (SD) 实体查询 — 参数与字段参考\n\n覆盖 SD v3 的 6 个 list 端点的查询参数与字段定义。通用约定、共用参数、错误码见 `../api.md`；写操作（create/update）通过 `scripts/sd/create_*.py` 与 `scripts/sd/update_*.py` 调用，payload 透传 Amazon 原生格式。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sd/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sd/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sd/list_product_ads.py` | 商品广告 | `productAds` |\n| `sd/list_targets.py` | 定向子句（商品/受众） | `targetingClauses` |\n| `sd/list_negative_targets.py` | 否定定向子句 | `negativeTargetingClauses` |\n| `sd/list_creatives.py` | 创意素材 | `creatives` |\n\n> **注意**：Sponsored Display **没有 keywords**（仅商品 / 受众 / 品类定向）。按 id 单查、创建、删除、归档，以及 brandSafety / forecasts / budgetRules / optimizationRules / locations 等\"非基础实体查询\"接口本技能不覆盖。\n\n## SD 接口形态\n\n| 维度 | Sponsored Display v3 |\n|------|----------------------|\n| HTTP 方法 | `GET` |\n| 参数位置 | querystring |\n| 分页方式 | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 逗号分隔小写串，如 `enabled,paused,archived` |\n| id 类过滤实参 | 逗号分隔字符串，如 `\"123,456\"` |\n| 扩展字段 | 通过路径区分：基础 `/sd/`，扩展 `/sd//extended` |\n| Content-Type | `application/json` |\n\n所有过滤字段对外统一接受 `{\"include\":[...]}`、裸数组、单值字符串三种宽容形态；脚本会将其序列化为 Sponsored Display 端所需的 querystring 参数。\n\n## 过滤器结构\n\n### Object —— `{\"include\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` / `targetIdFilter` / `portfolioIdFilter` / `creativeIdFilter` / `stateFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\":{\"include\": [\"1122334455\", \"6677889900\"]}}\n```\n\n兼容写法（自动归一）：\n- 裸数组 `[\"ENABLED\"]` → `{\"include\":[\"ENABLED\"]}`\n- 裸字符串 `\"ENABLED\"` → `{\"include\":[\"ENABLED\"]}`\n\n### Text —— `nameFilter`\n\nSponsored Display **仅支持精确匹配**，没有 `BROAD_MATCH`：\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\":\"EXACT_MATCH\",\"include\":[\"holiday\"]}}\n```\n\n传 `BROAD_MATCH` 时脚本会在 stderr 输出一次提示，并按 `include[0]` 作 `name` 精确匹配。\n\n### Client-side filter —— `asinFilter` / `skuFilter`（仅 productAds）\n\nSponsored Display 的 `/sd/productAds` 接口不支持按 ASIN / SKU 过滤；脚本会先按其他过滤条件拉取 productAds，再在本地按精确值匹配。建议同时传 `campaignIdFilter` 或 `adGroupIdFilter` 收窄上游拉取范围，否则 stderr 会输出性能提示。\n\n```json\n{\"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}\n```\n\n## 其他入参\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `fetchAll` | bool | 默认 `true`，关闭后只拉第一页 |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count`（每页大小） |\n| `includeExtendedDataFields` | bool | 默认 `false`；`true` 时请求 `/sd//extended` 路径；**`creatives` 没有 extended 路径，此入参无效** |\n| `skipDepCheck` | bool | 跳过 ads-auth 依赖检查 |\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED`（脚本提交上游时自动转为 `enabled` / `paused` / `archived`） | 全部 6 个实体 |\n| `expressionType` | `auto` / `manual` | targets |\n| `creativeType` | （Sponsored Display 各 creative 类型，由上游返回原值） | creatives |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_negative_targets.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_creatives.py` | `creativeIdFilter`、`adGroupIdFilter`（互斥，同时传时上游会按 400 / 422 返回） |\n\n## 常见实体字段\n\n| 实体 | 字段（节选；extended 路径返回更多） |\n|------|---------|\n| campaigns | `campaignId` / `name` / `state` / `tactic`（`T00020` / `T00030`）/ `costType`（`cpc` / `vcpm`）/ `budget` / `budgetType` / `startDate` / `endDate` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` / `bidOptimization` / `creativeType` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `state` / `asin` / `sku` / `landingPageURL` / `landingPageType` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expressionType`（auto / manual）/ `expression`（type ∈ `asinSameAs` / `asinCategorySameAs` / `audience` / `views` / `purchases` ...） / `bid` |\n| negativeTargetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression`（与 targets 类似，type 仅限 `asinSameAs` / `asinBrandSameAs`） |\n| creatives | `creativeId` / `adGroupId` / `name` / `creativeType` / `properties`（headline / brandLogoAssetID / video 等，按 creativeType 不同） / `moderationStatus` |\n\n## 调用示例\n\n```bash\n# 列活跃 SD campaigns\npython sd/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 SD adGroups（含扩展字段，请求 /sd/adGroups/extended）\npython sd/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"includeExtendedDataFields\":true}'\n\n# 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\npython sd/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# 列某 adGroup 下的定向子句\npython sd/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的否定定向\npython sd/list_negative_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的创意\npython sd/list_creatives.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n## 与 SP / SB 的差异速查\n\n供从 Sponsored Products / Sponsored Brands 迁移到 Sponsored Display 的开发者对照查阅。\n\n| 维度 | SP v3 | SB v4 | SD v3 |\n|------|-------|-------|-------|\n| 路径前缀 | `sp/` | `sb/v4/` | `sd/`（+ `/extended` 子路径） |\n| HTTP 方法 | POST list | POST list | GET |\n| Content-Type | `application/vnd.sp.v3+json` | `application/vnd.sbresource.v4+json` | `application/json` |\n| 实体数量 | 6 个 list | 3 个 list | 6 个 list（含 creatives；不含 keywords） |\n| 分页 | `nextToken` | `nextToken` + `totalCount` | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 大写 ENUM | 大写 ENUM | 接口端要求小写串，脚本会自动转换 |\n| 扩展字段 | `includeExtendedDataFields:true` 标志 | `includeExtendedDataFields:true` 标志 | 路径切换 `/sd//extended` |\n| Client-side filter | `asinFilter` / `skuFilter`（productAds） | 暂无 | `asinFilter` / `skuFilter`（productAds） |\n\nFile v1.0.5:references/api/sp.md\n\n# Sponsored Products (SP) 实体查询 — 参数与字段参考\n\n覆盖 6 个 SP v3 list 端点。通用约定、共用参数、错误码见 `../api.md`。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sp/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sp/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sp/list_keywords.py` | 关键词 | `keywords` |\n| `sp/list_negative_keywords.py` | 否定关键词 | `negativeKeywords` |\n| `sp/list_product_ads.py` | 商品广告 | `productAds` |\n| `sp/list_targets.py` | 商品定向 | `targetingClauses`（不是 `targets`）|\n\n## 过滤器结构（5 类）\n\n### 1. Object —— `{\"include\":[...]}` / `{\"exclude\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `keywordIdFilter` / `targetIdFilter` / `adIdFilter` / `negativeKeywordIdFilter` / `portfolioIdFilter` / `stateFilter` / `expressionTypeFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\": {\"include\": [\"1122334455\"]}}\n{\"expressionTypeFilter\": {\"include\": [\"AUTO\"]}}\n```\n\n### 2. Array —— 裸数组 `[\"EXACT\",\"BROAD\"]`\n\n适用：`matchTypeFilter`（keywords / negativeKeywords）\n\n```json\n{\"matchTypeFilter\": [\"EXACT\",\"PHRASE\"]}\n```\n\n兼容：传 `{\"include\":[\"EXACT\"]}` 本 skill 自动解包。\n\n### 3. Scalar —— 裸字符串 `\"AUTO\"`\n\n适用：`campaignTargetingTypeFilter`（adGroups）\n\n```json\n{\"campaignTargetingTypeFilter\": \"AUTO\"}\n```\n\n### 4. Text —— `{\"queryTermMatchType\":\"...\",\"include\":[...]}`\n\n适用：`nameFilter`（campaigns / adGroups）、`keywordTextFilter`（keywords / negativeKeywords）\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\": \"BROAD_MATCH\", \"include\": [\"holiday\"]}}\n```\n\n`queryTermMatchType`: `BROAD_MATCH` / `EXACT_MATCH`。\n\n### 5. Client —— 本 skill 在本地过滤\n\n适用：`asinFilter` / `skuFilter`（productAds）\n\n```json\n{\"asinFilter\": {\"include\": [\"B01ABCDEFG\"]}}\n{\"asinFilter\": [\"B01ABCDEFG\"]}\n{\"asinFilter\": \"B01ABCDEFG\"}\n```\n\nAmazon 原生 list 接口对这两个字段不生效，本 skill 拉取后本地精确匹配。建议同时传 `campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` 收窄拉取量；否则触发全量拉取 + stderr 性能提示。\n\n输出会多出：`serverTotalBeforeClientFilter` / `clientSideFilters`。\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED` | 全部 6 个实体 |\n| `matchType` | `BROAD` / `PHRASE` / `EXACT` | keywords |\n| `matchType` | `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` | negativeKeywords |\n| `expressionType` | `AUTO` / `MANUAL` | targets |\n| `campaignTargetingType` | `AUTO` / `MANUAL` | adGroups |\n| `queryTermMatchType` | `BROAD_MATCH` / `EXACT_MATCH` | nameFilter / keywordTextFilter |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter`、`campaignTargetingTypeFilter` |\n| `list_keywords.py` | `keywordIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`matchTypeFilter`、`keywordTextFilter` |\n| `list_negative_keywords.py` | `negativeKeywordIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`matchTypeFilter`、`keywordTextFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`expressionTypeFilter` |\n\n## 常见实体字段\n\n| 实体 | 字段 |\n|------|------|\n| campaigns | `campaignId` / `name` / `state` / `targetingType` / `budget.{budget,budgetType}` / `startDate` / `endDate` / `dynamicBidding.strategy` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` |\n| keywords | `keywordId` / `adGroupId` / `campaignId` / `keywordText` / `matchType` / `state` / `bid` |\n| negativeKeywords | 同 keywords，`matchType` ∈ `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `asin` / `sku` / `state` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression` / `expressionType` / `bid` |\n\n## 调用示例\n\n```bash\n# 列活跃 campaigns\npython sp/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 AUTO 广告组\npython sp/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"campaignTargetingTypeFilter\":\"AUTO\"}'\n\n# EXACT 关键词\npython sp/list_keywords.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]},\n \"matchTypeFilter\":[\"EXACT\"]}'\n\n# 按 ASIN 反查（client-side，带 campaign 收窄）\npython sp/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# AUTO 定向目标\npython sp/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]},\n \"expressionTypeFilter\":{\"include\":[\"AUTO\"]}}'\n```\n\nFile v1.0.5:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n - `python scripts/onboarding.py send-code ` → 展示 JSON 里的 phone/agreements\n - 收到验证码后：`python scripts/onboarding.py login `（workbuddy 宿主加 `--channel workbuddy`）\n - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"\"`\n - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"\"' >> ~/.zshrc && source ~/.zshrc`\n - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"\"' >> ~/.bashrc && source ~/.bashrc`\n - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order ` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query `，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.5:skill-card.md\n\n## Description:\n\nManages Amazon Ads Sponsored Products, Sponsored Brands, and Sponsored Display entities by listing, creating, and updating campaigns, ad groups, ads, keywords, targets, product ads, creatives, negative criteria, and budget rules.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and advertising operators use this skill to manage Amazon Ads account entities across Sponsored Products, Sponsored Brands, and Sponsored Display. It supports account-specific profile selection, entity lookup, and controlled create or update operations that can affect campaign state and spend.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Create and update actions can change live Amazon Ads campaign state, bids, budgets, and related entities.\n\nMitigation: Require an explicit confirmation summary before create or update operations unless the user has already authorized automatic execution for the task.\n\nRisk: The skill handles API keys, account login flows, phone-based onboarding, and billing or payment steps.\n\nMitigation: Install only in a dedicated workspace and proceed only when the user is comfortable with LinkFox handling those flows.\n\nRisk: Full API responses are saved persistently under the workspace and may contain sensitive advertising account data.\n\nMitigation: Review saved linkfox response files for sensitive data and limit workspace access to users who should see the account information.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-ads-manager)\n- [Amazon Ads manager API overview](references/api.md)\n- [Sponsored Products API reference](references/api/sp.md)\n- [Sponsored Brands API reference](references/api/sb.md)\n- [Sponsored Display API reference](references/api/sd.md)\n- [Authentication and billing onboarding](references/onboarding.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell command examples; scripts return JSON responses and save response files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Query results include entity metadata, pagination summaries, and saved response-file paths when output is large.]\n\n## Skill Version(s):\n\n1.0.5 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.4: 70 files, 101801 bytes\n\nFiles: references/api.md (3195b), references/api/sb.md (4135b), references/api/sd.md (7740b), references/api/sp.md (5274b), scripts/_common.py (30476b), scripts/check_auth_dependency.py (6567b), scripts/sb/create_ad_groups.py (1740b), scripts/sb/create_ads.py (2379b), scripts/sb/create_budget_rules.py (1734b), scripts/sb/create_campaigns.py (1744b), scripts/sb/list_ad_groups.py (3007b), scripts/sb/list_ads.py (3076b), scripts/sb/list_budget_rules.py (2766b), scripts/sb/list_campaigns.py (3074b), scripts/sb/update_ad_groups.py (1754b), scripts/sb/update_ads.py (1711b), scripts/sb/update_budget_rules.py (1747b), scripts/sb/update_campaigns.py (1759b), scripts/sd/create_ad_groups.py (1696b), scripts/sd/create_budget_rules.py (1734b), scripts/sd/create_campaigns.py (1698b), scripts/sd/create_creatives.py (1742b), scripts/sd/create_negative_targets.py (1731b), scripts/sd/create_product_ads.py (1706b), scripts/sd/create_targets.py (1688b), scripts/sd/list_ad_groups.py (3091b), scripts/sd/list_budget_rules.py (2766b), scripts/sd/list_campaigns.py (3476b), scripts/sd/list_creatives.py (3280b), scripts/sd/list_negative_targets.py (3368b), scripts/sd/list_product_ads.py (5026b), scripts/sd/list_targets.py (3460b), scripts/sd/update_ad_groups.py (1710b), scripts/sd/update_budget_rules.py (1747b), scripts/sd/update_campaigns.py (1713b), scripts/sd/update_creatives.py (1715b), scripts/sd/update_negative_targets.py (1744b), scripts/sd/update_product_ads.py (1715b), scripts/sd/update_targets.py (1707b), scripts/sp/create_ad_groups.py (1726b), scripts/sp/create_budget_rules_association.py (1828b), scripts/sp/create_budget_rules.py (1800b), scripts/sp/create_campaign_negative_keywords.py (1841b), scripts/sp/create_campaign_negative_targets.py (1852b), scripts/sp/create_campaigns.py (1730b), scripts/sp/create_keywords.py (1723b), scripts/sp/create_negative_keywords.py (1782b), scripts/sp/create_negative_targets.py (1793b), scripts/sp/create_product_ads.py (1740b), scripts/sp/create_targets.py (1734b), scripts/sp/list_ad_groups.py (2926b), scripts/sp/list_budget_rules.py (2766b), scripts/sp/list_campaigns.py (2911b), scripts/sp/list_keywords.py (3131b), scripts/sp/list_negative_keywords.py (3029b), scripts/sp/list_product_ads.py (5110b), scripts/sp/list_targets.py (2933b), scripts/sp/update_ad_groups.py (1740b), scripts/sp/update_budget_rules.py (1753b), scripts/sp/update_campaign_negative_keywords.py (1855b), scripts/sp/update_campaign_negative_targets.py (1865b), scripts/sp/update_campaigns.py (1745b), scripts/sp/update_keywords.py (1743b), scripts/sp/update_negative_keywords.py (1796b), scripts/sp/update_negative_targets.py (1806b), scripts/sp/update_product_ads.py (1749b), scripts/sp/update_targets.py (1753b), skill-card.md (2866b), SKILL.md (17202b), _meta.json (145b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: linkfox-amazon-ads-manager\ndescription: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 三个产品线的广告查询（list）与创建/修改（create/update）操作。查询覆盖 Sponsored Products (SP) 的广告活动/广告组/关键词/否定关键词/商品广告/定向 6 个 list、Sponsored Brands (SB v4) 的广告活动/广告组/广告 3 个 list，以及 Sponsored Display (SD v3) 的广告活动/广告组/商品广告/定向/否定定向/创意 6 个 list；写操作覆盖全部 create/update（含出价调整、预算修改、状态变更、Budget Rules）。当用户提到查询、创建、修改、调价亚马逊广告时触发。本技能依赖 linkfox-amazon-ads-auth。Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n---\n\n# Amazon Ads 广告管理\n\nAmazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作，自动处理 token、分页、过滤字段规范化。\n\n| 广告产品 | 覆盖实体 | 脚本子目录 | 详细参数 |\n|---------|---------|-----------|---------|\n| **SP** (Sponsored Products) v3 | campaigns / adGroups / keywords / negativeKeywords / productAds / targets | `scripts/sp/` | [references/api/sp.md](./references/api/sp.md) |\n| **SB** (Sponsored Brands) v4 | campaigns / adGroups / ads | `scripts/sb/` | [references/api/sb.md](./references/api/sb.md) |\n| **SD** (Sponsored Display) v3 | campaigns / adGroups / productAds / targets / negativeTargets / creatives | `scripts/sd/` | [references/api/sd.md](./references/api/sd.md) |\n\n**依赖 `linkfox-amazon-ads-auth`**（脚本启动时自动检查；未安装时 exit 42，stderr 打 `DEPENDENCY_MISSING`）。\n\n### ⚠️ 多账号场景：调用前必须解析好 profileId\n\n用户经常只说自然语言（\"美国站\"、\"日本站\"、\"我的店铺\"），本 skill 的所有脚本都必须拿到数字 `profileId` 才能调。按下列顺序处理，**不要跳过**：\n\n1. 先调 `linkfox-amazon-ads-auth` 的 `authorized_stores.py` 拉出用户已授权的账号 × 站点清单。\n2. 根据用户提到的站点（映射到 `countryCode`，如 美国→`US`）匹配候选 profile：\n - **只有 1 个候选** → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。\n - **≥ 2 个候选（同站点下多个授权账号）** → **必须向用户澄清**，用 `accountName` 问：\"你在美国站授权了 A 和 B 两个账号，这次用哪个？\"\n - **0 个候选** → 告知用户该站点未授权，引导去 `linkfox-amazon-ads-auth` 做授权。\n3. **严禁**让用户直接报 profileId 数字。\n4. **严禁**在歧义下\"挑第一个\"或\"选默认\"绕过澄清。\n\n完整决策表见 `linkfox-amazon-ads-auth` SKILL.md 的 **Usage Scenarios 第 4 节**。\n\n## Core Concepts\n\n- **自动分页**：`fetchAll=true`（默认）跟随分页 token 到结束或 `maxPages=50` 兜底（约 5000 条，超出标 `truncated=true`）；SP / SB 用 `nextToken`，SD 用 `startIndex + count` 偏移分页\n- **过滤器结构不统一**：不同字段需要不同写法（详见下方\"过滤器结构速查\"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入\n- **只给 metadata，不含指标**：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 `linkfox-amazon-ads-report`，按 id join\n- **支持 create / update**：各模块下 `create_*.py` / `update_*.py` 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式\n- **SB 和 SP 的差异**：SB 只有 campaigns/adGroups/ads 三个 list；其 keywords/targets 官方未提供 list all\n- **SD 接口形态**：Sponsored Display 是 v3 REST endpoint，`GET /sd/` + querystring，分页用 `startIndex + count`；state / id 类过滤为逗号分隔字符串；`includeExtendedDataFields:true` 时请求 `/sd//extended` 路径。所有过滤字段统一支持 `{\"include\":[...]}` 入参\n\n## 可用脚本\n\n### SP（28 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sp/list_campaigns.py` | 广告活动 | 查询 |\n| `sp/create_campaigns.py` | 广告活动 | 创建 |\n| `sp/update_campaigns.py` | 广告活动 | 修改（预算/策略/状态/名称等） |\n| `sp/list_ad_groups.py` | 广告组 | 查询 |\n| `sp/create_ad_groups.py` | 广告组 | 创建 |\n| `sp/update_ad_groups.py` | 广告组 | 修改（默认出价/状态/名称等） |\n| `sp/list_keywords.py` | 关键词 | 查询 |\n| `sp/create_keywords.py` | 关键词 | 创建 |\n| `sp/update_keywords.py` | 关键词 | 修改（出价/状态等） |\n| `sp/list_negative_keywords.py` | 否定关键词 | 查询 |\n| `sp/create_negative_keywords.py` | 否定关键词 | 创建 |\n| `sp/update_negative_keywords.py` | 否定关键词 | 修改（状态等） |\n| `sp/list_product_ads.py` | 商品广告 | 查询 |\n| `sp/create_product_ads.py` | 商品广告 | 创建 |\n| `sp/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sp/list_targets.py` | 商品定向 | 查询 |\n| `sp/create_targets.py` | 商品定向 | 创建 |\n| `sp/update_targets.py` | 商品定向 | 修改（出价/状态等） |\n| `sp/create_campaign_negative_keywords.py` | 活动级否定关键词 | 创建 |\n| `sp/update_campaign_negative_keywords.py` | 活动级否定关键词 | 修改（状态等） |\n| `sp/create_campaign_negative_targets.py` | 活动级否定定向 | 创建 |\n| `sp/update_campaign_negative_targets.py` | 活动级否定定向 | 修改（状态等） |\n| `sp/create_negative_targets.py` | 广告组级否定定向 | 创建 |\n| `sp/update_negative_targets.py` | 广告组级否定定向 | 修改（状态等） |\n| `sp/list_budget_rules.py` | 预算规则 | 查询 |\n| `sp/create_budget_rules.py` | 预算规则 | 创建 |\n| `sp/update_budget_rules.py` | 预算规则 | 修改 |\n| `sp/create_budget_rules_association.py` | 预算规则关联 | 关联规则到活动 |\n\n### SB（12 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sb/list_campaigns.py` | 广告活动 | 查询 |\n| `sb/create_campaigns.py` | 广告活动 | 创建 |\n| `sb/update_campaigns.py` | 广告活动 | 修改（预算/状态/名称等） |\n| `sb/list_ad_groups.py` | 广告组 | 查询 |\n| `sb/create_ad_groups.py` | 广告组 | 创建 |\n| `sb/update_ad_groups.py` | 广告组 | 修改（出价/状态等） |\n| `sb/list_ads.py` | 广告创意 | 查询 |\n| `sb/create_ads.py` | 广告创意 | 创建（按 adType 选路径） |\n| `sb/update_ads.py` | 广告创意 | 修改（出价/状态/创意等） |\n| `sb/list_budget_rules.py` | 预算规则 | 查询 |\n| `sb/create_budget_rules.py` | 预算规则 | 创建 |\n| `sb/update_budget_rules.py` | 预算规则 | 修改 |\n\n### SD（21 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sd/list_campaigns.py` | 广告活动 | 查询 |\n| `sd/create_campaigns.py` | 广告活动 | 创建 |\n| `sd/update_campaigns.py` | 广告活动 | 修改（预算/状态/名称等） |\n| `sd/list_ad_groups.py` | 广告组 | 查询 |\n| `sd/create_ad_groups.py` | 广告组 | 创建 |\n| `sd/update_ad_groups.py` | 广告组 | 修改（出价/状态等） |\n| `sd/list_product_ads.py` | 商品广告 | 查询 |\n| `sd/create_product_ads.py` | 商品广告 | 创建 |\n| `sd/update_product_ads.py` | 商品广告 | 修改（状态等） |\n| `sd/list_targets.py` | 定向子句 | 查询 |\n| `sd/create_targets.py` | 定向子句 | 创建 |\n| `sd/update_targets.py` | 定向子句 | 修改（出价/状态等） |\n| `sd/list_negative_targets.py` | 否定定向子句 | 查询 |\n| `sd/create_negative_targets.py` | 否定定向子句 | 创建 |\n| `sd/update_negative_targets.py` | 否定定向子句 | 修改（状态等） |\n| `sd/list_creatives.py` | 创意素材 | 查询 |\n| `sd/create_creatives.py` | 创意素材 | 创建 |\n| `sd/update_creatives.py` | 创意素材 | 修改（素材/状态等） |\n| `sd/list_budget_rules.py` | 预算规则 | 查询 |\n| `sd/create_budget_rules.py` | 预算规则 | 创建 |\n| `sd/update_budget_rules.py` | 预算规则 | 修改 |\n详细过滤器、枚举值、返回字段见 [references/api/sp.md](./references/api/sp.md) / [references/api/sb.md](./references/api/sb.md) / [references/api/sd.md](./references/api/sd.md)。\n\n## 调用方式\n\n- **API 端点**：`POST /amazonAds/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-ads-manager-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用skill内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\n - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。如需用户授权才可下载，要询问用户获得授权，你不能自己放弃下载。\n- 兜底措施：仅当前面两个措施经过所有努力都走不通时，才提示用户依据 https://skill.linkfox.com/linkfoxskills/guide.htm 指引获取API Key，或去 https://os.linkfox.com/ 补充积分。\n\n## Financial Safety Guidance\n\n创建和更新操作可能直接影响广告花费，立即生效且无法撤回。\n\n**决策规则：**\n\n| 用户状态 | Agent 行为 |\n|----------|-----------|\n| 已授权（说过\"自动调价\"/\"按你判断来\"/\"不用问我\"/\"确认\"等） | 直接执行 → 输出操作回执 |\n| 未授权（首次交互、未明确表态） | 先输出确认摘要 → 等用户确认后执行 |\n\n**确认摘要模板**（未授权时，执行前输出）：\n```\n📋 即将执行：\n- 操作：[创建/修改] [N 个] [实体类型]\n- 变更：[关键字段变化，如 bid $1.0→$1.5 / budget $50→$100]\n- 影响：[花费变化预估，引用日预算作为上限]\n确认执行？后续如需自动处理，告诉我即可。\n```\n\n**操作回执模板**（每次写操作执行后必须输出）：\n```\n✅ 已执行：[简短描述]\n- 范围：[实体数量、名称或 ID]\n- 变化：[具体变更内容]\n- 结果：[成功 N 个 / 失败 M 个]\n```\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `profileId` | number | 必填，从 ads-auth 获取 |\n| `region` | string | 必填，`NA` / `EU` / `FE` |\n| `fetchAll` | bool | 默认 `true`；SP / SB 用 `nextToken`，SD 用 `startIndex + count` 偏移分页 |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count` |\n| `includeExtendedDataFields` | bool | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 本地化（SP keywords 支持） |\n\n## 过滤器结构速查（最易错）\n\n| 结构 | 示例 | 适用字段 |\n|------|------|----------|\n| **Object** | `{\"include\":[...]}` / `{\"exclude\":[...]}` | 全部 id/状态类：campaignIdFilter、adGroupIdFilter、keywordIdFilter、stateFilter、portfolioIdFilter、expressionTypeFilter、adIdFilter |\n| **Array** | `[\"EXACT\",\"BROAD\"]` | matchTypeFilter（SP keywords/negativeKeywords） |\n| **Scalar** | `\"AUTO\"` | campaignTargetingTypeFilter（SP adGroups） |\n| **Text** | `{\"queryTermMatchType\":\"BROAD_MATCH\",\"include\":[\"...\"]}` | nameFilter、keywordTextFilter |\n| **Client** | 任意形式，本 skill 本地过滤 | asinFilter、skuFilter（SP productAds） |\n\n**易错点**：\n- SP `matchTypeFilter` 是**裸数组** `[\"EXACT\"]`（传错本 skill 自动规范化）\n- `expressionTypeFilter` 反而是 **Object**（与 matchType 不同）\n- `asinFilter` / `skuFilter` 客户端过滤，建议同时传 `campaignIdFilter` / `adGroupIdFilter` 收窄\n\n## 响应格式\n\n```json\n{\n \"success\": true,\n \"\": [ /* 实体数组，字段原样 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\nSP productAds 客户端过滤时额外带：`serverTotalBeforeClientFilter` + `clientSideFilters`。\n\n## 使用示例\n\n### 1. 列活跃 SP 广告活动\n```bash\npython scripts/sp/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 2. 看某 SP campaign 下的广告组\n```bash\npython scripts/sp/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 3. 按 ASIN 反查 SP 投放（客户端过滤）\n```bash\npython scripts/sp/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 4. 列 SB 广告活动\n```bash\npython scripts/sb/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 5. 列某 SB campaign 下的 adGroups / ads\n```bash\npython scripts/sb/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\npython scripts/sb/list_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n### 6. 列活跃 SD 广告活动\n```bash\npython scripts/sd/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'\n```\n\n### 7. 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\n```bash\npython scripts/sd/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'\n```\n\n### 8. 与 report 配合分析指标\n本 skill 返回实体**元数据**（id、名称、状态、匹配类型等）；指标（曝光、点击、花费、转化）交给 `linkfox-amazon-ads-report`（`reportTypeId: \"spTargeting\"` / `\"sbCampaigns\"` / `\"sdCampaigns\"` 等），按 id join。\n\n## 调用原则\n\n- 返回字段原样保留；不改名、不翻译、不补算派生指标\n- 非 2xx 不自动重试；保留 `httpStatus` + `body` 告知用户\n- `truncated=true` 时明确提示数据未取完\n\n## 常见错误\n\n| 状态 | 含义 | 建议 |\n|------|------|------|\n| `HTTP 401` | accessToken 过期 | 调 ads-auth 的 `refresh_token.py` 后重试 |\n| `HTTP 403` | profileId 无权限 | 核对 profileId 归属 |\n| `HTTP 400` | 入参结构错 | 先核对\"过滤器结构速查\"表 |\n| `HTTP 429` | 限流 | 等 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n## Not Applicable\n\n- 删除 / 归档 → 本 skill 不支持 DELETE（可通过 update state 为 ARCHIVED 实现归档，但归档不可逆）\n- SB 的 keywords / negativeKeywords / targets / negativeTargets 的 list all → **Amazon 官方未提供**，需按 id 单查（不在本 skill）\n- SD 的按 id 单查 / brandSafety / recommendations / forecasts / optimizationRules / locations 等\"非基础实体\"接口 → 不在本 skill\n- DSP / ST 实体 → 不在本 skill\n- 指标报表 → `linkfox-amazon-ads-report`\n- 授权 / token / profile → `linkfox-amazon-ads-auth`\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback:**\n\nAuto-detect and report feedback via the Feedback API when any of the following apply:\n1. The functionality or purpose described in this skill does not match actual behavior\n2. The skill's results do not match the user's intent\n3. The user expresses dissatisfaction or praise about this skill\n4. Anything you believe could be improved\n\nCall the feedback API as specified in `references/api.md`. Do not interrupt the user's flow.\n\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.0.4:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-ads-manager\",\n \"version\": \"1.0.4\",\n \"publishedAt\": 1783944119042\n}\n\nFile v1.0.4:references/api.md\n\n# linkfox-amazon-ads-manager — 参数与字段参考（总览）\n\n按 Amazon Ads 广告产品分类维护。\n\n| 广告产品 | 脚本子目录 | 查询参考 |\n|---------|-----------|---------|\n| **Sponsored Products (SP)** — v3 | `scripts/sp/` | [api/sp.md](./api/sp.md) |\n| **Sponsored Brands (SB)** — v4 | `scripts/sb/` | [api/sb.md](./api/sb.md) |\n| **Sponsored Display (SD)** — v3 | `scripts/sd/` | [api/sd.md](./api/sd.md) |\n\n> Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n\n## 通用约定\n\n- 每个脚本接受一个 JSON 字符串作为唯一位置参数\n- 鉴权：环境变量 `LINKFOX_AGENT_API_KEY`（或旧名 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- API 网关地址：环境变量 `LINKFOX_TOOL_GATEWAY`（默认 `https://tool-gateway.linkfox.com`）\n- 依赖 `linkfox-amazon-ads-auth`（脚本启动自动检查；缺失时 exit 42，stderr 打 `DEPENDENCY_MISSING`）\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| `profileId` | number | ✅ | — | 从 ads-auth 获取 |\n| `region` | string | ✅ | — | `NA` / `EU` / `FE` |\n| `fetchAll` | boolean | 否 | `true` | 自动翻页（SP / SB 跟 `nextToken`，SD 用 `startIndex + count`） |\n| `maxResults` | integer | 否 | `100` | 单页 1-100；超限上游可能静默 clamp；对应 SD 端 `count` |\n| `skipDepCheck` | boolean | 否 | `false` | 跳过依赖检查 |\n| `includeExtendedDataFields` | boolean | 否 | — | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 否 | — | 本地化（keywords 支持） |\n\n## 输出格式\n\n```json\n{\n \"success\": true,\n \"\": [ /* 实体数组 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\n客户端过滤时（SP productAds 的 asinFilter/skuFilter）额外带 `serverTotalBeforeClientFilter` + `clientSideFilters`。\n\n失败：\n```json\n{\n \"error\": \"Upstream HTTP 401\",\n \"httpStatus\": 401,\n \"body\": \"...\",\n \"pagesFetched\": 0\n}\n```\n\n## 通用错误码\n\n| httpStatus / exit | 含义 | 建议 |\n|-------------------|------|------|\n| 200 | 成功 | — |\n| 400 | 入参结构错 | 核对对应 adProduct 的过滤器结构（api/sp.md / api/sb.md / api/sd.md） |\n| 401 | accessToken 过期 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 402 | 积分或余额不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 403 | profileId 无权限 | 核对 profileId 归属 |\n| 429 | 限流 | 间隔 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n---\n\n## Feedback API\n\n与上面的工具 API **base URL 不同**：\n\n```bash\ncurl -X POST https://skill-api.linkfox.com/api/v1/public/feedback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"skillName\":\"linkfox-amazon-ads-manager\",\"sentiment\":\"POSITIVE\",\n \"category\":\"OTHER\",\"content\":\"实体查询结果与预期一致\"}'\n```\n\n- `sentiment`: `POSITIVE` / `NEUTRAL` / `NEGATIVE`\n- `category`: `BUG` / `COMPLAINT` / `SUGGESTION` / `OTHER`\n\nFile v1.0.4:references/api/sb.md\n\n# Sponsored Brands (SB) 实体查询 — 参数与字段参考\n\n覆盖 SB v4 的 3 个 list 端点。通用约定、共用参数、错误码见 `../api.md`。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sb/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sb/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sb/list_ads.py` | 广告创意 | `ads` |\n\n> **注意**：SB v4 仅提供 campaigns/adGroups/ads 三个 list。SB 的 keywords/negativeKeywords/targets/negativeTargets 是 v3 REST 风格（`GET /sb/xxx/{id}` 按 id 单查 / `POST /sb/xxx` 创建），**Amazon 官方没有提供\"list all\"端点**，本 skill 也不提供。\n\n## 响应额外字段\n\nSB v4 响应除 ``、`nextToken` 之外，还会带 `totalCount`：\n\n```json\n{\n \"campaigns\": [ ... ],\n \"totalCount\": 42,\n \"nextToken\": \"...\"\n}\n```\n\n本 skill 输出会自动汇总所有分页 items，`total` 字段是**最终**条数。\n\n## 过滤器结构\n\nSB v4 的 filter 体系与 SP v3 **基本一致**（复用 skill 的结构化规范）：\n\n### Object —— `{\"include\":[...]}` / `{\"exclude\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` / `portfolioIdFilter` / `stateFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\": {\"include\": [\"1122334455\"]}}\n```\n\n### Text —— `{\"queryTermMatchType\":\"...\",\"include\":[...]}`\n\n适用：`nameFilter`（campaigns / adGroups）\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\": \"BROAD_MATCH\", \"include\": [\"holiday\"]}}\n```\n\n`queryTermMatchType`: `BROAD_MATCH` / `EXACT_MATCH`。\n\n### 其他入参\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `includeExtendedDataFields` | boolean | 返回扩展字段（策略、时间戳等） |\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED` | 全部 3 个实体 |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter` |\n| `list_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n\n## 常见实体字段\n\n| 实体 | 字段 |\n|------|------|\n| campaigns | `campaignId` / `name` / `state` / `portfolioId` / `budget.{budget,budgetType}` / `brandEntityId` / `brandName` / `startDate` / `endDate` / `bidding` 等 |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `bidOptimization` 等 |\n| ads | `adId` / `adGroupId` / `campaignId` / `state` / `creativeType`（`PRODUCT_COLLECTION` / `VIDEO` / `BRAND_VIDEO` / `STORE_SPOTLIGHT` 等）/ 对应类型的创意字段 |\n\n> SB v4 的 ads 列表返回各种创意类型的元数据；若需读取创意细节，Amazon 另提供 `/sb/ads/creatives/*` 端点（本 skill 暂未覆盖）。\n\n## 调用示例\n\n```bash\n# 列活跃 SB campaigns\npython sb/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 adGroups（带名称模糊匹配）\npython sb/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"nameFilter\":{\"queryTermMatchType\":\"BROAD_MATCH\",\"include\":[\"spring\"]}}'\n\n# 列某 adGroup 下的 ads\npython sb/list_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n## 与 SP 的差异速查\n\n| 维度 | SP v3 | SB v4 |\n|------|-------|-------|\n| 路径前缀 | `sp/` | `sb/v4/` |\n| Content-Type | `application/vnd.sp.v3+json`（Amazon 严格要求小写 vendor MIME） | `application/vnd.sbresource.v4+json`（全小写；响应 MIME） |\n| 实体数量 | 6 个 list | 3 个 list（keywords/targets 等 v3 未提供 list） |\n| 过滤器 | Object / Array / Scalar / Text / Client 5 类 | 主要 Object + Text；暂未见到 Array/Scalar 需求 |\n| 响应分页 | `nextToken` | `nextToken` + `totalCount`（SB 特有） |\n| 客户端过滤 | `asinFilter` / `skuFilter`（productAds） | 暂无 |\n\nFile v1.0.4:references/api/sd.md\n\n# Sponsored Display (SD) 实体查询 — 参数与字段参考\n\n覆盖 SD v3 的 6 个 list 端点的查询参数与字段定义。通用约定、共用参数、错误码见 `../api.md`；写操作（create/update）通过 `scripts/sd/create_*.py` 与 `scripts/sd/update_*.py` 调用，payload 透传 Amazon 原生格式。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sd/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sd/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sd/list_product_ads.py` | 商品广告 | `productAds` |\n| `sd/list_targets.py` | 定向子句（商品/受众） | `targetingClauses` |\n| `sd/list_negative_targets.py` | 否定定向子句 | `negativeTargetingClauses` |\n| `sd/list_creatives.py` | 创意素材 | `creatives` |\n\n> **注意**：Sponsored Display **没有 keywords**（仅商品 / 受众 / 品类定向）。按 id 单查、创建、删除、归档，以及 brandSafety / forecasts / budgetRules / optimizationRules / locations 等\"非基础实体查询\"接口本技能不覆盖。\n\n## SD 接口形态\n\n| 维度 | Sponsored Display v3 |\n|------|----------------------|\n| HTTP 方法 | `GET` |\n| 参数位置 | querystring |\n| 分页方式 | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 逗号分隔小写串，如 `enabled,paused,archived` |\n| id 类过滤实参 | 逗号分隔字符串，如 `\"123,456\"` |\n| 扩展字段 | 通过路径区分：基础 `/sd/`，扩展 `/sd//extended` |\n| Content-Type | `application/json` |\n\n所有过滤字段对外统一接受 `{\"include\":[...]}`、裸数组、单值字符串三种宽容形态；脚本会将其序列化为 Sponsored Display 端所需的 querystring 参数。\n\n## 过滤器结构\n\n### Object —— `{\"include\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` / `targetIdFilter` / `portfolioIdFilter` / `creativeIdFilter` / `stateFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\":{\"include\": [\"1122334455\", \"6677889900\"]}}\n```\n\n兼容写法（自动归一）：\n- 裸数组 `[\"ENABLED\"]` → `{\"include\":[\"ENABLED\"]}`\n- 裸字符串 `\"ENABLED\"` → `{\"include\":[\"ENABLED\"]}`\n\n### Text —— `nameFilter`\n\nSponsored Display **仅支持精确匹配**，没有 `BROAD_MATCH`：\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\":\"EXACT_MATCH\",\"include\":[\"holiday\"]}}\n```\n\n传 `BROAD_MATCH` 时脚本会在 stderr 输出一次提示，并按 `include[0]` 作 `name` 精确匹配。\n\n### Client-side filter —— `asinFilter` / `skuFilter`（仅 productAds）\n\nSponsored Display 的 `/sd/productAds` 接口不支持按 ASIN / SKU 过滤；脚本会先按其他过滤条件拉取 productAds，再在本地按精确值匹配。建议同时传 `campaignIdFilter` 或 `adGroupIdFilter` 收窄上游拉取范围，否则 stderr 会输出性能提示。\n\n```json\n{\"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}\n```\n\n## 其他入参\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `fetchAll` | bool | 默认 `true`，关闭后只拉第一页 |\n| `maxResults` | int | 1-100，默认 100；对应 Sponsored Display 端 `count`（每页大小） |\n| `includeExtendedDataFields` | bool | 默认 `false`；`true` 时请求 `/sd//extended` 路径；**`creatives` 没有 extended 路径，此入参无效** |\n| `skipDepCheck` | bool | 跳过 ads-auth 依赖检查 |\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED`（脚本提交上游时自动转为 `enabled` / `paused` / `archived`） | 全部 6 个实体 |\n| `expressionType` | `auto` / `manual` | targets |\n| `creativeType` | （Sponsored Display 各 creative 类型，由上游返回原值） | creatives |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter` |\n| `list_product_ads.py` | `adIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`asinFilter`（Client）、`skuFilter`（Client） |\n| `list_targets.py` | `targetIdFilter`、`adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_negative_targets.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter` |\n| `list_creatives.py` | `creativeIdFilter`、`adGroupIdFilter`（互斥，同时传时上游会按 400 / 422 返回） |\n\n## 常见实体字段\n\n| 实体 | 字段（节选；extended 路径返回更多） |\n|------|---------|\n| campaigns | `campaignId` / `name` / `state` / `tactic`（`T00020` / `T00030`）/ `costType`（`cpc` / `vcpm`）/ `budget` / `budgetType` / `startDate` / `endDate` / `portfolioId` |\n| adGroups | `adGroupId` / `campaignId` / `name` / `state` / `defaultBid` / `bidOptimization` / `creativeType` |\n| productAds | `adId` / `adGroupId` / `campaignId` / `state` / `asin` / `sku` / `landingPageURL` / `landingPageType` |\n| targetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expressionType`（auto / manual）/ `expression`（type ∈ `asinSameAs` / `asinCategorySameAs` / `audience` / `views` / `purchases` ...） / `bid` |\n| negativeTargetingClauses | `targetId` / `adGroupId` / `campaignId` / `state` / `expression`（与 targets 类似，type 仅限 `asinSameAs` / `asinBrandSameAs`） |\n| creatives | `creativeId` / `adGroupId` / `name` / `creativeType` / `properties`（headline / brandLogoAssetID / video 等，按 creativeType 不同） / `moderationStatus` |\n\n## 调用示例\n\n```bash\n# 列活跃 SD campaigns\npython sd/list_campaigns.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]},\"maxResults\":50}'\n\n# 按 campaign 列 SD adGroups（含扩展字段，请求 /sd/adGroups/extended）\npython sd/list_ad_groups.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]},\n \"includeExtendedDataFields\":true}'\n\n# 按 ASIN 反查 SD 投放（client-side 过滤，带 campaign 收窄）\npython sd/list_product_ads.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"1122334455\"]}}'\n\n# 列某 adGroup 下的定向子句\npython sd/list_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的否定定向\npython sd/list_negative_targets.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n\n# 列某 adGroup 下的创意\npython sd/list_creatives.py '{\"profileId\":1111111111,\"region\":\"NA\",\n \"adGroupIdFilter\":{\"include\":[\"5566778899\"]}}'\n```\n\n## 与 SP / SB 的差异速查\n\n供从 Sponsored Products / Sponsored Brands 迁移到 Sponsored Display 的开发者对照查阅。\n\n| 维度 | SP v3 | SB v4 | SD v3 |\n|------|-------|-------|-------|\n| 路径前缀 | `sp/` | `sb/v4/` | `sd/`（+ `/extended` 子路径） |\n| HTTP 方法 | POST list | POST list | GET |\n| Content-Type | `application/vnd.sp.v3+json` | `application/vnd.sbresource.v4+json` | `application/json` |\n| 实体数量 | 6 个 list | 3 个 list | 6 个 list（含 creatives；不含 keywords） |\n| 分页 | `nextToken` | `nextToken` + `totalCount` | `startIndex` + `count`（偏移分页） |\n| `stateFilter` 实参 | 大写 ENUM | 大写 ENUM | 接口端要求小写串，脚本会自动转换 |\n| 扩展字段 | `includeExtendedDataFields:true` 标志 | `includeExtendedDataFields:true` 标志 | 路径切换 `/sd//extended` |\n| Client-side filter | `asinFilter` / `skuFilter`（productAds） | 暂无 | `asinFilter` / `skuFilter`（productAds） |\n\nFile v1.0.4:references/api/sp.md\n\n# Sponsored Products (SP) 实体查询 — 参数与字段参考\n\n覆盖 6 个 SP v3 list 端点。通用约定、共用参数、错误码见 `../api.md`。\n\n## 可用脚本\n\n| 脚本 | 业务实体 | 返回 key |\n|------|---------|---------|\n| `sp/list_campaigns.py` | 广告活动 | `campaigns` |\n| `sp/list_ad_groups.py` | 广告组 | `adGroups` |\n| `sp/list_keywords.py` | 关键词 | `keywords` |\n| `sp/list_negative_keywords.py` | 否定关键词 | `negativeKeywords` |\n| `sp/list_product_ads.py` | 商品广告 | `productAds` |\n| `sp/list_targets.py` | 商品定向 | `targetingClauses`（不是 `targets`）|\n\n## 过滤器结构（5 类）\n\n### 1. Object —— `{\"include\":[...]}` / `{\"exclude\":[...]}`\n\n适用：`campaignIdFilter` / `adGroupIdFilter` / `keywordIdFilter` / `targetIdFilter` / `adIdFilter` / `negativeKeywordIdFilter` / `portfolioIdFilter` / `stateFilter` / `expressionTypeFilter`\n\n```json\n{\"stateFilter\": {\"include\": [\"ENABLED\",\"PAUSED\"]}}\n{\"campaignIdFilter\": {\"include\": [\"1122334455\"]}}\n{\"expressionTypeFilter\": {\"include\": [\"AUTO\"]}}\n```\n\n### 2. Array —— 裸数组 `[\"EXACT\",\"BROAD\"]`\n\n适用：`matchTypeFilter`（keywords / negativeKeywords）\n\n```json\n{\"matchTypeFilter\": [\"EXACT\",\"PHRASE\"]}\n```\n\n兼容：传 `{\"include\":[\"EXACT\"]}` 本 skill 自动解包。\n\n### 3. Scalar —— 裸字符串 `\"AUTO\"`\n\n适用：`campaignTargetingTypeFilter`（adGroups）\n\n```json\n{\"campaignTargetingTypeFilter\": \"AUTO\"}\n```\n\n### 4. Text —— `{\"queryTermMatchType\":\"...\",\"include\":[...]}`\n\n适用：`nameFilter`（campaigns / adGroups）、`keywordTextFilter`（keywords / negativeKeywords）\n\n```json\n{\"nameFilter\": {\"queryTermMatchType\": \"BROAD_MATCH\", \"include\": [\"holiday\"]}}\n```\n\n`queryTermMatchType`: `BROAD_MATCH` / `EXACT_MATCH`。\n\n### 5. Client —— 本 skill 在本地过滤\n\n适用：`asinFilter` / `skuFilter`（productAds）\n\n```json\n{\"asinFilter\": {\"include\": [\"B01ABCDEFG\"]}}\n{\"asinFilter\": [\"B01ABCDEFG\"]}\n{\"asinFilter\": \"B01ABCDEFG\"}\n```\n\nAmazon 原生 list 接口对这两个字段不生效，本 skill 拉取后本地精确匹配。建议同时传 `campaignIdFilter` / `adGroupIdFilter` / `adIdFilter` 收窄拉取量；否则触发全量拉取 + stderr 性能提示。\n\n输出会多出：`serverTotalBeforeClientFilter` / `clientSideFilters`。\n\n## 枚举值\n\n| 字段 | 值 | 适用 |\n|------|----|------|\n| `state` | `ENABLED` / `PAUSED` / `ARCHIVED` | 全部 6 个实体 |\n| `matchType` | `BROAD` / `PHRASE` / `EXACT` | keywords |\n| `matchType` | `NEGATIVE_EXACT` / `NEGATIVE_PHRASE` | negativeKeywords |\n| `expressionType` | `AUTO` / `MANUAL` | targets |\n| `campaignTargetingType` | `AUTO` / `MANUAL` | adGroups |\n| `queryTermMatchType` | `BROAD_MATCH` / `EXACT_MATCH` | nameFilter / keywordTextFilter |\n\n## 每个脚本的过滤器\n\n| 脚本 | 可用过滤器 |\n|------|-----------|\n| `list_campaigns.py` | `campaignIdFilter`、`stateFilter`、`nameFilter`、`portfolioIdFilter` |\n| `list_ad_groups.py` | `adGroupIdFilter`、`campaignIdFilter`、`stateFilter`、`nameFilter`、`campaignTargetingTypeFilter` |\n| `list_keywords.py` | `keywordIdFilter`、`adGroupIdFilter\n\nArchive v1.0.3: 70 files, 101130 bytes\n\nFiles: references/api.md (2982b), references/api/sb.md (4135b), references/api/sd.md (7740b), references/api/sp.md (5274b), scripts/_common.py (30425b), scripts/check_auth_dependency.py (6567b), scripts/sb/create_ad_groups.py (1740b), scripts/sb/create_ads.py (2379b), scripts/sb/create_budget_rules.py (1734b), scripts/sb/create_campaigns.py (1744b), scripts/sb/list_ad_groups.py (3007b), scripts/sb/list_ads.py (3076b), scripts/sb/list_budget_rules.py (2766b), scripts/sb/list_campaigns.py (3074b), scripts/sb/update_ad_groups.py (1754b), scripts/sb/update_ads.py (1711b), scripts/sb/update_budget_rules.py (1747b), scripts/sb/update_campaigns.py (1759b), scripts/sd/create_ad_groups.py (1696b), scripts/sd/create_budget_rules.py (1734b), scripts/sd/create_campaigns.py (1698b), scripts/sd/create_creatives.py (1742b), scripts/sd/create_negative_targets.py (1731b), scripts/sd/create_product_ads.py (1706b), scripts/sd/create_targets.py (1688b), scripts/sd/list_ad_groups.py (3091b), scripts/sd/list_budget_rules.py (2766b), scripts/sd/list_campaigns.py (3476b), scripts/sd/list_creatives.py (3280b), scripts/sd/list_negative_targets.py (3368b), scripts/sd/list_product_ads.py (5026b), scripts/sd/list_targets.py (3460b), scripts/sd/update_ad_groups.py (1710b), scripts/sd/update_budget_rules.py (1747b), scripts/sd/update_campaigns.py (1713b), scripts/sd/update_creatives.py (1715b), scripts/sd/update_negative_targets.py (1744b), scripts/sd/update_product_ads.py (1715b), scripts/sd/update_targets.py (1707b), scripts/sp/create_ad_groups.py (1726b), scripts/sp/create_budget_rules_association.py (1828b), scripts/sp/create_budget_rules.py (1800b), scripts/sp/create_campaign_negative_keywords.py (1841b), scripts/sp/create_campaign_negative_targets.py (1852b), scripts/sp/create_campaigns.py (1730b), scripts/sp/create_keywords.py (1723b), scripts/sp/create_negative_keywords.py (1782b), scripts/sp/create_negative_targets.py (1793b), scripts/sp/create_product_ads.py (1740b), scripts/sp/create_targets.py (1734b), scripts/sp/list_ad_groups.py (2926b), scripts/sp/list_budget_rules.py (2766b), scripts/sp/list_campaigns.py (2911b), scripts/sp/list_keywords.py (3131b), scripts/sp/list_negative_keywords.py (3029b), scripts/sp/list_product_ads.py (5110b), scripts/sp/list_targets.py (2933b), scripts/sp/update_ad_groups.py (1740b), scripts/sp/update_budget_rules.py (1753b), scripts/sp/update_campaign_negative_keywords.py (1855b), scripts/sp/update_campaign_negative_targets.py (1865b), scripts/sp/update_campaigns.py (1745b), scripts/sp/update_keywords.py (1743b), scripts/sp/update_negative_keywords.py (1796b), scripts/sp/update_negative_targets.py (1806b), scripts/sp/update_product_ads.py (1749b), scripts/sp/update_targets.py (1753b), skill-card.md (2836b), SKILL.md (16356b), _meta.json (145b)\n\nArchive v1.0.2: 70 files, 101258 bytes\n\nFiles: references/api.md (2982b), references/api/sb.md (4135b), references/api/sd.md (7740b), references/api/sp.md (5274b), scripts/_common.py (30425b), scripts/check_auth_dependency.py (6567b), scripts/sb/create_ad_groups.py (1740b), scripts/sb/create_ads.py (2379b), scripts/sb/create_budget_rules.py (1734b), scripts/sb/create_campaigns.py (1744b), scripts/sb/list_ad_groups.py (3007b), scripts/sb/list_ads.py (3076b), scripts/sb/list_budget_rules.py (2766b), scripts/sb/list_campaigns.py (3074b), scripts/sb/update_ad_groups.py (1754b), scripts/sb/update_ads.py (1711b), scripts/sb/update_budget_rules.py (1747b), scripts/sb/update_campaigns.py (1759b), scripts/sd/create_ad_groups.py (1696b), scripts/sd/create_budget_rules.py (1734b), scripts/sd/create_campaigns.py (1698b), scripts/sd/create_creatives.py (1742b), scripts/sd/create_negative_targets.py (1731b), scripts/sd/create_product_ads.py (1706b), scripts/sd/create_targets.py (1688b), scripts/sd/list_ad_groups.py (3091b), scripts/sd/list_budget_rules.py (2766b), scripts/sd/list_campaigns.py (3476b), scripts/sd/list_creatives.py (3280b), scripts/sd/list_negative_targets.py (3368b), scripts/sd/list_product_ads.py (5026b), scripts/sd/list_targets.py (3460b), scripts/sd/update_ad_groups.py (1710b), scripts/sd/update_budget_rules.py (1747b), scripts/sd/update_campaigns.py (1713b), scripts/sd/update_creatives.py (1715b), scripts/sd/update_negative_targets.py (1744b), scripts/sd/update_product_ads.py (1715b), scripts/sd/update_targets.py (1707b), scripts/sp/create_ad_groups.py (1726b), scripts/sp/create_budget_rules_association.py (1828b), scripts/sp/create_budget_rules.py (1800b), scripts/sp/create_campaign_negative_keywords.py (1841b), scripts/sp/create_campaign_negative_targets.py (1852b), scripts/sp/create_campaigns.py (1730b), scripts/sp/create_keywords.py (1723b), scripts/sp/create_negative_keywords.py (1782b), scripts/sp/create_negative_targets.py (1793b), scripts/sp/create_product_ads.py (1740b), scripts/sp/create_targets.py (1734b), scripts/sp/list_ad_groups.py (2926b), scripts/sp/list_budget_rules.py (2766b), scripts/sp/list_campaigns.py (2911b), scripts/sp/list_keywords.py (3131b), scripts/sp/list_negative_keywords.py (3029b), scripts/sp/list_product_ads.py (5110b), scripts/sp/list_targets.py (2933b), scripts/sp/update_ad_groups.py (1740b), scripts/sp/update_budget_rules.py (1753b), scripts/sp/update_campaign_negative_keywords.py (1855b), scripts/sp/update_campaign_negative_targets.py (1865b), scripts/sp/update_campaigns.py (1745b), scripts/sp/update_keywords.py (1743b), scripts/sp/update_negative_keywords.py (1796b), scripts/sp/update_negative_targets.py (1806b), scripts/sp/update_product_ads.py (1749b), scripts/s...","readmeExcerpt":"Skill: 亚马逊-广告管理 Owner: linkfox-ai Summary: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。 Tags: latest:1.1.1 Version history: v1.1.0 |","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"📋 即将执行：\n- 操作：[创建/修改] [N 个] [实体类型]\n- 变更：[关键字段变化，如 bid $1.0→$1.5 / budget $50→$100]\n- 影响：[花费变化预估，引用日预算作为上限]\n确认执行？后续如需自动处理，告诉我即可。"},{"language":"text","snippet":"✅ 已执行：[简短描述]\n- 范围：[实体数量、名称或 ID]\n- 变化：[具体变更内容]\n- 结果：[成功 N 个 / 失败 M 个]"},{"language":"json","snippet":"{\n \"success\": true,\n \"apiVersion\": \"V3 | V4\",\n \"amazonResourceVersion\": \"V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED\",\n \"\": [ /* 实体数组，字段原样 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}"},{"language":"bash","snippet":"python scripts/sp/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"stateFilter\":{\"include\":[\"ENABLED\"]}}'"},{"language":"bash","snippet":"python scripts/sp/list_ad_groups.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'"},{"language":"bash","snippet":"python scripts/sp/list_product_ads.py '{\"profileId\":1234567890,\"region\":\"NA\",\n \"asinFilter\":{\"include\":[\"B01ABCDEFG\"]},\n \"campaignIdFilter\":{\"include\":[\"998877665544\"]}}'"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-amazon-ads-manager\ndescription: 亚马逊广告（Amazon Ads）管理技能，覆盖 SP/SB/SD 的查询与创建/修改。Sponsored Brands 同时支持 V3 Legacy 与 V4：新活动、多 Ad Group、Ad/Creative 默认走 V4，历史 Legacy 可显式走 V3，Keyword/Target 按 Campaign 结构通过版本化脚本调用 Amazon 共享 targeting 资源；禁止 V4 失败后自动回落 V3，禁止用 V3 静默截断多 Ad Group 数据。适用于查询、创建、调价、改预算、改状态及管理 SP/SB/SD 广告。本技能依赖 linkfox-amazon-ads-auth；不覆盖 Sponsored Television / DSP。\n---\n\n# Amazon Ads 广告管理\n\nAmazon Ads 广告管理 skill，支持 list（查询）和 create / update（创建与修改）操作；经 `developerProxy` 传 `profileId`，由服务端解析 token（勿先 `storeTokens` 取 raw token）。自动处理分页、过滤字段规范化。\n\n| 广告产品 | 覆盖实体 | 脚本子目录 | 详细参数 |\n|---------|---------|-----------|---------|\n| **SP** (Sponsored Products) v3 | campaigns / adGroups / keywords / negativeKeywords / productAds / targets | `scripts/sp/` | [references/api/sp.md](./references/api/sp.md) |\n| **SB** V3 Legacy + V4 | V3 campaigns/keywords/targets；V4 campaigns/adGroups/ads/keywords/targets/creatives | `scripts/sb/v3/`、`scripts/sb/v4/` | [references/api/sb.md](./references/api/sb.md) |\n| **SD** (Sponsored Display) v3 | campaigns / adGroups / productAds / targets / negativeTargets / creatives | `scripts/sd/` | [references/api/sd.md](./references/api/sd.md) |\n\n**依赖 `linkfox-amazon-ads-auth`**（脚本启动时自动检查；未安装时 exit 42，stderr 打 `DEPENDENCY_MISSING`）。\n\n### ⚠️ 多账号场景：调用前必须解析好 profileId\n\n用户经常只说自然语言（\"美国站\"、\"日本站\"、\"我的店铺\"），本 skill 的所有脚本都必须拿到数字 `profileId` 才能调。按下列顺序处理，**不要跳过**：\n\n1. 先调 `linkfox-amazon-ads-auth` 的 `authorized_stores.py` 拉出用户已授权的账号 × 站点清单。\n2. 根据用户提到的站点（映射到 `countryCode`，如 美国→`US`）匹配候选 profile：\n - **只有 1 个候选** → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。\n - **≥ 2 个候选（同站点下多个授权账号）** → **必须向用户澄清**，用 `accountName` 问：\"你在美国站授权了 A 和 B 两个账号，这次用哪个？\"\n - **0 个候选** → 告知用户该站点未授权，引导去 `linkfox-amazon-ads-auth` 做授权。\n3. **严禁**让用户直接报 profileId 数字。\n4. **严禁**在歧义下\"挑第一个\"或\"选默认\"绕过澄清。\n\n完整决策表见 `linkfox-amazon-ads-auth` SKILL.md 的 **Usage Scenarios 第 4 节**。\n\n## Core Concepts\n\n- **自动分页**：`fetchAll=true`（默认）跟随分页到结束或 `maxPages=50` 兜底；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count`\n- **过滤器结构不统一**：不同字段需要不同写法（详见下方\"过滤器结构速查\"）；本 skill 已对常见写错格式做自动兜底规范化，但仍建议按速查表准确传入\n- **只给 metadata，不含指标**：返回实体字段（id / 名称 / 状态 / 匹配类型 等），曝光 / 点击 / 花费 / 转化 等指标要调 `linkfox-amazon-ads-report`，按 id join\n- **支持 create / update**：各模块下 `create_*.py` / `update_*.py` 脚本创建或修改实体（campaign / adGroup / keyword / target / productAd / creative / budgetRule），payload 透传 Amazon 原生格式\n- **SB V3/V4 共存**：默认使用 `scripts/sb/v4/`；只有确认是 Legacy 或用户明确要求 V3 时使用 `scripts/sb/v3/`。不自动执行 V4→V3 回落；已知 Multi-Ad-Group Campaign 必须拒绝 V3\n- **SB 共享 Targeting**：Amazon 的 Keyword/Target 仍使用 `sb/keywords`、`sb/targets[/list]`，没有伪造的 `/sb/v4/keywords`；V3/V4 脚本入口隔离，但底层共享官方 targeting 资源\n- **SD 接口形态**：Sponsored Display 是 v3 REST endpoint，`GET /sd/` + querystring，分页用 `startIndex + count`；state / id 类过滤为逗号分隔字符串；`includeExtendedDataFields:true` 时请求 `/sd//extended` 路径。所有过滤字段统一支持 `{\"include\":[...]}` 入参\n\n## 可用脚本\n\n### SP（28 个）\n| 脚本 | 业务实体 | 操作 |\n|------|---------|------|\n| `sp/list_campaigns.py` | 广告活动 | 查询 |\n| `sp/cr"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-ads-manager\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1787053007211\n}"},{"path":"references/api.md","content":"# linkfox-amazon-ads-manager — 参数与字段参考（总览）\n\n按 Amazon Ads 广告产品分类维护。\n\n| 广告产品 | 脚本子目录 | 查询参考 |\n|---------|-----------|---------|\n| **Sponsored Products (SP)** — v3 | `scripts/sp/` | [api/sp.md](./api/sp.md) |\n| **Sponsored Brands (SB)** — V3 Legacy + V4 | `scripts/sb/v3/`、`scripts/sb/v4/` | [api/sb.md](./api/sb.md) |\n| **Sponsored Display (SD)** — v3 | `scripts/sd/` | [api/sd.md](./api/sd.md) |\n\n> Sponsored Television (ST) / Amazon DSP 暂未覆盖。\n\n## 通用约定\n\n- 每个脚本接受一个 JSON 字符串作为唯一位置参数\n- 鉴权：环境变量 `LINKFOX_AGENT_API_KEY`（或旧名 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- API 网关地址：环境变量 `LINKFOX_TOOL_GATEWAY`（默认 `https://tool-gateway.linkfox.com`）\n- 依赖 `linkfox-amazon-ads-auth`（脚本启动自动检查；缺失时 exit 42，stderr 打 `DEPENDENCY_MISSING`）\n\n## 共用参数（SP + SB + SD 均适用）\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| `profileId` | number | ✅ | — | 从 ads-auth 获取 |\n| `region` | string | ✅ | — | `NA` / `EU` / `FE` |\n| `fetchAll` | boolean | 否 | `true` | 自动翻页；SP/SB V4/Target 用 `nextToken`，SB V3 GET 与 SD 用 `startIndex + count` |\n| `maxResults` | integer | 否 | `100` | 单页 1-100；超限上游可能静默 clamp；对应 SD 端 `count` |\n| `skipDepCheck` | boolean | 否 | `false` | 跳过依赖检查 |\n| `includeExtendedDataFields` | boolean | 否 | — | 返回扩展字段（部分实体）；SD 通过路径切换为 `/sd//extended` 实现 |\n| `locale` | string | 否 | — | 本地化（keywords 支持） |\n\n## 输出格式\n\n```json\n{\n \"success\": true,\n \"apiVersion\": \"V3 | V4\",\n \"amazonResourceVersion\": \"V4 | V3_SHARED_TARGETING | V3.2_SHARED_TARGETING | SHARED\",\n \"\": [ /* 实体数组 */ ],\n \"total\": 157,\n \"pagesFetched\": 2,\n \"truncated\": false\n}\n```\n\n客户端过滤时（SP productAds 的 asinFilter/skuFilter）额外带 `serverTotalBeforeClientFilter` + `clientSideFilters`。\n\nSB 输出中的两个版本字段含义不同：`apiVersion` 表示调用入口和 Campaign 结构意图；`amazonResourceVersion` 表示实际 Amazon 资源传输版本。V4 Keyword/Target 入口使用 Amazon 共享 V3/V3.2 targeting 路径，不代表自动回落。\n\n失败：\n```json\n{\n \"error\": \"Upstream HTTP 401\",\n \"httpStatus\": 401,\n \"body\": \"...\",\n \"pagesFetched\": 0\n}\n```\n\n## 通用错误码\n\n| httpStatus / exit | 含义 | 建议 |\n|-------------------|------|------|\n| 200 | 成功 | — |\n| 400 | 入参结构错 | 核对对应 adProduct 的过滤器结构（api/sp.md / api/sb.md / api/sd.md） |\n| 401 | accessToken 过期 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 402 | 积分或余额不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 403 | profileId 无权限 | 核对 profileId 归属 |\n| 429 | 限流 | 间隔 2-5s 重试 |\n| exit 42 | 依赖 skill 未安装 | 先装 `linkfox-amazon-ads-auth` |\n\n---\n\n## Feedback API\n\n与上面的工具 API **base URL 不同**：\n\n```bash\ncurl -X POST https://skill-api.linkfox.com/api/v1/public/feedback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"skillName\":\"linkfox-amazon-ads-manager\",\"sentiment\":\"POSITIVE\",\n \"category\":\"OTHER\",\"content\":\"实体查询结果与预期一致\"}'\n```\n\n- `sentiment`: `POSITIVE` / `NEUTRAL` / `NEGATIVE`\n- `category`: `BUG` / `COMPLAINT` / `SUGGESTION` / `OTHER`"},{"path":"references/api/sb-coexistence.md","content":"# Sponsored Brands V3 / V4 共存与路由\n\n## 版本边界\n\n| 调用入口 | 适用结构 | 用途 |\n|---|---|---|\n| `scripts/sb/v4/` | `LEGACY` 或 `MULTI_AD_GROUP` | 默认入口；新建活动、多广告组、Ad/Creative 管理 |\n| `scripts/sb/v3/` | 仅 `LEGACY` | 历史活动兼容 |\n| `scripts/sb/*.py` | 同 V4 | 旧路径兼容；新调用应迁到 `scripts/sb/v4/` |\n\n新业务默认使用 V4。只有用户明确要求 V3，或已确认 Campaign 为 Legacy 时，才使用 V3。\n\n## 不自动回落\n\n脚本不执行 `V4 失败 → V3 重试`。Amazon 返回非 2xx 时，保留状态码和响应体交给调用方判断。原因：\n\n1. API 版本不等于 Campaign 结构；\n2. Multi-Ad-Group Campaign 无法无损转换成 V3；\n3. 自动回落会掩盖权限、参数或资源状态错误；\n4. V3 读取 V4 活动可能造成多 Ad Group 数据截断。\n\n当顶层参数或 `payload` 内出现 `campaignStructure=MULTI_AD_GROUP` / `isMultiAdGroupsEnabled=true`（含 `\"true\"`/`1` 等写法）时，V3 脚本会在发请求前返回：\n\n```json\n{\n \"code\": \"SB_V4_CAMPAIGN_NOT_SUPPORTED\",\n \"message\": \"This campaign uses the Sponsored Brands V4 multi-ad-group structure. Use scripts/sb/v4 instead of V3.\"\n}\n```\n\n脚本没有本地 Campaign 数据库；如果调用方未提供结构信息，无法仅凭 `campaignId` 可靠判断结构。因此 Agent 应先用 V4 `list_campaigns.py` 查询 `isMultiAdGroupsEnabled`，再决定是否允许使用 V3。\n\n## Amazon 路径与脚本版本不是一回事\n\nAmazon 的 Campaign / Ad Group / Ad 主资源有明确 V4 路径：\n\n```text\nsb/v4/campaigns/**\nsb/v4/adGroups/**\nsb/v4/ads/**\n```\n\n但 Keyword 与 Product Target 仍使用共享资源路径：\n\n```text\nsb/keywords\nsb/targets\nsb/targets/list\n```\n\n这些共享路径可以通过 `campaignId + adGroupId` 管理多广告组活动。为让调用意图明确，本 skill 在 `sb/v3/` 和 `sb/v4/` 都提供 keyword/target 入口；两者底层调用同一 Amazon 资源：\n\n- `sb/v3/*`：声明调用方已确认是 Legacy；\n- `sb/v4/*`：声明按 V4 Campaign/Ad Group 结构管理；\n- 输出中的 `amazonResourceVersion` 会标记为 `V3_SHARED_TARGETING` 或 `V3.2_SHARED_TARGETING`。\n\n这不是 V4 自动降级，也不会在失败后切换版本。\n\n## Creative 边界\n\n- V3 Legacy Campaign 的 Creative 是 Campaign payload 的组成部分，没有独立的 V3 Creative CRUD 脚本。\n- V4 使用 Ad 与独立 Creative Version：\n - `sb/v4/list_ads.py`\n - `sb/v4/create_ads.py`\n - `sb/v4/list_creatives.py`\n - `sb/v4/create_creatives.py`\n\n不要伪造不存在的 `sb/v3/creatives` 或 `sb/v4/keywords` Amazon 路径。\n\n## 决策流程\n\n```text\n新建 / 多 Ad Group / Ad / Creative\n → scripts/sb/v4/\n\n关键词或 Target\n → 默认 scripts/sb/v4/\n → 仅在已确认 Legacy 或用户明确要求 V3 时使用 scripts/sb/v3/\n\nV3 + MULTI_AD_GROUP\n → 拒绝并提示使用 V4\n\n任一版本调用失败\n → 返回原错误；不自动重试另一版本\n```"},{"path":"references/api/sb-v3.md","content":"# Sponsored Brands V3 Legacy API\n\nV3 仅用于历史 Legacy Campaign。共存与路由规则见 [sb-coexistence.md](./sb-coexistence.md)。\n\n## 脚本\n\n| 脚本 | Amazon 路径 | 方法 | 说明 |\n|---|---|---|---|\n| `sb/v3/list_campaigns.py` | `sb/campaigns` | GET | offset 分页查询 Legacy 活动 |\n| `sb/v3/create_campaigns.py` | `sb/campaigns` | POST | 创建 Legacy 活动；新业务不推荐 |\n| `sb/v3/update_campaigns.py` | `sb/campaigns` | PUT | 更新 Legacy 活动 |\n| `sb/v3/list_ad_groups.py` | `sb/adGroups` | GET | 查询 Legacy 活动关联的 Ad Group |\n| `sb/v3/list_keywords.py` | `sb/keywords` | GET | 查询关键词 |\n| `sb/v3/create_keywords.py` | `sb/keywords` | POST | 创建关键词，最多 100 个 |\n| `sb/v3/update_keywords.py` | `sb/keywords` | PUT | 更新关键词，最多 100 个 |\n| `sb/v3/list_targets.py` | `sb/targets/list` | POST | nextToken 分页查询商品定向 |\n| `sb/v3/create_targets.py` | `sb/targets` | POST | 创建商品定向，最多 100 个 |\n| `sb/v3/update_targets.py` | `sb/targets` | PUT | 更新商品定向 |\n\nV3 Creative 没有独立 CRUD；品牌名、标题、ASIN、素材等位于 Campaign 的 `creative` 字段中，通过 Campaign create/update 管理。\n\n## Legacy 安全参数\n\nV3 脚本额外接受：\n\n| 参数 | 作用 |\n|---|---|\n| `campaignStructure` | 传 `MULTI_AD_GROUP` 时拒绝调用 |\n| `isMultiAdGroupsEnabled` | 传 `true` 时拒绝调用 |\n\n这些字段只用于本地保护，不会发送给 Amazon。\n\n## GET list 参数\n\nCampaign：\n\n- `campaignIdFilter`\n- `stateFilter`\n- `nameFilter`\n- `portfolioIdFilter`\n- `creativeType`\n\nAd Group：\n\n- `adGroupIdFilter`\n- `campaignIdFilter`\n- `stateFilter`\n- `nameFilter`\n- `creativeType`\n\nKeyword：\n\n- `keywordIdFilter`\n- `adGroupIdFilter`\n- `campaignIdFilter`\n- `stateFilter`\n- `matchTypeFilter`\n- `keywordText`\n- `creativeType`\n- `locale`\n\nID、状态、匹配类型可传字符串、数组或 `{\"include\":[...]}`，脚本转换成 Amazon 所需的逗号分隔 query。分页参数为 `maxResults`、`fetchAll`、`maxPages`。\n\n## Target list 参数\n\nTarget list 接受 Amazon 原生 `filters`，也接受顶层 Object/Array 过滤（脚本会映射为 Amazon `filters[]`）：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"campaignIdFilter\": {\"include\": [\"1122334455\"]},\n \"stateFilter\": [\"enabled\", \"paused\"],\n \"maxResults\": 100\n}\n```\n\n等价原生写法：\n\n```json\n{\n \"profileId\": 1234567890,\n \"region\": \"NA\",\n \"payload\": {\n \"maxResults\": 100,\n \"filters\": [\n {\"filterType\": \"CAMPAIGN_ID\", \"values\": [\"1122334455\"]},\n {\"filterType\": \"TARGETING_STATE\", \"values\": [\"enabled\", \"paused\"]}\n ]\n }\n}\n```\n\n可映射字段：`campaignIdFilter`→`CAMPAIGN_ID`，`adGroupIdFilter`→`AD_GROUP_ID`，`stateFilter`→`TARGETING_STATE`，`targetIdFilter`→`TARGET_ID`，`creativeTypeFilter`→`CREATIVE_TYPE`。\n\n## 示例\n\n```bash\npython scripts/sb/v3/list_campaigns.py '{\"profileId\":1234567890,\"region\":\"NA\",\"stateFilter\":[\"enabled\",\"paused\"]}'\n\npython scripts/sb/v3/list_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignIdFilter\":[\"1122334455\"]}'\n\npython scripts/sb/v3/update_keywords.py '{\"profileId\":1234567890,\"region\":\"NA\",\"campaignStructure\":\"LEGACY\",\"payload\":[{\"keywordId\":1,\"campaignId\":2,\"adGroupId\":3,\"bid\":1.2}]}'\n```\n\n写操作不会自动切换到 V4；非 2xx 原样返回。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1172,"uniquenessScore":37,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T22:14:04.387Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T22:14:04.387Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T00:32:19.637Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}