|
|
@@ -1,23 +1,25 @@
|
|
|
# auto_put_ad_mini — 项目结构文档
|
|
|
|
|
|
> **定位**: 微信小程序投流 — 面向 ROI 的广告粒度自动调控 + 自动创建投放系统
|
|
|
-> **最后更新**: 2026-07-16
|
|
|
+> **最后更新**: 2026-07-27
|
|
|
|
|
|
---
|
|
|
|
|
|
## 一、项目概述
|
|
|
|
|
|
-`auto_put_ad_mini` 是腾讯广告自动化投放系统的**核心业务单元**，专注微信小程序投流场景（`MARKETING_CARRIER_TYPE_MINI_PROGRAM_WECHAT`）。
|
|
|
+`auto_put_ad_mini` 是腾讯广告自动化投放系统的**核心生产单元**，专注微信小程序投流场景（`MARKETING_CARRIER_TYPE_MINI_PROGRAM_WECHAT`）。
|
|
|
|
|
|
-项目已从最初的"数据→决策→执行"单向链路，演进出**两条独立但共存的生产线**：
|
|
|
+项目包含**三条独立但协同的生产线**：
|
|
|
|
|
|
| 业务线 | 入口 | 频率 | 职责 |
|
|
|
|--------|------|------|------|
|
|
|
-| **Flow A: 决策调控** | `execute_once.py` | 每日 1 次 (UTC 02:00) | 分析 ROI + 跑量数据 → LLM 推理 → 出价调整/暂停广告 |
|
|
|
-| **Flow B: 创建投放** | `execute_creation_once.py` | 每日 1 次 (UTC 02:30) | 创建新广告 + 准备动态创意 → 提交腾讯审核 |
|
|
|
-| **Flow C: 审核扫描** | `scan_creative_reviews.py` | 每 2 小时 | 扫描创意审核结果 → 记录拒审事实 |
|
|
|
+| **Flow A: 决策调控** | `execute_once.py` | 每日 1 次 | Agent 驱动：LLM 动态编排工具调用 → ROI 分析 → 出价调整/暂停广告 |
|
|
|
+| **Flow B: 创建投放** | `execute_creation_once.py` | 每日 1 次 | 硬编码 Pipeline：创建广告 → 准备创意 → 飞书审批 → 提交腾讯 |
|
|
|
+| **Flow C: 审核扫描** | `scan_creative_reviews.py` | 每 2 小时 | 硬编码循环：扫描创意审核结果 → 记录拒审事实 |
|
|
|
|
|
|
-**核心决策架构**: 规则标记候选（Python）→ LLM 综合判断（Claude Sonnet 4.5）→ 护栏兜底（Python），三层递进。
|
|
|
+**两种执行模式**：
|
|
|
+- **Flow A**：Agent 驱动 — `execute_once.py` 通过 Agent 框架启动 LLM，由 LLM 动态决定调用哪些工具、以何种顺序执行。system prompt 中嵌入了推荐的执行流程，但实际编排权在模型。
|
|
|
+- **Flow B / C**：确定性 Pipeline — `execute_creation_once.py` 和 `scan_creative_reviews.py` 是硬编码的多阶段脚本，不经过 LLM 编排。
|
|
|
|
|
|
---
|
|
|
|
|
|
@@ -27,8 +29,9 @@
|
|
|
examples/auto_put_ad_mini/
|
|
|
│
|
|
|
├── 🔵 核心入口
|
|
|
-│ ├── run.py # 交互式 Agent REPL
|
|
|
-│ ├── execute_once.py # Flow A 主入口：决策调控（10 步 pipeline）
|
|
|
+│ ├── run.py # 交互式 Agent REPL（开发调试）
|
|
|
+│ ├── execute_once.py # Flow A 主入口：Agent 驱动决策调控
|
|
|
+│ ├── execute_once_test.py # Flow A 无审批模式（发审批但不阻塞等待，跳过执行）
|
|
|
│ ├── execute_creation_once.py # Flow B 主入口：创建投放（Module A + B）
|
|
|
│ ├── execute_creation_apply.py # Flow B Phase 3：独立提交创意到腾讯
|
|
|
│ ├── run_full_analysis.py # 仅数据准备步骤（无 LLM，用于调试）
|
|
|
@@ -36,232 +39,324 @@ examples/auto_put_ad_mini/
|
|
|
│ └── merge_data.py # 独立数据合并脚本
|
|
|
│
|
|
|
├── 🟢 生产服务
|
|
|
-│ ├── server.py # FastAPI + APScheduler 生产服务器
|
|
|
+│ ├── run_daily_service.py # ★ 生产日级服务入口（APScheduler，Flow B + C）
|
|
|
+│ ├── run_daily_roi.py # 独立日级 ROI 计算 + 飞书审批（可版本化运行）
|
|
|
+│ ├── server.py # 旧版生产服务器（FastAPI + APScheduler，仅 Flow A）
|
|
|
│ ├── schedule.sh # Shell Cron 包装脚本
|
|
|
-│ ├── k8s/ # Kubernetes 部署清单
|
|
|
-│ │ ├── deployment.yaml # Deployment 模式（APScheduler）
|
|
|
-│ │ ├── cronjob.yaml # Flow A CronJob
|
|
|
-│ │ ├── cronjob_creation.yaml # Flow B CronJob
|
|
|
-│ │ ├── cronjob_creative_review.yaml # Flow C CronJob
|
|
|
-│ │ ├── configmap.yaml / secret.yaml / pvc.yaml
|
|
|
-│ │ └── namespace.yaml / network-policy.yaml
|
|
|
-│ └── .env / .env.example # 环境变量
|
|
|
+│ ├── .env.example # 环境变量声明模板
|
|
|
+│ └── requirements.txt # 项目专属 Python 依赖
|
|
|
│
|
|
|
├── 🟡 配置与技能
|
|
|
-│ ├── config.py # 核心业务配置（~1023 行）
|
|
|
-│ ├── presets.json # 预设参数
|
|
|
+│ ├── config.py # 核心业务配置（~1073 行）
|
|
|
+│ ├── presets.json # Agent 预设参数
|
|
|
│ ├── strategy_params.json # 策略参数
|
|
|
│ ├── whitelist.json # 账户白名单（可被 DB 覆盖）
|
|
|
+│ ├── configs/
|
|
|
+│ │ └── material_creative_patterns_seed.json # 素材创意范式种子数据
|
|
|
│ ├── prompts/
|
|
|
-│ │ └── system.prompt # Agent 系统提示词
|
|
|
-│ └── skills/ # 领域知识（注入 LLM 上下文）
|
|
|
-│ ├── ad_domain.md # 裂变模型 / R 值 / ROI 公式
|
|
|
-│ ├── decision_strategy.md # 决策框架 / 候选标记 / 7 种 action
|
|
|
-│ ├── platform_rules.md # 腾讯平台硬约束
|
|
|
+│ │ ├── system.prompt # Flow A Agent 系统提示词（嵌入推荐执行流程）
|
|
|
+│ │ ├── ai_cover_copy.md # AI 封面文案生成 Prompt
|
|
|
+│ │ ├── ai_generated_material.md # AI 素材生成 Prompt
|
|
|
+│ │ ├── ai_pattern_selector.md # AI 创意范式选择 Prompt
|
|
|
+│ │ └── ai_sanitize_video_description.md # 视频描述清洗 Prompt
|
|
|
+│ └── skills/ # 领域知识（注入 Agent system prompt）
|
|
|
+│ ├── ad_domain.md # 裂变模型 / R 值 / 动态 ROI 公式
|
|
|
+│ ├── decision_strategy.md # 决策框架 / 候选标记 / 7 种 action / 权衡原则
|
|
|
+│ ├── platform_rules.md # 腾讯平台硬约束（oCPM 学习期 / API 限制）
|
|
|
│ └── posterior_wisdom.md # 后验经验积累
|
|
|
│
|
|
|
├── 🟣 数据库层
|
|
|
│ └── db/
|
|
|
│ ├── __init__.py # 公开 API
|
|
|
-│ ├── connection.py # MySQL 连接（pymysql）
|
|
|
+│ ├── connection.py # MySQL 连接（pymysql + 连接池）
|
|
|
│ ├── config.py # 系统配置 + 白名单 CRUD（5 分钟缓存）
|
|
|
│ └── schema.sql # 12 张表 + 默认种子数据
|
|
|
│
|
|
|
-├── 🟠 工具层（31 个文件）
|
|
|
+├── 🟠 工具层（35 个文件，含 `__init__.py`）
|
|
|
│ └── tools/
|
|
|
+│ ├── __init__.py # 包初始化
|
|
|
│ ├── _names.py # 字段名常量 + 禁止词黑名单
|
|
|
-│ ├── ad_api.py # 腾讯广告 API v3.0 封装
|
|
|
+│ │
|
|
|
+│ ├── ── 腾讯 API + 数据层 ──
|
|
|
+│ ├── ad_api.py # 腾讯广告 API v3.0 封装（读写统一入口）
|
|
|
│ ├── odps_module.py # ODPS 数据源模块
|
|
|
-│ ├── data_query.py # ODPS 数据拉取 + 合并
|
|
|
+│ ├── data_query.py # ODPS + Reporting API 数据拉取与合并
|
|
|
│ │
|
|
|
-│ ├── ── Flow A 核心 ──
|
|
|
-│ ├── roi_calculator.py # 动态 ROI (7日均值) 计算器
|
|
|
-│ ├── portfolio_metrics.py # 人群包级汇总（tier P50 等）
|
|
|
-│ ├── creative_roi_calculator.py # 创意级动态 ROI
|
|
|
-│ ├── ad_decision.py # 决策引擎（候选标记 + 三级分类）
|
|
|
-│ ├── guardrails.py # 护栏验证（频率/边界/方向）
|
|
|
+│ ├── ── Flow A：决策调控 ──
|
|
|
+│ ├── roi_calculator.py # 动态 ROI（7日均值）计算器
|
|
|
+│ ├── creative_roi_calculator.py # 创意级动态 ROI（pause 候选二次细化依据）
|
|
|
+│ ├── portfolio_metrics.py # 人群包级汇总（P25/P50/P75）
|
|
|
+│ ├── ad_decision.py # 决策引擎（候选标记 + 三级分类 + LLM 评估）
|
|
|
+│ ├── guardrails.py # 护栏验证（频率 / 边界 / 方向 / 兜底）
|
|
|
│ ├── execution_engine.py # 执行引擎（API 调用 + 审计日志）
|
|
|
-│ ├── im_approval.py # 飞书审批（发送 + 轮询回复）
|
|
|
-│ ├── report_generator.py # 报告生成（Excel + CSV）
|
|
|
+│ ├── im_approval.py # 飞书审批（Flow A：发送 + 阻塞轮询回复）
|
|
|
+│ ├── report_generator.py # 报告生成（Excel + CSV + 飞书表格）
|
|
|
│ ├── posterior_collector.py # 后验数据采集
|
|
|
│ └── feishu_doc.py # 飞书文档操作
|
|
|
│ │
|
|
|
-│ ├── ── Flow B 核心 ──
|
|
|
-│ ├── ad_creation.py # Module A：广告创建
|
|
|
-│ ├── creative_creation.py # Module B：创意准备
|
|
|
-│ ├── creative_material_usage.py # 素材使用追踪
|
|
|
+│ ├── ── Flow B：创建投放 ──
|
|
|
+│ ├── ad_creation.py # Module A：广告创建（指纹去重 + 候选枚举）
|
|
|
+│ ├── creative_creation.py # Module B：创意准备（素材召回 → 落地页 → 候选）
|
|
|
+│ ├── creative_material_usage.py # 素材使用追踪（7 日去重）
|
|
|
│ ├── creative_metrics.py # 创意级指标
|
|
|
-│ ├── creative_review.py # 创意审核结果扫描
|
|
|
-│ ├── material_recall.py # 素材召回（batchByText）
|
|
|
+│ ├── creative_review.py # 创意审核结果扫描（Flow C 核心逻辑）
|
|
|
+│ ├── material_recall.py # 素材召回（batchByText，sim ≥ 0.8）
|
|
|
│ ├── video_recall.py # 视频内容列表获取
|
|
|
│ ├── video_risk.py # 视频风险标签检查
|
|
|
-│ ├── video_feature_query.py # 视频元素特征查询
|
|
|
+│ ├── video_feature_query.py # 视频元素特征查询（ODPS 贡献度分析）
|
|
|
│ ├── landing_plan.py # 落地页方案创建（xcx/save）
|
|
|
│ ├── scene_spec.py # 场景规格 / 微信版位
|
|
|
│ ├── audience_grant.py # 人群包授权验证
|
|
|
-│ ├── im_approval_ad_creation.py # 广告创建审批
|
|
|
+│ ├── im_approval_ad_creation.py # 广告创建审批（飞书 Sheet + 轮询）
|
|
|
│ ├── im_approval_creation.py # 创意创建审批
|
|
|
│ └── sls_setup.py # SLS 日志上报
|
|
|
+│ │
|
|
|
+│ ├── ── Flow B：AI 素材 ──
|
|
|
+│ ├── account_material_strategy.py # 账户级素材来源策略（历史 / AI 生成）
|
|
|
+│ ├── ai_generated_material.py # AI 生成创意图片素材（LiblibAI 等）
|
|
|
+│ ├── ai_material_review.py # AI 生成素材审核（Gemini Flash）
|
|
|
+│ └── material_strategy_learning.py # 素材策略学习持久化（高消耗快照 + 标注）
|
|
|
+│ │
|
|
|
+│ └── ── 投放配置 ──
|
|
|
+│ └── delivery_config.py # 投放配置解析（出价模式 / 版位 / 地域）
|
|
|
│
|
|
|
-├── 🔴 辅助脚本
|
|
|
+├── 🔴 辅助脚本与工具
|
|
|
+│ ├── metrics.py # Prometheus 指标导出（可选，需 prometheus-client）
|
|
|
│ ├── sync_ad_status.py # 同步已删除广告状态
|
|
|
│ ├── sync_feishu_account_config.py # 同步飞书账户配置到 DB
|
|
|
-│ ├── scan_creative_reviews.py # Flow C 入口
|
|
|
+│ ├── scan_creative_reviews.py # Flow C 入口（独立的 2h 循环脚本）
|
|
|
│ ├── configure_creation_accounts.py # 批量写入账户三元组配置
|
|
|
+│ ├── seed_material_creative_patterns.py # 素材创意范式种子数据导入
|
|
|
+│ ├── import_material_strategy_learning.py # 素材策略学习数据导入
|
|
|
│ ├── quick_analysis.py # 快速分析（使用已有数据）
|
|
|
│ ├── regenerate_metrics.py # 从已有 CSV 重新生成指标
|
|
|
│ ├── analyze_snapshot.py # 决策质量分析（9 维度评估）
|
|
|
│ ├── analyze_dimensions.py # 维度使用率分析
|
|
|
│ ├── verify_decision.py # 决策验证
|
|
|
+│ ├── run_decision_test.py # 决策引擎单元测试（绕过 Agent，直接测 ad_decision）
|
|
|
│ └── get_chat_id.py # 获取飞书群聊 ID
|
|
|
│
|
|
|
-├── 📁 数据与文档
|
|
|
-│ ├── data/tencent_constants/ # 静态参考数据
|
|
|
-│ ├── shared/reports/ # 共享报告产物
|
|
|
-│ ├── utils/log_capture.py # 日志捕获
|
|
|
-│ ├── docs/ # 分析文档
|
|
|
-│ │ ├── strategy_review_2026-04-16.md # 专家级策略 Review
|
|
|
-│ │ └── 不走LLM的规则盘点.md # 绕过 LLM 的规则清单
|
|
|
-│ └── doc/ # 设计文档
|
|
|
+├── 🐛 调试脚本
|
|
|
+│ ├── debug_generate_ai_material.py # AI 素材生成调试
|
|
|
+│ └── debug_select_creative_patterns.py # 创意范式选择调试
|
|
|
+│
|
|
|
+├── 🧪 测试文件（22 个）
|
|
|
+│ ├── test_e2e_full_flow.py # 端到端全流程测试
|
|
|
+│ ├── test_approval_flow_e2e.py # 审批流程端到端测试
|
|
|
+│ ├── test_real_approval_flow.py # 真实审批流程测试
|
|
|
+│ ├── test_single_ad.py # 单广告测试
|
|
|
+│ ├── test_tencent_api.py # API 连通性测试
|
|
|
+│ ├── test_creative_review_scan.py # 创意审核扫描测试
|
|
|
+│ ├── test_ai_generated_materials.py # AI 素材生成测试
|
|
|
+│ ├── test_hot_video_feature_enrichment.py # 热门视频特征增强测试
|
|
|
+│ ├── test_landing_video_dedupe.py # 落地视频去重测试
|
|
|
+│ ├── test_video_recall_pagination.py # 视频召回分页测试
|
|
|
+│ ├── test_compute_signal_scores.py # 信号分数计算测试
|
|
|
+│ ├── test_ad_creation_status.py # 广告创建状态测试
|
|
|
+│ ├── test_feishu_approval.py # 飞书审批测试
|
|
|
+│ ├── test_feishu_import.py # 飞书数据导入测试
|
|
|
+│ ├── test_im_approval_creation.py # IM 审批创建测试
|
|
|
+│ ├── test_approval_replay.py # 审批回放测试
|
|
|
+│ ├── test_chat_send.py # 飞书消息发送测试
|
|
|
+│ ├── test_send_with_sheet.py # 飞书 Sheet 发送测试
|
|
|
+│ ├── test_send_with_sheet_simple.py # 飞书 Sheet 简化测试
|
|
|
+│ ├── test_strategy_upgrade.py # 策略升级测试
|
|
|
+│ ├── test_api_simple.py # API 简单连通性测试
|
|
|
+│ └── test_analysis_0415.py # 0415 分析验证
|
|
|
+│
|
|
|
+├── 📁 K8s 部署清单
|
|
|
+│ └── k8s/
|
|
|
+│ ├── deployment.yaml # Deployment 模式（APScheduler）
|
|
|
+│ ├── cronjob.yaml # Flow A CronJob
|
|
|
+│ ├── cronjob_creation.yaml # Flow B CronJob
|
|
|
+│ ├── cronjob_creative_review.yaml # Flow C CronJob
|
|
|
+│ ├── configmap.yaml
|
|
|
+│ ├── secret.yaml
|
|
|
+│ ├── pvc.yaml
|
|
|
+│ ├── namespace.yaml
|
|
|
+│ └── network-policy.yaml
|
|
|
│
|
|
|
-└── 🧪 测试文件（~25 个）
|
|
|
- ├── test_e2e_full_flow.py # 端到端全流程测试
|
|
|
- ├── test_approval_flow_e2e.py # 审批流程端到端测试
|
|
|
- ├── test_real_approval_flow.py # 真实审批流程测试
|
|
|
- ├── test_single_ad.py # 单广告测试
|
|
|
- ├── test_tencent_api.py # API 连通性测试
|
|
|
- └── ...（其余 20+ 个专项测试）
|
|
|
+├── 📁 数据与工具
|
|
|
+│ ├── data/tencent_constants/
|
|
|
+│ │ └── regions_sop_current.json # SOP 地域参考数据
|
|
|
+│ ├── shared/reports/ # 共享分析报告（20260427 样本数据）
|
|
|
+│ └── utils/log_capture.py # 日志捕获
|
|
|
+│
|
|
|
+└── 📚 文档
|
|
|
+ ├── PROJECT_STRUCTURE.md # ★ 本文档
|
|
|
+ ├── CLAUDE.md # 项目级 Claude 开发指南 + 工程纪律
|
|
|
+ ├── ONBOARDING.md # 新人上手文档
|
|
|
+ ├── DEPLOYMENT.md # 部署指南
|
|
|
+ ├── PRODUCTION_AUTOMATION.md # 生产自动化说明
|
|
|
+ ├── SCHEDULER_GUIDE.md # 调度器使用指南
|
|
|
+ ├── APPROVAL_FLOW_UPDATE.md # 审批流程更新说明
|
|
|
+ ├── CREATIVE_CREATION_TODO.md # 创意创建待办
|
|
|
+ ├── TEST_RESULT.md # 测试结果
|
|
|
+ ├── DOCKER_TEST.md # Docker 测试指南
|
|
|
+ ├── test_db_summary.md # DB 测试汇总
|
|
|
+ ├── doc/
|
|
|
+ │ └── skill_refactor_plan_20260422.md # Skill 重构方案
|
|
|
+ └── docs/
|
|
|
+ ├── ad_automation_platform_architecture_plan_2026-07-25.md # 统一平台架构方案
|
|
|
+ ├── unified_services_deployment.md # 统一服务部署方案
|
|
|
+ ├── ai_material_strategy_plan_2026-07-07.md # AI 素材策略方案
|
|
|
+ ├── material_strategy_learning_db_design_2026-07-08.md # 素材策略学习 DB 设计
|
|
|
+ ├── strategy_review_2026-04-16.md # 专家级策略 Review
|
|
|
+ └── 不走LLM的规则盘点.md # 绕过 LLM 的规则清单
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 三、Flow A: 决策调控流程（execute_once.py）
|
|
|
+## 三、Flow A: 决策调控（execute_once.py）
|
|
|
+
|
|
|
+### 3.1 执行模型：Agent 驱动，非硬编码 Pipeline
|
|
|
+
|
|
|
+> **关键认知**：`execute_once.py` **不是**一个步骤固定的脚本。它启动一个 Agent（`AgentRunner`），将控制权交给 LLM。LLM 读取 system prompt 中嵌入的推荐流程，**动态决定**调用哪些工具、以何种顺序调用。
|
|
|
|
|
|
-### 3.1 10 步 Pipeline
|
|
|
+实际运行时，LLM 通常会按以下顺序调用工具（顺序由 system prompt 中的推荐流程引导，但 LLM 可以跳过、重排或插入中间步骤）：
|
|
|
|
|
|
```
|
|
|
-Step 0: sync_ad_status ← 同步腾讯侧已删除的广告状态
|
|
|
- │
|
|
|
-Step 1: fetch_creative_data ← ODPS 拉创意原始数据 + 广告状态快照
|
|
|
- │ 输出: outputs/raw/creative_{date}.csv
|
|
|
- │ outputs/ad_status/ad_status_{date}.csv
|
|
|
-Step 2: merge_creative_data ← 合并创意数据 + 广告状态
|
|
|
- │ 输出: outputs/merged/
|
|
|
- │
|
|
|
-Step 3: calculate_roi_metrics ← 计算动态 ROI (7日均值)
|
|
|
- │ 输出: outputs/metrics/metrics_{date}.csv
|
|
|
+用户消息："分析广告，执行完整的ROI计算和决策流程"
|
|
|
│
|
|
|
-Step 3.5: calculate_creative_roi ← 创意级动态 ROI（pause 候选的二次细化依据）
|
|
|
- │
|
|
|
-Step 4: calculate_portfolio_summary ← 人群包级汇总 (tier P25/P50/P75)
|
|
|
- │
|
|
|
-Step 5: get_ads_for_review ← 三级分类 + 5 个候选标记计算
|
|
|
- │ ├── 零消耗待关停 (规则)
|
|
|
- │ ├── 待优化评估 (LLM)
|
|
|
- │ └── 正常运行 (规则)
|
|
|
- │
|
|
|
-Step 6: [LLM 决策] ← Claude Sonnet 4.5 综合推理
|
|
|
- │ 注入 skills/*.md 领域知识
|
|
|
- │ 输出: 每个广告的 action + reason
|
|
|
- │
|
|
|
-Step 7: apply_decisions ← 保存决策 + 合并 metrics 字段
|
|
|
- │ 输出: outputs/reports/llm_decisions_{date}.csv
|
|
|
- │
|
|
|
-Step 8: generate_report ← 生成 Excel + CSV 报告
|
|
|
- │
|
|
|
-Step 9: send_approval_request ← 飞书 IM 审批（发送 + 阻塞等待回复）
|
|
|
- │ 含 Excel 附件 + 统计摘要
|
|
|
- │
|
|
|
-Step 9.5: check_approval_status ← 轮询审批状态（超时 120 分钟）
|
|
|
- │
|
|
|
-Step 10: execute_decisions ← 执行审批通过的决策
|
|
|
- 调用 execution_engine → ad_api
|
|
|
- 写入 audit JSONL 日志
|
|
|
+ ▼
|
|
|
+┌─ Agent Loop（LLM 动态编排）────────────────────────────────────────┐
|
|
|
+│ │
|
|
|
+│ ① fetch_creative_data ODPS 拉创意数据 + 广告状态快照 │
|
|
|
+│ → outputs/raw/creative_{date}.csv │
|
|
|
+│ → outputs/ad_status/ad_status_{date}.csv│
|
|
|
+│ │
|
|
|
+│ ② merge_creative_data 合并（LLM 可能自动调用，也可能跳过） │
|
|
|
+│ │
|
|
|
+│ ③ calculate_roi_metrics 计算动态 ROI（7日均值） │
|
|
|
+│ → outputs/metrics/metrics_{date}.csv │
|
|
|
+│ │
|
|
|
+│ ④ calculate_creative_roi 创意级动态 ROI（pause 二次细化依据） │
|
|
|
+│ │
|
|
|
+│ ⑤ calculate_portfolio_summary 人群包级汇总（P25/P50/P75） │
|
|
|
+│ │
|
|
|
+│ ⑥ get_ads_for_review 三级分类 + 候选标记 │
|
|
|
+│ ├── 零消耗待关停（规则直达） │
|
|
|
+│ ├── 待优化评估（进入 LLM 推理） │
|
|
|
+│ └── 正常运行（跳过） │
|
|
|
+│ │
|
|
|
+│ ⑦ [LLM 推理] Agent 自身对候选广告做综合判断 │
|
|
|
+│ 注入 skills/*.md 领域知识 │
|
|
|
+│ 输出: action + reason │
|
|
|
+│ │
|
|
|
+│ ⑧ apply_decisions 保存决策 + 合并 metrics 字段 │
|
|
|
+│ → outputs/reports/llm_decisions_{date}.csv│
|
|
|
+│ │
|
|
|
+│ ⑨ validate_decisions 护栏验证（频率/边界/方向/兜底） │
|
|
|
+│ │
|
|
|
+│ ⑩ generate_report 生成 Excel + CSV 报告 │
|
|
|
+│ │
|
|
|
+│ ⑪ send_approval_request 飞书 IM 审批（发送 + 阻塞等待回复） │
|
|
|
+│ 含 Excel 附件 + 统计摘要 │
|
|
|
+│ │
|
|
|
+│ ⑫ check_approval_status 轮询审批状态（超时 120 分钟） │
|
|
|
+│ │
|
|
|
+│ ⑬ execute_decisions 执行审批通过的决策 │
|
|
|
+│ → execution_engine → ad_api │
|
|
|
+│ → audit JSONL 日志 │
|
|
|
+│ │
|
|
|
+│ ⑭ check_execution_feedback 执行效果检查 │
|
|
|
+│ │
|
|
|
+└─────────────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
+> `execute_once_test.py` 是该流程的**无审批模式变体**：发送审批请求但不阻塞等待，跳过执行步骤，仅生成报告收尾。用于无运营人员值班的场景。
|
|
|
+
|
|
|
### 3.2 核心决策架构（三层）
|
|
|
|
|
|
```
|
|
|
-┌─────────────────────────────────────────────────────┐
|
|
|
-│ Layer 1: 规则引擎 (ad_decision.py, Python) │
|
|
|
-│ │
|
|
|
-│ ① 年龄保护：冷启动 ≤3天 → 排除 │
|
|
|
-│ 早期成长 4-7天 → 仅允许 bid_up │
|
|
|
-│ 成熟期 >7天 → 全面调控 │
|
|
|
-│ │
|
|
|
-│ ② 零消耗检测：近 N 天消耗=0 → 规则关停 │
|
|
|
-│ │
|
|
|
-│ ③ 5 个候选标记计算： │
|
|
|
-│ ├── roi_low 动态ROI < P50 × 0.75 │
|
|
|
-│ ├── bid_down_candidate ROI < P50 × 0.90 │
|
|
|
-│ ├── bid_up_candidate ROI > P50 × 1.05 (仅冷启)│
|
|
|
-│ ├── decay_signal 裂变率持续下降 │
|
|
|
-│ └── high_burn 消耗异常高 + 低ROI │
|
|
|
-└─────────────────────────────────────────────────────┘
|
|
|
+┌─────────────────────────────────────────────────────────────────┐
|
|
|
+│ Layer 1: 规则引擎 (ad_decision.py, Python) │
|
|
|
+│ │
|
|
|
+│ ① 年龄保护：冷启动 ≤3 天 → 排除 │
|
|
|
+│ 早期成长 4-7 天 → 仅允许 bid_up │
|
|
|
+│ 成熟期 >7 天 → 全面调控 │
|
|
|
+│ │
|
|
|
+│ ② 零消耗检测：近 N 天消耗 = 0 → 规则关停 │
|
|
|
+│ │
|
|
|
+│ ③ 5 个候选标记计算： │
|
|
|
+│ ├── roi_low 动态 ROI < P50 × 0.75 │
|
|
|
+│ ├── bid_down_candidate 动态 ROI < P50 × 0.90 │
|
|
|
+│ ├── bid_up_candidate 动态 ROI > P50 × 1.05（仅冷启动） │
|
|
|
+│ ├── decay_signal 裂变率持续下降 │
|
|
|
+│ └── high_burn 消耗异常高 + 低 ROI │
|
|
|
+└─────────────────────────────────────────────────────────────────┘
|
|
|
│ 标记完的广告列表 → 喂给 LLM
|
|
|
▼
|
|
|
-┌─────────────────────────────────────────────────────┐
|
|
|
-│ Layer 2: LLM 推理 (Claude Sonnet 4.5) │
|
|
|
-│ │
|
|
|
-│ 注入 skills/*.md 领域知识： │
|
|
|
-│ ├── ad_domain.md 裂变模型、R值、ROI公式 │
|
|
|
-│ ├── decision_strategy.md 7 种 action、权衡原则 │
|
|
|
-│ ├── platform_rules.md oCPM学习期、调价上限 │
|
|
|
-│ └── posterior_wisdom.md 历史经验教训 │
|
|
|
-│ │
|
|
|
-│ 输出 7 种 action： │
|
|
|
-│ pause | bid_down | bid_up | scale_up | │
|
|
|
-│ creative_adjust | observe | hold │
|
|
|
-│ │
|
|
|
-│ Reason 规则：纯中文、禁止变量名、解释业务逻辑 │
|
|
|
-└─────────────────────────────────────────────────────┘
|
|
|
+┌─────────────────────────────────────────────────────────────────┐
|
|
|
+│ Layer 2: LLM 推理 (Agent 自身，Claude Sonnet 4.5) │
|
|
|
+│ │
|
|
|
+│ 注入 skills/*.md 领域知识： │
|
|
|
+│ ├── ad_domain.md 裂变模型、R 值、动态 ROI 公式 │
|
|
|
+│ ├── decision_strategy.md 7 种 action、权衡原则 │
|
|
|
+│ ├── platform_rules.md oCPM 学习期、调价上限 │
|
|
|
+│ └── posterior_wisdom.md 历史经验教训 │
|
|
|
+│ │
|
|
|
+│ 输出 7 种 action： │
|
|
|
+│ pause | bid_down | bid_up | scale_up | │
|
|
|
+│ creative_adjust | observe | hold │
|
|
|
+│ │
|
|
|
+│ Reason 规则：纯中文、禁止变量名、解释业务逻辑 │
|
|
|
+└─────────────────────────────────────────────────────────────────┘
|
|
|
│ LLM 决策 → 写入 decisions CSV
|
|
|
▼
|
|
|
-┌─────────────────────────────────────────────────────┐
|
|
|
-│ Layer 3: 护栏验证 (guardrails.py, Python) │
|
|
|
-│ │
|
|
|
-│ ① 方向检查：bid_down 是否合理（ROI 真的低？） │
|
|
|
-│ ② 频率检查：6h 内不能重复调同一广告 │
|
|
|
-│ ③ 边界检查：出价必须在 [0.05, 1.00] 元区间 │
|
|
|
-│ ④ 日累计检查：当日累计调幅 ≤ 20% │
|
|
|
-│ ⑤ 兜底检查：触发次数应为 0（有则说明规则层有漏） │
|
|
|
-│ ⑥ DRY_RUN 模式：True → 仅记录不执行 │
|
|
|
-└─────────────────────────────────────────────────────┘
|
|
|
+┌─────────────────────────────────────────────────────────────────┐
|
|
|
+│ Layer 3: 护栏验证 (guardrails.py, Python) │
|
|
|
+│ │
|
|
|
+│ ① 方向检查：bid_down 是否合理（ROI 真的低？） │
|
|
|
+│ ② 频率检查：6h 内不能重复调同一广告 │
|
|
|
+│ ③ 边界检查：出价必须在 [0.05, 1.00] 元区间 │
|
|
|
+│ ④ 日累计检查：当日累计调幅 ≤ 20% │
|
|
|
+│ ⑤ 兜底检查：触发次数应为 0（有则说明规则层有漏） │
|
|
|
+│ ⑥ DRY_RUN 模式：True → 仅记录不执行 │
|
|
|
+└─────────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
-### 3.3 ROI 计算公式
|
|
|
+### 3.3 动态 ROI 计算公式
|
|
|
+
|
|
|
+项目使用**动态 ROI（7日均值）**作为核心决策指标，而非简单 ROI。
|
|
|
|
|
|
```
|
|
|
对每一天（日消耗 ≥ 100 元才参与计算）：
|
|
|
- T0裂变系数 = T0裂变数 / 首层打开数
|
|
|
- arpu = 总收入 / 总回流人数
|
|
|
- 当日裂变收益率 = T0裂变数 × arpu / cost
|
|
|
- 当日回流倍数 = 总回流人数 / 首层打开数
|
|
|
+ T0裂变系数 = T0裂变数（fission0_count）/ 首层打开数（open_count）
|
|
|
+ arpu = 总收入 / 总回流人数
|
|
|
+ 当日裂变收益率 = T0裂变数 × arpu / cost
|
|
|
+ 当日回流倍数 = 总回流人数 / 首层打开数
|
|
|
|
|
|
-7日滚动均值（min_periods=3）：
|
|
|
- 动态 ROI (7日均值) = 当日裂变收益率 × (回流倍数_7日均值 / T0裂变系数_7日均值)
|
|
|
+7 日滚动均值（min_periods=3，至少 3 天合格数据即可计算）：
|
|
|
+ T0裂变系数_7日均值 = mean(T0裂变系数) over 7 天
|
|
|
+ 回流倍数_7日均值 = mean(当日回流倍数) over 7 天
|
|
|
+ 裂变效率稳定因子 = 回流倍数_7日均值 / T0裂变系数_7日均值
|
|
|
+
|
|
|
+ 动态 ROI（7日均值）= 当日裂变收益率 × 裂变效率稳定因子
|
|
|
```
|
|
|
|
|
|
**决策使用规则**：
|
|
|
-- **广告级决策**：使用单广告的动态 ROI (7日均值)
|
|
|
-- **人群包评估**：使用人群包整体的动态 ROI (7日均值) 均值
|
|
|
-- **关停阈值**：动态 ROI < 渠道 P50 × 0.75 → 触发 roi_low 标记
|
|
|
+- **广告级决策**：使用单广告的动态 ROI（7日均值）
|
|
|
+- **人群包评估**：使用人群包整体的动态 ROI（7日均值）均值
|
|
|
+- **关停阈值**：动态 ROI < 渠道 P50 × `ROI_LOW_FACTOR`（默认 0.75）→ 触发 `roi_low` 标记
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 四、Flow B: 创建投放流程（execute_creation_once.py）
|
|
|
+## 四、Flow B: 创建投放（execute_creation_once.py）
|
|
|
+
|
|
|
+### 4.1 执行模型：硬编码多阶段 Pipeline
|
|
|
|
|
|
-### 4.1 多阶段 Pipeline
|
|
|
+> 与 Flow A 不同，`execute_creation_once.py` 是**确定性 Python 脚本**，不经过 Agent 框架。所有步骤按固定顺序执行，不依赖 LLM 编排。
|
|
|
|
|
|
```
|
|
|
-Phase -1: sync_feishu_account_config ← 飞书配置 → DB (account + template)
|
|
|
+Phase -1: sync_feishu_account_config ← 飞书配置 → DB（account + template）
|
|
|
│
|
|
|
Phase 0 (Module A): 创建广告
|
|
|
│ ① enumerate_new_ad_candidates 按账户枚举候选
|
|
|
│ ├── 指纹去重：audience × 素材 组合
|
|
|
│ ├── 按 tier ROI 排序
|
|
|
│ └── 目标：每账户 ADS_PER_ACCOUNT=2 个在投广告
|
|
|
- │ ② 飞书审批广告创建方案
|
|
|
+ │ ② 飞书审批广告创建方案（im_approval_ad_creation.py）
|
|
|
│ ③ POST /adgroups/add
|
|
|
│ 固定参数：marketing_goal=USER_GROWTH, bid_mode=OCPM
|
|
|
│ targeting: age 45-66, 特定区域, 6:00-23:00 投放
|
|
|
@@ -269,18 +364,20 @@ Phase 0 (Module A): 创建广告
|
|
|
│
|
|
|
Phase 1 (Module B): 准备创意
|
|
|
│ ① find_ads_needing_creatives 找缺少创意的广告
|
|
|
- │ 目标：每广告 TARGET_CREATIVES_PER_AD=4 个创意
|
|
|
+ │ 目标：每广告 TARGET_CREATIVES_PER_AD=8 个合格创意
|
|
|
│ ② 对每个广告：
|
|
|
- │ ├── video_recall 拉取视频内容列表
|
|
|
- │ ├── video_risk 风险标签检查
|
|
|
- │ ├── material_recall batchByText 召回（sim ≥ 0.8）
|
|
|
- │ ├── material 排序 按消耗降序
|
|
|
- │ ├── 7 日去重 同素材同人群包不重复
|
|
|
- │ └── landing_plan xcx/save 落地页方案
|
|
|
+ │ ├── account_material_strategy 判断素材来源（历史 / AI 生成）
|
|
|
+ │ ├── video_recall 拉取视频内容列表
|
|
|
+ │ ├── video_risk 风险标签检查（≥6 拦截）
|
|
|
+ │ ├── video_feature_query 查询 ODPS 视频特征（解构选题/实质）
|
|
|
+ │ ├── material_recall batchByText 召回（sim ≥ 0.8）
|
|
|
+ │ ├── material 排序 按消耗降序
|
|
|
+ │ ├── 7 日去重 同素材同人群包不重复
|
|
|
+ │ └── landing_plan xcx/save 落地页方案
|
|
|
│ ③ 输出: creation_pending_{date}.json
|
|
|
│
|
|
|
Phase 2: 飞书审批
|
|
|
- │ 发送创意候选列表 → 等待运营审批
|
|
|
+ │ 发送创意候选列表 → 等待运营审批（im_approval_creation.py）
|
|
|
│ config: CREATION_APPROVAL_REQUIRED=True
|
|
|
│
|
|
|
Phase 3: 提交创意 (execute_creation_apply.py)
|
|
|
@@ -290,46 +387,75 @@ Phase 3: 提交创意 (execute_creation_apply.py)
|
|
|
④ 飞书通知执行结果
|
|
|
```
|
|
|
|
|
|
-### 4.2 关键配置
|
|
|
+### 4.2 AI 素材链路（2026-07 新增）
|
|
|
+
|
|
|
+部分账户支持 AI 生成素材替代历史素材召回：
|
|
|
+
|
|
|
+```
|
|
|
+account_material_strategy.py 判断素材来源
|
|
|
+ │
|
|
|
+ ├── source=history（默认）→ 走传统素材召回链路（Phase 1②）
|
|
|
+ │
|
|
|
+ └── source=ai_generated → 走 AI 生成链路：
|
|
|
+ ① ai_generated_material.py 调用 LiblibAI / 其他生成引擎
|
|
|
+ ② ai_material_review.py Gemini Flash 审核生成结果
|
|
|
+ ③ ai_pattern_selector.md 范式选择 Prompt
|
|
|
+ ④ ai_cover_copy.md 封面文案生成 Prompt
|
|
|
+ ⑤ 审核通过 → 进入 landing_plan + 审批流程
|
|
|
+```
|
|
|
+
|
|
|
+**素材策略学习**（`material_strategy_learning.py`）：
|
|
|
+- 独立于创建管线，不产生腾讯侧副作用
|
|
|
+- 存储高消耗素材快照 + 视觉标注
|
|
|
+- 为后续素材范式优化提供数据基础
|
|
|
+
|
|
|
+### 4.3 关键配置
|
|
|
|
|
|
-| 参数 | 值 | 说明 |
|
|
|
-|------|-----|------|
|
|
|
+| 参数 | 默认值 | 说明 |
|
|
|
+|------|--------|------|
|
|
|
| `ADS_PER_ACCOUNT` | 2 | 每账户目标在投广告数 |
|
|
|
-| `TARGET_CREATIVES_PER_AD` | 4 | 每广告目标创意数 |
|
|
|
+| `TARGET_CREATIVES_PER_AD` | 8 | 每广告目标合格创意数 |
|
|
|
| `CREATION_APPROVAL_REQUIRED` | True | 创意是否需要审批 |
|
|
|
| `RECALL_SIM_THRESHOLD` | 0.8 | 素材召回相似度阈值 |
|
|
|
| `RECALL_DAYS` | 180 | 素材召回时间窗口 |
|
|
|
| `MAX_LANDING_ATTEMPTS_PER_AD` | 100 | 每广告落地页创建最大尝试次数 |
|
|
|
-| `VIDEO_RISK_MAX_ALLOWED_LEVEL` | 5 | 视频风险等级上限 |
|
|
|
+| `VIDEO_RISK_MAX_ALLOWED_LEVEL` | 5 | 视频风险等级上限（6-10 拦截） |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 五、Flow C: 审核扫描（scan_creative_reviews.py）
|
|
|
|
|
|
+确定性脚本，不经过 Agent 框架：
|
|
|
+
|
|
|
```
|
|
|
-每 2 小时执行一次 (k8s CronJob):
|
|
|
+每 2 小时执行一次：
|
|
|
creative_review.scan_pending_reviews()
|
|
|
- ├── 读 DB: creative_creation_task (review_status=pending)
|
|
|
- ├── 调 API: GET /dynamic_creatives/get (查审核结果)
|
|
|
- ├── 写 DB: creative_review_result (审核结果)
|
|
|
- └── 写 DB: creative_rejection_fact (拒审事实，供后续召回排除)
|
|
|
+ ├── 读 DB: creative_creation_task（review_status=pending）
|
|
|
+ ├── 调 API: GET /dynamic_creatives/get（查审核结果）
|
|
|
+ ├── 写 DB: creative_review_result（审核结果）
|
|
|
+ └── 写 DB: creative_rejection_fact（拒审事实，供后续召回排除）
|
|
|
+
|
|
|
+DENIED 创意不计入有效创意，触发自动补量。
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 六、入口点全景
|
|
|
|
|
|
-| 入口 | 类型 | 用途 | 谁来调用 |
|
|
|
-|------|------|------|---------|
|
|
|
-| `run.py` | 交互 REPL | 开发调试、人工分析 | 开发者手动 |
|
|
|
-| `execute_once.py` | 自动化脚本 | Flow A 决策调控 | K8s CronJob / server.py |
|
|
|
-| `execute_creation_once.py` | 自动化脚本 | Flow B 创建投放 | K8s CronJob |
|
|
|
-| `execute_creation_apply.py` | 可独立执行 | Flow B Phase 3 独立提交 | 手动或 import |
|
|
|
+| 入口 | 执行模型 | 用途 | 谁来调用 |
|
|
|
+|------|---------|------|---------|
|
|
|
+| `run.py` | Agent REPL | 交互式调试、人工分析 | 开发者手动 |
|
|
|
+| `execute_once.py` | Agent 驱动 | **Flow A 决策调控**（LLM 编排工具） | K8s CronJob / server.py |
|
|
|
+| `execute_once_test.py` | Agent 驱动 | **Flow A 无审批模式**（不阻塞等待审批） | 无运营时的无人值守测试 |
|
|
|
+| `execute_creation_once.py` | 硬编码 Pipeline | **Flow B 创建投放** | run_daily_service.py / K8s CronJob |
|
|
|
+| `execute_creation_apply.py` | 硬编码脚本 | **Flow B Phase 3** 独立提交 | 手动或 import |
|
|
|
+| `run_daily_service.py` | 常驻调度 | **★ 生产日级服务**（Flow B + C，APScheduler） | Docker Compose / K8s Deployment |
|
|
|
+| `run_daily_roi.py` | 硬编码脚本 | 独立日级 ROI 计算 + 可选飞书审批 | 手动或 Cron |
|
|
|
| `run_full_analysis.py` | 调试工具 | 仅数据准备（无 LLM） | 开发者手动 |
|
|
|
| `fetch_data.py` | 独立工具 | 仅拉取 ODPS 数据 | 开发者手动 |
|
|
|
| `merge_data.py` | 独立工具 | 仅合并数据 | 开发者手动 |
|
|
|
-| `server.py` | 常驻服务 | 生产 APScheduler 调度 | K8s Deployment |
|
|
|
-| `scan_creative_reviews.py` | 自动化脚本 | Flow C 审核扫描 | K8s CronJob（每 2h） |
|
|
|
+| `server.py` | 常驻服务 | 旧版 Flow A 调度（FastAPI + APScheduler） | 历史保留，非当前生产入口 |
|
|
|
+| `scan_creative_reviews.py` | 硬编码脚本 | **Flow C 审核扫描** | run_daily_service.py / K8s CronJob |
|
|
|
| `sync_ad_status.py` | 辅助脚本 | 同步广告状态 | execute_once.py Step 0 |
|
|
|
| `sync_feishu_account_config.py` | 辅助脚本 | 同步飞书账户配置 | execute_creation_once.py Phase -1 |
|
|
|
| `configure_creation_accounts.py` | 运维工具 | 批量写入账户配置 | 运维手动 |
|
|
|
@@ -338,22 +464,38 @@ Phase 3: 提交创意 (execute_creation_apply.py)
|
|
|
|
|
|
## 七、部署架构
|
|
|
|
|
|
-### 7.1 两种部署模式
|
|
|
+### 7.1 Docker Compose（当前生产方案）
|
|
|
+
|
|
|
+同一镜像 `ad-put-agent` 启动两个容器：
|
|
|
+
|
|
|
+```
|
|
|
+docker-compose.yml
|
|
|
+├── ad_control_service → tencent_realtime_control/run_control_service.py
|
|
|
+│ 实时 CPM 调控 + 飞书 WebSocket 指令
|
|
|
+│
|
|
|
+└── ad_daily_service → auto_put_ad_mini/run_daily_service.py
|
|
|
+ Flow B（创建投放）+ Flow C（审核扫描）
|
|
|
+```
|
|
|
+
|
|
|
+> **注意**：Flow A（Agent 驱动决策调控）当前不在生产 Compose 中运行。`server.py` 保留但不再是生产入口。
|
|
|
+
|
|
|
+### 7.2 两种 K8s 部署模式
|
|
|
|
|
|
| 模式 | 文件 | 调度方式 | 优点 |
|
|
|
|------|------|---------|------|
|
|
|
-| **Deployment + APScheduler** | `k8s/deployment.yaml` + `server.py` | APScheduler 读取 DB `cron_schedule` | HTTP 健康检查、手动触发 API、单 Pod |
|
|
|
+| **Deployment + APScheduler** | `k8s/deployment.yaml` + `server.py` 或 `run_daily_service.py` | APScheduler 读取 DB `cron_schedule` | HTTP 健康检查、手动触发 API |
|
|
|
| **Kubernetes CronJob** | `k8s/cronjob*.yaml` | K8s CronJob | 简单、K8s 原生重试 |
|
|
|
|
|
|
-### 7.2 时间线
|
|
|
+### 7.3 生产时间线
|
|
|
|
|
|
```
|
|
|
-UTC 02:00 (北京时间 10:00) → Flow A: 决策调控
|
|
|
-UTC 02:30 (北京时间 10:30) → Flow B: 创建投放（与 A 间隔 30 分钟避免 API 争用）
|
|
|
-每 2 小时 → Flow C: 创意审核扫描
|
|
|
+北京时间 10:00 (UTC 02:00) → Flow A: Agent 驱动决策调控（execute_once.py）
|
|
|
+北京时间 10:30 (UTC 02:30) → Flow B: 创建投放（execute_creation_once.py）
|
|
|
+每 2 小时 → Flow C: 创意审核扫描（scan_creative_reviews.py）
|
|
|
+每 10 分钟 → CPM 实时调控（tencent_realtime_control）
|
|
|
```
|
|
|
|
|
|
-### 7.3 动态配置（DB 驱动）
|
|
|
+### 7.4 动态配置（DB 驱动）
|
|
|
|
|
|
| 配置项 | DB 表 | 默认值 | 说明 |
|
|
|
|--------|-------|--------|------|
|
|
|
@@ -363,7 +505,7 @@ UTC 02:30 (北京时间 10:30) → Flow B: 创建投放（与 A 间隔 30 分
|
|
|
| `whitelist_enabled` | `system_config` | `true` | 白名单机制开关 |
|
|
|
| `roi_low_factor` | `system_config` | `0.75` | 关停线系数 |
|
|
|
|
|
|
-优先级：DB > 环境变量 > 代码默认值
|
|
|
+**优先级**：DB > 环境变量 > 代码默认值
|
|
|
|
|
|
---
|
|
|
|
|
|
@@ -371,14 +513,14 @@ UTC 02:30 (北京时间 10:30) → Flow B: 创建投放（与 A 间隔 30 分
|
|
|
|
|
|
| 表名 | 用途 | Flow |
|
|
|
|------|------|------|
|
|
|
-| `account_whitelist` | 账户白名单 | A/B |
|
|
|
-| `ad_delivery_template` | 投放模板（出价/定向/预算） | B |
|
|
|
+| `account_whitelist` | 账户白名单 | A / B |
|
|
|
+| `ad_delivery_template` | 投放模板（出价 / 定向 / 预算） | B |
|
|
|
| `ad_creation_account_config` | 账户 × 人群包 × 出价配置 | B |
|
|
|
| `brand_asset_template` | 品牌资产模板 | B |
|
|
|
| `feedback_asset_template` | 反馈资产模板 | B |
|
|
|
-| `system_config` | 系统配置（KV） | A/B |
|
|
|
+| `system_config` | 系统配置（KV） | A / B |
|
|
|
| `decision_history` | 决策历史 | A |
|
|
|
-| `creative_creation_task` | 创意创建任务 | B/C |
|
|
|
+| `creative_creation_task` | 创意创建任务 | B / C |
|
|
|
| `creative_review_result` | 创意审核结果 | C |
|
|
|
| `creative_rejection_fact` | 创意拒审事实 | C |
|
|
|
| `video_element_feature_cache` | 视频特征缓存 | B |
|
|
|
@@ -389,32 +531,38 @@ UTC 02:30 (北京时间 10:30) → Flow B: 创建投放（与 A 间隔 30 分
|
|
|
## 九、与 auto_put_ad 的关系
|
|
|
|
|
|
```
|
|
|
-auto_put_ad (完整体系) auto_put_ad_mini (当前生产)
|
|
|
-┌──────────────────────┐ ┌──────────────────────────┐
|
|
|
-│ 受众策略 Agent │ │ │
|
|
|
-│ 创意策略 Agent │ │ Flow A: 决策调控 │
|
|
|
-│ 预算策略 Agent ───────┼──出价──▶ │ (规则→LLM→护栏→执行) │
|
|
|
-│ 监控调控 Agent ───────┼──决策──▶ │ │
|
|
|
-│ 数据分析 Agent │ │ Flow B: 创建投放 │
|
|
|
-│ 系统运维 Agent │ │ (广告+创意+审批+提交) │
|
|
|
-│ 自学习/反馈环 │ │ │
|
|
|
-└──────────────────────┘ │ Flow C: 审核扫描 │
|
|
|
- └──────────────────────────┘
|
|
|
+auto_put_ad（完整多 Agent 体系） auto_put_ad_mini（当前生产）
|
|
|
+┌──────────────────────────┐ ┌──────────────────────────────┐
|
|
|
+│ 受众策略 Agent │ │ │
|
|
|
+│ 创意策略 Agent │ │ Flow A: Agent 驱动决策调控 │
|
|
|
+│ 预算策略 Agent ───────┐ │ │ （LLM 编排 → 护栏 → 执行） │
|
|
|
+│ 监控调控 Agent ───┐ │ │ │ │
|
|
|
+│ 数据分析 Agent │ │ │ │ Flow B: 创建投放 │
|
|
|
+│ 系统运维 Agent │ │ │ │ （广告 + 创意 + AI素材 │
|
|
|
+│ 自学习 / 反馈环 │ │ │ │ + 审批 + 提交） │
|
|
|
+└──────────────────┼───┼───┘ │ │
|
|
|
+ │ │ │ Flow C: 审核扫描 │
|
|
|
+ │ └── 出价 ──────▶│ （每 2h 确定性脚本） │
|
|
|
+ └──── 决策 ──────▶ │ │
|
|
|
+ └──────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
- `auto_put_ad_mini` 最初是 `auto_put_ad` 中「监控调控 Agent」的独立落地版
|
|
|
-- 实际演进中，mini 发展出了更完整的决策三层架构和独立的创建子系统
|
|
|
-- 两者共享 `tools/ad_api.py` 的腾讯广告 API 封装思路和 `skills/` 领域知识
|
|
|
-- mini 的 `ad_decision.py` 三层架构可作为大项目后续迭代的参考
|
|
|
+- 演进中发展出完整的三层决策架构 + 独立的创建子系统（含 AI 素材链路）
|
|
|
+- 两者共享腾讯广告 API 封装思路和领域知识
|
|
|
+- `tencent_realtime_control` 作为独立的 CPM 实时调控服务，与 mini 的 Flow A 互补
|
|
|
|
|
|
---
|
|
|
|
|
|
## 十、关键设计原则
|
|
|
|
|
|
-1. **三层决策架构**: 规则标记 → LLM 推理 → 护栏兜底，各层职责清晰，LLM 只做"综合判断"不做"规则计算"
|
|
|
-2. **两条业务线解耦**: 决策调控和创建投放使用独立的入口/CronJob/审批流，避免互相阻塞
|
|
|
-3. **DB 驱动配置**: 关键开关（执行启用/白名单/调度表达式）在 DB 中，无需重启即可调整
|
|
|
-4. **人工审批嵌入**: 执行前必须通过飞书 IM 审批（可配置关闭），含 Excel 附件 + 统计摘要
|
|
|
-5. **7 日去重保护**: 素材使用记录保留 7 天，防止同一素材重复提交审核
|
|
|
-6. **年龄分层保护**: ≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
|
|
|
-7. **提降分离**: 提价 5%-10%、降价 3%-5%，降价更保守（因为 oCPM 模式下降价效果非线放大）
|
|
|
+1. **Agent 驱动 vs 确定性 Pipeline**：Flow A 由 LLM 动态编排工具调用（灵活性高、能处理边界情况），Flow B/C 是硬编码多阶段脚本（确定性、可审计、无 LLM 幻觉风险）。两者各司其职。
|
|
|
+2. **三层决策架构**：规则标记 → LLM 推理 → 护栏兜底，各层职责清晰，LLM 只做"综合判断"不做"规则计算"
|
|
|
+3. **两条业务线解耦**：决策调控（Flow A）和创建投放（Flow B + C）使用独立的入口 / CronJob / 审批流，避免互相阻塞
|
|
|
+4. **DB 驱动配置**：关键开关（执行启用 / 白名单 / 调度表达式）在 DB 中，无需重启即可调整
|
|
|
+5. **人工审批嵌入**：执行前必须通过飞书 IM 审批（可配置关闭），含 Excel 附件 + 统计摘要
|
|
|
+6. **7 日去重保护**：素材使用记录保留 7 天，防止同一素材重复提交审核
|
|
|
+7. **年龄分层保护**：≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
|
|
|
+8. **提降分离**：提价 5%-10%、降价 3%-5%，降价更保守（oCPM 模式下降价效果非线性放大）
|
|
|
+9. **副作用意识**：素材召回 / AI 生成 / `xcx/save` / 广告创建等均有外部副作用，端到端中断不会自动回滚
|
|
|
+10. **幂等优先**：重复运行应跳过已完成的工作，只补缺口
|
wangyunpeng