cli-calctool 0.1.0

package/skills/calctool/references/finance-example.md

@@ -0,0 +1,132 @@
+# 范例：经营健康诊断引擎（finance-health-diagnosis）
+
+完整走通「50 输入字段 → 归类 → 利润 → 十大指标评分 → 健康度 → 报告」的引擎定义范例。这是 calctool 的 reference implementation：任何新工具都可对照此结构生成。
+
+## 1. 引擎身份
+
+```yaml
+engineId: finance-health-diagnosis
+name: 经营健康诊断
+category: finance
+ownerType: platform-template
+status: published
+semanticVersion: 1.0.0
+compatibilityProfile: legacy-compatible
+decimalPolicy: decimal-string
+defaultCurrency: CNY
+defaultLocale: zh-CN
+schemaVersion: engine-spec/1
+```
+
+版本族：`1.x legacy-compatible`（复现原工具）；`2.x corrected`（修正财务口径，显式迁移发布）。
+
+## 2. 六层计算链路
+
+```
+输入层：利润表 50 个基础字段（货品成本、账单/订单/流量费用、薪酬、仓储…）
+  → 归类层：商品成本 / 账单费用 / 订单费用 / 流量费用 / 薪酬 / 仓储费用
+  → 利润层：GSV / 运营毛利 GP_oper / 管理费用 / 税前净利润 NP / 占比
+  → 诊断层：十大指标 / 动态阈值 / 单项得分 / 健康等级 / 加权健康度
+  → 专题层：增值税 / 盈亏平衡 / 私域复购 / 单品定价 / 利润率优化
+  → 展示层：历史分位 / 诊断重点 / HTML 报告 / 历史记录 / OGSM 执行方案
+```
+
+## 3. 十大指标权重（默认）
+
+| 指标 | 权重 |
+|---|---:|
+| 定价倍数 | 30% |
+| GSV | 17% |
+| 薪酬效率 | 15% |
+| GSV 人效 | 5% |
+| 毛利人效 | 5% |
+| 净利人效 | 5% |
+| 增值税率 | 10% |
+| 人均办公费用 | 3% |
+| 仓储费用占比 | 5% |
+| 单件发货成本 | 5% |
+
+## 4. 通用评分曲线（0-100）
+
+高值更优：
+```text
+S_high(A;P,E) = clamp(60 + 30 × (A-P)/(E-P), 0, 100)
+```
+
+低值更优（E < P，斜率自然为负）：
+```text
+S_low(A;P,E) = clamp(60 + 30 × (A-P)/(E-P), 0, 100)
+```
+
+带盈亏点的分段函数（定价倍数、GSV）：
+```text
+若 A < B： S_break = clamp(round(30 + 30 × (A-B)/(P-B)), 0, 100)
+否则：     S_break = clamp(round(60 + 30 × (A-P)/(E-P)), 0, 100)
+```
+（B=盈亏平衡，P=合格，E=优秀）
+
+## 5. 分数等级
+
+| 分数 | 等级 |
+|---:|---|
+| 非有限/空 | 需要优化成本结构而非数值 |
+| <60 | 危险 |
+| 60-<70 | 合格 |
+| 70-<80 | 良好 |
+| 80-<90 | 优秀 |
+| >=90 | 卓越 |
+
+## 6. 指标定义（当前值公式 + 目标 + 样例）
+
+| 指标 | 公式 | 合格/良好/优秀 | 样例分 |
+|---|---|---|---|
+| 定价倍数 | `S / 货品成本` | 动态阈值 | 63 |
+| GSV | `S` | 动态 | 63 |
+| 薪酬效率 | `GP_oper / 薪酬福利` | 2.0 / 2.5 / 3.0 | 71 |
+| GSV 人效 | `S / 正式员工数` | 100k / 120k / 150k | 60 |
+| 毛利人效 | `GP_oper / 正式员工数` | 17k / 20.4k / 25.5k | 61 |
+| 净利人效 | `NP / 正式员工数` | 5k / 6k / 7.5k | 64 |
+| 增值税率 | `C_tax / S` | 综合税率×1.0/0.9/0.8 | 38.4 |
+| 人均办公费用 | `办公费用 / 正式员工数` | 1,600 / 1,200 / 800 | 63.75 |
+| 仓储费用占比 | `仓储费用 / S` | 4.0% / 3.5% / 3.0% | 63 |
+| 单件发货成本 | `仓储费用 / 真实发货单量` | 1.80 / 1.60 / 1.40 | 76.5 |
+
+动态定价倍数阈值：
+```text
+c = 货品成本 / S
+n = 当前税前净利率
+盈亏倍数 B = 1 / (c + n)
+合格倍数 P = 1 / (c + n - 5%)
+```
+
+## 7. 总健康分
+
+- 加权：`总分 = Σ(指标分 × 权重)`，保留 2 位小数
+- 样例：62.2362（健康）
+- 历史百分位：程序按当前版本重算每条历史记录的十大指标，与全站用户样本比较
+
+## 8. 引擎定义产物（calctool 生成模板）
+
+```
+finance-health-diagnosis/
+├── manifest.yaml           # 引擎身份（见 §1）
+├── field-catalog.json      # 50 个输入字段 + 10 个派生指标
+├── scope-dimensions.json   # 公司 / 周期 维度
+├── formula-graph.json      # 六层公式图（§2）
+├── rule-packs.json         # 权重 + 评分曲线 + 等级（§3-5）
+├── import-profiles.json    # Excel 单元格映射 + OCR 字段映射
+├── report-template.json    # 指标卡 + 表格 + 诊断结论 + 建议
+└── tests/                  # 样例复算（健康分 62.2362 等）
+```
+
+## 9. 导入映射要点
+
+- 原工具为 Excel 导入：F 列单元格映射到字段目录，配置表覆盖顺序以算法主文档为准
+- 原生表格确定性解析，不做 OCR；截图/扫描件走 OCR + 人工草稿确认
+- 所有自动导入先进入草稿，人工确认后才写正式数据
+
+## 10. 生产注意事项
+
+- 增值税模块属于经营估算模型，生产使用前必须由持证财税人员复核
+- 本引擎复现的是当前产品口径，不代表会计准则、税法意见或税务筹划建议
+- 模型（Hermes/MiMo/OCR）只生成候选、草稿和解释，不能替代已发布确定性引擎给出正式财务数字

package/skills/calctool/references/formula-dsl.md

@@ -0,0 +1,92 @@
+# 公式 DSL 与确定性运行时
+
+## 1. 禁止任意 JavaScript
+
+禁止存储并执行 `eval(formula)` / `new Function(formula)`。原因：任意代码执行、无法静态分析、无法稳定迁移、难以做单位检查和依赖审计。
+
+自然语言或可视化公式统一编译为 **JSON AST**：
+
+```json
+{
+  "op": "mul",
+  "args": [
+    { "ref": "gmv" },
+    { "op": "sub", "args": [{ "lit": "1" }, { "ref": "preRefundRate" }] },
+    { "op": "sub", "args": [{ "lit": "1" }, { "ref": "postRefundRate" }] }
+  ]
+}
+```
+
+可提供接近 Excel 的编辑语法（字符串只用于编辑；保存前必须解析为 AST，执行时不重新解释任意脚本）。
+
+## 2. 最小运算符注册表
+
+| 类别 | 运算符 |
+|---|---|
+| 算术 | `add sub mul div mod pow abs neg min max` |
+| 比例 | `percentOf percentageChange basisPoints` |
+| 比较 | `eq ne gt gte lt lte between` |
+| 逻辑 | `and or not if case` |
+| 空值 | `coalesce isNull isFinite safeDivide` |
+| 取整 | `round floor ceil truncate` |
+| 聚合 | `sum avg minOf maxOf count countIf sumIf` |
+| 表格 | `rowRef column map filter groupBy lookup` |
+| 文本 | `concat trim upper lower match` |
+| 日期 | `dateAdd dateDiff startOf endOf` |
+| 维度 | `selectedIds containsAny containsAll isDescendantOf memberAttribute` |
+| 财务（二阶段） | `npv irr pmt rate` |
+| 统计（二阶段） | `percentile rank stdev` |
+| 引用 | `ref tableRef engineOutput configRef` |
+
+**显式除法**（必选其一）：
+- `div`：除数为 0 产生错误值（`DIV_ZERO`）
+- `safeDivide`：除数为 0 使用指定回退值（如兼容旧引擎"除零返回 0"）
+
+## 3. Decimal、单位与错误值
+
+生产运行时不依赖 JS `number` 作为财务真值：
+
+- 内部数值用 `decimal.js` 或等价 Decimal 实现
+- JSON 中以**字符串**持久化 Decimal
+- 公式定义精度和取整边界
+- 单位在**编译期推断**：
+  - `金额 + 比例` → 类型错误 `UNIT_MISMATCH`
+  - `金额 ÷ 人数` → 推导为 `CNY/person`
+- 错误以结构化值传播，不伪装成 0：
+
+```ts
+type CalcError =
+  | { code: 'DIV_ZERO'; nodeId: string }
+  | { code: 'MISSING_INPUT'; fieldId: string }
+  | { code: 'UNIT_MISMATCH'; expected: string; actual: string }
+  | { code: 'NON_FINITE'; nodeId: string }
+  | { code: 'CYCLE'; path: string[] };
+```
+
+## 4. 依赖图（发布前必查）
+
+1. 从 AST 提取字段和公式依赖
+2. 验证引用存在且符合可见范围
+3. 建立有向图
+4. 检测循环（`CYCLE` 错误）
+5. 标记跨模块/跨引擎引用（必须绑定版本和输出契约）
+
+## 5. 编译流程
+
+```
+自然语言/Excel 公式
+  → 解析（JSON AST，含 op/args/ref/lit）
+  → 类型检查（单位推断、字段存在、操作数类型）
+  → 依赖提取（字段/公式/表格/维度引用）
+  → 循环检测
+  → 编译为可执行运行时
+  → 测试（样例 → 期望结果，Decimal 精确比对）
+  → 发布（版本化，不可变）
+```
+
+## 6. 执行语义
+
+- 增量重算：字段变化只重算下游依赖
+- 执行轨迹：记录每个节点的输入/输出/错误，可审计
+- 快照：运行记录绑定引擎版本 + 输入 + 结果，可复现
+- 错误值传播：上游错误 → 下游保持错误（不吞掉）

package/skills/calctool/references/import-ocr.md

@@ -0,0 +1,72 @@
+# 导入与 OCR（上传内容自动识别）
+
+用户上传内容自动识别的分层管道设计——让工具能"读懂"Excel、图片、PDF 并填入字段。
+
+## 1. 分层管道
+
+```
+浏览器显式选择文件
+  → 私有对象存储原件区
+  → 确定性预处理（类型/大小/指纹校验）
+  → 原始证据层（OCR / 解析器原始输出）
+  → 语义层（多模态模型：理解内容 → 候选字段）
+  → 映射/校验层（文本模型：候选 → 标准字段，口径解释）
+  → 规则引擎（勾稽校验、冲突判定）
+  → 人工确认（草稿）→ 正式计算
+```
+
+## 2. 铁律
+
+1. **原始识别必须有确定性证据**：保存 OCR 原始 JSON、坐标、置信度、RequestId、页面图、模型/提示词/规则版本；任何改写都能反查原文框
+2. **原生 Excel/CSV 不做 OCR**：先用确定性解析器读单元格、公式、合并区域、工作表、格式；只有截图、扫描件、无法解析或以图片嵌入的表格才进入 OCR
+3. **PDF 按页编排**：OCR 一次识别一页，多页扫描件走页级任务（受控并发、可重试、页级状态）
+4. **所有对外任务异步化**：即使接口同步返回，产品 API 也返回内部 jobId（排队/限流/重试/取消/复核/审计）
+5. **自动导入先进草稿**：候选字段不直接覆盖正式数据
+
+## 3. 腾讯云能力矩阵（财务场景）
+
+| 场景 | 接口 | 用途 |
+|---|---|---|
+| 普通清晰页面 | `GeneralBasicOCR` | 非关键文字批量预识别 |
+| 长数字/小字/模糊/倾斜/金额密集/税率 | `GeneralAccurateOCR` | 关键财务字段默认 |
+| 表格 | `RecognizeTableAccurateOCR` | 表格、单元格文字、行列跨度、坐标、置信度，可返回 Base64 Excel |
+
+## 4. 导入 Profile（ImportProfile）
+
+```ts
+interface ImportProfile {
+  id: string;
+  kind: 'excel' | 'ocr' | 'manual';
+  sourceFormat: string;          // Excel 列 / OCR 字段布局
+  mapping: {
+    source: string;              // 源列/字段
+    targetField: string;         // 目标字段 key
+    transform?: string;          // 归一化变换
+  }[];
+  verification: 'draft' | 'auto'; // 默认 draft
+}
+```
+
+导入字段至少关联：
+- 页码、工作表、单元格（溯源）
+- `semanticConfidence`：模型对字段语义和映射关系的候选置信
+- 映射规则版本
+- 状态映射（草稿/确认/拒绝）
+
+## 5. 人工确认界面
+
+- 展示：OCR 证据（原文框/坐标）↔ 候选映射 ↔ 置信度
+- 操作：确认 / 修正 / 拒绝；确认后写入正式字段
+- 审计留痕：谁在何时确认了什么，原始证据完整保留
+
+## 6. 前端导入交互
+
+- `<input type="file" multiple>` 渐进增强；`webkitdirectory` 支持目录批量
+- 先本地校验（扩展名 + MIME + 大小上限 + 去重指纹），再上传
+- 上传即返回 jobId，状态轮询（queued → processing → review → done/failed）
+
+## 7. 失败与边界
+
+- 解析失败：保留原始文件 + 错误详情，提示重新上传或人工录入
+- 置信度低于阈值：强制进入人工确认，不自动通过
+- OCR 与 Excel 混用：同一字段多来源时以人工确认为准，记录来源优先级

package/skills/calctool/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "calctool",
+  "displayName": "calctool",
+  "description": "按需生成「万能计算工具」：输入领域需求（如财务经营健康诊断），通过提问明确指标/公式/输入方式，生成可执行、可验证、可发布的在线计算工具——支持自定义指标、自定义公式、上传内容自动识别（Excel/OCR）、报告输出。",
+  "schemaVersion": "cli.request/1.0",
+  "endpoint": "https://cli.tax/KKyA6xljUX",
+  "method": "POST",
+  "version": "v0.1.0",
+  "type": "Skill"
+}

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

@@ -0,0 +1,18 @@
+{
+  "cliTax": [
+    {
+      "code": "wvz6zmRWmX",
+      "slug": "blueprint",
+      "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 发布）"
+    }
+  ]
+}