name: tencentads-delivery-standard-update description: 營銷單元（原廣告）/智投專案通用更新。支援修改營銷單元或智投專案的多個欄位（名稱、日期、定向、時段、出價、預算、狀態、深度轉化、一鍵起量、創意增強、週期達成等），支援單個營銷單元/專案更新和多賬號多營銷單元/專案批次更新。 license: MIT compatibility: any metadata: author: Tencent Ads Delivery Team version: "0.5.7" icon: megaphone category: tencent-ads

廣告/智投專案通用更新（Adgroup General Update）

單廣告（或智投專案）多欄位通用更新技能，支援一次呼叫中同時修改廣告或智投專案的多個屬性。使用騰訊廣告同步 adgroups/update API。

適用場景：當用戶需要修改廣告或智投專案的出價、預算、定向、名稱、日期、時段、狀態、深度轉化、一鍵起量、創意增強、週期達成（週期預算/續投開關）等屬性時，使用本技能。

版本說明：本技能支援兩種模式： - 單廣告/專案更新：update-adgroup-general.mjs，適用於單賬號單個廣告或智投專案的精細操作。 - 批次更新：update-adgroup-batch.mjs，適用於多賬號多個廣告/智投專案的異構欄位批次操作（每個廣告/專案可更新不同的欄位組合）。

SOP 決策流程

指令碼選擇

選擇規則： - 使用者明確指定了 1 個廣告或智投專案 -> 用 general - 使用者指定了 2 個及以上廣告/智投專案 -> 用 batch - 使用者說"所有廣告"/"全部廣告"/"所有專案"/"全部專案" -> 先查詢列表，然後用 batch

單廣告/專案流程

批次更新流程

步驟 1：意圖識別

當用戶表達以下意圖時，啟用本 Skill：

步驟 2：引數構造

根據廣告/智投專案數量選擇對應模式（智投專案 ID 等同於 adgroup_id，引數構造方式完全一致）：

單個更新（1 個廣告或智投專案）： - account_id：必填，廣告主賬號 ID - adgroup_id：必填，廣告 ID 或智投專案 ID - 至少一個更新欄位（見下方欄位列表）

批次更新（2 個及以上廣告/智投專案）： - tasks：必填，陣列，每個元素包含 account_id、adgroup_id（廣告 ID 或智投專案 ID）和要更新的欄位 - 每個 task 可更新完全不同的欄位組合（異構批次）

步驟 3：更新前自檢（Pre-update Check，必須在呼叫 update-adgroup-*.mjs 前完成）

更新生效後會消耗預算並影響投放表現，出價/預算這類金錢欄位一旦寫錯可能在察覺前就產生不可挽回的扣費；定向寫錯也會燒錯錢（投到無關人群、誤變通投）。命中以下任一情況時，禁止直接執行指令碼，必須先向使用者複述變更，等待"確認/繼續/OK"等明確回覆後才能繼續：

• 金錢欄位：bid_amount / daily_budget / deep_conversion_behavior_bid / deep_conversion_worth_rate / auto_acquisition_budget 及其 _adjustment 變體、bid_adjustment（分版位係數）
• 狀態切換：configured_status（暫停立即停投、啟用立即開始消耗）
• 定向欄位：targeting（任意子欄位都會觸發——子欄位是覆蓋式而非合併式，傳 {} 直接變通投）
• 批次更新：update-adgroup-batch.mjs 且 tasks ≥ 2（必須列出每條受影響的 account_id/adgroup_id 及變更摘要）

複述要求：

• 金錢欄位：一律用「元（分）」雙標註；_adjustment 表示式必須先取當前值算出絕對結果再展示，禁止只丟給使用者 "-10%"
• 定向欄位：必須列出變更的子欄位（如 geo_location、age、custom_audience），並明確寫出"原值 → 新值"。特別警示兩類高危改動：(1) 子欄位被整體覆蓋（如原"北京+上海"傳"北京"會丟上海，要明確告知使用者）；(2) targeting: {} 會清空全部定向變成通投，必須顯式向用戶確認"是否要改成不限定向"
• 使用者未明確回覆或要求修改 → 不要執行指令碼；引數變了就重新走一遍本步驟

僅修改 adgroup_name / 日期 / 時段 / 創意衍生 / poi_list 等非金錢、非狀態、非定向欄位時可跳過本複述，但仍需完成下文「支援的更新欄位」表中的單位與範圍核對。

步驟 4：執行指令碼

單廣告更新：

node scripts/update-adgroup-general.mjs '<JSON引數>'

批次更新：

node scripts/update-adgroup-batch.mjs '<JSON引數>'

步驟 5：回查驗證

與步驟 3 的區別：步驟 3 是「提交前」對照請求體確認意圖；本步是「提交後」對照騰訊返回的最新值確認 API 實際生效結果。

指令碼執行後會自動輸出 _verify 回查資料，包含廣告更新後的實際欄位值（單廣告在 adgroup，批次在 results[].data）。

⛔ 同時輸出的 summary_text 欄位必須原樣陳列給使用者（含其中的換行）。該欄位已由指令碼拼裝好首行標題 + 多行列表的中文回執，覆蓋最新狀態、出價、日預算、定向、版位、投放時段、上線/暫停狀態等關鍵欄位。 - 允許：直接原文輸出 - 不允許：省略欄位、改動數值、自由翻譯列舉、合併成單段、改成表格 - 位置： - 單廣告：頂層 summary_text - 批次：每條 results[i].summary_text，並且回查彙總塊 _verify.adgroups[].summary_text 也有一份（兩處同源，逐條復讀即可） - summary_text 不存在或為 null 時（回查失敗），按 _verify_failed / _verify_error 提示使用者手動確認

步驟 6：反思比對

Agent 必須基於 _verify 回查資料進行反思比對： 1. 對比實際值與步驟 3 已被使用者確認的目標值 2. 金額欄位一律換算成元再比（API 返回分） 3. 如有不一致，明確告知使用者哪些欄位未達預期，並主動提示是否需要回滾（再次呼叫本 skill 改回原值） 4. 如回查失敗，提醒使用者手動確認

支援的更新欄位

⚠️ 重要：智投專案和標準廣告支援的欄位不同，使用前請確認廣告型別。指令碼內建的前置查詢 adgroups/get 會返回 smart_delivery_platform 欄位——有該欄位（且非 SMART_DELIVERY_PLATFORM_EDITION_STANDARD）即為智投專案，否則為標準廣告。

公共欄位（標準廣告 + 智投專案均可用）

僅標準廣告可用欄位

僅智投專案可用欄位

金額欄位統一使用分：bid_amount、daily_budget、deep_conversion_behavior_bid、auto_acquisition_budget 單位均為分，與騰訊廣告 API 及其他 skill（建立、查詢、賬戶更新）保持一致。Agent 需將使用者表達的元乘以 100 轉為分後傳入（如"1000元" → 100000）。 deep_conversion_worth_rate 是比率，不是金額，不做轉換。 相對調整表示式：4 個金額欄位（bid_amount、daily_budget、deep_conversion_behavior_bid、auto_acquisition_budget）和 1 個比率欄位（deep_conversion_worth_rate）均支援 _adjustment 伴隨欄位，用於基於當前值做相對調整（與絕對值欄位二選一）。支援的格式："+20%"（增加百分比）、"-10%"（減少百分比）、"*2"（乘以倍數）、"+50"（加 50 分）、"-30"（減 30 分）。調整後仍需滿足各欄位的範圍約束。當前值為 0 時不支援相對調整。注意：auto_acquisition_budget_adjustment 僅在一鍵起量已開啟時可用，新開啟時必須使用 auto_acquisition_budget 傳入絕對值。

定向更新 SOP（targeting 欄位詳細指引）

當用戶要求修改廣告定向時，按照以下流程構造 targeting 物件。

指令碼已內建 resolveTargetingFields 列舉自動匹配，支援傳入簡化值（如 "本科"、"4G"、"ANDROID_10+"），指令碼自動轉為 API 標準列舉。

定向查詢觸發規則

命中任一項就必須先呼叫 get-targeting-lookup.mjs 查編碼：

• 使用者給了地域、省市區、常駐地 → type: "geo"
• 使用者給了裝置品牌 / 型號 → type: "device"

# 地域編碼查詢（支援批次，keyword 用空格分隔）
node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"北京 上海 廣東"}'

# 裝置品牌型號 ID 查詢
node scripts/get-targeting-lookup.mjs '{"type":"device","keyword":"華為"}'

不需要呼叫 get-targeting-lookup.mjs 的定向維度（指令碼自動匹配列舉）：

• 性別：直接用 ["MALE"] / ["FEMALE"] / 不傳
• 年齡：直接用 [{"min":25,"max":29}, {"min":30,"max":39}] 格式的陣列。min 和 max 均為閉區間（包含邊界值），按使用者原始區間構造，不要合併連續段
• 作業系統（user_os）：傳 ["IOS"] / ["ANDROID"]（全版本），或用簡化格式如 ["ANDROID_10+"] 表示 Android 10 及以上，指令碼自動展開為版本列表
• 排除作業系統（excluded_os）：同 user_os 的簡化格式，也支援 WINDOWS、HARMONY 等直接列舉
• 聯網方式（network_type）：傳 ["WIFI"]、["4G"]、["5G"]，指令碼自動匹配為 API 列舉（如 4G → NET_4G）
• 學歷（education）：傳中文即可，如 ["本科", "碩士"]，指令碼自動匹配為 API 列舉（如 本科 → BACHELOR）
• 裝置價格（device_price）：傳簡化描述即可，如 ["2500以上"]、["1500-3500"]，指令碼自動展開為對應的價格區間列舉
• 微信廣告行為（wechat_ad_behavior）：傳中文即可，指令碼自動匹配為 API 列舉
• 排除已轉化：通過列舉查詢後構造

列舉查詢：

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

# 按分類查詢所有定向相關列舉
node scripts/get-enum-options.mjs '{"category":"targeting"}'

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

通投（不限定向）時傳 targeting: {}（空物件）。

完整定向維度對照表

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

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

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

正向定向（actions）：使用者說"定向已關注公眾號的使用者"等；排除行為（excluded_actions）：使用者說"排除已關注公眾號的使用者"等。列舉分別通過 get-enum-options.mjs '{"fields":["wechat_ad_behavior_actions"]}' 和 '{"fields":["wechat_ad_behavior_excluded_actions"]}' 查詢。

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

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

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

定向更新示例

示例 A：修改定向為北京+上海，25-45歲男性（需要先查地域編碼）

# 步驟1：查地域編碼
node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"北京 上海"}'
# 返回 110000（北京）、310000（上海）

# 步驟2：構造 targeting 並更新
node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"targeting":{"geo_location":{"location_types":["LIVE_IN"],"regions":[110000,310000]},"age":[{"min":25,"max":45}],"gender":["MALE"]}}'

示例 B：修改定向為本科以上、4G+5G、Android 10+（無需查編碼，指令碼自動匹配）

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"targeting":{"education":["本科","碩士","博士"],"network_type":["4G","5G"],"user_os":["ANDROID_10+"]}}'

示例 C：修改定向為不限（通投）

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"targeting":{}}'

示例 D：修改定向為指定裝置品牌（蘋果+華為）（需先查裝置 ID）

# 步驟1：查裝置品牌 ID
node scripts/get-targeting-lookup.mjs '{"type":"device","keyword":"蘋果 華為"}'
# 返回 蘋果=1, 華為=5

# 步驟2：構造 targeting 並更新（注意 device_brand_model 的巢狀格式）
node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"targeting":{"device_brand_model":{"included_list":[1,5],"excluded_list":[]}}}'

定向強約束

• 命中觸發規則後，必須先呼叫 get-targeting-lookup.mjs 獲取編碼，再構造 targeting
• 不要把自然語言直接翻成粗粒度佔位值
• 所有列舉值禁止憑記憶猜測，必須通過 get-enum-options.mjs 查詢確認
• targeting 中不能包含不可修改的欄位（指令碼會攔截）：marketing_goal、marketing_sub_goal、marketing_target_type、marketing_carrier_type、marketing_asset_id、marketing_asset_outer_spec、subordinate_product_id、asset_name、site_set、bid_mode、optimization_goal

不支援修改的欄位（建立時繫結）

以下欄位在廣告/智投專案建立後不可修改，如果使用者要求修改這些欄位，應建議到投放端手動操作或刪除重建：

• marketing_goal / marketing_sub_goal（營銷目的）
• marketing_target_type / marketing_carrier_type（推廣產品/載體型別）
• marketing_asset_id / marketing_asset_outer_spec（推廣產品）
• bid_mode / optimization_goal（出價方式/最佳化目標）
• site_set（版位）
• conversion_id（轉化 ID）

指令碼呼叫示例

示例 1：修改出價

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"bid_amount":12050}'

示例 2：同時修改出價和預算

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"bid_amount":12050,"daily_budget":60000}'

示例 3：修改定向為不限

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"targeting":{}}'

示例 3b：修改定向（地域+年齡+學歷+聯網方式）

地域編碼需先通過 get-targeting-lookup.mjs 查詢；學歷和聯網方式可直接傳簡化值，指令碼自動匹配為 API 列舉。

# 先查地域編碼
node scripts/get-targeting-lookup.mjs '{"type":"geo","keyword":"北京 上海 廣州"}'
# 返回 110000, 310000, 440100

# 再執行更新
node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"targeting":{"geo_location":{"location_types":["LIVE_IN"],"regions":[110000,310000,440100]},"age":[{"min":25,"max":45}],"education":["本科","碩士"],"network_type":["4G","5G"]}}'

示例 4：暫停廣告

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"configured_status":"AD_STATUS_SUSPEND"}'

示例 5：開啟一鍵起量

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_acquisition_enabled":true,"auto_acquisition_budget":50000}'

示例 6：修改投放時段（工作日 9:00-18:00）

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"delivery_time_ranges":["Monday 09:00~18:00","Tuesday 09:00~18:00","Wednesday 09:00~18:00","Thursday 09:00~18:00","Friday 09:00~18:00"]}'

示例 6b：修改投放時段並指定首日開始時間

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"delivery_time_ranges":["Monday 09:00~18:00","Tuesday 09:00~18:00","Wednesday 09:00~18:00","Thursday 09:00~18:00","Friday 09:00~18:00"],"first_day_begin_time":"09:00:00"}'

示例 6c：僅修改首日開始時間（無需同時傳投放時段）

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"first_day_begin_time":"11:00:00"}'

示例 7：多欄位同時更新

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"adgroup_name":"Q2-電商-促銷活動","bid_amount":8000,"daily_budget":100000,"begin_date":"2026-04-15","end_date":"2026-05-15","targeting":{"geo_location":{"location_types":["LIVE_IN"],"regions":[110000,310000,440100]},"age":[{"min":25,"max":45}]}}'

示例 8：出價下調 10%

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"bid_amount_adjustment":"-10%"}'

示例 9：預算翻倍

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"daily_budget_adjustment":"*2"}'

示例 10：出價加 0.5 元，預算增加 30%

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"bid_amount_adjustment":"+50","daily_budget_adjustment":"+30%"}'

示例 11：深度最佳化行為出價設為 30 元

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"deep_conversion_behavior_bid":3000}'

示例 12：深度最佳化行為出價下調 15%

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"deep_conversion_behavior_bid_adjustment":"-15%"}'

示例 13：深度最佳化期望ROI係數設為 1.5

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"deep_conversion_worth_rate":1.5}'

示例 14：深度最佳化期望ROI係數上調 10%

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"deep_conversion_worth_rate_adjustment":"+10%"}'
7w4.net有更好的技能外掛。

示例 15：關閉一鍵起量

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_acquisition_enabled":false}'

示例 16：一鍵起量已開啟時調整起量預算

使用者說"起量預算改為500元"，當前一鍵起量已開啟。 直接傳入新的 auto_acquisition_budget（單位：分，500元=50000分）即可，指令碼內部自動完成"先關閉再用新預算重新開啟"的流程。

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_acquisition_budget":50000}'

示例 16a：一鍵起量已開啟時用相對錶達式調整起量預算

使用者說"起量預算上調10%"，當前一鍵起量已開啟。 傳入 auto_acquisition_budget_adjustment 表示式即可，指令碼自動基於當前值計算目標絕對值，再執行先關後開流程。

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_acquisition_budget_adjustment":"+10%"}'

示例 17：開啟創意衍生（自動使用推薦衍生方式）

只需傳 auto_derived_creative_enabled: true，指令碼自動查詢 muse_derive_switch_info/get 獲取可用衍生方式並使用預設推薦項。

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_derived_creative_enabled":true}'

示例 18：開啟創意衍生並指定衍生方式

顯式指定衍生方式列表，指令碼會校驗每項是否對該廣告可用。

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_derived_creative_enabled":true,"auto_derived_creative_method_type_list":["AUTO_DERIVED_CREATIVE_METHOD_TYPE_OUTPAINTING","AUTO_DERIVED_CREATIVE_METHOD_TYPE_TEMPLATE"]}'

示例 19：關閉創意衍生

node scripts/update-adgroup-general.mjs '{"account_id":12345678,"adgroup_id":111111,"auto_derived_creative_enabled":false}'

示例 20-23：週期達成專案的編輯操作

週期達成專案的編輯操作包含週期預算調整、續投開關切換等，詳細說明和完整示例見 references/smart-delivery-period-update.md。

注意事項

1. targeting 中不能包含非法欄位：完整清單見上方"定向強約束"章節，指令碼會攔截報錯。

2. targeting 列舉自動匹配：指令碼內建列舉簡化值自動轉換，詳見上方"定向更新 SOP"章節。

3. 定向輔助指令碼：get-targeting-lookup.mjs 和 get-enum-options.mjs 在本 skill 的 scripts/ 目錄下可直接呼叫（軟連結指向共享實現）。

4. first_day_begin_time 交叉校驗：與 delivery_time_ranges 同時傳入時指令碼會校驗首日時間槽是否在投放範圍內，不相容則報錯。重要：使用者未明確要求修改 first_day_begin_time 時，禁止自行新增該引數——多傳會觸發 API 對 begin_date 的連帶校驗，導致已投放廣告更新失敗。

5. 無變化欄位自動跳過：指令碼會先查詢廣告當前值，如果某欄位的目標值與當前值一致，該欄位會被跳過（不呼叫更新 API），輸出中會列出 skipped_fields。

6. 廣告存在性校驗：指令碼執行前會先查詢廣告是否存在、是否已刪除。如果廣告不存在或已刪除，直接報錯不呼叫更新 API。

7. 搜尋廣告攔截：當前版本暫不支援搜尋廣告更新操作，指令碼執行前會檢查廣告的 site_set 是否包含搜尋版位（SITE_SET_WECHAT_SEARCH、SITE_SET_QBSEARCH、SITE_SET_SEARCH_MOBILE_UNION）。如果是搜尋廣告，指令碼會直接報錯並輸出 is_search_ad: true 標識，不呼叫更新 API。

8. 一鍵起量編輯規則：

9. ⛔ 智投專案不支援使用一鍵起量：如果目標廣告是智投專案，不允許執行一鍵起量的開啟、關閉或預算調整操作。應直接拒絕並告知使用者：「智投專案不支援使用一鍵起量功能，一鍵起量僅適用於標準投放廣告。」
10. 新開啟（當前關閉 -> enabled=true）：必須同時設定 auto_acquisition_budget，傳入絕對值（分）
11. 新關閉（當前開啟 -> enabled=false）：不可同時設定 budget
12. 已開啟時調整 budget：傳入 auto_acquisition_budget（絕對值，分）或 auto_acquisition_budget_adjustment（相對錶達式，如 "+10%"、"+20000"）均可，指令碼內部自動完成先關閉再用新預算重新開啟的流程（見示例 16、16a）。

13. 已關閉時：不可單獨調整 budget（如需設定請同時傳 auto_acquisition_enabled: true）

14. 週期達成編輯規則：詳情見 references/smart-delivery-period-update.md。核心要點：

15. ⚠️ 週期達成開關不可修改：smart_delivery_period_switch 在建立時確定後無法通過編輯介面開啟或關閉。非週期達成專案不能變成周期達成專案，反之亦然。
16. ⚠️ 週期達成專案的特殊限制：如果目標專案是週期達成專案，以下限制自動生效：
    • 禁止修改：begin_date（開始日期）、end_date（結束日期）、targeting（定向）、configured_status（啟停狀態）
    • 只允許提升：bid_amount（出價）、smart_delivery_period_budget（週期預算）、deep_conversion_behavior_bid（深層出價）只能往上調，不能降低；deep_conversion_worth_rate（ROI）只允許降低（ROI 低 = 目標放寬）
    • 允許修改：delivery_time_ranges（投放時段）、first_day_begin_time（首日時間）
    • 禁止設定：daily_budget（日預算）、total_budget（總預算）
    • 預算約束：修改後的 smart_delivery_period_budget 仍須滿足 ≥ 3 × 出價 × 週期天數
17. 修改續投開關（smart_delivery_period_continue）：
    • 從"不續投"→"續投"（PERIOD_CONTINUE_SWITCH_ON）：專案需未過期，切換後 end_date 自動清空（變為長期投放）
    • 從"續投"→"不續投"（PERIOD_CONTINUE_SWITCH_OFF）：系統自動計算當前週期的 end_date

18. 修改週期預算（smart_delivery_period_budget）：只允許提升，不允許降低

19. 創意衍生編輯規則：

20. 開啟（enabled=true）：指令碼自動查詢 muse_derive_switch_info/get 獲取可用衍生方式。若廣告不支援衍生（API 返回 show_derive_method=false 且無可用方式），指令碼報錯。可選傳入 auto_derived_creative_method_type_list 指定偏好，不傳則使用預設推薦。
21. 關閉（enabled=false）：直接關閉，無需傳 method_type_list
22. 僅更新偏好：不傳 enabled，僅傳 auto_derived_creative_method_type_list 可單獨更新衍生偏好（不校驗可用性，適用於已知合法值的場景）
23. 支援中文別名自動解析：如 ["AI模板", "擴圖"] 自動轉換為標準列舉 key

批次更新指令碼（update-adgroup-batch.mjs）

多賬號多廣告/智投專案異構欄位批次更新，每個廣告/專案可更新完全不同的欄位組合。

適用場景

• 使用者需要同時修改 2 個及以上廣告或智投專案
• 不同廣告/專案需要更新不同的欄位（異構）
• 跨賬號批次操作

入參格式

{
  "tasks": [
    { "account_id": 123, "adgroup_id": "111", "bid_amount": 12050 },
    { "account_id": 123, "adgroup_id": "222", "adgroup_name": "新名", "configured_status": "AD_STATUS_SUSPEND" },
    { "account_id": 456, "adgroup_id": "333", "bid_amount_adjustment": "+20%" }
  ]
}

每個 task 的格式與 update-adgroup-general.mjs 的入參完全一致（account_id + adgroup_id + 更新欄位）。

約束

• tasks 陣列最多 50 個元素
• 每個 task 必須包含 account_id 和 adgroup_id
• 每個 task 至少包含一個更新欄位
• 如果任何一個 task 格式不合法（缺少必填欄位），整個批次會被拒絕（fast-fail）

執行流程

1. 預校驗所有 task 格式（fast-fail）
2. 按 account_id 分組
3. 各賬號並行處理：
4. 批次前置查詢（同賬號內一次 adgroups/get）
5. 逐個廣告序列：buildUpdateBody + adgroups/update
6. 各賬號並行回查驗證
7. 彙總輸出所有結果

輸出格式

{
  "total": 3,
  "success_count": 2,
  "fail_count": 1,
  "skip_count": 0,
  "message": "2 個成功，1 個失敗，0 個跳過。請務必將失敗詳情告知使用者",
  "results": [
    {
      "account_id": 123,
      "adgroup_id": 111,
      "success": true,
      "updated_fields": { "bid_amount": { "previous": 10000, "target": 12050, "unit": "fen" } },
      "message": "廣告 111 更新成功: bid_amount 10000 -> 12050 分"
    },
    {
      "account_id": 456,
      "adgroup_id": 333,
      "success": false,
      "error": "bid_amount_adjustment: 當前出價為 0，無法進行相對調整，請使用 bid_amount 傳入絕對值（單位：分）",
      "message": "廣告 333 更新失敗: ..."
    }
  ]
}

指令碼呼叫示例

示例 B1：同賬號多廣告批次更新（相同欄位）

node scripts/update-adgroup-batch.mjs '{"tasks":[{"account_id":12345678,"adgroup_id":111,"bid_amount":50},{"account_id":12345678,"adgroup_id":222,"bid_amount":50}]}'

示例 B2：同賬號多廣告異構更新（不同欄位）

node scripts/update-adgroup-batch.mjs '{"tasks":[{"account_id":12345678,"adgroup_id":111,"bid_amount":50},{"account_id":12345678,"adgroup_id":222,"daily_budget":600,"configured_status":"AD_STATUS_SUSPEND"}]}'

示例 B3：跨賬號批次更新

node scripts/update-adgroup-batch.mjs '{"tasks":[{"account_id":11111,"adgroup_id":111,"bid_amount_adjustment":"+10%"},{"account_id":22222,"adgroup_id":222,"bid_amount_adjustment":"+10%"}]}'

示例 B4：使用檔案傳參（引數較長時推薦）

node scripts/update-adgroup-batch.mjs --file /tmp/batch_params.json

批次場景的 Pre-update Check 提醒：步驟 3 複述時必須列出每條 (account_id, adgroup_id) 的「當前值 → 目標值」；fast-fail 只能拒絕整批的預校驗，已執行的子任務不會自動回滾，需在確認時告知使用者。

部分成功場景的 Agent 行為

批次更新可能出現部分成功、部分失敗的情況。Agent 必須：

1. 逐條展示結果：遍歷 results 陣列，向用戶說明每個廣告的更新結果
2. 重點關注失敗項：失敗廣告的 error 和 message 必須完整告知使用者
3. 檢查 side_effects：如果失敗結果中包含 side_effects 欄位，必須告知使用者已發生的副作用（如一鍵起量在調整預算時已被關閉但主更新失敗）
4. 回查比對：對成功的廣告，基於 _verify 資料與使用者期望對比
5. 回查失敗提醒：如果輸出中包含 _verify_failed 的廣告，提醒使用者手動確認這些廣告的更新結果

這個 Skill 質量紮實可靠，文件寫得很詳細，涵蓋了廣告更新的各種常見操作，批次處理能力也很實用。優點是流程完整、有驗證機制、能避免誤操作；不足是文件略顯冗長，部分功能入口藏得比較深。普通使用者如果需要批次調整廣告設定，這個工具能很好地滿足需求。