Google Ads API 开发者助理 (v4.0.0) 不是通用聊天机器人，而是专为 AI 驱动的广告工程设计的任务控制系统，基于 Google Antigravity 和 Claude Code 智能体框架构建而成。
自然语言问答和特定于业务的上下文
您可以使用简单自然的语言向助理提出问题和请求。助理会分析您的意图，查阅官方 API 架构，并提供清晰的说明、可用于生产用途的代码或实时数据：
- 自然语言说明： 询问有关 Google Ads API 概念、资源层次结构、报告指标或细分规则的问题，以获得清晰的概念性概览和架构说明。
- 有针对性的代码生成： 如果您的任务需要实现，助理会提供惯用的、可用于生产用途的客户端库代码段、变更脚本或 GAQL 查询，这些代码段、脚本或查询会根据您的编程语言和应用场景量身定制。
- 问题排查和错误诊断： 粘贴 API 错误消息、gRPC 状态代码或意外的集成行为。助理会诊断根本原因，说明问题发生的原因，并提供必要的代码更正或配置修复。
- 临时报告： 使用简单自然的语言请求账号效果数据和广告系列指标。助理会直接针对您的账号构建、验证和运行 GAQL 查询，并在终端中显示格式化结果或将其导出为 CSV。
- 来自代码库的特定于业务的上下文： 使用
--context_dir设置参数注册您自己的项目代码库和代码库。通过分析您现有的数据流水线、辅助实用程序和业务逻辑，助理可以量身定制其说明、问题排查和生成的代码，以便与您的内部系统无缝集成。
全局视角：解决高合规性摩擦
此助理解决的根本问题是认知过载和技术苦差事。
Google Ads API 是功能最强大但也是最复杂的 API 之一。它具有严格的版本控制、独特的查询语言 (GAQL)、深度嵌套的协议缓冲区结构和严格的安全要求。开发者通常会花费大量时间与 API 作斗争，例如调试 gRPC 错误、查找字段兼容性以及修复 lint 问题，而不是构建实际的业务逻辑。
助理在 4.0.0 版中通过引入模块化插件架构 （由经过测试的专用技能 和内置斜杠命令提供支持）解决了此问题。它充当自动化的专家中间件，处理版本验证、架构发现和代码 linting 等苦差事，让开发者能够从意图层面而非语法层面进行操作。
基于官方架构，而非猜测
标准大型语言模型通常难以处理特定于领域的 API，因为它们完全依赖于通用训练数据，而随着新 API 版本的发布，这些数据很快就会过时。
Google Ads API 开发者助理通过将嵌入式 Google Ads API 架构规则与动态本地 Protobuf 架构检查相结合，解决了此问题：
- 确定性验证： 助理不会依赖于 LLM 在多次往返中的迭代猜测，而是运行本地 4 步验证流水线，该流水线只需一步即可验证字段兼容性、资源关系、零展示规则和日期细分。
- 版本准确的架构查找： 它直接从有效 API 版本的官方 API 架构中检查 Protobuf 资源定义、数据类型和枚举值，避免重复的远程元数据查询。
- 官方客户端库基础： 代码生成直接基于 Python、Java、PHP、.NET 和 Ruby 的官方 Google Ads 客户端库。
类比：专业的研究和诊断实验室
您可以将助理视为外科医生的一个高科技研究实验室。
- 外科医生（开发者）： 您确切地知道需要执行什么手术（例如，“我需要分析 PMax 效果”）。
- 实验室设备 (API)： 这些是执行手术所需的强大工具，但它们非常复杂，需要精确校准。
- 实验室助理（此工具）： 在您接触患者之前，实验室助理会使用专用技能 和内置命令来：
- 检查手册： 自动验证最新的 API 协议，并即时检查资源结构 (
inspect_object//inspect-object)。 - 预先测试工具： 使用实时 API 验证 (
validate_gaql//validate-gaql) 对查询执行确定性试运行，以便在错误发生之前捕获错误。 - 对环境进行消毒： 使用严格的 lint 流水线 (
rufflinting) 格式化和清理代码，以避免代码导致系统错误。 - 监控生命体征： 监控 API 异常，并针对离线转化等复杂操作运行高级诊断工作流 (
troubleshoot_conversions//troubleshoot-conversions)。 - 解释概念： 使用日常语言和现实世界的类比解释复杂概念 (
/explain、/step-by-step、/assistant-tutorial)。
- 检查手册： 自动验证最新的 API 协议，并即时检查资源结构 (
互联性：“安全第一”桥梁
助理充当桥梁，连接项目中的四个不同“世界”，并受控制合同 (AGENTS.md / CLAUDE.md) 的约束：
- 用户上下文： 它会听取您的宏观目标，并将其转化为技术策略。
- 本地工作区： 它在您的项目目录中拥有“眼睛和手”。 它可以读取现有代码并编写新代码以供日后使用，同时保持严格的隔离。
- Google Ads API： 它会连接到实时 API，以针对您的账号运行只读报告和测试查询。为了实现即时字段验证，它会直接检查本地 Protobuf 架构。
- 安全门卫： 它已硬编码为遵循严格的协议。如果脚本尚未经过 linting，它不会让您运行该脚本；如果查询尚未通过程序化验证检查，它也不会让您发送该查询。
助理的实际功能
简单来说，助理是您的保障和加速器。
- 它可以防止错误： 它会在执行之前针对有效 API 架构验证代码和查询，从而在语法和兼容性错误到达实时 API 之前阻止这些错误。
- 它了解地图： 它了解 Google Ads API 的地理位置，即数据所在的位置以及如何高效查询数据。
- 它可以自动执行枯燥的任务： 它会编写样板客户端库代码，将报告格式化为清晰的终端表格，并处理客户端库管道。
- 它可以排查复杂的工作流问题： 它可以对离线转化上传运行深度诊断，解决 MCC 账号层次结构问题，并配置复杂的广告系列结构，例如效果最大化广告系列商品详情过滤条件和网址排除对象。
- 它可以直播临时报告： 使用简单自然的英语请求效果数据，助理会直接针对您的账号构建、验证和运行 GAQL 查询，并将格式化结果直播到您的终端或将其导出为 CSV。
- 它可以保持最新状态： 通过检查有效 API 版本的本地 Protobuf 架构和文档，它可以帮助您避免使用已废弃的字段和过时的规则。
Google Ads API 开发者助理将“开发者与 API”之间的斗争转变为“开发者 + AI”之间的协作，从而生成安全、惯用且架构合理的代码。
架构和性能 (v4.0.0)
4.0.0 版将助理从独立项目设置转换为现代化的全局插件架构：
- 零守护程序开销： 技能和诊断命令仅在被调用时作为轻量级子进程临时运行，在空闲时将系统资源使用量降至零。
- 渐进式上下文披露： 规则和架构仅在与有效任务相关时按需加载，从而显著减少令牌消耗和提示延迟。
- 减少磁盘 I/O： 从插件树中移除不需要的 SDK 文件可防止 IDE 索引器、linter 和文件监视器扫描数万个未使用的文件。
- 多平台主机支持： 在 Linux、macOS 和 Windows 上使用统一的安装脚本，在 Google Antigravity 和 Claude Code 环境中无缝运行。