auto_put_ad_mini — 项目结构文档

定位: 微信小程序投流 — 面向 ROI 的广告粒度自动调控 + 自动创建投放系统 最后更新: 2026-07-27

一、项目概述

auto_put_ad_mini 是腾讯广告自动化投放系统的核心生产单元，专注微信小程序投流场景（MARKETING_CARRIER_TYPE_MINI_PROGRAM_WECHAT）。

项目包含三条独立但协同的生产线：

业务线	入口	频率	职责
Flow A: 决策调控	`execute_once.py`	每日 1 次	Agent 驱动：LLM 动态编排工具调用 → ROI 分析 → 出价调整/暂停广告
Flow B: 创建投放	`execute_creation_once.py`	每日 1 次	硬编码 Pipeline：创建广告 → 准备创意 → 飞书审批 → 提交腾讯
Flow C: 审核扫描	`scan_creative_reviews.py`	每 2 小时	硬编码循环：扫描创意审核结果 → 记录拒审事实

两种执行模式：

Flow A：Agent 驱动 — execute_once.py 通过 Agent 框架启动 LLM，由 LLM 动态决定调用哪些工具、以何种顺序执行。system prompt 中嵌入了推荐的执行流程，但实际编排权在模型。
Flow B / C：确定性 Pipeline — execute_creation_once.py 和 scan_creative_reviews.py 是硬编码的多阶段脚本，不经过 LLM 编排。

二、目录结构

examples/auto_put_ad_mini/
│
├── 🔵 核心入口
│   ├── 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，用于调试）
│   ├── fetch_data.py                   # 独立数据拉取脚本
│   └── merge_data.py                   # 独立数据合并脚本
│
├── 🟢 生产服务
│   ├── run_daily_service.py            # ★ 生产日级服务入口（APScheduler，Flow B + C）
│   ├── run_daily_roi.py                # 独立日级 ROI 计算 + 飞书审批（可版本化运行）
│   ├── server.py                       # 旧版生产服务器（FastAPI + APScheduler，仅 Flow A）
│   ├── schedule.sh                     # Shell Cron 包装脚本
│   ├── .env.example                    # 环境变量声明模板
│   └── requirements.txt                # 项目专属 Python 依赖
│
├── 🟡 配置与技能
│   ├── config.py                       # 核心业务配置（~1073 行）
│   ├── presets.json                    # Agent 预设参数
│   ├── strategy_params.json            # 策略参数
│   ├── whitelist.json                  # 账户白名单（可被 DB 覆盖）
│   ├── configs/
│   │   └── material_creative_patterns_seed.json  # 素材创意范式种子数据
│   ├── prompts/
│   │   ├── 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 + 连接池）
│       ├── config.py                   # 系统配置 + 白名单 CRUD（5 分钟缓存）
│       └── schema.sql                  # 12 张表 + 默认种子数据
│
├── 🟠 工具层（35 个文件，含 `__init__.py`）
│   └── tools/
│       ├── __init__.py                 # 包初始化
│       ├── _names.py                   # 字段名常量 + 禁止词黑名单
│       │
│       ├── ── 腾讯 API + 数据层 ──
│       ├── ad_api.py                   # 腾讯广告 API v3.0 封装（读写统一入口）
│       ├── odps_module.py              # ODPS 数据源模块
│       ├── data_query.py               # ODPS + Reporting API 数据拉取与合并
│       │
│       ├── ── 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              # 飞书审批（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  # 素材使用追踪（7 日去重）
│       ├── creative_metrics.py         # 创意级指标
│       ├── creative_review.py          # 创意审核结果扫描（Flow C 核心逻辑）
│       ├── material_recall.py          # 素材召回（batchByText，sim ≥ 0.8）
│       ├── video_recall.py             # 视频内容列表获取
│       ├── video_risk.py               # 视频风险标签检查
│       ├── video_feature_query.py      # 视频元素特征查询（ODPS 贡献度分析）
│       ├── landing_plan.py             # 落地页方案创建（xcx/save）
│       ├── scene_spec.py               # 场景规格 / 微信版位
│       ├── audience_grant.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 入口（独立的 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
│
├── 🐛 调试脚本
│   ├── 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
│
├── 📁 数据与工具
│   ├── 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）

3.1 执行模型：Agent 驱动，非硬编码 Pipeline

关键认知：execute_once.py 不是一个步骤固定的脚本。它启动一个 Agent（AgentRunner），将控制权交给 LLM。LLM 读取 system prompt 中嵌入的推荐流程，动态决定调用哪些工具、以何种顺序调用。

实际运行时，LLM 通常会按以下顺序调用工具（顺序由 system prompt 中的推荐流程引导，但 LLM 可以跳过、重排或插入中间步骤）：

用户消息："分析广告，执行完整的ROI计算和决策流程"
    │
    ▼
┌─ 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                 │
└─────────────────────────────────────────────────────────────────┘
        │ 标记完的广告列表 → 喂给 LLM
        ▼
┌─────────────────────────────────────────────────────────────────┐
│ 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 → 仅记录不执行                            │
└─────────────────────────────────────────────────────────────────┘

3.3 动态 ROI 计算公式

项目使用动态 ROI（7日均值）作为核心决策指标，而非简单 ROI。

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

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 × ROI_LOW_FACTOR（默认 0.75）→ 触发 roi_low 标记

四、Flow B: 创建投放（execute_creation_once.py）

4.1 执行模型：硬编码多阶段 Pipeline

与 Flow A 不同，execute_creation_once.py 是确定性 Python 脚本，不经过 Agent 框架。所有步骤按固定顺序执行，不依赖 LLM 编排。

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 投放
    │               day_amount: 200 CNY
    │
Phase 1 (Module B): 准备创意
    │  ① find_ads_needing_creatives   找缺少创意的广告
    │     目标：每广告 TARGET_CREATIVES_PER_AD=8 个合格创意
    │  ② 对每个广告：
    │     ├── 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)
       ① 读取已审批的 pending records
       ② POST /dynamic_creatives/add
       ③ 写入 creative_creation_task 表
       ④ 飞书通知执行结果

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`	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	视频风险等级上限（6-10 拦截）

五、Flow C: 审核扫描（scan_creative_reviews.py）

确定性脚本，不经过 Agent 框架：

每 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（拒审事实，供后续召回排除）

DENIED 创意不计入有效创意，触发自动补量。

六、入口点全景

入口	执行模型	用途	谁来调用
`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`	常驻服务	旧版 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`	运维工具	批量写入账户配置	运维手动

七、部署架构

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` 或 `run_daily_service.py`	APScheduler 读取 DB `cron_schedule`	HTTP 健康检查、手动触发 API
Kubernetes CronJob	`k8s/cronjob*.yaml`	K8s CronJob	简单、K8s 原生重试

7.3 生产时间线

北京时间 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.4 动态配置（DB 驱动）

配置项	DB 表	默认值	说明
`cron_schedule`	`system_config`	`0 2 * * *`	调度表达式
`execution_enabled`	`system_config`	`false`	是否启用实际执行
`run_on_startup`	`system_config`	`false`	启动时是否执行一次
`whitelist_enabled`	`system_config`	`true`	白名单机制开关
`roi_low_factor`	`system_config`	`0.75`	关停线系数

优先级：DB > 环境变量 > 代码默认值

八、数据库表（12 张）

表名	用途	Flow
`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
`decision_history`	决策历史	A
`creative_creation_task`	创意创建任务	B / C
`creative_review_result`	创意审核结果	C
`creative_rejection_fact`	创意拒审事实	C
`video_element_feature_cache`	视频特征缓存	B
`creative_material_usage`	素材使用记录（7 日去重）	B

九、与 auto_put_ad 的关系

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」的独立落地版
演进中发展出完整的三层决策架构 + 独立的创建子系统（含 AI 素材链路）
两者共享腾讯广告 API 封装思路和领域知识
tencent_realtime_control 作为独立的 CPM 实时调控服务，与 mini 的 Flow A 互补

十、关键设计原则

Agent 驱动 vs 确定性 Pipeline：Flow A 由 LLM 动态编排工具调用（灵活性高、能处理边界情况），Flow B/C 是硬编码多阶段脚本（确定性、可审计、无 LLM 幻觉风险）。两者各司其职。
三层决策架构：规则标记 → LLM 推理 → 护栏兜底，各层职责清晰，LLM 只做"综合判断"不做"规则计算"
两条业务线解耦：决策调控（Flow A）和创建投放（Flow B + C）使用独立的入口 / CronJob / 审批流，避免互相阻塞
DB 驱动配置：关键开关（执行启用 / 白名单 / 调度表达式）在 DB 中，无需重启即可调整
人工审批嵌入：执行前必须通过飞书 IM 审批（可配置关闭），含 Excel 附件 + 统计摘要
7 日去重保护：素材使用记录保留 7 天，防止同一素材重复提交审核
年龄分层保护：≤3 天冷启动零干预、4-7 天仅允许提价、>7 天全面调控
提降分离：提价 5%-10%、降价 3%-5%，降价更保守（oCPM 模式下降价效果非线性放大）
副作用意识：素材召回 / AI 生成 / xcx/save / 广告创建等均有外部副作用，端到端中断不会自动回滚
幂等优先：重复运行应跳过已完成的工作，只补缺口

PROJECT_STRUCTURE.md 34 KB Historia Czysty