Agent/examples/auto_put_ad_mini/config.py

"""
广告智能决策引擎配置 — auto_put_ad_mini

运营可直接修改此文件调整决策参数。
当前模式：智能判断
  - 基于 f_7日动态ROI 的精细化决策
  - AI 推理结合领域知识
  - 三级分类：零消耗待关停（规则）+ 待优化评估（智能）+ 正常运行（规则）
"""
import os
from pathlib import Path
from agent.core.runner import RunConfig, KnowledgeConfig

# 加载 .env 文件（如果存在）
try:
    from dotenv import load_dotenv
    load_dotenv(Path(__file__).parent / ".env")
except ImportError:
    pass

# ═══════════════════════════════════════════
# Agent 运行配置
# ═══════════════════════════════════════════

MAIN_CONFIG = RunConfig(
    model="qwen/qwen3.5-plus-02-15",
    temperature=0.3,
    max_iterations=50,
    name="广告智能调控助手",
    tools=[
        "fetch_creative_data",
        "merge_creative_data",
        "calculate_roi_metrics",
        "calculate_portfolio_summary",
        "get_ads_for_review",
        "apply_decisions",
        "query_ad_detail",      # Mode 2: 查询广告详情
        "modify_decisions",     # Mode 3: 修改已有决策
        "validate_decisions",
        "generate_report",
        # 执行引擎 + IM 审批（已集成阻塞式审批流）：
        "execute_decisions",
        "check_execution_feedback",
        "send_approval_request",
        "check_approval_status",
        "send_feishu_text_message",  # 执行后向您同步 diff / 确认 / 质疑回应
        # 飞书文档（报告导入 & 分享）：
        "import_to_feishu",
        # 注：曾考虑用内置 "agent" 工具按 tier 并行委托子 Agent，
        # 但框架的 agent 工具只返回文本 summary，主 Agent 拿不回结构化决策，
        # 会陷入"无法 apply"的死循环。直接在主 Agent 单次输出完成全部 decisions 更可靠。
    ],
    skills=["ad-domain", "roi-strategy", "guardrail-rules", "tencent-ad-playbook"],
    # extra_llm_params={"extra_body": {"enable_thinking": True}},  # 禁用：千问不支持 thinking
    knowledge=KnowledgeConfig(
        enable_extraction=False,
        enable_completion_extraction=False,
        enable_injection=False,
        owner="ad_mini_team",
    ),
)

SKILLS_DIR = str(Path(__file__).parent / "skills")
TRACE_STORE_PATH = ".trace"
LOG_LEVEL = "INFO"
LOG_FILE = None

# ═══════════════════════════════════════════
# V3 数据窗口配置
# ═══════════════════════════════════════════
DATA_WINDOW_DAYS = 7  # 测试阶段：采集 7 天历史数据
ROI_CALCULATION_DAYS = 7  # f_7日动态ROI 计算窗口

# ═══════════════════════════════════════════
# V3 决策阈值（默认值，可被 SKILL 覆盖）
# ═══════════════════════════════════════════
MIN_DAILY_COST = 100  # 日消耗 >= 100元才参与 ROI 计算
MIN_AD_AGE_DAYS = 3  # 广告创建 >= 3天才参与决策（与 min_periods 对齐）
ROI_LOW_FACTOR = 0.75  # f_7日动态ROI < 全体均值 × 0.75 → 关停
NO_SPEND_THRESHOLD = 10  # 7日消耗均值 < 10元 → 关停
STABLE_SPEND_THRESHOLD = 100  # 稳定消耗定义：>100元/天

# ═══════════════════════════════════════════
# 出价调整配置
# ═══════════════════════════════════════════
BID_ADJUSTMENT_ENABLED = True
BID_DOWN_ROI_FACTOR = 0.90      # ROI < 均值×0.90 → 考虑降价（低于渠道均值10%）
BID_UP_ROI_FACTOR = 1.05        # ROI > 均值×1.05 → 考虑提价（高于渠道均值5%）
BID_UP_MAX_SPEND = 1000          # 提价消耗上限：均值消耗<1000才提价（投手经验原文）
BID_CHANGE_MIN_PCT = 0.03       # 最小调幅 3%（兼容旧代码）
BID_CHANGE_MAX_PCT = 0.10       # 最大单次调幅 10%（兼容旧代码）
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%
BID_DOWN_MIN_SPEND = 500        # 降价消耗门槛：7日日均消耗≥500元
BID_FLOOR_YUAN = 0.05           # 出价下限（元）
BID_CEILING_YUAN = 1.00         # 出价上限（元）

# 广告年龄分段（基于决策树图片）
COLD_START_DAYS = 3             # 冷启动期（≤3天）：极度保护，几乎不干预
EARLY_GROWTH_DAYS = 7           # 早期成长期（4-7天）：可提价放量（满足ROI+消耗条件）
AD_AGE_MATURE = 7               # 成熟期（>7天）：全面调控

# 兼容性（已废弃）
AD_AGE_NEWBORN = COLD_START_DAYS   # 兼容旧代码
CAUTIOUS_DAYS = EARLY_GROWTH_DAYS  # 兼容旧代码

# 高燃烧预警配置
HIGH_BURN_AGE_THRESHOLD = 3     # 广告年龄>3天才检查
HIGH_BURN_COST_THRESHOLD = 300  # 昨日消耗>300元触发预警
ROI_LOW_MIN_YESTERDAY_COST = 300  # 关停消耗门槛：昨日消耗≥300才检查关停（投手经验2.4）

# ═══════════════════════════════════════════
# 安全护栏配置
# ═══════════════════════════════════════════
GUARDRAILS_ENABLED = True
DRY_RUN_MODE = False                       # 关闭干运行，让护栏正常放行（实际执行由 EXECUTION_ENABLED 控制）
MAX_ADJUSTMENTS_PER_AD_PER_DAY = 2
MIN_ADJUSTMENT_INTERVAL_HOURS = 6
MAX_DAILY_CUMULATIVE_CHANGE_PCT = 0.20     # 日累计调幅上限 20%
MAX_DAILY_OPS = 10000                       # 单日最多操作广告数（实际不限制）
DATA_FRESHNESS_MAX_HOURS = 96               # 数据超过 96 小时视为过期（已从48小时放宽至96小时）

# ═══════════════════════════════════════════
# 执行引擎配置
# ═══════════════════════════════════════════
EXECUTION_ENABLED = False          # 主开关！False = 只验证不执行
API_QPS_LIMIT = 8                  # 保守QPS（平台上限10）
API_MAX_RETRIES = 3
TIER1_MAX_CHANGE_PCT = 0.00       # Tier1自动执行已禁用（改为0%，所有操作都需审批）
TIER3_MIN_DAILY_SPEND = 1500      # 高价值广告门槛（元/天）
FEEDBACK_CHECK_HOURS = 6

# ═══════════════════════════════════════════
# IM 审批配置（飞书直连）
# ═══════════════════════════════════════════
IM_ENABLED = True                  # IM 主开关（True 时审批消息发飞书）
IM_APPROVAL_TIMEOUT_MINUTES = 30   # 审批超时（分钟）
IM_APPROVAL_POLL_INTERVAL_SECONDS = 30  # 审批轮询间隔（秒）

# 飞书应用凭据（"增长投放"机器人）— 优先从环境变量读取
FEISHU_APP_ID = os.getenv("FEISHU_APP_ID", "cli_a955e97067f85cb3")
FEISHU_APP_SECRET = os.getenv("FEISHU_APP_SECRET", "NQaG4ci1plXRDTgwCqrLJgMLLoA2tdF8")

# 运营审批人飞书信息
FEISHU_OPERATOR_OPEN_ID = os.getenv("FEISHU_OPERATOR_OPEN_ID", "ou_498988d823b61ab89c9afe4310f85bb4")
FEISHU_OPERATOR_CHAT_ID = os.getenv("FEISHU_OPERATOR_CHAT_ID", "oc_88e0a1970a7de02eb5ac225a8b0cedea")

# 投放项目群聊 — 用于接收决策结果通知和审批回复
# 置空则不发送到群，仅发送到个人
FEISHU_AD_PROJECT_CHAT_ID = os.getenv("FEISHU_AD_PROJECT_CHAT_ID", "")

# 腾讯广告默认账户（测试账户）
TENCENT_AD_ACCOUNT_ID = int(os.getenv("TENCENT_AD_ACCOUNT_ID", "80769799"))

# ═══════════════════════════════════════════
# 输出路径配置
# ═══════════════════════════════════════════
OUTPUTS_DIR = Path(__file__).parent / "outputs"
RAW_DATA_DIR = OUTPUTS_DIR / "raw"  # 创意级原始 CSV
AD_STATUS_DIR = OUTPUTS_DIR / "ad_status"  # 广告状态 CSV
REPORTS_DIR = OUTPUTS_DIR / "reports"  # 决策报告
EXECUTION_LOG_DIR = OUTPUTS_DIR / "execution_log"  # 执行审计日志
DATA_DIR = OUTPUTS_DIR / "data"  # 运行时数据（如调整历史）
ADJUSTMENT_HISTORY_PATH = DATA_DIR / "adjustment_history.json"

# ═══════════════════════════════════════════
# 人群包系数（保留，用于展示）
# ═══════════════════════════════════════════
AUDIENCE_COEFFICIENTS = {
    "R500":    3.0,
    "R330+":   2.5,
    "R330":    2.0,
    "R180":    1.5,
    "R100":    1.2,
    "R50":     1.0,
    "R10":     1.0,
    "R2":      1.0,
    "default": 1.0,
}

# 从广告名称提取 R 值的匹配顺序
AUDIENCE_TIER_PATTERNS = [
    ("R500",   ["R500", "R_500", "r500"]),
    ("R330+",  ["回流330+", "回流330+-", "回流q330", "330+全品类", "R330+", "R_330+"]),
    ("R330",   ["回流330", "R330", "R_330", "定向330", "r330", "r300"]),
    ("R180",   ["回流180", "R180", "R_180", "定向180", "r180",
                "r180-330", "r180-300", "R100-180", "R_100-180", "r100-180"]),
    ("R100",   ["回流100", "R100", "R_100", "定向100", "r100", "R50-100"]),
    ("R50",    ["回流50", "R50", "R_50", "r50"]),
    ("R10",    ["R_10", "R10", "r10"]),
    ("R2",     ["R_2", "R2", "r2"]),
]