广告/智投项目通用更新（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 ''

批量更新：

node scripts/update-adgroup-batch.mjs ''

步骤 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%"}'

示例 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. 一键起量编辑规则：

   • ⛔ 智投项目不支持使用一键起量：如果目标广告是智投项目，不允许执行一键起量的开启、关闭或预算调整操作。应直接拒绝并告知用户：「智投项目不支持使用一键起量功能，一键起量仅适用于标准投放广告。」
   • 新开启（当前关闭 -> 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）

9. 周期达成编辑规则：详情见 references/smart-delivery-period-update.md。核心要点：

   • ⚠️ 周期达成开关不可修改：smart_delivery_period_switch 在创建时确定后无法通过编辑接口开启或关闭。非周期达成项目不能变成周期达成项目，反之亦然。
   • ⚠️ 周期达成项目的特殊限制：如果目标项目是周期达成项目，以下限制自动生效：
     • 禁止修改：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 × 出价 × 周期天数
   • 修改续投开关（smart_delivery_period_continue）：
     • 从"不续投"→"续投"（PERIOD_CONTINUE_SWITCH_ON）：项目需未过期，切换后 end_date 自动清空（变为长期投放）
     • 从"续投"→"不续投"（PERIOD_CONTINUE_SWITCH_OFF）：系统自动计算当前周期的 end_date
   • 修改周期预算（smart_delivery_period_budget）：只允许提升，不允许降低

10. 创意衍生编辑规则：<