# 腾讯广告平台 API 测试指南

## 项目分析总结

### 系统架构

**auto_put_ad_mini** 是一个智能广告投放系统,主要功能包括:

```
数据拉取 → ROI 计算 → 广告分类(A/B/C) → AI 推理决策 → 保存决策 → 护栏验证 → 生成报告 → 执行
```

### 核心组件

1. **API 封装** (`tools/ad_api.py`)
   - 腾讯广告 Marketing API v3.0 封装
   - 支持广告创建、更新、查询
   - 支持创意管理
   - 支持数据报表查询
   - 支持账户信息查询

2. **数据查询** (`tools/data_query.py`)
   - 拉取创意数据
   - 合并数据

3. **ROI 计算** (`tools/roi_calculator.py`)
   - 计算 f_7日动态ROI
   - 多维度 ROI 分析

4. **决策引擎** (`tools/ad_decision.py`)
   - 广告分类 (A/B/C)
   - AI 推理决策
   - 应用决策

5. **安全护栏** (`tools/guardrails.py`)
   - 验证决策安全性
   - 防止过度调整

6. **执行引擎** (`tools/execution_engine.py`)
   - 分级执行决策
   - 效果检查

7. **报告生成** (`tools/report_generator.py`)
   - 生成决策报告
   - 对比分析

### 关键特性

- **API 版本**: 腾讯广告 Marketing API v3.0
- **层级结构**: 广告(Ad) → 创意(Dynamic Creative)
- **决策依据**: f_7日动态ROI + 消耗双维度
- **决策范围**: 调整出价、暂停广告
- **安全模式**: DRY_RUN_MODE 默认开启,不实际执行

---

## API 测试配置指南

### 1. 获取腾讯广告 API 凭证

#### 1.1 获取 Access Token

1. 登录腾讯广告平台: https://e.qq.com
2. 进入"开发者中心" → "API 管理"
3. 创建应用并获取 `App ID` 和 `App Secret`
4. 使用 OAuth2.0 授权流程获取 `access_token`

详细文档: https://developers.e.qq.com/docs/guide/auth

#### 1.2 获取账户 ID

1. 登录腾讯广告平台
2. 在账户管理页面查看账户 ID (数字格式)
3. 或通过 API 调用 `/accounts/get` 获取

### 2. 配置环境变量

编辑项目根目录的 `.env` 文件,添加以下配置:

```bash
# 腾讯广告 API 配置
TENCENT_AD_ACCESS_TOKEN=your_access_token_here
TENCENT_AD_ACCOUNT_ID=your_account_id_here

# 可选: 自定义 API Base URL (默认为 v3.0)
TENCENT_AD_BASE_URL=https://api.e.qq.com/v3.0
```

**示例:**

```bash
TENCENT_AD_ACCESS_TOKEN=abcdefghijklmnopqrstuvwxyz123456
TENCENT_AD_ACCOUNT_ID=1234567890
```

### 3. 安装依赖

```bash
# 安装 httpx (用于 API 请求)
pip3 install httpx

# 或安装完整依赖
pip3 install -r requirements.txt
```

### 4. 运行测试

```bash
cd /Users/liulidong/project/agent/Agent

# 运行简化版测试 (推荐)
python3 examples/auto_put_ad_mini/test_api_simple.py
```

### 5. 预期结果

如果配置正确,测试脚本会依次测试:

```
✅ 环境变量检查
✅ 账户信息查询
✅ 广告列表查询
✅ 数据报表查询

🎉 所有测试通过! 腾讯广告平台接口可用
```

---

## 测试失败排查

### 错误 1: 环境变量未设置

**现象:**
```
❌ TENCENT_AD_ACCESS_TOKEN: 未设置
```

**解决方法:**
- 确认 `.env` 文件存在于项目根目录
- 确认 `.env` 文件中已添加 `TENCENT_AD_ACCESS_TOKEN` 和 `TENCENT_AD_ACCOUNT_ID`
- 确认没有多余的空格或引号

### 错误 2: API 错误 code != 0

**现象:**
```
❌ API 错误 (code=4001): access_token invalid
```

**可能原因:**
1. Access Token 已过期
2. Access Token 格式错误
3. Access Token 权限不足

**解决方法:**
- 重新获取 Access Token
- 检查 Token 是否有账户访问权限
- 确认使用的是 v3.0 API

### 错误 3: HTTP 错误 403/401

**现象:**
```
❌ HTTP 错误: 403
```

**可能原因:**
1. 账户权限不足
2. IP 白名单未配置
3. 账户状态异常

**解决方法:**
- 检查账户状态是否正常
- 配置 API 调用 IP 白名单
- 确认账户有 API 调用权限

### 错误 4: 网络连接错误

**现象:**
```
❌ 网络请求错误: Connection timeout
```

**可能原因:**
1. 网络不通
2. 防火墙拦截
3. 需要代理

**解决方法:**
- 检查网络连接
- 配置代理 (如果需要):
  ```bash
  export HTTP_PROXY=http://127.0.0.1:7890
  export HTTPS_PROXY=http://127.0.0.1:7890
  ```

---

## API 限制说明

根据腾讯广告 API 文档:

- **QPS 限制**: 单账户 10 QPS
- **批量操作**: 单次最多 50 条
- **金额单位**: 分 (1元 = 100分)
- **审核时间**: 2-4 小时 (普通素材)
- **数据延迟**: 实时数据 15-30 分钟,转化数据 1-2 小时

---

## 下一步操作

配置成功后,可以:

1. **运行完整系统**:
   ```bash
   python3 examples/auto_put_ad_mini/run.py
   ```
   输入指令: `分析广告`

2. **查看系统配置**:
   - 配置文件: `examples/auto_put_ad_mini/config.py`
   - 决策策略: `examples/auto_put_ad_mini/skills/roi_strategy.md`
   - 安全护栏: `examples/auto_put_ad_mini/skills/guardrail_rules.md`

3. **启用执行模式** (谨慎):
   - 编辑 `config.py`
   - 设置 `DRY_RUN_MODE = False`
   - 设置 `EXECUTION_ENABLED = True`

---

## 技术支持

- 腾讯广告 API 文档: https://developers.e.qq.com/docs/
- Marketing API v3.0: https://developers.e.qq.com/docs/api/marketing
- OAuth2.0 授权: https://developers.e.qq.com/docs/guide/auth

---

**最后更新**: 2026-04-15