AdLoop

提示

AdLoop Cloud 是本项目的托管版本，提供无需信用卡的免费套餐。 只需两步即可连接 Google，并从 claude.ai、ChatGPT、Claude Code、Cursor 或 Gemini 使用完整工具集。无需 Google Cloud 项目，无需申请 API 访问权限，也无需等待 OAuth 验证。托管于欧盟，优先考虑 GDPR 合规，并包含 DPA。

📚 文档：docs.getadloop.com — 针对各 AI 客户端的设置指南、工具集、安全模型，以及两个版本的故障排除说明。

---

Cloud 还是自托管？

两个版本都运行相同的工具，并采用相同的安全模型。区别在于由谁负责处理基础配置：

	☁️ AdLoop Cloud	🛠️ 自托管（本仓库）
设置	两步连接 Google	约 5 分钟：自备 Google Cloud 项目 + adloop init
Google Cloud 项目	不需要	必需（免费）
Ads API 访问权限	不需要	授予你的 Cloud 项目（无需开发者令牌，自 2026 年 9 月起无需 MCC）
适用平台	claude.ai、ChatGPT、Claude Code、Cursor、Gemini	Claude Code、Cursor、Claude Desktop，以及任何本地 MCP 客户端
数据流向	欧盟服务器（德国），优先考虑 GDPR 合规，并包含 DPA	100% 在你的设备上运行 — 数据不会离开设备
更新	自动	pip install -U adloop
价格	免费套餐，无需银行卡；付费套餐适用于更多账号和更高用量	永久免费（MIT）

不确定选哪种？先试试 Cloud — 这是了解 AdLoop 功能最快的方式，也是唯一能从 claude.ai 或 ChatGPT 使用 AdLoop 的方式。如果你希望所有内容都运行在自己的设备上，或需要修改代码，可以选择自托管。如果你是来参与 AdLoop 开发的：欢迎，继续往下看。

解决的问题

AdLoop 旨在解决将 Google Ads 与代码一同管理时的种种混乱。它专门处理以下问题：

• “转化量下降了，我不知道为什么。” AdLoop 会在一次查询中交叉比对 Ads 点击、GA4 会话和转化事件。它能判断差异究竟是由 GDPR 同意拒绝、跟踪损坏，还是实际的落地页问题造成的，免得你浪费数小时分别检查各个仪表板。

• “我在无关搜索上浪费了广告预算。” 提取搜索字词报告、找出无关词并添加否定关键词——只需在 IDE 中进行一次对话即可完成。无需切换到 Ads 界面。

• “我的跟踪到底有没有正常工作？” 将实际代码库中的事件名称与 GA4 收到的事件进行比较，找出不匹配之处：你触发了但 GA4 从未收到的事件，以及 GA4 记录了但你并不知情的事件。

• “我需要创建广告，但 Google Ads 界面很难用。” 通过自然语言撰写响应式搜索广告、创建广告系列、添加关键词。每项更改都会先显示预览。未经你的明确确认，任何更改都不会生效：在 Claude、ChatGPT 和 VS Code 中，预览会显示为审批卡片，只有你点击 Apply 才会更改账户（AI 无法点击它）。新广告和广告系列初始状态均为暂停。

• “我的落地页有付费流量，却没有人转化。” AdLoop 会将广告最终到达网址与 GA4 页面级数据关联起来。查看哪些页面有点击却没有转化、哪些页面跳出率很高，以及哪些页面没有关联任何广告系列。

• “每个页面都添加了转化跟踪标签吗？” AdLoop 会读取你的实时 Google Tag Manager 容器，并将其与代码库中的事件以及 GA4 中触发的事件关联起来，准确告知你哪些转化已被采集、哪些标签已暂停、哪些页面范围过滤条件过于严格，以及哪些代码库事件根本没有对应标签——这种三方审计无法通过 GTM Preview 的单一视图完成。

• “我不知道欧盟的同意设置是否造成了数据缺失。” 在欧洲，30-70% 的用户会拒绝分析 Cookie。AdLoop 会自动考虑这一点，不会将正常的 GDPR 同意造成的数据缺失误诊为跟踪损坏。

源自真实使用场景

每个工具都源于运行真实 Google Ads 广告系列时遇到的实际问题。交叉比对工具之所以存在，是因为我们总要手动让 AI“先获取 Ads 数据，再获取 GA4 数据，然后进行比较”——所以我们把关联流程自动化了。广泛匹配 + 手动 CPC 安全规则之所以存在，是因为 AI 曾创建过这种组合，导致预算浪费。GDPR 同意感知功能之所以存在，是因为 AI 总把欧盟用户正常拒绝 Cookie 误诊为跟踪损坏。

最好的功能都来自真实工作流。如果你在使用 AdLoop 时发现它缺少某项功能，请提交 issue，描述你的情况——不要只说“添加功能 X”，而要说明“我想做 Y，但因为 Z 做不到”。具体背景比功能请求本身更重要。

所有工具

快速开始： pip install adloop 或 git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init——或者在 AdLoop Cloud 上零配置开始使用

诊断

工具	功能说明
health_check	一次调用即可测试 OAuth、GA4 和 Ads 的连接情况；如果出现问题，会提供可操作的错误消息。还会报告固定使用的 Google Ads API 版本，并在有更新版本可用时发出警告。

GA4 读取工具

工具	功能说明
get_account_summaries	列出 GA4 账号和媒体资源
run_ga4_report	自定义报告：会话、用户、关键事件、页面表现。支持可选的维度和指标筛选、排序、分页以及对比时段
run_realtime_report	实时数据——验证部署后跟踪是否正常触发
get_tracking_events	所有已配置事件及其数量
list_key_events	媒体资源的关键事件（转化），包括计数方法、创建时间以及是否可删除
list_ga4_dimensions_and_metrics	此媒体资源可报告的所有维度和指标，包括自定义项，并支持搜索

Google Ads 读取工具

工具	功能说明
list_accounts	查找可访问的 Ads 账号
get_campaign_performance	广告系列指标：展示次数、点击次数、费用、转化次数、CPA、搜索展示份额以及因预算／排名而损失的展示份额
get_ad_performance	广告文案分析：标题、描述、CTR、政策审核状态和主题
get_keyword_performance	关键词——质量得分、竞争指标
get_search_terms	用户点击前实际搜索的内容
get_negative_keywords	列出直接应用于广告系列级别的否定关键词
get_negative_keyword_lists	列出所有共享否定关键词列表（SharedSets）——名称、ID、状态、关键词数量
get_negative_keyword_list_keywords	列出特定共享否定关键词列表中的关键词
get_negative_keyword_list_campaigns	列出应用了共享否定关键词列表的广告系列
get_recommendations	Google 自动生成的建议，包含类型、预估影响和广告系列背景信息
get_pmax_performance	Performance Max 广告系列指标，包含网络细分数据和素材资源组广告强度
get_pmax_assets	PMax 中各项素材资源的详细信息——字段类型、投放状态、内容
get_asset_group_signals	PMax 素材资源组的搜索主题和受众信号，以及可用于该资源组的受众
get_detailed_asset_performance	表现最佳的素材资源组合——Google 最常选择的标题＋描述＋图片组合
get_audience_performance	受众细分效果——再营销、意向受众、兴趣相似受众、人口统计特征
get_shopping_product_performance	Shopping 和 Performance Max 中各商品的支出、转化次数、CPA 和 ROAS，以及有支出但未产生转化的商品
get_change_history	效果下滑前发生的变更：谁在何时通过哪个客户端（界面、API、脚本、自动应用的建议）更改了什么；查看最近 30 天的记录
get_demographic_targeting	列出广告组或广告系列上的人口统计定位条件（年龄／性别／父母身份／收入）
get_audience_lists	账号的再营销和客户列表（规模、资格、开放／关闭状态）、自定义细分和组合细分
search_audience_segments	按名称查找 Google 的意向受众和兴趣相似受众细分
get_audience_targeting	广告系列或广告组上的受众和受众排除项，以及受众模式（观察或定位）
suggest_brands	将品牌名称解析为 Google 可识别的品牌——品牌 ID、名称、状态、URL
check_brand_names	对照 Google 品牌知识图谱检查品牌名称候选列表（每次调用最多 25 个）
get_brand_lists	列出品牌列表（类型为 BRANDS 的 SharedSets）——ID、名称、状态、成员数量
get_brand_list_brands	列出列表中的品牌，包含商业 KG MID 和用于移除的条件 ID
get_brand_list_campaigns	列出应用了品牌列表的广告系列，以及每项关联是排除还是定位
get_ai_max_settings	每个广告系列和广告组的 AI Max 参数——enable_ai_max、bundling_required、完整的 asset_automation_settings 列表，以及每个广告组的 disable_search_term_matching
get_campaign_settings	每个搜索广告系列对应一条扁平记录——网络、位置选项、广告系列级广泛匹配、出价、预算、URL 选项和 AI Max，并标记扩大覆盖范围的设置
get_custom_conversion_goals	自定义转化目标及其操作，以及一个广告系列的目标配置
run_gaql	执行任意 GAQL 查询以获取其他信息

品牌列表——品牌列表是类型为 BRANDS 的 SharedSet；将其应用到广告系列时，使用的是 CampaignCriterion.brand_list（negative=true 表示排除，false 表示限制），而不是像否定关键词列表那样使用 CampaignSharedSet。remove_from_brand_list 和 detach_brand_list_from_campaigns 会真正移除条目——SharedCriterion 没有状态字段。 品牌定向 — 品牌条件（品牌列表、品牌排除项）定向的是品牌的 Commercial Knowledge Graph ID，而不是其显示名称。使用 suggest_brands 查询单个名称，或使用 check_brand_names 查询候选名称列表以获取 ID；exact_match 表示候选名称除大小写和标点外完全匹配，其余结果均为 Google 建议。

AI Max 是搜索品牌排除项的承载方式 — 对于普通搜索广告系列，Google 会拒绝品牌列表，并提示 "For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns." draft_prepare_brand_exclusions 会设置必要状态，使排除项可用，而不会将自动化交给 Google：启用 AI Max，按广告组关闭搜索字词匹配，并选择退出文字和最终到达网址自动化。当只需更改该状态的部分设置时，可使用通用表单 draft_ai_max_settings — 它会拒绝可能导致某项自动化在未被察觉的情况下保持开启的方案；如果明确请求开启该自动化，则会要求进行第二次确认。

自定义转化目标 — 一组命名的转化操作，可供广告系列指定为目标。get_custom_conversion_goals 会显示目标及其转化操作，以及广告系列当前的目标配置；draft_custom_conversion_goal 用于创建目标集，draft_update_custom_conversion_goal 用于重命名目标或替换其转化操作，draft_assign_custom_conversion_goal 用于将广告系列指向该目标，draft_clear_custom_conversion_goal 则会将广告系列恢复为使用账户级目标。此操作只会影响目标及广告系列的目标配置 — 转化操作、出价和预算均保持不变。

紧凑模式 — get_campaign_performance、get_keyword_performance、get_search_terms 和 get_ad_performance 支持 compact=true：返回账户总计、细分数据、排名前 10 的行，以及预先计算的问题项列表（有花费但无转化的对象、QS 较低的关键字、否定关键字候选项、内容单薄的 RSA），而不是返回所有行。响应体积缩小约 90% — 专为账户审计设计，避免原始表格占满 AI 的上下文。

交叉引用工具（GA4 + Ads 联合分析）

这些工具会在内部调用两个 API，并返回附带自动生成洞察的统一结果。它们是 AdLoop 区别于单独使用 GA4 和 Ads 工具的核心所在。

工具	功能
analyze_campaign_conversions	按广告系列映射 Ads 点击 → GA4 会话 → 转化。检测 GDPR 同意缺口，计算真实 CPA，并比较付费渠道与自然渠道。
landing_page_analysis	将广告最终到达网址与 GA4 页面数据关联起来。显示每个着陆页的转化率、跳出率和互动情况。标记有付费流量但零转化的页面。
attribution_check	比较 Ads 报告的转化与 GA4 事件。诊断差异是否源于 GDPR 同意、归因窗口或跟踪故障。

跟踪工具

工具	功能
validate_tracking	将代码库中发现的事件名称与 GA4 实际记录的事件进行比较。返回匹配、缺失和意外事件，并附带诊断信息。
generate_tracking_code	为任意事件生成可直接粘贴的 GA4 gtag JavaScript；为常见事件（sign_up、purchase 等）提供推荐参数，并可选添加触发器包装代码。

Google Tag Manager 工具

这些工具会读取实时 GTM 容器，并将其与代码库和 GA4 关联起来，以发现仅检查 GA4 无法发现的跟踪缺口——页面范围触发器、已暂停的代码、动态事件名称、不稳定的 CSS 选择器，以及完全没有关联代码的代码库事件。

工具	功能说明
audit_event_coverage	核心工具。 三方关联：代码库事件 ↔ GTM 代码 ↔ GA4 实际触发记录。对于 expected_events 中的每个事件名称，返回 10 种状态之一（ok、no_tag_no_fire、tag_paused、tag_active_but_not_firing、gtm_only_firing、ga4_only 等），并针对缺口自动生成洞察。
list_gtm_accounts	查找可访问的 GTM 账号
list_gtm_containers	列出账号下的容器——返回数字形式的 container_id（其他工具需要此值）、公开的 GTM-XXXXXXX ID，以及使用场景（Web/iOS/Android/服务器）
list_gtm_tags	列出实时容器中的所有代码，并解析事件名称和已解析的触发／阻止触发器名称。传入 workspace_id 可改为读取工作区未发布的状态，以便查看刚起草的代码（get_gtm_tag、list_gtm_triggers、get_gtm_trigger、list_gtm_variables 也支持此功能）
get_gtm_tag	单个代码的完整原始配置——所有参数、带筛选条件的触发／阻止触发器、优先级、暂停状态和采样设置
list_gtm_triggers	列出所有触发器，并将筛选条件解析为易读文本（例如 {{Page Path}} contains service-promotions、{{Form ID}} NOT contains wf-form-...）。明确显示 negate 标志。
get_gtm_trigger	完整触发器配置，以及使用该触发器的所有代码的反向查找结果。对于 elementVisibility 触发器，包含解析后的 element_visibility 区块（选择器、屏幕可见比例、触发频率）；对于 triggerGroup 类型，包含 group_member_trigger_ids
list_gtm_variables	自定义变量（数据层、常量、JS）以及已启用的内置变量
list_gtm_workspaces	列出容器下的草稿（工作区）——get_gtm_workspace_diff 需要工作区 ID
get_gtm_workspace_diff	已起草但尚未发布的更改——这是“我编辑了代码，但什么也没发生”的常见原因。没有待处理更改时返回 is_clean: true。
list_gtm_versions	版本历史，按时间从新到旧排列，并包含版本 ID 和实体数量。Tag Manager API 不会为版本返回时间戳或作者信息。
get_gtm_version	单个历史容器版本的名称、备注，以及代码和触发器名称
get_gtm_version_diff	发布更改的内容：新增、移除和修改的代码、触发器及变量，并列出更改字段，以及已启用或停用的内置变量。默认对比实时版本与其前一个版本；需要调用 API 两到三次。

GTM 写入工具（选择启用）

默认关闭。请在 ~/.adloop/config.yaml 中设置 gtm.write_enabled: true 并重启；下次调用时会要求你重新同意授予 Tag Manager 编辑和发布权限范围，这些权限绝不会包含在默认授权中。所有操作均遵循常规的草稿 → 预览 → confirm_and_apply 流程，且标签和触发器的编辑只会影响工作区，直到你发布该工作区。

工具	功能
draft_gtm_tag	创建标签，或通过 tag_id 更新标签。更新采用读取-修改-写入方式：parameters 按键合并，你未传入的所有字段（优先级、同意设置、触发选项、计划、文件夹等）都会保留。标签类型使用 GTM 规范模板 ID（googtag、gaawe、awct、sp、gclidw 等）或 cvt_<id> 图库模板。
draft_gtm_trigger	创建触发器，或通过 trigger_id 更新触发器（类型不可更改）。custom_event_name 可将 customEvent 触发器连接到 dataLayer 事件。
draft_gtm_variable	创建或更新变量，例如用于 GA4 电商值的数据层变量；如果重命名被引用的变量，操作会被拒绝；自定义 JavaScript 受限
draft_delete_gtm_entity	删除工作区中的标签、触发器或变量。仍在使用中的触发器和变量会被提前拒绝删除，并列出引用位置。
draft_publish_gtm_workspace	将工作区发布上线。预览会列出所有待处理更改，包括其他人在 GTM 界面中所做的编辑。
draft_rollback_gtm_version	将较早的容器版本重新发布上线。预览会显示线上版本与目标版本之间的差异；计划会锁定线上版本，因此如果有人在此期间发布，应用操作就会被拒绝。工作区保持原样。

GTM 专属安全限制：

• 自定义 HTML 会在你的网站上运行任意 JavaScript，因此除非同时设置 gtm.allow_custom_html: true，否则创建或编辑 html 标签，或发布新增或修改了此类标签的工作区，都会被拒绝。暂停或删除此类标签始终允许。
• 禁止过时写入。 更新和删除操作会锁定预览时实体的指纹，发布操作会锁定工作区的待处理更改；如果有人在此期间编辑了容器，应用操作就会被拒绝，你需要重新起草。
• 如果存在合并冲突或 GTM 编译器错误，发布会停止。试运行会先运行 Tag Manager 快速预览（Tag Manager 没有仅验证模式），因此在创建版本之前就会显示编译器错误。该预览是一次 POST 操作，会在容器中存储一个预览版本——不会发布任何内容，也不会更改任何线上标签；试运行的其余部分只会读取数据。
• 发布和回滚结果会注明被替换的版本（previous_live_version_id），因此回滚只需一步：使用该 ID 调用 draft_rollback_gtm_version。如果版本已创建但发布失败，错误信息会同时包含已创建的版本 ID 和仍在线上的版本 ID。
• safety.blocked_operations 的操作名称：gtm_create_tag、gtm_update_tag、gtm_delete_tag、gtm_create_trigger、gtm_update_trigger、gtm_delete_trigger、gtm_publish_workspace、gtm_rollback_version。

Google 账号还需要拥有该容器的编辑权限（发布时还需要发布权限），可在 Admin → User Management 中设置。

GTM 工具设置 — 在你的 GCP 项目中启用 Tag Manager API v2，然后在 GTM 容器的 Admin → User Management 中，将 AdLoop 凭据所用邮箱（OAuth 用户邮箱，或使用服务账号时的服务账号邮箱）添加为具有 读取权限的用户。服务账号会在下次调用时获得访问权限。从较早版本的 AdLoop 升级的 OAuth 用户必须重新授权一次：GTM 权限范围是新增的，因此请删除 ~/.adloop/token.json 并运行任意工具以重新同意授权；在此之前，GTM 工具会返回权限错误。

Search Console 工具

工具	功能说明
list_gsc_sites	列出已连接账号可访问的 Search Console 资源
run_gsc_report	自然搜索分析：按查询、页面、国家/地区、设备、日期、searchAppearance 或小时统计点击次数、展示次数、CTR 和排名。支持获取最新数据（data_state="all"）、aggregation_type，以及通过 start_row 翻页获取超过 25,000 行的数据

网页性能工具

工具	功能说明
analyze_page_speed	针对着陆页提供 PageSpeed Insights 数据：Lighthouse 得分、Core Web Vitals、真实用户 CrUX 数据（当页面流量过少时，改用整个来源的数据，并标明数据范围）以及主要优化建议。无需 OAuth（可选 API 密钥）。

Merchant Center 工具

工具	功能说明
list_merchant_accounts	查找可访问的 Merchant Center 账号
get_merchant_feed_health	商品源健康状况——按报告上下文统计已批准、待处理和未批准的商品数量；列出附带文档链接的主要商品问题以及账号级问题。未批准会悄无声息地削弱 Shopping/PMax 的效果。
get_merchant_product_issues	查看商品源健康状况统计背后的商品：哪些商品未获批准、受限或待处理，以及每个问题对应的属性和受影响的国家/地区

Merchant Center 工具的设置——在 GCP 项目中启用 Merchant API（Shopping Content API 已弃用）。Merchant API 没有只读范围；AdLoop 严格以只读方式使用该 API。升级的 OAuth 用户需要重新授权一次。

GSC 工具的设置——在 GCP 项目中启用 Search Console API。升级的 OAuth 用户必须针对新范围重新授权一次（删除 ~/.adloop/token.json，然后运行任意工具）。关键组合：将自然搜索查询与 get_keyword_performance 的结果交叉分析，以发现付费搜索与自然搜索之间的蚕食现象，以及尚未挖掘的关键词机会。

Reddit Ads 工具

另一个广告平台，相同的安全模型。Reddit 是独立的连接：使用独立的开发者应用和 OAuth，无需开发者令牌，也无需审批流程。每个工具都接受 ad_account_id（默认使用 reddit.ad_account_id）。

工具	功能
list_reddit_accounts	查找企业和广告账户（币种、时区、审批状态）
list_reddit_funding_instruments	账单工具和发帖资料 — 创建广告系列和广告的前置条件
get_reddit_campaigns / get_reddit_ad_groups / get_reddit_ads	广告结构，包含已配置状态与生效状态、预算、出价、像素、定向、每周排期和拒登原因；include_copy 会返回每条广告的帖子（标题、正文、目标地址、媒体）
get_reddit_performance	按账户／广告系列／广告组／广告统计支出、点击量、CTR、CPC、转化量、CPA、ROAS；可选细分项（日期、国家／地区、社区、关键词、版位等），以及包含洞察的精简模式
run_reddit_report	用于查询任意指标的原始报告端点（REACH、视频、按事件统计的转化量）
get_reddit_pixels	像素及每种事件最近触发时间 — 标记针对像素从未发送过的事件进行优化的广告组
get_reddit_audiences	自定义受众和已保存受众，包含状态、规模和来源，以及定向或排除这些受众的广告组
search_reddit_targeting	社区、兴趣、地理位置、语言、关键词建议，以及 Reddit 根据种子社区或网站提供的相关社区建议
get_reddit_account_history	谁在何时更改了什么：字段、更改前／后、成员
estimate_reddit_ad_group	为计划中的广告组估算受众规模和投放情况，并提供建议出价范围（Reddit 对应于 estimate_budget 的工具）
pause_reddit_entity / enable_reddit_entity / remove_reddit_entity	通过预览关卡更改状态（移除 = ARCHIVE，不可逆，需二次确认）
update_reddit_campaign / update_reddit_ad_group / update_reddit_ad	更新预算、出价、投放日期、每周排期（星期名称、按查看者本地时间计算的小时数）、定向、版位和要定向或排除的受众（起草时由 Reddit 验证）、落地页 URL 和评论；预览旧值 → 新值，并提供预算上限和出价增幅防护
draft_reddit_campaign / draft_reddit_ad_group / draft_reddit_ad	创建广告系列 → 广告组（必需设置像素和定向）→ 帖子和广告（文本、图片、视频或 2–6 张卡片的轮播广告，媒体通过 URL 提供），也可使用 post_id 推广现有帖子。所有内容创建后均为 暂停 状态。
draft_reddit_custom_audience	根据网站访客（像素事件）或与你的广告系列互动过的人创建再营销受众。不支持上传客户名单。

Reddit Ads 工具的设置 — 在 Reddit Ads Manager 中打开 Business Manager → Developer Application → Create app（仅限企业管理员；无需等待审批）。将重定向 URL 原样注册为 http://localhost:8765/callback，然后运行 adloop init 并完成 Reddit Ads 步骤：该步骤会打开 Reddit 的授权页面（权限范围为 adsread + adsedit，永久授权），将刷新令牌保存到 ~/.adloop/reddit_token.json，并让你选择默认广告账户。Reddit 按用户进行速率限制（报告：每分钟 60 次请求），且要求提供描述性 User-Agent；AdLoop 会根据你的应用 ID 和 Reddit 用户名生成该值。Reddit 没有仅验证模式，因此 confirm_and_apply(dry_run=true) 会重新读取目标，并再次检查安全上限。

图片上传

电脑中的图片或你在聊天中附加的图片没有公开 URL，AI 应用也无法将文件交给工具。upload_images 可以解决这个问题。

工具	功能
upload_images	在支持 MCP Apps 的应用中显示上传卡片（可拖入不超过 5 MB 的 PNG、JPEG 或 GIF）；在其他应用中使用 AdLoop Cloud 时，会返回一次性上传链接，编码 Agent 也可以通过 curl -T 使用该链接
list_uploads	列出尚未过期的上传内容（保留 24 小时），包括 ID、尺寸和大小

上传 ID 可传入 draft_image_assets(upload_ids=[...])，也可在 AdLoop Cloud 上以 upload:<id> 的形式填入 draft_reddit_ad 的图片字段。

规划工具

工具	功能
discover_keywords	根据种子关键词和／或 URL 发掘新的关键词创意；可选使用 Google Ads Keyword Planner 提供每月搜索历史和季节性洞察（include_monthly_volumes）。返回月均搜索量、竞争程度和首页出价范围。
estimate_budget	使用 Google Ads Keyword Planner 预测一组关键词的点击量、费用和转化次数。支持地理位置／语言定位，是投放广告系列前进行预算规划的必备工具。

Google Ads 写入工具

所有写入操作都遵循 草拟 → 预览 → 确认 工作流。未经明确批准，不会执行任何操作。

工具	功能
draft_campaign	创建完整的广告系列结构：预算 + 广告系列（PAUSED）+ 广告组 + 可选的关键字。支持搜索合作伙伴、展示广告扩展，以及用于 MANUAL_CPC 初始广告组出价或 TARGET_SPEND（最大化点击次数）CPC 上限的 max_cpc。
draft_shopping_campaign	为关联的 Merchant Center Feed 创建标准购物广告系列：通过一次原子请求创建预算、广告系列（PAUSED）、商品广告组、购物广告和“All products”分组。支持手动 CPC、最大化点击次数或目标 ROAS。
draft_asset_group_assets	通过一次更改添加和移除 Performance Max 资源（文本、图片，包括上传的图片，以及 YouTube 视频），替换资源时不会导致广告组低于 Google 的最低要求
draft_asset_group_signals	为 PMax 资源组添加搜索主题或设置受众信号
draft_pmax_product_exclusions	按商品 ID、品牌或自定义标签，从零售 PMax 资源组中排除商品
update_campaign	修改现有广告系列设置，包括出价、预算、地理位置/语言定位、搜索合作伙伴、展示广告扩展，以及 TARGET_SPEND（最大化点击次数）的 max_cpc 上限。
draft_ad_group	在现有广告系列中创建已暂停的 SEARCH_STANDARD 广告组，可选择设置 MANUAL_CPC max_cpc。
update_ad_group	更新广告组名称和/或 MANUAL_CPC max_cpc。更改广告组状态请使用 pause_entity / enable_entity。
draft_responsive_search_ad	创建 RSA 预览（3-15 个标题，每个 ≤30 个字符；2-4 条说明，每条 ≤90 个字符）。如果标题或说明数量低于最佳实践要求，会发出警告。
draft_callouts	为广告组、广告系列或账号创建宣传信息资源（1-25 个字符）。
draft_structured_snippets	使用官方标题值和 3-10 个值，为广告组、广告系列或账号创建结构化摘要资源。
draft_business_name_asset	为广告系列或账号创建随广告显示的商家名称。
link_asset_to_customer	在账号范围内关联现有资源；会根据字段类型检查资源类型。
update_callout / update_sitelink / update_structured_snippet	原位编辑资源，保留其 ID 和历史记录；如果预览后该资源在 Google Ads 中已发生更改，应用操作会被拒绝。
draft_call_asset / update_call_asset	为广告组、广告系列或账号创建电话资源，或原位编辑现有资源；系统会解析电话号码并检查其是否与对应国家/地区匹配。
add_ad_schedule	为广告系列添加广告投放时段；不允许时段重叠，广告系列的首个投放时段需要二次确认。
draft_promotion / update_promotion	创建促销资源，或原位编辑现有资源而不丢失未传入的字段；金额使用账号货币。
draft_price_asset	创建包含 3-8 个商品的价格资源，金额使用账号货币。
draft_image_assets	使用本地文件、公共图片 URL 或上传的图片（PNG、JPEG 或 GIF）创建广告系列图片资源。
draft_keywords	提议添加具有匹配类型的关键字。会主动检查出价策略——如果未使用智能出价的广告系列采用 BROAD 匹配，会在预览中将其标记为危险。
add_negative_keywords	直接为广告系列提议否定关键字
add_negative_locations	为广告系列提议地理位置否定排除项：排除城市/地区，同时保留范围更广的正向定位
draft_key_event	将 GA4 事件标记为关键事件（转化）——用于解决“事件已触发但未计为转化”的问题
draft_delete_key_event	移除 GA4 关键事件。该事件仍会触发，但之后不再计为转化；仅影响未来数据
draft_demographic_targeting	提议人口统计条件（年龄、性别、家长身份、收入）——默认采用排除方式
draft_audience_attachment	将受众设为观察（默认）、定位（二次确认）或排除；如果受众组合不受 Google 支持，或搜索受众列表过小而无法用于定位，则会拒绝操作
propose_negative_keyword_list	创建共享否定关键字列表（SharedSet）草案并关联到广告系列，可在多个广告系列中重复使用
propose_brand_list	根据 Commercial KG MIDs 创建品牌列表（类型为 BRANDS 的 SharedSet）草案，并可选择关联到广告系列——negative=true（默认）会排除这些品牌，false 则将定位限制在这些品牌
add_to_brand_list	提议将品牌添加到现有品牌列表
remove_from_brand_list	提议从列表中移除品牌（SharedCriteria 没有状态字段，因此只能通过移除来完成；需要二次确认）
attach_brand_list_to_campaigns	提议通过 CampaignCriterion.brand_list 将现有品牌列表关联到广告系列
detach_brand_list_from_campaigns	提议从广告系列中解除品牌列表关联（仅移除条件，保留列表）
draft_ai_max_settings	为搜索广告系列拟定 AI Max 控制项：enable_ai_max、按广告组设置的 disable_search_term_matching，以及文本和最终 URL 资源自动化设置（各自可设为 OPTED_IN / OPTED_OUT / UNCHANGED）
draft_prepare_brand_exclusions	一步拟定安全的标准状态：启用 AI Max，为每个未移除的广告组关闭搜索词匹配，并选择退出文本和最终 URL 自动化。不触及其他设置
draft_custom_conversion_goal	创建自定义转化目标（由一组命名的转化操作组成）
draft_update_custom_conversion_goal	重命名自定义转化目标和/或替换其操作列表（替换列表，而非追加）
draft_assign_custom_conversion_goal	将广告系列指定为使用自定义转化目标（goal_config_level = CAMPAIGN）
draft_clear_custom_conversion_goal	将广告系列恢复为使用账号级目标（回滚）
draft_dismiss_recommendations	忽略你不会采纳的 Google 建议，使其不再重复出现（Google 之后仍可能再次显示）
pause_entity	暂停广告系列、广告组、广告、关键字或 PMax 资源组
enable_entity	重新启用已暂停的实体
remove_entity	永久移除实体（不可撤销——优先选择暂停）。支持关键字、否定关键字、广告、广告组和广告系列。
confirm_and_apply	执行先前预览过的更改

编排规则

AdLoop 内置了编排规则，教 AI 如何 组合这些工具，涵盖营销工作流、GAQL 语法、安全协议、GDPR 意识和最佳实践。没有规则，AI 虽然有工具，却不知道该如何运用。

• Cursor：.cursor/rules/adloop.mdc（规范源文件）
• Claude Code：.claude/rules/adloop.md（通过 scripts/sync-rules.py 从 Cursor 规则同步）

规则包括：

• 常见工作流的编排模式（效果评估、转化诊断、广告系列创建、否定关键词维护、关键词发现、跟踪验证、预算规划、着陆页分析）
• GAQL 速查参考，涵盖语法、常用查询和易错点
• 安全规则，包括防止组合使用广泛匹配与手动 CPC，以及写入前验证
• 广告文案字符数限制指南（30 字符的标题比你想的更短）
• GDPR 同意意识，防止在欧盟市场出现错误的跟踪诊断

斜杠命令（Claude Code）

AdLoop 在 .claude/commands/ 中提供了预构建的斜杠命令，适用于常见工作流：

命令	功能
/analyze-performance	全面评估 Google Ads + GA4 的效果
/create-ad	创建响应式搜索广告并进行安全检查
/diagnose-tracking	诊断跟踪和转化问题
/optimize-campaign	广告系列的完整优化清单
/create-campaign	创建新的搜索广告系列并估算预算
/budget-plan	通过 Keyword Planner 估算关键词预算

Safety Model

AdLoop 管理真实的广告支出，因此安全性不容妥协。

• 审批卡片。 在显示 MCP Apps 的应用（Claude、ChatGPT、VS Code 等）中，每项更改都会显示为带有 Test run 和 Apply 的卡片。只有点击卡片才能应用更改：无论聊天中如何指示，AI 自己调用 confirm_and_apply(dry_run=false) 都会被拒绝，并返回 APPROVE_ON_CARD。
• 确认对话框。 对于不支持卡片但支持 elicitation 的应用（例如 Claude Code），AdLoop 会在每次实际更改前显示对话框。AI 无法替用户作答；拒绝确认不会产生任何更改。
• 两步写入。 每次变更操作都会先返回预览。必须单独调用 confirm_and_apply 才能执行。
• 默认试运行。 即使是 confirm_and_apply，默认值也是 dry_run=true。只有显式设置 dry_run=false 才会进行实际更改。
• 两阶段应用（可选）。 设置 safety.two_phase_apply: true 后，计划未完成一次试运行前，confirm_and_apply 会拒绝 dry_run=false。这样，先预览再应用就由服务端强制执行，而不是仅依赖约定。
• 预算上限。 可配置每日最高预算；服务会拒绝任何超过上限的金额。
• 审计日志。 每项操作（包括试运行）都会记录到 ~/.adloop/audit.log。
• 新广告系列和广告均为已暂停状态。 未经手动启用，任何内容都不会上线。
• 破坏性操作会标记为需要二次确认。 删除实体或大幅提高预算时，结果会附带额外警告，并指示 AI 确认两次。
• 检测未搭配智能出价的广泛匹配。 这是广告支出浪费的首要原因：如果广告系列未使用智能出价，draft_campaign 会拒绝广泛匹配关键词；draft_keywords / draft_ad_group 则会在预览中将其标记为危险，因此 AI 必须在应用前提出警告。
• 写入前验证。 任何写入操作前，AI 都会检查出价策略、转化跟踪状态和质量得分。如果广告系列存在根本性问题，AdLoop 会发出警告，而不是让情况变得更糟。
• 结构化错误处理。 所有工具都会返回附带提示、可供采取行动的错误消息，而不是原始异常。身份验证错误会提供具体的重新授权步骤。
• 固定 API 版本。 固定 Google Ads API 版本，以防库更新导致静默的破坏性更改。health_check 会在有更新版本时发出警告。
• 兼容 Ask 模式。 读取工具声明 readOnlyHint，因此无需切换到 Agent 模式，就能在 Cursor 的 Ask 模式下使用。

设置

AdLoop 使用你自己的（免费）Google Cloud 项目进行 OAuth。 adloop init 向导会引导你完成设置——一次性设置约需 5 分钟，没有共享用户数上限，也无需等待他人完成验证审核。AdLoop 不提供内置 OAuth 凭据。

想要零设置？ AdLoop Cloud 是托管版本：只需两次点击即可连接 Google——无需 Cloud 项目，无需申请 API 访问权限，并托管在欧盟。

（从 ≤0.9 版本（使用内置凭据）升级？这些登录方式已于 0.10 版本停用——运行一次 adloop init，即可切换到你自己的项目。）

重要

看到 deleted_client: The OAuth client was deleted. 或 invalid_client？ AdLoop ≤0.9 捆绑凭据所依赖的共享 Google Cloud 项目已关闭，因此储存的登录信息不再刷新。你可以选择以下两种方式：AdLoop Cloud（两次点击即可连接 Google，无需配置），或者继续自行托管，运行 pip install -U adloop && adloop init 来设置你自己的免费 Google Cloud 项目。详情请参阅置顶议题（#49）。

安装

从 PyPI 安装：

pip install adloop
adloop init

从源代码安装：

git clone https://github.com/kLOsk/adloop.git
cd adloop
uv sync
uv run adloop init

adloop init 的作用

向导首先会询问是否设置 Google。选择否，即可仅通过 Reddit Ads 运行 AdLoop：向导会跳过步骤 1 到 6，直接进入 Reddit 步骤。否则，向导会引导你完成以下操作：

1. 设置 Google Cloud — 创建项目、启用三个 API 并生成 OAuth 客户端（向导会引导你参阅下方的自定义 Google Cloud 项目设置，了解具体步骤）
2. 获取 Google Ads API 访问权限 — 在 Cloud 项目的 Google Ads API 概览页面上申请；旧版开发者令牌提示可以留空
3. MCC 帐户 ID — 可选，仅当你通过管理帐户访问多个帐户时才需要
4. OAuth 登录 — 打开浏览器并使用 Google 登录（无头服务器会显示一个 URL）
5. 自动发现你的帐户 — 自动查找你的 GA4 媒体资源和 Ads 帐户
6. 可选服务 — 固定一个 GTM 容器、一个 Search Console 媒体资源（两者也会自动发现）和一个 PageSpeed API 密钥；按 Enter 可跳过任意项
7. Reddit Ads — 与 Google 并用时可选；不使用 Google 时则必需：需要你自己的 Reddit 开发者应用、登录和默认广告帐户
8. 安全默认设置 — 预算上限和试运行偏好设置
9. 工具集 — 可选择仅向 AI 客户端公开工具目录中的部分工具（参见工具集 — 缩减上下文占用）
10. 编辑器配置片段 — 显示 Cursor 和 Claude Code 的 MCP 配置，其中包括你选择的工具集

要求

• Python 3.11+
• Google Ads 帐户（管理帐户为可选；只有在通过一次登录访问多个帐户时才需要）
• Google Cloud 项目上的 Google Ads API 访问权限（见下文）

Google Ads API 访问权限

自 2026 年 9 月 9 日起，Google Ads API 访问权限归属于拥有 OAuth 客户端的 Google Cloud 项目。开发者令牌已停用：API 会忽略该请求头，向导中的令牌提示为可选项，你也不再需要管理帐户来获取访问权限。

在 Cloud Console 中前往项目的 Google Ads API 概览页面申请：

级别	获取方式	可进行的操作
Test	启用 Google Ads API 时自动获得	仅限测试帐户，不能用于生产帐户。出现 CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION（较旧的 API 版本会显示 DEVELOPER_TOKEN_NOT_APPROVED）表示你当前处于此级别。
Explorer	选择“升级访问级别”→ 申请；通常会自动获批	在生产帐户上每天可执行 2,880 次操作。足以开始使用。
Basic	提交申请；项目完成品牌验证后，通常会在几分钟内自动审核（OAuth 同意屏幕需设为 External，并发布为“In production”）	每天可执行 15,000 次操作。
Standard	提交申请；人工审核，约需十个工作日	更高的限制；须遵守 Google 的 RMF 政策

处于 Cloud 免费试用期或停用了结算功能的项目无法获得 Explorer 和 Basic 级别的访问权限；请使用已设置结算功能的项目。

遇到 CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION？ 你的项目处于 Test 级别。打开上方的概览页面并申请 Explorer 访问权限。

无头服务器

如果你在没有浏览器的服务器上运行（VM、Docker、SSH），向导会自动检测并切换到手动流程：它会显示一个授权 URL，你可以在任意设备上打开，然后将重定向 URL 粘贴回终端。

自定义 Google Cloud 项目设置

向导会引导你完成以下步骤——请在运行 adloop init 之前（或向导等待 OAuth 提示时）在浏览器中完成这些操作。

步骤 1 — Google Cloud 项目

1. 前往 console.cloud.google.com 并创建一个新项目
2. 启用以下三个 API（在 API 库中分别搜索）：
   • Google Analytics Data API — 用于 GA4 报告和事件
   • Google Analytics Admin API — 用于列出 GA4 媒体资源
   • Google Ads API — 用于所有广告操作

步骤 2 — OAuth 凭据

1. 在 Google Cloud 项目中，前往 API 和服务 → 凭据
2. 点击 创建凭据 → OAuth 客户端 ID
3. 将应用类型选为 桌面应用，名称可任意填写
4. 下载 JSON 文件，并将其保存为 ~/.adloop/credentials.json

也支持服务账号——只需将服务账号密钥 JSON 放在相同的 credentials_path 中。AdLoop 会自动检测文件类型。

步骤 3 — 连接到你的编辑器

Cursor — 添加到项目的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "adloop": {
      "command": "/absolute/path/to/adloop/.venv/bin/python",
      "args": ["-m", "adloop"]
    }
  }
}

然后将此仓库中的 .cursor/rules/adloop.mdc 复制到项目的 .cursor/rules/ 目录中。

Claude Code — 运行：

claude mcp add --transport stdio adloop -- /absolute/path/to/adloop/.venv/bin/python -m adloop

或者添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "adloop": {
      "command": "/absolute/path/to/adloop/.venv/bin/python",
      "args": ["-m", "adloop"]
    }
  }
}

然后全局安装编排规则和斜杠命令，让每个 Claude Code 会话都能使用它们：

adloop install-rules

这会向 ~/.claude/CLAUDE.md 写入一个托管代码块，并将斜杠命令（前缀为 adloop-*）复制到 ~/.claude/commands/。该代码块由哨兵注释标记，因此可以安全地多次运行——重新运行只会刷新内容。提供两种安装模式：

• inline（install-rules 的默认模式）——将完整规则嵌入 ~/.claude/CLAUDE.md。可靠，但无论是否连接 AdLoop，这些规则都会加载到每个仓库中的每个 Claude Code 会话，占用约 30K 个 token。
• lazy（adloop install-rules --lazy，也是 adloop init 的默认模式）——在 CLAUDE.md 中添加一条简短指令，指向 ~/.adloop/rules/adloop.md。只有在 AdLoop 工具处于作用范围内时，大模型才会读取规则文件，因此不使用 AdLoop 的会话几乎不会产生开销。该文件特意放在 ~/.claude/ 之外：Claude Code 会将 ~/.claude/rules/ 中的所有内容加载到每个会话中。

升级 AdLoop 后若要刷新：adloop update-rules。若要彻底移除：adloop uninstall-rules——只会处理托管代码块和 adloop-* 命令，不会触碰你自己的内容。

如果你更愿意手动管理，也可以将此仓库中的 .claude/rules/adloop.md 和 .claude/commands/ 复制到项目的 .claude/ 目录中。

Claude Desktop / claude.ai 没有可通过程序设置的规则位置。运行 adloop install-rules，它会输出规则内容，供你粘贴到 claude.ai 的“项目设置 → 自定义说明”中。

开始使用

可以向 AI 助手提出以下问题：

• “本月我的 Google Ads 广告系列表现如何？”
• “哪些搜索词在浪费预算？将它们添加为否定关键词。”
• “我的注册转化量下降了——检查 GA4 和 Ads，找出原因。”
• “为我的主要广告系列起草一则新的自适应搜索广告。”
• “哪些着陆页有付费流量但没有转化？”
• “我的跟踪设置正确吗？将代码库中的事件与 GA4 进行比较。”
• “审核我的 Google Tag Manager 容器——记录了哪些转化？还有哪些遗漏？”
• “针对 [product]，我应该投放哪些关键词？查找建议并估算预算。”
• “这些关键词在德国需要多少预算？”
• “为 [product feature] 创建一个新的搜索广告系列，预算为 €20/天。”

配置参考

所有配置均位于 ~/.adloop/config.yaml。请参阅 config.yaml.example 获取带注释的模板。

Section	Key	Default	Description
google	project_id	(empty)	Google Cloud 项目 ID（仅在使用自定义凭据时需要）
google	credentials_path	(empty)	OAuth 客户端 JSON 或服务账号密钥的路径。留空 = ~/.adloop/credentials.json，否则使用 Application Default Credentials。
google	token_path	~/.adloop/token.json	OAuth 令牌的存储位置（自动创建）
ga4	property_id	—	你的 GA4 媒体资源 ID（由 adloop init 自动发现）
ads	developer_token	—	旧版选项，可选：自 2026 年 9 月起，API 访问权限归属于你的 Cloud 项目
ads	customer_id	—	默认 Google Ads 客户 ID（由 adloop init 自动发现）
ads	login_customer_id	—	你的 MCC 账号 ID
reddit	client_id / client_secret	(empty)	你的 Reddit 开发者应用（Business Manager → Developer Application）
reddit	ad_account_id	(empty)	所有 Reddit 工具的默认 Reddit 广告账号（由 adloop init 选定）
reddit	username	(empty)	你的 Reddit 用户名，仅用于 Reddit 要求的 User-Agent
reddit	token_path	~/.adloop/reddit_token.json	Reddit 刷新令牌的存储位置
safety	max_daily_budget	50.00	每个广告系列允许的最高日预算
safety	require_dry_run	true	强制所有写入操作以 dry-run 模式运行
safety	two_phase_apply	false	计划通过 dry-run 检查前，拒绝实际应用
safety	blocked_operations	[]	完全禁止的操作

工具集——缩减上下文占用

大多数 MCP 客户端（claude.ai、ChatGPT、Cursor 等）会在每次对话开始时，将每个工具架构都加载到模型的上下文中。AdLoop 的完整目录会占用相当一部分上下文窗口，这部分开销在你输入任何内容前就已产生。如果你只使用 AdLoop 的部分功能，可在 MCP 客户端的 env 区块中使用 ADLOOP_TOOLSETS 环境变量，开放部分工具（adloop init 向导提供此选项，并会为你将其写入代码片段）：

"env": { "ADLOOP_TOOLSETS": "ads,ga4" }

工具集	涵盖范围
ads	Google Ads 读取、写入和规划（Keyword Planner）
ga4	Google Analytics 报告、实时数据、关键事件
tracking	跨渠道归因 + 跟踪代码生成
gtm	Google Tag Manager 审核、读取和选择性写入
gsc	Search Console 读取
web	PageSpeed / Core Web Vitals
merchant	Merchant Center Feed 健康状况
reddit	Reddit Ads 读取、写入和规划

还可以进一步缩小 Google Ads 的范围。使用以下任一项代替 ads：

子集	涵盖范围
ads:read	Ads 报告、GAQL，以及 Ads/Analytics 交叉检查（attribution_check、analyze_campaign_conversions、landing_page_analysis）
ads:write	Ads 草稿和变更；也会启用 ads:read，因为创建草稿前需要先读取数据（ID、出价策略）
ads:plan	关键词创意和预算预测（discover_keywords、estimate_budget）

无论选择什么，都会始终包含 health_check 和 confirm_and_apply。未设置 = 完整目录；名称无效时，启动会失败并列出有效选项。效果显著：对于审核和诊断，ads:read,ga4 的开销约为 ads,ga4 的 40%；仅使用 ads:plan 进行关键词研究的客户端，开销约为完整目录的 5%。工具集按客户端配置，而非按安装配置：同一份 AdLoop 配置可以同时为精简配置的 Cursor 和使用完整目录的 Claude Code 提供服务。

在 AdLoop Cloud 上，相同功能按 API 密钥配置：在控制面板中创建密钥时选择工具集，该密钥的 tools/list 会在服务端进行精简，供使用该密钥的任意 AI 客户端调用。

项目结构

src/adloop/
├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
├── server.py          # FastMCP server — every tool registration with safety annotations and toolset tags
├── config.py          # Config loader (~/.adloop/config.yaml)
├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
├── cli.py             # Interactive 'adloop init' setup wizard
├── crossref.py        # Cross-reference tools (GA4 + Ads + GTM combined analysis)
├── tracking.py        # Tracking validation + code generation tools
├── ga4/
│   ├── client.py      # GA4 Data + Admin API clients
│   ├── reports.py     # Account summaries, reports, realtime
│   └── tracking.py    # Event discovery
├── ads/
│   ├── client.py      # Google Ads API client (version-pinned) + retry/backoff for rate limits
│   ├── gaql.py        # GAQL query execution with human-readable error parsing
│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, shared sets, recommendations, audience reads
│   ├── pmax.py        # Performance Max tools — campaign/asset group performance, asset labels, top combinations
│   ├── write.py       # Draft campaign, RSA, keywords; pause, enable, remove, confirm
│   └── forecast.py    # Budget estimation + keyword discovery via Keyword Planner API
├── gtm/
│   ├── client.py      # Google Tag Manager API v2 client
│   └── read.py        # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
├── reddit/
│   ├── auth.py        # Reddit OAuth2 (own app, permanent refresh token, loopback flow for adloop init)
│   ├── client.py      # Reddit Ads API v3 REST client — bearer refresh, per-user rate limits, pagination
│   ├── read.py        # Accounts, campaigns, ad groups, ads, performance reports, pixels, targeting lookups
│   └── write.py       # Draft/preflight/apply for status, budget, bid, targeting, and PAUSED creation
└── safety/
    ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
    ├── preview.py     # Change plans and previews
    └── audit.py       # Mutation audit logging

路线图

已发布内容与后续计划：

• GA4 读取工具 ✓
• 带安全层的 Google Ads 读取与写入工具 ✓
• 交叉引用分析（广告系列→转化映射、落地页分析、归因对比） ✓
• 跟踪实用工具（根据 GA4 验证事件、生成 gtag 代码） ✓
• 通过 Keyword Planner 估算预算 + 发现关键词 ✓
• 共享否定关键词列表（SharedSet API） ✓
• API 速率限制的重试/退避机制 ✓
• 设置向导（adloop init） ✓
• 支持 Claude Code ✓ — CLAUDE.md、.mcp.json、.claude/rules/、.claude/commands/、CLI 向导代码片段
• Claude Desktop 一键安装 — adloop install claude-desktop（和/或 .dxt 扩展包），自动将 AdLoop MCP 配置写入 claude_desktop_config.json，让 Claude Desktop + Cowork 用户无需手动编辑 JSON
• PyPI 包 ✓ — pip install adloop
• AdLoop Cloud ✓ — 托管版本：无需 Google Cloud 项目，无需申请 API 访问权限，只需两步即可连接 Google（托管于欧盟，优先保障 GDPR 合规）
• 无头服务支持 ✓ — 为没有浏览器的服务提供手动复制粘贴 URL 的流程
• 行为评估测试套件 ✓ — tests/evals/ 中用于测试读取、写入、跟踪和规划工作流的提示词与预期结果测试
• Google Tag Manager 集成 ✓ — 提供标签、触发器、变量、工作区和版本历史的读取工具，以及 audit_event_coverage，用于关联代码库事件、GTM 标签和 GA4 实际触发的三方数据
• 社区发布 — HN、Indie Hackers、r/cursor、Twitter
• 视频演示

贡献

请参阅 CONTRIBUTING.md 了解指南。简而言之：先提交 issue 说明你的情况，如果想参与开发，再提交 PR。

许可证

MIT — 请参阅 LICENSE。

隐私

开源版本完全在你的计算机上运行。不会收集、存储或向任何服务传输数据。请参阅 PRIVACY.md 了解完整的隐私政策。AdLoop Cloud 有自己的隐私政策和 DPA。

---