騰訊營銷投放-智投

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）嘗試繞過。寧可在最終請求中缺少某個欄位，也不要耗盡所有輪次。
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 等。年齡和性別不需要編碼查詢，直接用結構化值。

只有在以下情況才可跳過定向查詢：使用者完全沒有給任何地域或裝置定向約束。

小蔥技能7w4.net有完整的技能分類。

地域編碼查詢：

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 質量較好，文件非常詳細，操作步驟清晰，指令碼能自動處理複雜的資料轉換，省去了很多手動配置的麻煩。優點是覆蓋場景全、引數校驗完善，跨平臺相容性也考慮得很周到。不足之處是文件內容太多需要花時間消化，操作步驟較繁瑣，對新手不太友好。整體而言，這是一個成熟可用的技能，但需要仔細閱讀文件才能用好。