488 lines
15 KiB
Markdown
488 lines
15 KiB
Markdown
# 广告自动化开放协议
|
||
|
||
`广告技术` `MCP协议` `AI自动化` `程序化广告` `开放标准`
|
||
|
||
# AdCP - 广告自动化开放标准
|
||
|
||
**基于 MCP 和 A2A 协议的广告自动化开放标准**
|
||
|
||
[](https://github.com/adcontextprotocol/adcp)
|
||
[](https://adcontextprotocol.org)
|
||
[](https://www.npmjs.com/package/@adcp/client)
|
||
[](https://modelcontextprotocol.io)
|
||
|
||
> **AdCP 通过提供一套统一的、AI 驱动的协议，彻底革新广告自动化领域，支持所有主流广告平台。**
|
||
|
||
## 文档
|
||
|
||
访问 [adcontextprotocol.org](https://adcontextprotocol.org) 查看完整文档。
|
||
|
||
## 什么是 AdCP？
|
||
|
||
广告上下文协议（Ad Context Protocol，AdCP）是一套**广告自动化开放标准**，使 AI 助手能够通过自然语言与广告平台进行交互。AdCP 定义了基于 MCP 和 A2A 传输层的领域专属任务和数据结构：
|
||
|
||
- 🔌 **统一广告 API** - 面向所有广告平台的单一接口
|
||
- 🤖 **AI 驱动自动化** - 专为自然语言广告活动管理而生
|
||
- 📊 **跨平台分析** - 跨所有平台的标准化报告
|
||
- 🔓 **开放标准** - 无厂商锁定，社区驱动开发
|
||
- ⚡ **程序化就绪** - 专为现代广告技术工作流设计
|
||
|
||
### 快速示例
|
||
|
||
无需在复杂界面中导航，直接说：
|
||
|
||
> "找到对高端跑步鞋感兴趣的优质运动爱好者受众信号，并在 Scope3 上激活。"
|
||
|
||
AI 助手会自动处理：
|
||
- 跨平台信号发现
|
||
- 透明定价比较
|
||
- 在决策平台上直接激活
|
||
|
||
## 可用协议
|
||
|
||
### 🎯 信号激活协议 - RFC/v0.1
|
||
使用自然语言发现并激活数据信号。
|
||
|
||
- **自然语言发现**："对可持续时尚感兴趣的高收入千禧一代"（受众信号）
|
||
- **情境信号**："高可见度的优质汽车内容"
|
||
- **多维度组合**：结合地理、时间和行为信号
|
||
- **多平台激活**：跨 DSP 和数据平台部署
|
||
- **透明定价**：CPM 和收益分成模式
|
||
- **实时状态**：跟踪激活和部署进度
|
||
|
||
### 📍 精选协议 - 即将推出
|
||
基于情境和品牌安全要求精选媒体库存。
|
||
|
||
### 💰 媒体购买协议 - RFC/v0.1
|
||
跨平台以编程方式执行并优化媒体购买。
|
||
|
||
## 快速开始
|
||
|
||
### 安装客户端库
|
||
|
||
#### JavaScript/TypeScript
|
||
```bash
|
||
npm install @adcp/client
|
||
```
|
||
- **NPM 包**：[@adcp/client](https://www.npmjs.com/package/@adcp/client)
|
||
- **GitHub**：[adcp-client](https://github.com/adcontextprotocol/adcp-client)
|
||
|
||
#### Python
|
||
```bash
|
||
pip install adcp
|
||
```
|
||
- **PyPI 包**：[adcp](https://pypi.org/project/adcp/)
|
||
|
||
### 面向平台提供商
|
||
|
||
实现 AdCP，为您的客户启用 AI 驱动的工作流：
|
||
|
||
1. **阅读规范**：[信号协议](https://adcontextprotocol.org/docs/signals/specification)
|
||
2. **实现 MCP 服务器**：参考[参考实现](#参考实现)
|
||
3. **测试您的实现**：使用验证测试套件
|
||
|
||
### 面向广告主和代理商
|
||
|
||
使用支持 AdCP 的平台配合您的 AI 助手：
|
||
|
||
1. **检查平台支持**：查看哪些平台支持 AdCP
|
||
2. **配置您的 AI**：将支持 AdCP 的平台连接到 Claude、GPT 或其他助手
|
||
3. **开始使用**：用自然语言描述您的营销目标
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
adcontextprotocol/
|
||
├── mintlify-docs/ # Mintlify 文档 (docs.adcontextprotocol.org)
|
||
│ ├── docs/ # 协议文档
|
||
│ │ ├── signals/ # 信号协议
|
||
│ │ ├── media-buy/ # 媒体购买协议
|
||
│ │ └── creatives/ # 创意协议
|
||
├── server/ # Express 服务器
|
||
│ ├── src/ # TypeScript 服务器代码
|
||
│ └── public/ # 静态 HTML 页面（主页、注册表 UI）
|
||
├── static/ # 静态资源
|
||
│ └── schemas/ # JSON 模式
|
||
├── registry/ # 代理注册表
|
||
│ ├── creative/ # 创意代理
|
||
│ ├── media-buy/ # 媒体购买代理
|
||
│ └── signals/ # 信号代理
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
## 社区
|
||
|
||
### 工作组
|
||
|
||
加入我们的工作组，共同塑造广告协议的未来：
|
||
|
||
- **每月例会**：每月第一个星期三
|
||
- **GitHub 讨论**：[加入对话](https://github.com/adcontextprotocol/adcp/discussions)
|
||
- **邮件列表**：announcements@adcontextprotocol.org
|
||
|
||
### 贡献
|
||
|
||
我们欢迎来自以下方面的贡献：
|
||
|
||
- **平台提供商**：实现并改进协议
|
||
- **代理商和广告主**：分享用例和反馈
|
||
- **开发者**：贡献代码、文档和示例
|
||
- **行业专家**：帮助定义标准和最佳实践
|
||
|
||
详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
||
|
||
## 参考实现
|
||
|
||
- [信号代理](https://github.com/adcontextprotocol/signals-agent)
|
||
- [销售代理](https://github.com/adcontextprotocol/salesagent)
|
||
|
||
## 平台实现
|
||
|
||
### 当前支持
|
||
|
||
- **参考实现**：完整的 MCP 服务器示例
|
||
- **Scope3**：完整信号激活协议支持
|
||
- **更多平台**：其他平台将于 2025 年第一季度接入
|
||
|
||
## 本地开发
|
||
|
||
本仓库运行一个统一的 Express 服务器，从单一进程提供所有服务：
|
||
|
||
- 🏠 **主页** - `/`
|
||
- 🤖 **代理注册表** - `/registry` - 浏览并测试所有 AdCP 代理
|
||
- 📋 **AdAgents 管理器** - `/adagents` - 验证和创建 adagents.json 文件
|
||
- 📚 **Mintlify 文档** - 完整协议文档
|
||
- 📄 **JSON 模式** - `/schemas/*`
|
||
- 🔧 **REST API** - `/api/*`
|
||
- 📡 **MCP 协议** - `/mcp`
|
||
|
||
### 前置条件
|
||
|
||
- Node.js 18+
|
||
- Docker（用于本地数据库）
|
||
- npm 或 yarn
|
||
|
||
### 快速开始
|
||
|
||
#### 1. 安装依赖
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
#### 2. 环境配置
|
||
|
||
复制环境模板并配置密钥：
|
||
```bash
|
||
cp .env.local.example .env.local
|
||
```
|
||
|
||
#### 3. 数据库设置（必需）
|
||
|
||
```bash
|
||
# 在 Docker 中启动 PostgreSQL
|
||
docker-compose up -d
|
||
|
||
# 运行迁移
|
||
npm run db:migrate
|
||
```
|
||
|
||
#### 4. 启动开发环境
|
||
|
||
**方式一：一起运行所有服务（推荐）**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
启动内容：
|
||
- **HTTP 服务器**（蓝色）- 应用运行在 3000 端口
|
||
- **Mintlify 文档**（绿色）- 文档运行在 3333 端口
|
||
- **Stripe CLI**（紫红色）- Webhook 转发（如已配置 Stripe）
|
||
|
||
**方式二：单独运行各服务**
|
||
```bash
|
||
# 终端 1：启动服务器
|
||
npm start
|
||
|
||
# 终端 2：启动文档（可选）
|
||
npm run start:mintlify
|
||
|
||
# 终端 3：启动 Stripe Webhook（可选，如已配置 Stripe）
|
||
npm run start:stripe
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
- http://localhost:3000 - 主页
|
||
- http://localhost:3000/registry - 代理注册表
|
||
- http://localhost:3000/adagents - AdAgents.json 管理器
|
||
- http://localhost:3000/schemas/v1/index.json - 模式注册表
|
||
- http://localhost:3000/api/agents - REST API
|
||
- http://localhost:3333 - Mintlify 文档（单独运行时）
|
||
|
||
### 数据库操作
|
||
|
||
```bash
|
||
# 运行迁移
|
||
npm run db:migrate
|
||
```
|
||
|
||
### 其他命令
|
||
|
||
```bash
|
||
# 运行测试
|
||
npm test
|
||
|
||
# 类型检查
|
||
npm run typecheck
|
||
|
||
# 构建 TypeScript
|
||
npm run build
|
||
|
||
# 以 MCP 模式启动（stdio）
|
||
npm start:mcp
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
所有环境变量在服务器启动时验证。完整模板请参见 `.env.local.example`。
|
||
|
||
**服务器配置：**
|
||
- `PORT` - 服务器端口（默认：3000）
|
||
- `NODE_ENV` - 环境（development|production）
|
||
- `MODE` - 服务器模式（http|mcp）
|
||
- `LOG_LEVEL` - 日志级别（trace|debug|info|warn|error|fatal，开发默认：debug，生产默认：info）
|
||
|
||
**数据库配置（必需）：**
|
||
- `DATABASE_URL` - PostgreSQL 连接字符串（**必需**）
|
||
- `DATABASE_SSL` - 启用 SSL（默认：false）
|
||
- `DATABASE_SSL_REJECT_UNAUTHORIZED` - 验证 SSL 证书（启用 SSL 时默认：true）
|
||
- `DATABASE_MAX_POOL_SIZE` - 连接池大小（默认：20）
|
||
- `DATABASE_IDLE_TIMEOUT_MS` - 空闲超时（默认：30000）
|
||
- `DATABASE_CONNECTION_TIMEOUT_MS` - 连接超时（默认：5000）
|
||
|
||
**认证（注册表功能必需）：**
|
||
- `WORKOS_API_KEY` - WorkOS API 密钥（**必需**）
|
||
- `WORKOS_CLIENT_ID` - WorkOS OAuth 客户端 ID（**必需**）
|
||
- `WORKOS_COOKIE_PASSWORD` - 会话加密密钥，最少 32 个字符（**必需**）
|
||
- `WORKOS_REDIRECT_URI` - OAuth 回调 URL（默认：http://localhost:3000/auth/callback）
|
||
|
||
**计费（可选 - Stripe）：**
|
||
- `STRIPE_SECRET_KEY` - Stripe 密钥（sk_test_... 或 sk_live_...）
|
||
- `STRIPE_PUBLISHABLE_KEY` - Stripe 公钥（pk_test_... 或 pk_live_...）
|
||
- `STRIPE_PRICING_TABLE_ID` - 订阅 UI 的 Stripe 定价表 ID
|
||
- `STRIPE_WEBHOOK_SECRET` - Webhook 签名密钥（whsec_...，开发环境由 Stripe CLI 自动提供）
|
||
|
||
**注意：** 注册表现仅支持数据库存储。运行服务器必须提供 `DATABASE_URL`。如果启动时数据库不可用，服务器将立即失败（快速失败行为），确保不会在缺少数据持久化的情况下意外运行。
|
||
|
||
### 本地 Stripe 测试
|
||
|
||
使用 `npm run dev` 或 `npm run start:stripe` 时，Stripe CLI 会将 Webhook 转发至 `localhost:3000/api/webhooks/stripe` 并在控制台打印 Webhook 签名密钥。使用测试卡号 `4242 4242 4242 4242` 创建订阅。
|
||
|
||
**触发测试事件：**
|
||
```bash
|
||
stripe trigger customer.subscription.created
|
||
stripe trigger customer.subscription.updated
|
||
```
|
||
|
||
### 分析与商业智能
|
||
|
||
AdCP 集成了由 Metabase 驱动的分析功能，用于追踪收入、客户健康指标和订阅分析。
|
||
|
||
#### 配置 Metabase
|
||
|
||
1. **启动 Metabase 容器：**
|
||
```bash
|
||
docker-compose -f docker-compose.metabase.yml up -d
|
||
```
|
||
|
||
Metabase 将在 http://localhost:3001 可用
|
||
|
||
2. **初始设置**（仅首次）：
|
||
- 打开 http://localhost:3001
|
||
- 创建管理员账户
|
||
- 进入 Admin → Settings → Embedding
|
||
- 启用"在其他应用中嵌入"
|
||
- 复制嵌入密钥
|
||
|
||
3. **在 `.env.local` 中添加 Metabase 配置：**
|
||
```bash
|
||
METABASE_SITE_URL=http://localhost:3001
|
||
METABASE_SECRET_KEY=<your-secret-key-from-metabase>
|
||
```
|
||
|
||
4. **连接 PostgreSQL 数据库：**
|
||
- 在 Metabase 中：Admin → Databases → Add database
|
||
- 类型：PostgreSQL
|
||
- 主机：`host.docker.internal`（Mac/Windows）或 `172.17.0.1`（Linux）
|
||
- 端口：`5432`（或 docker-compose 中的 PostgreSQL 端口）
|
||
- 数据库：`adcp_registry`
|
||
- 用户名：`adcp`
|
||
- 密码：`localdev`
|
||
|
||
5. **创建第一个仪表板：**
|
||
- 在 Metabase 中新建仪表板（如"收入分析"）
|
||
- 使用预置分析视图添加查询（参见 [ANALYTICS.md](./ANALYTICS.md)）
|
||
- 启用仪表板嵌入（分享 → 嵌入 → 启用）
|
||
- 从 URL 记录仪表板 ID（如 `/dashboard/2` → ID 为 `2`）
|
||
|
||
6. **配置嵌入仪表板：**
|
||
```bash
|
||
# 添加到 .env.local
|
||
METABASE_DASHBOARD_ID=2
|
||
```
|
||
|
||
7. **重启开发服务器并访问分析：**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
访问 http://localhost:3000/admin/analytics 查看嵌入仪表板！
|
||
|
||
#### 填充测试收入数据
|
||
|
||
向分析功能填充测试数据：
|
||
|
||
```bash
|
||
# 填充测试收入事件用于分析
|
||
psql $DATABASE_URL -f scripts/seed-test-revenue.sql
|
||
```
|
||
|
||
将创建以下示例数据：
|
||
- 初始订阅付款
|
||
- 数月内的循环付款
|
||
- 示例退款
|
||
- 所有分析视图的数据
|
||
|
||
#### 分析文档
|
||
|
||
关于以下内容的详细信息：
|
||
- 可用分析视图（收入、客户健康、订阅）
|
||
- 示例 SQL 查询
|
||
- 仪表板模板
|
||
- 故障排查
|
||
|
||
详见 [ANALYTICS.md](./ANALYTICS.md)
|
||
|
||
#### 生产环境分析
|
||
|
||
**推荐方式：直接 SQL 访问**
|
||
|
||
对于低流量场景，使用预置分析视图直接查询生产数据库：
|
||
|
||
**可用分析视图：**
|
||
- `monthly_revenue_summary` - 按月收入趋势
|
||
- `customer_health` - 活跃订阅和客户状态
|
||
- `product_revenue` - 按产品细分收入
|
||
- `revenue_events` - 单笔收入交易记录
|
||
|
||
**查询示例：**
|
||
```sql
|
||
-- 月度收入趋势（近 12 个月）
|
||
SELECT month, total_revenue / 100.0 as revenue_usd
|
||
FROM monthly_revenue_summary
|
||
ORDER BY month DESC LIMIT 12;
|
||
|
||
-- 活跃订阅数量
|
||
SELECT COUNT(*) FROM customer_health
|
||
WHERE subscription_status = 'active';
|
||
|
||
-- 按产品划分收入
|
||
SELECT product_name, total_revenue / 100.0 as total_usd
|
||
FROM product_revenue
|
||
ORDER BY total_revenue DESC;
|
||
```
|
||
|
||
**访问生产数据库：**
|
||
```bash
|
||
# 从 Fly.io 密钥获取连接字符串
|
||
fly ssh console --app adcp-docs -C "echo \$DATABASE_URL"
|
||
|
||
# 使用 psql 连接
|
||
psql <DATABASE_URL>
|
||
```
|
||
|
||
`/admin/analytics` 仪表板使用 SQL 视图提供内置分析，无需外部 BI 工具。
|
||
|
||
### 安全要求
|
||
|
||
**生产环境必须使用 HTTPS：**
|
||
|
||
⚠️ **重要**：会话 Cookie 和认证令牌在生产和预发环境中必须通过 HTTPS 传输。
|
||
|
||
- 设置 `NODE_ENV=production` 以启用安全 Cookie
|
||
- 使用反向代理（nginx、Caddy 或云负载均衡器）终止 TLS
|
||
- 从 Let's Encrypt 或您的证书提供商获取 SSL 证书
|
||
- 将 `WORKOS_REDIRECT_URI` 更新为 https:// 方案
|
||
|
||
**开发环境设置：**
|
||
|
||
在本地开发中，为方便起见 Cookie 通过 HTTP 发送。这仅在 localhost 上可接受。对于预发环境，即使使用自签名证书也应始终使用 HTTPS。
|
||
|
||
**生成安全密钥：**
|
||
|
||
```bash
|
||
# 生成 WORKOS_COOKIE_PASSWORD（最少 32 个字符）
|
||
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
```dockerfile
|
||
FROM node:18
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm ci --only=production
|
||
COPY . .
|
||
RUN npm run build
|
||
ENV NODE_ENV=production
|
||
EXPOSE 3000
|
||
CMD ["npm", "start"]
|
||
```
|
||
|
||
## 许可证
|
||
|
||
广告上下文协议规范采用 [Apache 2.0](./LICENSE) 许可证。
|
||
|
||
## 联系方式
|
||
|
||
- **一般咨询**：hello@adcontextprotocol.org
|
||
- **技术支持**：support@adcontextprotocol.org
|
||
- **安全问题**：security@adcontextprotocol.org
|
||
- **合作洽谈**：partnerships@adcontextprotocol.org
|
||
|
||
## 使用场景
|
||
|
||
### 面向广告技术公司
|
||
- 构建统一的广告自动化工具
|
||
- 通过单一 API 集成多个平台
|
||
- 启用 AI 驱动的广告工作流
|
||
- 创建兼容 MCP 的广告服务器
|
||
|
||
### 面向代理商和广告主
|
||
- 跨所有平台自动化广告活动管理
|
||
- 使用自然语言进行广告操作
|
||
- 获取统一的分析和报告
|
||
- 降低集成和维护成本
|
||
|
||
### 面向发布商和广告网络
|
||
- 通过标准化协议开放库存
|
||
- 启用 AI 助手集成
|
||
- 参与自动化广告生态系统
|
||
- 一次实现，兼容所有 AI 工具
|
||
|
||
## 关键词
|
||
|
||
`广告自动化`、`程序化广告 API`、`MCP 广告集成`、`AI 广告工作流`、`统一广告平台 API`、`广告协议标准`、`模型上下文协议广告`、`跨平台广告自动化`
|
||
|
||
## 链接
|
||
|
||
- **官网**：[adcontextprotocol.org](https://adcontextprotocol.org)
|
||
- **API 文档**：[任务参考](https://adcontextprotocol.org/docs/media-buy/task-reference/index)
|
||
- **MCP 集成**：[MCP 指南](https://adcontextprotocol.org/docs/protocols/mcp-guide)
|
||
- **规范**：[信号协议 RFC](https://adcontextprotocol.org/docs/signals/specification)
|
||
- **讨论**：[GitHub 讨论](https://github.com/adcontextprotocol/adcp/discussions)
|
||
- **问题反馈**：[提交 Issue](https://github.com/adcontextprotocol/adcp/issues)
|
||
|
||
---
|
||
|
||
由广告技术社区用心构建。 |