retail-analysis-toolkit
通用零售数据分析技能:把任何来源(CSV / JSON / 自有 BI API)的零售数据, 套用到经过实战沉淀的 9 类分析方法上,输出带诊断结论与行动建议的 Markdown 报告。 覆盖:目标追踪(红绿灯预警)、环比与量价归因、历史基线(四分位异常检测)、 多主体横评 Benchmark、矩阵象限、能力雷达、客户漏斗转化、帕累托结构与 波动归因(关键人识别)、商品画像、订单结构、四维度综合业绩评价。 触发条件(满足任一即使用本技能): - 用户询问业绩/目标/达成率(如"本月目标完成得怎么样""哪些店要报警") - 用户分析变化与原因(如"销售为什么下滑""客流转化率下降原因") - 用户需要对比(如"和别的店比怎么样""导购业绩排名""和历史同期比") - 用户分析结构(如"导购团队结构""谁拖累了业绩""商品品类分布") - 用户需要综合诊断(如"帮我全面评价一下这家门店") - 用户提供零售销售/客流/导购/SKU/客户数据并希望得到分析结论 适用对象:门店、电商、品牌零售的运营/督导/数据分析角色; 分析主体可为门店、导购、商品 SKU、区域等任意业务单元。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/cynthia10086--retail-analysis-toolkit)HTML
<a href="/listings/cynthia10086--retail-analysis-toolkit"><img src="/api/listings/cynthia10086--retail-analysis-toolkit/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 104 lines
- ---
- name: retail-analysis-toolkit
- description: |
- 通用零售数据分析技能:把任何来源(CSV / JSON / 自有 BI API)的零售数据,
- 套用到经过实战沉淀的 9 类分析方法上,输出带诊断结论与行动建议的 Markdown 报告。
- 覆盖:目标追踪(红绿灯预警)、环比与量价归因、历史基线(四分位异常检测)、
- 多主体横评 Benchmark、矩阵象限、能力雷达、客户漏斗转化、帕累托结构与
- 波动归因(关键人识别)、商品画像、订单结构、四维度综合业绩评价。
- 触发条件(满足任一即使用本技能):
- - 用户询问业绩/目标/达成率(如"本月目标完成得怎么样""哪些店要报警")
- - 用户分析变化与原因(如"销售为什么下滑""客流转化率下降原因")
- - 用户需要对比(如"和别的店比怎么样""导购业绩排名""和历史同期比")
- - 用户分析结构(如"导购团队结构""谁拖累了业绩""商品品类分布")
- - 用户需要综合诊断(如"帮我全面评价一下这家门店")
- - 用户提供零售销售/客流/导购/SKU/客户数据并希望得到分析结论
- 适用对象:门店、电商、品牌零售的运营/督导/数据分析角色;
- 分析主体可为门店、导购、商品 SKU、区域等任意业务单元。
- ---
- # 零售分析方法论工具箱(Retail Analysis Toolkit)
- ## 你(agent)要做什么
- 用户带着零售业务问题和数据来找你。你的工作流程:
- 1. **判断分析类型** — 根据下方「方法路由表」选 1-2 个最匹配的分析模块。
- 2. **准备数据** — 把用户数据(CSV/JSON/数据库/接口)整理成模块要求的结构
- (字段清单见 `references/data-schema.md`)。不要凭空编造数据;
- 数据缺失时明确告诉用户缺什么、怎么补。
- 3. **运行分析** — `sys.path.insert(0, '<本目录>')` 后 import 对应模块,
- 或直接调 CLI:`python3 scripts/cli.py <子命令> --data <文件>`。
- 4. **输出报告** — 调用各模块的 `format_report()` 生成 Markdown 报告,
- 报告已包含诊断发现(阈值判定)与行动建议;补充你的业务解读。
- 5. **建议下一步** — 报告结论应指向下一步分析(如环比归因发现订单量是主因
- → 建议下钻客户漏斗定位是引流还是转化问题)。
- ## 方法路由表
- | 用户问题类型 | 模块 | 关键函数 | CLI 子命令 |
- |---|---|---|---|
- | 目标达成了吗 / 谁要报警 | `analyses.target_tracking` | `track_target` `check_alerts` | `target` |
- | 比上期好了还是差了 / 为什么 | `analyses.period_compare` | `compare_periods` `attribute_sales_change` | `compare` |
- | 和历史比正常吗 / 周期规律 | `analyses.baseline` | `analyze_baseline` `assess_value` | `baseline` |
- | 排名 / 和同行比 / 门店等级 | `analyses.benchmark` | `benchmark_subjects` | `benchmark` |
- | 门店定位 / 件单价×连带率 | `analyses.benchmark` | `matrix_quadrant` | `quadrant` |
- | 个人能力 vs 团队均值 | `analyses.benchmark` | `radar_compare` | `radar` |
- | 客流 / 转化率 / 漏斗 | `analyses.funnel` | `analyze_funnel` | `funnel` |
- | 团队结构 / 谁拖累了业绩 | `analyses.pareto` | `pareto_structure` `attribute_change` | `pareto` `attribute` |
- | 品类/价格带/颜色分布 | `analyses.profile` | `profile_distribution` `compare_profiles` `order_structure` | `profile` |
- | 综合评价 / 到底达没达预期 | `analyses.evaluate` | `evaluate_comprehensive` | `evaluate` |
- **组合套路**(实战常用):
- - 月度复盘 = `target` + `compare`(含归因)+ `evaluate`
- - 业绩下滑排查 = `compare` 定主因 → `pareto.attribute_change` 找关键人 → `funnel` 查转化
- - 门店体检 = `benchmark` + `quadrant` + `baseline` + `evaluate`
- - 导购诊断 = `radar` + `pareto` + `profile`
- ## 使用示例
- ```python
- import sys
- sys.path.insert(0, '/path/to/retail-analysis-toolkit') # 本目录
- from scripts.analyses import target_tracking
- result = target_tracking.track_target("S001 旗舰店", actual=268000, target=250000)
- print(result["light"]) # {'level': 'normal', 'icon': '🟢', ...}
- # 或 CLI:
- # python3 scripts/cli.py target --data examples/data/targets.csv
- ```
- 先跑 `python3 scripts/cli.py demo` 可用内置示例数据看到全部 9 类分析的输出样例。
- ## 核心方法论(内化后不必翻参考资料)
- 1. **红绿灯五档**:达成率 ≥100% 🟢 / 95-100% 🟡 / 85-95% 🟠 / 70-85% 🔴 / <70% 🔴紧急。
- 2. **量价归因**:Δ销售额 = Δ订单数×上期客单价 + Δ客单价×本期订单数,绝对值大者为主因。
- 3. **基线四分位**:按星期几/周/月分组,P25/P50/P75 圈定正常区间;
- 低于 P25 报异常;分组样本 <6 不出结论。
- 4. **互斥桶漏斗**:有效客户=普通+潜在+意向+成交(先做加和校验);
- 潜在→意向 =(意向+成交)/(潜在+意向+成交);意向→成交 = 成交/(意向+成交)。
- 5. **帕累托与关键人**:TOP3 占比>70% 或变异系数>0.5 报集中度风险;
- 波动归因按下滑绝对值排序、累计贡献度 80% 截止,输出下钻名单。
- 6. **综合评价四维度**:目标/环比/基线/同行各算达成率,取最弱维度作为结论主叙事。
- 所有阈值集中在 `scripts/thresholds.py`,不同业务线可传自定义 `Thresholds` 覆盖。
- ## 参考资料(按需阅读)
- - `references/methodology.md` — 9 类方法的完整方法论、诊断规则阈值表、
- 以及与原始 14 个专项 skill 的映射关系(梳理产出)。
- - `references/data-schema.md` — 每个分析模块期望的数据字段与格式、
- 自有 BI/API 对接方式(DataSource 协议)。
- - `examples/run_examples.py` — 全部分析的可运行端到端示例。
- - `examples/generate_demo_data.py` — 演示数据生成(虚构数据)。
- ## 边界与原则
- - 只分析用户提供的真实数据;示例数据仅用于演示,结论中不要冒充真实业务结论。
- - 数据口径存疑时(如漏斗四层加和不等于总量),先报告数据问题再给分析。
- - 诊断阈值是经验默认值,涉及考核/决策时提醒用户按自身业务校准。
README.md · README · 308 lines
- # Retail Analysis Toolkit · 零售分析方法论工具箱
- **[English](./README.en.md)** | 简体中文
- [](../../actions/workflows/ci.yml)
- [](./LICENSE)
- [](./.github/workflows/ci.yml)
- [](#)
- > 一套从 **14 个实战零售分析 Skill** 中提炼出的通用分析方法论:
- > 任何数据源(CSV / JSON / 自有 BI),9 类分析,带诊断结论与行动建议的 Markdown 报告。
- > 既是一个 **Python 工具库 + CLI**,也是一个开箱即用的 **AI Agent Skill**。
- ---
- ## 目录
- - [它解决什么问题](#它解决什么问题)
- - [核心特性](#核心特性)
- - [快速开始](#快速开始)
- - [方式一:CLI 一分钟体验](#方式一cli-一分钟体验)
- - [方式二:Python 库](#方式二python-库)
- - [方式三:作为 AI Agent Skill](#方式三作为-ai-agent-skill)
- - [9 类分析方法](#9-类分析方法)
- - [示例输出](#示例输出)
- - [数据要求与对接自有数据](#数据要求与对接自有数据)
- - [诊断阈值体系](#诊断阈值体系)
- - [仓库结构](#仓库结构)
- - [方法论来源(14 → 1 梳理)](#方法论来源14--1-梳理)
- - [FAQ](#faq)
- - [参与贡献](#参与贡献)
- - [许可证](#许可证)
- ---
- ## 它解决什么问题
- 零售运营中的分析问题高度重复:**目标达成了吗、为什么下滑、和同行比怎么样、
- 客流转化哪个环节出了问题、谁拖累了团队业绩、商品结构变了没有**……
- 这些问题背后其实是有限的几类分析方法。本项目把门店运营分析师日常使用的
- 14 个专项分析工具(各自绑定私有 BI、彼此割裂)做了完整梳理,
- 提炼出 **9 类通用分析方法 + 1 套集中管理的诊断阈值体系**,
- 重新实现为一个不依赖任何特定环境的开源工具箱:
- - **对数据分析师**:一个零依赖(纯 Python 标准库)的分析库和 CLI,
- 喂 CSV/JSON 就能出带结论的报告。
- - **对 AI Agent(Claude Code / ZCode / 任意支持 Agent Skills 的客户端)**:
- 一个即装即用的 Skill——Agent 读 `SKILL.md` 就知道该用哪个分析方法、
- 怎么准备数据、怎么解读结论。
- ## 核心特性
- 1. **9 类分析方法全覆盖**:目标追踪、环比归因、历史基线、横评 Benchmark、
- 矩阵象限、能力雷达、客户漏斗、帕累托结构、商品画像、综合评价。
- 2. **诊断即结论**:不是只给数字,每份报告自带阈值判定的
- 「诊断发现(🔴🟡🟢 分级)+ 行动建议」。
- 3. **数据源无关**:CSV / JSON 开箱即用;对接自有 BI 只需实现
- 一个 `fetch()` 函数([DataSource 协议](./references/data-schema.md))。
- 4. **零第三方依赖**:纯 Python 标准库(3.9+),克隆即用,无需 pip install。
- 5. **阈值全部可调**:所有诊断阈值集中在 `scripts/thresholds.py`,
- 按业务线一行覆盖。
- 6. **人机两用**:CLI 给人用,`SKILL.md` 给 AI Agent 用,同一套引擎。
- ## 快速开始
- ### 方式一:CLI 一分钟体验
- ```bash
- git clone https://github.com/Cynthia10086/retail-analysis-toolkit.git
- cd retail-analysis-toolkit
- # 用内置示例数据一键跑通全部 9 类分析
- python3 scripts/cli.py demo
- ```
- 单类分析(吃你自己的 CSV):
- ```bash
- # 目标追踪:CSV 需要 subject,actual,target 三列
- python3 scripts/cli.py target --data my_targets.csv
- # 历史基线:今天卖 6500 正常吗(按星期几分组的四分位区间)
- python3 scripts/cli.py baseline --data store_daily.csv \
- --value sales --group weekday --window 13w --assess '周一=6500'
- # 四维度综合评价
- python3 scripts/cli.py evaluate --actual 268000 --target 250000 \
- --previous 291000 --baseline 282000 --benchmark 163000
- ```
- 各子命令的完整参数与数据格式见 [`references/data-schema.md`](./references/data-schema.md)。
- ### 方式二:Python 库
- ```python
- import sys
- sys.path.insert(0, "/path/to/retail-analysis-toolkit")
- from scripts.analyses import target_tracking
- result = target_tracking.track_target(
- "S001 旗舰店", actual=268000, target=250000,
- days_elapsed=30, days_total=30,
- )
- print(result["light"]) # {'level': 'normal', 'icon': '🟢', 'label': '正常', ...}
- print(target_tracking.format_report(
- target_tracking.track_targets_batch([
- {"subject": "S001", "actual": 268000, "target": 250000},
- {"subject": "S002", "actual": 62000, "target": 130000},
- ])
- ))
- ```
- 端到端示例见 [`examples/run_examples.py`](./examples/run_examples.py)。
- ### 方式三:作为 AI Agent Skill
- 本仓库根目录就是标准 Agent Skill 结构(`SKILL.md` + `scripts/` + `references/`)。
- ```bash
- # Claude Code / 任何读取 ~/.agents/skills 的客户端
- git clone https://github.com/Cynthia10086/retail-analysis-toolkit.git \
- ~/.agents/skills/retail-analysis-toolkit
- ```
- 之后直接对 Agent 说:
- > "这是本月各门店的销售数据 targets.csv,帮我做目标追踪,哪些店需要报警?"
- Agent 会按 `SKILL.md` 的方法路由表自动选择分析模块、准备数据、运行并输出报告。
- ## 9 类分析方法
- | # | 方法 | 回答的问题 | 模块 | CLI |
- |---|---|---|---|---|
- | 1 | 目标追踪 | 目标达成了吗?谁需要报警?缺口还要多快补? | `analyses/target_tracking` | `target` |
- | 2 | 环比 + 量价归因 | 比上期好了还是差了?主因是订单量还是客单价? | `analyses/period_compare` | `compare` |
- | 3 | 历史基线 | 和历史同期比正常吗?周一通常卖多少? | `analyses/baseline` | `baseline` |
- | 4 | 横评 Benchmark | 排第几?什么等级?和同行差距多大? | `analyses/benchmark` | `benchmark` |
- | 5 | 矩阵象限 | 门店/商品定位如何(如 件单价×连带率 四象限)? | `analyses/benchmark` | `quadrant` |
- | 6 | 能力雷达 | 某成员各维度能力 vs 群体均值,强在哪弱在哪? | `analyses/benchmark` | `radar` |
- | 7 | 客户漏斗 | 客流和转化率哪个环节出了问题? | `analyses/funnel` | `funnel` |
- | 8 | 帕累托 + 波动归因 | 团队结构健康吗?谁拖累/驱动了业绩?该找谁下钻? | `analyses/pareto` | `pareto` `attribute` |
- | 9 | 画像分布 | 成交商品的品类/价格带/颜色结构如何?两期变了什么? | `analyses/profile` | `profile` |
- | ⊕ | 综合评价 | 目标/环比/基线/同行四维度看,到底达没达预期? | `analyses/evaluate` | `evaluate` |
- **常用组合套路**:
- - **月度复盘** = `target` → `compare`(归因)→ `evaluate`
- - **业绩下滑排查** = `compare` 定主因 → `attribute` 找关键人 → `funnel` 查转化环节
- - **门店体检** = `benchmark` → `quadrant` → `baseline` → `evaluate`
- - **导购诊断** = `radar` → `pareto` → `profile`
- ## 示例输出
- `python3 scripts/cli.py target --data examples/data/targets.csv`:
- ```markdown
- | 主体 | 实际 | 目标 | 达成率 | 状态 | 缺口 |
- | --- | --- | --- | --- | --- | --- |
- | S001 旗舰店 | ¥268,000 | ¥250,000 | 107.2% | 🟢 正常 | ¥-18,000 |
- | S002 社区店 | ¥152,000 | ¥160,000 | 95.0% | 🟡 关注 | ¥8,000 |
- | S003 奥莱店 | ¥118,000 | ¥140,000 | 84.3% | 🔴 告警 | ¥22,000 |
- | S004 交通枢纽店 | ¥62,000 | ¥130,000 | 47.7% | 🔴 紧急 | ¥68,000 |
- ## 需关注
- - 🔴 **S004 交通枢纽店** 达成率 47.7%(缺口 ¥68,000)
- ...
- ```
- `python3 scripts/cli.py compare --data examples/data/period_metrics.csv`:
- ```markdown
- ## 量价归因
- - 销售额变化:**¥-23,008**
- - 订单数贡献:¥-19,401(84.3%)
- - 客单价贡献:¥-3,606(15.7%)
- - 主因:**订单数**
- ## 建议
- - 🔴 诊断订单量下滑原因:分析客流、转化率变化,定位是引流问题还是转化问题
- ```
- 更多完整输出运行 `python3 scripts/cli.py demo` 查看。
- ## 数据要求与对接自有数据
- - **最低要求**:能导出 CSV 的任何系统(POS / ERP / 电商后台 / Excel)。
- - **字段约定**:每个分析模块只需要少量字段(如目标追踪只要
- `subject,actual,target` 三列),完整清单见
- [`references/data-schema.md`](./references/data-schema.md),
- 文末附常见 BI 字段名映射表(`gmv→sales`、`order_cnt→orders` 等)。
- - **API / 数据库**:实现两行的 `DataSource` 协议即可接入:
- ```python
- class MyBI:
- def fetch(self, dataset: str, **params): ...
- ```
- - 主体不限门店——`subject` 可以是导购、SKU、区域、渠道、直播间,方法全部通用。
- ## 诊断阈值体系
- 所有判定规则集中在 [`scripts/thresholds.py`](./scripts/thresholds.py),默认值来自实战经验:
- | 类别 | 代表规则 | 默认阈值 |
- |---|---|---|
- | 红绿灯五档 | 达成率分档 | ≥100%🟢 / 95-100%🟡 / 85-95%🟠 / 70-85%🔴 / <70%🔴 |
- | 环比异常 | 销售额显著下滑 | ≤ -10%(严重 ≤ -20%) |
- | 客流漏斗 | 客流显著下滑 / 转化率环节下降 | ≤ -10% / ≤ -5pp |
- | 结构健康 | TOP3 集中度 / 人效变异系数 | > 70% / > 0.5 |
- | 订单结构 | 1 件单占比 / 低折扣订单占比 | > 60% / > 20% |
- | 基线 | 分组最小样本量 | < 6 不出结论 |
- 按业务线自定义:
- ```python
- from scripts.thresholds import Thresholds
- 零售价敏感业态 = Thresholds.with_overrides(mom_drop_warn=-15.0, top3_share_warn=60.0)
- ```
- 完整方法论(公式、阈值表、与原始 14 个 skill 的映射)见
- [`references/methodology.md`](./references/methodology.md)。
- ## 仓库结构
- ```
- retail-analysis-toolkit/
- ├── SKILL.md # AI Agent Skill 定义(方法路由 + 工作流)
- ├── README.md / README.en.md # 中英文文档
- ├── scripts/
- │ ├── cli.py # 命令行入口(11 个子命令)
- │ ├── loader.py # CSV/JSON 加载 + DataSource 协议
- │ ├── metrics.py # 通用指标计算(ATV/UPT/达成率/排名…)
- │ ├── thresholds.py # 诊断阈值集中管理(可覆盖)
- │ ├── report.py # Markdown 报告渲染
- │ └── analyses/ # 8 个分析模块 + 1 个综合评价
- │ ├── target_tracking.py # 目标追踪(红绿灯)
- │ ├── period_compare.py # 环比 + 量价归因
- │ ├── baseline.py # 历史基线(四分位)
- │ ├── benchmark.py # 横评/象限/雷达
- │ ├── funnel.py # 客户漏斗(互斥桶)
- │ ├── pareto.py # 结构 + 波动归因
- │ ├── profile.py # 画像分布 + 订单结构
- │ └── evaluate.py # 四维度综合评价
- ├── references/
- │ ├── methodology.md # 方法论梳理(14→9 映射、阈值表、公式)
- │ └── data-schema.md # 数据契约(字段清单、BI 对接)
- ├── examples/
- │ ├── data/ # 演示数据(虚构,可复现)
- │ ├── generate_demo_data.py # 演示数据生成器
- │ └── run_examples.py # 端到端示例
- ├── tests/ # 28 个单元测试(unittest,零依赖)
- └── .github/workflows/ci.yml # CI:Python 3.9-3.13 矩阵
- ```
- ## 方法论来源(14 → 1 梳理)
- 本工具箱并非凭空设计。源头是门店运营分析师的 14 个专项分析 Skill
- (目标追踪、客流漏斗、Benchmark、导购业绩、导购结构、货盘、客户清单、
- SKU 分析、业绩评价、历史基线……),它们的问题在于:
- 1. 各自绑定特定私有 BI API,离开原环境不可用;
- 2. 方法论重复度高(对比、结构、漏斗逻辑散落在各脚本里);
- 3. 阈值硬编码,无法按业务线调整。
- 通用化改造的关键决策:**「分析主体 × 分析方法 × 诊断规则」三维解耦**
- ——主体从"门店"泛化为任意 `subject`;方法提炼为 9 类;规则集中外置。
- 完整的映射表与公式备忘见 [`references/methodology.md`](./references/methodology.md)。
- ## FAQ
- **Q: 需要安装依赖吗?**
- 不需要。纯 Python 标准库实现,Python 3.9+ 直接运行。
- **Q: 我的数据字段名和你们不一样怎么办?**
- 字段名不强制。加载 CSV 后做一次映射即可(或改表头)。常见 BI 字段对照表见
- [data-schema.md](./references/data-schema.md#从数据库导出的字段映射示例)。
- **Q: 支持哪些 AI Agent 客户端?**
- 任何支持 Agent Skills(`SKILL.md` 约定)的客户端,如 Claude Code、ZCode 等;
- 也可以直接把本仓库作为 MCP/插件的参考资料库使用。
- **Q: 能用于电商/线上零售吗?**
- 可以。漏斗分层的业务口径(试用/加购/收藏)不同但结构一致,
- `funnel` 模块按"由浅到深"排列即可复用。
- **Q: 阈值不适合我的业务怎么办?**
- `Thresholds.with_overrides(...)` 一行覆盖任意阈值,
- 不需要改源码。见上文示例。
- ## 参与贡献
- 欢迎提交 Issue / PR:新增分析方法、补充数据适配器、完善阈值、改进文档。
- 流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。运行测试:
- ```bash
- python3 -m unittest discover tests # 或 pytest tests
- ```
- ## 许可证
- [MIT](./LICENSE) © 2026 Cynthia10086
- ## 更新日志
- 见 [CHANGELOG.md](./CHANGELOG.md)。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.