name: tencentads-management description: 腾讯营销（原腾讯广告）管理 — 跨账户查询营销单元（原广告）/创意/素材等多层级数据及报表指标；查看营销单元完整配置（定向、出价、转化、版位等）与智能投放项目详情；获取创意列表及组件详情，单创意时自动解析组件并获取图片/视频预览 URL；管理关键词和否定词的增删改查；创建推广内容资产。 license: MIT compatibility: any metadata: author: Tencent Ads Delivery Team version: "0.5.7" icon: megaphone category: tencent-ads

腾讯广告管理（Tencent Ads Management）

前置依赖：运行脚本前需安装 CLI — npm install tencentads-cli@1.0.0（需要 Node.js ≥ 20）

腾讯广告的综合管理技能，提供以下核心能力：

1. 综合数据报表查询（query-report.mjs）：支持跨账户查询广告/创意/组件/素材等多层级数据，同时返回属性字段和报表指标数据。
2. 广告详情查询（query-adgroups.mjs）：获取广告的完整配置信息，包括定向设置、出价策略、转化规格、版位配置、投放时段等详细属性。
3. 智能投放项目详情查询（query-adgroups.mjs）：获取智能投放项目的详细配置信息，支持按需指定返回字段。
4. 创意列表查询（query-creatives.mjs）：获取创意的完整信息，包括创意组件引用、投放模式、创意类型等。当查询结果只有 1 条创意时，脚本自动解析组件详情并获取图片/视频预览 URL，一次调用即可返回完整的创意 + 组件 + 素材预览信息。
5. 操作日志查询（query-operation-logs.mjs）：查询广告/创意对象的操作日志，返回每次操作（新建/修改）前后的字段变化详情，支持按日期范围、对象 id、操作动作等过滤，详见 references/operation-log-list-get.md。
6. 关键词管理（bidword/add.mjs / bidword/update.mjs / bidword/delete.mjs / bidword/get.mjs）：管理广告的关键词（竞价词），支持创建、更新、删除和查询操作。
7. 否定词管理（negativewords/add.mjs / negativewords/update.mjs / negativewords/get.mjs）：管理广告的否定词，支持新增、更新和查询操作。
8. 推广内容资产管理：创建推广内容资产（marketing_asset），支持金融、教育、房地产、旅游、餐饮等多种资产类型。详细说明见 references/marketing-asset.md，执行前务必先读取该文档。

重要提示: 本技能基于腾讯广告营销 API（api.e.qq.com）API。以本文档为准，字段名称、参数结构可能与开放 API 不同，请勿混淆。

所有 API 调用均通过本技能的专用脚本执行，脚本负责参数构建与数据处理。Agent 只需关注：从用户意图中提取查询参数，并解读返回的数据。

脚本选择指南

脚本调用格式统一： - Bash / Zsh / Git Bash：node scripts/<脚本名>.mjs '<JSON 参数>'（直接传 JSON 字符串） - Windows PowerShell：node scripts/<脚本名>.mjs --base64 <Base64字符串>（必须使用 --base64）

执行脚本时先进入本 skill 根目录，再按相对 scripts/ 路径调用。

⚠️ 跨平台 JSON 参数传递规则（经实测验证）

Bash / Zsh / Git Bash

直接传 JSON 字符串，单引号包裹即可：

node scripts/query-report.mjs '{"account_ids":["73412663"],"date_range":{"start_date":"2026-04-13","end_date":"2026-04-13"},"level":"ADGROUP"}'

Windows PowerShell

PowerShell 的引号解析规则复杂，直接传 JSON 字符串会导致双引号被吞掉。必须使用 --base64 方式，通过 Here-String 构造 JSON 再编码为 Base64，彻底规避引号问题：

$json = @'
{"account_ids":["73412663"],"date_range":{"start_date":"2026-04-13","end_date":"2026-04-13"},"level":"ADGROUP"}
'@
$base64 = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($json))
node scripts/query-report.mjs --base64 $base64

⚠️ Here-String 格式要求极其严格（违反则 PowerShell 直接报语法错误）：

1. @' 后面必须立即换行，同一行不能跟任何字符（包括空格）
2. '@ 必须单独一行且顶格写，前面不能有空格或缩进
3. JSON 内容从 @' 的下一行开始书写

```powershell

❌ 错误：@' 后面直接跟了 JSON 内容

$json = @'{"account_ids":["73412663"]}'@

❌ 错误：'@ 前面有空格

$json = @' {"account_ids":["73412663"]} '@

✅ 正确：@' 后立即换行，'@ 顶格独占一行

$json = @' {"account_ids":["73412663"]} '@ ```

⛔ SOP 决策流程（严格按顺序执行，不可跳步）：

步骤1                步骤2                步骤2.5                                                              步骤3
意图识别  ─────→    分流路由   ─────→  字段名确认(> **🚫🚫🚫 禁止猜测字段名！违反此规则 = 查询失败！**)   ─────→       执行查询
是否使用本SKILL      │
                     ├─ 路径A（报表/效果数据）─→ 字段名确认（见步骤2.5）─→ query-report.mjs → 结束
                     │
                     ├─ 路径B（项目/广告/创意详情）
                     │    │
                     │    └─ query-adgroups / query-creatives
                     │       （有时间范围时通过 filtering 中 created_time 筛选）
                     │
                     └─ 路径C（营销资产查询）─→ 见下方"营销资产查询（路径 C）"

创意查询分支：
  query-creatives.mjs 自动判断：
    │
    ├─ 查询结果只有 1 条创意（单个创意详情）
    │    → 自动执行完整解析流程：
    │      ├─ 1. 从 creative_components 提取 component_id
    │      ├─ 2. 批量拉取组件详情
    │      ├─ 3. 从组件中提取 image_id / video_id
    │      ├─ 4. 获取图片/视频预览 URL
    │      └─ 5. 内联到 _component_detail + _preview，一次返回完整创意+组件+素材预览
    │
    └─ 查询结果有多条创意（创意列表）
         → 只返回创意基本信息，不解析组件

SOP 决策流程（高优先级，覆盖后文冲突）

若本节与下文表述冲突，以本节为准。

步骤1：意图识别 — 是否使用本 SKILL

用户意图必须命中以下任一类别，才进入本 SKILL 的处理流程：

⚠️ 关键规则：用户笼统说"查询广告数据"、"看下创意数据"等，未明确提到指标关键词（消耗、曝光、点击等）时，一律归入 B 类（实体查询），而非 A 类（报表）。只有明确提到指标或趋势时才走报表。

❌ 不命中 → 不使用本 SKILL，交给其他技能处理。

步骤 1.5：确定实体类型 — tencent_ads_type 参数（所有脚本通用）

⚠️ 必须在调用任何脚本前确定 tencent_ads_type，该参数直接影响返回字段的命名。

tencent_ads_type 是枚举类型，只允许以下三个值，传其他值脚本会报错退出：

规则： - 用户提到"项目"、"智投项目"、"智能投放项目" → tencent_ads_type: "smart" - 用户提到"竞价广告"、"3.0广告"、"非智投广告" → tencent_ads_type: "standard" - 用户只说"广告"或未明确说明 → tencent_ads_type: "all"（默认，包含智投项目 + 竞价广告，不注入 smart_delivery_platform 过滤，不做字段重命名） - ⚠️ 只允许传 "smart" / "standard" / "all" 三个枚举值之一，传其他任何值（如 "project"、"ad" 等）脚本会直接报错 - tencent_ads_type 对所有脚本（query-report.mjs、query-adgroups.mjs、query-creatives.mjs）均适用

步骤2：分流路由 — 报表 or 详情

⚠️ 时间范围修饰对象判断（必须在分流前执行）

用户说的时间范围修饰的是「报表数据」还是「广告实体」？

用户说法	时间修饰对象	走向
"最近一周的消耗" / "最近7天的效果" / "上周的报表"	报表数据	路径 A
"最近一周的广告" / "最近7天的项目" / "上周的创意" （无效果指标词）	广告实体	路径 B（filtering 加 created_time）
"最近一周内创建的广告" / "这周新建的项目"	广告实体	路径 B（filtering 加 created_time）

判断规则：用户说"最近N天/周的广告/项目/创意"但没有提到任何效果指标词（消耗、曝光、点击、转化、ROI等）→ 一律视为查广告实体，走路径 B，通过 filtering 中的 created_time 筛选。

命中类别 A（报表/效果数据）且时间范围修饰的是报表数据
  └─→ 直接走【路径 A】

命中类别 B（实体列表/详情，不涉及报表指标）
或 用户说"最近N天的广告/项目/创意"但无效果指标词
  └─→ 进入【路径 B】二次意图判断

⚠️ "数据"一词的歧义消解规则

用户说"查看创意/广告的数据"时，必须判断是否包含效果指标意图，不能仅凭"数据"二字走路径 A：

规则：仅有"数据"二字、不带任何效果指标词（消耗、曝光、点击、转化、ROI、成本等）→ 默认视为查询实体详情，走路径 B。

路径 A：与报表/效果数据相关 → query-report.mjs

直接使用 query-report.mjs，一次请求同时返回实体属性 + 报表指标，流程结束。

⚠️ 路径 A 排除规则：用户说"最近N天的广告/项目/创意"但未提及任何效果指标词 → 不走路径 A，转路径 B。

路径 B：与项目/广告/创意详情相关（不涉及报表指标） → 直接调用详情脚本

根据用户查询目标，直接调用对应的详情脚本。如果用户带有时间范围筛选条件（如"最近3天的广告"、"这周新建的项目"），通过 filtering 中的 created_time 进行筛选，无需先走 query-report.mjs。

⚠️ 创意查询的组件解析策略（脚本自动判断，Agent 无需控制）： - 查询结果只有 1 条创意：脚本自动从 creative_components 中提取所有 component_id，调用组件详情接口拉取组件详情，再从组件中提取 image_id / video_id，获取预览 URL。最终将组件内容内联到 _component_detail 字段，图片/视频预览信息内联到 _preview 字段。 - 查询结果有多条创意：只返回创意基本信息，不解析组件，避免大量 API 请求影响性能。

路径 C：营销资产查询

当用户需要查询营销资产（推广产品、应用包、渠道包等）时，根据资产类型选择对应的查询方式：

步骤 2.5：字段名确认 — 不在常用映射表中的字段必须先查字典

⚠️ 强制规则：禁止猜测字段名！

当用户请求的报表指标或广告字段不在下方「常用报表字段映射」表中时，必须先用 --query-fields 查询字段字典，确认准确的 API 字段名后再构造请求。

绝对禁止根据英文命名规律自行拼凑字段名（如猜测 "关注数" → wechat_official_account_follower_count，实际应为 scan_follow_user_count）。API 字段名与直觉差异极大，猜测几乎必错。

判断标准：逐一检查用户要求的每个指标/字段，如果在「常用报表字段映射」或「常用 fields 字段」表中能找到精确对应 → 直接使用；找不到 → 必须查字典。

查字典方法： - 报表指标字段：node scripts/query-report.mjs --query-fields "关键词1,关键词2" - 广告配置字段：node scripts/query-adgroups.mjs --query-fields "关键词1,关键词2"

示例：用户要求查看"5秒播放数、关注数、关注成本、关注率" 1. 检查常用映射表 → 这4个指标都不在表中 2. 执行：node scripts/query-report.mjs --query-fields "5秒播放,关注" 3. 从返回结果中确认准确字段名，再构造 fields 参数

步骤3：执行查询 — 快速参考

脚本：query-report.mjs

这是本技能的核心脚本，封装了报表查询的全部复杂逻辑。

脚本自动处理的逻辑（Agent 无需关心）

1. 标准过滤条件：根据 level 自动构建基础过滤条件 + 智投/非智投区分条件（通过 LEVEL_FILTERING_CONFIG 配置驱动）
2. 广告层级（ADGROUP 等）：adgroup.brand_ad_type + adgroup.campaign_type + adgroup.smart_delivery_platform
3. 创意层级（DYNAMIC_CREATIVE）：dynamic_creative.brand_ad_type + adgroup.campaign_type + dynamic_creative.smart_delivery_platform
4. 维度层级（REGION/CITY/AGE/GENDER 等）：使用对应 report.* 前缀
5. 模糊搜索字段自动切换：fuzzy_name 在广告层级使用 adgroup.fuzzy_name，在创意层级使用 dynamic_creative.fuzzy_name
6. group_by 推导：根据 level 自动推导合适的 group_by（如 ADGROUP → ["adgroup_id"]，DYNAMIC_CREATIVE → ["dynamic_creative_id"]，REGION → ["area_id"]）
7. fields 补全：未指定 fields 时，自动包含该 level 的默认属性字段 + 常用报表字段
8. 返回数据裁剪：移除空对象和无效字段，减少 Agent 解析负担
9. 默认排序：未指定 order_by 时，自动使用 [{"sort_field": "report.default_order_by", "sort_type": "ASCENDING"}]，Agent 无需手动传 order_by，除非用户明确要求按某个指标排序

调用方式

node scripts/query-report.mjs '<JSON 参数>'

参数说明

使用示例

1. 查询所有广告列表（最常用，默认模式）

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"}}'

不传 tencent_ads_type、fields、group_by 时，脚本默认 tencent_ads_type: "all"（智投项目 + 竞价广告全部返回） + 默认属性与报表字段 + group_by: ["adgroup_id"]。

2. 查询智投广告

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"tencent_ads_type":"smart"}'

3. 查询指定广告 ID 的数据

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"adgroup_ids":["72536365535"]}'

传了 adgroup_ids 后，脚本自动切换到 specified 模式，只使用 ID 过滤，不加基础 3 条和智投/非智投条件。

4. 查看指定广告的分时趋势

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"adgroup_ids":["72536365535"],"group_by":["date","hour"],"page_size":100}'

分时查询：group_by 使用 ["date", "hour"]，脚本自动精简 fields 只保留报表指标。

5. 查看指定广告的按天趋势

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-19","end_date":"2026-03-25"},"adgroup_ids":["72536365535"],"group_by":["date"]}'

6. 按消耗排序

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"order_by":[{"sort_field":"report.cost","sort_type":"DESCENDING"}]}'

7. 用后置过滤筛选高消耗广告

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"post_filtering":[{"field":"report.cost","operator":"GREATER","values":["100000"]}]}'

8. 查询创意级别数据

查询智投项目下的创意列表：

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","tencent_ads_type":"smart"}'

查询竞价广告下的创意列表：

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","tencent_ads_type":"standard"}'

按创意名称模糊搜索（fuzzy_name 在创意层级自动使用 dynamic_creative.fuzzy_name）：

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","fuzzy_name":"品牌创意"}'

按投放模式筛选（只看组件化创意），通过 filtering 追加：

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","filtering":[{"field":"dynamic_creative.delivery_mode","operator":"EQUALS","values":["DELIVERY_MODE_COMPONENT"]}]}'

按创意状态筛选（竞价广告创意用 DYNAMIC_CREATIVE_STATUS_*，智投项目创意用 SMART_DYNAMIC_CREATIVE_STATUS_*）：

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","tencent_ads_type":"standard","filtering":[{"field":"dynamic_creative.system_status","operator":"IN","values":["DYNAMIC_CREATIVE_STATUS_PENDING","DYNAMIC_CREATIVE_STATUS_ACTIVE"]}]}'

按创意类型筛选（客户自建 vs 妙思自动生成）：

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","filtering":[{"field":"dynamic_creative.source","operator":"EQUALS","values":["AD_CREATIVE_SOURCE_NORMAL"]}]}'

创意层级自动处理说明： - operation_status 过滤自动使用 dynamic_creative.operation_status（不是 adgroup.operation_status） - 智投/非智投区分自动使用 dynamic_creative.smart_delivery_platform（不是 adgroup.smart_delivery_platform） - fuzzy_name 自动使用 dynamic_creative.fuzzy_name（不是 adgroup.fuzzy_name）

9. 查询账户汇总数据

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"is_total":true,"page_size":1}'

10. 按名称模糊搜索广告

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"fuzzy_name":"品牌推广"}'

10.5. 多账户同时查询

node scripts/query-report.mjs '{"account_ids":["39412855","73412663"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"}}'

account_id 支持传入数组，一次请求同时查询多个账户的数据。返回结果中每条数据包含 account_id 字段，可区分所属账户。

10.6. 自动分页拉取全部广告数据

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"fetch_all":true}'

开启 fetch_all 后，脚本自动翻页拉取所有数据，最终返回的 page_info 中 total_number 为全部条数，total_page 固定为 1。

fetch_all 使用规则

⚠️ 判断关键词：当用户使用"全部"、"所有"、"一共"、"总共"、"导出"、"拉取全量"、"完整列表"等词汇时，应设置 fetch_all: true。 当用户只是普通查询或明确指定了分页参数时，保持默认 fetch_all: false。

#### 11. 查询指定广告的分地域投放数据（受众分析-地域报表）

```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"REGION","adgroup_ids":["72536365535"]}'

分地域查询关键点：当用户要求"分地域"、"按地域"、"各地区"、"省份分布"等维度查看投放数据时，必须使用 level: "REGION"，脚本会自动推导 group_by: ["area_id"] 和正确的过滤条件。同理，"分城市" → level: "CITY"，"分年龄" → level: "AGE"，"分性别" → level: "GENDER"。切勿使用 level: "ADGROUP" 来查询地域/城市/年龄/性别维度的数据。

12. 按创建时间筛选广告/项目（adindex 实体过滤）

适用场景：用户说"最近 N 天内创建的项目/广告"、"本周新建的广告"等——这是对广告实体的筛选，不是报表时间窗口。 - date_range 用近期时间（如当天）即可，其值不影响广告实体的筛选 - 创建时间用 filtering 中的 adgroup.created_time，值为 YYYY-MM-DD HH:mm:ss 格式（如 "2026-03-18 00:00:00"），脚本内部自动转为时间戳

查询最近一周内创建的智投项目（不关心报表数据）：

node scripts/query-report.mjs '{
  "account_ids": ["39412855"],
  "date_range": {"start_date": "2026-03-27", "end_date": "2026-03-27"},
  "tencent_ads_type": "smart",
  "filtering": [
    {"field": "adgroup.created_time", "operator": "GREATER_EQUALS", "values": ["<7天前 YYYY-MM-DD 00:00:00>"]},
    {"field": "adgroup.created_time", "operator": "LESS_EQUALS",    "values": ["<今天 YYYY-MM-DD 23:59:59>"]}
  ],
  "fields": [
    "account_id",
    "adgroup.adgroup_id",
    "adgroup.adgroup_name",
    "adgroup.configured_status_cn",
    "adgroup.system_status_cn",
    "adgroup.smart_delivery_platform",
    "adgroup.project_ability_spec",
    "adgroup.begin_date"
  ]
}'

fields 里不含 report.* 字段时，date_range 仅作为接口必填项存在，对结果无实质影响。

13. 查询创意资产（文案素材）级别数据

当用户要查文案素材（标题/描述）维度的投放效果时，使用 CREATIVE_ASSET 级别。注意：过滤条件使用 report.* 字段，不使用 adgroup.* 字段。

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"CREATIVE_ASSET","group_by":["creative_asset_id","adgroup_id","dynamic_creative_id"],"order_by":[{"sort_field":"report.cost","sort_type":"DESCENDING"}],"fields":["creative_asset.creative_asset_id","creative_asset.creative_asset_name","creative_asset.component_id","creative_asset.component_type","creative_asset.component_value","creative_asset.component_custom_name","creative_asset.account_id","report.cost","report.view_count","report.valid_click_count","report.ctr","report.thousand_display_price","report.cpc","report.conversions_rate","report.adgroup_id","report.dynamic_creative_id"],"filtering":[{"field":"report.brand_ad_type","operator":"EQUALS","values":["BRAND_AD_TYPE_NONE"]},{"field":"report.campaign_type","operator":"EQUALS","values":["CAMPAIGN_TYPE_NORMAL"]},{"field":"report.creative_asset_sub_type","operator":"IN","values":["DESCRIPTION","TITLE"]}]}'

CREATIVE_ASSET 查询要点： - level 设为 "CREATIVE_ASSET"，group_by 包含 "creative_asset_id" - filtering 使用 report.* 字段（如 report.brand_ad_type、report.campaign_type、report.creative_asset_sub_type），不使用 adgroup.* 字段 - 按素材子类型过滤文案：report.creative_asset_sub_type IN ["DESCRIPTION", "TITLE"]

14. 查询组件级别数据

node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"COMPONENT"}'

返回结构

{
  "file_path": "/absolute/path/to/output/report_39412855_ADGROUP_20260325_20260325_20260325T103000.json",
  "summary": {
    "total_rows": 150,
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 150,
      "total_page": 8
    },
    "level": "ADGROUP",
    "date_range": { "start_date": "2026-03-25", "end_date": "2026-03-25" },
    "account_ids": [39412855],
    "tencent_ads_type": "all"
  },
  "preview": [
    {
      "account_id": 39412855,
      "adgroup": {
        "adgroup_id": 123456,
        "adgroup_name": "广告名称",
        "configured_status": "AD_STATUS_NORMAL"
      },
      "report": {
        "cost": 10000,
        "view_count": 50000,
        "valid_click_count": 1200,
        "ctr": "2.40"
      }
    }
  ]
}

输出说明：脚本会将完整查询结果写入 output/ 目录下的 JSON 文件，stdout 只返回文件路径、摘要信息和前 3 条预览数据。模型可通过 file_path 读取完整数据文件，编写实时分析脚本生成数据报告。

数据文件格式：output/report_<账户ID>_<level>_<日期范围>_<时间戳>.json，内容为 { "list": [...], "page_info": {...} }。

常用报表字段映射（用户描述 → fields 字段名）

当用户提到以下指标时，请在 fields 参数中使用对应的字段名：

提示：当用户要求查看多个指标时，请将所有对应的 report.* 字段都加入 fields 数组中。如果用户没有明确指定指标，可以不传 fields，脚本会自动使用默认字段集。

⚠️ 强制规则：上表仅列出最常用的 18 个字段，报表系统共有 854 个字段。如果用户提到的指标不在上表中，必须先执行 node scripts/query-report.mjs --query-fields "关键词" 查询字段字典，确认准确字段名后再构造请求。禁止自行猜测或拼凑字段名。

核心脚本

请求参数

必填参数

可选参数

level 数据维度与 group_by 对应表：

每个 level 只支持特定的 group_by 值，不传时脚本自动使用默认值。自定义 group_by 时必须从该 level 的合法值中选取，禁止使用不在此表中的值。

关键参数组合规则（必须遵守，否则 report 会返回空对象）:

1. order_by 排序规则：
2. 脚本已自动处理默认排序：未传 order_by 时，脚本自动使用 [{"sort_field": "report.default_order_by", "sort_type": "ASCENDING"}]。通常不需要手动传 order_by。
3. 仅当用户明确要求排序时才传：当用户描述中包含排序意图（如"按 XX 从高到低"、"按 XX 排序"等），按用户意图构造：
4. 格式：[{"sort_field": "report.xxx", "sort_type": "DESCENDING"}]
5. sort_type 枚举值：DESCENDING（降序，从高到低）、ASCENDING（升序，从低到高）
6. 示例：用户说"按曝光量从高到低排序" → [{"sort_field": "report.view_count", "sort_type": "DESCENDING"}]
7. 示例：用户说"按消耗升序" → [{"sort_field": "report.cost", "sort_type": "ASCENDING"}]

8. 最多支持 2 个排序条件

9. group_by 事实上必填：虽然协议定义为可选，但不传 group_by 时接口几乎不会返回有效 report 数据。每个 level 的合法值和默认值见上方 level 数据维度与 group_by 对应表。

10. hour 必须配 date：使用 hour 时必须同时带 date（如 ["date", "hour"] 或 ["adgroup_id", "date", "hour"]），单独传 hour 不带 date 不会报错但数据不完整（不同天的同一小时会被合并）。

11. 分时/按天趋势查询：查看指定广告的分时趋势 → group_by: ["date", "hour"]；查看指定广告的按天趋势 → group_by: ["date"]；查看广告列表的每日汇总 → group_by: ["adgroup_id", "date"]。

12. filtering 强烈推荐：不传过滤条件时，接口可能返回空结果或无法匹配到有效数据。

场景一：查询广告列表（无指定 adgroup_id）— 需要完整的标准过滤（基础 3 条 + 智投/非智投条件），详见下方。

场景二：查询指定广告 ID 的数据（如分时趋势、按天趋势）— 只需传 adgroup.adgroup_id 过滤即可，不需要加基础 3 条和智投/非智投条件，因为已经精确定位到具体广告。 json [{"field": "adgroup.adgroup_id", "operator": "EQUALS", "values": ["72536365535"]}]

场景一的标准过滤分为基础 3 条 + 第 4 条智投/非智投区分条件：

⚠️ 重要：filtering 中的过滤字段层级必须与 level 匹配，不同 level 使用不同的过滤字段前缀： - level 为 ADGROUP、COMPONENT 等 → 使用 adgroup.* 层级过滤字段 - level 为 DYNAMIC_CREATIVE → 混合使用：operation_status 和 brand_ad_type 使用 dynamic_creative.*，campaign_type 使用 adgroup.*（见下方详细说明） - level 为 CREATIVE_ASSET（创意资产级别）→ 使用 report.* 层级过滤字段（如 report.brand_ad_type、report.campaign_type、report.creative_asset_sub_type），不使用 adgroup.* 层级过滤 - level 为 ADVERTISER（账户级别报表）→ 不需要也不应该传任何实体层级的过滤条件

基础过滤条件（仅适用于 level 为 ADGROUP/DYNAMIC_CREATIVE/COMPONENT 等实体级别时）：

广告层级（level=ADGROUP）：

json {"field": "adgroup.brand_ad_type", "operator": "EQUALS", "values": ["BRAND_AD_TYPE_NONE"]}, {"field": "adgroup.campaign_type", "operator": "EQUALS", "values": ["CAMPAIGN_TYPE_NORMAL"]}

创意层级（level=DYNAMIC_CREATIVE，注意 brand_ad_type 前缀变为 dynamic_creative.*）：

json {"field": "dynamic_creative.operation_status", "operator": "EQUALS", "values": ["CALCULATE_STATUS_EXCLUDE_DEL"]}, {"field": "dynamic_creative.brand_ad_type", "operator": "EQUALS", "values": ["BRAND_AD_TYPE_NONE"]}, {"field": "adgroup.campaign_type", "operator": "EQUALS", "values": ["CAMPAIGN_TYPE_NORMAL"]}

⚠️ operation_status 仅在查询广告列表或创意列表时添加，查询报表数据（如汇总统计、效果分析等纯报表场景）时不添加此条件。 使用 query-report.mjs 脚本时，以上基础过滤条件由脚本自动构建，无需手动传入。

CREATIVE_ASSET 级别的过滤条件（使用 report.* 字段，不使用 adgroup.*）： json {"field": "report.brand_ad_type", "operator": "EQUALS", "values": ["BRAND_AD_TYPE_NONE"]}, {"field": "report.campaign_type", "operator": "EQUALS", "values": ["CAMPAIGN_TYPE_NORMAL"]} 如需按素材子类型过滤（如只看文案描述和标题）： json {"field": "report.creative_asset_sub_type", "operator": "IN", "values": ["DESCRIPTION", "TITLE"]}

⚠️ 注意：CREATIVE_ASSET 级别不需要也不应该加 adgroup.operation_status、adgroup.smart_delivery_platform 等 adgroup.* 过滤条件。

第 4 条：smart_delivery_platform（必须根据查询意图选择，同样仅适用于实体级别）：

⚠️ 广告层级（ADGROUP）与创意层级（DYNAMIC_CREATIVE）使用不同的字段： - level=ADGROUP → 使用 adgroup.smart_delivery_platform - level=DYNAMIC_CREATIVE → 使用 dynamic_creative.smart_delivery_platform - 使用 query-report.mjs 脚本时，脚本会根据 level 自动选择正确的字段，无需手动指定。

• 查智投广告/创意（默认，当前大部分广告都是智投广告）： json {"field": "adgroup.smart_delivery_platform", "operator": "GREATER_EQUALS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]} 或（创意层级）： json {"field": "dynamic_creative.smart_delivery_platform", "operator": "GREATER_EQUALS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
• 查非智投广告/创意（用户明确要求查非智投/竞价广告时）： json {"field": "adgroup.smart_delivery_platform", "operator": "LESS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]} 或（创意层级）： json {"field": "dynamic_creative.smart_delivery_platform", "operator": "LESS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}

⚠️ 智投和非智投不能在同一次请求中混合查询，每次请求只能查其中一种。

意图判断规则： - 用户说"查非智投广告"、"查常规广告"、"查老广告"、"不含智投"、"排除智投"、"竞价广告"、"只看竞价"、"不含智投项目" → 查常规广告（非智投）（LESS），只需一次请求 - 用户说"查智投广告"、"智投项目"、"智投报表" → 查智投广告（GREATER_EQUALS），只需一次请求 - 用户说"两种都看"、"智投和非智投都要" → 先查智投广告（GREATER_EQUALS），再查常规广告（非智投）（LESS），共两次请求（顺序发，不要并行） - ⚠️ 如果意图不确定（用户未明确指定智投或非智投），应发两次请求：先智投 GREATER_EQUALS，再非智投 LESS，以保证最终数据的准确性和完整性

1. fields 必须包含所需字段：
2. 查询广告列表时：fields 必须同时包含属性字段（如 adgroup.adgroup_id、adgroup.adgroup_name）和报表字段（如 report.cost），否则 report 会返回空对象。
3. 查询指定广告的分时/按天趋势时：fields 只需包含用户关心的报表指标即可（如 ["report.view_count", "report.view_user_count"]），不需要额外加 adgroup.* 属性字段和 account_id，因为已经通过 filtering 精确定位到了具体广告。
4. 实体级别查询（level 为 ADGROUP、DYNAMIC_CREATIVE、COMPONENT 等）：必须同时包含属性字段和报表字段，仅请求 report.* 字段而不请求对应的属性字段（如 adgroup.adgroup_id）会导致 report 返回空。应同时请求 adgroup.* 和 report.* 字段。

5. 账户级别查询（level 为 ADVERTISER）：查询的是账户维度汇总报表，只需传用户关心的 report.* 报表字段即可，不需要也不应该传 account_id、adgroup.* 等属性字段，否则会导致参数冗余。 > - ✅ 正确："fields": ["report.view_count", "report.cost"]

   • ❌ 错误："fields": ["account_id", "report.view_count", "report.cost"]

6. is_total 的正确用法：

7. is_total: false（默认）= 返回逐条明细数据（每个广告/创意一行），这是最常用的模式
8. is_total: true = 返回全账户汇总（所有广告合并为一条），此时仍需传 group_by、filtering 和 fields（包含属性+报表字段）

9. 查询广告列表时请使用 is_total: false

10. date_range vs adgroup.created_time：两套独立系统，含义完全不同

本接口底层由两个独立系统协同工作： - 报表系统：负责 report.* 字段的统计数据，由 date_range 控制统计区间 - adindex（广告实体索引）：负责返回哪些广告/创意实体，由 filtering 中的 adgroup.created_time 等条件控制

用途	参数	示例
控制报表指标的统计时间窗口	date_range	{"start_date":"2026-03-01","end_date":"2026-03-27"}
筛选某段时间内创建的广告/项目	filtering 中 adgroup.created_time	{"field":"adgroup.created_time","operator":"GREATER_EQUALS","values":["2026-03-20 00:00:00"]}

⚠️ 关键区别： - date_range 不是广告的创建时间，也不是投放时间，是报表统计窗口 - 如果某广告在 date_range 范围内没有消耗/曝光，report.* 字段会返回空，但广告实体本身仍然存在 - 只查广告/项目实体信息（不关心消耗数据）时，date_range 设为任意有效时间段即可（通常用近期时间）

意图判断规则（模型必须遵守）：

用户说的	正确做法
"最近一周的消耗数据" / "最近7天的报表"	date_range = 最近7天，不加 created_time 过滤
"最近一周内创建的广告/项目"	date_range = 当天（或近期），filtering 加 adgroup.created_time >= 7天前的时间戳
"最近一周的广告/项目/创意"（无效果指标词）	同"创建"处理：date_range = 当天，filtering 加 adgroup.created_time 范围，走路径 B
"最近一周内创建且有投放数据的广告"	date_range = 最近7天，filtering 同时加 adgroup.created_time 范围
"查看某个项目的历史数据"	date_range = 目标历史时间段，filtering 加 adgroup.adgroup_id

created_time 时间格式：值为 YYYY-MM-DD HH:mm:ss 格式字符串（如 "2026-03-21 00:00:00"），脚本内部自动转为 API 所需的 Unix 时间戳。 json // 示例：筛选 2026-03-21 00:00:00 ~ 2026-03-27 23:59:59 创建的项目 {"field": "adgroup.created_time", "operator": "GREATER_EQUALS", "values": ["2026-03-21 00:00:00"]}, {"field": "adgroup.created_time", "operator": "LESS_EQUALS", "values": ["2026-03-27 23:59:59"]}

1. report_only 默认不要传：report_only: true 表示仅查报表指标数据、不返回实体属性（广告名称、状态等）。只有在用户明确只需要效果数据（如"今天总消耗多少"）而不关心广告属性时才设为 true。大多数查询都需要同时看到广告属性和报表数据，因此默认不传或设为 false。

time_line 时间口径枚举值

过滤条件（filtering）

filtering 结构

{
  "field": "过滤字段",
  "operator": "操作符",
  "values": ["值1", "值2"]
}

常用过滤字段

广告层级（adgroup.*）

动态创意层级（dynamic_creative.*）

dynamic_creative.system_status 枚举值说明：

竞价广告（非智投）下的创意与智投项目下的创意，system_status 枚举值不同：

组件层级（component.*）

报表层级（report.*）

素材层级

产品层级（marketing_asset.*）

后置过滤条件（post_filtering）

用于基于报表指标数值进行筛选，在数据返回后过滤。

支持的过滤字段： - report.cost - 消耗 - report.view_count - 展示量 - report.valid_click_count - 有效点击量 - report.conversions_count - 转化数 - report.conversions_cost - 转化成本 - report.conversions_rate - 转化率

操作符说明

响应结构

{
  "data": {
    "list": [
      {
        "account_id": 39412855,
        "account": { ... },
        "adgroup": {
          "adgroup_id": 123456,
          "adgroup_name": "广告名称",
          "configured_status": "AD_STATUS_NORMAL",
          "system_status": "ADGROUP_STATUS_NORMAL",
          ...
        },
        "dynamic_creative": { ... },
        "component": { ... },
        "bidword": { ... },
        "report": {
          "cost": 10000,
          "view_count": 50000,
          "valid_click_count": 1200,
          "ctr": "2.40",
          "conversions_count": 100,
          "conversions_cost": 10000,
          ...
        },
        "image": { ... },
        "media": { ... },
        "video": { ... },
        "marketing_asset": { ... },
        "joint_budget_rule": { ... },
        "product_catalog": { ... },
        "project_creative": { ... },
        "video_aggregation": { ... },
        "creative_asset": { ... },
        "jump_info": { ... }
      }
    ],
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 150,
      "total_page": 8
    },
    "update_time": "2025-11-29 10:30:00"
  }
}

list 每项返回结构

常用 fields 字段

广告属性字段（adgroup.*）

报表指标字段（report.*）

完整字段列表见下方「字段字典参考 → 报表指标字典」，此处仅列举最常用的字段：

基础效果指标：

通用参数说明

以下公共约定由构建阶段自动内联：

以下内容为腾讯广告营销 API（api.e.qq.com）各 skill 共享的公共约定，会在构建阶段自动内联到目标 skill 文档中。各 skill 不需要重复这些内容。

基础信息

• Base URL: https://api.e.qq.com
• 认证方式: API Key 鉴权（api.e.qq.com），可通过 tencent-ads auth status 查看当前认证状态
• 权限要求: 需登录api.e.qq.com 并具有对应账户操作权限
• 时区: GMT+8（北京时间）
• 金额单位: 分（不是元），示例：10000 分 = 100 元人民币
• 时间戳: API 底层为秒级 Unix timestamp，但脚本统一使用 YYYY-MM-DD HH:mm:ss 格式（如 "2026-03-18 00:00:00"），脚本内部自动完成格式转换

调用方式

所有接口均通过 tencent-ads CLI 工具调用（agent 通过 bash 执行）。API Key 鉴权由 CLI 自动处理（通过 X-MKT-API-Key header），无需手动传入。

GET 请求

tencent-ads api '{
  "method": "GET",
  "path": "/v3.0/xxx/get",
  "account_id": "YOUR_ACCOUNT_ID",
  "params": {"page": 1, "page_size": 10}
}'

POST 请求

tencent-ads api '{
  "method": "POST",
  "path": "/v3.0/xxx/add",
  "account_id": "YOUR_ACCOUNT_ID",
  "body": {"account_id": 12345, "field1": "value1"}
}'

参数说明

严格规则：调用任何接口时，必须严格使用该接口文档中声明的 HTTP 方法（GET / POST），不得擅自更改。使用错误的请求方法会导致服务端返回 405 Method Not Allowed。

通用响应格式

所有接口返回的 JSON 响应都遵循以下格式：

{
  "code": 0,
  "message": "",
  "message_cn": "",
  "data": {
    // 接口特定的响应数据
  }
}

错误处理

tencent-ads api 返回的 JSON 响应中包含 code 字段： - code 为 0 表示成功 - code 非 0 时，检查 message_cn 获取中文错误说明

常见错误码

数值单位说明

金额单位

• 所有涉及金额的字段（出价、预算等）单位均为分（不是元）
• 示例：10000 分 = 100 元人民币
• 日预算范围：5000-400000000 分（50 元-400 万元）

时间单位

• 时间字段（created_time、last_modified_time、completed_time）：统一使用 YYYY-MM-DD HH:mm:ss 格式（如 "2026-03-18 00:00:00"），脚本内部自动与 API 的 Unix 时间戳互转
• 日期格式：YYYY-MM-DD
• 时间格式：HH:ii:ss
• 时区：GMT+8（北京时间）

分页参数

大多数列表查询接口支持以下分页参数：

标准分页

游标分页

分页响应

{
  "page_info": {
    "page": 1,
    "page_size": 10,
    "total_number": 100,
    "total_page": 10
  }
}

过滤参数

大多数查询接口支持 filtering 参数进行条件过滤：

filtering 结构

{
  "filtering": [
    {
      "field": "字段名",
      "operator": "操作符",
      "values": ["值1", "值2"]
    }
  ]
}

操作符说明

最佳实践

1. 请求方法：严格按照各接口文档声明的 HTTP 方法（GET/POST）发起请求，不得混用
2. 错误处理：始终检查响应中的 code 字段
3. 重试机制：对于系统错误（code = 6），可以实施指数退避重试
4. **API Key 如失效需重新配置
5. 分页处理：对于大数据量查询，使用游标分页性能更好
6. 字段筛选：使用 fields 参数只请求需要的字段，减少数据传输

字段字典参考

以下字典由构建阶段自动内联，包含所有可用字段的完整定义。

🚫 强制规则：遇到不在常用映射表中的字段名时，必须先查字典，禁止猜测！

用户描述中提到的字段名称往往与 API 实际字段名差异很大，例如： - "AIGC 创意" → smart_delivery_aigc_option（而非 aigc_creative） - "锁量" → flow_lock_status（而非 lock_status） - "关注数" → scan_follow_user_count（而非 wechat_official_account_follower_count） - "5秒播放数" → 需查字典确认（而非 video_play_5s_count）

本文档不可能穷举所有字段，但 adgroup-fields.json（236 个字段）和 report-fields.json（854 个字段）中有完整的字段定义。

强制做法：当用户提到的字段不在上方「常用报表字段映射」或「常用 fields 字段」表中时，必须先用 --query-fields 查询字段字典，确认正确字段名后再构造请求。绝对禁止根据英文命名规律自行拼凑字段名。

示例：用户说"帮我查询最近一周开启 AIGC 的广告" 1. 先查字典：node scripts/query-adgroups.mjs --query-fields "aigc" 2. 得到匹配字段（如 smart_delivery_aigc_option、smart_delivery_aigc_creative 等） 3. 再用正确的字段名构造查询请求的 fields 或 filtering 参数

示例：用户说"查看5秒播放数、关注数、关注成本" 1. 这些指标不在常用映射表中 → 必须查字典 2. 执行：node scripts/query-report.mjs --query-fields "5秒播放,关注" 3. 从返回结果中确认准确字段名，再构造 fields 参数

广告字段字典（adgroup.*）

广告字段定义存储在 resources/adgroup-fields.json 中（共 236 个字段，按分类组织：定向设置、广告基本信息、营销配置、投放时间与预算、出价与优化、深度优化、一键起量、版位与场景定向、创意相关、转化与数据源、搜索定向、动态广告、其他、智投项目专有、报表广告维度属性、分页）。

查询方式：通过 query-adgroups.mjs --query-fields [关键词] 获取字段定义。

自动中文名附加：query-adgroups.mjs 查询广告数据时，返回的每个字段自动附加中文名（如 adgroup_name: "xxx" 旁会有 广告名称: "xxx"），无需手动翻译。

报表指标字典（report.*）

报表指标字段定义存储在 resources/report-fields.json 中（共 854 个字段，按分类组织）。

查询方式：通过 query-report.mjs --query-fields [关键词] 获取字段定义。

⚠️ 强制使用场景：只要用户提到的报表指标不在「常用报表字段映射」表中，就必须先用 --query-fields 查询字段字典，确认正确的 report.* 字段名后再构造查询请求。这是强制步骤，不可跳过。

分页信息

注意事项

1. 请求方式: 该接口使用 POST 方法，参数放在请求体中（非 URL 参数）。

2. fields 字段格式: fields 中的字段使用 对象.属性 的格式，如 adgroup.adgroup_id、report.cost。顶层的 account_id 不带前缀。

3. 查询广告列表时：fields 必须同时包含属性字段（如 adgroup.*）和报表字段（report.*），否则 report 会返回空对象。

4. 查询指定广告的分时/按天趋势时：fields 只需包含用户关心的 report.* 指标即可。

5. 金额单位: 所有金额字段单位为分。

6. 示例：report.cost = 10000 表示消耗 100 元

7. adgroup.total_budget = 100000 表示预算 1000 元

8. 日期范围: 最早支持查询近 365 天的数据。start_date ≤ end_date，格式 YYYY-MM-DD。当天和昨天的日期均可使用。

9. 分页: 支持大页面（page_size 最大 99999999），但建议按需设置合理的分页大小。数据量大时注意响应时间。

10. report_only（慎用）: 设为 true 时表示仅查报表指标数据，不返回实体属性数据（广告名称、状态、预算、出价等业务字段都不会返回）。适用场景：用户只需要效果数据（消耗、点击、转化等）而不关心广告属性信息，如纯数据汇总统计。查询广告列表时应使用默认值 false（或不传此参数），以同时获取广告属性和报表数据。

1. group_by（关键）: 聚合参数决定了数据的汇总维度。不传 group_by 会导致 report 返回空对象。每个 level 的合法值和默认值见 level 数据维度与 group_by 对应表。

1. 二维过滤（or_filtering）: 支持 OR 逻辑组合过滤。外层数组为 OR 关系，内层 and_filtering 数组为 AND 关系。

2. 常见的返回空数据原因排查:

3. list 返回空数组（total_number: 0）：
   • 缺少 smart_delivery_platform 过滤或方向错误（最常见原因）→ 智投和非智投必须分开查。默认应用 LESS（查常规广告/非智投）。 若用户明确要求查智投，用 GREATER_EQUALS。
   • 使用了 report_only: true 导致不返回实体属性数据 → 去掉 report_only 或设为 false
   • filtering 其他条件过于严格 → 先用基础 3 条 + 智投/非智投过滤查询
4. report 返回空对象（report: {}）：
   • 缺少 group_by 参数 → 加上 "group_by": ["adgroup_id"]（列表查询）或 ["date", "hour"]（分时查询）
   • 查询广告列表时缺少 filtering 参数 → 至少加上基础 3 条过滤 + 智投/非智投条件
   • 查询广告列表时 fields 只有 report.* 没有 adgroup.* → 补充属性字段

5. 以上各项需同时正确才能返回有效数据

6. 🚫 禁止重复调用（极其重要）：

   • 脚本调用成功返回了 list 数据（即使所有指标值为 0），说明参数正确、接口正常，应直接使用返回数据向用户展示，绝不要因为数据值全为 0 而反复修改参数重试。
   • 数据值为 0 是正常的业务情况（如该日期没有投放、没有消耗等），不代表参数有误。
   • 区分"接口报错"和"数据为零"：
   • 接口报错（返回 error 字段、HTTP 错误等）→ 检查参数后可重试 1 次
   • list 返回空数组（total_number: 0）→ 可按第 9 条排查后重试 1 次
   • list 有数据但 report 中的值为 0 → 这是正常结果，直接使用，禁止重试
   • 严禁以下行为：反复调整 group_by、level、fields、is_total 等参数尝试"修复"数据；绕过脚本直接调用底层 API；查看脚本源码试图排查问题。这些行为浪费大量步骤且不会改变结果。

脚本：query-adgroups.mjs

广告详情查询脚本，用于获取广告的完整配置信息。

适用场景

• 需要查看广告的详细配置（定向、出价、转化规格、版位、投放时段等），而不仅是基本属性和报表数据
• 需要查看已删除的广告信息
• 需要根据广告名称、状态、创建时间等条件筛选广告
• 需要获取广告的定向设置详情（地域、年龄、性别、设备等）
• 需要查看广告的深度转化规格、用户行为数据源等高级配置

与 query-report.mjs 的区别

| 返回报表数据 | ✅ 返回消耗、曝光、点击等报表指标 | ❌ 不返回报表数据 | | 返回配置详情 | ⚠️ 仅返回基本属性 | ✅ 返回完整配置（定向、出价、转化、版位等） | | 需要日期范围 | ✅ 必填 | ❌ 不需要 | | 支持跨账户 | ✅ 支持 | ❌ 单账户 | | 查看已删除广告 | ❌ 不支持 | ✅ 支持 | | 支持游标分页 | ❌ | ✅ 支持 |

调用方式

node scripts/query-adgroups.mjs '<JSON 参数>'

参数说明

过滤条件（filtering）

使用示例

1. 查询指定广告 ID 的详情（最常用）

node scripts/query-adgroups.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"]}'

2. 查询账户下所有广告列表

node scripts/query-adgroups.mjs '{"account_id":"39412855"}'

3. 查询指定返回字段

node scripts/query-adgroups.mjs '{"account_id":"39412855","fields":["adgroup_id","adgroup_name","configured_status","targeting","bid_amount","daily_budget"]}'

4. 根据广告名称模糊搜索

node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"adgroup_name","operator":"CONTAINS","values":["品牌推广"]}]}'

5. 按状态筛选广告

node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"configured_status","operator":"EQUALS","values":["AD_STATUS_NORMAL"]}]}'

6. 查询已删除的广告

node scripts/query-adgroups.mjs '{"account_id":"39412855","is_deleted":true}'

7. 使用游标分页获取全量数据

# 第一次请求
node scripts/query-adgroups.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100}'

# 后续请求（使用上一次返回的 cursor）
node scripts/query-adgroups.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100,"cursor":"xxx"}'

8. 按创建时间筛选（查最近 7 天创建的广告）

node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"created_time","operator":"GREATER_EQUALS","values":["2026-04-03 00:00:00"]}]}'

created_time 支持 YYYY-MM-DD HH:mm:ss 格式，脚本自动转为 Unix 时间戳。也支持直接传时间戳。

返回结构

{
  "list": [
    {
      "adgroup_id": 72536365535,
      "adgroup_name": "广告名称",
      "campaign_id": 12345,
      "configured_status": "AD_STATUS_NORMAL",
      "system_status": "ADGROUP_STATUS_NORMAL",
      "marketing_goal": "MARKETING_GOAL_PRODUCT_SALES",
      "bid_amount": 5000,
      "optimization_goal": "OPTIMIZATIONGOAL_ECOMMERCE_ORDER",
      "begin_date": "2026-03-20",
      "end_date": "2026-04-20",
      "daily_budget": 100000,
      "targeting": {
        "geo_location": { "regions": [110000, 310000] },
        "age": [{ "min": 18, "max": 45 }],
        "gender": ["MALE", "FEMALE"]
      },
      "site_set": ["SITE_SET_WECHAT"],
      "bid_mode": "BID_MODE_OCPM",
      "smart_bid_type": "SMART_BID_TYPE_CUSTOM",
      ...
    }
  ],
  "page_info": {
    "page": 1,
    "page_size": 10,
    "total_number": 50,
    "total_page": 5
  }
}

注意事项

1. 请求方式: 该脚本使用 GET 方法。
2. 金额单位: 所有金额字段单位为分（如 bid_amount = 5000 表示出价 50 元）。
3. 分页限制: 普通分页模式下 page 最大 100，page_size 最大 100。需获取全量数据时推荐使用游标分页模式。
4. 字段选择: 未指定 fields 时脚本自动使用默认字段集，覆盖基础信息、定向、出价、转化、智投项目配置（含周期达成、成本保障、直播加热等）等全量字段。如需查看特定字段，建议显式传入 fields 参数。
5. 与 query-report.mjs 配合: 先用 query-report.mjs 获取广告列表和报表数据，找到感兴趣的广告后，再用 query-adgroups.mjs 查看其详细配置。

智能投放项目详情查询

智能投放项目复用了 adgroup（广告）的接口，因此接口中的字段名与项目概念的对应关系如下：

项目概念	接口字段	说明
项目 ID	adgroup_id	智投项目 ID 对应接口中的广告 ID
项目名称	adgroup_name	智投项目名称对应接口中的广告名称
项目状态	configured_status / system_status	项目的配置状态与系统状态
项目预算	daily_budget / total_budget	项目日预算与总预算
项目出价	bid_amount	项目出价对应接口中的广告出价
项目创建时间	created_time	项目创建时间（返回 YYYY-MM-DD HH:mm:ss 格式）
项目修改时间	last_modified_time	项目最后修改时间（返回 YYYY-MM-DD HH:mm:ss 格式）

其他字段也类同，接口层面项目与广告共用同一套数据结构，调用方式完全一致。

智能投放项目详情的获取使用 query-adgroups.mjs 脚本。脚本支持按需指定 fields 参数来获取所需字段；如果不指定 fields，脚本内置了覆盖智投项目全量配置的默认字段集（包括周期达成、成本保障、直播加热等），无需手动传入。

使用示例

1. 获取智能投放项目详情（使用默认字段，最常用）

node scripts/query-adgroups.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"]}'

不指定 fields 时，脚本自动返回上述所有默认字段。

2. 按需获取指定字段

node scripts/query-adgroups.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"],"fields":["adgroup_id","adgroup_name","smart_delivery_platform","smart_delivery_scene","project_ability_list","smart_delivery_aigc_option","smart_targeting_status"]}'

只需要查看智投相关配置时，可以通过 fields 按需获取，减少返回数据量。

3. 查询账户下所有智投项目详情

node scripts/query-adgroups.mjs '{"account_id":"39412855","page_size":100}'

4. 按项目名称搜索智投项目详情

node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"adgroup_name","operator":"CONTAINS","values":["智投项目关键词"]}]}'

智投项目专有字段说明

脚本：query-creatives.mjs

创意列表查询脚本，用于获取创意的完整信息。

适用场景

• 需要查看广告下的创意列表及其组成结构（创意组件引用）
• 需要了解创意的投放模式、创意类型、创意状态等配置信息
• 需要查看创意中组件的具体内容（标题文案、描述文案、图片、视频等）
• 需要查看已删除的创意信息
• 需要根据创意名称、广告 ID、创建时间等条件筛选创意

与其他脚本的区别

调用方式

node scripts/query-creatives.mjs '<JSON 参数>'

参数说明

过滤条件（filtering）

返回的创意详情字段

创意基础信息

smart_delivery_platform 枚举值说明

判断规则：smart_delivery_platform 为 SMART_DELIVERY_PLATFORM_EDITION_STANDARD 时为竞价广告（非智投），其余枚举值均为智投项目。

展示规则：智投项目的 adgroup_id 展示为"项目ID"；竞价广告的 adgroup_id 展示为"广告ID"。

创意组件（creative_components）

核心字段：包含创意使用的所有组件引用信息。

creative_components 是一个 map 结构，key 为组件类型标识，value 为该类型的组件配置。常见的组件类型包括：

每个组件通常包含 component_id（引用的组件 ID）。当查询结果只有 1 条创意时，脚本会自动拉取组件详情，并以 _component_detail 字段内联到各组件中，包含组件的实际内容（文案文本、图片 URL、视频 URL 等）。此外还会自动获取图片/视频的预览 URL，以 _preview 字段内联到对应素材中。

其他字段

使用示例

1. 查询指定广告下的所有创意（最常用）

node scripts/query-creatives.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"]}'

自动解析组件详情，返回创意完整信息 + 组件内容。

2. 查询指定创意 ID 的详情

node scripts/query-creatives.mjs '{"account_id":"39412855","creative_ids":["98765432"]}'

3. 查询账户下所有创意列表

node scripts/query-creatives.mjs '{"account_id":"39412855","page_size":20}'

4. 按创意名称模糊搜索

node scripts/query-creatives.mjs '{"account_id":"39412855","filtering":[{"field":"dynamic_creative_name","operator":"CONTAINS","values":["品牌推广"]}]}'

5. 查询已删除的创意

node scripts/query-creatives.mjs '{"account_id":"39412855","is_deleted":true}'

7. 使用游标分页获取全量创意

# 第一次请求
node scripts/query-creatives.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100}'

# 后续请求（使用上一次返回的 cursor）
node scripts/query-creatives.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100,"cursor":"xxx"}'

8. 指定返回字段

node scripts/query-creatives.mjs '{"account_id":"39412855","fields":["dynamic_creative_id","dynamic_creative_name","adgroup_id","creative_components","configured_status"]}'

返回结构

{
  "list": [
    {
      "dynamic_creative_id": 98765432,
      "dynamic_creative_name": "创意名称-横版视频",
      "adgroup_id": 72536365535,
      "creative_template_id": 1708,
      "delivery_mode": "DELIVERY_MODE_DEFAULT",
      "dynamic_creative_type": "DYNAMIC_CREATIVE_TYPE_NORMAL",
      "creative_components": {
        "title": [{
          "component_id": 11111,
          "_component_detail": {
            "component_id": 11111,
            "component_value": {
              "title": { "content": "这是标题文案" }
            },
            "component_sub_type": "TITLE",
            "component_custom_name": "品牌标题"
          }
        }],
        "description": [{
          "component_id": 22222,
          "_component_detail": {
            "component_id": 22222,
            "component_value": {
              "description": { "content": "这是描述文案" }
            },
            "component_sub_type": "DESCRIPTION"
          }
        }],
        "video": [{
          "component_id": 33333,
          "_component_detail": {
            "component_id": 33333,
            "component_value": {
              "video": {
                "video_id": "abc123",
                "_preview": {
                  "video_id": "abc123",
                  "preview_url": "https://example.com/video_preview.mp4",
                  "key_frame_image_url": "https://example.com/keyframe.jpg",
                  "width": 1280,
                  "height": 720
                }
              }
            },
            "component_sub_type": "VIDEO"
          }
        }],
        "image": [{
          "component_id": 44444,
          "_component_detail": {
            "component_id": 44444,
            "component_value": {
              "image": {
                "image_id": "def456",
                "_preview": {
                  "image_id": "def456",
                  "preview_url": "https://example.com/image_preview.jpg",
                  "width": 800,
                  "height": 600
                }
              }
            },
            "component_sub_type": "IMAGE"
          }
        }]
      },
      "configured_status": "AD_STATUS_NORMAL",
      "created_time": 1742860800,
      "last_modified_time": 1742947200,
      "is_deleted": false
    }
  ],
  "page_info": {
    "page": 1,
    "page_size": 10,
    "total_number": 1,
    "total_page": 1
  }
}

_component_detail 字段：当查询结果只有 1 条创意时，脚本自动为每个包含 component_id 的组件引用附加 _component_detail 字段，其中包含完整组件信息。

_preview 字段：对于组件中包含 image_id 或 video_id 的素材，脚本自动获取预览信息（preview_url、尺寸等），以 _preview 字段内联到对应素材对象中。

注意事项

1. 请求方式: 该脚本使用 GET 方法。
2. 组件自动解析: 当查询结果只有 1 条创意时，脚本自动解析组件详情并获取图片/视频预览 URL，无需额外配置。多条创意时不解析组件，避免大量 API 请求影响性能。
3. 分页限制: 普通分页模式下 page 最大 100，page_size 最大 100。需获取全量数据时推荐使用游标分页模式。
4. 与 query-report.mjs 配合: 先用 query-report.mjs 获取创意级别的报表数据（level: DYNAMIC_CREATIVE），找到需要查看详情的创意后，再用 query-creatives.mjs 传入 creative_ids 查看其完整组件内容。
5. 与 query-adgroups.mjs 配合: 先用 query-adgroups.mjs 获取广告详情，再用 query-creatives.mjs 按 adgroup_id 查询该广告下的所有创意。
6. 展示 adgroup_id 时区分广告/项目：返回数据中的 adgroup_id 根据 smart_delivery_platform 字段决定展示名称：
7. EDITION_SCENE 或 EDITION_SCENE_PRO → 展示为项目ID（智能投放项目）
8. EDITION_STANDARD 或 EDITION_NONE（或字段缺失）→ 展示为广告ID（竞价广告）
9. ⚠️ 预览 URL 必须展示（强制）：脚本返回的 _preview.preview_url（视频/图片预览链接）和 _cover_preview.preview_url（封面预览链接）必须在回复中以可点击链接的形式呈现给用户，不得省略或忽略。具体规则：
10. 视频组件：展示视频 preview_url（🎥 视频预览链接）和封面 preview_url（🖼️ 封面链接）
11. 图片组件：展示图片 preview_url（🖼️ 图片预览链接）
12. 每个素材组件单独列出，用 Markdown 链接格式 [描述](URL) 呈现
13. 绝对禁止因内容过长、信息繁杂等原因而省略预览 URL

脚本：关键词管理（bidword）

管理广告的关键词（竞价词）。关键词用于搜索扩量场景，当广告开启搜索扩量（search_expansion_switch = SEARCH_EXPANSION_SWITCH_OPEN）后，可为广告设置搜索关键词。

详细参数、示例和返回值见 references/bidword.md

脚本：否定词管理（adgroup_negativewords）

管理广告组级别的否定关键词。否定词用于排除不相关的搜索词，避免广告在不相关的搜索结果中展示。

详细参数、示例和返回值见 references/negativewords.md

推广内容资产管理

创建和查询推广内容资产（marketing_asset）。执行前必须先读取 references/marketing-asset/overview.md。

详细流程说明（CPV/SPU/电商分类、创建步骤、参数说明、约束等）见 references/marketing-asset/overview.md

相关技能

• tencentads-adgroups - 管理广告（创建/更新/删除广告）
• tencentads-delivery-smart - 智投选参指南（智投报表需与非智投分开查询）
• tencentads-delivery-standard - 常规投放选参指南
• tencentads-creatives - 管理动态创意
• tencentads-components - 管理创意组件
• tencentads-batch - 批量调整广告
• tencentads-materials - 管理素材

这个 Skill 质量较好，文档非常详细，功能覆盖腾讯广告的核心管理需求，包括数据报表查询、广告详情查看、创意管理、关键词和否定词操作等。它提供了清晰的意图判断指南和多层级的脚本选择逻辑，用户按文档流程操作即可获得较好的支持。不过使用前需要安装额外的 CLI 工具，对新手用户存在一定门槛。总体而言，这是一个专业度高、功能完善的广告管理 Skill。