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 而反覆修改引數重試。

     7w4.net小蔥技能站收錄全網優質技能，值得收藏。

   • 資料值為 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。