# auto_put_ad — 项目结构文档

> **定位**: 腾讯广告自动化投放多 Agent 协作系统
> **最后更新**: 2026-07-16

---

## 一、项目概述

`auto_put_ad` 是一个基于 Reson Agent 框架的多 Agent 广告投放系统，面向腾讯广告 Marketing API v3.0。系统由 **8 个专业 sub-agent** 组成，通过主 Agent 统一调度，覆盖预算/出价优化、受众定向、创意策略、监控告警、系统运维、数据分析等投放全链路。

### 当前成熟度

| Agent | 状态 | 说明 |
|-------|------|------|
| **main** | ✅ 就绪 | 任务分发中枢 |
| **budget** | ✅ 就绪 | 预算约束下的出价调整 |
| **execute** | ✅ 就绪 | 审批后执行 API 操作 |
| **audience** | 🟡 部分就绪 | 定向推荐可用，A/B 测试待实现 |
| **data_analyst** | 🟡 部分就绪 | 基础查询可用，深度分析待实现 |
| **creative** | 🔴 未就绪 | 创意策略框架已搭建 |
| **monitor** | 🔴 未就绪 | 监控规则已定义，实时检测待实现 |
| **system_ops** | 🔴 未就绪 | API 运维操作框架已搭建 |

> **与 auto_put_ad_mini 的关系**: `auto_put_ad_mini` 是本项目中「监控调控 Agent」角色的独立落地版本，实际已演进出更完整的决策 + 创建双业务线。本项目当前的核心可用链路是 **budget → execute** 出价调整。

---

## 二、目录结构

```
examples/auto_put_ad/
│
├── run.py                          # 🔵 分析入口：交互式 Agent CLI
├── run_execute.py                  # 🟢 执行入口：审批后执行 API 操作
├── config.py                       # 运行配置（3 套 RunConfig + 工具白名单）
├── task.prompt                     # 主 Agent 任务描述
├── presets.json                    # 8 个 sub-agent 预设定义
├── odps_module.py                  # ODPS（MaxCompute）数据仓库客户端
├── test_budget.py                  # 出价调整独立测试脚本
│
├── README.md                       # 项目概览
├── TODO.md                         # 任务追踪（P0/P1/P2）
├── BID_ADJUSTMENT_README.md        # 出价调整系统深度文档
├── EXECUTION_GUIDE.md              # 生产部署与执行指南
├── IMPLEMENTATION_SUMMARY.md       # 实现总结
│
├── configs/
│   └── budget_strategy_v1.json     # 策略配置（阈值/决策矩阵/出价边界/保护规则）
│
├── docs/
│   ├── budget_decision_framework.md    # 预算决策框架（scale_ratio、2×2 矩阵、保护机制）
│   ├── budget_strategy_detail.md       # 预算策略详解
│   └── 腾讯广告智能投放策略研究-参考.md    # 行业策略参考
│
├── prompts/                        # 各 Agent 系统提示词
│   ├── main.prompt                 # 主调度 Agent
│   ├── budget.prompt               # 预算/出价优化专家
│   ├── execute.prompt              # 执行 Agent
│   ├── audience.prompt             # 受众定向专家
│   ├── creative.prompt             # 创意/素材专家
│   ├── monitor.prompt              # 监控告警
│   └── system_ops.prompt           # API 运维操作
│
├── skills/                         # 领域知识（注入 Agent 上下文）
│   ├── ad_domain.md                # 腾讯广告 3.0 平台知识
│   ├── budget_strategy.md          # 预算/出价决策知识
│   ├── audience_strategy.md        # 受众定向策略
│   ├── creative_strategy.md        # 创意生命周期管理
│   └── monitor_rules.md            # 异常检测规则
│
└── tools/                          # 自定义工具（@tool 装饰器）
    ├── __init__.py
    ├── ad_api.py                   # 腾讯广告 API v3.0 封装（13 个工具）
    ├── data_query.py               # ODPS 数据查询（3 个工具）
    ├── budget_calc.py              # 出价计算引擎（6 个工具）
    ├── audience_tools.py           # 受众定向工具（2 个工具）
    ├── monitor_tools.py            # 监控工具（2 个工具）
    ├── execute_agent.py            # 执行编排（1 个工具）
    └── strategy_config.py          # 策略配置管理（3 个工具）
```

---

## 三、入口点与执行流程

### 3.1 两个入口

| 入口 | 文件 | 用途 | 模型 | 工具范围 |
|------|------|------|------|---------|
| **分析入口** | `run.py` | 交互式分析，制定出价调整方案 | `qwen/qwen3.5-plus-02-15` | ANALYSIS_TOOLS（只读+计算） |
| **执行入口** | `run_execute.py` | 读取已审批的方案，执行 API 操作 | `qwen/qwen3.5-plus-02-15` (temp=0.1) | EXECUTION_TOOLS（含写操作） |

### 3.2 分析流程（run.py）

```
用户输入："今天小程序预算 10 万"
        │
        ▼
┌──────────────────────────────────────┐
│  Main Agent (投放决策中枢)             │
│  System Prompt: prompts/main.prompt  │
│  Skills: ad_domain.md                │
│  Tools: ANALYSIS_TOOLS + agent tool  │
└──────────────────────────────────────┘
        │ 理解意图 → 分派 sub-agent
        ▼
┌──────────────────────────────────────┐
│  Budget Agent (预算出价Agent)          │
│  System Prompt: prompts/budget.prompt│
│  Skills: ad_domain, budget_strategy  │
│                                      │
│  7 步工作流：                          │
│  ① load_strategy_config()  加载策略配置│
│  ② get_account_summary()   拉 ODPS 数据│
│  ③ 战略判断（周末？促销？是否调阈值）     │
│  ④ compute_budget_thresholds() 分位数  │
│  ⑤ classify_ads()          2×2 分类   │
│  ⑥ compute_bid_adjustment() 出价方案   │
│  ⑦ 展示方案 → 等待用户确认              │
└──────────────────────────────────────┘
        │ 用户确认后
        ▼
  bid_adjustment_execute() → 批量 API 调用
        │
        ▼
  输出: outputs/adjustment_plan_YYYYMMDD_HHMMSS.xlsx
```

### 3.3 执行流程（run_execute.py）

```
用户输入："执行最新方案"
        │
        ▼
  自动发现 outputs/ 下最新的 Excel 方案文件
        │
        ▼
┌──────────────────────────────────────┐
│  Execute Agent (投放执行系统)           │
│  System Prompt: prompts/execute.prompt│
│  Skills: ad_domain, budget_strategy,  │
│          monitor_rules                │
│  Tools: EXECUTION_TOOLS               │
└──────────────────────────────────────┘
        │
        ▼
  execute_adjustment_plan():
    ① 加载方案（Excel → 决策列表）
    ② 验证：冷启动跳过 / 赔付保护 / 出价边界 / 15% 振幅上限
    ③ dry_run=True → 仅输出模拟报告
    ④ dry_run=False → 执行：
       a. 出价调整（increase/decrease）→ ad_update()
       b. 广告关停（close）→ ad_batch_update_status()
       c. 执行后监控 → monitor_check_metrics()
    ⑤ 输出执行报告
```

### 3.4 数据流架构

```
ODPS (MaxCompute)                    腾讯广告 API (api.e.qq.com/v3.0)
├── creative_detail                   ├── /adgroups/update
├── ad_put_tencent_ad                 ├── /adgroups/add
├── ad_put_tencent_creative_day       └── /dynamic_creatives/add
├── ad_put_tencent_creative_data_day
└── ad_put_tencent_account
        │                                      ▲
        ▼                                      │
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ data_query.py│ →  │ budget_calc  │ →  │  ad_api.py   │
│ (ODPS SQL)   │    │ (计算引擎)    │    │ (API 调用)    │
└──────────────┘    └──────────────┘    └──────────────┘
        │                   │
        ▼                   ▼
   pandas DataFrame    决策矩阵查找 → [action, ratio]
        效率分 = fission0_count / cost
        百分位阈值 (P70/P30 ROI, P50 消耗)
        2×2 分类 (ROI × 消耗)
```

---

## 四、核心架构设计

### 4.1 策略驱动架构

所有决策参数外置在 `configs/budget_strategy_v1.json`，LLM 可在运行时通过 `update_strategy_config()` 调整策略（如周末放宽 ROI 阈值），变更自动版本化管理：

```json
{
  "thresholds": {
    "roi_high_percentile": 0.70,
    "roi_low_percentile": 0.30,
    "cost_mid_percentile": 0.50,
    "valid_ad_min_open_count": 100
  },
  "decision_matrix": {
    "aggressive_scale_down": {
      "high_high": ["keep", 0.0],
      "mid_high": ["decrease", -0.10],
      "low_low":  ["close", 0.0]
    }
    // ... 5 种策略 × 6 个象限
  },
  "protection": {
    "cold_start": { "enabled": true, "hours": 48, "min_conversions": 6 },
    "compensation": { "enabled": true, "min_conversions": 6, "cpa_deviation": 0.20 }
  }
}
```

### 4.2 决策框架（5 步）

| 步骤 | 操作 | 产出 |
|------|------|------|
| ① **全局策略** | `scale_ratio = 今日预算 ÷ 昨日消耗` | aggressive_scale_down / moderate_scale_down / maintain / moderate_scale_up / aggressive_scale_up |
| ② **样本过滤** | 排除 `open_count < 100` 的广告 | 有效广告池 |
| ③ **分位数计算** | ROI P70/P30 + 消耗 P50 | 动态阈值（非固定值） |
| ④ **2×2 分类** | ROI 高/中/低 × 消耗 高/低 | 6 个象限 |
| ⑤ **矩阵查找** | 策略 × 象限 → [action, ratio] | keep / increase / decrease / close / observe |

### 4.3 保护机制（按优先级）

| 优先级 | 机制 | 规则 |
|--------|------|------|
| 🔴 最高 | 冷启动保护 | 创建 < 48h 或转化 < 6 → 强制 observe |
| 🟠 高 | 赔付保护 | 转化 3-5 次 → 改为 observe，等积累到 6 次申请赔付 |
| 🟡 中 | 出价边界 | 截断到 [10, 10000] 分 |
| 🟢 低 | 振幅上限 | 单次调整 ≤ 15%；超过需拆阶梯执行（间隔 ≥ 2h） |

### 4.4 Multi-Agent 协作

```
presets.json 定义了 8 个 sub-agent：

main ──分派──▶ budget     ← 当前可用
         ├──▶ audience    ← 部分可用
         ├──▶ creative    ← 未就绪
         ├──▶ system_ops  ← 未就绪
         ├──▶ monitor     ← 未就绪
         └──▶ data_analyst← 部分可用

execute ←── 独立入口，不通过 main 调度
```

---

## 五、工具清单

### ad_api.py — 腾讯广告 API 封装（13 个工具）

| 工具 | API 端点 | 说明 |
|------|---------|------|
| `ad_create` | POST /adgroups/add | 创建广告 |
| `ad_update` | POST /adgroups/update | 更新广告（出价/状态） |
| `ad_batch_update_status` | POST /adgroups/update (batch) | 批量更新广告状态 |
| `ad_get_list` | GET /adgroups/get | 查询广告列表 |
| `ad_get_report` | GET /daily_reports/get | 广告报表 |
| `creative_create` | POST /dynamic_creatives/add | 创建动态创意 |
| `creative_get_list` | GET /dynamic_creatives/get | 查询创意列表 |
| `creative_update` | POST /dynamic_creatives/update | 更新创意 |
| `creative_get_report` | GET /daily_reports/get | 创意报表 |
| `asset_get_list` | GET /assets/get | 查询资产列表 |
| `audience_get_list` | GET /custom_audiences/get | 查询人群包 |
| `account_get_info` | GET /advertiser/get | 查询账户信息 |

### data_query.py — ODPS 数据查询（3 个工具）

| 工具 | 说明 |
|------|------|
| `data_query` | 通用 ODPS SQL 查询（含模板：creative_detail, account_summary, ad_detail 等） |
| `data_aggregate` | 数据聚合查询 |
| `get_ad_current_status` | 查询广告当前状态（出价/预算/定向） |

### budget_calc.py — 出价计算引擎（6 个工具）

| 工具 | 说明 |
|------|------|
| `get_ad_performance` | 拉取广告昨日效率数据 |
| `get_account_summary` | 拉取账户汇总数据 |
| `compute_budget_thresholds` | 计算分位数阈值（P70/P30/P50） |
| `classify_ads` | 2×2 象限分类（ROI × 消耗） |
| `compute_bid_adjustment` | 计算出价调整方案 |
| `bid_adjustment_execute` | 批量执行出价调整 |

---

## 六、配置说明

`config.py` 定义了三套 `RunConfig`：

| 配置 | 用途 | Temperature | Max Iterations |
|------|------|-------------|----------------|
| `MAIN_CONFIG` | 主分析 Agent | 0.3 | 50 |
| `BUDGET_CONFIG` | 预算/出价 sub-agent | 0.3 | 30 |
| `EXECUTE_CONFIG` | 执行 Agent | 0.1 | 50 |

工具白名单：

- `ANALYSIS_TOOLS`: 只读查询 + 计算工具（不含 ad_create/ad_update 等写操作）
- `EXECUTION_TOOLS`: 全量工具（含所有写操作）

---

## 七、关键设计原则

1. **策略外置**: 决策参数在 JSON 配置文件中，LLM 可运行时调整并版本化管理
2. **两段式执行**: 分析（run.py）与执行（run_execute.py）分离，中间有人工审批环节
3. **保护优先**: 冷启动 → 赔付 → 边界 → 振幅，四层保护从高到低依次生效
4. **用出价控制消耗**: oCPM 模式下通过 bid 调整影响 eCPM → 竞价胜率 → 消耗量，而非直接设 day_amount
5. **非线性认知**: 降价效果放大（-10% 出价 ≈ -15~25% 消耗），需警惕"掉量悬崖"