# 🚀 新人上手指南 — auto_put_ad_mini

> **阅读时间**: 15 分钟
> **前提**: 已经有 GIT_CHANGELOG.md（项目根目录），建议先快速浏览它的目录了解演进历史
> **最后更新**: 2026-07-06

---

## 1. 这个项目是干什么的？

一句话：**基于 ROI 数据，自动判断腾讯广告该提价、降价还是关停，然后把决策发给运营审批，审批通过后自动执行。**

```
数据拉取 → ROI 计算 → 决策引擎 → 飞书审批 → API 执行
  (ODPS)    (Python)   (LLM+规则)   (飞书IM)    (腾讯广告API)
```

两个独立的业务线共享同一套代码库：

| 业务线 | 做什么 | 入口文件 |
|--------|--------|---------|
| **广告调控**（主） | 分析已投放广告的 ROI，决定是否提价/降价/关停 | `execute_once.py` |
| **广告创建**（副） | 给新账户自动创建广告 + 挂创意 | `execute_creation_once.py` |

---

## 2. 先跑起来

### 2.1 环境准备

```bash
cd /path/to/Agent

# 创建虚拟环境（只需要一次）
python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt
pip3 install -r examples/auto_put_ad_mini/requirements.txt

# 复制环境变量模板
cp .env.template .env
# 编辑 .env，填入必填的 API key（至少需要 TENCENT_AD_* 和 OPENROUTER_API_KEY）
```

### 2.2 执行调控流程（最主要的功能）

```bash
cd examples/auto_put_ad_mini

# 完整 10 步 pipeline（数据拉取 → 决策 → 审批 → 执行）
.venv/bin/python3 execute_once.py --date 20260705

# 常用参数：
#   --date YYYYMMDD   指定分析日期（默认昨天）
#   --dry-run         只分析不执行
#   --skip-approval   跳过飞书审批，直接执行
```

### 2.3 执行创建流程

```bash
# 单次创建（找缺创意的广告 → 召回素材 → 创建 → 审批 → 执行）
.venv/bin/python3 execute_creation_once.py --date 20260705

# 批量创建（给多个账户创建广告）
.venv/bin/python3 execute_creation_apply.py --date 20260705
```

### 2.4 交互式模式（Agent 对话）

```bash
.venv/bin/python3 run.py
# 进入对话，可以自然语言问"今天哪些广告需要调整？"
```

---

## 3. 核心文件速查

### 3.1 改了就能生效的文件（运营/产品可改）

| 文件 | 改什么 | 何时改 |
|------|--------|--------|
| `config.py` | ROI 阈值、出价边界、审批超时等参数 | 调策略参数 |
| `skills/*.md` | 决策规则、平台约束、后验经验 | 改业务规则 |
| `prompts/system.prompt` | LLM 行为、输出格式、执行顺序 | 调 Agent 行为 |
| `db/schema.sql` | 数据库表结构 | 加新表/新字段 |

### 3.2 代码文件（改了会改变行为）

| 文件 | 职责 | 代码量 |
|------|------|--------|
| `tools/ad_decision.py` | **决策引擎** — 候选标记 + LLM 评估 | 84KB（最大） |
| `tools/roi_calculator.py` | **ROI 计算** — 动态 ROI (7日均值)、人群包基线 | 25KB |
| `tools/im_approval.py` | **飞书审批** — 发消息 + 轮询回复 + Excel 附件 | 53KB |
| `tools/execution_engine.py` | **执行引擎** — 调腾讯 API + 审计日志 | 40KB |
| `tools/guardrails.py` | **安全护栏** — 频率/边界/方向检查 | 37KB |
| `tools/ad_api.py` | **腾讯 API 封装** — GET/POST 统一入口 | 31KB |
| `tools/data_query.py` | **数据拉取** — ODPS 查询 + 合并 | 23KB |
| `tools/creative_creation.py` | **创意创建** — POST /dynamic_creatives/add | 37KB |
| `tools/material_recall.py` | **素材召回** — batchByText + 评分排序 | 24KB |
| `tools/creative_review.py` | **创意审核** — 扫描审核结果 | 21KB |

### 3.3 业务知识（Skills，LLM 自动加载）

| 文件 | 内容 |
|------|------|
| `skills/ad_domain.md` | 裂变模型、R 值、ROI 公式、数据字段定义 |
| `skills/platform_rules.md` | 腾讯平台硬约束（oCPM 学习期、调价上限 30% 等） |
| `skills/decision_strategy.md` | 决策框架：5 种候选标记、三级年龄保护、7 种 action |
| `skills/posterior_wisdom.md` | 后验经验入口（生产后动态补充） |

---

## 4. 决策流程详解（最重要的一节）

### 4.1 10 步 Pipeline

```
Step 0: 同步广告状态     — sync_ad_status.py（从腾讯 API 拉最新状态）
Step 1: 拉取创意数据     — fetch_creative_data（ODPS）
Step 2: 合并创意数据     — merge_creative_data
Step 3: 计算 ROI 指标    — calculate_roi_metrics（动态 ROI (7日均值)）
Step 4: 计算人群包基线   — calculate_portfolio_summary（各人群包的 P50 等）
Step 5: 获取待评估广告   — get_ads_for_review（年龄保护 + 候选标记）
Step 6: LLM 决策         — 主 Agent 调用（规则标记 + LLM 判断）
Step 7: 应用决策         — apply_decisions（合并 metrics 字段 + 护栏检查）
Step 8: 生成报告         — generate_report（Excel + CSV）
Step 9: 飞书审批 + 执行  — send_approval_request → 等回复 → execute_decisions
```

### 4.2 决策的三层架构

```
┌─────────────────────────────┐
│  第1层：规则引擎（硬约束）     │  ← Python 代码，不做 LLM 调用
│  - 年龄保护（≤3天不评估）     │
│  - 零消耗识别（自动关停候选）  │
│  - 候选信号计算               │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│  第2层：LLM 智能评估          │  ← Claude Sonnet 4.5
│  - 多维度推理（ROI+裂变+CTR） │
│  - 输出 action + reason       │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│  第3层：护栏兜底检查          │  ← Python 代码，LLM 输出后执行
│  - 方向一致性（bid_down必须<0）│
│  - 频率限制（同广告6h内不重复）│
│  - 边界检查（出价下限0.05元）  │
└─────────────────────────────┘
```

### 4.3 7 种决策类型

| Action | 含义 | 是否调用 API | 审批要求 |
|--------|------|:----------:|:------:|
| `pause` | 暂停广告 | ✅ | 必须审批 |
| `bid_down` | 降价 3%-5% | ✅ | 必须审批 |
| `bid_up` | 提价 5%-10% | ✅ | 自动执行 |
| `scale_up` | 建议扩量 | ❌ | 参考信息 |
| `creative_adjust` | 建议换素材 | ❌ | 参考信息 |
| `observe` | 观察等待 | ❌ | 参考信息 |
| `hold` | 保持不变 | ❌ | 不展示 |

### 4.4 核心概念：动态 ROI (7日均值)

```
对每一天（日消耗 ≥ 100 元才参与计算）：
  裂变收益率 = T0裂变数 × arpu / 当日消耗
  回流倍数   = 总回流人数 / 首层打开数

7 日滚动均值（至少 3 天合格数据）：
  裂变效率稳定因子 = 回流倍数_7日均值 / T0裂变系数_7日均值

动态 ROI (7日均值) = 当日裂变收益率 × 裂变效率稳定因子
```

**决策时用"动态 ROI (7日均值) 均值"（多天的均值），而非单日值。**

---

## 5. 数据流

### 5.1 数据来源

```
ODPS（阿里 MaxCompute）
  ↓ fetch_creative_data
CSV 文件 → outputs/raw/creative_raw_{date}.csv
  ↓ merge_creative_data
合并后 CSV → outputs/raw/creative_merged_{date}.csv
  ↓ calculate_roi_metrics
Metrics CSV → outputs/metrics_{date}.csv
  ↓ get_ads_for_review + LLM
Decisions CSV → outputs/reports/decisions_{date}.csv
  ↓ generate_report
审批 Excel → outputs/reports/approval_table_{date}.xlsx
```

### 5.2 数据库

MySQL（`db/schema.sql`）存储：
- `account_whitelist` — 账户白名单 + feedback_id + 用户 token
- `ad_creation_account_config` — 广告创建配置（人群包、出价区间等）
- `ad_delivery_template` — 投放模板（版位、地域、时段等）
- `creative_creation_task` — 创意创建任务记录
- `creative_review_result` — 创意审核结果
- `creative_rejection_fact` — 审核拒绝原因
- `creative_material_usage` — 素材使用记录（7 天去重）
- `adjustment_history` — 调价历史（护栏用）

---

## 6. 关键配置项

### 6.1 决策阈值（config.py）

```python
ROI_LOW_FACTOR = 0.75        # 动态ROI < 渠道P50×0.75 → 关停
BID_DOWN_ROI_FACTOR = 0.90   # 动态ROI < 渠道P50×0.90 → 降价
BID_UP_ROI_FACTOR = 1.05     # 动态ROI > 渠道P50×1.05 → 提价
COLD_START_DAYS = 3          # ≤3天冷启动（完全不干预）
EARLY_GROWTH_DAYS = 7        # 4-7天早期成长（只能提价）
```

### 6.2 出价边界

```python
BID_FLOOR_YUAN = 0.05        # 出价下限（分）
BID_CEILING_YUAN = 1.00      # 出价上限（元）
BID_UP_MIN_PCT = 0.05        # 提价最小 5%
BID_UP_MAX_PCT = 0.10        # 提价最大 10%
BID_DOWN_MIN_PCT = 0.03      # 降价最小 3%
BID_DOWN_MAX_PCT = 0.05      # 降价最大 5%
```

### 6.3 环境变量（.env）

必需的环境变量（至少本地开发）：`OPENROUTER_API_KEY`、数据库连接信息（`DB_HOST` 等）、腾讯广告 API 的 `TENCENT_AD_*` 系列。

完整列表见 `.env.example`。

---

## 7. 常见调试场景

### 7.1 "我想看看今天 LLM 做了什么决策"

```bash
# 查看 decisions CSV
cat outputs/reports/decisions_20260706.csv | head -20

# 查看日志
grep "LLM" outputs/decision_log_20260706.log
```

### 7.2 "决策不对，我想改规则"

1. 如果是**参数值不对** → 改 `config.py` 中的阈值
2. 如果是**判断逻辑不对** → 改 `skills/decision_strategy.md`（改 LLM 的推理指导）
3. 如果是**硬约束不对** → 改 `tools/guardrails.py` 或 `tools/ad_decision.py`

### 7.3 "飞书审批没反应"

```bash
# 检查飞书 token 是否有效
.venv/bin/python3 -c "
from examples.auto_put_ad_mini.tools.im_approval import _get_tenant_access_token
print(_get_tenant_access_token()[:20])
"

# 手动发一条测试消息
.venv/bin/python3 test_chat_send.py
```

### 7.4 "想看某个广告为什么被标记为关停候选"

```bash
# 找到对应日期的 metrics CSV
grep "广告ID" outputs/metrics_20260706.csv

# 检查年龄保护逻辑是否生效
grep "年龄保护" outputs/decision_log_20260706.log
```

---

## 8. 工程约定（重要！）

### 8.1 不要猜测

项目 CLAUDE.md 中明确规定：**禁止凭"常识 / 文档框架 / 命名规律"推断腾讯 API 的字段名、枚举值、参数结构。**

正确做法：
1. 拉真实数据反推（`/adgroups/get` 查已跑通的广告 JSON）
2. 读现有代码（`tools/ad_api.py` 中已封装参数）
3. 反问用户

### 8.2 Git 规范

- **不自动 commit / push** — 等用户明确说
- Commit message: `feat(xxx): ...` / `fix(xxx): ...` 一行标题，不加 `Co-Authored-By` / `Generated with`
- 不修改 `agent/` 目录（框架源码）

### 8.3 Python 环境

- 始终用 `.venv/bin/python3` 执行脚本
- 用 `pip3` 安装依赖
- 数据库配置优先从环境变量读取

---

## 9. 相关文档索引

| 文档 | 位置 | 内容 |
|------|------|------|
| 完整变更日志 | `../../GIT_CHANGELOG.md` | 77 个 commit 的详细变更记录 |
| 架构文档 | `ARCHITECTURE.html` | 可视化架构图 |
| 新模块架构 | `ARCHITECTURE_NEW_MODULES.html` | 创建模块架构 |
| 生产自动化 | `PRODUCTION_AUTOMATION.md` | 生产环境部署说明 |
| 部署指南 | `DEPLOYMENT.md` | Docker + K8s 部署 |
| 调度指南 | `SCHEDULER_GUIDE.md` | CronJob 配置 |
| K8s 配置 | `k8s/` | deployment、cronjob、secret 等 |
| 审批流更新 | `APPROVAL_FLOW_UPDATE.md` | 审批协议变更记录 |

---

## 10. 快速问答

**Q: 改了个 config.py 参数，要重启什么？**
A: 如果是 cronjob 模式，等下次 cron 触发自动生效。如果是手动执行，直接重新 `python3 execute_once.py`。

**Q: 如何在本地测试而不调真实 API？**
A: 设置 `DRY_RUN_MODE=True` 在 config.py 中，或者用 `--dry-run` 参数。

**Q: auto_put_ad 和 auto_put_ad_mini 的关系？**
A: `auto_put_ad` 是多 Agent 架构的 Budget Domain（预算分配），是独立系统。`auto_put_ad_mini` 是单 Agent 的广告调控系统，当前分支的主力项目。两者共享 `auto_put_ad/tools/ad_api.py` 的腾讯 API 封装。

**Q: 创建模块的代码在哪？**
A: 在 `auto_put_ad_mini/tools/` 下，以 `ad_creation.py`、`creative_creation.py`、`material_recall.py` 等命名。入口是 `execute_creation_once.py` 和 `execute_creation_apply.py`。