内容投放 ROI 计算器

根据用户提供的投放数据，计算标准营销效果指标，对比行业基准，输出结构化分析报告。

输入

用户提供以下字段的任意子集（缺失字段跳过其依赖指标）：

字段	代号	单位	必要性
投放费用	ad_spend	CNY	核心（为 0 或缺失时切换有机模式）
曝光量	impressions	次	可选
点击量	clicks	次	可选
互动量	engagements	次（赞+评+转）	可选
转化数	conversions	次	可选
客单价	avg_order_value	CNY	可选
内容制作成本	production_cost	CNY	可选，默认不计

两种模式：

• Mode A — 单活动分析：一组输入数据，输出完整指标卡片
• Mode B — 多活动对比：多组数据（表格或逐条），按 ROI 降序排列，横向对比

输出

指标计算（公式表）

以下指标仅在分母数据存在且非零时计算，否则标注"数据不足，已跳过"：

指标	公式	依赖字段
CTR（点击率）	clicks / impressions	impressions, clicks
CPC（单次点击成本）	ad_spend / clicks	ad_spend, clicks
CPM（千次曝光成本）	(ad_spend / impressions) * 1000	ad_spend, impressions
CPE（单次互动成本）	ad_spend / engagements	ad_spend, engagements
转化率	conversions / clicks	conversions, clicks
CPA（单次转化成本）	ad_spend / conversions	ad_spend, conversions
营收	conversions * avg_order_value	conversions, avg_order_value
ROAS（广告支出回报率）	revenue / ad_spend	revenue, ad_spend
总成本	ad_spend + production_cost	ad_spend（production_cost 缺失按 0）
利润	revenue - total_cost	revenue, total_cost
ROI	(revenue - total_cost) / total_cost	revenue, total_cost

输出格式

Mode A — 单活动分析：

## 投放效果报告

### 基础数据
（用户提供的原始字段）

### 计算指标
| 指标 | 值 | 公式 | 基准对比 |
|------|----|------|----------|
| CTR  | x% | clicks/impressions | ▲ 高于行业均值 |
| ...  |    |      |          |

### 基准对比图例
▲ 高于行业均值（表现良好）
▼ 低于行业均值（需关注）
≈ 接近行业均值（正常水平）
⚠ 显著偏离（超出基准 2 倍或低于 50%）

### 诊断
- 表现突出：（列出高于基准的指标及优势分析）
- 待优化：（列出低于基准的指标及具体改进方向）
- 综合评价：（一句话总结本次投放效果）

Mode B — 多活动对比：

## 多活动横向对比（按 ROI 降序）

| 活动 | 花费 | 营收 | ROI | ROAS | CTR | CPC | 综合评价 |
|------|------|------|-----|------|-----|-----|----------|
| ...  |      |      |     |      |     |     |          |

### 最优/最差活动分析
（对比 ROI 最高与最低活动的关键指标差异，找出差距来源）

### 预算分配建议
（基于各活动效率，建议预算向高 ROI 活动倾斜的比例）

### 优化建议
（针对低效活动的具体改进方向）

执行步骤

确定性计算交给脚本，LLM 只做解读。 上表各项指标（含营收/利润派生，有机模式另算互动率）、 有机模式切换、字段校验、Mode B 按 ROI 降序排序，全部由 scripts/calc.py 完成（复用 skills/shared/scripts/social_stats.py 的 safe_div，除零/缺字段一律返回 null，不心算、不猜数）。

1. 解析输入 — 从用户 prompt 中提取数据字段，识别 Mode A（单组数据）或 Mode B（多组数据）
2. 调用脚本算指标 —
   • Mode A（单活动）：

     python3 skills/builtin/roi-calculator/scripts/calc.py single --name "活动名" \
       --ad-spend 5000 --impressions 100000 --clicks 3000 \
       --engagements 8000 --conversions 150 --avg-order-value 200 \
       --production-cost 1000
     

   • Mode B（多活动，按 ROI 降序）：把各活动整理成 JSON 数组文件后

     python3 skills/builtin/roi-calculator/scripts/calc.py multi --file campaigns.json
     

   脚本自动：11 指标逐项计算（分母为 0/缺失返回 null 并视为"数据不足"）、 营收→ROAS/利润/ROI 派生、ad_spend 为 0/缺失时切有机模式（跳过成本类指标）、 字段校验（负值 / 曝光<点击 / 转化>点击 写入 warnings）、Mode B 按 roi_pct 降序排序并标 roi_rank。
3. 加载基准 — 读取 benchmarks.md 获取行业基准数据
4. 确定对比基准 —
   • 有 Profile：读取 platforms.md 确定主平台，选对应平台基准
   • 无 Profile：使用跨平台均值
5. 基准对比（LLM 解读） — 把脚本输出的每个指标与基准比较，标注 ▲ 高于 / ▼ 低于 / ≈ 持平 / ⚠ 显著偏离
6. 生成诊断（LLM 解读） — 汇总表现突出项和待优化项，给出可操作的改进建议；转达脚本 warnings
7. Mode B 追加（LLM 解读） — 基于脚本已排好的 ROI 排名，标注最优/最差，分析差异原因，给出预算分配建议

有机内容模式

当 ad_spend 为 0 或缺失时，自动切换：

• 跳过所有成本类指标（CPC/CPM/CPE/CPA/ROAS/ROI/利润）
• 仅计算：CTR（若有 impressions + clicks）、互动率（engagements / impressions）
• 报告标题标注"有机内容效果分析"
• 基准对比使用自然流量基准（通常高于付费流量）

Profile 感知

有 Profile 时：

• 读取 platforms.md 获取主投放平台，选用平台专属基准区间
• 读取 audience.md 了解受众特征，为转化率判断提供上下文
• 对比结论使用平台维度的精确基准

无 Profile 时：

• 使用跨平台综合均值作为基准
• 在报告末尾附注："提供账号 Profile（含平台信息）可获得平台专属基准对比"

规则

1. 不捏造输入 — 所有指标仅从用户提供的数据计算，缺失字段跳过依赖指标
2. 公式透明 — 每个指标旁标注计算公式，用户可验证
3. 基准对比 — 与行业基准比较，明确标注高于/低于/持平
4. 缺失容忍 — 缺字段不假设数值，跳过并说明"因缺少 X 数据无法计算"
5. 有机切换 — ad_spend 为 0 或缺失时自动切换有机模式，不报错

自研笔记

基准数据来源（定期更新 references/benchmarks.md）：

• Google Ads / Meta Ads 官方行业基准报告
• 巨量引擎 / 千川 投放效果白皮书
• 新榜 / 飞瓜 / 蝉妈妈 行业报告
• 各平台创作者中心公开数据

迭代方向：

• 增加时间序列对比（周环比、月同比）
• 支持自定义基准（用户提供历史均值作为对比基线）
• 接入真实 API 数据源（巨量引擎 / 小红书聚光 / 微信广告）
• 漏斗可视化输出（impressions → clicks → conversions 漏斗图）
• 归因模型支持（首次触达 / 末次触达 / 线性归因）
• 与 content-postmortem SKILL 联动，投放数据反哺内容策略

基准数据维护规则：

• 每季度对照最新行业报告校准 benchmarks.md 中的数值区间
• 标注数据采集时间，过期超过 6 个月的基准加 ⚠ 提示
• 鼓励用户提供自身历史数据，逐步建立账号级内部基准