Tencentads Management

腾讯广告管理（Tencent Ads Management）

前置依赖：需安装 tencentads-cli（Node.js ≥ 20）。执行 npm install -g tencentads-cli@latest 安装或升级；版本过低时 tencentads 会给出提示。

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

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 内容从 @' 的下一行开始书写

# ❌ 错误：@' 后面直接跟了 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 配置驱动）
   • 广告层级（ADGROUP 等）：adgroup.brand_ad_type + adgroup.campaign_type + adgroup.smart_delivery_platform
   • 创意层级（DYNAMIC_CREATIVE）：dynamic_creative.brand_ad_type + adgroup.campaign_type + dynamic_creative.smart_delivery_platform
   • 维度层级（REGION/CITY/AGE/GENDER 等）：使用对应 report.* 前缀
2. 模糊搜索字段自动切换：fuzzy_name 在广告层级使用 adgroup.fuzzy_name，在创意层级使用 dynamic_creative.fuzzy_name
3. group_by 推导：根据 level 自动推导合适的 group_by（如 ADGROUP → ["adgroup_id"]，DYNAMIC_CREATIVE → ["dynamic_creative_id"]，REGION → ["area_id"]）
4. fields 补全：未指定 fields 时，自动包含该 level 的默认属性字段 + 常用报表字段
5. 返回数据裁剪：移除空对象和无效字段，减少 Agent 解析负担
6. 默认排序：未指定 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 会返回空对象）:

0. order_by 排序规则：

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

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

   • hour 必须配 date：使用 hour 时必须同时带 date（如 ["date", "hour"] 或 ["adgroup_id", "date", "hour"]），单独传 hour 不带 date 不会报错但数据不完整（不同天的同一小时会被合并）。
   • 分时/按天趋势查询：查看指定广告的分时趋势 → group_by: ["date", "hour"]；查看指定广告的按天趋势 → group_by: ["date"]；查看广告列表的每日汇总 → group_by: ["adgroup_id", "date"]。

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

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

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

   [{"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）：

{"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.*）：

{"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.*）：

{"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 级别不需要也不应该加 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 自动选择正确的字段，无需手动指定。

• 查智投广告/创意（默认，当前大部分广告都是智投广告）：

  {"field": "adgroup.smart_delivery_platform", "operator": "GREATER_EQUALS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
  

  或（创意层级）：

  {"field": "dynamic_creative.smart_delivery_platform", "operator": "GREATER_EQUALS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
  

• 查非智投广告/创意（用户明确要求查非智投/竞价广告时）：

  {"field": "adgroup.smart_delivery_platform", "operator": "LESS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
  

  或（创意层级）：

  {"field": "dynamic_creative.smart_delivery_platform", "operator": "LESS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
  

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

意图判断规则：

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

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

      - ✅ 正确：`"fields": ["report.view_count", "report.cost"]`
     

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

4. is_total 的正确用法：

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

5. 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 时间戳。

   // 示例：筛选 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"]}
   

6. 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 枚举值不同：

…(truncated)