ai-ads-agent

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gomarble-ai/ai-ads-agent/main/assets/logo-dark.png"> <img alt="AI Ads Agent — by GoMarble" src="https://raw.githubusercontent.com/gomarble-ai/ai-ads-agent/main/assets/logo-light.png" width="320"> </picture> </p> <h1 align="center">AI 广告代理</h1> <p align="center"> <i>您终端中的高级 AI 广告代理。<br/> 由 <a href="https://gomarble.ai"><b>GoMarble</b></a> 构建。</i> </p> <p align="center"> <a href="https://www.npmjs.com/package/ai-ads-agent"><img src="https://img.shields.io/npm/v/ai-ads-agent?color=1F3A8A&label=npm" alt="npm 版本"></a> <a href="https://www.npmjs.com/package/ai-ads-agent"><img src="https://img.shields.io/npm/dm/ai-ads-agent?color=1F3A8A&label=downloads" alt="npm 下载量"></a> <img src="https://img.shields.io/npm/l/ai-ads-agent?color=1F3A8A&label=license" alt="MIT License"> <img src="https://img.shields.io/badge/Claude_Code-supported-1F3A8A" alt="Claude Code 支持"> <img src="https://img.shields.io/badge/Codex_CLI-supported-1F3A8A" alt="Codex CLI 支持"> </p> --- > **您指尖的高级 AI 广告代理。** Meta 策略师、Google Ads 专家、创意疲劳分析师、GA4 属性专家、Shopify 运营负责人 — 每个人都是具有 battle-tested 流程的专业代理，而不是普通的聊天机器人。 **AI 广告代理** 是适用于 **Claude Code & Codex CLI** 的 AI 广告代理 — 它将您的终端连接到您的广告账户，并将其变成跨 Google Ads、Meta、TikTok、LinkedIn、Bing、GA4、Shopify、Klaviyo 和 Search Console 的高级性能营销人员。由 [GoMarble](https://gomarble.ai) 构建，该团队为一些增长最快的 DTC 品牌提供付费媒体服务。 - 🔌 **实时广告平台数据** 通过 GoMarble MCP 服务器 — OAuth，一键登录 - 🧠 **36 个专家创作的技能** — Google Ads、Meta（Facebook/Instagram）、GA4、Shopify、Search Console、Klaviyo、TikTok、LinkedIn、Bing Ads、文档生成 - ⚡ **8 个晨间工作流 slash 命令** — Meta + Google 的日常审计和决策矩阵 - 🛡️ **内置防护栏** — 无合成数据，无虚构关键词，正确的归因规则 --- ## 安装 ### Claude Code 在一个 Claude Code 会话中，粘贴以下三个命令： ```text /plugin marketplace add https://github.com/gomarble-ai/ai-ads-agent.git /plugin install ai-ads-agent@ai-ads-agent /reload-plugins ``` > 使用 **完整的 HTTPS URL** （而不是 `owner/repo` 简写）可以避免在配置了将 GitHub HTTPS URL 重写为 SSH 的机器上出现 SSH 密钥错误。 然后连接 MCP 服务器： ```text /mcp ``` 选择 `gomarble`，点击 **Authenticate** — 浏览器打开，您登录到 GoMarble，完成。 ### Codex CLI ```bash codex plugin marketplace add https://github.com/gomarble-ai/ai-ads-agent.git ``` 启动 Codex，打开 **Plugins** 面板，找到 `AI Ads Agent` 并安装。然后： ```bash codex mcp login gomarble ``` 相同的 OAuth 流程，一次性。 ### 一键安装适用于两者（通过 npm） ```bash npx ai-ads-agent ``` 此操作包装了上述官方命令，适用于 macOS / Linux / Windows。 --- ## 🗣️ 您可以向代理询问的内容 技能根据您的提问自动调用 — 您不需要记住任何内容。一些例子： | 提问 | 会发生什么 | |---|---| | _"审计我的 Meta 账户 act_12345 最近 30 天的表现。"_ | 加载性能 + 创意 + 深度分析技能，拉取 30 天数据，运行帕累托分析，标记疲劳创意，显示 ROAS 离群值，生成报告。 | | _"我的 Google Ads 搜索活动本周表现如何？"_ | 加载搜索分析技能，分类查询 Q1–Q5，诊断 CPC 通货膨胀或排名压力，返回决策矩阵。 | | _"为此创意创建 Meta 广告组，针对美国 iOS 用户。"_ | 加载创建/主技能 + 广告组技能，验证父活动，检测像素，构建提议负载，询问您确认后再发布。 | | _"拉取 7 天 Shopify 销售报告，并与 GA4 转化进行比较。"_ | 加载 Shopify 订单规则 + GA4 源技能，查询两者，协调差异。 | | _"生成一个总结我所有付费媒体表现的 PPTX。"_ | 加载 pptx 技能 + 相关分析技能，生成一个文档。 | ### ⚡ Slash 命令（仅 Claude Code） 8 个只读晨间工作流命令。每个命令都生成分析 + 推荐 — **永远不会执行突变**。突变发生在用户明确选择代理模式后。点击任何命令名称以查看其源代码。 **📊 Meta（4）** | 命令 | 功能 | |---|---| | [`/ai-ads-agent:meta-daily-optimization <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/meta-daily-optimization.md) | 晨间简报：1D vs 3D vs 7D，变更日志门控，根本原因行动建议（暂停/削减/重新分配/扩展候选） | | [`/ai-ads-agent:meta-ads-audit <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/meta-ads-audit.md) | 30 天综合审计 — 像素/CAPI，疲劳，观众分割，ROAS 离群值，预算分配 | | [`/ai-ads-agent:meta-creative-fatigue-detection <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/meta-creative-fatigue-detection.md) | 每广告评分（健康/早期警告/疲劳/死亡），附刷新建议 | | [`/ai-ads-agent:meta-creative-strategy <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/meta-creative-strategy.md) | 胜者 + 输家，模式提取，测试计划，扩展计划，12 创意生产规格 | **🎯 Google（4）** | 命令 | 功能 | |---|---| | [`/ai-ads-agent:google-search-audit <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/google-search-audit.md) | 每日搜索简报：品牌与非品牌细分，CUT / FIX / SCALE 建议 | | [`/ai-ads-agent:google-pmax-pulse <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/google-pmax-pulse.md) | 3d-vs-3d PMax 异常检测 — 关键/警报/监控分类，针对过度纠正的纪律 | | [`/ai-ads-agent:google-search-term-audit <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/google-search-term-audit.md) | 使用 80/80 帕累托 + 活动相对触发器的取证浪费审计；建议的否定关键词和根否定 | | [`/ai-ads-agent:google-impression-share <acct>`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/commands/google-impression-share.md) | 失去 IS 分析 → 扩展机会（预算）vs 投标/质量工作（排名），以盈利能力为门控 | 在 Codex 中，只需用自然语言描述任务 — 技能的 `description` 字段负责路由。 --- ## 📦 已发布的技能（36） 点击任何技能名称以查看其 `SKILL.md` 源代码。 ### 🎯 Google Ads（17） | 类型 | 技能 | 功能 | |---|---|---| | 🏗️ 基础 | [`google-ads-tool-fundamentals`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-tool-fundamentals/SKILL.md) | 工具调用模式，GAQL 基础知识，账户结构 | | 🏗️ 基础 | [`google-ads-guardrails`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-guardrails/SKILL.md) | 突变安全性，归因规则，永远不要伪造的内容 | | 🔍 分析 | [`google-ads-search-analysis`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-search-analysis/SKILL.md) | Q1–Q5 查询分类，CPC 通货膨胀诊断 | | 🔍 分析 | [`google-ads-shopping`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-shopping/SKILL.md) | Shopping / Merchant Center 性能审计 | | 🔍 分析 | [`google-ads-pmax-evaluation`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-pmax-evaluation/SKILL.md) | PMax 3d-vs-3d 异常检测 | | 🔍 分析 | [`google-ads-pmax-scaling`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-pmax-scaling/SKILL.md) | PMax 扩展决策，纪律严明以防止过度纠正 | | 🔍 分析 | [`google-ads-keywordplanner`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-keywordplanner/SKILL.md) | 关键词发现，无需编造 | | 🔍 分析 | [`google-ads-depth-of-analysis`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-depth-of-analysis/SKILL.md) | 多层钻取方法 | | ⚡ 执行 | [`google-ads-search-execution`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-search-execution/SKILL.md) | 投标 / 预算 / 结构更改（以盈利能力为门控） | | 🚀 创建 | [`google-ads-create-master-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-master-skill/SKILL.md) | 新活动构建的主管协调器 | | 🚀 创建 | [`google-ads-create-campaign`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-campaign/SKILL.md) | 活动级设置 | | 🚀 创建 | [`google-ads-create-ad-group`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-ad-group/SKILL.md) | 广告组创建 | | 🚀 创建 | [`google-ads-create-ad`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-ad/SKILL.md) | 广告级别创建 | | 🚀 创建 | [`google-ads-create-asset`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-asset/SKILL.md) | 资产上传 | | 🚀 创建 | [`google-ads-create-experiment`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-experiment/SKILL.md) | 实验 / 草稿设置 | | 🚀 创建 | [`google-ads-create-negative-keyword-list`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-negative-keyword-list/SKILL.md) | 否定关键词列表管理 | | 🚀 创建 | [`google-ads-create-bid-modifiers`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/google-ads-create-bid-modifiers/SKILL.md) | 出价修改器设置 | ### 📊 Meta — Facebook + Instagram（10） | 类型 | 技能 | 功能 | |---|---|---| | 🏗️ 基础 | [`meta-tool-fundamentals`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-tool-fundamentals/SKILL.md) | 工具调用模式，账户 / 活动 / 广告组 / 广告分类 | | 🏗️ 基础 | [`meta-guardrails`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-guardrails/SKILL.md) | 突变安全性，归因规则 | | 🔍 分析 | [`meta-performance-analysis`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-performance-analysis/SKILL.md) | 账户级性能审计 | | 🔍 分析 | [`meta-creative-analysis`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-creative-analysis/SKILL.md) | 创意疲劳评分（健康 / 警告 / 疲劳 / 死亡） | | 🔍 分析 | [`meta-depth-of-analysis`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-depth-of-analysis/SKILL.md) | Meta 账户的多层钻取 | | ⚙️ 操作 | [`meta-agent-operations`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-agent-operations/SKILL.md) | Meta 工作流的代理循环模式 | | 🚀 创建 | [`meta-create-master-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-create-master-skill/SKILL.md) | 新 Meta 活动构建的主管协调器 | | 🚀 创建 | [`meta-create-campaign`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-create-campaign/SKILL.md) | 活动级设置 | | 🚀 创建 | [`meta-create-adset`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-create-adset/SKILL.md) | 广告组设置 | | 🚀 创建 | [`meta-create-ad-with-creative`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/meta-create-ad-with-creative/SKILL.md) | 广告 + 创意配对 | ### 📈 其他平台（4） | 平台 | 技能 | 功能 | |---|---|---| | 📊 GA4 | [`ga4-source-of-truth`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/ga4-source-of-truth/SKILL.md) | 转化 ≠ 交易，渠道子集求和陷阱，归因规则 | | 🛍️ Shopify | [`shopify-order-discipline`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/shopify-order-discipline/SKILL.md) | 无 `financial_status` 过滤器，毛净，退款，多币种 | | 🔎 搜索控制台 | [`search-console-master-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/search-console-master-skill/SKILL.md) | 有机搜索分析 + 机会评分 | | 🎨 创意 | [`creative-research`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/creative-research/SKILL.md) | 竞争对手研究，常绿 + 爆款赢家，模式分析 | ### 📄 文档生成（5） | 格式 | 技能 | 功能 | |---|---|---| | 📝 DOCX | [`documents-docx-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/documents-docx-skill/SKILL.md) | Word 文档生成 | | 🎯 PPTX | [`documents-pptx-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/documents-pptx-skill/SKILL.md) | PowerPoint 文档生成 | | 📑 PDF | [`documents-pdf-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/documents-pdf-skill/SKILL.md) | PDF 报告生成 | | 📊 XLSX | [`documents-xlsx-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/documents-xlsx-skill/SKILL.md) | Excel 电子表格生成 | | 🐍 Python | [`python-sandbox-skill`](https://github.com/gomarble-ai/ai-ads-agent/blob/main/skills/python-sandbox-skill/SKILL.md) | 所有文档生成的基础 | --- ## 🔗 文档生成基础 | ### 📄 仓库布局 此安装命令适用于所有安装命令： ``` ai-ads-agent/ ├── .claude-plugin/ │ ├── plugin.json # Claude Code 清单 │ └── marketplace.json # 市场清单声明 ├── .codex-plugin/ │ └── plugin.json # Codex 清单，包含丰富的安装元数据 ├── .mcp.json # 远程 MCP 接线（Streamable HTTP + OAuth） ├── commands/ # 8 个 slash 命令（Claude 读取；Codex 忽略） ├── hooks/ │ ├── hooks.json # 注册 SessionStart 钩子 │ └── session-start.mjs # MCP 探测 + 版本检查 + 今日日期注入 ├── skills/ # 36 个 SKILL.md 文件夹 — 两个主机都从这里读取 └── README.md ``` ### 为什么一个文件夹适用于两个主机 每个主机在其专用子文件夹中查找其清单；其他所有内容都是共享的。 | 主机 | 清单 | 读取 | 忽略 | |---|---|---|---| | Claude Code | `.claude-plugin/plugin.json` | `skills/`、`commands/`、`.mcp.json` (`mcpServers` 键) | `.codex-plugin/` | | Codex | `.codex-plugin/plugin.json` | `skills/`、`.mcp.json` (`mcp_servers` 键) | `.claude-plugin/plugin.json`、`commands/` | `.mcp.json` 发布 **两个** 包装器键，内容相同，以便每个主机找到其首选表单。 --- ## 支持 - **文档和示例：** https://gomarble.ai - **问题和功能请求：** https://github.com/gomarble-ai/ai-ads-agent/issues - **账户 / 计费：** https://apps.gomarble.ai --- <p align="center"> <a href="https://gomarble.ai"> <img src="https://raw.githubusercontent.com/gomarble-ai/ai-ads-agent/main/assets/icon.svg" alt="GoMarble" height="40"> </a> </p> <p align="center"> <b>由 <a href="https://gomarble.ai">GoMarble</b> 构建。<br/> 适用于性能营销人员的 AI 广告代理 — Google Ads、Meta、TikTok、LinkedIn、Bing、GA4、Shopify、Klaviyo 等。</i> </p> <p align="center"> _{© GoMarble. MIT 许可。} </p>