roi-calculator

ROI 计算器

此技能可根据各种适合您目标和现有数据的方法，计算并传达网红营销活动的投资回报率。

跨领域（付费广告）： 这是付费广告共用的回报计算引擎。付费测量循环（paid-measurement-loop）、attribution-reconciler 和预算优化器会在此计算 ROAS/CPA/回本周期比率，而不是重复计算。将付费广告运行结果保存到 memory/ad/roi-calculator/。

快速开始

最简调用：

Calculate ROI for our influencer campaign: $25K spend, $72K revenue, 2.1M reach

常见场景——在报告前比较不同方法：

What's the ROI of our campaign using direct revenue, EMV, and LTV-based methods?

技能约定

• 读取：活动 ID、需要按创作者计算时完整的不透明创作者范围、支出/成本依据明细、去重后的结果数据（触达人数、展示次数、互动次数、点击次数、转化次数、归因收入、新客户数）、预先声明的归因模型/窗口/决策规则、纳入 LTV 计算时所需的 AOV 和经济 LTV 输入，以及 performance-analyzer 的历史表现输出。重复使用获授权的不透明 creator_ref 值；原始账号名/姓名/URL/服务商 ID 仅临时使用，绝不用于标识已保存的行。
• 写入：默认在内联回复中提供 ROI 计算结果和摘要；只有获得明确的 WARM 保存授权后，才将其保存到 memory/influencer/roi-calculator/YYYY-MM-DD-<topic>.md（或声明的付费广告路径）。保存的输出使用 campaign_id、完整的不透明 creator_ref 范围和不透明的证据/素材引用——绝不包含原始身份定位信息。
• 提升：只有获得单独的明确授权后，才将包含归因窗口、来源和不确定性的持久化关键数据提升至 memory/hot-cache.md；计算请求或 WARM 保存请求均不构成此操作的授权。
• 完成条件：
  1. 至少计算一种 ROI 方法，并展示所用输入和公式。
  2. 每项关键指标均须与明确声明且注明来源日期的比较目标对照；不得凭空编造通用基准。
  3. 写出最终的算术评估和 1-3 条建议。只有在归因收入和完整活动成本依据都得到核实后，才能称活动盈利；否则应说明盈利情况未经核实。
  4. 每个分母都必须是已核实的数值且 > 0；若分母为零、负数、缺失或不兼容，则返回 undefined/NEEDS_INPUT，绝不计算比率。
• 主要后续技能：report-generator

移交摘要

按照 skill-contract.md §Handoff Summary Format 输出标准格式。

数据来源

此技能系列属于第 1 级，无需实时集成即可运行。请用户提供支出和结果数据，并根据这些输入完成所有计算。以下连接器可在可用时自动获取数据：

• ~~社交平台分析 — 获取各平台的触达人数、展示次数、互动次数和视频观看次数，用于 EMV 和单项指标成本计算。
• ~~电商 / 分析 — 获取收入、转化次数、链接点击次数和 AOV，用于直接 ROI 和归因计算。
• ~~CRM — 获取新客户数、重复购买率和客户生命周期价值，用于基于 LTV 的 ROI 计算。
• ~~网红数据库 — 获取网红费用和层级数据，用于按网红计算 ROI。

即使没有任何集成，手动提供投资和结果表后，此技能仍可完成所有计算。请参阅 CONNECTORS.md，了解各类别的免费/免密钥配置方法。

说明

用户请求计算 ROI 时，请按以下步骤操作。每个步骤在 references/roi-templates.md 中都有填写模板——将步骤编号链接到其中对应的区块。

1. 收集 ROI 输入 — 活动详情、投资（总支出）表和结果数据表。（模板）

2. 计算直接 ROI — 简单 ROI =（收入 − 投资）/ 投资 × 100；ROAS = 收入 / 投资。除非已核实收入归因和完整成本口径，否则应称为按声明公式计算的净回报，而非利润。注明算术回报为正、零或负，并单独说明盈利能力核验状态。(template)

3. 计算赢得媒体价值（EMV） — 仅使用已提供或引用且注明来源日期的比较基准，按展示量计算（展示量 × 可比 CPM / 1000）或按互动量计算（互动量 × 可比 CPE）。分别报告适用的方法，并采用预先声明的选择/加权规则；默认情况下，绝不对存在重叠的方法取平均或相加。如果没有有效的比较基准，则对 EMV 返回 NEEDS_INPUT。(template)

4. 计算成本效率指标 — CPM、CPR、CPE、CPV、CPC、CPA 和 CAC。仅与已声明且注明来源日期、并且市场、时间范围和归因口径兼容的目标进行比较；否则仅描述性报告该指标，并将比较标记为待处理。(template)

5. 应用归因模型 — 只有在提供完整的转化范围、订单/事件去重键、用户旅程触点、符合条件的渠道和分配规则后，才能使用一个预先声明的模型。可选的替代模型应明确标示为基于同一去重转化集的非累加敏感性场景；绝不能在查看结果后选择最有利的模型。缺少输入或模型选择权限时，应返回 NEEDS_INPUT，而非归因收入。(template)

6. 计算客户终身价值影响 — 只有在 New Customers 已根据主归因范围去重，且提供的 LTV 具备完整的贡献利润口径（包括群组、时间范围、留存/流失、退款、利润率、折现/时间点、是否包含首笔订单、来源/日期），并且投资分母为正且口径兼容时，才能将结果标记为 基于 LTV 的 ROI。然后使用 ((New Customers × contribution-margin LTV) − Investment) / Investment × 100。如果输入的是收入 LTV，则只能生成预估收入口径场景，并注明其口径/时间范围/状态；该结果不是经济 ROI 或利润，也绝不能与直接归因收入或其他 LTV 时间范围相加。缺少必要字段时返回 NEEDS_INPUT。(template)

7. 按创作者计算 ROI — 仅适用于范围完整且已锁定、模糊引用已解析、时间范围/成本口径兼容且归因收入已去重的创作者。单个创作者和层级汇总的 ROAS 均按 sum(attributed revenue) / sum(spend) 计算，绝不能简单取平均；仅在预先声明的规则下进行排名。(template)

8. 生成 ROI 报告摘要 — 投资、回报、按方法计算的 ROI、与基准相比的关键指标、结论，以及 1–3 条建议。(template)

9. 评定候选回报（R）证据是否满足门槛

   步骤 1–8 的财务结果是 STAR 的候选回报（R）证据：将 ROI/ROAS 与声明的目标对照（R1），将 CPE/CPM/CPA 按标准化时间范围与基准对照（R2），将 KPI 达成情况与预先注册的目标对照（R4），注明方法和严谨程度的归因转化（R5），以及在可测量时与基准分离的增量影响（R6）。只有在核实了字段的确切来源、实体、观测时间范围和归因口径后，该字段才能标记为 Measured；对用户提供或预估输入进行算术计算，结果属于 Calculated，而非 Measured。回报证据仅适用于 assessment_time: actual；预测结果不包含 R1–R6。 将这份 Return 证据交给 creator-content-auditor 关卡 —— 它会将 R 并入完整的实际 STAR 运行，并计算按 profile 加权的 SQS。本技能不运行评分器，也不输出综合分。未经核实的转化会输出 results-unverified：将 R1/R2/R5 报告为低置信度，并且不做任何可归因回报的声明。这些财务数字会作为 R 证据被消费；它们本身并不是 SQS。

   对于多创作者营销活动，该关卡会分别对每个创作者合作关系评分；对每个合作关系的 SQS 值取预算加权平均值可以概括整个营销活动，但绝不能取代对每个合作关系的诊断。本技能提供的是按合作关系划分的 Return 证据；它不对综合分进行汇总或上卷。

10. 仅在获得许可后持久化 —— 只有在获得授权后才保存到 memory/influencer/roi-calculator/（或付费路径）下；热缓存提升需另行请求授权。

对于本技能中的每个公式，请验证分母为数值且严格大于零。如果投资、曝光、触达、互动、观看、点击、获取、客户或另一个必需分母为零、负数、缺失，或与分子的时间窗口不兼容，则将该比率报告为 undefined，并为该指标返回 NEEDS_INPUT。绝不要静默地除以零、强行转换它，或用名义值替代。

示例

用户："计算我们网红营销活动的 ROI：$25K 支出，$72K 收入，2.1M 触达"

输出：

# ROI Calculation Summary

## Investment & Returns

| Item | Value |
|------|-------|
| Total Investment | $25,000 |
| Revenue used in calculation | $72,000 (User-provided; source/window unverified) |
| Total Reach | 2,100,000 |

## ROI Results

### Direct ROI — calculated on User-provided revenue basis
- **Net return under the declared formula**: $47,000
- **ROI**: 188%
- **ROAS**: 2.88:1

The supplied revenue implies $2.88 per $1 spent. `results-unverified`: no attribution source, method, or window was supplied, so this is not an attributable, causal, or incremental-return claim.

### Earned Media Value
- **EMV**: `NEEDS_INPUT` — no source-dated comparable CPM/CPE or declared valuation rule was supplied
- **EMV Multiple**: `NEEDS_INPUT`

### Cost Efficiency
- **CPM**: $11.90
- **CPA**: Unknown (conversion count was not supplied)

## Assessment: Positive arithmetic return on the supplied basis; profitability and causality unverified

Supplied revenue exceeds supplied investment under the declared formula, but no complete cost basis, attribution source/window, source-dated peer target, or incrementality evidence was provided. Do not infer profit, benchmark outperformance, or causal lift, and do not authorize a scale decision from this read alone; obtain verified conversions, attribution evidence, complete costs, and the campaign owner's precommitted decision rule first.

带来源日期的基准证据模板位于 references/roi-templates.md#benchmark-evidence-template。

参考材料

• references/roi-templates.md —— 每个 Instructions 步骤、完整示例和基准证据输入的填写模板。
• measurement-protocol.md —— 在回读窗口内对照对照组读取 ROI 和 Return (R) 增量；不要过度声称归因。
• skill-contract.md —— 共享契约和 Handoff Summary 格式。
• state-model.md —— 记忆层级和保存路径约定。
• CONNECTORS.md —— 每个连接器类别的免费/无需密钥数据配方。
• STAR 评分：star-benchmark.md —— 本技能证据所供给的 Return (R) 维度，以及关卡计算的按 profile 加权 SQS。
• performance-analyzer —— 提供本技能所消费的结果数据。
• report-generator —— 将这些数字包装成完整报告。
• budget-optimizer —— 使用 ROI 输出来重新分配支出。
• campaign-planner —— 设定这些结果所对照检查的 ROI 目标。

最佳下一技能

首选：report-generator —— 将 ROI 数字转化为可供利益相关者使用的报告。

备选（同属 Report 系列）：

• performance-analyzer —— 如果 ROI 计算暴露出缺口，返回以获取更深入的绩效细分。
• budget-optimizer —— 将按网红和按层级的 ROI 输入下一次预算分配。

终止说明：保留一个本次会话中已调用技能的 visited-set。如果首选下一技能已经运行过，则停止并报告链路已完成，而不是重新调用它。单条链路最多经过 3 跳后停止。