# auto_put_ad_mini — 广告智能调控 Agent

> **工作目录**: `examples/auto_put_ad_mini/`
> **业务场景**: 微信小程序投流
> **核心目标**: 基于 ROI + 跑量双维度，自动给出广告粒度的操作决策

## 项目定位

`auto_put_ad_mini` 是 `auto_put_ad` 终极体系中 **Monitor/调控 Agent** 的前身。
当前阶段独立运行，只做"数据→决策→执行"单向链路。

## 项目结构

```
examples/auto_put_ad_mini/
├── run.py                    # 运行入口（Agent 交互模式）
├── execute_once.py           # 单次执行入口（10 步 pipeline）
├── config.py                 # 业务配置（ROI 阈值、出价边界等）
├── presets.json              # 预设参数
├── strategy_params.json      # 策略参数
├── prompts/
│   └── system.prompt         # Agent 系统 Prompt
├── tools/
│   ├── ad_api.py             # 腾讯广告 API 封装
│   ├── ad_decision.py        # 广告决策引擎（候选信号 + LLM 评估）
│   ├── data_query.py         # ODPS 数据查询
│   ├── roi_calculator.py     # ROI 计算（动态ROI）
│   ├── guardrails.py         # 安全护栏
│   ├── execution_engine.py   # 执行引擎（API 调用 + 审计）
│   ├── im_approval.py        # 飞书审批（阻塞式轮询）
│   ├── report_generator.py   # 报告生成（Excel + 飞书表格）
│   ├── feishu_doc.py         # 飞书文档操作
│   ├── creative_metrics.py   # 创意级数据指标
│   ├── odps_module.py        # ODPS 数据源模块
│   ├── portfolio_metrics.py  # 组合级指标聚合
│   └── posterior_collector.py # 后验数据收集
├── skills/                   # 领域知识（框架自动注入）
│   ├── ad_domain.md          # 业务模型：裂变模型、ROI公式
│   ├── platform_rules.md     # 平台硬约束
│   ├── decision_framework.md # 决策框架：候选标记 + 年龄策略
│   ├── action_playbook.md    # 动作手册：7种action
│   └── posterior_wisdom.md   # 后验经验
└── outputs/                  # 运行输出
```

## 关键配置入口

- **决策阈值**（关停线、降价线、提价线）→ `config.py`
- **决策逻辑**（候选标记、年龄保护、权衡原则）→ `skills/*.md`
- **Agent行为**（工具编排、输出规范）→ `prompts/system.prompt`

业务规则以 `config.py` 和 `skills/` 为准，本文件不重复描述。

---

## 🚨 工程纪律:不推导,不猜测(2026-06-05 用户多次确认)

**绝对禁止凭"常识 / 文档框架 / 命名规律"推断或猜测字段值、枚举名、参数结构、业务规则。**

### 三段式处理原则

| 情况 | 必须做的 |
|---|---|
| **不确定** | 查询(读代码、读真实数据、读文档、调 API 反查) |
| **查不到** | 直接反问用户,**不要硬给一个"可能值"** |
| **要写代码** | 拿到确切答案后才下手 |

### 适用范围(全部)

- 腾讯广告 v3.0 API 字段名 / 枚举值 / 嵌套结构
- 业务配置项的默认值 / 取值策略
- 字段语义(比如"稳定拿量"= 哪个 enum?)
- 各种 ID(account_id、audience_pack_id、conversion_id、user_action_set_id...)
- LLM 推理框架的具体阈值
- 工作流的执行顺序

### 反例(过去犯过的错)

| 我猜测 | 实际值 | 教训 |
|---|---|---|
| `marketing_carrier_type=MINI_PROGRAM_WECHAT` | `JUMP_PAGE` | 凭文档常识猜,错 |
| `smart_bid_type=SYSTEMATIC`(稳定拿量) | `CUSTOM` + 配 `bid_strategy=AVERAGE_COST` + `auto_acquisition=True` 三件套 | 凭命名猜单字段,错 |
| `optimization_goal=PAGE_VIEW` | `PROMOTION_VIEW_KEY_PAGE` | 凭含义猜枚举名,错 |
| `auto_acquisition_enabled=False` | `True` | 凭"SOP 关闭智能"猜,错 |
| `daily_budget=20000`(200 元) | `0`(不限,由 auto_acquisition_budget 控) | 凭习惯猜,错 |

### 验证手段优先级

1. **拉真实数据反推**(最准):`/adgroups/get` 查已跑通的广告 JSON
2. **读现有代码**:`tools/ad_api.py` 中已封装的真实参数
3. **读官方文档**(WebFetch 可能失败/有总结失真,作为辅助参考)
4. **dry run 试错**(用 `configured_status=AD_STATUS_SUSPEND` 试创建,看腾讯报错)
5. **反问用户**

### 哪些 WebFetch 等"二手"信息要警惕

- 文档页面如果只返回标题/header → 内容无效,不能引用
- WebFetch 返回的"原文照搬"结果,可能是 AI 处理过的摘要,**字段类型 / 必填性 / 枚举值** 都可能被简化
- → 二手信息**只用于"知道有这字段"**,具体值必须从真实数据反推

**这条规则**比任何 plan / skill / config 都优先级高。