🚀 新人上手指南 — 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 环境准备

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 执行调控流程（最主要的功能）

cd examples/auto_put_ad_mini

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

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

2.3 执行创建流程

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

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

2.4 交互式模式（Agent 对话）

.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）

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 出价边界

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 做了什么决策"

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

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

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

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

7.3 "飞书审批没反应"

# 检查飞书 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 "想看某个广告为什么被标记为关停候选"

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

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

8. 工程约定（重要！）

8.1 不要猜测

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

正确做法：

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

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。

ONBOARDING.md 12 KB Historie Surový