广告/智投项目通用更新（Adgroup General Update）

单广告（或智投项目）多字段通用更新技能，支持一次调用中同时修改广告或智投项目的多个属性。使用腾讯广告同步 adgroups/update API。

适用场景：当用户需要修改广告或智投项目的出价、预算、定向、名称、日期、时段、状态、深度转化、一键起量、创意增强等属性时，使用本技能。

版本说明：本技能支持两种模式：

单广告/项目更新：update-adgroup-general.mjs，适用于单账号单个广告或智投项目的精细操作。

批量更新：update-adgroup-batch.mjs，适用于多账号多个广告/智投项目的异构字段批量操作（每个广告/项目可更新不同的字段组合）。

SOP 决策流程

脚本选择

| 场景 | 使用脚本 | 说明 | |------|----------|------| | 单账号单个广告/项目 | update-adgroup-general.mjs | 精细操作，详细日志 | | 多个广告/项目（同/跨账号）| update-adgroup-batch.mjs | 批量操作，每个广告/项目可更新不同字段 |

选择规则：

用户明确指定了 1 个广告或智投项目 -> 用 general
用户指定了 2 个及以上广告/智投项目 -> 用 batch
用户说"所有广告"/"全部广告"/"所有项目"/"全部项目" -> 先查询列表，然后用 batch

单广告/项目流程

步骤1                步骤2                  步骤3               步骤4           步骤5
意图识别  ─────→    参数构造    ─────→    执行脚本   ─────→   回查验证  ─────→  反思比对
是否使用本SKILL      account_id             update-adgroup-      脚本自动       Agent 对比
                     adgroup_id             general.mjs          回查           _verify 数据
                     + 更新字段             (智投项目同用)                       与用户预期

批量更新流程

步骤1                步骤2                  步骤3               步骤4           步骤5
意图识别  ─────→    参数构造    ─────→    执行脚本   ─────→   汇总回查  ─────→  反思比对
多广告/项目           构造 tasks 数组        update-adgroup-      脚本自动       Agent 对比
更新意图              每个 task 含             batch.mjs           批量回查       每个广告/项目
                     account_id +                                              的 _verify 数据
                     adgroup_id +
                     各自的更新字段

步骤 1：意图识别

当用户表达以下意图时，激活本 Skill：

| 用户意图示例 | 说明 | |-------------|------| | "帮我把广告X的出价改为120元" | 单字段更新（绝对值） | | "把广告X的预算调整为600元，出价改为50元" | 多字段更新（绝对值） | | "广告X的出价下调10%" / "出价降低10%" | 出价百分比调整（用 bid_amount_adjustment: "-10%"） | | "广告X的预算提高2倍" / "预算翻倍" | 预算倍数调整（用 daily_budget_adjustment: "*2"） | | "广告X出价加0.5元" | 出价加减调整（用 bid_amount_adjustment: "+50"，即加50分） | | "帮我把广告X的定向改为不限" | 定向更新 | | "把广告X的名称改为ABC" | 名称更新 | | "暂停广告X" / "启用广告X" | 状态更新 | | "帮我把广告X的投放时段改为工作日9-18点" | 时段更新 | | "开启广告X的一键起量，预算500元" | 一键起量开启 | | "关闭广告X的一键起量" | 一键起量关闭（用 auto_acquisition_enabled: false） | | "广告X的起量预算改为500元" | 一键起量已开启时调整预算绝对值（用 auto_acquisition_budget: 50000，即500元=50000分），脚本内部自动先关后开 | | "广告X的起量预算提升10%" / "起量预算增加200元" | 一键起量已开启时相对调整（用 auto_acquisition_budget_adjustment: "+10%" 或 "+20000"，即加20000分），与 auto_acquisition_budget 二选一 | | "关闭广告X的创意增强" | 创意增强关闭 | | "开启广告X的创意增强，偏好AIGC" | 创意增强开启+偏好（用 auto_derived_creative_enabled: true + auto_derived_creative_method_type_list） | | "把广告X的深度出价改为30元" | 深度转化出价绝对值 | | "广告X的深度出价下调15%" | 深度转化出价相对调整（用 deep_conversion_behavior_bid_adjustment: "-15%"） | | "广告X的ROI系数改为1.5" | ROI系数绝对值（用 deep_conversion_worth_rate: 1.5） | | "广告X的ROI上升10%" | ROI系数相对调整（用 deep_conversion_worth_rate_adjustment: "+10%"，百分比与用户表述一致） | | "帮我把广告A和广告B的出价都调到50元" | 批量更新：用 update-adgroup-batch.mjs，tasks 包含两个广告，各自 bid_amount: 5000（50元=5000分） | | "把这3个广告全部暂停" | 批量更新：用 update-adgroup-batch.mjs，tasks 各自 configured_status: "AD_STATUS_SUSPEND" | | "广告A出价加10%，广告B预算改500，广告C暂停" | 异构批量更新：用 update-adgroup-batch.mjs，每个 task 更新不同字段 | | "帮我把项目X的出价改为120元" | 智投项目单字段更新（智投项目 ID 等同于 adgroup_id） | | "暂停项目X" / "启用项目X" | 智投项目状态更新 | | "把这3个智投项目全部暂停" | 批量更新：用 update-adgroup-batch.mjs，tasks 各自 configured_status: "AD_STATUS_SUSPEND" | | "项目X的预算调到800元，出价改为60元" | 智投项目多字段更新 |

步骤 2：参数构造

根据广告/智投项目数量选择对应模式（智投项目 ID 等同于 adgroup_id，参数构造方式完全一致）：

单个更新（1 个广告或智投项目）：

account_id：必填，广告主账号 ID
adgroup_id：必填，广告 ID 或智投项目 ID
至少一个更新字段（见下方字段列表）

批量更新（2 个及以上广告/智投项目）：

tasks：必填，数组，每个元素包含 account_id、adgroup_id（广告 ID 或智投项目 ID）和要更新的字段
每个 task 可更新完全不同的字段组合（异构批量）

步骤 3：执行脚本

单广告更新：

node scripts/update-adgroup-general.mjs '<JSON参数>'

批量更新：

node scripts/update-adgroup-batch.mjs '<JSON参数>'

步骤 4：回查验证

脚本执行后会自动输出 _verify 回查数据，包含广告更新后的实际字段值。

步骤 5：反思比对

Agent 必须基于 _verify 回查数据进行反思比对：

对比 _verify.adgroup 中的实际值与用户的修改预期
重点检查金额字段（API 返回分，用户期望元）：如 bid_amount 12050 分 = 120.50 元
如有不一致，明确告知用户哪些字段未达预期
如回查失败，提醒用户手动确认

支持的更新字段

| 字段 | 类型 | 说明 | 单位/格式 | |------|------|------|-----------| | adgroup_name | string | 广告名称 | 最大 120 等宽字符（中文=2，英文=1，即最多 60 个中文或 120 个英文） | | begin_date | string | 开始投放日期 | YYYY-MM-DD | | end_date | string | 结束投放日期 | YYYY-MM-DD，空串=长期投放 | | delivery_time_ranges | string[] | 投放时段 | "Monday 09:00~18:00" 或 ["all"] | | first_day_begin_time | string | 首日开始投放时间 | HH:MM:SS（默认 00:00:00，可单独传入，投放时段需包含该时间） | | bid_amount | number | 出价（绝对值） | 分（如 120.50元 → 12050） | | bid_amount_adjustment | string | 出价相对调整（与 bid_amount 二选一） | 表达式，如 "+20%"、"-10%"、"*2"、"+50"（加50分） | | daily_budget | number | 日预算（绝对值） | 分（0=不限，范围 5000~400,000,000，即 50~4,000,000 元） | | daily_budget_adjustment | string | 日预算相对调整（与 daily_budget 二选一） | 表达式，如 "+30%"、"*1.5"、"-10000"（减10000分） | | configured_status | string | 广告状态 | AD_STATUS_NORMAL / AD_STATUS_SUSPEND | | targeting | object | 定向设置 | 传空对象 {} = 不限定向 | | deep_conversion_behavior_bid | number | 深度优化行为出价（绝对值） | 分（如 50元 → 5000） | | deep_conversion_behavior_bid_adjustment | string | 深度优化行为出价相对调整（与 deep_conversion_behavior_bid 二选一） | 表达式，如 "+15%"、"*0.8" | | deep_conversion_worth_rate | number | 深度优化期望ROI系数（绝对值） | 无单位，范围 0.001~1000 | | deep_conversion_worth_rate_adjustment | string | 深度优化期望ROI系数相对调整（与 deep_conversion_worth_rate 二选一） | 表达式，如 "+10%"、"-5%"、"*1.2"、"+0.5" | | auto_acquisition_enabled | boolean | 一键起量开关 | true/false | | auto_acquisition_budget | number | 一键起量预算（绝对值） | 分（范围 20000~10,000,000，即 200~100,000 元） | | auto_acquisition_budget_adjustment | string | 一键起量预算相对调整（与 auto_acquisition_budget 二选一） | 表达式，如 "+10%"、"-20%"、"+100"；仅已开启时可用，新开启时请用绝对值 | | auto_derived_creative_enabled | boolean | 创意衍生开关 | true/false；开启时脚本自动查询 muse_derive_switch_info/get 校验可用衍生方式 | | auto_derived_creative_method_type_list | string[] | 创意衍生偏好（开启时可选） | 开启时可选：不传则自动使用 API 返回的默认推荐项；传入时脚本自动校验合法性。关闭时无需传入 |

金额字段统一使用分：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: {}（空对象）。

完整定向维度对照表

| 定向维度 | targeting 子字段 | 说明 | 获取方式 | |----------|-----------------|------|----------| | 地域 | geo_location.regions + geo_location.location_types | regions 通过地域查询获取；location_types 常见值 LIVE_IN（常住） | get-targeting-lookup.mjs type:geo + 枚举查询 | | 性别 | gender | ["MALE"] / ["FEMALE"] | 直接构造 | | 年龄 | age | [{"min":25,"max":29}]（闭区间，不要合并连续段） | 直接构造 | | 操作系统 | user_os | 支持简化格式如 ["ANDROID_10+"]，脚本自动展开 | 查枚举后直接构造 | | 排除操作系统 | excluded_os | 同 user_os 简化格式 | 查枚举后直接构造 | | 学历 | education | 传中文如 ["本科", "硕士"]，脚本自动匹配枚举 | 脚本自动匹配 | | 婚恋状态 | marital_status | 枚举查询 | 查枚举后直接构造 | | 联网方式 | network_type | 传 ["4G"]、["5G"]，脚本自动匹配枚举 | 脚本自动匹配 | | 设备价格 | device_price | 传 ["2500以上"]，脚本自动展开为价格区间枚举 | 脚本自动匹配 | | 设备品牌型号 | device_brand_model | 必须使用数字 ID | get-targeting-lookup.mjs type:device | | 应用安装状态 | app_install_status | 仅推广 APP 时可用 | 查枚举后直接构造 | | 游戏消费能力 | game_consumption_level | 枚举查询 | 查枚举后直接构造 | | 兴趣分类 | interest_category_id_list | 兴趣分类 ID 列表 | 通过 tencentads-targeting 获取 | | 兴趣关键词 | interest_keyword_id_list | 兴趣关键词 ID 列表 | 通过 tencentads-targeting 获取 | | 行为分类 | behavior_category_id_list | 行为分类 ID 列表 | 通过 tencentads-targeting 获取 | | 行为关键词 | behavior_keyword_id_list | 行为关键词 ID 列表 | 通过 tencentads-targeting 获取 | | 自定义人群 | custom_audience | 人群包 ID 列表 | 用户提供 | | 排除人群 | excluded_custom_audience | 排除的人群包 ID | 用户提供 | | 排除已转化 | excluded_converted_audience | 见下方格式说明 | 查枚举后直接构造 | | 微信广告行为 | wechat_ad_behavior | 见下方格式说明 | 脚本自动匹配 |

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

定向强约束

命中触发规则后，必须先调用 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%"}'

示例 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}'

注意事项

targeting 中不能包含非法字段：完整清单见上方"定向强约束"章节，脚本会拦截报错。
targeting 枚举自动匹配：脚本内置 resolveTargetingFields，支持传入简化值自动转换为 API 标准枚举。覆盖维度：education（中文 → 枚举，如 "本科" → "BACHELOR"）、network_type（如 "4G" → "NET_4G"）、device_price（简化描述 → 多个价格区间枚举）、user_os / excluded_os（如 "ANDROID_10+" → 展开为 ANDROID_VERSION_10~15 列表）、wechat_ad_behavior（中文行为名 → 枚举 key）。详见上方"定向更新 SOP"章节。
定向辅助脚本：get-targeting-lookup.mjs 和 get-enum-options.mjs 在本 skill 的 scripts/ 目录下可直接调用（软链接指向共享实现）。
delivery_time_ranges 格式：每条格式为 "<Weekday> <HH:MM>~<HH:MM>"，支持 Monday~Sunday 和 Mon~Sun 缩写。传 ["all"] 表示全时段投放。脚本内部自动转换为 336 位 time_series 字符串。
first_day_begin_time：首日开始投放时间，格式 HH:MM:SS（如 09:00:00），默认 00:00:00。可单独传入，也可与 delivery_time_ranges 同时传入。同时传入时脚本会进行交叉校验：根据广告的 begin_date 判断首日星期几，检查该时间槽在 time_series 中是否为投放状态，不兼容则报错。重要：用户未明确要求修改 first_day_begin_time 时，禁止自行添加该参数——多传会触发 API 对 begin_date 的连带校验，导致已投放广告更新失败。
创意衍生 auto_derived_creative 自动校验：开启创意衍生时，脚本自动调用 muse_derive_switch_info/get 查询该广告可用的衍生方式。auto_derived_creative_method_type_list 在开启时为可选参数——不传则自动使用 API 返回的默认推荐项，传入时脚本校验每项是否对该广告可用。关闭创意衍生时直接传 auto_derived_creative_enabled: false 即可。auto_derived_creative_method_type_list 支持中文别名自动解析：用户可传入中文描述（如 ["AI模板", "扩图"]）或标准枚举 key（如 ["AUTO_DERIVED_CREATIVE_METHOD_TYPE_TEMPLATE"]），脚本自动转换为 API 所需的标准枚举值。支持的中文别名映射见 _tencent-ads-cli/enums.ts 中的 AUTO_DERIVED_CREATIVE_METHOD_TYPE_ALIAS。
无变化字段自动跳过：脚本会先查询广告当前值，如果某字段的目标值与当前值一致，该字段会被跳过（不调用更新 API），输出中会列出 skipped_fields。
广告存在性校验：脚本执行前会先查询广告是否存在、是否已删除。如果广告不存在或已删除，直接报错不调用更新 API。
搜索广告拦截：当前版本咱不支持搜索广告更新操作，脚本执行前会检查广告的 site_set 是否包含搜索版位（SITE_SET_WECHAT_SEARCH、SITE_SET_QBSEARCH、SITE_SET_SEARCH_MOBILE_UNION）。如果是搜索广告，脚本会直接报错并输出 is_search_ad: true 标识，不调用更新 API。
一键起量编辑规则：

⛔ 智投项目不支持使用一键起量：如果目标广告是智投项目，不允许执行一键起量的开启、关闭或预算调整操作。应直接拒绝并告知用户：「智投项目不支持使用一键起量功能，一键起量仅适用于标准投放广告。」
新开启（当前关闭 -> enabled=true）：必须同时设置 auto_acquisition_budget，传入绝对值（分）
新关闭（当前开启 -> enabled=false）：不可同时设置 budget
已开启时调整 budget：传入 auto_acquisition_budget（绝对值，分）或 auto_acquisition_budget_adjustment（相对表达式，如 "+10%"、"+20000"）均可，脚本内部自动完成先关闭再用新预算重新开启的流程（见示例 16、16a）。
已关闭时：不可单独调整 budget（如需设置请同时传 auto_acquisition_enabled: true）

创意衍生编辑规则：

开启（enabled=true）：脚本自动查询 muse_derive_switch_info/get 获取可用衍生方式。若广告不支持衍生（API 返回 show_derive_method=false 且无可用方式），脚本报错。可选传入 auto_derived_creative_method_type_list 指定偏好，不传则使用默认推荐。
关闭（enabled=false）：直接关闭，无需传 method_type_list
仅更新偏好：不传 enabled，仅传 auto_derived_creative_method_type_list 可单独更新衍生偏好（不校验可用性，适用于已知合法值的场景）

批量更新脚本（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）

执行流程

预校验所有 task 格式（fast-fail）
按 account_id 分组
各账号并行处理：
- 批量前置查询（同账号内一次 adgroups/get）
- 逐个广告串行：buildUpdateBody + adgroups/update
各账号并行回查验证
汇总输出所有结果

输出格式

{
  "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

部分成功场景的 Agent 行为

批量更新可能出现部分成功、部分失败的情况。Agent 必须：

逐条展示结果：遍历 results 数组，向用户说明每个广告的更新结果
重点关注失败项：失败广告的 error 和 message 必须完整告知用户
检查 side_effects：如果失败结果中包含 side_effects 字段，必须告知用户已发生的副作用（如一键起量在调整预算时已被关闭但主更新失败）
回查比对：对成功的广告，基于 _verify 数据与用户期望对比
回查失败提醒：如果输出中包含 _verify_failed 的广告，提醒用户手动确认这些广告的更新结果

腾讯广告投放-更新广告

广告/智投项目通用更新（Adgroup General Update）

SOP 决策流程

脚本选择

单广告/项目流程

批量更新流程

步骤 1：意图识别

步骤 2：参数构造

步骤 3：执行脚本

步骤 4：回查验证

步骤 5：反思比对

支持的更新字段

定向更新 SOP（targeting 字段详细指引）

定向查询触发规则

完整定向维度对照表

定向更新示例

定向强约束

不支持修改的字段（创建时绑定）

脚本调用示例

示例 1：修改出价

示例 2：同时修改出价和预算

示例 3：修改定向为不限

示例 3b：修改定向（地域+年龄+学历+联网方式）

示例 4：暂停广告

示例 5：开启一键起量

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

示例 6b：修改投放时段并指定首日开始时间

示例 6c：仅修改首日开始时间（无需同时传投放时段）

示例 7：多字段同时更新

示例 8：出价下调 10%

示例 9：预算翻倍

示例 10：出价加 0.5 元，预算增加 30%

示例 11：深度优化行为出价设为 30 元

示例 12：深度优化行为出价下调 15%

示例 13：深度优化期望ROI系数设为 1.5

示例 14：深度优化期望ROI系数上调 10%

示例 15：关闭一键起量

示例 16：一键起量已开启时调整起量预算

示例 16a：一键起量已开启时用相对表达式调整起量预算

示例 17：开启创意衍生（自动使用推荐衍生方式）

示例 18：开启创意衍生并指定衍生方式

示例 19：关闭创意衍生

注意事项

批量更新脚本（update-adgroup-batch.mjs）

适用场景

入参格式

约束

执行流程

输出格式

脚本调用示例

示例 B1：同账号多广告批量更新（相同字段）

示例 B2：同账号多广告异构更新（不同字段）

示例 B3：跨账号批量更新

示例 B4：使用文件传参（参数较长时推荐）

部分成功场景的 Agent 行为