Agent/examples/auto_put_ad_mini/.env.example

# 兼容本地开发的组件级样例。生产部署统一以仓库根目录 runtime.env.example 为准。
# 不要在两个组件样例中分别维护生产配置。

# ========================================
# 本地日志与阿里云 SLS
# ========================================
LOG_LEVEL=INFO
SLS_ENDPOINT=cn-hangzhou.log.aliyuncs.com
SLS_ACCESS_KEY_ID=xxx
SLS_ACCESS_KEY_SECRET=xxx
SLS_PROJECT=auto-put-tecent
D=info-log
SLS_ERROR_LOGSTORE=error-log
# SLS_INFO_LOGSTORE 未设置时的回退 logstore
# SLS_LOGSTORE=info-log
# SLS 上报最低日志级别，默认 INFO
# SLS_LOG_LEVEL=INFO
# SLS 批量上报最大条数，默认 1024
# SLS_BATCH_SIZE_MAX=1024
# SLS 批量上报等待间隔(毫秒)，默认 2000
# SLS_PUT_WAIT_MS=2000

# ========================================
# 腾讯广告 API 配置
# ========================================
TENCENT_AD_ACCOUNT_ID=80769799

# Access Token（应用级认证）
# TENCENT_AD_ACCESS_TOKEN=xxx        # 可选，优先使用 Token API 动态获取

# User Token（用户级实名认证令牌）
# ⚠️ 重要：写操作（暂停广告/修改出价）必须配置 user_token
# 获取方式：https://docs.qq.com/doc/DSVdkdk1LQ1hOam5n
TENCENT_AD_USER_TOKEN=xxx
# 可选,默认使用内部接口按 accountId 动态获取最新 user_token
# TENCENT_AD_USER_TOKEN_API=https://api.piaoquantv.com/ad/put/tencent/getUserToken

# TENCENT_AD_BASE_URL=https://api.e.qq.com/v3.0

# ========================================
# 创意搭建子系统（模块 B）
# ========================================
# 每广告目标创意数，默认 8
TARGET_CREATIVES_PER_AD=8
# 创意准备阶段并发数，默认 1（串行）
# CREATIVE_PREPARE_MAX_WORKERS=1
# 创意准备任务缓冲数，默认 16
# CREATIVE_PREPARE_TASK_BUFFER=16
# 是否走飞书审批流程，默认 true
# CREATION_APPROVAL_REQUIRED=true
# 飞书审批消息中是否嵌入素材预览图，默认 1
# CREATION_APPROVAL_EMBED_IMAGES=1
# 审批超时分钟数，默认 120
CREATION_APPROVAL_TIMEOUT_MINUTES=120
# 同一广告单次运行中最多使用同一落地页数，默认 1
# MAX_SAME_LANDING_PER_AD_IN_RUN=1
# 落地页品类排除列表（逗号分隔），默认排除常见品类
# LANDING_EXCLUDED_CATEGORIES=早中晚好,祝福音乐,历史名人
# 仅处理指定账户（逗号分隔），已废弃，请使用 --account-id CLI 参数
# CREATION_ONLY_ACCOUNT_IDS=
# 仅处理指定人群包（逗号分隔），为空=全部
# CREATION_ONLY_CROWD_PACKAGES=
# 跳过 Phase0（广告创建），仅执行后续步骤。调试用，默认 0
# CREATION_SKIP_PHASE0=0
# 素材去重回溯天数，默认 7
# CREATIVE_MATERIAL_DEDUPE_LOOKBACK_DAYS=7
# 落地页去重回溯天数，默认 7
# CREATIVE_LANDING_DEDUPE_LOOKBACK_DAYS=7
# 创建恢复回溯小时数，默认 24
# CREATION_RECOVERY_LOOKBACK_HOURS=24

# 统一生产服务
DAILY_CREATION_ENABLED=0
DAILY_CREATION_HOUR=10
DAILY_CREATION_MINUTE=30
DAILY_REVIEW_ENABLED=0
DAILY_REVIEW_INTERVAL_HOURS=2
DAILY_RUN_ON_STARTUP=0
DAILY_REVIEW_RUN_ON_STARTUP=0
DAILY_SYNC_DELIVERY_TEMPLATE=0

# 日级 ROI 北极星指标与表格逐行审批。默认关闭,分阶段启用。
DAILY_ROI_ENABLED=0
DAILY_ROI_HOUR=11
DAILY_ROI_MINUTE=0
DAILY_ROI_RUN_ON_STARTUP=0
# 每天15:30运行独立内部测试，只将“自动化投放”分表发送到“内部”Webhook，不进入腾讯审批执行。
ROI_INTERNAL_TEST_ENABLED=0
ROI_INTERNAL_TEST_HOUR=15
ROI_INTERNAL_TEST_MINUTE=30
# 生产默认去重；测试环境显式设0时每次触发使用独立测试批次。
ROI_INTERNAL_TEST_DEDUP_ENABLED=1
ROI_APPLY_ENABLED=0
ROI_SHEET_APPROVAL_ENABLED=0
ROI_SHEET_APPROVAL_POLL_SECONDS=60
ROI_APPROVAL_TTL_MINUTES=120
# 合格小程序创意三日ROI前20%且广告age>=3时生成扩量建议。
ROI_SCALE_RATIO=1.10
ROI_SCALE_COOLDOWN_DAYS=3
ROI_MAX_BASE_RATIO=2.00
# 小程序使用T-1实际成本5%软预算；公众号即转保留独立实体等权P20。
ROI_SELF_STOP_MIN_AGE=4
ROI_SELF_STOP_COST_SOFT_LOWER_RATIO=0.045
ROI_SELF_STOP_COST_TARGET_RATIO=0.05
ROI_SELF_STOP_COST_SOFT_UPPER_RATIO=0.055
ROI_SELF_STOP_COST_HARD_CAP_RATIO=0.06
ROI_SELF_STOP_THREE_DAY_SHARE=0.60
ROI_SELF_STOP_ONE_DAY_SHARE=0.40
ROI_PARTNER_STOP_QUANTILE=0.20
ROI_UP_QUANTILE=0.80
ROI_OBSERVE_MIN_LATEST_UV=200
# 严格排除三日正式样本；剩余创意需同时满足UV>200、ROI<=0.20和实体等权P10。
ROI_ONE_DAY_MIN_UV=200
ROI_ONE_DAY_HARD_STOP_ROI=0.20
ROI_ONE_DAY_STOP_QUANTILE=0.10
ROI_FISSION_PARAMETER_VERSION=20260712_A0-A15_v2
# ROI报表发送到此群；同时抄送 FEISHU_OPERATOR_CHAT_ID，重复ID自动去重。
# 审批表链接为获得链接者可编辑，黄色审批列选择“批准”即自动执行。
# 为空时依次复用 FEISHU_AD_PROJECT_CHAT_ID / RTC_COMMAND_CHAT_ID
ROI_FEISHU_CHAT_ID=
# 日级ROI定时任务失败告警群；为空时回退FEISHU_OPERATOR_CHAT_ID。
ROI_FAILURE_FEISHU_CHAT_ID=
# 代理表由飞书应用上传后，通过各代理自定义机器人发送在线表卡片。
# 默认关闭；JSON 的 key 使用代理简称（如“棱镜”），“内部”为内部测试专用路由。
ROI_AGENCY_WEBHOOK_ENABLED=0
ROI_AGENCY_WEBHOOKS_JSON={}

RTC_START_HOUR=12
RTC_STOP_HOUR=21
RTC_POLL_SECONDS=600
RTC_HIGH_CPM=250
RTC_LOW_CPM=190
RTC_BID_UP_RATIO=1.05
RTC_MAX_PARTITION_LAG_HOURS=2
RTC_APPLY_ENABLED=0
RTC_COMMAND_ENABLED=1
RTC_COMMAND_CHAT_ID=
RTC_COMMAND_ALLOWED_OPEN_IDS=
RTC_COMMAND_CONFIRM_TTL_MINUTES=10
RTC_COMMAND_WORKERS=2
RTC_COMMAND_NEXT_DELIVERY_HOUR=6
RTC_COMMAND_DRAFT_TTL_MINUTES=5
RTC_NL_COMMAND_ENABLED=0
RTC_COMMAND_LLM_MODEL=google/gemini-3-flash-preview
RTC_COMMAND_LLM_TIMEOUT_SECONDS=20
RTC_COMMAND_LLM_CONFIDENCE_THRESHOLD=0.85
OPEN_ROUTER_API_KEY=

# ========================================
# 飞书 IM 审批配置
# ========================================
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx

# 运营审批群聊（需要审批回复的群）
FEISHU_OPERATOR_OPEN_ID=ou_498988d823b61ab89c9afe4310f85bb4
FEISHU_OPERATOR_CHAT_ID=oc_88e0a1970a7de02eb5ac225a8b0cedea
# 广告审批、创意审批和创建执行汇报专用群；为空时回退运营审批群。
FEISHU_CREATION_CHAT_ID=

# 投放项目群聊（仅通知，不需审批）— 可选配置
# 如何获取群聊ID：运行 python3 get_chat_id.py
# FEISHU_AD_PROJECT_CHAT_ID=oc_xxxxxxxxxxxxxxxxxxxxxx

# 飞书 IM 总开关（1=启用, 0=关闭所有飞书消息），默认 1
# IM_ENABLED=1

# ========================================
# ODPS 数据平台配置
# ========================================
# ODPS_ACCESS_ID=xxx
# ODPS_ACCESS_SECRET=xxx
# ODPS_PROJECT=loghubods
# ODPS 服务端点，默认 http://service.odps.aliyun.com/api
# ODPS_ENDPOINT=http://service.odps.aliyun.com/api

# Datanexus 数据平台（用于 TencentAD 数据查询）
# DATANEXUS_ACCESS_TOKEN=
# DATANEXUS_TOKEN_API=

# ========================================
# LLM / AI 模型配置
# ========================================
# QWEN_API_KEY=xxx
# OPEN_ROUTER_API_KEY=xxx
# OpenRouter 对话补全端点，默认 https://openrouter.ai/api/v1/chat/completions
# OPENROUTER_CHAT_COMPLETIONS_URL=https://openrouter.ai/api/v1/chat/completions
# OpenRouter 图片生成端点，默认 https://openrouter.ai/api/v1/images
# OPENROUTER_IMAGES_URL=https://openrouter.ai/api/v1/images
# AI 图片生成模型，默认 google/gemini-3.1-flash-image
# OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image
# AI 文本生成模型，默认 google/gemini-3-flash-preview
# OPENROUTER_TEXT_MODEL=google/gemini-3-flash-preview
# AI 素材审核模型，默认 google/gemini-3-flash-preview
# AI_MATERIAL_REVIEW_MODEL=google/gemini-3-flash-preview

# ========================================
# AI 素材生成（图片 + 封面文案）
# ========================================
# 是否使用图案选择器（1=启用, 0=关闭），默认 1
# AI_IMAGE_USE_PATTERN_SELECTOR=1
# 图案选择器返回 Top K 结果，默认 1
# AI_IMAGE_PATTERN_TOP_K=1
# 图片生成版位，默认 WECHAT_OFFICIAL_ACCOUNTS
# AI_IMAGE_PATTERN_PLACEMENT=WECHAT_OFFICIAL_ACCOUNTS
# 是否生成封面文案（1=启用, 0=关闭），默认 1
# AI_COVER_COPY_REQUIRED=1
# 封面文案最大 token 数，默认 900
# AI_COVER_COPY_MAX_TOKENS=900
# 封面文案标题最大长度（字符），默认 22
# AI_COVER_COPY_TITLE_MAX_LEN=22
# OSS 上传路径前缀，默认 auto_put_tencent/image
# AI_IMAGE_OSS_PREFIX=auto_put_tencent/image
# 图片宽高比，默认 16:9
# AI_IMAGE_ASPECT_RATIO=16:9
# 图片分辨率，默认 1K
# AI_IMAGE_RESOLUTION=1K
# 图片输出格式，默认 jpeg
# AI_IMAGE_OUTPUT_FORMAT=jpeg
# 图片目标宽度(px)，默认 1280
# AI_IMAGE_TARGET_WIDTH=1280
# 图片目标高度(px)，默认 720
# AI_IMAGE_TARGET_HEIGHT=720
# 自定义图片生成 Prompt 模板路径（留空=使用内置模板）
# AI_IMAGE_PROMPT_TEMPLATE_PATH=
# 自定义内容安全 Prompt 模板路径（留空=使用内置模板）
# AI_SANITIZE_PROMPT_TEMPLATE_PATH=
# 自定义封面文案 Prompt 模板路径（留空=使用内置模板）
# AI_COVER_COPY_PROMPT_TEMPLATE_PATH=

# ========================================
# 阿里云 OSS（AI 图片上传存储）
# ========================================
# ALIYUN_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
# ALIYUN_OSS_BUCKET=your-bucket
# 也可用 AI_IMAGE_OSS_BUCKET 替代 ALIYUN_OSS_BUCKET
# AI_IMAGE_OSS_BUCKET=your-bucket
# ALIYUN_OSS_ACCESS_KEY_ID=xxx
# ALIYUN_OSS_ACCESS_KEY_SECRET=xxx
# OSS 公开访问基础 URL（用于生成图片外链）
# AI_IMAGE_PUBLIC_BASE_URL=https://your-bucket.oss-cn-hangzhou.aliyuncs.com

# 外部素材召回账户专用。飞书「素材来源」填”外部素材”或”外部素材召回”时生效。
EXTERNAL_RECALL_SOURCE_LABEL=外部合作
EXTERNAL_RECALL_CANDIDATE_LIMIT=300
EXTERNAL_RECALL_EDIT_LIMIT_PER_LANDING=3
EXTERNAL_RECALL_UV_WINDOW_DAYS=90
# 默认复用 OPENROUTER_IMAGE_MODEL；可单独指定支持 input_references 的图片模型。
# EXTERNAL_IMAGE_MODEL=google/gemini-3.1-flash-image

# ========================================
# 视频召回与风控
# ========================================
# 视频风控 API 地址
# VIDEO_RISK_API_URL=https://longvideoapi.piaoquantv.com/longvideoapi/openapi/video/getVideoTagIds
# 视频风控最大允许级别，默认 5（超过则拒绝）
# VIDEO_RISK_MAX_ALLOWED_LEVEL=5
# 视频风控 API 超时秒数，默认 10
# VIDEO_RISK_API_TIMEOUT_SECONDS=10
# 视频召回并发数，默认 4
# RECALL_PARALLEL_MAX_WORKERS=4
# 单视频召回查询上限，默认 12
# RECALL_QUERY_LIMIT_PER_VIDEO=12
# 飘泉 TV 登录手机号（素材召回用）
# CONTENTPLATFORM_TEL_NUM=
# 飘泉 TV 登录密码（素材召回用）
# CONTENTPLATFORM_PASSWORD=
# 飘泉 TV 静态 Token（可选，优先使用动态登录）
# PIAOQUANTV_TOKEN=
# 飘泉 TV 视频来源过滤
# PIAOQUANTV_VIDEO_SOURCE=
# 飘泉 TV 视频类型过滤
# PIAOQUANTV_VIDEO_TYPE=
# 热门素材兜底开关（1=启用，召回量不足时自动回退热门源），默认 1
# PIAOQUANTV_HOT_FALLBACK_ENABLED=1
# 热门素材兜底来源标签，默认 hot
# PIAOQUANTV_HOT_FALLBACK_SOURCE=hot
# 飘泉 TV 视频最大页数，默认 3
# PIAOQUANTV_VIDEO_MAX_PAGES=3
# 落地计划保存接口地址
# PIAOQUANTV_XCX_SAVE_URL=https://tp-open.piaoquantv.com/contentPlatform/plan/xcx/save
# 视频向量检索服务地址
# VECTOR_BASE_URL=https://api-internal.piaoquantv.com/videoVector
# 人群包→素材来源映射（JSON），为空时使用内置默认值
# VIDEO_RECALL_CROWD_PACKAGE_MAP=
# 素材来源标签映射（JSON），为空时使用内置默认值
# VIDEO_RECALL_SOURCE_MAP=

# ========================================
# 创意审核扫描
# ========================================
# 审核扫描回溯小时数，默认 72
# CREATIVE_REVIEW_LOOKBACK_HOURS=72
# 审核扫描单次上限，默认 1000
# CREATIVE_REVIEW_SCAN_LIMIT=1000
# 审核扫描批次大小，默认 100
# CREATIVE_REVIEW_BATCH_SIZE=100

# ========================================
# 数据库配置（MySQL）
# ========================================
DB_HOST=localhost
DB_PORT=3306
DB_USER=ad_rw
DB_PASSWORD=your_password
DB_NAME=auto_put_ad_mini
# 数据库连接超时秒数，默认 10
# DB_CONNECT_TIMEOUT=10
# 数据库读超时秒数，默认 60
# DB_READ_TIMEOUT=60
# 数据库写超时秒数，默认 60
# DB_WRITE_TIMEOUT=60

# ========================================
# 生产环境配置（海外部署）
# ========================================

# 白名单账户（逗号分隔）
# 注意：优先从数据库读取，数据库不可用时降级到环境变量
WHITELIST_ENABLED=true
WHITELIST_ACCOUNTS=80769799,71305011

# 代理配置（海外访问腾讯 API）
# HTTP_PROXY=http://proxy-server:port
# HTTPS_PROXY=http://proxy-server:port

# 时区配置（默认 UTC，可选 Asia/Shanghai）
TZ=UTC

# 执行开关（生产环境谨慎开启）
# 注意：优先从数据库读取，数据库不可用时降级到环境变量
EXECUTION_ENABLED=false

# API 端点（可选覆盖）
# TENCENT_AD_BASE_URL=https://api.e.qq.com/v3.0

# APScheduler 定时调度（使用 server.py 时）
# CRON_SCHEDULE=0 2 * * *  # 每天凌晨2点UTC
# RUN_ON_STARTUP=false     # 启动时是否立即执行
# PORT=8080                # FastAPI 服务端口

# ========================================
# 高级配置（通常无需修改）
# ========================================

# -- 腾讯广告 AccessToken 动态获取 API --
# 默认 https://api.piaoquantv.com/ad/put/tencent/getAccessToken
# TENCENT_AD_TOKEN_API=https://api.piaoquantv.com/ad/put/tencent/getAccessToken

# -- ROI 策略补充参数 --
# 自投提价最小广告天数，默认 3
# ROI_SELF_UP_MIN_AGE=3
# 自投最小日均 UV，默认 200（也支持旧名 ROI_SELF_MIN_AVG_UV）
# ROI_SELF_MIN_DAILY_UV=200
# 代投最小日均 UV，默认 200（也支持旧名 ROI_PARTNER_MIN_AVG_UV）
# ROI_PARTNER_MIN_DAILY_UV=200
# 关停分位数（ROI_PARTNER_STOP_QUANTILE 的回退值），默认 0.20
# ROI_STOP_QUANTILE=0.20
# 关停权重上限分位数，默认 0.95
# ROI_STOP_WEIGHT_CAP_QUANTILE=0.95
# 素材策略学习 - 模型最低评分阈值，默认 75
# PATTERN_SELECTOR_MIN_MODEL_SCORE=75
# ROI 参数发布者标识，默认取系统 USER 环境变量
# ROI_PARAMETER_PUBLISHED_BY=

# -- 定时任务调度锁（多实例互斥） --
# 每日创建任务锁名，默认 ad_daily_creation
# DAILY_CREATION_LOCK_NAME=ad_daily_creation
# 每日创建 misfire 容忍秒数，默认 3600
# DAILY_CREATION_MISFIRE_GRACE_SECONDS=3600
# 每日审核扫描锁名，默认 ad_creative_review_scan
# DAILY_REVIEW_LOCK_NAME=ad_creative_review_scan
# 每日 ROI 任务锁名，默认 ad_daily_roi
# DAILY_ROI_LOCK_NAME=ad_daily_roi
# 每日 ROI misfire 容忍秒数，默认 3600
# DAILY_ROI_MISFIRE_GRACE_SECONDS=3600
# 每日 ROI 内部测试锁名，默认 ad_daily_roi
# DAILY_ROI_INTERNAL_TEST_LOCK_NAME=ad_daily_roi
# ROI 内部测试 misfire 容忍秒数，默认 3600
# ROI_INTERNAL_TEST_MISFIRE_GRACE_SECONDS=3600
# 实时调控 DB 锁名，默认 tencent_realtime_control
# RTC_DB_LOCK_NAME=tencent_realtime_control

# -- 人群包授权 --
# 人群包来源账户 ID，默认 55615440
# TENCENT_AUDIENCE_SOURCE_ACCOUNT_ID=55615440
# 人群包授权业务 ID，默认 0
# TENCENT_AUDIENCE_GRANT_BUSINESS_ID=0