腾讯广告 - 常规(标准)广告组创建：按步执行

> 前置依赖：运行脚本前需安装 CLI — npm install tencentads-cli@1.0.0（需要 Node.js ≥ 20）

本技能是常规展示广告的执行指南——按 7 个步骤顺序完成一条常规广告组的创建。严格按步骤顺序执行，后面的步骤依赖前面的输出，不可跳步。

所有 API 调用均通过本技能的专用脚本执行，脚本负责：API 分支路由、返回数据裁剪、格式转换（rules_json 解析、geo 编码查找等）。Agent 专注于：从脚本返回结果中做出业务决策（选哪个组合、选哪个转化目标、选什么出价方式）。

> 脚本调用格式统一：node scripts/<脚本名>.mjs ''

> 执行脚本时先进入本 skill 根目录，再按相对 scripts/ 路径调用。

⚠️ 跨平台 JSON 参数传递规则（经实测验证）

脚本调用格式为 node scripts/<脚本名>.mjs ''，但 JSON 参数的引号包裹方式因操作系统/终端而异，传递不当会导致 JSON.parse 报错（如 Expected property name or '}' in JSON at position 1）。

> ⛔ PowerShell 5.x 是重灾区：单引号 '...'、反引号 ` " ` 、反斜杠 \" 三种常见写法全部失败（双引号会被吞掉）。必须使用 --% 停止解析符或 \" `` 组合转义。

> ⛔ Windows CMD 不支持单引号包裹字符串，单引号会被当作普通字符传入脚本，导致 JSON 解析失败。

常规广告与智投的关键区别（执行参考）

> 以下差异直接影响步骤 6 请求体的构建，执行时需注意。

⛔ 执行顺序（不可跳步）：

步骤1 → 步骤1A(可选) → 步骤2 → 步骤3 → 步骤4 → 步骤5 → 步骤6
获取      资产反推       确定      确定       获取      配置       组装请求体
四元组    四元组         推广产品   版位       转化目标  定向+时间  → create-adgroup.mjs
          (有资产线索时)  +载体               +出价

执行协议（高优先级，覆盖后文）

> 若本节与下文"继续执行""不要重复查询"等表述冲突，以本节为准。

⛔ 出价方式与步骤跳过规则

> 步骤 1、2、5、6 无论什么出价方式都必须执行。以下规则只影响步骤 3~4：

• CPC/CPM（轻量路径）：
• 步骤 3：自动版位 → 直接设 automatic_site_enabled: true，跳过 get-site-set.mjs；手动版位 → 仍需查询
• 步骤 4：跳过 4B 转化查询，只需 bid_mode + bid_amount
• oCPM/oCPC（完整路径）：
• 步骤 3~4 全部执行（步骤 4 的 get-conversions.mjs 依赖步骤 3 返回的 site_set）

1. ⛔ 步骤 1 → 2 是绝对必须执行的前两步，不可跳过。 即使用户 input 中看起来已包含四元组、商品信息，仍必须调用 get-rules.mjs 确认四元组、调用 get-assets.mjs 获取推广资产 ID。原因：不同账号的可选组合不同，自然语言描述无法直接转为精确的枚举值和 ID。例外：步骤 1A 成功确定资产后，步骤 2 可跳过 get-assets.mjs 调用（但仍需从 1A 的数据构造字段）。步骤 3-5 中的查询子动作在满足"显式证据白名单"或"出价方式跳过规则"时可跳过，但步骤 1 不可。
2. 进入下一步前，必须先拿到上一步输出并确认来源。 合法来源只有三类：用户在原始需求中明确给出、当前 session 前一步脚本返回、当前 session 前一步 API 返回。
3. 自然语言意图不能替代结构化字段。 "电商推广""品牌曝光"等描述只能用于步骤 1 筛选四元组，不能直接当作四元组、营销载体 ID、conversion_id 的依据。
4. 进入步骤 6 前必须能回答每个关键字段来自哪里。 说不清来源的字段，不要猜。
5. ⚠️ 错误处理与重试限制：每个脚本调用最多重试 1 次（换参数或换调用方式）。如果 2 次仍失败（如返回 "Mock not found"、空结果、报错），立即跳过该步骤，用已有数据继续推进到下一步直至步骤 6。严禁反复重试同一脚本、读取脚本源码、或切换到非脚本方式（如 tencent-ads api）尝试绕过。宁可在最终请求中缺少某个字段，也不要耗尽所有轮次。
6. 显式证据白名单（仅适用于步骤 3-5 的查询子动作，步骤 1 不适用）：
• 四元组查询：用户明确给出 marketing_goal、marketing_sub_goal、marketing_target_type、marketing_carrier_type 这 4 个枚举值全部；或当前 session 已从 get-rules.mjs 返回中得到。
• 推广产品 / 营销载体查询：用户明确给出构造请求体所需的完整 ID；或当前 session 已从 get-assets.mjs 返回中得到；或步骤 1A 的 get-assets-by-rules.mjs 已成功匹配到资产。
• 转化目标查询：用户明确给出 conversion_id；或当前 session 已从 get-conversions.mjs 返回中得到。
• 定向查询：用户没有任何定向约束时可跳过；只要用户给了地域、年龄、性别、排除已转化、设备等要求，就必须先调用 get-targeting-lookup.mjs。

步骤 1（⛔ 最先执行）：获取四元组

> 前置：account_id + 用户营销需求

> 输出：marketing_goal、marketing_sub_goal、marketing_target_type、marketing_carrier_type

四元组是腾讯广告的产品术语，指营销内容 + 转化/优化目标的完整匹配集合，共10个字段：

• 营销内容（4个）：marketing_goal、marketing_sub_goal、marketing_carrier_type、marketing_target_type
• 转化/优化目标（6个）：optimization_goal、deep_behavior_optimization_goal、deep_behavior_advanced_goal、deep_worth_optimization_goal、deep_worth_advanced_goal、forward_link_assist

这10个字段作为一个整体定义广告的投放语义，必须从脚本返回的可选范围中选取，禁止通过推理猜测。

为什么不能猜？

• 不同账号准入的组合不同，猜错会导致 adgroups/add 报错
• 看似相同的场景（如"电商推广"），在不同账号上对应的 marketing_goal 可能完全不同
• 四元组错误会级联导致后续推广产品、转化目标等全部错误

调用方式：

node scripts/get-rules.mjs '{"account_id":"<ACCOUNT_ID>"}'

示例：

node scripts/get-rules.mjs '{"account_id":"123456789"}'

脚本已处理：内部调用 get_rules_by_advertiser（不传 delivery_scene，获取常规广告可用组合），解析 rules_json 嵌套 JSON 字符串，按 marketing_goal 分组输出紧凑格式。

返回格式说明：

> 所有枚举值均为完整 key（如 MARKETING_TARGET_TYPE_APP_ANDROID），可直接使用。

返回示例：

{
  "goals": ["MARKETING_GOAL_PRODUCT_SALES", "MARKETING_GOAL_USER_GROWTH"],
  "total": 5,
  "default_sub_goal": "MARKETING_SUB_GOAL_UNKNOWN",
  "by_goal": {
    "MARKETING_GOAL_PRODUCT_SALES": [
      {"t": "MARKETING_TARGET_TYPE_CONSUMER_PRODUCT", "c": "MARKETING_CARRIER_TYPE_JUMP_PAGE", "pt": 30}
    ],
    "MARKETING_GOAL_USER_GROWTH": [
      {"s": "MARKETING_SUB_GOAL_APP_ACQUISITION", "t": "MARKETING_TARGET_TYPE_APP_ANDROID", "c": "MARKETING_CARRIER_TYPE_APP_ANDROID", "pt": 43}
    ]
  }
}

Agent 需要做的决策：当返回多个组合时，根据用户意图选择正确的一组。

选择规则（按优先级逐层过滤）：

1. 先从用户意图提取关键约束：
• 用户提到了"卖货"/"电商"/"商品销售" → marketing_goal 应含 PRODUCT_SALES
• 用户提到了"APP下载"/"拉新"/"注册" → marketing_goal 应含 USER_GROWTH
• 用户提到了"品牌"/"曝光" → marketing_goal 应含 BRAND_PROMOTION
• 用户提到了"线索"/"表单"/"留资" → marketing_goal 应含 LEAD_RETENTION
• 用户提到了"涨粉"/"加关注" → marketing_goal 应含 INCREASE_FANS_INTERACTION
• 用户提到了"小程序" → marketing_target_type 应含 MINI_PROGRAM_WECHAT
• 用户提到了"APP"/"应用"作为推广产品（非营销载体） → marketing_target_type 应含 APP_ANDROID 或 APP_IOS。
• 用户提到了"小游戏" → marketing_target_type 应含 WECHAT_MINI_GAME
• 用户提到了"视频号直播"作为推广对象（非营销载体） → marketing_target_type 应含 WECHAT_CHANNELS_LIVE
• 用户提到了"视频号直播"作为营销载体 → marketing_carrier_type 应含 WECHAT_CHANNELS_LIVE（⛔ 不要据此设置 marketing_target_type）
• 用户提到了"跳转页面" → marketing_carrier_type 应含 JUMP_PAGE
• 用户提到了"新游推广"/"新游上线"/"新游首发"/"游戏上线" → marketing_sub_goal 应含 NEW_GAME_LAUNCH
• 用户提到了"新游测试"/"测试服"/"删档测试"/"试玩"/"新客试玩" → marketing_sub_goal 应含 NEW_GAME_TEST
• 用户提到了"新游预约"/"预约" → marketing_sub_goal 应含 NEW_GAME_RESERVE
• 用户提到了"平稳期"/"长线运营"/"平稳期推广" → marketing_sub_goal 应含 PLATEAU_PHASE_LAUNCH
• 用户提到了"小游戏新客"/"小游戏拉新"/"新客增长" → marketing_sub_goal 应含 MINI_GAME_NEW_CUSTOMER_GROWTH
• 用户提到了"小游戏回流"/"小游戏促活"/"回流促活" → marketing_sub_goal 应含 MINI_GAME_RETURN_CUSTOMER_ENGAGEMENT

1. 按 marketing_goal 匹配用户的营销目标

1. 按 marketing_target_type 匹配用户的推广对象类型

> ⛔⛔⛔ 前置强制检查（最高优先级）：用户是否同时给了「推广产品 ID 或名称」？

> - 是 → 禁止在步骤 1 确定 marketing_target_type，必须直接跳到步骤 1A，把该 marketing_goal 下的全部 combinations 传入，由脚本自动匹配。即使用户同时说了"营销载体: iOS应用"，也绝对不能据此把 combinations 缩窄为只含 APP_IOS 的那一个。

> - 否 → 继续按下面的规则选择。

>

> ⚠️ marketing_target_type 反映的是"产品/店铺/内容"的类型，不要与优化目标、出价方式混淆。无法直接确定时，按 marketing_goal 过滤后从剩余项中选择。

>

> ⛔ "营销载体"只能确定 marketing_carrier_type，禁止用来推断或缩窄 marketing_target_type。

> ⚠️ 商品库类 marketing_target_type 选择规则（仅当 PRODUCT_SALES 且 combinations 同时含 CONSUMER_PRODUCT、WECHAT_STORE_PRODUCT、WECHAT_STORE 中多个时）：

> 1. 用户明确说了"商品库" → 选 CONSUMER_PRODUCT

> 2. 用户明确说了"微信小店"/"视频号小店" → 选 WECHAT_STORE_PRODUCT（推广单个商品）或 WECHAT_STORE（推广整个店铺），根据用户意图区分

> 3. 用户给了推广产品名称或 ID → ⛔ 禁止暂定，必须直接进入步骤 1A 通过资产反推确定。传给 1A 的 combinations 按 1A-① 规则过滤（只按 marketing_goal 过滤，其余维度全量）。

> 4. 用户未明确且未给任何资产线索 → 暂定 CONSUMER_PRODUCT，步骤 2 会根据资产查询结果自动回退（见步骤 2B「商品库类空资产回退」）

1. ⛔ 穷尽以上规则后仍无法唯一确定 marketing_target_type 时（强制检查点）：

> 先回答：用户是否给了推广产品的名称或 ID？

> - 是 → 立即进入步骤 1A，通过资产反推确定四元组。禁止猜测 marketing_target_type。传给 1A 的 combinations 按 1A-① 规则过滤（只按 marketing_goal 过滤，其余维度全量）。

> - 否 → 向用户列出剩余 combinations 中的 marketing_target_type 选项确认，附中文含义帮助选择。

1. 若过滤后 marketing_carrier_type 仍有多个可选值（即同一 marketing_goal + marketing_target_type 对应多种 carrier_type），必须向用户确认营销载体类型，不能自行猜测。此时应将 combinations 中实际剩余的所有 marketing_carrier_type 选项列出给用户，让用户选择。例如："根据您的推广目标，当前支持以下营销载体：1) XXX 2) YYY 3) ZZZ，请问您要使用哪种？"（其中 XXX/YYY/ZZZ 替换为 combinations 中实际返回的 carrier_type 值）
2. marketing_sub_goal 只能复用 get-rules.mjs 返回值，禁止语义改写：例如用户说"注册"、"新客"、"拉新"时，也不要自造 MARKETING_SUB_GOAL_USER_REGISTER；如果步骤 1 返回的是 MARKETING_SUB_GOAL_MINI_GAME_NEW_CUSTOMER_GROWTH 或 MARKETING_SUB_GOAL_APP_ACQUISITION，后续所有脚本都必须原样复用

步骤 1 完成后你应该有：四元组 4 个值 + product_type（从 combinations 数组的匹配项取）。product_type 需透传给步骤 3 和步骤 4 的脚本。

步骤 1A（可选，有资产线索时执行）：通过资产反推四元组

> ⛔ 前置门禁：步骤 1 过滤后只剩 1 个 combination → 四元组已确定，直接跳到步骤 2，禁止进入 1A。 即使用户给了推广产品 ID/名称也不需要 1A——资产查询在步骤 2 完成。

>

> 触发条件（仅当通过前置门禁后）：用户提到了推广产品/资产的 ID 或名称，且步骤 1 过滤后仍有 2 个及以上 combinations 无法唯一确定四元组。

>

> 不触发的情况：① 步骤 1 已经唯一确定了四元组（只剩 1 个 combination）② 用户没有给出任何资产 ID 或名称线索

目的：通过查询账号下所有可能组合的真实资产列表，用用户给的资产 ID 或名称进行匹配，精确锁定四元组，避免向用户确认。

1A-① 预过滤（由脚本自动完成）

⛔ 规则不变：只按 marketing_goal 过滤，marketing_target_type 和 marketing_carrier_type 维度不做任何缩窄。

脚本内部自动调用 get_rules_by_advertiser API 获取全量 combinations，并按传入的 marketing_goal 过滤。Agent 不需要透传 combinations 数组。 脚本还支持传入 marketing_target_type 进行优先查询（非缩窄）：优先查该类型的资产并尝试匹配，命中则跳过其余类型的 API 调用以加速返回，未命中则自动 fallback 全量查询。脚本还会在资产匹配成功且载体类型需要时自动查询载体列表，结果通过 carrier_result 返回（详见 1A-③+）。

1A-② 调用 get-assets-by-rules.mjs

node scripts/get-assets-by-rules.mjs '{"account_id":"<ACCOUNT_ID>","marketing_goal":"<用户确定的MARKETING_GOAL或不传>","marketing_target_type":"<用户明确的TARGET_TYPE或不传>","match_hint":{"asset_id":"<用户给的ID或null>","asset_name":"<用户给的名称或null>"},"carrier_hint":{"carrier_id":"<用户给的载体ID或null>","carrier_name":"<用户给的载体名称或null>"}}'

参数说明：

• account_id：必填
• marketing_goal：可选。传入后脚本只查该 goal 下的 combinations（等价于原来 Agent 手动按 goal 过滤）。用户明确了 goal 就传，未明确就不传（脚本查全量）
• marketing_target_type：可选。用户明确了推广产品类型时传入（如用户说"小程序"就传 MARKETING_TARGET_TYPE_MINI_PROGRAM_WECHAT）。脚本会优先查该类型下的资产，匹配成功则跳过其余类型查询以加速返回；未传或优先查未命中时自动 fallback 全量查询。注意：这里传 marketing_target_type 仅影响查询顺序（优先查 → fallback 全量），不等同于步骤 1 中"缩窄 combinations"——即使传了，脚本仍保证不漏查其他类型
• match_hint：用户给了资产 ID 就传 asset_id，给了名称就传 asset_name，两个都给了就都传（ID 优先匹配）
• carrier_hint：可选，用户给了载体 ID 传 carrier_id，给了载体名称传 carrier_name

返回示例（unique_match）：

{
  "asset_dict": {
    "MARKETING_GOAL_PRODUCT_SALES|MARKETING_SUB_GOAL_UNKNOWN|MARKETING_TARGET_TYPE_PRODUCT_AGGREGATION_PAGE|MARKETING_CARRIER_TYPE_JUMP_PAGE": {
      "combination": {
        "marketing_goal": "MARKETING_GOAL_PRODUCT_SALES",
        "marketing_sub_goal": "MARKETING_SUB_GOAL_UNKNOWN",
        "marketing_target_type": "MARKETING_TARGET_TYPE_PRODUCT_AGGREGATION_PAGE",
        "marketing_carrier_type": "MARKETING_CARRIER_TYPE_JUMP_PAGE",
        "product_type": 30
      },
      "asset_type": "INDUSTRY",
      "assets": [
        { "marketing_asset_id": "578879856", "name": "某资产名" }
      ]
    },
    "其他组合...": { "combination": {...}, "asset_type": "...", "assets": "[3 items, omitted]" }
  },
  "match_result": {
    "status": "unique_match",
    "match_type": "id_exact",
    "matched_items": [
      {
        "combination_key": "MARKETING_GOAL_PRODUCT_SALES|...|MARKETING_CARRIER_TYPE_JUMP_PAGE",
        "combination": { "marketing_goal": "...", "marketing_sub_goal": "...", "marketing_target_type": "...", "marketing_carrier_type": "...", "product_type": 30 },
        "asset_type": "INDUSTRY",
        "asset": { "marketing_asset_id": "578879856", "name": "某资产名" }
      }
    ]
  },
  "carrier_result": {
    "status": "found",
    "carriers": [
      { "carrier_id": "417200582", "carrier_name": "唯品会" }
    ],
    "matched_carrier": { "carrier_id": "417200582", "carrier_name": "唯品会" }
  }
}

> 注意：unique_match 时脚本会自动裁剪非命中 combination 的 assets（显示为 "[N items, omitted]"），减少上下文开销。

1A-③ 匹配结果处理

脚本返回的 match_result 已按优先级完成匹配，直接根据 status 处理：

1A-③+ 载体查询结果处理（carrier_result）

当资产匹配成功（unique_match / multiple_match）且载体类型不是 JUMP_PAGE 时，脚本自动查询载体列表并返回 carrier_result。

> 载体查询的接口路由（脚本内部自动判断，Agent 无需关心）：

> - 统一通过 bff_promoted_objects/get 接口查询，脚本根据 marketing_carrier_type 自动映射到对应的 promoted_object_type

1A-④ 步骤 1A 完成后的影响

步骤 2（⛔ 默认必须执行）：获取推广产品 + 营销载体

> 前置：步骤 1 的 marketing_target_type、marketing_carrier_type、marketing_goal

> 输出：asset_id、carrier_id 等扁平 ID（步骤 6 传给 create-adgroup.mjs，由脚本自动组装为 API 所需的嵌套结构）

> ⚡ 快速路径：如果步骤 1A 的 match_result.status 为 unique_match，可跳过 get-assets.mjs 调用，直接使用脚本返回的 flat_params 中的扁平 ID。

> ⚡ ONEID 类自动短路：当用户给了明确的资产 ID 时，通过 asset_hint.asset_id 传给 get-assets.mjs，脚本内部会自动短路（不调 API，直接返回 shortcut: true），返回的 flat_params 可直接透传。用户给的是名称时传 asset_hint.asset_name，脚本不会短路，走正常查询。

调用方式（步骤 1A 未执行或未成功时）：

node scripts/get-assets.mjs '{"account_id":"<ACCOUNT_ID>","marketing_target_type":"<...>","marketing_carrier_type":"<...>","marketing_goal":"<...>","product_type":<number>,"carrier_hint":{"carrier_id":"...","carrier_name":"..."},"asset_hint":{"asset_id":"...","asset_name":"..."}}'

参数说明：

• account_id、marketing_target_type：必填
• marketing_carrier_type、marketing_goal：可选
• product_type：可选，来自步骤 1 的 combination.product_type，载体查询时使用
• carrier_hint：可选，用于载体匹配。用户给了载体 ID 就传 carrier_id，给了载体名称就传 carrier_name
• asset_hint：可选，用户给了明确的资产 ID 就传 asset_id，给了资产名称就传 asset_name。ONEID 类传 asset_id 时脚本自动短路

> ⚡ 载体查询已内置：当传入 marketing_carrier_type + product_type（或 carrier_hint）时，脚本会自动查询并匹配载体，返回 carrier_result 字段。无需额外调用 get-assets-by-rules.mjs 来获取载体 ID。

脚本已处理：自动根据 marketing_target_type 判断分类（ONEID / 商品库 / 行业产品库），路由到正确的 API，返回统一格式的资产列表。同时自动查询载体（如需要）。

返回示例（ONEID 类）：

{
  "asset_type": "ONEID",
  "assets": [
    {
      "marketing_asset_outer_id": "wx1234567890",
      "marketing_carrier_id": "wx1234567890",
      "name": "我的小程序",
      "type": "MINI_PROGRAM_WECHAT"
    }
  ],
  "carrier_result": {
    "status": "not_needed",
    "reason": "ONEID/视频号类资产已包含 marketing_carrier_id"
  }
}

Agent 需要做的决策——资产选择规则（⛔ 禁止默认选第一个）：

1. 用户提及了产品/商品名称 → 从 assets 中选 asset_name（或 name）与用户意图最相关的项
2. 仅 1 个资产 → 直接使用
3. 多个且无法区分 → 展示给用户确认

2A. 透传 flat_params 给步骤 6（⛔ 不要手动构造嵌套结构）

> 核心原则：Agent 只负责将脚本返回的扁平 ID 透传给步骤 6 的 create-adgroup.mjs。嵌套结构（marketing_asset_outer_spec、marketing_asset_id、marketing_carrier_detail）全部由 create-adgroup.mjs 根据 marketing_target_type / marketing_carrier_type 自动组装，Agent 不要手动构造。

get-assets-by-rules.mjs 的 flat_params：

脚本会为每条 matched_items 都计算并挂载 flat_params（与 create-adgroup.mjs 入参直接对齐）：

• unique_match → 顶层也输出 flat_params（= matched_items[0].flat_params），Agent 直接透传即可
• multiple_match / name_multiple_match → 用户选完后，取对应项的 matched_items[n].flat_params 即可，无需手动提取字段

{
  "flat_params": {
    "asset_id": "342574",        // INDUSTRY → marketing_asset_id; ONEID → marketing_asset_outer_id; CATALOG → catalog_id
    "carrier_id": "417200582",   // 优先 carrier_result.matched_carrier，其次 ONEID 资产的 marketing_carrier_id
    "catalog_id": "123456",      // 仅商品库类
    "asset_sub_id": "...",       // 商品库子 ID / ONEID 子包 / 直播预约 notice_id 等（可选）
    "sub_carrier_id": "..."      // 通常与 asset_sub_id 同值（可选）
  }
}

get-assets.mjs 的 flat_params：

get-assets.mjs 也会为每条 assets 都挂载 flat_params，格式与上面一致。Agent 选完后直接取 assets[n].flat_params 透传即可。assets 恰好 1 条时顶层也输出 flat_params（= assets[0].flat_params）。

> 总结：无论走哪个脚本、匹配到几条，每条结果都带 flat_params。Agent 选定后直接透传，永远不需要手动判断"该取哪个字段"。

asset_sub_id / sub_carrier_id 补充说明（flat_params 已自动处理，以下仅供了解）：

• APP_ANDROID：子包标识（如 "0;00011609313139363030393334"），asset_sub_id 和 sub_carrier_id 填同一值
• PC_GAME：区服标识（如 "hwbz"），asset_sub_id 和 sub_carrier_id 填同一值
• WECHAT_CHANNELS_LIVE_RESERVATION：直播预约 notice_id（如 "finderlivenotice-..."），asset_sub_id 和 sub_carrier_id 填同一值
• 商品库类（CONSUMER_PRODUCT / WECHAT_STORE_PRODUCT / COMMODITY_SET / WECHAT_STORE_PRODUCT_SET）：asset_sub_id = product_outer_id / wechat_store_id / commodity_set_id
• 无子级时不传这两个字段即可

carrier_id 的来源（按优先级）：

1. flat_params.carrier_id（两个脚本每条结果都带，最简单直接）
2. 用户明确给出的载体 ID。⛔ 用户给的"推广产品 ID"不是载体 ID，两者不可互换。
3. 以上都没有时，需向用户确认

视频号直播预约场景补充：get-assets.mjs 返回含 live_notices，Agent 必须选取 notice_id（格式 finderlivenotice-xxx），同时传给 asset_sub_id 和 sub_carrier_id。多场次选择：① 用户指定 → 匹配 ② 未指定 → start_time 最晚且在投放日期内 ③ 都不在范围 → start_time 最晚。（get-assets-by-rules.mjs 的 flat_params 中已自动选取最晚场次，如需用户指定可覆盖）

> 脚本会根据 marketing_target_type 自动判断三分类（ONEID / 商品库 / 行业产品库），组装正确的 marketing_asset_outer_spec 或 marketing_asset_id。根据 marketing_carrier_type 自动判断是否需要 marketing_carrier_detail。不需要手动构造这些嵌套结构。

2B. 强约束

• 白名单例外：用户在原始需求里已明确给出完整 ID（如 catalog_id、product_outer_id、marketing_asset_id 等），则可直接作为对应的扁平 ID 使用并跳过查询。ONEID 类用户给了资产 ID 时通过 asset_hint.asset_id 传给 get-assets.mjs，脚本会自动短路处理。
• 空字符串不是合法结果：不要把空字符串当作"已完成步骤 2"。查不到且用户也未提供时，保留缺失状态。
• ⚠️ 商品库类空资产回退（脚本已自动处理）：get-assets.mjs 内部已实现自动回退——当 CONSUMER_PRODUCT 查询返回空资产时，脚本会自动尝试 WECHAT_STORE_PRODUCT，反之亦然。Agent 无需手动重试或切换类型。
• 回退成功时，返回结果中会包含 actual_marketing_target_type（实际生效的类型）和 fallback_applied: true
• ⛔ Agent 必须检查返回的 actual_marketing_target_type 字段：如果与传入的类型不同，说明发生了回退，后续步骤 3~7 都必须使用 actual_marketing_target_type 的值（而非原始传入值）
• 如果返回 assets: [] 且无 fallback_applied，说明两种类型都没有资产，按正常的空结果处理（保留缺失状态）
• 跳转页面载体 (MARKETING_CARRIER_TYPE_JUMP_PAGE)：不需要传 carrier_id，但推广资产仍需正常查询

步骤 2 完成后你应该有：flat_params（包含 asset_id、carrier_id 等扁平 ID），或已从脚本返回中选定了一条带 flat_params 的资产。这些值不能是空字符串。

步骤 3（⛔ oCPM/oCPC 必须执行）：确定版位

> 前置：步骤 1 的 marketing_target_type、marketing_carrier_type

> 输出：site_set（数组）或确认使用自动版位

> ⚡ 快速路径：仅 CPC/CPM + 自动版位 → 直接设 automatic_site_enabled: true，跳过本步查询，进入步骤 4。

>

> ⛔ oCPM/oCPC 时必须调用 get-site-set.mjs，即使用户已明确指定了版位名称。原因：步骤 4 的 get-conversions.mjs 依赖此步返回的 available_site_set 来构造 site_set 参数，用户给的版位名称不能直接替代。

版位决定了广告的投放位置。常规广告支持手动选择版位和自动版位两种模式。

版位确定规则：

1. 用户指定了版位 → 先调用 get-site-set.mjs，再从脚本返回的真实 available_site_set 中选择（如"投朋友圈" → ["SITE_SET_MOMENTS"]；如"投腾讯平台与内容媒体/PCAD" → 按 3B 一级分类展开为 ["SITE_SET_KANDIAN", "SITE_SET_QQ_MUSIC_GAME", "SITE_SET_TENCENT_NEWS", "SITE_SET_TENCENT_VIDEO"] 再与 available_site_set 取交集）。确定最终的用户版位列表供步骤 4B 和步骤 6 使用
2. 用户要求自动版位 → automatic_site_enabled: true，仍需查询可用版位列表，后续 get-conversions.mjs 传入 auto_site_set 中的版位
3. 用户未指定版位 → 推荐自动版位，仍需调用 get-site-set.mjs 获取版位列表

3A. 获取可用版位列表

node scripts/get-site-set.mjs '{"account_id":"<ACCOUNT_ID>","marketing_goal":"<MARKETING_GOAL_枚举key>","marketing_sub_goal":"<MARKETING_SUB_GOAL_枚举key>","marketing_target_type":"<MARKETING_TARGET_TYPE_枚举key>","marketing_carrier_type":"<MARKETING_CARRIER_TYPE_枚举key>"}'

示例：

node scripts/get-site-set.mjs '{"account_id":"123456789","marketing_goal":"MARKETING_GOAL_USER_GROWTH","marketing_sub_goal":"MARKETING_SUB_GOAL_UNKNOWN","marketing_target_type":"MARKETING_TARGET_TYPE_APP_ANDROID","marketing_carrier_type":"MARKETING_CARRIER_TYPE_APP_ANDROID"}'

脚本已处理：内部自动设置 bid_mode、buying_type、campaign_type 等 API 必传参数，调用方只需传四元组枚举 key。

返回：

{
  "available_site_set": ["SITE_SET_MOMENTS", "SITE_SET_WECHAT", "SITE_SET_MOBILE_UNION", "SITE_SET_QQ_MUSIC_GAME", "SITE_SET_TENCENT_VIDEO", "SITE_SET_CHANNELS", "SITE_SET_MOBILE_YYB"],
  "auto_site_set": ["SITE_SET_MOMENTS", "SITE_SET_WECHAT", "SITE_SET_MOBILE_UNION"],
  "non_multi_site_set": ["SITE_SET_MOBILE_YYB"]
}

3B. 版位枚举对照表（权威）

> ⚠️ 此表为 API 真实枚举 key 与中文名称的对照表，以 API 文档为准。Agent 在从用户自然语言映射版位时，必须参考此表，严禁凭猜测使用表中不存在的 key。

> ⛔ site_set 枚举值只允许使用上表第一列的 key，禁止自行从中文翻译构造枚举名。 脚本返回什么就用什么。

>

> ⚠️ 标注"仅支持搜索广告"的版位（SITE_SET_WECHAT_SEARCH、SITE_SET_QBSEARCH）在非搜索场景下不可使用，不要将其加入普通展示广告的 site_set。

版位集合一级分类对照表

3C. 强约束

• 手动版位：automatic_site_enabled: false + site_set 数组（来自脚本返回的 available_site_set 或用户指定，按上表映射）
• 自动版位（推荐）：automatic_site_enabled: true，site_set 不传

⚠️ 传给 get-conversions.mjs 的 site_set 参数规则（仅 oCPM/oCPC 需关注，CPC/CPM 跳过）

> ⛔ site_set 只能包含 available_site_set 中存在的版位。 必须传入用户最终选择的版位列表（即手动版位场景下用于 adgroups/add 的 site_set，自动版位场景下传 auto_site_set），要根据用户实际选择的版位传入，不要盲目传完整的 available_site_set**。

> ⚠️ 用户说的"优先版位"（如"优先视频号"）≠ site_set 参数。"优先版位"影响的是 priority_site_set，而 get-conversions.mjs 的 site_set 是查询范围，自动版位时必须传 auto_site_set 全量。

❌ 典型错误：自动版位时只传了 ["SITE_SET_CHANNELS"]（用户的优先版位）→ 应传 auto_site_set 全量。

步骤 3 完成后你应该有：版位模式（自动/手动）+ 供步骤 4 使用的 site_set（oCPM/oCPC 时：自动版位 = auto_site_set 全量，手动版位 = 用户指定 ∩ available_site_set；CPC/CPM + 自动版位时无需 site_set）。

3D. 版位定投场景（scene_spec，可选）

> scene_spec 是请求体根层级字段（与 targeting 并列），用于对已选版位内的流量做精细筛选。

> 默认"不限"（不传），仅在用户明确提到定投/屏蔽特定流量场景时才构造。

场景定向完整字段（以下字段均放在 scene_spec: { ... } 对象内）：

wechat_scene 子字段：

构造示例：

定投联盟流量包 + 屏蔽指定流量包：

"scene_spec": {
  "union_position_package": [6001403],
  "exclude_union_position_package": [91019]
}

定投指定公众号 + 联盟信息流场景：

"scene_spec": {
  "mobile_union": ["MOBILE_UNION_SCENE_IN_FEEDS_NATIVE"],
  "wechat_position": [123456, 789012]
}

> ⚠️ 枚举类字段（mobile_union、exclude_mobile_union、tencent_news、display_scene、qbsearch_scene、pc_scene、wechat_search_scene）必须通过 get-enum-options.mjs 查询确认枚举值，禁止猜测。

> ⚠️ ID 列表类字段（union_position_package、exclude_union_position_package、wechat_position、mobile_union_category、wechat_channels_scene、wechat_scene 子字段）直接传用户给出的 ID。

> ⚠️ 用户未提到任何版位定投场景需求时，不传 scene_spec（等同于 UI 上全部选"不限"）。

步骤 4：获取转化目标 + 确定出价

> 前置：步骤 1 的四元组 + 步骤 2 的资产 ID + 步骤 3 的 site_set

> 输出：conversion_id（可选）、bid_mode、smart_bid_type、bid_amount（手动出价时）或 daily_budget（自动出价时）

> ⚡ 快速路径：CPC/CPM → 跳过 4B 转化查询，只需确定 bid_mode + bid_amount，然后进入步骤 5。

4A. 确定出价方式 (bid_mode)

根据用户意图确定出价方式：

核心规则：

1. CPC/CPM：只需 bid_mode + bid_amount，不需要查询转化目标，跳过步骤 4B
2. oCPM/oCPC：需 bid_mode + conversion_id，手动出价（CUSTOM）还需 bid_amount
3. 用户未指定出价方式时，默认使用 BID_MODE_OCPM

4A-2. 确定出价方案（smart_bid_type）

> CPC/CPM 固定走手动出价。oCPM/oCPC 根据用户意图选择，默认手动出价。

SYSTEMATIC（最大转化量）约束：

1. daily_budget 必填且 > 0，用户未给时必须向用户确认
2. bid_amount 不传
3. 必须是 oCPM/oCPC
4. ⛔ 不能同时开启：auto_acquisition_enabled、live_recommend_strategy_enabled、aoi_optimization_strategy

控制成本（仅 SYSTEMATIC 可用）：

根据是否配置了 ROI 深度优化，选择对应字段（二选一，互斥）：

> 都需同时传 cost_constraint_scene: COST_CONSTRAINT_SCENE_OPEN

4B. 获取转化目标（仅 oCPM/oCPC 需要）

node scripts/get-conversions.mjs '{"account_id":"<ACCOUNT_ID>","site_set":["<用户表达的版位>"],"available_site_set":["<步骤3返回的全量可用版位>"],"non_multi_site_set":["<步骤3返回的non_multi_site_set>"],"marketing_carrier_id":"<步骤2返回的载体ID>","asset_id":"<步骤2返回的行业资产ID>","marketing_goal":"<MARKETING_GOAL_枚举key>","marketing_sub_goal":"<MARKETING_SUB_GOAL_枚举key>","marketing_carrier_type":"<MARKETING_CARRIER_TYPE_枚举key>","marketing_target_type":"<MARKETING_TARGET_TYPE_枚举key>","create_source_type":"<CreateSourceType的枚举值，用户未提及来源时不传此参数>"}'

> 注意：常规广告不需要传 delivery_scene。四元组字段统一传字符串枚举 key，脚本内部自动转为数值。bid_mode 来自步骤 4A 的出价方式（如 BID_MODE_OCPM），用于按出价方式过滤转化目标。

>

> create_source_type：如果用户指定了转化来源，则根据用户意图传入——PLATFORM平台转化或SELF_CREATED自建转化等。用户未提及来源时不传此参数。

>

> ⛔ site_set 参数来源：必须严格按步骤 3C 的规则传入——自动版位时传步骤 3 返回的 auto_site_set 完整数组（不是用户提到的"优先版位"子集），手动版位时传用户指定版位与 available_site_set 的交集。

>

> ⛔ available_site_set 参数：必须同时传入步骤 3 返回的 available_site_set 完整数组（即 get-site-set.mjs 返回的全量可用版位列表）。脚本内部会用 site_set ∩ available_site_set 取交集，作为防御性校验，确保只传入合法版位。即使你认为 site_set 已经是正确的子集，也必须传 available_site_set。

>

> ⛔ non_multi_site_set 参数：必须同时传入步骤 3 返回的 non_multi_site_set 数组（不支持多版位组合的版位列表，即 site_set_multi=0 的版位）。脚本内部会自动过滤掉这些版位（除非用户只选了一个版位），避免查询转化目标时传入不支持多版位组合的版位。

>

> ⛔ 行业产品库类（步骤 2 返回 asset_type: "INDUSTRY"） 传 asset_id！

>

> marketing_carrier_id 和 asset_id 是两个独立参数，由脚本按两个维度分别决定是否传给 API：

> - marketing_carrier_id（→ API 的 product_id）：传入 flat_params.carrier_id。脚本根据 marketing_carrier_type 判断是否传：除页面跳转 (JUMP_PAGE) 外的载体类型都传。

> - asset_id（→ API 的 marketing_asset_id）：仅行业产品库类需要传（asset_type: "INDUSTRY" 时），传入 flat_params.asset_id。ONEID 类和商品库类不需要传此字段。

> - 两者可以都传、只传一个、或都不传，互不排斥。

>

> ⛔ 特别注意：当 asset_type: "INDUSTRY" 时，必须将 flat_params.asset_id 作为 asset_id 传入本脚本，否则转化目标查询可能会失败！

脚本已处理：通过 access_status 过滤仅返回已完成接入的转化目标，标注深度转化类型，裁剪无关字段。

返回示例：

{
  "goals": [
    {
      "conversion_id": 12345,
      "name": "APP激活",
      "optimization_goal": "OPTIMIZATIONGOAL_APP_ACTIVATE",
      "bid_mode": "BID_MODE_OCPM",
      "has_deep_conversion": false,
      "create_source_type": "PLATFORM"
    },
    {
      "conversion_id": 12346,
      "name": "注册-首日付费ROI",
      "optimization_goal": "OPTIMIZATIONGOAL_APP_REGISTER",
      "bid_mode": "BID_MODE_OCPM",
      "has_deep_conversion": true,
      "deep_conversion_type": "DEEP_CONVERSION_WORTH",
      "deep_conversion_worth_goal": "OPTIMIZATIONGOAL_1DAY_PURCHASE_ROAS",
      "create_source_type": "SELF_CREATED"
    }
  ]
}

Agent 需要做的决策——conversion 选择规则：

1. 排除 permission=1 的项（脚本已过滤，但仍需意识到约束）
2. 用户提供了深度出价参数时（ROI 系数或行为出价金额），按以下三步选择：
• Step A — 确定出价字段：根据用户自然语言，参考文末「用户意图提取规则」表，确定对应的出价字段名（如 deep_conversion_worth_rate）
• Step B — 反推 deep_conversion_type：根据下方 4D 映射表，从出价字段名反推对应的 deep_conversion_type（如 deep_conversion_worth_rate → DEEP_CONVERSION_WORTH）
• Step C — 从 goals 中选择：在 goals 列表中，找 has_deep_conversion=true 且 deep_conversion_type 与 Step B 结果一致的转化ID。不同 deep_conversion_type 的 conversion_id 不可互换
3. 用户指定了优化目标（但没给深度出价参数） → 按 name 字段匹配
4. 用户未指定 → 取 goals 数组第一个项
5. 用户指定了转化创建来源（如"自建转化"/"自建归因"/"自建"/"自定义转化"→ SELF_CREATED，"平台预置"/"平台转化"/"平台上报"/"系统预置"/"预置转化"→ PLATFORM）→ 在调用 get-conversions.mjs 时传入 create_source_type 过滤；用户未提及来源时不传此参数

4C. 出价字段清单

4D. 深度转化优化

oCPM/oCPC 可选配置，前置条件：步骤 4B 的 get-conversions.mjs 返回中，选中的转化目标 has_deep_conversion=true。

⚠️ 二选一规则：深度/深度辅助出价一级扁平字段与 deep_conversion_spec 嵌套结构互斥，不能同时传：

常规广告使用 conversion_id，因此直接传一级扁平字段即可。

一级扁平字段示例（用户说"深度ROI 1.5"）：

{
  "conversion_id": 12345,
  "deep_conversion_worth_rate": 1.5
}

> deep_conversion_type 取自 get-conversions.mjs 返回，根据类型选用对应的一级出价字段：

> - DEEP_CONVERSION_WORTH → deep_conversion_worth_rate（深度ROI出价 / 深度转化价值率）

> - DEEP_CONVERSION_WORTH_ADVANCED → deep_conversion_worth_advanced_rate（深度辅助ROI）

> - DEEP_CONVERSION_BEHAVIOR → deep_conversion_behavior_bid（深度OG出价）

> - DEEP_CONVERSION_BEHAVIOR_ADVANCED → deep_conversion_behavior_advanced_bid（深度辅助OG出价）

>

> ⛔ 不同 deep_conversion_type 的 conversion_id 不可互换。例如 DEEP_CONVERSION_WORTH 对应的 conversion_id 和 DEEP_CONVERSION_WORTH_ADVANCED 对应的是不同的 conversion_id，必须根据脚本返回的 deep_conversion_type 精确选择。

强约束：

• conversion_id 只能来自：用户明确给出的 ID，或 get-conversions.mjs 返回
• 白名单例外：用户在原始需求中已明确给出完整的 conversion_id 数值 ID，则直接使用
• CPC/CPM 出价不需要 conversion_id
• optimization_goal 不需要传，API 会根据 conversion_id 自动推导

步骤 4 完成后你应该有：bid_mode、smart_bid_type、conversion_id（oCPM/oCPC时）；CUSTOM 还有 bid_amount，SYSTEMATIC 还有 daily_budget。

步骤 5：配置定向 + 投放时间

> 前置：用户意图中的定向需求

> 输出：targeting、begin_date、end_date、delivery_time_ranges

5A. 定向配置

常规广告拥有完整定向能力，支持地域、年龄、性别、兴趣、行为、人群包等多维度定向。

定向查询触发规则（命中任一项就必须先调用 get-targeting-lookup.mjs）：

• 用户给了地域、省市区、常驻地 → type: "geo"
• 用户给了设备品牌 / 型号 → type: "device"

不需要调用 get-targeting-lookup.mjs 的定向维度（脚本自动匹配枚举）：

• 性别：直接用 ["MALE"] / ["FEMALE"] / 不传
• 年龄：直接用 [{"min":25,"max":29}, {"min":30,"max":39}] 格式的数组。min 和 max 均为闭区间（包含边界值），即用户说"25~29岁"→ {"min":25,"max":29}，不是 {"min":25,"max":30}。每个区间对应用户给出的一段年龄范围，如果用户说了多个不同年龄段区间，就按照多个区间构造，不要合并连续段
• 排除已转化：通过 get-enum-options.mjs '{"fields":["excluded_dimension","excluded_day"]}' 查询枚举后构造
• 操作系统（user_os）：通过 get-enum-options.mjs '{"fields":["user_os"]}' 查询枚举值后构造（支持系统+版本号, 传 ["IOS"] / ["ANDROID"]（全版本），或用简化格式如 ["ANDROID_10+"] 表示 Android 10 及以上
• 排除操作系统（excluded_os）：通过 get-enum-options.mjs '{"fields":["excluded_os"]}' 查询枚举后构造，同 user_os 的简化格式，也支持 WINDOWS、HARMONY 等直接枚举
• 联网方式（network_type）：通过 get-enum-options.mjs '{"fields":["network_type"]}' 查询枚举后构造，传用户提到的联网方式即可，如 ["WIFI"]、["4G"]、["5G"]，脚本自动匹配为 API 枚举（如 4G → NET_4G）
• 学历（education）：通过 get-enum-options.mjs '{"fields":["education"]}' 查询枚举后构造，传中文即可，如 ["本科", "硕士"]，脚本自动匹配为 API 枚举（如 本科 → BACHELOR）
• 设备价格（device_price）：通过 get-enum-options.mjs '{"fields":["device_price"]}' 查询枚举后构造，传简化描述即可，如 ["2500以上"]、["1500-3500"]，脚本自动展开为对应的价格区间枚举
• 微信广告行为（wechat_ad_behavior）：通过 get-enum-options.mjs '{"fields":["wechat_ad_behavior_actions"]}' 查询枚举后构造，传中文即可，如 {"actions": ["注册过小游戏"], "mini_game_wechat_registered_activity": "30天未活跃"}，脚本自动匹配为 API 枚举
• 微信广告行为排除：通过 get-enum-options.mjs '{"fields":["wechat_ad_behavior_excluded_actions"]}' 查询枚举后构造
• 其他枚举定向（学历/联网方式/设备价格/婚恋状态等）：均通过 `get-enum-options.mjs 查询

> ⚠️ get-targeting-lookup.mjs 只支持 type: "geo" 和 type: "device" 两种查询，不支持 age、gender 等。年龄和性别不需要编码查询，直接用结构化值。

只有在以下情况才可跳过定向查询：用户完全没有给任何地域或设备定向约束。

> ⚠️ 通投（不限定向）时仍需传 targeting: {}（空对象），不要省略该字段。

地域编码查询：

node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"广东"}'
# 支持批量：keyword 用空格分隔
node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"北京 上海 广东"}'

> ⚠️ 地域查询效率规则（P0 级，违反会导致轮次耗尽被终止）：

> 1. 一次查完所有地域：脚本是本地文件查询，无数量限制。把用户给的所有城市名用空格拼接到一个 keyword 里一次调用即可，不要分批，不要逐个查询。即使 100+ 个城市也只需 1 次调用。

> 2. 省级优先原则：如果用户说"北京"、"广东"等省级地域，直接用省名查询，会返回省级编码（如 110000）。不要拆解为区级编码，除非用户明确列举了具体的区/市。

> 3. 不加行政区前缀：直接用城市名（如 "南宁 成都 杭州"），不要加"广西南宁"、"四川成都"等前缀。

> 4. 重名消歧：如果查询结果中有重名地域（如"朝阳区"同时返回北京和长春的），根据用户上下文和 parent 字段筛选正确的。

地域排除（用户表达"排除某省/不投某省/除 X 外全国投放"）：

调 get-geo-exclude.mjs，直接返回排除后剩余省份的编码，取 id 组成 regions 数组：

node scripts/get-geo-exclude.mjs '{"exclude":"河北"}'
# → {"results":[{"id":110000,"name":"北京市","level":"province"},{"id":120000,"name":"天津市","level":"province"},...]}

设备品牌型号 ID 查询：

node scripts/get-targeting-lookup.mjs '{"type":"device","keyword":"华为"}'

地域输出示例：

{
  "results": [
    {"id": 440000, "name": "广东省", "level": "province", `"city_level": 4}
  ]
}

设备输出示例：

{
  "results": [
    {"id": 10001, "name": "华为 Mate 60"},
    {"id": 10002, "name": "华为 P60"}
  ]
}

常规广告支持的完整定向维度（以下字段均放在 targeting: { ... } 对象内，不要放到请求体顶层）：

⛔ 所有枚举值禁止凭记忆猜测，必须通过 get-enum-options.mjs 查询确认：

# 查询单个/多个字段的枚举
node scripts/get-enum-options.mjs '{"fields":["education","device_price","excluded_dimension"]}'

# 按分类查询所有枚举
node scripts/get-enum-options.mjs '{"category":"targeting"}'    # 定向相关
node scripts/get-enum-options.mjs '{"category":"scene_spec"}'   # 场景定向
node scripts/get-enum-options.mjs '{"category":"bid"}'          # 出价相关
node scripts/get-enum-options.mjs '{"category":"conversion"}'   # 转化相关
node scripts/get-enum-options.mjs '{"category":"strategy"}'     # 探索策略
node scripts/get-enum-options.mjs '{"category":"switch"}'       # 开关类

可查询的枚举字段包括但不限于：gender、education、user_os、excluded_os、network_type、device_price、marital_status、app_install_status、location_types、excluded_dimension、excluded_day、wechat_ad_behavior_actions、wechat_ad_behavior_excluded_actions、bid_mode、smart_bid_type、deep_conversion_type、deep_conversion_goal、exploration_strategy、search_expand_targeting_switch、search_expansion_switch、cost_constraint_scene、configured_status、ecom_pkam_switch、smart_coupon_mode、live_recommend_strategy_enabled、dynamic_ad_type、short_play_pay_type、smart_targeting_mode、adx_realtime_type、game_consumption_level、conversion_behavior_list 等。

excluded_converted_audience 格式（⚠️ 仅在用户明确提到"排除已转化"时才添加，禁止自行添加）：

{
  "excluded_dimension": "<通过 get-enum-options.mjs 查 excluded_dimension>",
  "excluded_day": "<通过 get-enum-options.mjs 查 excluded_day>"
}

wechat_ad_behavior 格式（⚠️ 仅在用户明确提到微信广告行为排除时才添加，禁止自行添加）：

用户说"排除已关注公众号的用户"、"排除已注册小游戏的用户"等时，构造此字段。excluded_actions 的枚举通过 get-enum-options.mjs '{"fields":["wechat_ad_behavior_excluded_actions"]}' 查询。

"wechat_ad_behavior": {
  "excluded_actions": ["GDT_WECHAT_OFFICIAL_ACCOUNT_FOLLOWED"],
  "wechat_official_account_id": ["wx18c408376c727a19"]
}

• 涉及公众号行为时，需同时传 wechat_official_account_id（用户给的公众号 ID）
• 涉及企业微信行为时，需同时传 corp_id

强约束：

• 命中触发规则后，必须先调用 get-targeting-lookup.mjs 获取编码，再构造 targeting
• 不要把自然语言直接翻成粗粒度占位值
• targeting 是必填字段：即使用户没有明确表达任何定向需求，也必须传 targeting: {}（空对象），不能省略该字段
• targeting 及其子结构只传上方表格中列出的字段和子字段，不要自行推测或类推添加文档中未出现的字段

targeting 构造示例：

{
  "bid_amount": 5000,
  "targeting": {
    "age": [{"min": 25, "max": 29}, {"min": 30, "max": 39}],
    "gender": ["MALE"],
    "geo_location": {
      "regions": [440000, 310000],
      "location_types": ["LIVE_IN"]
    }
  }
}

无定向需求（通投）时传空对象："targeting": {}

5B. 投放时间与状态

delivery_time_ranges 格式说明：

数组中每条格式为:全时段/全天投放/未设置："all"；指定时段： " ~"，时间精度为半小时（只支持 :00 或 :30）；

示例：["all"]=全时段；["Monday 09:00~18:00",...,"Sunday 09:00~18:00"]=每天9点到18点（支持 Monday-Sunday ）

// 全时段（用户未指定投放时段）
"delivery_time_ranges": ["all"]
// 周二全天
"delivery_time_ranges": ["Tuesday 00:00~24:00"]
// 周一上午9点到12点，周二下午14点到18点
"delivery_time_ranges": ["Monday 09:00~12:00","Tuesday 14:00~18:00"]
// 周二全天
"delivery_time_ranges": ["Tuesday 00:00~24:00"]

时间精度规则：

• 时间只能是整点 :00 或半点 :30
• ⚠️ 如果用户说的时间不是整半小时（如 "10:00~10:15"），需要向用户确认：精度只支持半小时，可以选择 "10:00~10:30"（多了 15 分钟），请用户确认或调整
• ⚠️ end 边界规则：当用户说 "23:59"、"24:00"、"午夜" 或"投到当天结束"时，一律用 24:00 作为结束时间
• 星期名支持全称（Monday-Sunday）

Agent 需要做的：从用户自然语言中理解投放时段意图，转为 delivery_time_ranges 数组。常见自然语言映射：

• "全天投放" / 未指定 → ["all"]
• "工作日" → Monday 到 Friday
• "周末" → Saturday + Sunday
• "每天 X 到 Y" → 7 天都写上相同时段
• "某天" → 如果用户没有表达时间段默认 00:00~24:00，例如某天是星期二：Tuesday 00:00~24:00
• "排除周三下午" → 列出除周三下午外的所有时段，这时候agent需要列出其他有效的时段

步骤 5 完成后你应该有：targeting（如需）、begin_date、end_date、delivery_time_ranges。

步骤 6：组装请求体 → 创建广告组

> 前置：步骤 1-5 的所有输出

> 动作：按检查清单组装完整请求体，调用 create-adgroup.mjs

6A. 站点与版位

> ⚠️ priority_site_set（优先版位集合）：当 automatic_site_enabled: true 且用户同时指定了"优先投放某些版位"时使用。填入用户指定的版位枚举数组（参考步骤 3B 枚举表），系统会在自动版位的基础上优先在这些版位投放。

6B. 常规广告特有说明

• 不传 smart_delivery_platform — 这是常规广告，不是智投
• 不传 optimization_goal — API 会根据 conversion_id 自动推导，无需传此字段
• 可传 exploration_strategy — 版位探索策略，枚举值通过 get-enum-options.mjs '{"fields":["exploration_strategy"]}' 查询

6C. 创意控制字段

创意通过 dynamic_creatives/add 接口单独创建，adgroup 级别可传以下控制字段：

6D. 创建前自检（Pre-flight Check，⛔ 必须在调用 create-adgroup.mjs 前完成）

在组装完请求体后、真正调用创建接口前，逐项核对以下内容：

• 用户需求一致性：用户明确给出的每个条件（定向、出价、预算、三元组、商品等）是否都被原样保留在请求体中，未被丢弃、修改或替换
• 字段来源可追溯：四元组、转化目标、营销载体等关键字段是否来自实际脚本查询结果（而非猜测或编造）
• 编码已确认：定向条件中的地域编码、设备 ID 等是否经过查询脚本确认
• 金额单位正确：所有金额字段是否已转换为分

如有任何字段与用户原始需求不一致，必须停止并说明差异原因，等待用户确认后才能继续。

字段检查清单：

> ⚠️ 定向字段禁止自行添加：excluded_converted_audience、wechat_ad_behavior 等定向字段，只有用户明确要求时才加入 targeting。用户没提到的定向维度一律不传。

6E. 执行创建

node scripts/create-adgroup.mjs '<完整参数JSON>'

返回示例（成功）：

{
  "success": true,
  "adgroup_id": 987654321
}

返回示例（失败）：

{
  "success": false,
  "error": { "code": 1000014, "message": "...", "message_cn": "..." }
}

用户意图提取规则

| "搜索场景" | site_set | → 包含 SITE_SET_SEARCH_SCENE

⚠️ 四元组枚举值使用规则（防幻觉）

> 四元组的全部10个字段（营销内容：marketing_goal、marketing_sub_goal、marketing_carrier_type、marketing_target_type；转化/优化目标：optimization_goal、deep_behavior_optimization_goal、deep_behavior_advanced_goal、deep_worth_optimization_goal、deep_worth_advanced_goal、forward_link_assist）必须从 get-rules.mjs 返回的 combinations 中选取，禁止自行编造或语义改写。

> 例如 MARKETING_CARRIER_TYPE_MINI_GAME、MARKETING_GOAL_APP_MONETIZATION、MARKETING_CARRIER_TYPE_APP 这类"看起来合理但 API 不存在"的值，会直接导致报错。

> marketing_sub_goal 只能原样复用 get-rules.mjs 返回的 key，不能因为用户说了"注册"/"下载"就改写成自造枚举。

marketing_goal 意图速查（值域稳定，共 5 个）

marketing_target_type 易混淆速查（60+ 枚举，仅列易错项）

> 完整值域以 get-rules.mjs 返回为准，下表仅帮助区分易混淆项。

执行原则

1. ⛔ 用户原始需求不可修改（最高优先级原则）：

用户明确给定的所有业务条件（包括但不限于：定向条件、出价、预算、三元组、优化目标、商品、推广产品、广告名称等）在整个执行流程中绝对不可被修改、替换、省略或放宽，无论出于任何原因——包括 API 报错、冲突检测、字段校验失败、查询结果不匹配等。

• ❌ 禁止自动修改性别/年龄/地域/操作系统等定向来绕过错误或冲突
• ❌ 禁止自动更换商品或推广产品来绕过错误或冲突
• ❌ 禁止去掉定向限制（改为全量投放）来绕过错误或冲突
• ❌ 禁止更换三元组或优化目标来绕过错误或冲突
• ❌ 禁止用更宽泛的值替代用户给出的精确条件
• ❌ 禁止任何形式的未经用户确认的参数变更
• 如果因为用户给定的条件导致流程无法继续（如冲突、校验失败），必须立即停止并向用户如实报告问题，等待用户明确指示后才能继续。

1. 严格按步骤 1→(1A)→2→3→4→5→6 顺序执行；只有"显式证据白名单"或"出价方式快速路径"允许跳过对应查询；步骤 1A 在有资产线索且四元组未唯一确定时执行
2. CPC/CPM 出价时可跳过步骤 3 的版位查询（自动版位场景）、步骤 4B（转化目标查询）——参见执行协议中的"出价方式决定的步骤执行路径"表
3. 用户明确给出的结构化字段可直接复用，但只豁免该字段对应的查询，不会自动豁免其他步骤
4. 禁止把自然语言意图当作 API 返回值使用；中文描述只能用于筛选，不等于枚举值或 ID
5. 辅助查询失败时可以继续完成最终 API，但只能使用已确认字段；不能为了凑齐请求体编造四元组、营销载体 ID、定向枚举
6. 空字符串和 0 不是默认值：它们通常表示"你没有拿到真实结果"，不要拿来伪装步骤已完成
7. 只要用户给了定向条件，就不要省略步骤 5，也不要用更宽泛的值替代精确编码
8. 金额单位是分（10000分 = 100元）
9. 统一使用字符串枚举 key：四元组等字段始终传字符串 key（如 "MARKETING_GOAL_USER_GROWTH"），脚本内部负责转为 API 所需数值
10. campaign_id 不需要 — v3.0 展示广告中 adgroup 直接属于 account
11. 广告名称唯一性 — 同一账号下广告名称必须唯一
12. 有报错请提供 trace_id