腾讯营销投放-智投

name: tencentads-delivery-smart-create description: "专用于创建智投(AIM+)营销单元（原广告组）的 SDK 化技能。当用户意图涉及智投、AIM+、艾米、智能投放、自动投放、小店智投、smart delivery 的创建场景时，使用本技能。覆盖场景：小店艾米、商品艾米、线索艾米、内容艾米、APP艾米(游戏/阅读/AI应用)、小游戏跑量、爆剧跑量、小说智投、全域通、视频号直播智投等。本技能通过专用脚本（而非全局 CLI 工具）调用 API，脚本已处理复杂分支、字段过滤和数据转换。" license: MIT. See LICENSE for full terms. compatibility: any metadata: author: Tencent Ads Delivery Team version: "0.5.7" icon: megaphone category: tencent-ads

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

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

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

脚本调用格式统一：node scripts/<脚本名>.mjs '<JSON 参数>' 执行脚本时先进入本 skill 根目录，再按相对 scripts/ 路径调用。

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

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

⛔ PowerShell 5.x 是重灾区：单引号 '...'、反引号 `" 、反斜杠 \" 三种常见写法全部失败（双引号会被吞掉）。必须使用 --% 停止解析符或 \`" 组合转义。 ⛔ Windows CMD 不支持单引号包裹字符串，单引号会被当作普通字符传入脚本，导致 JSON 解析失败。

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

步骤1 → 步骤2 → 步骤3 → 步骤4 → 步骤5 → 步骤6 → 步骤7
确定      获取      获取       确定      获取      配置       组装请求体
智投场景  四元组    推广产品   版位      转化目标  定向+时段  → create-adgroup.mjs
                    +载体               +出价

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

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

1. ⛔ 步骤 1 → 2 → 3 是绝对必须执行的前三步，不可跳过。 即使用户 input 中看起来已包含场景、四元组、商品信息，仍必须调用 get-rules.mjs 确认四元组、调用 get-assets.mjs 获取推广资产 ID。原因：不同账号的可选组合不同，自然语言描述无法直接转为精确的枚举值和 ID。步骤 4-6 中的查询子动作在满足"显式证据白名单"时可跳过，但步骤 1-3 不可。
2. 进入下一步前，必须先拿到上一步输出并确认来源。 合法来源只有三类：用户在原始需求中明确给出、当前 session 前一步脚本返回、当前 session 前一步 API 返回。
3. 自然语言意图不能替代结构化字段。 "小游戏拉新""微信小游戏""新客增长"等描述只能用于步骤 1 识别场景，不能直接当作四元组、营销载体 ID、conversion_id 的依据。
4. 进入步骤 7 前必须能回答每个关键字段来自哪里。 说不清来源的字段，不要猜。
5. ⚠️ 错误处理与重试限制：每个脚本调用最多重试 1 次（换参数或换调用方式）。如果 2 次仍失败（如返回 "Mock not found"、空结果、报错），立即跳过该步骤，用已有数据继续推进到下一步直至步骤 7。严禁反复重试同一脚本、读取脚本源码、或切换到非脚本方式（如 tencent-ads api）尝试绕过。宁可在最终请求中缺少某个字段，也不要耗尽所有轮次。

   7w4.net收录了海量优质技能插件。

6. 显式证据白名单（仅适用于步骤 4-6 的查询子动作，步骤 1-3 不适用）：
7. 四元组查询：用户明确给出 marketing_goal、marketing_sub_goal、marketing_target_type、marketing_carrier_type 这 4 个枚举值全部；或当前 session 已从 get-rules.mjs 返回中得到。
8. 推广产品 / 营销载体查询：用户明确给出构造请求体所需的完整 ID；或当前 session 已从 get-assets.mjs 返回中得到。
9. 转化目标查询：用户明确给出 conversion_id；或当前 session 已从 get-conversions.mjs 返回中得到。
10. 定向查询：用户没有任何定向约束时可跳过；只要用户给了定向要求，地域/设备编码通过 get-targeting-lookup.mjs 查询，其他枚举通过 get-enum-options.mjs 查询。

步骤 1（⛔ 最先执行）：确定智投场景

前置：用户意图 输出：smart_delivery_platform、delivery_scene（数值）

根据用户意图从下表匹配 smart_delivery_platform 枚举值。枚举统一前缀 SMART_DELIVERY_PLATFORM_EDITION_（表中用 ... 省略）。

⚠️ 小店枚举名与中文业务名严重不一致：SINGLE_PRODUCT = 短直双开（不是"单品"），PRODUCT_OR_LIVE = 小店单链路（不是"品商直播合开"）。

步骤 1 完成后你应该有：smart_delivery_platform 枚举值，以及同场景的数值 delivery_scene（即上表 value 列）。

字段含义拆开记： - smart_delivery_platform：字符串枚举，如 SMART_DELIVERY_PLATFORM_EDITION_MINI_GAME_PROMOTION - delivery_scene：数值 value，如 1003 - 调 get-rules.mjs 时，delivery_scene 传 smart_delivery_platform 字符串枚举，不是数值 1003 - 调 get-conversions.mjs 等投放端内部接口时，再传数值 delivery_scene

步骤 2（⛔ 默认必须执行，仅白名单可跳过）：获取四元组

前置：account_id + 步骤 1 的 smart_delivery_platform 输出：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>","delivery_scene":"<smart_delivery_platform枚举值>"}'

示例：

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

脚本已处理：内部解析 rules_json 嵌套 JSON 字符串，展开四层嵌套树为扁平组合列表。

返回示例：

{
  "combinations": [
    {
      "marketing_goal": "MARKETING_GOAL_APP_PROMOTED",
      "marketing_sub_goal": "MARKETING_SUB_GOAL_APP_INSTALL",
      "marketing_target_type": "MARKETING_TARGET_TYPE_WECHAT_MINI_GAME",
      "marketing_carrier_type": "MARKETING_CARRIER_TYPE_MINI_PROGRAM"
    }
  ]
}

Agent 需要做的决策：从 combinations 中确定唯一的一组四元组。

情况 A：返回 1 个组合 → 直接确定

combinations 只有 1 条时，四元组已唯一确定，不需要任何选择逻辑，直接取该条进入步骤 3。

情况 B：返回多个组合 → 需要按规则选择

combinations 有多条时，按以下优先级从高到低逐层过滤，直到缩小为唯一一组。切忌乱猜四元组，一旦选错后续推广产品、转化目标等全部级联错误。

选择规则（按优先级）：

1. （最高优先级）通过资产 ID 反推：

触发条件：用户在 input 中明确给出了 推广产品ID、产品ID、推广资产ID、资产ID、应用ID、游戏ID、APP ID、marketing_asset_id、product_id、marketing_asset_outer_id 等资产标识。

资产 ID 能直接关联到某个 marketing_target_type，因此可反推缩小四元组范围。调用 get-assets-by-rules.mjs：

bash node scripts/get-assets-by-rules.mjs '{"account_id":"<ACCOUNT_ID>","combinations":<get-rules返回的combinations数组>}'

脚本内部自动对 marketing_target_type 去重，每种只调一次 API，返回 asset_map（以 marketing_target_type 为 key）。返回结构与 get-assets.mjs 完全一致（含 flat_params、type 等字段），可直接复用于步骤 3 的资产选择：

json { "asset_map": { "MARKETING_TARGET_TYPE_REAL_ESTATE": { "asset_type": "INDUSTRY", "assets": [ { "marketing_asset_id": "342574", "name": "京投发展森与天成", "type": "REAL_ESTATE", "flat_params": { "asset_id": "342574" } } ] }, "MARKETING_TARGET_TYPE_WECHAT_MINI_GAME": { "asset_type": "ONEID", "assets": [ { "marketing_asset_outer_id": "wx123", "marketing_carrier_id": "wx123", "name": "某小游戏", "type": "WECHAT_MINI_GAME", "flat_params": { "asset_id": "wx123", "carrier_id": "wx123", "asset_name": "某小游戏", "carrier_name": "某小游戏" } } ] } } }

反推流程： - 遍历 asset_map 各 target_type 下的 assets，用 flat_params.asset_id 统一匹配用户给出的资产 ID（无需区分 marketing_asset_id / marketing_asset_outer_id / product_outer_id，flat_params.asset_id 已归一化） - 找到 → 确定了该资产所属的 marketing_target_type，在 combinations 中筛选含该 target_type 的组合。若缩小到唯一一组，四元组确定；若仍有多组（同一 target_type 对应多个 goal/carrier），继续走后续规则。同时直接保存该资产的 flat_params，步骤 3 选资产时无需再查 - 找不到 → 资产 ID 反推失败，不代表用户给的 ID 是错的（例如小游戏 ID 可能不在 API 返回的列表中），跳过此规则，继续按后续规则选择

1. 从用户意图提取关键约束：
2. 用户提到了"直播"/"直播间"/"视频号直播" → marketing_carrier_type 应含 WECHAT_CHANNELS_LIVE
3. 用户提到了"小游戏" → marketing_target_type 应含 WECHAT_MINI_GAME
4. 用户提到了"小程序" → marketing_target_type 应含 MINI_PROGRAM_WECHAT
5. 用户提到了"小店商品"/"商品页" → marketing_target_type 应含 WECHAT_STORE_PRODUCT
6. 用户提到了"跳转页面" → marketing_carrier_type 应含 JUMP_PAGE

7. 用户提到了"APP"/"应用" → marketing_carrier_type 应含 APP_ANDROID 或 APP_IOS

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

9. 用户提到"卖货"/"下单"/"成交"/"GMV"/"ROI" → MARKETING_GOAL_PRODUCT_SALES
10. 用户提到"拉新"/"注册"/"激活"/"付费" → MARKETING_GOAL_USER_GROWTH
11. 用户提到"品牌"/"曝光" → MARKETING_GOAL_BRAND_PROMOTION
12. 用户提到"涨粉"/"加关注" → MARKETING_GOAL_INCREASE_FANS_INTERACTION

13. 用户提到"留资"/"表单"/"线索" → MARKETING_GOAL_LEAD_RETENTION

14. 短直双开场景特殊规则：短直双开（WECHAT_STORE_SINGLE_PRODUCT）有两条链路（直播+短视频），只需创建一条广告组。按照直播链路选择四元组——即 marketing_carrier_type = MARKETING_CARRIER_TYPE_WECHAT_CHANNELS_LIVE、marketing_target_type = MARKETING_TARGET_TYPE_WECHAT_CHANNELS_LIVE。

15. 若过滤后仍有多个组合 → 必须向用户确认，禁止猜测。将剩余的所有组合选项列出给用户选择。

16. marketing_sub_goal 只能复用 get-rules.mjs 返回值，禁止语义改写：例如用户说"注册"、"新客"时，不要自造 MARKETING_SUB_GOAL_USER_REGISTER；必须原样使用返回的枚举值。

智投强约束：delivery_scene 参数传的是 smart_delivery_platform 字符串枚举，不是数值。

步骤 2 完成后你应该有：四元组 4 个值（从 combinations 数组的匹配项取）。

步骤 3：获取推广产品 + 营销载体

前置：步骤 2 的 marketing_target_type 输出：选定 asset 的 flat_params（ONEID 类和视频号直播类已包含 carrier_id；行业/商品库类不含 carrier_id，若 carrier_type 需要载体则需从用户处获取）

调用方式：

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

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

返回示例：

{
  "asset_type": "ONEID",
  "assets": [
    {
      "marketing_asset_outer_id": "wx1234567890",
      "marketing_carrier_id": "wx1234567890",
      "name": "以闪亮之名",
      "type": "WECHAT_MINI_GAME",
      "flat_params": {
        "asset_id": "wx1234567890",
        "carrier_id": "wx1234567890",
        "asset_name": "以闪亮之名",
        "carrier_name": "以闪亮之名"
      }
    }
  ]
}

重要：如果步骤 2 中已通过 get-assets-by-rules.mjs 获取了 asset_map，且当前 marketing_target_type 在 map 中已有结果，可复用该结果，无需再调 get-assets.mjs。

Agent 需要做的决策：从返回的资产列表中确定用户要使用的资产。

资产选择规则（按优先级）：

1. 用户给了资产 ID（marketing_asset_id、product_id、marketing_asset_outer_id 等）：
2. 在资产列表中找到 → 直接使用
3. 在资产列表中找不到 → 不判定为错误，保留用户给的 ID 继续流程，交给后台接口校验
4. 用户给了资产名称但没给 ID → 按名称模糊匹配资产列表，匹配到 1 条直接使用，匹配到多条列出让用户选
5. 用户未提及任何资产信息 → 若只有 1 条资产直接使用；若有多条，展示列表让用户确认选择

3A. 字段组装规则（flat_params 直接透传）

选定资产后，直接使用该 asset 的 flat_params 对象，在调用 create-adgroup.mjs 时将 flat_params 里的 key-value 展开到请求体顶层即可。create-adgroup.mjs 会根据 marketing_target_type 自动组装 API 所需的嵌套结构（marketing_asset_outer_spec / marketing_asset_id / marketing_carrier_detail）。

flat_params 各字段含义（与 create-adgroup.mjs 方式一入参完全对齐，共 7 个）：

多传无害：asset_name、carrier_name 在非 QUICK_APP / PC_GAME 类型时，create-adgroup.mjs 内部会自动过滤掉，不会传给 API。

示例——Agent 选定 asset 后传给 create-adgroup.mjs 的参数：

{
  "account_id": "123456789",
  "adgroup_name": "...",
  "marketing_target_type": "MARKETING_TARGET_TYPE_WECHAT_MINI_GAME",
  "asset_id": "wx1234567890",
  "carrier_id": "wx1234567890",
  "asset_name": "以闪亮之名",
  "carrier_name": "以闪亮之名",
  "...其他字段..."
}

上面的 asset_id、carrier_id、asset_name、carrier_name 都是从 assets[n].flat_params 里展开的。

不再需要手动组装以下嵌套结构（create-adgroup.mjs 自动处理）： - ❌ 不需要手动构造 marketing_asset_outer_spec - ❌ 不需要手动构造 marketing_carrier_detail - ❌ 不需要手动设置 marketing_asset_id（行业类） - ✅ 只需把 flat_params 展开透传

3B. 强约束

• 白名单例外：用户在原始需求里已明确给出完整 ID（如 product_id、marketing_asset_outer_id、catalog_id、product_outer_id、marketing_asset_id、marketing_carrier_id），则可直接使用并跳过查询。
• 空字符串不是合法结果：不要把空字符串当作"已完成步骤 3"。查不到且用户也未提供时，保留缺失状态。
• 字段名强约束：marketing_asset_outer_spec 里使用 marketing_asset_outer_id / marketing_asset_outer_sub_id，不要写 outer_id / outer_sub_id。

步骤 3 完成后你应该有：选定 asset 的 flat_params（包含 asset_id、carrier_id 等，将在步骤 7 展开透传给 create-adgroup.mjs）。

步骤 4（⛔ 默认必须执行）：获取版位列表

前置：步骤 1 的 smart_delivery_platform + 步骤 2 的四元组 输出：site_set（数组），仅供后续 get-conversions.mjs 使用

智投场景下版位固定为智能版位（系统将智能进行版位择优投放），用户不可选择或修改。如果用户提到了版位相关需求，应告知用户：「智投场景下版位为系统智能择优投放，无需手动选择」。

本步骤的唯一目的是获取当前场景的 site_set 列表，供步骤 5 查询转化目标时使用。

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>"}'

返回：

{
  "auto_site_set": ["SITE_SET_WECHAT", "SITE_SET_MOBILE_UNION"]
}

• site_set 列表是动态的，不要手写示例数组
• 后续 get-conversions.mjs 必须使用此处返回的真实 site_set

步骤 4 完成后你应该有：site_set 数组（来自脚本返回）。

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

前置：步骤 1 的 delivery_scene（数值）+ 步骤 2 的四元组 + 步骤 4 的 site_set 输出：conversion_id、bid_amount、出价相关字段

5A. 获取转化目标

node scripts/get-conversions.mjs '{"account_id":"<ACCOUNT_ID>","delivery_scene":<数值>,"site_set":["..."],"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的枚举值，用户未提及来源时不传此参数>"}'

注意：get-conversions.mjs 的入参中，四元组字段统一传字符串枚举 key（如 "MARKETING_GOAL_USER_GROWTH"），脚本内部自动转为数值。不需要传 product_type、live_video_mode、live_video_sub_mode，脚本会根据 marketing_carrier_type + delivery_scene 自动推导。delivery_scene 传步骤 1 的数值。

特别注意 marketing_sub_goal：这里传的必须是步骤 2 选中的原始 key，不能因为用户说了"注册"、"下载"、"安装"，或转化名称里带这些词，就改写成 MARKETING_SUB_GOAL_USER_REGISTER、MARKETING_SUB_GOAL_MINI_GAME_APP_INSTALL 之类的自造枚举。

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

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

返回示例：

{
  "goals": [
    {
      "conversion_id": 12345,
      "name": "小游戏注册",
      "optimization_goal": "OPTIMIZATIONGOAL_APP_REGISTER",
      "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_MONETIZATION_ROAS_7DAY",
      "create_source_type": "SELF_CREATED"
    }
  ]
}

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

1. 用户提供了 ROI 系数 → 必须选 has_deep_conversion=true 的转化ID
2. 用户未提供 ROI 系数 → 选与用户指定优化目标匹配的项
3. 用户未指定 → 取 goals 数组第一个项
4. 用户指定了转化创建来源（如"自建转化"/"自建归因"/"自建"/"自定义转化"→ SELF_CREATED，"平台预置"/"平台转化"/"平台上报"/"系统预置"/"预置转化"→ PLATFORM）→ 在调用 get-conversions.mjs 时传入 create_source_type 过滤；用户未提及来源时不传此参数

强约束： - conversion_id 只能来自：用户明确给出的 ID，或 get-conversions.mjs 返回 - 白名单例外：用户在原始需求中已明确给出 conversion_id 数值 ID，则直接使用 - conversion_id: 0 视为错误占位，不可提交 - 若用户未明确给出且也没有成功查询到，不要编造 0、空字符串或占位值

5B. 出价字段

智投出价核心规则： 1. conversion_id 和 bid_amount 放在请求体顶层 2. 不需要传 optimization_goal — 智投的优化目标隐含在 conversion_id 中 3. 金额单位是分（10000分 = 100元） 4. deep_conversion_worth_rate 和 deep_conversion_worth_advanced_rate 是两个不同字段，支持3位小数

步骤 5 完成后你应该有：conversion_id（顶层，非 0，非空）、bid_amount、出价相关可选字段。

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

前置：用户意图中的定向需求 输出：targeting、begin_date、end_date、delivery_time_ranges

6A. 定向配置

• 用户未提及任何定向时（通投）→ targeting 传空对象 {}，跳过以下所有定向步骤，直接进入 6B
• 用户有定向需求时 → 按下方规则构造 targeting

智能定向模式（smart_targeting_mode）

⚠️ smart_targeting_mode 是请求体顶层字段（不在 targeting 对象内），控制定向方式——AI 自动探索还是人工圈选。与 targeting 内的定向内容字段（地域/年龄/性别等）是不同层级的概念。

• 用户说"不使用智能定向"/"关闭智能定向"/"手动定向" → 传 "smart_targeting_mode": "SMART_TARGETING_MANUAL"
• 用户说"使用智能定向"/"开启智能定向" → 传 "smart_targeting_mode": "SMART_TARGETING_AUTO"
• 用户未提及 → 不传此字段

不同智投场景支持的定向维度不同。如果传入了当前场景不支持的定向字段，创建时会报错并列出不支持的字段。收到此报错后，告知用户输入合适的定向。

智投广告支持完整定向能力，包括地域、年龄、性别、操作系统、学历、设备价格、微信广告行为等多维度定向。

定向查询触发规则（命中任一项就必须先调用 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 等。年龄和性别不需要编码查询，直接用结构化值。

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

地域编码查询：

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"}'

可查询的定向枚举字段包括：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、smart_targeting_mode。

⚠️ 智投场景下，出价方式（bid_mode）固定为 BID_MODE_OCPM，转化目标从 get-conversions.mjs 返回获取，版位策略固定为自动版位 —— 这些字段不需要通过 get-enum-options.mjs 查询。get-enum-options.mjs 在智投中仅用于定向枚举查询。

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 及其子结构只传上方表格中列出的字段和子字段，不要自行推测或类推添加文档中未出现的字段 - ⛔ 所有枚举值禁止凭记忆猜测，必须通过 get-enum-options.mjs 查询确认

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"]
    }
  }
}

6B. 投放时间与状态

delivery_time_ranges 格式说明：

数组中每条格式为:全时段/全天投放/未设置："all"；指定时段： "<Weekday> <HH:MM>~<HH:MM>"，时间精度为半小时（只支持 :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 - "排除周三下午" → 列出除周三下午外的所有时段

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

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

前置：步骤 1-6 的所有输出 动作：按检查清单组装完整请求体，调用 create-adgroup.mjs

7A. 版位与探索策略（智投固定值，脚本自动处理）

7B. 智投专有字段

smart_delivery_aigc_creative（AIGC自动创意）：

// 关闭
{"is_open": false, "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_AIGC"]}
// 开启
{"is_open": true, "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_AIGC"]}

smart_delivery_history_comp_reused_creative（全库智选）：

// 关闭
{"is_open": false, "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_HISTORY_COMP_REUSE"]}
// 开启
{"is_open": true, "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_HISTORY_COMP_REUSE"]}

⚠️ 废弃字段：不要使用 smart_delivery_scene_spec、smart_delivery_auto_creative、aigc_creative_switch。

爆剧跑量场景专有字段

当 smart_delivery_platform = SMART_DELIVERY_PLATFORM_EDITION_ECOLOGY_PLAYLET（爆剧跑量）时，支持设置短剧售卖方式和场景规格。脚本自动校验：收费剧必须提供售卖策略 ID。

• short_play_pay_type：SHORT_PLAY_PAY_TYPE_FREE_PLAY（免费剧）/ SHORT_PLAY_PAY_TYPE_CHARGE_PLAY（收费剧）
• sell_strategy_id：收费剧时必填，免费剧不需要

枚举值、校验规则、请求体示例详见 references/short-play-pay-type.md

周期达成（Period Completion）：

完整字段定义、约束规则和 JSON 示例见 references/smart-delivery-period.md（可通过 load_skill_reference 加载）。以下是关键要点：

• 触发条件：仅在用户明确提出"周期达成"/"周期稳投"需求时才开启，不要自行添加
• 必填字段：smart_delivery_period_switch=PERIOD_SWITCH_ON + smart_delivery_period_days + smart_delivery_period_budget + smart_delivery_period_continue
• 预算约束：smart_delivery_period_budget ≥ 3 × bid_amount × 周期天数
• 禁止字段：开启时不允许传 daily_budget、total_budget；end_date 由脚本统一设为 ""，后端根据 begin_date + 周期天数自动计算实际结束日期
• 出价限制：不允许使用自动出价（smart_bid_type 不能为 SMART_BID_TYPE_SYSTEMATIC）
• 支持场景：线索智投（SMART_DELIVERY_PLATFORM_EDITION_ECOLOGY_LEADS）

⛔ 创意字段场景化必填规则（P0 级，脚本会校验拦截）

以下两条规则由 create-adgroup.mjs 自动校验，不满足时会报错拦截。Agent 必须在组装请求体时主动满足这些规则，避免被脚本拦截。

规则 A：视频号直播场景必填 sku_id + catalog_id

三个条件同时满足时，smart_delivery_aigc_creative为开启状态时，必须额外包含： - sku_id（string）— 商品 SKU ID - catalog_id（integer）— 商品目录 ID

这两个值需要从用户处获取。如果用户未提供，必须向用户询问，不可省略。

// 视频号直播场景 AIGC 创意（开启 + sku_id + catalog_id）
{
  "smart_delivery_aigc_creative": {
    "is_open": true,
    "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_AIGC"],
    "sku_id": "10000299440478",
    "catalog_id": 1023958
  }
}

规则 B：非视频号直播场景必填品牌形象

三个条件同时满足时，smart_delivery_aigc_creative 或 smart_delivery_history_comp_reused_creative处于开启状态时，必须满足： 1. 在 creative_components.brand 数组中填写至少一个 component_id（品牌形象组件 ID） 2. 在 supply_strategy_type 数组中包含 SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION（与原有策略类型并存） 3. 注意：SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION 必须和原有的策略类型并存，不能单独使用。 结构示例：

// 非视频号直播场景 AIGC 创意（开启 + 品牌形象）
{
  "smart_delivery_aigc_creative": {
    "is_open": true,
    "supply_strategy_type": [
      "SUPPLY_STRATEGY_TYPE_AIGC",
      "SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION"
    ],
    "creative_components": {
      "brand": [{"component_id": 1917953657934}]
    }
  }
}
// 非视频号直播场景 组件全库智选（开启 + 品牌形象）
{
  "smart_delivery_history_comp_reused_creative": {
    "is_open": true,
    "supply_strategy_type": [
      "SUPPLY_STRATEGY_TYPE_HISTORY_COMP_REUSE",
      "SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION"
    ],
    "creative_components": {
      "brand": [{"component_id": 1917953657934}]
    }
  }
}

⚠️ 注意：SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION 和 creative_components.brand 必须同时存在，缺一不可。只传 brand 不加策略类型、或只加策略类型不传 brand，都会导致创建失败。

7C. project_ability_list（全店托管多商品场景）

适用场景：smart_delivery_platform = SMART_DELIVERY_PLATFORM_EDITION_WECHAT_STORE_MANAGEMENT（全店托管）且用户指定了多个商品时，或任何需要传入多个商品营销表达式的场景。

规则： - 当用户指定多个商品（如"含2个商品"、"商品A和商品B"）时，每个商品对应一条 project_ability_list 项 - project_ability_list 替代顶层的 marketing_asset_outer_spec：各商品的 asset 信息放入每个 item 的 marketing_expression.marketing_asset_outer_spec 内 - 四元组（marketing_goal、marketing_sub_goal、marketing_carrier_type）在每个 item 内重复

结构示例（2个微信小店商品，营销载体为跳转页面）：

{
  "project_ability_list": [
    {
      "project_ability_type": "ABILITY_TYPE_MARKETING_EXPRESSION",
      "ability_content": {
        "marketing_expression": {
          "marketing_goal": "MARKETING_GOAL_PRODUCT_SALES",
          "marketing_sub_goal": "MARKETING_SUB_GOAL_UNKNOWN",
          "marketing_carrier_type": "MARKETING_CARRIER_TYPE_JUMP_PAGE",
          "marketing_asset_outer_spec": {
            "marketing_target_type": "MARKETING_TARGET_TYPE_WECHAT_STORE_PRODUCT",
            "marketing_asset_outer_id": "<catalog_id>",
            "marketing_asset_outer_sub_id": "<product_outer_id_1>"
          }
        }
      }
    },
    {
      "project_ability_type": "ABILITY_TYPE_MARKETING_EXPRESSION",
      "ability_content": {
        "marketing_expression": {
          "marketing_goal": "MARKETING_GOAL_PRODUCT_SALES",
          "marketing_sub_goal": "MARKETING_SUB_GOAL_UNKNOWN",
          "marketing_carrier_type": "MARKETING_CARRIER_TYPE_JUMP_PAGE",
          "marketing_asset_outer_spec": {
            "marketing_target_type": "MARKETING_TARGET_TYPE_WECHAT_STORE_PRODUCT",
            "marketing_asset_outer_id": "<catalog_id>",
            "marketing_asset_outer_sub_id": "<product_outer_id_2>"
          }
        }
      }
    }
  ]
}

字段来源： - catalog_id（即 marketing_asset_outer_id）和 product_outer_id（即 marketing_asset_outer_sub_id）来自步骤 3 get-assets.mjs 返回的 assets[n].catalog_id 和 assets[n].product_outer_id - 单商品场景仍用顶层 marketing_asset_outer_spec，无需 project_ability_list

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

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

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

字段检查清单（20项）：

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

7E. 执行创建

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

返回示例（成功）：

{
  "success": true,
  "adgroup_id": <integer>,
  "summary_text": "<由脚本拼装的单句中文回执，包含创建关键信息>"
}

返回示例（失败）：

{
  "success": false,
  "error": { "code": <integer>, "message": "...", "message_cn": "..." }
}

⛔ 创建成功后必须将 summary_text 原样输出给用户（含其中的换行）。该字段已由脚本拼装好首行标题 + 多行列表的中文回执，不要省略字段、不要改写、不要翻译、不要重新排版（不要改成表格或合并成单段），也不要参考其中具体数值作为后续推理依据。失败时无 summary_text，按 error.message_cn 与 trace_id 向用户说明原因。

用户意图提取规则

执行原则

1. ⛔ 用户原始需求不可修改（最高优先级原则）： 用户明确给定的所有业务条件（包括但不限于：定向条件、出价、预算、三元组、优化目标、商品、推广产品、广告名称等）在整个执行流程中绝对不可被修改、替换、省略或放宽，无论出于任何原因——包括 API 报错、冲突检测、字段校验失败、查询结果不匹配等。
2. ❌ 禁止自动修改性别/年龄/地域/操作系统等定向来绕过错误或冲突
3. ❌ 禁止自动更换商品或推广产品来绕过错误或冲突
4. ❌ 禁止去掉定向限制（改为全量投放）来绕过错误或冲突
5. ❌ 禁止更换三元组或优化目标来绕过错误或冲突
6. ❌ 禁止用更宽泛的值替代用户给出的精确条件
7. ❌ 禁止任何形式的未经用户确认的参数变更
8. 如果因为用户给定的条件导致流程无法继续（如冲突、校验失败），必须立即停止并向用户如实报告问题，等待用户明确指示后才能继续。
9. 严格按步骤 1→2→3→4→5→6→7 顺序执行；只有"显式证据白名单"允许跳过对应查询
10. 用户明确给出的结构化字段可直接复用，但只豁免该字段对应的查询，不会自动豁免其他步骤
11. 禁止把自然语言意图当作 API 返回值使用；中文描述只能用于筛选，不等于枚举值或 ID
12. 辅助查询失败时可以继续完成最终 API，但只能使用已确认字段；不能为了凑齐请求体编造四元组、conversion_id、营销载体 ID、定向枚举
13. 空字符串和 0 不是默认值：它们通常表示"你没有拿到真实结果"，不要拿来伪装步骤已完成
14. 只要用户给了定向条件，就不要省略步骤 6，也不要用更宽泛的值替代精确编码
15. 金额单位是分（10000分 = 100元）
16. 统一使用字符串枚举 key：四元组等字段始终传字符串 key（如 "MARKETING_GOAL_USER_GROWTH"），脚本内部负责转为 API 所需数值

这个 Skill 质量较好，文档非常详细，操作步骤清晰，脚本能自动处理复杂的数据转换，省去了很多手动配置的麻烦。优点是覆盖场景全、参数校验完善，跨平台兼容性也考虑得很周到。不足之处是文档内容太多需要花时间消化，操作步骤较繁琐，对新手不太友好。整体而言，这是一个成熟可用的技能，但需要仔细阅读文档才能用好。