ecom

ecom — 电商业务评估工具包

D2C 电商分析。随附的 Python 引擎会根据订单交易数据计算 KPI、运行健康检查并评估业绩； 你（Claude）负责解读数据并撰写易于理解的报告。

核心原则： Python 负责计算数据。Claude 负责解读数据。 切勿脱离业务背景呈现原始数据。

参数： $ARGUMENTS（如果为空，则根据对话推断意图）

模式选择

参数 / 意图	模式	输出
为空或 review	完整评估（根据数据自动选择时间段）	REVIEW.md
review 30d / 90d / 365d	完整评估，单个时间段	REVIEW_{PERIOD}.md
包含自然语言问题	定向查询	直接回答，不创建文件

输入

订单交易 CSV。每行对应一笔订单或一个订单明细项。 必需列：订单 ID、订单日期、客户 ID（或电子邮件）、收入 （折扣后、税费和运费前）。可选列：数量、SKU/产品、 折扣金额。加载器会模糊匹配列名。

如果未指定 CSV，则在工作目录中搜索 *.csv；如果找到多个可能的文件， 请询问用户要使用哪一个。

运行引擎

启用此插件时，ecom CLI 位于 PATH 中：

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（运行 --period 时为 review_{period}.json；默认输出目录为当前目录）。

工作流

阶段 1：计算（Python）

运行引擎（根据“模式选择”添加 --period）。引擎会针对每个 可用时间段计算：包含与上一时间段对比的汇总 KPI、 新客与回头客 KPI 树、收入驱动因素分解（AOV / 销量 / 组合），以及在 365d 时间段下计算复购率和 12 个月的 monthly_trend。引擎还会对收入、 客户和产品进行约 30 项健康检查；每项检查会返回通过 / 关注 / 失败状态，并生成 🟢/🟡/🔴 标记。

阶段 2：解读（你 — Claude）

完整评估：

1. 阅读 review.json（参见下方“数据规则”；完整架构见 review-schema.md）
2. 阅读 report-format.md — 撰写前必须阅读； 其中包含所有章节模板和“发现质量标准”
3. 阅读 review-narratives.md，选择 叙事主线
4. 按需加载其他参考资料（见下表）
5. 撰写 REVIEW.md（或 REVIEW_{PERIOD}.md），并遵守下方的报告 约定

定向查询：

1. 阅读 focused-query.md — 必须阅读； 其中包含查询到时间段的映射和回答格式
2. 按映射运行引擎，读取 JSON 并直接回答 （10-30 行）。不要创建文件。

你的任务是将趋势和诊断编织成一个连贯的故事。 时间段分析告诉你情况正朝着什么方向发展；健康检查告诉你 当前出了什么问题。报告需要兼顾两者。

报告规范（完整评审）

撰写前，请确认报告包含以下所有部分，且顺序完全一致。缺少或调换顺序均属格式违规。

1. 执行摘要 — 叙述性引用块（4-6 行）+ 评分板表格
2. 30 天脉搏（如有数据）— KPI 树 + 最多 1 项发现
3. 90 天动能（如有数据）— KPI 树 + 驱动因素 + 最多 2 项发现
4. 365 天结构（如有数据）— KPI 树 + 驱动因素 + 最多 3 项发现
5. 行动计划 — 按时间范围分组，最多 5 项 + 护栏（必需）
6. 数据说明 — 2-4 行

硬性规则：

• 总长度目标约为 150 行；所有周期合计最多 5-7 项发现；绝不在多个周期重复同一项发现
• 各部分须按此顺序排列；不要按主题重新组织；不得单独设置“表现良好的方面”/“需要解决的问题”部分——积极信号应体现在执行摘要和 KPI 树标记中
• 每个周期部分都使用带 🟢/🟡/🔴 标记的 KPI 树格式
• 每项发现均遵循 现状 → 重要性 → 行动方向 （量化事实 → 有数据支撑的矛盾 → 行动方向；禁止使用“考虑”“改进”“优化”“探索”）
• 行动计划是截止期限和成功指标的唯一依据，并以护栏收尾（2-3 个不得恶化的指标）

模板、示例和完整质量标准见 report-format.md。

参考文件

按需加载——启动时不要全部加载。路径相对于此技能目录。

文件	加载时机
report-format.md	每次完整评审，撰写前
review-narratives.md	每次完整评审——按健康水平和趋势确定叙述脉络
focused-query.md	每次聚焦查询
review-schema.md	review.json 含义不明确时
finding-clusters.md	完整评审——将相关问题归为主题时
recommended-actions.md	将观察/失败检查转化为行动时
impact-formulas.md	估算收入影响时
health-checks.md	检查项定义/阈值不明确时
benchmarks.md	将 KPI 与 D2C 基准进行比较时

数据规则

• 仅使用 review.json。 所有数字都必须来自 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% 用于提出意外发现（推动行动）
• 不使用数字评分、字母等级或百分比健康评级——仅使用通过/观察/失败信号