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 推理 → 决策合并 → 护栏 → 审批 → 执行 → 报告。每步前置依赖严格。

01
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
02
merge_creative_data
tools/data_query.py

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

outputs/merged/merged_{date}.csv
03
calculate_roi_metrics
tools/roi_calculator.py

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

outputs/metrics_{date}.csv (广告级)
04
portfolio_metrics
tools/portfolio_metrics.py

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

outputs/portfolio_summary/portfolio_summary_{date}.json
05
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[ ]
06
LLM 推理(分批)
主 Agent

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

JSON 累积数组(全部 tier)
07
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
08
validate_decisions
tools/guardrails.py

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

outputs/reports/validated_decisions_{date}.csv
09
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}/
10
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
2

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

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。
永久