Reson Agent · 业务示例 · v0.4.27

auto_put_ad_mini

数据驱动的广告调控 Agent —— 把 ODPS 裂变数据、动态 ROI、规则候选与 LLM 综合判断,串成单向链路的 ROI 优化系统。

业务场景微信小程序投流

承载类型 MARKETING_CARRIER_TYPE_
MINI_PROGRAM_WECHAT

出价模式 BID_MODE_OCPM

LLM 后端 OpenRouter · Claude Sonnet 4.5

数据窗口 14 天 / 7 日均值

执行开关 EXECUTION_ENABLED = False

入口 run.py · execute_once.py

部署 K8s CronJob · 02:00 UTC

§ 01 — 整体架构

框架与业务的双层解耦

框架(agent/)只关心 LLM 调度 + 工具调度 + 持久化,完全不感知业务。业务层通过 @tool 装饰器和 .md skill 单向注入,从不反向依赖。

L1 · Framework

Reson Agent

通用 Agent 框架,只读,业务零侵入。

AgentRunner · ReAct 主循环 · new/resume/rewind
ToolRegistry · @tool 装饰器 + JSON Schema
SkillLoader · 扫 .md + frontmatter 注入 prompt
FileSystemTraceStore · 持久化 .trace/ + 侧分支
LLM 适配层 · OpenRouter / Qwen / Gemini

L2 · Skills

领域知识

4 份 markdown,启动时注入 system prompt,定义业务术语 + 决策原则 + 平台硬约束。

ad_domain · R 值人群 + 裂变变现模型
platform_rules · 腾讯平台硬约束(优先级最高)
decision_strategy · 7 action 决策框架(核心 19.5K)
posterior_wisdom · 后验经验查询入口

L3 · Tools

业务工具

10+ 个工具组成 10 步流水线,从数据采集到决策执行单向流转。

data_query · ODPS 拉数 + 多日合并
roi_calculator · 创意聚合 + 动态 ROI
portfolio_metrics · 渠道 P50 + tier 基线
ad_decision · 候选标记 + 决策合并
guardrails · 护栏校验
execution_engine · 分级执行 + 审计
im_approval · 飞书审批 + 阻塞 polling
report_generator · Excel 决策表
feishu_doc · 飞书文档 + IM 推送
ad_api · 腾讯广告 API 封装

L4 · Config

硬约束与开关

所有阈值、白名单、执行开关集中于 config.py。运行时可被数据库覆盖。

ROI 阈值 · ROI_LOW_FACTOR = 0.75
调价边界 · BID_FLOOR/CEILING = 0.05/1.00 元
年龄保护 · COLD_START_DAYS = 3, EARLY_GROWTH_DAYS = 7
频率限制 · MAX_ADJUSTMENTS_PER_AD_PER_DAY = 2
执行开关 · EXECUTION_ENABLED = False

§ 02 — 数据流水线

十步,从 ODPS 到飞书

单向链路:数据采集 → 指标计算 → 候选筛选 → LLM 推理 → 决策合并 → 护栏 → 审批 → 执行 → 报告。每步前置依赖严格。

fetch_creative_data

tools/data_query.py

从 ODPS 表 loghubods.touliu_data 增量拉取 14 天创意级原始数据(消耗、首层打开数、T0 裂变数、总回流人数、总收入)。已存在的日期文件自动跳过。

outputs/raw/creative_{date}.csv outputs/ad_status/ad_status_{date}.csv

merge_creative_data

tools/data_query.py

每日 raw + 广告状态做 left join,前置过滤 DELETED/SUSPEND 状态。生成单日 merged CSV。

outputs/merged/merged_{date}.csv

calculate_roi_metrics

tools/roi_calculator.py

加载 30 天 merged · 创意 → 广告聚合 · 计算 动态ROI = 当日裂变收益率 × 裂变效率稳定因子 · 7 日滚动均值(min_periods=3)· 日消耗 < 100 元的天数标 NaN 不入均值。含临时 TEMP 块过滤近 7 天累计消耗 = 0 的广告。

outputs/metrics_{date}.csv (广告级)

portfolio_metrics

tools/portfolio_metrics.py

在 calculate_roi_metrics 内自动调用。计算渠道 P25/P50/P75 ROI 基线 + 人群包(tier)级 fission/CTR/bid 均值,作为决策对比基准。

outputs/portfolio_summary/portfolio_summary_{date}.json

get_ads_for_review

tools/ad_decision.py

三层分类:零消耗待关停 / 候选广告 / 正常运行。计算 5 个候选标记:roi_low、decay_signal、bid_up_candidate(双分支)、bid_down_candidate、scale_up_candidate。年龄保护:≤3 天剔除,4-7 天屏蔽负向标记。按 audience_tier 分批返回。

JSON: tier_batches[ ]

LLM 推理(分批)

主 Agent

按 tier 分批调用,降低单次输入 60-80%(避免 lost in the middle)。每批 LLM 输出决策 JSON 数组(action/dimension/reason/confidence/recommended_change_pct)。禁止多次调 apply_decisions(后调吞前调)。

JSON 累积数组(全部 tier)

apply_decisions

tools/ad_decision.py

合并三类决策来源:零消耗自动关停(规则) + LLM 输出(主) + 正常运行兜底 hold(规则)。左连接 metrics CSV 补全(ad_name / ad_age_days / cost_7d_avg / 动态ROI / audience_tier 等 20+ 字段)。

outputs/reports/llm_decisions_{date}.csv

validate_decisions

tools/guardrails.py

护栏校验:冷启动保护、出价上下界(0.05-1.00 元)、单日调整频率(≤2 次)、单次累计变化(≤20%)、数据新鲜度(≤96h)。失败的决策会被强制改 hold + 记录原因。

outputs/reports/validated_decisions_{date}.csv

send_approval_request

tools/im_approval.py · feishu_doc.py

前置过滤 FEISHU_EXCLUDE_ACTIONS = {hold, observe, scale_up, bid_up}(消息和表格用同一份过滤后数据,数字一致)。生成审批 xlsx 上传飞书文档,带预览链接的卡片推送给操作员私聊 + 项目群,阻塞轮询 chat_history 等回复(超时 120 分钟)。

飞书 sheets URL · approvals/{request_id}/

execute_decisions + send_feishu_text_message

tools/execution_engine.py · ad_api.py

分级执行(tier 1 自动 / tier 2-3 审批通过)。EXECUTION_ENABLED=False 时仅 log 不调腾讯 API。完成后发送简单文字摘要("已执行 N 条:关停 X / 降价 Y"),不再发完整报告。

outputs/execution_log/{date}.csv 飞书文字消息

§ 03 — 领域知识(Skills)

注入 prompt 的四份手册

.md + YAML frontmatter,框架启动时按 name 索引,内容拼接到 system prompt 末尾。冲突优先级:platform-rules > decision-strategy > posterior-wisdom > ad-domain。

CORE

decision_strategy.md

决策的判断框架与 reason 输出规范

19.5 KB · 约 570 行 · 决策 80% 重量

真正的"作战手册"。三层架构(规则候选 → LLM → 输出规范),三维对比基准(ROI 看渠道P50,裂变看同类,CTR 看同类),7 种 action 详解 × 触发前提 × 综合权衡 × pct 要求 × 禁用场景。reason 5 元组模板 + 提交前自检 5 问。

§一 · 角色与原则 §二 · 候选标记解读 §三 · 年龄策略 §四 · 决策思考 5 步 §五 · 7 action 详解 §六 · 多因素权衡 + 冲突表 §七 · 输出规范 + 自检

DOMAIN

ad_domain.md

微信小程序投流的业务模型

6.5 KB · 业务知识基底

解释裂变变现模型("每一层都在变现",非线性漏斗)、R 值人群含义(R500/R330+/R330/R180/R100/R50/R10/R2 的带人能力 + 投放单价 + 当日 ROI 表现)、动态 ROI 公式与字段定义。

变现模型 R 值对照表动态 ROI 公式字段定义

PLATFORM

platform_rules.md

腾讯广告平台硬约束

5.3 KB · 优先级最高

oCPM 学习期(前 5 转化 / 24h 内 ≤2 次调整)、调价幅度上限(单次 ≤30%)、少广告多素材策略(单广告创意数 ≥5)、素材疲劳识别、数据口径(T+1 而非实时)、API QPS 与批量限制。

学习期保护调价上限数据口径 API 约束

POSTERIOR

posterior_wisdom.md

后验经验查询入口

0.8 KB · 待积累

通过 ask_knowledge() 查询历史投放案例。当前系统尚未积累足够后验数据,提供查询模板:周期性效应、调价效果、人群包对比、异常模式、创意冷启动等。

ask_knowledge 查询模板

§ 04 — 工具清单

十二个 tool · 按数据流向排序

每个工具用 @tool 装饰注册到 ToolRegistry,JSON Schema 自动生成。隐藏参数(context、trace_id)由 Runner 注入,LLM 看不到。

文件 / 函数

分类

职责

所属步骤

data_query.py

DATA

fetch_creative_data + merge_creative_data · 从 ODPS 拉创意级原始数据,合并多日 + 广告状态。

Step 01—02

roi_calculator.py

COMPUTE

calculate_roi_metrics · 创意 → 广告聚合,计算动态 ROI(7 日均值 + 裂变效率稳定因子)。

Step 03

portfolio_metrics.py

COMPUTE

_describe_group + _compute_daily_tier_snapshot + _compute_market_signal · 渠道 P25/P50/P75 + tier 均值,作为决策基线。

Step 04

ad_decision.py

DECIDE

get_ads_for_review + apply_decisions + query_ad_detail + modify_decisions · 候选标记 + 三层分类 + LLM 决策合并。

Step 05, 07

guardrails.py

VALIDATE

validate_decisions · 冷启动 / 出价边界 / 频率 / 数据新鲜度多重护栏校验,失败强制改 hold。

Step 08

execution_engine.py

EXECUTE

execute_decisions + _classify_tier · 分级执行,EXECUTION_ENABLED 控制是否真改腾讯 API。

Step 10

im_approval.py

EXECUTE

send_approval_request + send_feishu_text_message · 飞书审批阻塞轮询,FEISHU_EXCLUDE_ACTIONS 前置过滤。

Step 09—10

report_generator.py

REPORT

generate_report · 带条件格式的 Excel 决策表(action 颜色编码)。

Step 10

feishu_doc.py

REPORT

import_to_feishu · 上传 xlsx 到飞书文档,设置权限,带预览链接的 IM 卡片推送。

Step 09

ad_api.py

EXECUTE

腾讯广告 Marketing API v3.0 封装(/v3.0/adgroups/get / update),指数退避 + 操作幂等键。

Step 10

creative_metrics.py

COMPUTE

创意级数据指标聚合,服务于 ROI 计算上游。

Step 03 (内部)

odps_module.py

DATA

ODPS 客户端封装,SQL 模板执行 + tunnel session 下载。

Step 01 (内部)

§ 05 — 决策框架

规则与 LLM 的四层协作

规则定"是否评估",LLM 定"如何操作"。年龄保护是硬约束,候选标记决定进入 LLM 的范围,LLM 在已限定的边界内做综合判断,兜底层覆盖未决策广告。

L1 · Hard Gate

年龄保护(硬约束)

≤COLD_START_DAYS(3 天):完全剔除,不评估。
4-EARLY_GROWTH_DAYS(7 天):屏蔽 roi_low / decay_signal / bid_down_candidate,只放过提价/扩量信号。

L2 · Rule

候选标记(5 个 flag)

规则层在 get_ads_for_review 中输出 roi_low / decay_signal / bid_up_candidate(双分支:唤醒沉默 + 优质放量) / bid_down_candidate / scale_up_candidate。决定哪些广告进入 LLM。

L3 · LLM

综合判断(7 action)

LLM 看候选标记 + 同类基线 + 调价历史 + tier 组合,从 7 种 action 中选一个 + 写 reason(5 元组规范)。可"越权":如规则没标但有强烈信号。

L4 · Fallback

兜底检查(规则)

apply_decisions 末尾,所有未被 LLM 覆盖的广告自动归 hold(source=规则判断)。确保所有候选都有决策落盘,无遗漏。

7 种 Action 触发条件

pause

roi_low=True + LLM 综合判断(双低/调价无效);或 7 日均消耗<10 自动关停。pct = 0。

bid_down

bid_down_candidate=True + 裂变低于同类 + 成熟期 + 7 日均消耗 ≥500。pct ∈ [-5%, -3%]。

bid_up

bid_up_candidate=True(仅 4-7 天)。分支 A 唤醒沉默(低消耗 + CTR 正常)/ 分支 B 优质放量(高 ROI + 高裂变)。pct ∈ [+5%, +10%]。

scale_up

scale_up_candidate=True(成熟 >7 天 + 稳定 ≥7 天 + 高消耗 >1000 + ROI ≥ P50×0.9)。pct = 0(由运营新增广告/创意)。

creative_adjust

ROI 达标但消耗起不来 / CTR + CVR 同跌(素材疲劳)/ 已换创意但裂变仍低。pct = 0,人工换素材。

observe

数据不充分(roi_valid_days <5)/ 7 天内已调价(等效果显现)/ 信号冲突(ROI 低但裂变好)。pct = 0。

hold

无异常信号(默认兜底)。pct = 0。

§ 06 — 关键阈值

决策的数值边界

所有阈值集中在 config.py,部分可被数据库 tencent_ad_autoput.config 表覆盖。修改前应通过 evaluation 验证。

ROI_LOW_FACTOR

0.75

关停线乘子 · 动态ROI < 渠道P50×0.75 → 候选关停

BID_DOWN_ROI_FACTOR

0.90

降价线乘子 · ROI < P50×0.90 + 裂变低 → 候选降价

BID_UP_ROI_FACTOR

1.05

提价线乘子 · ROI > P50×1.05 + 早期成长期 → 候选提价

COLD_START_DAYS

3 天

冷启动期 · 完全保护,不评估,不调整

EARLY_GROWTH_DAYS

7 天

早期成长期 · 仅允许 bid_up / scale_up

MIN_DAILY_COST

100 元

日消耗 < 100 元 → ROI 当日数据不入 7 日滚动均值

NO_SPEND_THRESHOLD

10 元

7 日均消耗 < 10 → 自动 pause(年龄>7 天)

BID_DOWN range

3 — 5%

降价幅度 · 单次绝对值上限 5%(更严守)

BID_UP range

5 — 10%

提价幅度 · 单次绝对值上限 10%(可放宽)

BID_FLOOR / CEILING

0.05 — 1.00元

出价硬边界 · 任何调整不得突破

MAX_ADJUSTMENTS_PER_AD_PER_DAY

单广告每日最大调整次数 · 平台学习期防抖

EXECUTION_ENABLED

false

执行开关 · 默认关闭,所有操作走审批不真改

§ 07 — 数据流向

从 ODPS 到腾讯广告 API

外部数据源 → 本地落盘 → 内存计算 → LLM 调用 → 飞书人机交互 → 腾讯广告写入。所有中间产物均落盘,可独立回放。

§ 08 — 部署形态

两种运行模式

本地交互(REPL,人工触发分析)+ K8s CronJob(每日 02:00 UTC 自动跑)。共享同一份代码 + skill + tool。

Mode A · Interactive

run.py · REPL

手工启动 Agent,交互式问答。适合临时分析单个广告 / 修改决策 / 调试 skill。Agent 在每轮等待用户输入,可执行任意工具。

$ .venv/bin/python3 run.py

Mode B · Batch

execute_once.py · 单次执行

一次性走完 10 步流水线,自动取 T-1(昨天)作为数据日期。K8s CronJob 直接调度,可手工调试。完成后退出。

$ .venv/bin/python3 execute_once.py cron 0 2 * * * UTC (每日 02:00)

K8s 资源 deployment.yaml · 1 副本 + Service + PVC(挂 /app/outputs)
cronjob.yaml · 02:00 UTC + forbidConcurrent + 2h deadline
configmap.yaml · 公开环境变量
secret.yaml · ODPS / Feishu / 腾讯广告凭证
network-policy.yaml · 限制 Pod 出入流量

§ 09 — 输出物

每次执行留下的痕迹

所有中间产物均落盘到 outputs/,可独立回放或调试。生产环境通过 PVC 持久化。

路径

类型

用途

持久化

outputs/raw/

CSV (per day)

ODPS 创意级原始数据。增量缓存,已存在跳过。

14 天

outputs/merged/

CSV (per day)

合并多日 + 广告状态快照。下游 ROI 计算的输入。

30 天

outputs/metrics_*.csv

CSV (latest)

广告级指标:动态 ROI 7 日均值、cost_7d_avg、ad_age_days、creative_count 等 30+ 字段。

每日

outputs/portfolio_summary/

JSON

渠道 P25/P50/P75 + tier 级 fission/CTR/bid 均值。

每日

outputs/reports/llm_decisions_*.csv

CSV

LLM 输出 + 规则补全的完整决策表。20+ 字段。

每日

outputs/reports/validated_decisions_*.csv

CSV

护栏校验后的决策表(失败的强制改 hold)。

每日

outputs/approvals/{request_id}/

XLSX + JSON

飞书审批表 + 请求/响应缓存。

永久

outputs/execution_log/

CSV

执行审计:每条决策的 API 调用结果。

永久

.trace/{trace_id}/

JSON

框架 Trace 持久化:meta + GoalTree + 所有 messages + events。

永久