name: tencentads-delivery-standard-create description: "專用於建立常規(標準)展示營銷單元（原廣告組）的 SDK 化技能。當用戶意圖涉及常規投放、標準營銷單元建立、CPC/CPM/oCPM/oCPC出價營銷單元的建立場景時，使用本技能。當用戶未明確提到智投關鍵詞或者使用者指定了手動版位的，應優先使用本技能。覆蓋場景：電商推廣、APP下載註冊、品牌曝光、銷售線索收集、內容變現等常規展示營銷單元。本技能通過專用指令碼（而非全域性 CLI 工具）呼叫 API，指令碼已處理複雜分支、欄位過濾和資料轉換。注意：如果當用戶明確提到智投、專案、AIM+、艾米等關鍵詞，應使用 tencentads-delivery-smart-create 技能" 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 解析失敗。

常規廣告與智投的關鍵區別（執行參考）

以下差異直接影響步驟 6 請求體的構建，執行時需注意。

⛔ 執行順序（不可跳步）：

步驟1 → 步驟1A(可選) → 步驟2 → 步驟3 → 步驟4 → 步驟5 → 步驟6
獲取      資產反推       確定      確定       獲取      配置       組裝請求體
四元組    四元組         推廣產品   版位       轉化目標  定向+時間  → create-adgroup.mjs
          (有資產線索時)  +載體               +出價

執行協議（高優先順序，覆蓋後文）

若本節與下文"繼續執行""不要重複查詢"等表述衝突，以本節為準。

⛔ 出價方式與步驟跳過規則

步驟 1、2、5、6 無論什麼出價方式都必須執行。以下規則隻影響步驟 3~4：

• CPC/CPM（輕量路徑）：
• 步驟 3：自動版位 → 直接設 automatic_site_enabled: true，跳過 get-site-set.mjs；手動版位 → 仍需查詢
• 步驟 4：跳過 4B 轉化查詢，只需 bid_mode + bid_amount
• oCPM/oCPC（完整路徑）：

• 步驟 3~4 全部執行（步驟 4 的 get-conversions.mjs 依賴步驟 3 返回的 site_set）

  來源於7w4.net。

• ⛔ 步驟 1 → 2 是絕對必須執行的前兩步，不可跳過。 即使使用者 input 中看起來已包含四元組、商品資訊，仍必須呼叫 get-rules.mjs 確認四元組、呼叫 get-assets.mjs 獲取推廣資產 ID。原因：不同賬號的可選組合不同，自然語言描述無法直接轉為精確的列舉值和 ID。例外：步驟 1A 成功確定資產後，步驟 2 可跳過 get-assets.mjs 呼叫（但仍需從 1A 的資料構造欄位）。步驟 3-5 中的查詢子動作在滿足"顯式證據白名單"或"出價方式跳過規則"時可跳過，但步驟 1 不可。

• 進入下一步前，必須先拿到上一步輸出並確認來源。 合法來源只有三類：使用者在原始需求中明確給出、當前 session 前一步指令碼返回、當前 session 前一步 API 返回。
• 自然語言意圖不能替代結構化欄位。 "電商推廣""品牌曝光"等描述只能用於步驟 1 篩選四元組，不能直接當作四元組、營銷載體 ID、conversion_id 的依據。
• 進入步驟 6 前必須能回答每個關鍵欄位來自哪裡。 說不清來源的欄位，不要猜。
• ⚠️ 錯誤處理與重試限制：每個指令碼呼叫最多重試 1 次（換引數或換呼叫方式）。如果 2 次仍失敗（如返回 "Mock not found"、空結果、報錯），立即跳過該步驟，用已有資料繼續推進到下一步直至步驟 6。嚴禁反覆重試同一指令碼、讀取指令碼原始碼、或切換到非指令碼方式（如 tencent-ads api）嘗試繞過。寧可在最終請求中缺少某個欄位，也不要耗盡所有輪次。
• 顯式證據白名單（僅適用於步驟 3-5 的查詢子動作，步驟 1 不適用）：
• 四元組查詢：使用者明確給出 marketing_goal、marketing_sub_goal、marketing_target_type、marketing_carrier_type 這 4 個列舉值全部；或當前 session 已從 get-rules.mjs 返回中得到。
• 推廣產品 / 營銷載體查詢：使用者明確給出構造請求體所需的完整 ID；或當前 session 已從 get-assets.mjs 返回中得到；或步驟 1A 的 get-assets-by-rules.mjs 已成功匹配到資產。
• 轉化目標查詢：使用者明確給出 conversion_id；或當前 session 已從 get-conversions.mjs 返回中得到。
• 定向查詢：使用者沒有任何定向約束時可跳過；只要使用者給了地域、年齡、性別、排除已轉化、裝置等要求，就必須先呼叫 get-targeting-lookup.mjs。

步驟 1（⛔ 最先執行）：獲取四元組

前置：account_id + 使用者營銷需求 輸出：marketing_goal、marketing_sub_goal、marketing_target_type、marketing_carrier_type

四元組是騰訊廣告的產品術語，指營銷內容 + 轉化/最佳化目標的完整匹配集合，共10個欄位： - 營銷內容（4個）：marketing_goal、marketing_sub_goal、marketing_carrier_type、marketing_target_type - 轉化/最佳化目標（6個）：optimization_goal、deep_behavior_optimization_goal、deep_behavior_advanced_goal、deep_worth_optimization_goal、deep_worth_advanced_goal、forward_link_assist

這10個欄位作為一個整體定義廣告的投放語義，必須從指令碼返回的可選範圍中選取，禁止通過推理猜測。

為什麼不能猜？ - 不同賬號准入的組合不同，猜錯會導致 adgroups/add 報錯 - 看似相同的場景（如"電商推廣"），在不同賬號上對應的 marketing_goal 可能完全不同 - 四元組錯誤會級聯導致後續推廣產品、轉化目標等全部錯誤

呼叫方式：

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

示例：

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

指令碼已處理：內部呼叫 get_rules_by_advertiser（不傳 delivery_scene，獲取常規廣告可用組合），解析 rules_json 巢狀 JSON 字串，按 marketing_goal 分組輸出緊湊格式。

返回格式說明：

所有列舉值均為完整 key（如 MARKETING_TARGET_TYPE_APP_ANDROID），可直接使用。

返回示例：

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

Agent 需要做的決策：當返回多個組合時，根據使用者意圖選擇正確的一組。

選擇規則（按優先順序逐層過濾）：

1. 先從使用者意圖提取關鍵約束：
2. 使用者提到了"賣貨"/"電商"/"商品銷售" → marketing_goal 應含 PRODUCT_SALES
3. 使用者提到了"APP下載"/"拉新"/"註冊" → marketing_goal 應含 USER_GROWTH
4. 使用者提到了"品牌"/"曝光" → marketing_goal 應含 BRAND_PROMOTION
5. 使用者提到了"線索"/"表單"/"留資" → marketing_goal 應含 LEAD_RETENTION
6. 使用者提到了"漲粉"/"加關注" → marketing_goal 應含 INCREASE_FANS_INTERACTION
7. 使用者提到了"小程式" → marketing_target_type 應含 MINI_PROGRAM_WECHAT
8. 使用者提到了"APP"/"應用"作為推廣產品（非營銷載體） → marketing_target_type 應含 APP_ANDROID 或 APP_IOS。
9. 使用者提到了"小遊戲" → marketing_target_type 應含 WECHAT_MINI_GAME
10. 使用者提到了"影片號直播"作為推廣物件（非營銷載體） → marketing_target_type 應含 WECHAT_CHANNELS_LIVE
11. 使用者提到了"影片號直播"作為營銷載體 → marketing_carrier_type 應含 WECHAT_CHANNELS_LIVE（⛔ 不要據此設定 marketing_target_type）
12. 使用者提到了"跳轉頁面" → marketing_carrier_type 應含 JUMP_PAGE
13. 使用者提到了"新遊推廣"/"新游上線"/"新遊首發"/"遊戲上線" → marketing_sub_goal 應含 NEW_GAME_LAUNCH
14. 使用者提到了"新遊測試"/"測試服"/"刪檔測試"/"試玩"/"新客試玩" → marketing_sub_goal 應含 NEW_GAME_TEST
15. 使用者提到了"新遊預約"/"預約" → marketing_sub_goal 應含 NEW_GAME_RESERVE
16. 使用者提到了"平穩期"/"長線運營"/"平穩期推廣" → marketing_sub_goal 應含 PLATEAU_PHASE_LAUNCH
17. 使用者提到了"小遊戲新客"/"小遊戲拉新"/"新客增長" → marketing_sub_goal 應含 MINI_GAME_NEW_CUSTOMER_GROWTH

18. 使用者提到了"小遊戲迴流"/"小遊戲促活"/"迴流促活" → marketing_sub_goal 應含 MINI_GAME_RETURN_CUSTOMER_ENGAGEMENT

19. 按 marketing_goal 匹配使用者的營銷目標

20. 按 marketing_target_type 匹配使用者的推廣物件型別

⛔⛔⛔ 前置強制檢查（最高優先順序）：使用者是否同時給了「推廣產品 ID 或名稱」？ - 是 → 禁止在步驟 1 確定 marketing_target_type，必須直接跳到步驟 1A，把該 marketing_goal 下的全部 combinations 傳入，由指令碼自動匹配。即使使用者同時說了"營銷載體: iOS應用"，也絕對不能據此把 combinations 縮窄為只含 APP_IOS 的那一個。 - 否 → 繼續按下面的規則選擇。

⚠️ marketing_target_type 反映的是"產品/店鋪/內容"的型別，不要與最佳化目標、出價方式混淆。無法直接確定時，按 marketing_goal 過濾後從剩餘項中選擇。

⛔ "營銷載體"只能確定 marketing_carrier_type，禁止用來推斷或縮窄 marketing_target_type。

⚠️ 商品庫類 marketing_target_type 選擇規則（僅當 PRODUCT_SALES 且 combinations 同時含 CONSUMER_PRODUCT、WECHAT_STORE_PRODUCT、WECHAT_STORE 中多個時）： 1. 使用者明確說了"商品庫" → 選 CONSUMER_PRODUCT 2. 使用者明確說了"微信小店"/"影片號小店" → 選 WECHAT_STORE_PRODUCT（推廣單個商品）或 WECHAT_STORE（推廣整個店鋪），根據使用者意圖區分 3. 使用者給了推廣產品名稱或 ID → ⛔ 禁止暫定，必須直接進入步驟 1A 通過資產反推確定。傳給 1A 的 combinations 按 1A-① 規則過濾（只按 marketing_goal 過濾，其餘維度全量）。 4. 使用者未明確且未給任何資產線索 → 暫定 CONSUMER_PRODUCT，步驟 2 會根據資產查詢結果自動回退（見步驟 2B「商品庫類空資產回退」）

1. ⛔ 窮盡以上規則後仍無法唯一確定 marketing_target_type 時（強制檢查點）：

   先回答：使用者是否給了推廣產品的名稱或 ID？ - 是 → 立即進入步驟 1A，通過資產反推確定四元組。禁止猜測 marketing_target_type。傳給 1A 的 combinations 按 1A-① 規則過濾（只按 marketing_goal 過濾，其餘維度全量）。 - 否 → 向用戶列出剩餘 combinations 中的 marketing_target_type 選項確認，附中文含義幫助選擇。

2. 若過濾後 marketing_carrier_type 仍有多個可選值（即同一 marketing_goal + marketing_target_type 對應多種 carrier_type），必須向用戶確認營銷載體型別，不能自行猜測。此時應將 combinations 中實際剩餘的所有 marketing_carrier_type 選項列出給使用者，讓使用者選擇。例如："根據您的推廣目標，當前支援以下營銷載體：1) XXX 2) YYY 3) ZZZ，請問您要使用哪種？"（其中 XXX/YYY/ZZZ 替換為 combinations 中實際返回的 carrier_type 值）

3. marketing_sub_goal 只能複用 get-rules.mjs 返回值，禁止語義改寫：例如使用者說"註冊"、"新客"、"拉新"時，也不要自造 MARKETING_SUB_GOAL_USER_REGISTER；如果步驟 1 返回的是 MARKETING_SUB_GOAL_MINI_GAME_NEW_CUSTOMER_GROWTH 或 MARKETING_SUB_GOAL_APP_ACQUISITION，後續所有指令碼都必須原樣複用

步驟 1 完成後你應該有：四元組 4 個值 + product_type（從 combinations 陣列的匹配項取）。product_type 需透傳給步驟 3 和步驟 4 的指令碼。

步驟 1A（可選，有資產線索時執行）：通過資產反推四元組

⛔ 前置門禁：步驟 1 過濾後只剩 1 個 combination → 四元組已確定，直接跳到步驟 2，禁止進入 1A。 即使使用者給了推廣產品 ID/名稱也不需要 1A——資產查詢在步驟 2 完成。

觸發條件（僅當通過前置門禁後）：使用者提到了推廣產品/資產的 ID 或名稱，且步驟 1 過濾後仍有 2 個及以上 combinations 無法唯一確定四元組。

不觸發的情況：① 步驟 1 已經唯一確定了四元組（只剩 1 個 combination）② 使用者沒有給出任何資產 ID 或名稱線索

目的：通過查詢賬號下所有可能組合的真實資產列表，用使用者給的資產 ID 或名稱進行匹配，精確鎖定四元組，避免向用戶確認。

1A-① 預過濾（由指令碼自動完成）

⛔ 規則不變：只按 marketing_goal 過濾，marketing_target_type 和 marketing_carrier_type 維度不做任何縮窄。

指令碼內部自動呼叫 get_rules_by_advertiser API 獲取全量 combinations，並按傳入的 marketing_goal 過濾。Agent 不需要透傳 combinations 陣列。 指令碼還支援傳入 marketing_target_type 進行優先查詢（非縮窄）：優先查該型別的資產並嘗試匹配，命中則跳過其餘型別的 API 呼叫以加速返回，未命中則自動 fallback 全量查詢。指令碼還會在資產匹配成功且載體型別需要時自動查詢載體列表，結果通過 carrier_result 返回（詳見 1A-③+）。

1A-② 呼叫 get-assets-by-rules.mjs

node scripts/get-assets-by-rules.mjs '{"account_id":"<ACCOUNT_ID>","marketing_goal":"<使用者確定的MARKETING_GOAL或不傳>","marketing_target_type":"<使用者明確的TARGET_TYPE或不傳>","match_hint":{"asset_id":"<使用者給的ID或null>","asset_name":"<使用者給的名稱或null>"},"carrier_hint":{"carrier_id":"<使用者給的載體ID或null>","carrier_name":"<使用者給的載體名稱或null>"}}'

引數說明： - account_id：必填 - marketing_goal：可選。傳入後腳本只查該 goal 下的 combinations（等價於原來 Agent 手動按 goal 過濾）。使用者明確了 goal 就傳，未明確就不傳（指令碼查全量） - marketing_target_type：可選。使用者明確了推廣產品型別時傳入（如使用者說"小程式"就傳 MARKETING_TARGET_TYPE_MINI_PROGRAM_WECHAT）。指令碼會優先查該型別下的資產，匹配成功則跳過其餘型別查詢以加速返回；未傳或優先查未命中時自動 fallback 全量查詢。注意：這裡傳 marketing_target_type 僅影響查詢順序（優先查 → fallback 全量），不等同於步驟 1 中"縮窄 combinations"——即使傳了，指令碼仍保證不漏查其他型別 - match_hint：使用者給了資產 ID 就傳 asset_id，給了名稱就傳 asset_name，兩個都給了就都傳（ID 優先匹配） - carrier_hint：可選，使用者給了載體 ID 傳 carrier_id，給了載體名稱傳 carrier_name

返回示例（unique_match）：

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

注意：unique_match 時指令碼會自動裁剪非命中 combination 的 assets（顯示為 "[N items, omitted]"），減少上下文開銷。

1A-③ 匹配結果處理

指令碼返回的 match_result 已按優先順序完成匹配，直接根據 status 處理：

1A-③+ 載體查詢結果處理（carrier_result）

當資產匹配成功（unique_match / multiple_match）且載體型別不是 JUMP_PAGE 時，指令碼自動查詢載體列表並返回 carrier_result。

載體查詢的介面路由（指令碼內部自動判斷，Agent 無需關心）： - 統一通過 bff_promoted_objects/get 介面查詢，指令碼根據 marketing_carrier_type 自動對映到對應的 promoted_object_type

1A-④ 步驟 1A 完成後的影響

步驟 2（⛔ 預設必須執行）：獲取推廣產品 + 營銷載體

前置：步驟 1 的 marketing_target_type、marketing_carrier_type、marketing_goal 輸出：asset_id、carrier_id 等扁平 ID（步驟 6 傳給 create-adgroup.mjs，由指令碼自動組裝為 API 所需的巢狀結構）

⚡ 快速路徑：如果步驟 1A 的 match_result.status 為 unique_match，可跳過 get-assets.mjs 呼叫，直接使用指令碼返回的 flat_params 中的扁平 ID。

⚡ ONEID 類自動短路：當用戶給了明確的資產 ID 時，通過 asset_hint.asset_id 傳給 get-assets.mjs，指令碼內部會自動短路（不調 API，直接返回 shortcut: true），返回的 flat_params 可直接透傳。使用者給的是名稱時傳 asset_hint.asset_name，指令碼不會短路，走正常查詢。

呼叫方式（步驟 1A 未執行或未成功時）：

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

引數說明： - account_id、marketing_target_type：必填 - marketing_carrier_type、marketing_goal：可選 - product_type：可選，來自步驟 1 的 combination.product_type，載體查詢時使用 - carrier_hint：可選，用於載體匹配。使用者給了載體 ID 就傳 carrier_id，給了載體名稱就傳 carrier_name - asset_hint：可選，使用者給了明確的資產 ID 就傳 asset_id，給了資產名稱就傳 asset_name。ONEID 類傳 asset_id 時指令碼自動短路

⚡ 載體查詢已內建：當傳入 marketing_carrier_type + product_type（或 carrier_hint）時，指令碼會自動查詢並匹配載體，返回 carrier_result 欄位。無需額外呼叫 get-assets-by-rules.mjs 來獲取載體 ID。

指令碼已處理：自動根據 marketing_target_type 判斷分類（ONEID / 商品庫 / 行業產品庫），路由到正確的 API，返回統一格式的資產列表。同時自動查詢載體（如需要）。

返回示例（ONEID 類）：

{
  "asset_type": "ONEID",
  "assets": [
    {
      "marketing_asset_outer_id": "wx1234567890",
      "marketing_carrier_id": "wx1234567890",
      "name": "我的小程式",
      "type": "MINI_PROGRAM_WECHAT"
    }
  ],
  "carrier_result": {
    "status": "not_needed",
    "reason": "ONEID/影片號類資產已包含 marketing_carrier_id"
  }
}

Agent 需要做的決策——資產選擇規則（⛔ 禁止預設選第一個）：

1. 使用者提及了產品/商品名稱 → 從 assets 中選 asset_name（或 name）與使用者意圖最相關的項
2. 僅 1 個資產 → 直接使用
3. 多個且無法區分 → 展示給使用者確認

2A. 透傳 flat_params 給步驟 6（⛔ 不要手動構造巢狀結構）

核心原則：Agent 只負責將指令碼返回的扁平 ID 透傳給步驟 6 的 create-adgroup.mjs。巢狀結構（marketing_asset_outer_spec、marketing_asset_id、marketing_carrier_detail）全部由 create-adgroup.mjs 根據 marketing_target_type / marketing_carrier_type 自動組裝，Agent 不要手動構造。

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

指令碼會為每條 matched_items 都計算並掛載 flat_params（與 create-adgroup.mjs 入參直接對齊）： - unique_match → 頂層也輸出 flat_params（= matched_items[0].flat_params），Agent 直接透傳即可 - multiple_match / name_multiple_match → 使用者選完後，取對應項的 matched_items[n].flat_params 即可，無需手動提取欄位

{
  "flat_params": {
    "asset_id": "342574",        // INDUSTRY → marketing_asset_id; ONEID → marketing_asset_outer_id; CATALOG → catalog_id
    "carrier_id": "417200582",   // 優先 carrier_result.matched_carrier，其次 ONEID 資產的 marketing_carrier_id
    "catalog_id": "123456",      // 僅商品庫類
    "asset_sub_id": "...",       // 商品庫子 ID / ONEID 子包 / 直播預約 notice_id 等（可選）
    "sub_carrier_id": "..."      // 通常與 asset_sub_id 同值（可選）
  }
}

get-assets.mjs 的 flat_params：

get-assets.mjs 也會為每條 assets 都掛載 flat_params，格式與上面一致。Agent 選完後直接取 assets[n].flat_params 透傳即可。assets 恰好 1 條時頂層也輸出 flat_params（= assets[0].flat_params）。

總結：無論走哪個指令碼、匹配到幾條，每條結果都帶 flat_params。Agent 選定後直接透傳，永遠不需要手動判斷"該取哪個欄位"。

asset_sub_id / sub_carrier_id 補充說明（flat_params 已自動處理，以下僅供瞭解）： - APP_ANDROID：子包標識（如 "0;00011609313139363030393334"），asset_sub_id 和 sub_carrier_id 填同一值 - PC_GAME：區服標識（如 "hwbz"），asset_sub_id 和 sub_carrier_id 填同一值 - WECHAT_CHANNELS_LIVE_RESERVATION：直播預約 notice_id（如 "finderlivenotice-..."），asset_sub_id 和 sub_carrier_id 填同一值 - 商品庫類（CONSUMER_PRODUCT / WECHAT_STORE_PRODUCT / COMMODITY_SET / WECHAT_STORE_PRODUCT_SET）：asset_sub_id = product_outer_id / wechat_store_id / commodity_set_id - 無子級時不傳這兩個欄位即可

carrier_id 的來源（按優先順序）： 1. flat_params.carrier_id（兩個指令碼每條結果都帶，最簡單直接） 2. 使用者明確給出的載體 ID。⛔ 使用者給的"推廣產品 ID"不是載體 ID，兩者不可互換。 3. 以上都沒有時，需向用戶確認

影片號直播預約場景補充：get-assets.mjs 返回含 live_notices，Agent 必須選取 notice_id（格式 finderlivenotice-xxx），同時傳給 asset_sub_id 和 sub_carrier_id。多場次選擇：① 使用者指定 → 匹配 ② 未指定 → start_time 最晚且在投放日期內 ③ 都不在範圍 → start_time 最晚。（get-assets-by-rules.mjs 的 flat_params 中已自動選取最晚場次，如需使用者指定可覆蓋）

指令碼會根據 marketing_target_type 自動判斷三分類（ONEID / 商品庫 / 行業產品庫），組裝正確的 marketing_asset_outer_spec 或 marketing_asset_id。根據 marketing_carrier_type 自動判斷是否需要 marketing_carrier_detail。不需要手動構造這些巢狀結構。

2B. 強約束

• 白名單例外：使用者在原始需求裡已明確給出完整 ID（如 catalog_id、product_outer_id、marketing_asset_id 等），則可直接作為對應的扁平 ID 使用並跳過查詢。ONEID 類使用者給了資產 ID 時通過 asset_hint.asset_id 傳給 get-assets.mjs，指令碼會自動短路處理。
• 空字串不是合法結果：不要把空字串當作"已完成步驟 2"。查不到且使用者也未提供時，保留缺失狀態。
• ⚠️ 商品庫類空資產回退（指令碼已自動處理）：get-assets.mjs 內部已實現自動回退——當 CONSUMER_PRODUCT 查詢返回空資產時，指令碼會自動嘗試 WECHAT_STORE_PRODUCT，反之亦然。Agent 無需手動重試或切換型別。
• 回退成功時，返回結果中會包含 actual_marketing_target_type（實際生效的型別）和 fallback_applied: true
• ⛔ Agent 必須檢查返回的 actual_marketing_target_type 欄位：如果與傳入的型別不同，說明發生了回退，後續步驟 3~7 都必須使用 actual_marketing_target_type 的值（而非原始傳入值）
• 如果返回 assets: [] 且無 fallback_applied，說明兩種型別都沒有資產，按正常的空結果處理（保留缺失狀態）
• 跳轉頁面載體 (MARKETING_CARRIER_TYPE_JUMP_PAGE)：不需要傳 carrier_id，但推廣資產仍需正常查詢

步驟 2 完成後你應該有：flat_params（包含 asset_id、carrier_id 等扁平 ID），或已從指令碼返回中選定了一條帶 flat_params 的資產。這些值不能是空字串。

步驟 3（⛔ oCPM/oCPC 必須執行）：確定版位

前置：步驟 1 的 marketing_target_type、marketing_carrier_type 輸出：site_set（陣列）或確認使用自動版位

⚡ 快速路徑：僅 CPC/CPM + 自動版位 → 直接設 automatic_site_enabled: true，跳過本步查詢，進入步驟 4。

⛔ oCPM/oCPC 時必須呼叫 get-site-set.mjs，即使使用者已明確指定了版位名稱。原因：步驟 4 的 get-conversions.mjs 依賴此步返回的 available_site_set 來構造 site_set 引數，使用者給的版位名稱不能直接替代。

版位決定了廣告的投放位置。常規廣告支援手動選擇版位和自動版位兩種模式。

版位確定規則：

1. 使用者指定了版位 → 先呼叫 get-site-set.mjs，再從指令碼返回的真實 available_site_set 中選擇（如"投朋友圈" → ["SITE_SET_MOMENTS"]；如"投騰訊平臺與內容媒體/PCAD" → 按 3B 一級分類展開為 ["SITE_SET_KANDIAN", "SITE_SET_QQ_MUSIC_GAME", "SITE_SET_TENCENT_NEWS", "SITE_SET_TENCENT_VIDEO"] 再與 available_site_set 取交集）。確定最終的使用者版位列表供步驟 4B 和步驟 6 使用
2. 使用者要求自動版位 → automatic_site_enabled: true，仍需查詢可用版位列表，後續 get-conversions.mjs 傳入 auto_site_set 中的版位
3. 使用者未指定版位 → 推薦自動版位，仍需呼叫 get-site-set.mjs 獲取版位列表

3A. 獲取可用版位列表

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

示例：

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

指令碼已處理：內部自動設定 bid_mode、buying_type、campaign_type 等 API 必傳引數，呼叫方只需傳四元組列舉 key。

返回：

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

3B. 版位列舉對照表（權威）

⚠️ 此表為 API 真實列舉 key 與中文名稱的對照表，以 API 文件為準。Agent 在從使用者自然語言對映版位時，必須參考此表，嚴禁憑猜測使用表中不存在的 key。

⛔ site_set 列舉值只允許使用上表第一列的 key，禁止自行從中文翻譯構造列舉名。 指令碼返回什麼就用什麼。

⚠️ 標註"僅支援搜尋廣告"的版位（SITE_SET_WECHAT_SEARCH、SITE_SET_QBSEARCH）在非搜尋場景下不可使用，不要將其加入普通展示廣告的 site_set。

版位集合一級分類對照表

3C. 強約束

• 手動版位：automatic_site_enabled: false + site_set 陣列（來自指令碼返回的 available_site_set 或使用者指定，按上表對映）
• 自動版位（推薦）：automatic_site_enabled: true，site_set 不傳

⚠️ 傳給 get-conversions.mjs 的 site_set 引數規則（僅 oCPM/oCPC 需關注，CPC/CPM 跳過）

⛔ site_set 只能包含 available_site_set 中存在的版位。 必須傳入使用者最終選擇的版位列表（即手動版位場景下用於 adgroups/add 的 site_set，自動版位場景下傳 auto_site_set），要根據使用者實際選擇的版位傳入，不要盲目傳完整的 available_site_set**。

⚠️ 使用者說的"優先版位"（如"優先影片號"）≠ site_set 引數。"優先版位"影響的是 priority_site_set，而 get-conversions.mjs 的 site_set 是查詢範圍，自動版位時必須傳 auto_site_set 全量。

❌ 典型錯誤：自動版位時只傳了 ["SITE_SET_CHANNELS"]（使用者的優先版位）→ 應傳 auto_site_set 全量。

步驟 3 完成後你應該有：版位模式（自動/手動）+ 供步驟 4 使用的 site_set（oCPM/oCPC 時：自動版位 = auto_site_set 全量，手動版位 = 使用者指定 ∩ available_site_set；CPC/CPM + 自動版位時無需 site_set）。

3D. 版位定投場景（scene_spec，可選）

scene_spec 是請求體根層級欄位（與 targeting 並列），用於對已選版位內的流量做精細篩選。 預設"不限"（不傳），僅在使用者明確提到定投/遮蔽特定流量場景時才構造。

場景定向完整欄位（以下欄位均放在 scene_spec: { ... } 物件內）：

wechat_scene 子欄位：

構造示例：

定投聯盟流量包 + 遮蔽指定流量包：

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

定投指定公眾號 + 聯盟資訊流場景：

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

⚠️ 列舉類欄位（mobile_union、exclude_mobile_union、tencent_news、display_scene、qbsearch_scene、pc_scene、wechat_search_scene）必須通過 get-enum-options.mjs 查詢確認列舉值，禁止猜測。 ⚠️ ID 列表類欄位（union_position_package、exclude_union_position_package、wechat_position、mobile_union_category、wechat_channels_scene、wechat_scene 子欄位）直接傳使用者給出的 ID。 ⚠️ 使用者未提到任何版位定投場景需求時，不傳 scene_spec（等同於 UI 上全部選"不限"）。

步驟 4：獲取轉化目標 + 確定出價

前置：步驟 1 的四元組 + 步驟 2 的資產 ID + 步驟 3 的 site_set 輸出：conversion_id（可選）、bid_mode、smart_bid_type、bid_amount（手動出價時）或 daily_budget（自動出價時）

⚡ 快速路徑：CPC/CPM → 跳過 4B 轉化查詢，只需確定 bid_mode + bid_amount，然後進入步驟 5。

4A. 確定出價方式 (bid_mode)

根據使用者意圖確定出價方式：

核心規則： 1. CPC/CPM：只需 bid_mode + bid_amount，不需要查詢轉化目標，跳過步驟 4B 2. oCPM/oCPC：需 bid_mode + conversion_id，手動出價（CUSTOM）還需 bid_amount 3. 使用者未指定出價方式時，預設使用 BID_MODE_OCPM

4A-2. 確定出價方案（smart_bid_type）

CPC/CPM 固定走手動出價。oCPM/oCPC 根據使用者意圖選擇，預設手動出價。

SYSTEMATIC（最大轉化量）約束： 1. daily_budget 必填且 > 0，使用者未給時必須向用戶確認 2. bid_amount 不傳 3. 必須是 oCPM/oCPC 4. ⛔ 不能同時開啟：auto_acquisition_enabled、live_recommend_strategy_enabled、aoi_optimization_strategy

控制成本（僅 SYSTEMATIC 可用）：

根據是否配置了 ROI 深度最佳化，選擇對應欄位（二選一，互斥）：

都需同時傳 cost_constraint_scene: COST_CONSTRAINT_SCENE_OPEN

4B. 獲取轉化目標（僅 oCPM/oCPC 需要）

node scripts/get-conversions.mjs '{"account_id":"<ACCOUNT_ID>","site_set":["<使用者表達的版位>"],"available_site_set":["<步驟3返回的全量可用版位>"],"non_multi_site_set":["<步驟3返回的non_multi_site_set>"],"marketing_carrier_id":"<步驟2返回的載體ID>","asset_id":"<步驟2返回的行業資產ID>","marketing_goal":"<MARKETING_GOAL_列舉key>","marketing_sub_goal":"<MARKETING_SUB_GOAL_列舉key>","marketing_carrier_type":"<MARKETING_CARRIER_TYPE_列舉key>","marketing_target_type":"<MARKETING_TARGET_TYPE_列舉key>","create_source_type":"<CreateSourceType的列舉值，使用者未提及來源時不傳此引數>"}'

注意：常規廣告不需要傳 delivery_scene。四元組欄位統一傳字串列舉 key，指令碼內部自動轉為數值。bid_mode 來自步驟 4A 的出價方式（如 BID_MODE_OCPM），用於按出價方式過濾轉化目標。

create_source_type：如果使用者指定了轉化來源，則根據使用者意圖傳入——PLATFORM平臺轉化或SELF_CREATED自建轉化等。使用者未提及來源時不傳此引數。

⛔ site_set 引數來源：必須嚴格按步驟 3C 的規則傳入——自動版位時傳步驟 3 返回的 auto_site_set 完整陣列（不是使用者提到的"優先版位"子集），手動版位時傳使用者指定版位與 available_site_set 的交集。

⛔ available_site_set 引數：必須同時傳入步驟 3 返回的 available_site_set 完整陣列（即 get-site-set.mjs 返回的全量可用版位列表）。指令碼內部會用 site_set ∩ available_site_set 取交集，作為防禦性校驗，確保只傳入合法版位。即使你認為 site_set 已經是正確的子集，也必須傳 available_site_set。

⛔ non_multi_site_set 引數：必須同時傳入步驟 3 返回的 non_multi_site_set 陣列（不支援多版位組合的版位列表，即 site_set_multi=0 的版位）。指令碼內部會自動過濾掉這些版位（除非使用者只選了一個版位），避免查詢轉化目標時傳入不支援多版位組合的版位。

⛔ 行業產品庫類（步驟 2 返回 asset_type: "INDUSTRY"） 傳 asset_id！

marketing_carrier_id 和 asset_id 是兩個獨立引數，由指令碼按兩個維度分別決定是否傳給 API： - marketing_carrier_id（→ API 的 product_id）：傳入 flat_params.carrier_id。指令碼根據 marketing_carrier_type 判斷是否傳：除頁面跳轉 (JUMP_PAGE) 外的載體型別都傳。 - asset_id（→ API 的 marketing_asset_id）：僅行業產品庫類需要傳（asset_type: "INDUSTRY" 時），傳入 flat_params.asset_id。ONEID 類和商品庫類不需要傳此欄位。 - 兩者可以都傳、只傳一個、或都不傳，互不排斥。

⛔ 特別注意：當 asset_type: "INDUSTRY" 時，必須將 flat_params.asset_id 作為 asset_id 傳入本指令碼，否則轉化目標查詢可能會失敗！

指令碼已處理：通過 access_status 過濾僅返回已完成接入的轉化目標，標註深度轉化型別，裁剪無關欄位。

返回示例：

{
  "goals": [
    {
      "conversion_id": 12345,
      "name": "APP啟用",
      "optimization_goal": "OPTIMIZATIONGOAL_APP_ACTIVATE",
      "bid_mode": "BID_MODE_OCPM",
      "has_deep_conversion": false,
      "create_source_type": "PLATFORM"
    },
    {
      "conversion_id": 12346,
      "name": "註冊-首日付費ROI",
      "optimization_goal": "OPTIMIZATIONGOAL_APP_REGISTER",
      "bid_mode": "BID_MODE_OCPM",
      "has_deep_conversion": true,
      "deep_conversion_type": "DEEP_CONVERSION_WORTH",
      "deep_conversion_worth_goal": "OPTIMIZATIONGOAL_1DAY_PURCHASE_ROAS",
      "create_source_type": "SELF_CREATED"
    }
  ]
}

Agent 需要做的決策——conversion 選擇規則：

1. 排除 permission=1 的項（指令碼已過濾，但仍需意識到約束）
2. 使用者提供了深度出價引數時（ROI 係數或行為出價金額），按以下三步選擇：
3. Step A — 確定出價欄位：根據使用者自然語言，參考文末「使用者意圖提取規則」表，確定對應的出價欄位名（如 deep_conversion_worth_rate）
4. Step B — 反推 deep_conversion_type：根據下方 4D 對映表，從出價欄位名反推對應的 deep_conversion_type（如 deep_conversion_worth_rate → DEEP_CONVERSION_WORTH）
5. Step C — 從 goals 中選擇：在 goals 列表中，找 has_deep_conversion=true 且 deep_conversion_type 與 Step B 結果一致的轉化ID。不同 deep_conversion_type 的 conversion_id 不可互換
6. 使用者指定了最佳化目標（但沒給深度出價引數） → 按 name 欄位匹配
7. 使用者未指定 → 取 goals 陣列第一個項
8. 使用者指定了轉化建立來源（如"自建轉化"/"自建歸因"/"自建"/"自定義轉化"→ SELF_CREATED，"平臺預置"/"平臺轉化"/"平臺上報"/"系統預置"/"預置轉化"→ PLATFORM）→ 在呼叫 get-conversions.mjs 時傳入 create_source_type 過濾；使用者未提及來源時不傳此引數

4C. 出價欄位清單

4D. 深度轉化最佳化

oCPM/oCPC 可選配置，前置條件：步驟 4B 的 get-conversions.mjs 返回中，選中的轉化目標 has_deep_conversion=true。

⚠️ 二選一規則：深度/深度輔助出價一級扁平欄位與 deep_conversion_spec 巢狀結構互斥，不能同時傳： 常規廣告使用 conversion_id，因此直接傳一級扁平欄位即可。

一級扁平欄位示例（使用者說"深度ROI 1.5"）：

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

deep_conversion_type 取自 get-conversions.mjs 返回，根據型別選用對應的一級出價欄位： - DEEP_CONVERSION_WORTH → deep_conversion_worth_rate（深度ROI出價 / 深度轉化價值率） - DEEP_CONVERSION_WORTH_ADVANCED → deep_conversion_worth_advanced_rate（深度輔助ROI） - DEEP_CONVERSION_BEHAVIOR → deep_conversion_behavior_bid（深度OG出價） - DEEP_CONVERSION_BEHAVIOR_ADVANCED → deep_conversion_behavior_advanced_bid（深度輔助OG出價）

⛔ 不同 deep_conversion_type 的 conversion_id 不可互換。例如 DEEP_CONVERSION_WORTH 對應的 conversion_id 和 DEEP_CONVERSION_WORTH_ADVANCED 對應的是不同的 conversion_id，必須根據指令碼返回的 deep_conversion_type 精確選擇。

強約束： - conversion_id 只能來自：使用者明確給出的 ID，或 get-conversions.mjs 返回 - 白名單例外：使用者在原始需求中已明確給出完整的 conversion_id 數值 ID，則直接使用 - CPC/CPM 出價不需要 conversion_id - optimization_goal 不需要傳，API 會根據 conversion_id 自動推導

步驟 4 完成後你應該有：bid_mode、smart_bid_type、conversion_id（oCPM/oCPC時）；CUSTOM 還有 bid_amount，SYSTEMATIC 還有 daily_budget。

步驟 5：配置定向 + 投放時間

前置：使用者意圖中的定向需求 輸出：targeting、begin_date、end_date、delivery_time_ranges

5A. 定向配置

常規廣告擁有完整定向能力，支援地域、年齡、性別、興趣、行為、人群包等多維度定向。

定向查詢觸發規則（命中任一項就必須先呼叫 get-targeting-lookup.mjs）： - 使用者給了地域、省市區、常駐地 → type: "geo" - 使用者給了裝置品牌 / 型號 → type: "device"

不需要呼叫 get-targeting-lookup.mjs 的定向維度（指令碼自動匹配列舉）： - 性別：直接用 ["MALE"] / ["FEMALE"] / 不傳 - 年齡：直接用 [{"min":25,"max":29}, {"min":30,"max":39}] 格式的陣列。min 和 max 均為閉區間（包含邊界值），即使用者說"25~29歲"→ {"min":25,"max":29}，不是 {"min":25,"max":30}。每個區間對應使用者給出的一段年齡範圍，如果使用者說了多個不同年齡段區間，就按照多個區間構造，不要合併連續段 - 排除已轉化：通過 get-enum-options.mjs '{"fields":["excluded_dimension","excluded_day"]}' 查詢列舉後構造 - 作業系統（user_os）：通過 get-enum-options.mjs '{"fields":["user_os"]}' 查詢列舉值後構造（支援系統+版本號, 傳 ["IOS"] / ["ANDROID"]（全版本），或用簡化格式如 ["ANDROID_10+"] 表示 Android 10 及以上 - 排除作業系統（excluded_os）：通過 get-enum-options.mjs '{"fields":["excluded_os"]}' 查詢列舉後構造，同 user_os 的簡化格式，也支援 WINDOWS、HARMONY 等直接列舉 - 聯網方式（network_type）：通過 get-enum-options.mjs '{"fields":["network_type"]}' 查詢列舉後構造，傳使用者提到的聯網方式即可，如 ["WIFI"]、["4G"]、["5G"]，指令碼自動匹配為 API 列舉（如 4G → NET_4G） - 學歷（education）：通過 get-enum-options.mjs '{"fields":["education"]}' 查詢列舉後構造，傳中文即可，如 ["本科", "碩士"]，指令碼自動匹配為 API 列舉（如 本科 → BACHELOR） - 裝置價格（device_price）：通過 get-enum-options.mjs '{"fields":["device_price"]}' 查詢列舉後構造，傳簡化描述即可，如 ["2500以上"]、["1500-3500"]，指令碼自動展開為對應的價格區間列舉 - 微信廣告行為（wechat_ad_behavior）：通過 get-enum-options.mjs '{"fields":["wechat_ad_behavior_actions"]}' 查詢列舉後構造，傳中文即可，如 {"actions": ["註冊過小遊戲"], "mini_game_wechat_registered_activity": "30天未活躍"}，指令碼自動匹配為 API 列舉 - 微信廣告行為排除：通過 get-enum-options.mjs '{"fields":["wechat_ad_behavior_excluded_actions"]}' 查詢列舉後構造 - 其他列舉定向（學歷/聯網方式/裝置價格/婚戀狀態等）：均通過 `get-enum-options.mjs 查詢

⚠️ get-targeting-lookup.mjs 只支援 type: "geo" 和 type: "device" 兩種查詢，不支援 age、gender 等。年齡和性別不需要編碼查詢，直接用結構化值。

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

⚠️ 通投（不限定向）時仍需傳 targeting: {}（空物件），不要省略該欄位。

地域編碼查詢：

node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"廣東"}'
# 支援批次：keyword 用空格分隔
node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"北京 上海 廣東"}'

⚠️ 地域查詢效率規則（P0 級，違反會導致輪次耗盡被終止）： 1. 一次查完所有地域：指令碼是本地檔案查詢，無數量限制。把使用者給的所有城市名用空格拼接到一個 keyword 裡一次呼叫即可，不要分批，不要逐個查詢。即使 100+ 個城市也只需 1 次呼叫。 2. 省級優先原則：如果使用者說"北京"、"廣東"等省級地域，直接用省名查詢，會返回省級編碼（如 110000）。不要拆解為區級編碼，除非使用者明確列舉了具體的區/市。 3. 不加行政區字首：直接用城市名（如 "南寧 成都 杭州"），不要加"廣西南寧"、"四川成都"等字首。 4. 重名消歧：如果查詢結果中有重名地域（如"朝陽區"同時返回北京和長春的），根據使用者上下文和 parent 欄位篩選正確的。

地域排除（使用者表達"排除某省/不投某省/除 X 外全國投放"）： 調 get-geo-exclude.mjs，直接返回排除後剩餘省份的編碼，取 id 組成 regions 陣列：

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

裝置品牌型號 ID 查詢：

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

地域輸出示例：

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

裝置輸出示例：

{
  "results": [
    {"id": 10001, "name": "華為 Mate 60"},
    {"id": 10002, "name": "華為 P60"}
  ]
}

常規廣告支援的完整定向維度（以下欄位均放在 targeting: { ... } 物件內，不要放到請求體頂層）：

⛔ 所有列舉值禁止憑記憶猜測，必須通過 get-enum-options.mjs 查詢確認：

# 查詢單個/多個欄位的列舉
node scripts/get-enum-options.mjs '{"fields":["education","device_price","excluded_dimension"]}'

# 按分類查詢所有列舉
node scripts/get-enum-options.mjs '{"category":"targeting"}'    # 定向相關
node scripts/get-enum-options.mjs '{"category":"scene_spec"}'   # 場景定向
node scripts/get-enum-options.mjs '{"category":"bid"}'          # 出價相關
node scripts/get-enum-options.mjs '{"category":"conversion"}'   # 轉化相關
node scripts/get-enum-options.mjs '{"category":"strategy"}'     # 探索策略
node scripts/get-enum-options.mjs '{"category":"switch"}'       # 開關類

可查詢的列舉欄位包括但不限於：gender、education、user_os、excluded_os、network_type、device_price、marital_status、app_install_status、location_types、excluded_dimension、excluded_day、wechat_ad_behavior_actions、wechat_ad_behavior_excluded_actions、bid_mode、smart_bid_type、deep_conversion_type、deep_conversion_goal、exploration_strategy、search_expand_targeting_switch、search_expansion_switch、cost_constraint_scene、configured_status、ecom_pkam_switch、smart_coupon_mode、live_recommend_strategy_enabled、dynamic_ad_type、short_play_pay_type、smart_targeting_mode、adx_realtime_type、game_consumption_level、conversion_behavior_list 等。

excluded_converted_audience 格式（⚠️ 僅在使用者明確提到"排除已轉化"時才新增，禁止自行新增）：

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

wechat_ad_behavior 格式（⚠️ 僅在使用者明確提到微信廣告行為排除時才新增，禁止自行新增）：

使用者說"排除已關注公眾號的使用者"、"排除已註冊小遊戲的使用者"等時，構造此欄位。excluded_actions 的列舉通過 get-enum-options.mjs '{"fields":["wechat_ad_behavior_excluded_actions"]}' 查詢。

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

• 涉及公眾號行為時，需同時傳 wechat_official_account_id（使用者給的公眾號 ID）
• 涉及企業微信行為時，需同時傳 corp_id

強約束： - 命中觸發規則後，必須先呼叫 get-targeting-lookup.mjs 獲取編碼，再構造 targeting - 不要把自然語言直接翻成粗粒度佔位值 - targeting 是必填欄位：即使使用者沒有明確表達任何定向需求，也必須傳 targeting: {}（空物件），不能省略該欄位 - targeting 及其子結構只傳上方表格中列出的欄位和子欄位，不要自行推測或類推新增文件中未出現的欄位

targeting 構造示例：

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

無定向需求（通投）時傳空物件："targeting": {}

5B. 投放時間與狀態

delivery_time_ranges 格式說明：

陣列中每條格式為:全時段/全天投放/未設定："all"；指定時段： "<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 - "排除週三下午" → 列出除週三下午外的所有時段，這時候agent需要列出其他有效的時段

步驟 5 完成後你應該有：targeting（如需）、begin_date、end_date、delivery_time_ranges。

步驟 6：組裝請求體 → 建立廣告組

前置：步驟 1-5 的所有輸出 動作：按檢查清單組裝完整請求體，呼叫 create-adgroup.mjs

6A. 站點與版位

⚠️ priority_site_set（優先版位集合）：當 automatic_site_enabled: true 且使用者同時指定了"優先投放某些版位"時使用。填入使用者指定的版位列舉陣列（參考步驟 3B 列舉表），系統會在自動版位的基礎上優先在這些版位投放。

6B. 常規廣告特有說明

• 不傳 smart_delivery_platform — 這是常規廣告，不是智投
• 不傳 optimization_goal — API 會根據 conversion_id 自動推導，無需傳此欄位
• 可傳 exploration_strategy — 版位探索策略，列舉值通過 get-enum-options.mjs '{"fields":["exploration_strategy"]}' 查詢

6C. 創意控制欄位

創意通過 dynamic_creatives/add 介面單獨建立，adgroup 級別可傳以下控制欄位：

6D. 建立前自檢（Pre-flight Check，⛔ 必須在呼叫 create-adgroup.mjs 前完成）

在組裝完請求體後、真正呼叫建立介面前，逐項核對以下內容： - 使用者需求一致性：使用者明確給出的每個條件（定向、出價、預算、三元組、商品等）是否都被原樣保留在請求體中，未被丟棄、修改或替換 - 欄位來源可追溯：四元組、轉化目標、營銷載體等關鍵欄位是否來自實際指令碼查詢結果（而非猜測或編造） - 編碼已確認：定向條件中的地域編碼、裝置 ID 等是否經過查詢指令碼確認 - 金額單位正確：所有金額欄位是否已轉換為分

如有任何欄位與使用者原始需求不一致，必須停止並說明差異原因，等待使用者確認後才能繼續。

欄位檢查清單：

6E. 執行建立

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 向用戶說明原因。

使用者意圖提取規則

⚠️ 四元組列舉值使用規則（防幻覺）

四元組的全部10個欄位（營銷內容：marketing_goal、marketing_sub_goal、marketing_carrier_type、marketing_target_type；轉化/最佳化目標：optimization_goal、deep_behavior_optimization_goal、deep_behavior_advanced_goal、deep_worth_optimization_goal、deep_worth_advanced_goal、forward_link_assist）必須從 get-rules.mjs 返回的 combinations 中選取，禁止自行編造或語義改寫。 例如 MARKETING_CARRIER_TYPE_MINI_GAME、MARKETING_GOAL_APP_MONETIZATION、MARKETING_CARRIER_TYPE_APP 這類"看起來合理但 API 不存在"的值，會直接導致報錯。 marketing_sub_goal 只能原樣複用 get-rules.mjs 返回的 key，不能因為使用者說了"註冊"/"下載"就改寫成自造列舉。

marketing_goal 意圖速查（值域穩定，共 5 個）

|---------------|----------| | 使用者增長（APP下載/拉新/註冊/啟用/付費/遊戲推廣 A| MARKETING_GOAL_USER_GROWTH | | 商品銷售 電商/賣貨/成交/GMV/ROI | MARKETING_GOAL_PRODUCT_SALES | | 線索留資 表單/留資/線索收集 | MARKETING_GOAL_LEAD_RETENTION | | 品牌推廣 品牌/曝光 | MARKETING_GOAL_BRAND_PROMOTION | | 漲粉互動 漲粉/加關注 | MARKETING_GOAL_INCREASE_FANS_INTERACTION |

marketing_target_type 易混淆速查（60+ 列舉，僅列易錯項）

完整值域以 get-rules.mjs 返回為準，下表僅幫助區分易混淆項。

執行原則

1. ⛔ 使用者原始需求不可修改（最高優先順序原則）： 使用者明確給定的所有業務條件（包括但不限於：定向條件、出價、預算、三元組、最佳化目標、商品、推廣產品、廣告名稱等）在整個執行流程中絕對不可被修改、替換、省略或放寬，無論出於任何原因——包括 API 報錯、衝突檢測、欄位校驗失敗、查詢結果不匹配等。
2. ❌ 禁止自動修改性別/年齡/地域/作業系統等定向來繞過錯誤或衝突
3. ❌ 禁止自動更換商品或推廣產品來繞過錯誤或衝突
4. ❌ 禁止去掉定向限制（改為全量投放）來繞過錯誤或衝突
5. ❌ 禁止更換三元組或最佳化目標來繞過錯誤或衝突
6. ❌ 禁止用更寬泛的值替代使用者給出的精確條件
7. ❌ 禁止任何形式的未經使用者確認的引數變更
8. 如果因為使用者給定的條件導致流程無法繼續（如衝突、校驗失敗），必須立即停止並向用戶如實報告問題，等待使用者明確指示後才能繼續。
9. 嚴格按步驟 1→(1A)→2→3→4→5→6 順序執行；只有"顯式證據白名單"或"出價方式快速路徑"允許跳過對應查詢；步驟 1A 在有資產線索且四元組未唯一確定時執行
10. CPC/CPM 出價時可跳過步驟 3 的版位查詢（自動版位場景）、步驟 4B（轉化目標查詢）——參見執行協議中的"出價方式決定的步驟執行路徑"表
11. 使用者明確給出的結構化欄位可直接複用，但只豁免該欄位對應的查詢，不會自動豁免其他步驟
12. 禁止把自然語言意圖當作 API 返回值使用；中文描述只能用於篩選，不等於列舉值或 ID
13. 輔助查詢失敗時可以繼續完成最終 API，但只能使用已確認欄位；不能為了湊齊請求體編造四元組、營銷載體 ID、定向列舉
14. 空字串和 0 不是預設值：它們通常表示"你沒有拿到真實結果"，不要拿來偽裝步驟已完成
15. 只要使用者給了定向條件，就不要省略步驟 5，也不要用更寬泛的值替代精確編碼
16. 金額單位是分（10000分 = 100元）
17. 統一使用字串列舉 key：四元組等欄位始終傳字串 key（如 "MARKETING_GOAL_USER_GROWTH"），指令碼內部負責轉為 API 所需數值
18. campaign_id 不需要 — v3.0 展示廣告中 adgroup 直接屬於 account
19. 廣告名稱唯一性 — 同一賬號下廣告名稱必須唯一
20. 有報錯請提供 trace_id

這個 Skill 功能很全面，能處理騰訊廣告常規投放的各種場景，文件寫得很詳細，指令碼工具也比較實用。但文件太長太複雜，步驟多、規則多，新手不容易上手。部分說明存在重複，理解起來有門檻。整體質量不錯，適合有一定經驗的投放人員使用。