腾讯广告管理助手

在腾讯广告投放中需要解决的具体问题

管理腾讯广告账户时，优化师和开发者常面临几个核心痛点：跨账户数据聚合困难，不同账户的广告效果数据分散，难以快速获取统一的投放报表；广告实体配置复杂，智能投放项目、竞价广告、创意等实体的定向、出价、版位等详细信息查询步骤繁琐；受众与关键词管理分散，人群包、否定词、竞价词的增删改查操作需要分别对接不同接口；操作追溯性差，广告或创意的修改历史缺乏结构化日志，排查问题时缺乏字段变更的前后对比。

这些分散的管理需求在日常投放优化、数据复盘、问题排查和策略调整中造成了大量重复性手工操作。

技能如何工作：核心能力与关键步骤

本技能通过封装一套专用 Node.js 脚本（如 query-report.mjs、query-adgroups.mjs）来统一处理底层 API 的复杂逻辑。Agent 或开发者只需关注意图识别和参数提取，无需直接构建原始 API 请求。

核心能力模块

• 数据报表与效果查询：通过 query-report.mjs 脚本，支持按广告、创意、地域、年龄等多个维度查询消耗、曝光、点击、转化等指标，并能处理自动分页（fetch_all: true）和排序。
• 实体详情与配置获取：使用 query-adgroups.mjs 获取广告或智能投放项目的完整配置（如定向、出价、版位）；query-creatives.mjs 获取创意详情，并对单条创意自动解析组件与素材预览 URL。
• 运营日志审计：query-operation-logs.mjs 可查询广告/创意对象的操作日志，返回每次修改前后的字段变化详情，用于审计与问题追踪。
• 关键词与受众管理：提供一组脚本（如 bidword/add.mjs, audiences/update.mjs）来管理竞价词、否定词以及自定义人群包（支持六种人群类型），涵盖增、删、改、查全流程。

关键工作流示例

一个典型的数据查询流程遵循以下步骤：

1. 意图识别与路由：判断用户请求是报表效果数据（明确提到消耗、ROI等）还是实体详情查询（仅提及广告、创意配置）。这决定了调用 query-report.mjs 还是详情类脚本。
2. 确定广告实体类型：根据用户提到的“智投项目”、“竞价广告”或未指定的“广告”，设定 tencent_ads_type 参数为 smart、standard 或默认 all，这直接影响返回字段的命名。
3. 参数构造与字段校验：如果请求的字段（如报表指标）不在常用映射表中，必须先通过 --query-fields 参数查询字段字典，获取准确的 API 字段名，避免猜测错误。
4. 执行与结果处理：调用对应脚本，脚本会自动处理标准过滤条件、group_by 推导和数据裁剪，返回结构化结果。

适用边界与注意点

• API 依赖性：本技能完全基于腾讯广告营销 API（api.e.qq.com）。所有字段名称和参数结构以此技能文档为准，可能与腾讯开放平台其他文档不同，请勿混淆。
• 字段名准确性至关重要：腾讯广告 API 的字段名（如 report.cost）与常见英文命名可能差异较大。严禁自行拼凑字段名，对于非常用字段，务必先使用查询字典功能获取官方字段名。
• 跨平台调用规则：在 Bash 和 PowerShell 中调用脚本的参数传递方式不同。Windows PowerShell 必须使用 --base64 方式传递 JSON 参数，并严格遵守 Here-String 格式（@' 后换行，'@ 顶格），否则会导致语法错误。
• 时间范围语义：date_range 参数用于筛选报表统计数据的时间窗口，而非广告实体的创建时间。筛选“最近创建的广告”应在 filtering 中使用 created_time 字段。
• 脚本自动优化逻辑：脚本内部已处理许多优化，例如创意查询时，若结果仅一条会自动展开组件与预览链接；报表查询会自动添加基础过滤条件。Agent 无需干预这些自动行为。