Agent/examples/auto_put_ad_mini/CLAUDE.md

auto_put_ad_mini — 广告智能调控 Agent

工作目录: examples/auto_put_ad_mini/ 业务场景: 微信小程序投流 核心目标: 基于 ROI + 跑量双维度，自动给出广告粒度的操作决策

项目定位

auto_put_ad_mini 是 auto_put_ad 终极体系中 Monitor/调控 Agent 的前身。 当前阶段独立运行，只做"数据→决策→执行"单向链路。

项目结构

examples/auto_put_ad_mini/
├── run.py                    # 运行入口（Agent 交互模式）
├── execute_once.py           # 单次执行入口（10 步 pipeline）
├── config.py                 # 业务配置（ROI 阈值、出价边界等）
├── presets.json              # 预设参数
├── strategy_params.json      # 策略参数
├── prompts/
│   └── system.prompt         # Agent 系统 Prompt
├── tools/
│   ├── ad_api.py             # 腾讯广告 API 封装
│   ├── ad_decision.py        # 广告决策引擎（候选信号 + LLM 评估）
│   ├── data_query.py         # ODPS 数据查询
│   ├── roi_calculator.py     # ROI 计算（动态ROI）
│   ├── guardrails.py         # 安全护栏
│   ├── execution_engine.py   # 执行引擎（API 调用 + 审计）
│   ├── im_approval.py        # 飞书审批（阻塞式轮询）
│   ├── report_generator.py   # 报告生成（Excel + 飞书表格）
│   ├── feishu_doc.py         # 飞书文档操作
│   ├── creative_metrics.py   # 创意级数据指标
│   ├── odps_module.py        # ODPS 数据源模块
│   ├── portfolio_metrics.py  # 组合级指标聚合
│   └── posterior_collector.py # 后验数据收集
├── skills/                   # 领域知识（框架自动注入）
│   ├── ad_domain.md          # 业务模型：裂变模型、ROI公式
│   ├── platform_rules.md     # 平台硬约束
│   ├── decision_framework.md # 决策框架：候选标记 + 年龄策略
│   ├── action_playbook.md    # 动作手册：7种action
│   └── posterior_wisdom.md   # 后验经验
└── outputs/                  # 运行输出

关键配置入口

• 决策阈值（关停线、降价线、提价线）→ config.py
• 决策逻辑（候选标记、年龄保护、权衡原则）→ skills/*.md
• Agent行为（工具编排、输出规范）→ prompts/system.prompt

业务规则以 config.py 和 skills/ 为准，本文件不重复描述。

---

🚨 工程纪律:不推导,不猜测(2026-06-05 用户多次确认)

绝对禁止凭"常识 / 文档框架 / 命名规律"推断或猜测字段值、枚举名、参数结构、业务规则。

三段式处理原则

情况	必须做的
不确定	查询(读代码、读真实数据、读文档、调 API 反查)
查不到	直接反问用户,不要硬给一个"可能值"
要写代码	拿到确切答案后才下手

适用范围(全部)

• 腾讯广告 v3.0 API 字段名 / 枚举值 / 嵌套结构
• 业务配置项的默认值 / 取值策略
• 字段语义(比如"稳定拿量"= 哪个 enum?)
• 各种 ID(account_id、audience_pack_id、conversion_id、user_action_set_id...)
• LLM 推理框架的具体阈值
• 工作流的执行顺序

反例(过去犯过的错)

我猜测	实际值	教训
marketing_carrier_type=MINI_PROGRAM_WECHAT	JUMP_PAGE	凭文档常识猜,错
smart_bid_type=SYSTEMATIC(稳定拿量)	CUSTOM + 配 bid_strategy=AVERAGE_COST + auto_acquisition=True 三件套	凭命名猜单字段,错
optimization_goal=PAGE_VIEW	PROMOTION_VIEW_KEY_PAGE	凭含义猜枚举名,错
auto_acquisition_enabled=False	True	凭"SOP 关闭智能"猜,错
daily_budget=20000(200 元)	0(不限,由 auto_acquisition_budget 控)	凭习惯猜,错

验证手段优先级

1. 拉真实数据反推(最准):/adgroups/get 查已跑通的广告 JSON
2. 读现有代码:tools/ad_api.py 中已封装的真实参数
3. 读官方文档(WebFetch 可能失败/有总结失真,作为辅助参考)
4. dry run 试错(用 configured_status=AD_STATUS_SUSPEND 试创建,看腾讯报错)
5. 反问用户

哪些 WebFetch 等"二手"信息要警惕

• 文档页面如果只返回标题/header → 内容无效,不能引用
• WebFetch 返回的"原文照搬"结果,可能是 AI 处理过的摘要,字段类型 / 必填性 / 枚举值 都可能被简化
• → 二手信息只用于"知道有这字段",具体值必须从真实数据反推

这条规则比任何 plan / skill / config 都优先级高。