Agent 项目级改代码原则

适用范围

本仓库包含生产级自动投放系统。凡是修改 examples/auto_put_ad_mini 下的代码,都要按生产自动化系统处理,不能当成一次性脚本。

生产自动化原则

优先使用数据库和飞书配置,避免硬编码账户级参数。
人工配置应尽量只包含账户 ID、人群包名称、出价、预算、是否执行。
每日自动流程应根据腾讯侧当前状态自行判断是否需要创建广告或补创意。
飞书配置行关闭时,只代表不再新建广告或补创意,不能因此暂停、删除或改动既有广告。
尽量保持幂等。重复运行时应跳过已完成的工作,只补缺口。

模块 B 创意创建规则

目标是单广告最终合格创意数,不是单次生成的 pending 行数。
当前目标:每条广告最终有效创意不少于 4 个。
DENIED 创意不计入有效创意。
每次创意准备中,每个视频来源最多获取并尝试 100 条视频。
先尝试 primary 视频来源。
如果 primary 视频经过品类过滤、风险审核、素材质量过滤后仍无法产出可用 pending creative,再用同一个 crowdPackage 尝试 source=hot。
source=hot 只能改变内容服务的视频来源,不能改变账户配置的人群包。
hot 兜底必须走和 primary 完全一致的品类过滤、风险审核、素材召回和审批流程。

承接视频安全和质量

创建落地计划或腾讯创意前,必须先做视频风险审核。
默认风险阈值是 1。风险等级 2-10 应拦截。
风险接口异常时要保守处理,不能创建落地计划。
使用 videoContentList.category 做内容品类过滤。
默认过滤品类是 早中晚好、祝福音乐。
品类过滤必须发生在风险审核、素材召回和 xcx/save 之前。
不要把 categoryName 当作内容品类使用;它是召回逻辑使用的语义/视觉特征字段。

素材召回规则

除非用户明确要求,不要随意降低素材质量门槛。
当前素材门槛:impressions > 2000、ctr >= 0.10、统计窗口 180 天。
视频可以通过风险审核,但仍然因为没有素材满足质量门槛而不能被选中。
不能为了凑满创意数量而静默降低素材质量阈值。

腾讯人群包和资产规则

创建广告前,人群包 ID 必须验证为目标广告账户可见。
跨账号使用人群包时,要走腾讯人群授权接口,授权后再次验证目标账户可见。
品牌图 ID 是账户级资产,不能复用其他账户的 brand_image_id。
监测链接 feedback_id 是账户级资产,应通过配置模板查找或创建。

飞书同步规则

飞书配置同步是每日主流程的一部分。
飞书同步失败时应停止创建流程。
是否自动化执行 不等于 是 时,只关闭新建/补量,不删除 DB 配置,不修改腾讯既有资产。
不要因为飞书行被关闭就删除或回滚线上状态。

代码修改纪律

修改范围要收敛在当前生产链路相关模块内。
运营可能需要调整的生产行为,应提供配置项。
属于账户、人群包、预算、出价、品牌、监测链接的值,优先进入飞书或 DB,不要写死在代码里。
端到端执行前,必须意识到可能产生外部副作用:腾讯广告/创意创建、图片上传、DataNexus 监测链接创建、人群包授权、xcx/save 落地计划创建。
端到端流程中断时,已经完成的外部副作用不会自动回滚。
行为、环境变量或运营流程变化时,要同步更新面向生产的文档。