ecom 是一个面向 D2C 电商的业务复盘工具包，用于从订单交易 CSV 数据中生成结构化的电商业务分析报告。其核心设计原则是：Python 引擎负责计算数字，Claude 负责解读数字，任何原始数字都必须结合业务语境呈现。
【用途】 该工具用于对 D2C 店铺进行业务复盘，通过订单交易数据计算 KPI、运行健康检查并评估绩效，最终产出人类可读的分析报告。
【主要能力】 内置 Python 引擎按可用周期计算：摘要 KPI 及环比对比、新客与回头客 KPI 树、收入驱动分解（客单价/销量/结构）；365 天周期还计算复购率和 12 个月月度趋势。引擎同时评估约 30 项健康检查，覆盖收入、客户、产品三类，每项返回 pass/watch/fail 状态，并对应 🟢/🟡/🔴 标记。
【使用方式】 支持三种模式：
- 完整复盘：无参数或输入 review，自动从数据中选择周期，输出 REVIEW.md。
- 指定周期复盘：如 review 30d / 90d / 365d，输出 REVIEW_{PERIOD}.md。
- 聚焦问答：输入自然语言问题，内联回答（10-30 行），不写文件。
输入为订单交易 CSV，每行代表一个订单或行项目。必需列：订单 ID、订单日期、客户 ID（或邮箱）、收入（折后、税前/运费前）。可选列：数量、SKU/产品、折扣金额。列名由加载器模糊匹配。若未指定 CSV，会在工作目录中查找 *.csv，存在多个候选时询问用户。
引擎调用命令： ecom review orders.csv --output <output-dir> ecom review orders.csv --period 90d --output <output-dir>
若 ecom 不在 PATH 中，可使用捆绑启动器："${CLAUDE_SKILL_DIR}/../../bin/ecom"。首次运行会在 ~/.local/share/claude-ecom/ 下引导创建私有 Python venv，可能耗时一分钟，后续运行即时完成。输出为输出目录中的 review.json（指定周期时为 review_{period}.json），默认输出到当前目录。
【工作流程】 第一阶段（计算）：运行引擎，按可用周期计算 KPI、KPI 树、收入驱动分解及健康检查。 第二阶段（解读）：完整复盘时读取 review.json、report-format.md（必读）、review-narratives.md，按需加载其他参考文件，撰写 REVIEW.md；聚焦问答时读取 focused-query.md（必读），按查询到周期的映射运行引擎，读取 JSON 后内联回答。
【报告契约】 完整复盘报告必须按以下顺序包含全部章节：执行摘要（叙述性引用块 4-6 行 + 记分板表格）、30d 脉搏（如数据可用，KPI 树 + 最多 1 条发现）、90d 动量（如数据可用，KPI 树 + 驱动因素 + 最多 2 条发现）、365d 结构（如数据可用，KPI 树 + 驱动因素 + 最多 3 条发现）、行动计划（最多 5 项，按时间范围分组 + 必需护栏指标）、数据说明（2-4 行）。硬性规则：目标约 150 行，所有周期合计最多 5-7 条发现，不得跨周期重复发现；章节顺序固定，不得按主题重组；不得设独立的“表现良好”或“待解决问题”章节；每个周期章节使用带 🟢/🟡/🔴 标记的 KPI 树格式；每条发现遵循“是什么→为何重要→怎么做”，禁用“考虑”“改进”“优化”“探索”等措辞；行动计划是截止日期和成功指标的唯一来源，并以护栏指标（2-3 项不得恶化的指标）结尾。
【参考文件】 按需加载，不在启动时全部加载：report-format.md（每次完整复盘写作前）、review-narratives.md（每次完整复盘）、focused-query.md（每次聚焦问答）、review-schema.md（review.json 语义不清时）、finding-clusters.md（归组相关问题时）、recommended-actions.md（将 watch/fail 转为行动时）、impact-formulas.md（估算收入影响时）、health-checks.md（检查定义或阈值不清时）、benchmarks.md（与 D2C 基准对比时）。
【数据规则】 所有数字必须来自 review.json 或由其值推导，不得引用外部来源（如 Shopify Analytics、GA）。periods 仅包含 data_coverage 中为 true 的周期，所有 _change 字段为相对上一周期的比例（0.08 = +8%）。health.top_issues 是失败检查的预排序子集，action_candidates 是 Python 的建议，需用业务语言改写，不得逐字复制。报告中不得暴露内部检查 ID 或检查数量。data_quality 非空时需在数据说明中提及相关警告，且不得将不完整月份的环比作为真实绩效信号。数据不完整时省略无法衡量的内容，不写 N/A、空章节或致歉；数据越短报告越短，缺口仅在数据说明中注明。
【语言与质量】 整份报告（含数据说明）使用单一语言，与用户提示/店铺语言一致。质量要求：数字必须附带解读；使用业务语言而非术语，首次使用时解释；将相关发现连接为系统性模式；遵循 80/20 规则（约 80% 确认以建立信任，约 20% 意外以推动行动）；不使用数字评分、字母等级或百分比健康评级，仅使用 pass/watch/fail 信号。
【限制】 该工具依赖订单交易 CSV 数据，必需列缺失时无法分析；所有数字仅来自 review.json，不引用外部数据源；数据不完整时省略无法衡量的内容；首次运行需引导创建 Python venv，可能耗时一分钟。