Tencentads Delivery Smart Create

---
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.8"
  icon: megaphone
  category: tencent-ads
---

> **前置依赖**：需安装 `tencentads-cli`（Node.js ≥ 20）。执行 `npm install -g tencentads-cli@latest` 安装或升级；版本过低时 `tencentads` 会给出提示。

本技能是智投广告的**执行指南**——按 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`）。

| 终端环境 | 正确写法 | 说明 |
|---------|---------|------|
| **Linux / macOS (Bash/Zsh)** | `node scripts/xxx.mjs '{"key":"value"}'` | ✅ 单引号包裹，内部双引号原样保留 |
| **Windows Git Bash** | `node scripts/xxx.mjs '{"key":"value"}'` | ✅ 同 Bash |
| **Windows CMD** | `node scripts/xxx.mjs "{\"key\":\"value\"}"` | ✅ 双引号包裹 + 反斜杠转义 |
| **Windows CMD (备选)** | `node scripts/xxx.mjs "{""key"":""value""}"` | ✅ 双引号包裹 + 双双引号转义 |
| **Windows PowerShell 5.x** | `node --% scripts/xxx.mjs "{\"key\":\"value\"}"` | ✅ 必须加 `--%` 停止解析符 |
| **Windows PowerShell 5.x (备选)** | `` node scripts/xxx.mjs "{\`"key\`":\`"value\`"}" `` | ✅ 反斜杠 + 反引号组合转义 |

> **⛔ 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**。严禁反复重试同一脚本、读取脚本源码、或切换到非脚本方式（如 `tencentads-cli api`）尝试绕过。宁可在最终请求中缺少某个字段，也不要耗尽所有轮次。
6. **显式证据白名单（仅适用于步骤 4-6 的查询子动作，步骤 1-3 不适用）**：
   - 四元组查询：用户明确给出 `marketing_goal`、`marketing_sub_goal`、`marketing_target_type`、`marketing_carrier_type` 这 4 个枚举值全部；或当前 session 已从 `get-rules.mjs` 返回中得到。
   - 推广产品 / 营销载体查询：用户明确给出构造请求体所需的完整 ID；或当前 session 已从 `get-assets.mjs` 返回中得到。
   - 转化目标查询：用户明确给出 `conversion_id`；或当前 session 已从 `get-conversions.mjs` 返回中得到。
   - 定向查询：用户没有任何定向约束时可跳过；只要用户给了定向要求，地域/设备编码通过 `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` = 小店单链路（不是"品商直播合开"）。

| 分类 | 场景名称 | 枚举 key | value | 识别关键词 |
|------|----------|----------|-------|-----------|
| 小店(3000) | 短直双开 | `..._WECHAT_STORE_SINGLE_PRODUCT` | `3001` | 短直双开、短视频+直播、双链路 |
| 小店(3000) | 小店单链路智投 | `..._WECHAT_STORE_PRODUCT_OR_LIVE` | `3002` | 单链路、小店单链路 |
| 小店(3000) | 全店托管智投 | `..._WECHAT_STORE_MANAGEMENT` | `3003` | 全店托管、托管 |
| 小店(3000) | 推直播间 | `..._WECHAT_STORE_LIVE` | `3004` | 推直播间、直播间引流 |
| 小店(3000) | 推商品 | `..._WECHAT_STORE_PRODUCT` | `3005` | 推商品（仅指小店的"推商品"入口，不带"智投"二字） |
| 生态(1000) | 爆剧跑量 | `..._ECOLOGY_PLAYLET` | `1001` | 爆剧、短剧、微短剧 |
| 生态(1000) | 线索跑量 | `..._ECOLOGY_LEADS` | `1002` | 线索艾米、线索跑量、表单 |
| 生态(1000) | 小游戏跑量 | `..._MINI_GAME_PROMOTION` | `1003` | 小游戏 |
| 生态(1000) | 商品智投 | `..._DRUG_PRODUCT` | `1018` | 商品艾米、商品智投、推商品智投、医药智投（注意：带"智投"二字的"推商品智投"属于此场景，不是小店的"推商品"） |
| 生态(1000) | 小说智投 | `..._FICTION` | `1019` | 小说、网文 |
| 全域通(4000) | 全域通-直播 | `..._QYT_LIVE` | `4001` | 全域通+直播 |
| 全域通(4000) | 全域通-直购 | `..._QYT_WECHAT_STORE` | `4002` | 全域通+直购/小店 |
| APP(6000) | 游戏应用智投 | `..._GAME_APP` | `6001` | 游戏APP、游戏应用 |
| APP(6000) | 阅读应用智投 | `..._READING_APP` | `6002` | 阅读APP、阅读应用 |
| APP(6000) | AI应用智投 | `..._AI_APP` | `6003` | AI应用、AI APP |

**步骤 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` 可能完全不同
- 四元组错误会级联导致后续推广产品、转化目标等全部错误

**调用方式**：

```bash
node scripts/get-rules.mjs '{"account_id":"<ACCOUNT_ID>","delivery_scene":"<smart_delivery_platform枚举值>"}'
```

示例：
```bash
node scripts/get-rules.mjs '{"account_id":"123456789","delivery_scene":"SMART_DELIVERY_PLATFORM_EDITION_MINI_GAME_PROMOTION"}'
```

**脚本已处理**：内部解析 `rules_json` 嵌套 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 返回的列表中），跳过此规则，继续按后续规则选择

2. **从用户意图提取关键约束**：
   - 用户提到了"直播"/"直播间"/"视频号直播" → `marketing_carrier_type` 应含 `WECHAT_CHANNELS_LIVE`
   - 用户提到了"小游戏" → `marketing_target_type` 应含 `WECHAT_MINI_GAME`
   - 用户提到了"小程序" → `marketing_target_type` 应含 `MINI_PROGRAM_WECHAT`
   - 用户提到了"小店商品"/"商品页" → `marketing_target_type` 应含 `WECHAT_STORE_PRODUCT`
   - 用户提到了"跳转页面" → `marketing_carrier_type` 应含 `JUMP_PAGE`
   - 用户提到了"APP"/"应用" → `marketing_carrier_type` 应含 `APP_ANDROID` 或 `APP_IOS`

3. **按 `marketing_goal` 匹配用户的营销目标**：
   - 用户提到"卖货"/"下单"/"成交"/"GMV"/"ROI" → `MARKETING_GOAL_PRODUCT_SALES`
   - 用户提到"拉新"/"注册"/"激活"/"付费" → `MARKETING_GOAL_USER_GROWTH`
   - 用户提到"品牌"/"曝光" → `MARKETING_GOAL_BRAND_PROMOTION`
   - 用户提到"涨粉"/"加关注" → `MARKETING_GOAL_INCREASE_FANS_INTERACTION`
   - 用户提到"留资"/"表单"/"线索" → `MARKETING_GOAL_LEAD_RETENTION`

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

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

6. **`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` 需要载体则需从用户处获取）

**调用方式**：

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

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

**返回示例**：
```json
{
  "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` 等）：
   - **在资产列表中找到** → 直接使用
   - **在资产列表中找不到** → **不判定为错误**，保留用户给的 ID 继续流程，交给后台接口校验
2. **用户给了资产名称但没给 ID** → 按名称模糊匹配资产列表，匹配到 1 条直接使用，匹配到多条列出让用户选
3. **用户未提及任何资产信息** → 若只有 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 个）：

| flat_params key | 含义 | 来源 |
|----------------|------|------|
| `asset_id` | 推广产品 ID | ONEID→outer_id / 行业→asset_id / 商品库→catalog_id |
| `carrier_id` | 载体 ID | ONEID 类和视频号直播类→自动填入（= outer_id，和 asset_id 同值）；⚠️ **行业/商品库类不含此字段**，若 `carrier_type` 需要载体则需从用户处获取后补入 |
| `catalog_id` | 商品目录 ID | 仅商品库类 |
| `asset_sub_id` | 子标识 | 商品库→product_outer_id；直播预约→notice_id（需 Agent 从 live_notices 中选择后补入） |
| `asset_name` | 资产名称 | ONEID 类自动填入 asset 的 name；create-adgroup.mjs 写入 `marketing_asset_outer_name`（仅 APP_QUICK_APP / PC_GAME 生效） |
| `carrier_name` | 载体名称 | ONEID 类自动填入 asset 的 name；create-adgroup.mjs 写入 `marketing_carrier_name`（仅 QUICK_APP / PC_GAME 载体类型生效，其他类型自动忽略） |
| `sub_carrier_id` | 载体子标识 | 直播预约→notice_id（需 Agent 从 live_notices 中选择后补入）；create-adgroup.mjs 写入 `marketing_sub_carrier_id` |

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

**示例——Agent 选定 asset 后传给 create-adgroup.mjs 的参数**：
```json
{
  "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 查询转化目标时使用**。

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

**返回**：
```json
{
  "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. 获取转化目标

```bash
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` 过滤仅返回已完成接入的转化目标，标注深度转化类型，裁剪无关字段。

**返回示例**：
```json
{
  "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. 出价字段

| 字段 | 类型 | 必填 | 说明 | 如何获取 |
|------|------|------|------|----------|
| `conversion_id` | integer | **是** | 转化ID（**放在请求体顶层**） | 5A 获取 |
| `bid_amount` | integer | **是** | 出价（单位：**分**，顶层） | 用户提供，"出价42元" → `4200` |
| `bid_mode` | enum | 否 | 出价方式 | 智投默认 `BID_MODE_OCPM` |
| `smart_bid_type` | enum | 否 | 出价类型 | `SMART_BID_TYPE_CUSTOM`（手动）或 `SMART_BID_TYPE_SYSTEMATIC`（自动） |
| `smart_cost_cap` | integer | 否 | 自动出价成本上限（分） | 用户提供 |
| `daily_budget` | integer | 否 | 日预算（分，5000~400000000） | 用户提供，"日预算1000元" → `100000` |
| `deep_conversion_worth_rate` | float | 否 | 深度ROI（对应 `DEEP_CONVERSION_WORTH`） | 用户说"深度ROI 1.5" → `1.5` |
| `deep_conversion_worth_advanced_rate` | float | 否 | 深度辅助ROI（对应 `DEEP_CONVERSION_WORTH_ADVANCED`） | 用户说"深度辅助ROI 1.812" → `1.812` |
| `deep_conversion_behavior_bid` | integer | 否 | 深度优化行为出价（分） | 用户提供 |
| `bid_scene` | enum | 场景依赖 | 出价场景 | 小游戏跑量传 `BID_SCENE_NORMAL_AVERAGE`；其他不传 |

**智投出价核心规则**：
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 等。年龄和性别不需要编码查询，直接用结构化值。

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

**地域编码查询**：
```bash
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` 数组：
```bash
node scripts/get-geo-exclude.mjs '{"exclude":"河北"}'
# → {"results":[{"id":110000,"name":"北京市","level":"province"},{"id":120000,"name":"天津市","level":"province"},...]}
```

**设备品牌型号 ID 查询**：
```bash
node scripts/get-targeting-lookup.mjs '{"type":"device","keyword":"华为"}'
```

**地域输出示例**：
```json
{
  "results": [
    {"id": 440000, "name": "广东省", "level": "province", "city_level": 4}
  ]
}
```

**设备输出示例**：
```json
{
  "results": [
    {"id": 10001, "name": "华为 Mate 60"},
    {"id": 10002, "name": "华为 P60"}
  ]
}
```

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

| 定向维度 | `targeting` 内的字段 | 说明 | 获取方式 |
|----------|-----------------|------|----------|
| 地域 | `geo_location.regions` + `geo_location.location_types` | `regions` 是**纯整数数组**（如 `[440000]`），取地域查询返回的 `id` 值；`location_types` 常用 `LIVE_IN`。**`geo_location` 只传本表列出的子字段，不要自行推测添加字段** | ✅ `get-targeting-lookup.mjs type:geo` + 枚举查询 `location_types` |
| 商圈 | `geo_location.business_districts` | 商圈 ID 数组（integer[]） | 用户提供商圈 ID |
| 自定义位置 | `geo_location.custom_locations` | 经纬度+半径定向，格式: `[{"longitude":113.26,"latitude":23.13,"radius":3000}]`，radius 单位米 | 用户提供 |
| 性别 | `gender` | 枚举查询 | ❌ 查枚举后直接构造 |
| 年龄 | `age` | 数组格式: `[{"min":25,"max":29}, {"min":30,"max":39}]`（**`min`/`max` 均为闭区间**，按用户原始区间构造，**不要合并连续段**） | ❌ 直接构造（无枚举） |
| 操作系统 | `user_os` | 支持系统+版本号（如 `IOS_VERSION_18`），枚举查询 | ❌ 查枚举后直接构造 |
| 排除操作系统 | `excluded_os` | 枚举查询 | ❌ 查枚举后直接构造 |
| 学历 | `education` | 枚举查询，传中文（如 `["本科", "硕士"]`）或枚举 key 均可，脚本自动匹配 | ❌ 查枚举后直接构造 |
| 婚恋状态 | `marital_status` | 枚举查询 | ❌ 查枚举后直接构造 |
| 联网方式 | `network_type` | 枚举查询 | ❌ 查枚举后直接构造 |
| 设备价格 | `device_price` | 枚举查询，传简化描述（如 `["2500以上"]`、`["1500-3500"]`）或枚举 key 均可，脚本自动展开 | ❌ 查枚举后直接构造 |
| 设备品牌型号 | `device_brand_model` | 嵌套结构：`{"included_list":[5,9]}` 定向 / `{"excluded_list":[1]}` 排除，**数字 ID** | ✅ `get-targeting-lookup.mjs type:device` |
| 应用安装状态 | `app_install_status` | 枚举查询（仅推广 APP 时可用） | ❌ 查枚举后直接构造 |
| 自定义人群 | `custom_audience` | 人群包 ID 列表 | 用户提供 |
| 排除人群 | `excluded_custom_audience` | 排除的人群包 ID | 用户提供 |
| 排除已转化 | `excluded_converted_audience` | 见下方格式说明 | ❌ 查枚举后直接构造 |
| 微信广告行为 | `wechat_ad_behavior` | 见下方格式说明 | ❌ 查枚举后直接构造 |

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

```bash
# 查询单个/多个字段的枚举
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` 格式**（仅在用户明确提到"排除已转化"时才添加，禁止自行添加）：
```json
{
  "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"]}'` 查询。

```json
"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 构造示例**：

```json
{
  "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. 投放时间与状态

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `begin_date` | string | **是** | 开始日期，格式 `YYYY-MM-DD` |
| `end_date` | string | **是** | 结束日期，格式 `YYYY-MM-DD`；未指定传 `""`（长期投放） |
| `first_day_begin_time` | string | 否 | 首日开始时间，格式 `HH:ii:ss` |
| `delivery_time_ranges` | string[] | **是** | 投放时段数组，半小时精度。|
| `configured_status` | enum | 否 | 广告状态，默认暂停(`AD_STATUS_SUSPEND`)；用户明确要求上线时传 `AD_STATUS_NORMAL` |

**`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 ）

```json
// 全时段（用户未指定投放时段）
"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. 版位与探索策略（智投固定值，脚本自动处理）

| 字段 | 值 | 说明 |
|------|-----|------|
| `automatic_site_enabled` | `true` | 脚本自动设置，无需传入 |
| `site_set` | 不传 | 智能版位，系统自动择优 |
| `exploration_strategy` | 推荐 `AUTOMATIC_EXPLORATION` | |

### 7B. 智投专有字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `smart_delivery_platform` | enum | **是** | 步骤 1 确定的智投场景标识 |
| `smart_delivery_aigc_creative` | struct | **推荐必传** | AIGC自动创意，用户未提及默认关闭 |
| `smart_delivery_history_comp_reused_creative` | struct | **推荐必传** | 组件全库智选，用户未提及默认关闭 |
| `auto_derived_creative_enabled` | boolean | 推荐传 | 自动衍生视频创意，推荐 `true` |
| `smart_delivery_period_switch` | enum | 否 | 周期达成开关，`PERIOD_SWITCH_ON` / `PERIOD_SWITCH_OFF`。仅用户明确要求"周期达成"/"周期稳投"时传入 |
| `smart_delivery_period_days` | enum | 周期达成时**必填** | 周期天数，支持 `PERIOD_DAYS_THREE`(3天) / `PERIOD_DAYS_SEVEN`(7天) |
| `smart_delivery_period_budget` | integer | 周期达成时**必填** | 周期总预算（单位：**分**），约束：≥ 3 × 出价 × 周期天数 |
| `smart_delivery_period_continue` | enum | 周期达成时**必填** | 续投开关，`PERIOD_CONTINUE_SWITCH_ON`（长期自动续投）/ `PERIOD_CONTINUE_SWITCH_OFF`（单周期结束即停） |
| `short_play_pay_type` | enum | 爆剧跑量场景可选 | 短剧售卖方式类型，详见 [references/short-play-pay-type.md](references/short-play-pay-type.md) |
| `sell_strategy_id` | integer | 条件必填 | 售卖策略 ID，`short_play_pay_type` 为收费剧时**必填** |

**smart_delivery_aigc_creative（AIGC自动创意）**：
```json
// 关闭
{"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（全库智选）**：
```json
// 关闭
{"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](references/short-play-pay-type.md)

**周期达成（Period Completion）**：

完整字段定义、约束规则和 JSON 示例见 [references/smart-delivery-period.md](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_platform` = 3002（小店单链路）或 3004（推直播间） | 投放场景 |
| `marketing_target_type` = `MARKETING_TARGET_TYPE_WECHAT_CHANNELS_LIVE` | 推广产品类型为视频号直播 |
| `marketing_carrier_type` = `MARKETING_CARRIER_TYPE_WECHAT_CHANNELS_LIVE` | 载体为视频号直播 |

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

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

```json
// 视频号直播场景 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_platform` = 3002（小店单链路）或 3003（全店托管）或 3005（推商品） | 投放场景 |
| `marketing_target_type` ≠ `MARKETING_TARGET_TYPE_WECHAT_CHANNELS_LIVE` | 推广产品类型**不是**视频号直播 |
| `marketing_carrier_type` ≠ `MARKETING_CARRIER_TYPE_WECHAT_CHANNELS_LIVE` | 载体**不是**视频号直播 |

**三个条件同时满足时**，`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` 必须和原有的策略类型并存，不能单独使用。
结构示例：
```json
// 非视频号直播场景 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个微信小店商品，营销载体为跳转页面）**：
```json
{
  "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项）**：

| # | 检查项 | 要点 |
|---|--------|------|
| 1 | `account_id` | 广告主账号ID |
| 2 | `adgroup_name` | 用户提供的原文名称，不要编造 |
| 3 | `smart_delivery_platform` | 步骤 1 确定，与场景匹配 |
| 4 | 四元组 | `marketing_goal`、`marketing_sub_goal`、`marketing_target_type`、`marketing_carrier_type` — **统一使用字符串枚举 key**（如 `"MARKETING_GOAL_USER_GROWTH"`），`create-adgroup.mjs` 脚本内部自动转为数值。**默认全部从步骤 2 的脚本返回中选出**；只有用户明确给出 4 个枚举值全部时才可直接使用 |
| 5 | `marketing_target_type` 位置 | 传在**请求体顶层**即可，`create-adgroup.mjs` 会自动将其移入 `marketing_asset_outer_spec` 内部（ONEID类/商品库类）或用于 `marketing_asset_id` 组装（行业产品库类）。**不需要手动放进 spec** |
| 6 | 资产/载体扁平字段 | 步骤 3 选定 asset 的 `flat_params` 各 key-value **展开到请求体顶层**（如 `asset_id`、`carrier_id`、`catalog_id` 等）；ONEID 类和视频号直播类已含 `carrier_id`；**行业/商品库类不含 `carrier_id`**，若 `carrier_type` 需要载体则需从用户处获取后补入；**不要手动构造 `marketing_carrier_detail`** |
| 7 | `marketing_asset_outer_spec` / `marketing_asset_id` | **不需要手动构造**，`create-adgroup.mjs` 根据 `asset_id` + `marketing_target_type` 自动组装 |
| 8 | `conversion_id`（顶层） | 步骤 5 获取。有 ROI 系数时选 `has_deep_conversion=true` 的；用户明确给出则直接使用；**禁止写 `0`、空字符串或漏传** |
| 9 | `bid_amount`（顶层） | 单位分 |
| 10 | `begin_date` / `end_date` | 未指定 end_date 传 `""` |
| 11 | `delivery_time_ranges` | 投放时段数组，每条格式 `"<Weekday> <HH:MM>~<HH:MM>"`，如 `["Monday 09:00~18:00", "Tuesday 09:00~18:00"]`；传 `["all"]` 表示全时段投放。支持 Monday-Sunday  |
| 12 | `bid_mode` | 默认 `BID_MODE_OCPM` |
| 13 | `automatic_site_enabled` | 智投必须 `true` |
| 14 | `smart_delivery_aigc_creative` | 必传，用户未提及时关闭。**视频号直播场景(3002/3004+视频号直播target+视频号直播carrier)开启时必须含 `sku_id` 和 `catalog_id`**；**非视频号直播场景(3002/3003/3005)开启时必须含 `creative_components.brand` 和 `SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION`**。用户未提供品牌形象时，脚本会自动查询品牌形象列表返回供选择 |
| 15 | `smart_delivery_history_comp_reused_creative` | 必传，用户未提及时关闭。**非视频号直播场景(3002/3003/3005)开启时必须含 `creative_components.brand` 和 `SUPPLY_STRATEGY_TYPE_CUSTOMER_MANUAL_CREATION`**。用户未提供品牌形象时，脚本会自动查询品牌形象列表返回供选择 |
| 16 | `bid_scene` | 小游戏跑量传 `BID_SCENE_NORMAL_AVERAGE`，其他不传 |
| 17 | `targeting` 来源 | 只要用户给了任何定向约束，地域/设备必须通过 `get-targeting-lookup.mjs` 查编码，枚举通过 `get-enum-options.mjs` 查询；定向白名单由 `create-adgroup.mjs` 自动校验，不支持的字段会报错返回 |
| 18 | `search_expansion_switch` | 用户要求时传 `SEARCH_EXPANSION_SWITCH_OPEN`，未提及不传 |
| 19 | `project_ability_list` | 全店托管多商品场景必须用此字段替代顶层 `marketing_asset_outer_spec`；单商品不需要 |
| 20 | `wechat_ad_behavior` | 用户提到微信广告行为排除时，通过 `get-enum-options.mjs` 查询枚举后构造；**用户未提及 → 不传** |
| 21 | 定向枚举值 | `education`、`network_type`、`device_price`、`excluded_dimension`、`excluded_day` 等定向枚举**必须通过 `get-enum-options.mjs` 查询确认，禁止凭记忆猜测** |
| 22 | `material_package_id`（素材标签） | 用户提及素材标签/素材包时按 [references/material-labels.md](references/material-labels.md) 取值；未提及 → **不传** |
| 23 | `smart_targeting_mode` | 智能定向模式。`SMART_TARGETING_MANUAL`（手动定向）=不使用/关闭智能定向，`SMART_TARGETING_AUTO`（智能定向）=开启/使用智能定向。枚举通过 `get-enum-options.mjs '{"fields":["smart_targeting_mode"]}'` 查询。用户未提及不传 |
| 24 | `short_play_pay_type` + `sell_strategy_id` | 仅爆剧跑量场景。用户提及短剧售卖方式时设置；收费剧必须提供 `sell_strategy_id`；未提及 → **不传** |
| 25 | 周期达成字段 | 用户明确要求"周期达成"/"周期稳投"时传入 `smart_delivery_period_switch`=`PERIOD_SWITCH_ON` + `smart_delivery_period_days` + `smart_delivery_period_budget` + `smart_delivery_period_continue`；预算 ≥ 3×出价×天数；禁止同时传 `daily_budget`/`total_budget`/`end_date`；用户未提及 → **不传任何周期达成字段** |

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

### 7E. 执行创建

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

**返回示例（成功）**：
```json
{
  "success": true,
  "adgroup_id": 987654321
}
```

**返回示例（失败）**：
```json
{
  "success": false,
  "error": { "code": 1000014, "message": "...", "message_cn": "..." }
}
```

---

## 用户意图提取规则

| 用户输入 | 对应字段 | 转换规则 |
|---------|----------|----------|
| 场景关键词 | `smart_delivery_platform` | 按步骤 1 场景参考表匹配 |
| 四元组相关 | `marketing_goal` 等 | **从步骤 2 脚本返回中选取**，禁止猜测。**统一使用字符串枚举 key**，脚本内部转数值 |
| "出价136.54元" | `bid_amount` | → `13654`（×100，分） |
| "日预算1000元" | `daily_budget` | → `100000`（×100，分） |
| "深度ROI 1.5" | `deep_conversion_worth_rate` | → `1.5`，需选 `has_deep_conversion=true` 的转化ID |
| "深度辅助ROI 1.812" | `deep_conversion_worth_advanced_rate` | → `1.812`，需选 ROI 类转化ID |
| "全国投放"/"不限地域" | `targeting.geo_location` | 不传 `geo_location` |
| "排除X省"/"不投X省"/"除X外全国" | `targeting.geo_location` | → 调 `get-geo-exclude.mjs`，取返回 `results` 中的 `id` 组成 `regions` 数组，加 `location_types: ["LIVE_IN"]` |
| 指定省市 | `targeting.geo_location` | → `get-targeting-lookup.mjs` 查编码，取返回的 `id` 组成纯整数数组放入 `regions`（如 `[440000]`），`location_types: ["LIVE_IN"]` |
| 指定性别 | `targeting.gender` | → 通过 `get-enum-options.mjs` 查 `gender` 枚举后构造 |
| 指定年龄 | `targeting.age` | → `[{"min":25,"max":29}, {"min":30,"max":39}]`，**`min`/`max` 均为闭区间（包含边界值）**，即"25~29岁"→ `{"min":25,"max":29}`，不是 `{"min":25,"max":30}`。按用户给出的区间直接构造，如果用户说了多个不同年龄段，**不要合并** |
| 指定设备 | `targeting.device_brand_model` | → `get-targeting-lookup.mjs` 搜数字ID |
| 指定操作系统 | `targeting.user_os` | 全版本：`["ANDROID"]` / `["IOS"]`；指定版本范围：如"Android 10及以上"→ `["ANDROID_VERSION_10", ..., "ANDROID_VERSION_15"]`，"iOS 14及以上"→ `["IOS_VERSION_14", ..., "IOS_VERSION_18"]` |
| 排除操作系统 | `targeting.excluded_os` | 排除特定系统版本，如排除鸿蒙纯净版 → `["ANDROID_PURE_MODE"]`，排除低版本Android → `["ANDROID_VERSION_1", "ANDROID_VERSION_2", ..., "ANDROID_VERSION_4"]` |
| 指定联网方式 | `targeting.network_type` | 如"仅WiFi"→ `["WIFI"]`，"4G及以上"→ `["NET_4G", "NET_5G", "WIFI"]` |
| 排除已转化 | `targeting.excluded_converted_audience` | → 按定向规则填写 |
| 排除小游戏注册用户（N天未活跃） | `targeting.wechat_ad_behavior` | → `{"excluded_actions": ["MINI_GAME_WECHAT_REGISTERED"], "mini_game_wechat_registered_activity": "THIRTY_DAYS_NO_ACTIVE"}` |
| 定向枚举值 | `education`、`network_type`、`device_price` 等 | **必须通过 `get-enum-options.mjs` 查询确认，禁止凭记忆猜测** |
| 项目名称 | `adgroup_name` | 按用户原文 |
| "转化来源/自建转化/平台预置" | `create_source_type` | → `CreateSourceType`，枚举通过 `get-enum-options.mjs '{"fields":["create_source_type"]}'` 查询 |
| "AIGC开启"/"AIGC创意"/"AIGC" | `smart_delivery_aigc_creative` | → **struct**：`{"is_open": true, "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_AIGC"]}`。|
| "全库智选开启"/"组件全库智选"/"历史组件复用" | `smart_delivery_history_comp_reused_creative` | → **struct**：`{"is_open": true, "supply_strategy_type": ["SUPPLY_STRATEGY_TYPE_HISTORY_COMP_REUSE"]}`。|
| "素材包/素材标签 ID 1234" | `material_package_id` | 按 [references/material-labels.md](references/material-labels.md) 取值；未提及不传 |
| "不使用智能定向"/"关闭智能定向"/"手动定向" | `smart_targeting_mode` | → `SMART_TARGETING_MANUAL`，枚举通过 `get-enum-options.mjs '{"fields":["smart_targeting_mode"]}'` 查询 |
| "使用智能定向"/"开启智能定向" | `smart_targeting_mode` | → `SMART_TARGETING_AUTO`，枚举通过 `get-enum-options.mjs '{"fields":["smart_targeting_mode"]}'` 查询 |
| "广告上线创建"/"创建后启用"/"创建后上线" | `configured_status` | → `AD_STATUS_NORMAL`，覆盖默认暂停行为 |
| "免费剧"/"免费短剧" | `short_play_pay_type` | → `SHORT_PLAY_PAY_TYPE_FREE_PLAY`（仅爆剧跑量场景） |
| "收费剧"/"付费剧"/"付费短剧" | `short_play_pay_type` | → `SHORT_PLAY_PAY_TYPE_CHARGE_PLAY`（仅爆剧跑量场景，必须同时提供 `sell_strategy_id`） |
| "售卖策略 ID xxx"/"短剧策略 ID xxx" | `sell_strategy_id` | → 整数值，收费剧场景必填 |
| "周期达成"/"周期稳投"/"固定周期" | `smart_delivery_period_switch` | → `PERIOD_SWITCH_ON`，同时必须配合 `smart_delivery_period_days`、`smart_delivery_period_budget`、`smart_delivery_period_continue`。禁止同时传 `daily_budget`/`total_budget`/`end_date` |
| "3天周期"/"三天" | `smart_delivery_period_days` | → `PERIOD_DAYS_THREE` |
| "7天周期"/"七天"/"一周" | `smart_delivery_period_days` | → `PERIOD_DAYS_SEVEN` |
| "周期预算X元" | `smart_delivery_period_budget` | → 金额×100（分），如"2000元" → `200000` |
| "续投"/"自动续投"/"长期投放" | `smart_delivery_period_continue` | → `PERIOD_CONTINUE_SWITCH_ON` |
| "不续投"/"单周期"/"投完即停" | `smart_delivery_period_continue` | → `PERIOD_CONTINUE_SWITCH_OFF` |
---

<!-- script get-available-marketing-assets → scripts/get-available-marketing-assets.mjs (injected at build time) -->
<!-- script get-android-packages → scripts/get-android-packages.mjs (injected at build time) -->

## 执行原则

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