ZJU-REAL/Easel / skills/builtin/roi-calculator
roi-calculator
Verified计算内容营销 ROI:根据投放数据算出 CTR/CPC/CPM/ROAS 等指标,对比行业基准,支持单活动分析与多活动横向比较。 当用户说"算ROI""投放效果""CTR/CPC/CPM/ROAS""投产比""广告效果""投放数据分析""活动ROI"时使用。
| File | Kind | Size |
|---|---|---|
| EASEL-META.md | markdown | 1.2 KB |
| SKILL.md | skill md | 7.7 KB |
| references/benchmarks.md | markdown | 3.6 KB |
| scripts/calc.py | script | 7.3 KB |
scripts/calc.py
View on GitHub#!/usr/bin/env python3
"""calc.py — roi-calculator 的确定性 ROI 计算.
把"逐项计算 11 个营销指标 / 派生营收利润 / 多活动按 ROI 降序"从 LLM
心算固化为代码。LLM 只负责读基准(references/benchmarks.md)、解读结果、
写诊断与预算建议。
11 个指标:CTR / CPC / CPM / CPE / 转化率 / CPA / 营收 / ROAS /
总成本 / 利润 / ROI
子命令:
single Mode A — 单活动分析(通过命令行 flag 传入各字段)
multi Mode B — 多活动对比(读 JSON 文件,按 ROI 降序排序)
有机模式:ad_spend 为 0 或缺失时自动切换,仅算 CTR + 互动率,跳过成本类指标。
输入字段(任意子集,缺失字段跳过其依赖指标):
ad_spend / impressions / clicks / engagements /
conversions / avg_order_value / production_cost
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "shared" / "scripts"))
import social_stats as ss # noqa: E402
FIELDS = ("ad_spend", "impressions", "clicks", "engagements",
"conversions", "avg_order_value", "production_cost")
def _scale(value, factor):
"""把 safe_div 的结果按 factor 缩放;None 透传(缺数据不参与)。"""
return None if value is None else value * factor
def _mul(a, b):
"""两数相乘;任一为 None 返回 None。"""
return None if (a is None or b is None) else a * b
def _is_organic(c) -> bool:
"""ad_spend 为 0 / None 时视为有机内容模式。"""
return not c.get("ad_spend")
def validate(c) -> list:
"""字段合理性校验,返回中文警告列表(不中断计算)。"""
warns = []
for k in FIELDS:
v = c.get(k)
if v is not None and v < 0:
warns.append(f"⚠ {k} 为负值({v}),指标可能失真")
imp, clk, conv = c.get("impressions"), c.get("clicks"), c.get("conversions")
if imp is not None and clk is not None and clk > imp:
warns.append(f"⚠ 点击量({clk}) > 曝光量({imp}),数据异常")
if clk is not None and conv is not None and conv > clk:
warns.append(f"⚠ 转化数({conv}) > 点击量({clk}),数据异常")
return warns
def compute(c: dict) -> dict:
"""计算单个活动的全部指标。缺分母的指标返回 None(标注"数据不足")。"""
spend = c.get("ad_spend")
imp = c.get("impressions")
clk = c.get("clicks")
eng = c.get("engagements")
conv = c.get("conversions")
aov = c.get("avg_order_value")
prod = c.get("production_cost") or 0
organic = _is_organic(c)
# 营收:转化数 × 客单价
revenue = _mul(conv, aov)
# 总成本:ad_spend + production_cost(有机模式下 ad_spend 视为 0)
total_cost = (spend or 0) + prod
total_cost = total_cost if total_cost > 0 else None
profit = None if revenue is None else revenue - (total_cost or 0)
metrics = {
# 通用(付费/有机都算)
"ctr_pct": _scale(ss.safe_div(clk, imp), 100),
"engagement_rate_pct": ss.engagement_rate(eng, imp, as_percent=True),
"conversion_rate_pct": _scale(ss.safe_div(conv, clk), 100),
}
if not organic:
metrics.update({
"cpc": ss.safe_div(spend, clk),
"cpm": _scale(ss.safe_div(spend, imp), 1000),
"cpe": ss.safe_div(spend, eng),
"cpa": ss.safe_div(spend, conv),
"revenue": revenue,
"roas": ss.safe_div(revenue, spend),
"total_cost": total_cost,
"profit": profit,
"roi_pct": _scale(ss.safe_div(profit, total_cost), 100),
})
else:
# 有机模式:跳过全部成本类指标
for k in ("cpc", "cpm", "cpe", "cpa", "revenue", "roas",
"total_cost", "profit", "roi_pct"):
metrics[k] = None
return {
"name": c.get("name"),
"mode": "organic" if organic else "paid",
"inputs": {k: c.get(k) for k in FIELDS if c.get(k) is not None},
"metrics": metrics,
"warnings": validate(c),
}
def cmd_single(args) -> None:
c = {k: getattr(args, k) for k in FIELDS}
c["name"] = args.name
result = compute(c)
print(json.dumps(result, ensure_ascii=False, indent=2))
def _load_campaigns(path: Path) -> list:
if not path.exists():
sys.exit(f"错误:未找到活动数据文件 {path}")
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as e:
sys.exit(f"错误:无法解析 {path}:{e}")
if isinstance(data, dict):
data = data.get("campaigns", [])
if not isinstance(data, list) or not data:
sys.exit("错误:活动数据应为非空数组(或 {\"campaigns\": [...]})")
return data
def cmd_multi(args) -> None:
campaigns = _load_campaigns(Path(args.file))
results = []
for i, c in enumerate(campaigns):
c.setdefault("name", f"活动{i + 1}")
results.append(compute(c))
# 按 ROI 降序(None 排最后,保持稳定)
def roi_key(r):
v = r["metrics"].get("roi_pct")
return (v is None, -(v if v is not None else 0))
ranked = sorted(results, key=roi_key)
for rank, r in enumerate(ranked, 1):
r["roi_rank"] = rank
roi_vals = ss.clean(r["metrics"].get("roi_pct") for r in ranked)
summary = {
"campaign_count": len(ranked),
"avg_roi_pct": ss.mean(roi_vals),
"best": ranked[0]["name"] if ranked else None,
"worst": ranked[-1]["name"] if ranked and roi_vals else None,
"warning": ss.sample_warning(len(ranked), 2, "对比活动"),
}
print(json.dumps({"summary": summary, "ranking": ranked},
ensure_ascii=False, indent=2))
def build_parser():
p = argparse.ArgumentParser(
description="内容投放 ROI 确定性计算(11 指标 + 多活动排序)")
sub = p.add_subparsers(dest="cmd", required=True)
s = sub.add_parser("single", help="Mode A 单活动分析")
s.add_argument("--name", help="活动名称")
s.add_argument("--ad-spend", dest="ad_spend", type=float,
help="投放费用 CNY(0/缺失切有机模式)")
s.add_argument("--impressions", type=float, help="曝光量")
s.add_argument("--clicks", type=float, help="点击量")
s.add_argument("--engagements", type=float, help="互动量(赞+评+转)")
s.add_argument("--conversions", type=float, help="转化数")
s.add_argument("--avg-order-value", dest="avg_order_value", type=float,
help="客单价 CNY")
s.add_argument("--production-cost", dest="production_cost", type=float,
help="内容制作成本 CNY")
s.add_argument("--json", action="store_true", help="以 JSON 输出(默认)")
s.set_defaults(func=cmd_single)
m = sub.add_parser("multi", help="Mode B 多活动对比(按 ROI 降序)")
m.add_argument("--file", required=True,
help="活动数据 JSON(数组或 {campaigns:[...]})")
m.add_argument("--json", action="store_true", help="以 JSON 输出(默认)")
m.set_defaults(func=cmd_multi)
return p
def main(argv=None):
args = build_parser().parse_args(argv)
args.func(args)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |