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