cli-blueprint 0.1.0 → 0.2.0

package/skills/calctool/templates/ecommerce-ops/README.md

@@ -0,0 +1,27 @@
+# 电商运营领域模板（ecommerce-ops）
+
+情报智能体（research-agent）从互联网收集的电商运营行业参考包，全部可溯源（见 `domain-reference.yaml` 的 sources）。
+
+## 内容
+
+- **10 个核心指标**：GMV / 转化率 / 客单价 / ROAS / ROI / 复购率 / UV / PV / LTV / CAC
+- **8 组计算口径**：转化率分母、ROI vs ROAS、GMV vs 实收、客单价、复购率、归因、LTV/CAC、漏斗
+- **6 项行业基准**：转化率 2-5%、ROAS ≥4、复购 25-30%、LTV/CAC ≥3 等
+- **1 条漏斗链路**：曝光 → 点击 → 访问 → 加购 → 下单 → 支付
+
+## 5 处口径争议（生成工具时做成用户可配置项）
+
+| 配置项 | 选项 | 影响 |
+|---|---|---|
+| 转化率分母 | UV 去重访客 / Sessions 会话数 | 结果差异可达 2 倍 |
+| 投产比分子 | 收入（ROAS）/ 利润（ROI） | 「投产比」一词两种语境 |
+| GMV 扣退款 | 是 / 否 | 流水口径 vs 净额口径 |
+| 复购率窗口 | 30 天 / 90 天 / 自然年 | 复盘 vs 品类周期 |
+| 归因窗口 | 7 天点击 / 1 天浏览 / 28 天 / 自定义 | 广告效果评估 |
+
+> 最终口径以老板确认为准，本模板只提供行业参考。
+
+## 使用方式
+
+calctool 的 research 蜂群任务在老板说「电商」等关键词时自动加载此模板，
+作为 fields/formulas 设计的领域知识基础。

package/skills/calctool/templates/ecommerce-ops/domain-reference.yaml

@@ -0,0 +1,172 @@
+domain: ecommerce-ops
+name: 电商运营
+# 说明：本参考包为行业公开资料整理（情报智能体 6 轮 web_search 收集），非官方标准；
+# 口径争议处列出差异选项，最终以老板确认为准。
+
+metrics:
+  - key: gmv
+    label: GMV（商品交易总额）
+    definition: 一定周期内成交商品的总价值，含未支付/已支付订单的标价总额，不等于平台确认收入；收入 = GMV − 退款退货 − 折扣 − 税费等扣减项
+    formula: GMV = Σ(售出商品数量 × 商品售价)；GMV = 客单价 × 订单数（验证等式）
+    source: https://www.wallstreetprep.com/knowledge/gross-merchandise-value-gmv/ , https://www.aftership.com/glossary/gross-merchandise-value , https://www.jiemian.com/article/4608249.html
+  - key: conversionRate
+    label: 转化率（CVR）
+    definition: 完成目标行为（下单/支付）的访客或会话占总访问量的比例，电商常用「支付转化率 = 支付订单数/访客数」
+    formula: 转化率 = 订单数 / 访客数（或会话数）× 100%
+    source: https://www.shopify.com/sg/blog/retail-conversion-rate , https://www.hostinger.com/tutorials/ecommerce-conversion-rate/ , https://www.smartinsights.com/ecommerce/ecommerce-analytics/ecommerce-conversion-rates/
+  - key: aov
+    label: 客单价（AOV）
+    definition: 平均每笔订单的成交金额，衡量客群消费力与连带销售水平
+    formula: 客单价 = GMV（或实收额）/ 订单数（有效订单）
+    source: https://help.klaviyo.com/hc/en-us/articles/360000676712 , https://www.shopify.com/blog/average-order-value , https://www.jiushuyun.com/blog/jsyty/65019.html
+  - key: roas
+    label: ROAS（广告支出回报率）
+    definition: 每花 1 元广告费带来的收入，只含收入不含成本
+    formula: ROAS = 广告带来的收入 / 广告花费
+    source: https://impact.com/marketing-intelligence/roi-vs-roas-whats-the-best-performance-metric/ , https://observix.ai/blog/roas-vs-roi , https://www.adexchanger.com/data-driven-thinking/roi-vs-roas-which-is-the-better-metric-for-digital-advertisers/
+  - key: roi
+    label: ROI（投资回报率/投产比）
+    definition: 广告投入带来的净收益（利润）占投入的比例；中国电商口语「投产比」多数指 ROI（含成本口径）
+    formula: ROI = (收入 − 广告花费 − 商品/履约等成本) / 广告花费 × 100%；简化口径 ROI = 利润 / 广告费
+    source: https://impact.com/marketing-intelligence/roi-vs-roas-whats-the-best-performance-metric/ , https://zhuanlan.zhihu.com/p/134032717 , https://diantuoyi.com/article/26916.html
+  - key: repurchaseRate
+    label: 复购率
+    definition: 统计窗口内发生≥2次购买的顾客占当期购买顾客总数的比例；与「回购率」区分
+    formula: 复购率 = 统计期内复购顾客数 / 统计期内购买顾客总数 × 100%（窗口 30天/90天/自然年）
+    source: https://www.finsi.ai/blog/repeat-purchase-rate-ecommerce/ , https://www.runfutureproof.com/terms/repeat-purchase-rate , https://cloud.tencent.com.cn/developer/article/1906279
+  - key: uv
+    label: UV（独立访客）
+    definition: 去重后的独立访客数（cookie/设备 ID 识别）
+    formula: 无公式，直接统计去重访客数
+    source: https://developer.aliyun.com/article/357958 , https://cloud.tencent.com.cn/developer/article/1483600
+  - key: pv
+    label: PV（页面浏览量）
+    definition: 页面被浏览总次数；人均浏览页数 = PV / UV
+    formula: PV = Σ各页面被浏览次数
+    source: https://developer.aliyun.com/article/357958 , https://cloud.tencent.com.cn/developer/article/1483600
+  - key: ltv
+    label: LTV/CLV（客户生命周期价值）
+    definition: 单个客户在整个生命周期内贡献的总利润（或营收）预期
+    formula: LTV = 客单价 × 年均购买频次 × 客户生命周期年限
+    source: https://www.shopify.com/blog/customer-lifetime-value , https://www.aftership.com/glossary/lifetime-value
+  - key: cac
+    label: CAC（客户获取成本）
+    definition: 获取一个新客户平均花费的营销与销售成本
+    formula: CAC = 总营销与销售成本 / 新增客户数
+    source: https://www.chargebee.com/resources/glossaries/ltv-cac-ratio , https://echai.ventures/d2c/d2c-unit-economics/ltv-cac-ratio-when-profitable
+
+formulas:
+  - key: conversionRate
+    expression: "转化率 = 支付订单数 / 访客数 × 100%（分母可选：UV 去重访客 / Sessions 会话数）"
+    attribution: 统计窗口与分母须一致；同一订单只归属首次访问来源
+    notes: "口径争议：会话数会把同一用户多次访问计入，转化率偏低；UV 更接近「人」口径；GA4 默认会话，国内后台常按 UV。工具应提供口径选项。"
+    source: https://moz.com/community/q/topic/58633/should-i-use-sessions-or-unique-visitors-to-work-out-my-ecommerce-conversion-rate/ , https://www.shopify.com/sg/blog/retail-conversion-rate
+  - key: roiVsRoas
+    expression: "ROAS = 广告收入/广告费（只看收入）；ROI = 利润/广告费（扣除成本）"
+    attribution: 广告收入须按选定归因口径统计
+    notes: "口径争议：ROAS 不含成本，盈亏平衡 ROAS = 1/毛利率；ROI 含成本更真实；国内「投产比」直通车常指 ROAS、财务语境常指 ROI。工具同时提供两者并标注分子口径。"
+    source: https://impact.com/marketing-intelligence/roi-vs-roas-whats-the-best-performance-metric/ , https://www.adexchanger.com/data-driven-thinking/roi-vs-roas-which-is-the-better-metric-for-digital-advertisers/ , https://zhuanlan.zhihu.com/p/134032717
+  - key: gmvVsNet
+    expression: "GMV = 全部订单金额（含未付款/已退款/含税）；实收 = GMV − 退款 − 折扣 − 税费 − 取消订单"
+    attribution: 按订单创建 vs 支付 vs 发货时间统计，结果不同
+    notes: "口径争议：GMV 是流水口径（下单即计入），实收是净额口径；对账用净收入，运营看趋势用 GMV。工具需提供「是否扣除退款」开关。"
+    source: https://www.wallstreetprep.com/knowledge/gross-merchandise-value-gmv/ , https://www.jiemian.com/article/4608249.html , https://www.jiushuyun.com/blog/ds/30546.html
+  - key: aov
+    expression: "客单价 = GMV / 订单数（或用实收额 / 有效订单数）"
+    attribution: 分子分母口径须一致
+    notes: "客单价 × 转化率 × 访客数 = GMV（联动分析）"
+    source: https://help.klaviyo.com/hc/en-us/articles/360000676712 , https://www.jiushuyun.com/blog/jsyty/65019.html
+  - key: repurchaseRate
+    expression: "复购率 = 窗口内复购顾客数 / 窗口内购买顾客总数 × 100%（按顾客去重）"
+    attribution: 统计窗口（30天/90天/自然年）不同结果差异大
+    notes: "口径争议：30 天窗口贴近营销复盘，90 天贴近品类周期；亦有按订单占比口径。工具需允许按订单或按顾客。"
+    source: https://www.finsi.ai/blog/repeat-purchase-rate-ecommerce/ , https://www.runfutureproof.com/terms/repeat-purchase-rate , https://cloud.tencent.com.cn/developer/article/1906279
+  - key: attribution
+    expression: "归因：点击归因 > 浏览归因 > 曝光归因"
+    attribution: "7天归因：互动后 7 天内转化归属该广告（Meta 默认 7天点击+1天浏览）"
+    notes: "口径差异：点击归因会高估广告贡献；曝光归因易把自然转化算到广告。高客单建议 7-28 天窗口，快消 1-7 天。工具应提供归因窗口+模型配置项。"
+    source: https://www.mobvista.com/en/glossary/attribution-window , https://tenjin.com/glossary/attribution-window/ , https://www.adadvisor.ai/docs/learn/attribution-models
+  - key: ltvCac
+    expression: "LTV/CAC = 客户生命周期价值 / 客户获取成本；LTV = 客单价 × 购买频次 × 生命周期"
+    attribution: LTV 用利润还是营收口径影响结论；CAC 含不含自然流量成本需定义
+    notes: "LTV/CAC ≥ 3 常被视为健康"
+    source: https://www.chargebee.com/resources/glossaries/ltv-cac-ratio , https://echai.ventures/d2c/d2c-unit-economics/ltv-cac-ratio-when-profitable
+  - key: funnelStages
+    expression: "漏斗：曝光 → 点击 → 访问 → 加购 → 下单 → 支付；各环节转化率 = 下一环节人数 / 当前环节人数"
+    attribution: 支付成功（剔除取消/退款）为最终有效转化
+    source: https://www.ipaylinks.com/information_details.php?id=18681 , https://trustedwebeservices.com/ecommerce-sales-funnel-optimisation/
+
+benchmarks:
+  - metric: conversionRate
+    healthy: 2%-5%（整体常引范围；GA 口径约 1.8%~3.9%，桌面端高于移动端）
+    source: https://www.smartinsights.com/ecommerce/ecommerce-analytics/ecommerce-conversion-rates/ , https://www.geekseller.com/blog/what-is-a-good-conversion-rate-for-ecommerce-websites/ , https://www.gorgias.com/blog/ecommerce-conversion-rate
+  - metric: roas
+    healthy: 「好」的 ROAS 常引 ≥4:1（Shopify）；2025 平均约 2.87（Upcounting）；盈亏平衡取决于毛利率
+    source: https://www.shopify.com/in/enterprise/blog/how-to-increase-roas , https://www.upcounting.com/blog/average-ecommerce-roas , https://niblin.com/blog/what-is-a-good-roas
+  - metric: aov
+    healthy: 未找到统一权威基准——客单价随品类/客群差异极大（服饰 vs 3C vs 家具），仅可参考按类目分组的第三方数据
+    source: https://fullmetrix.com/en/blog/panier-moyen-par-secteur-ecommerce , https://cdn.metorik.com/blog/average-order-value-benchmarks-woocommerce
+  - metric: repurchaseRate
+    healthy: 行业均值约 25%-30%（finsi.ai）；类目差异大：时尚约 26% 下限，宠物（Chewy）可达 80%+ 上限
+    source: https://www.finsi.ai/blog/repeat-purchase-rate-ecommerce/ , https://eightx.co/blog/average-ecommerce-repeat-purchase-rate-by-vertical-2026
+  - metric: ltvCac
+    healthy: LTV/CAC ≥ 3:1 为健康，>5:1 可能意味着获客投入不足
+    source: https://echai.ventures/d2c/d2c-unit-economics/ltv-cac-ratio-when-profitable , https://www.chargebee.com/resources/glossaries/ltv-cac-ratio
+  - metric: funnelStage
+    healthy: 加购率约 5-8%（访问→加购）、加购→下单约 40-60%、下单→支付约 50-70%；来源口径不一，仅作参考
+    source: https://trustedwebeservices.com/ecommerce-sales-funnel-optimisation/ , https://www.smartinsights.com/ecommerce/ecommerce-analytics/ecommerce-conversion-rates/
+
+funnel:
+  - 曝光（impression）→ 点击（click）→ 访问（visit/UV）→ 加购（add to cart）→ 下单（place order）→ 支付（payment success）
+  - 注：各环节人数逐级递减，环节转化率 = 下一环节人数/当前环节人数；支付后需剔除退款、取消才算有效成交
+
+# 5 处口径争议 → 工具中做成用户可配置项（最终以老板确认为准）
+configurableOptions:
+  - conversionRateBase: [UV 去重访客, Sessions 会话数]
+  - roiNumerator: [收入（ROAS）, 利润（ROI）]
+  - gmvDeductRefund: [是, 否]
+  - repurchaseWindow: [30天, 90天, 自然年]
+  - attributionWindow: [7天点击, 1天浏览, 28天点击, 自定义]
+
+sources:
+  - url: https://www.wallstreetprep.com/knowledge/gross-merchandise-value-gmv/
+  - url: https://www.aftership.com/glossary/gross-merchandise-value
+  - url: https://www.shopify.com/ph/blog/gross-merchandise-value
+  - url: https://www.jiemian.com/article/4608249.html
+  - url: https://www.jiushuyun.com/blog/ds/30546.html
+  - url: https://www.xinlingshou.com/wiki/gmv
+  - url: https://www.shopify.com/sg/blog/retail-conversion-rate
+  - url: https://www.hostinger.com/tutorials/ecommerce-conversion-rate/
+  - url: https://www.smartinsights.com/ecommerce/ecommerce-analytics/ecommerce-conversion-rates/
+  - url: https://moz.com/community/q/topic/58633/should-i-use-sessions-or-unique-visitors-to-work-out-my-ecommerce-conversion-rate/
+  - url: https://help.klaviyo.com/hc/en-us/articles/360000676712
+  - url: https://www.shopify.com/blog/average-order-value
+  - url: https://www.jiushuyun.com/blog/jsyty/65019.html
+  - url: https://impact.com/marketing-intelligence/roi-vs-roas-whats-the-best-performance-metric/
+  - url: https://observix.ai/blog/roas-vs-roi
+  - url: https://www.adexchanger.com/data-driven-thinking/roi-vs-roas-which-is-the-better-metric-for-digital-advertisers/
+  - url: https://zhuanlan.zhihu.com/p/134032717
+  - url: https://diantuoyi.com/article/26916.html
+  - url: https://www.finsi.ai/blog/repeat-purchase-rate-ecommerce/
+  - url: https://www.runfutureproof.com/terms/repeat-purchase-rate
+  - url: https://eightx.co/blog/average-ecommerce-repeat-purchase-rate-by-vertical-2026
+  - url: https://cloud.tencent.com.cn/developer/article/1906279
+  - url: https://developer.aliyun.com/article/357958
+  - url: https://cloud.tencent.com.cn/developer/article/1483600
+  - url: https://www.shopify.com/blog/customer-lifetime-value
+  - url: https://www.aftership.com/glossary/lifetime-value
+  - url: https://www.chargebee.com/resources/glossaries/ltv-cac-ratio
+  - url: https://echai.ventures/d2c/d2c-unit-economics/ltv-cac-ratio-when-profitable
+  - url: https://www.mobvista.com/en/glossary/attribution-window
+  - url: https://tenjin.com/glossary/attribution-window/
+  - url: https://www.adadvisor.ai/docs/learn/attribution-models
+  - url: https://www.ipaylinks.com/information_details.php?id=18681
+  - url: https://trustedwebeservices.com/ecommerce-sales-funnel-optimisation/
+  - url: https://www.geekseller.com/blog/what-is-a-good-conversion-rate-for-ecommerce-websites/
+  - url: https://www.gorgias.com/blog/ecommerce-conversion-rate
+  - url: https://www.shopify.com/in/enterprise/blog/how-to-increase-roas
+  - url: https://www.upcounting.com/blog/average-ecommerce-roas
+  - url: https://niblin.com/blog/what-is-a-good-roas
+  - url: https://fullmetrix.com/en/blog/panier-moyen-par-secteur-ecommerce
+  - url: https://cdn.metorik.com/blog/average-order-value-benchmarks-woocommerce
+  - url: https://ecomhint.com/blog/ecommerce-conversion-rate-benchmarks-by-industry

package/sources.json

@@ -6,6 +6,13 @@
       "endpoint": "https://cli.tax/api/public/skills/{code}",
       "doc": "https://cli.tax/wvz6zmRWmX",
       "description": "Blueprint 工程规划 CLI skill（CLI.Tax 发布）"
+    },
+    {
+      "code": "KKyA6xljUX",
+      "slug": "calctool",
+      "endpoint": "https://cli.tax/api/public/skills/{code}",
+      "doc": "https://cli.tax/KKyA6xljUX",
+      "description": "calctool 万能计算工具生成器（CLI.Tax 发布）"
     }
   ]
-}
+}