data-scientist-core

name	data-scientist-core
version	1.9.1
last_updated	2026-05-08
changelog	v1.9.1: 达尔文优化 R1-R3(69.5→84.5); frontmatter触发词+TL;DR速览+执行原则+4检查点+示例数据表+输出简洁性约束+B3路由显式行
description	经营体检+数据分析引擎。四层架构(L1便捷入口14个→L2语义路由27模式→L3引擎12模块43方法→L4叙事22方法)。覆盖归因/因果推断/分群/漏斗/时序/预测/经营决策/过程诊断/SVG可视化/HTML体检报告。输入CSV+分析目标，输出结构化分析+图表+洞察+行动建议。On-demand only — read SKILL.md when user asks to 经营体检/数据分析/归因分析/成本分析/health check/attribution/DID/AB test/clustering.

对标字节3-1级/阿里P8数据科学家的AI数据分析核心引擎

---

⚡ TL;DR — 60秒速览

项目	内容
定位	经营体检系统：CSV+分析目标 → 结构化报告+图表+洞察+行动建议
架构	L1(14便捷入口) → L2(27路由模式) → L3(12模块43方法) → L4(22叙事方法)
核心能力	归因/因果/分群/漏斗/时序/预测/经营决策/过程诊断/SVG可视化/HTML体检报告
快速开始	ds.analyze(df, goal="你的问题") 自动路由
经营体检	Storytelling().generate_health_check_report(data, config)
文件	4个核心脚本(data_scientist_core/l2_router/l3_engine/l4_storytelling)

---

🎯 执行原则（必须遵循）

收到分析需求时，直接给出完整分析方案，不要索要数据。 包括：命中的路由模式、方法名、参数映射、预期输出结构、可直接运行的代码示例。 如果信息不足以确定方法，给出最可能的1-2个候选方案并说明区别，让用户选择。 绝对不要只回复"请提供数据"——这不是数据分析助手该说的话。

输出简洁性：方案控制在3000字以内。 不要重复SKILL.md中的全部方法表格，只列出命中的那一个方法+代码+输出结构。经营体检场景只给config+调用代码+预期Section结构，不要展开每个Section的完整HTML。 洞察和结论用要点列表，不要大段文字。

检查点（关键决策前必须确认）

检查点	触发条件	动作
数据范围确认	经营体检/报告类任务	确认时间范围、维度、指标后再生成
方法选择确认	多种方法都能回答时	列出候选+区别，等用户选择
异常结论确认	统计显著但效应量小	主动标注"结论存疑"并说明原因
数据质量确认	precheck不通过	报告问题并建议修复方式，不强行分析

---

定位

从"分析工具"升级为经营体检系统。输入数据+分析目标/业务知识，输出结构化报告+可视化+洞察+行动建议。

核心能力

能力	说明
🔬 分析引擎	L3共12个模块43个方法，覆盖归因/因果/对比/分群/漏斗/时序/预测/经营决策/过程诊断
📊 SVG可视化	纯字符串拼接零依赖，4种图表（折线/柱状/热力图/漏斗）
📋 经营体检报告	四Section HTML报告：条线总览→末位分析→横向对标→预警清单
🔬 过程指标诊断	相关性分析+差距分解+根因定位
🚦 末位排名亮灯	红黄绿灯三级预警（🟢🟡🔴）

输入规范

类型	格式	说明
数据	CSV / Excel（.xlsx/.xls）	结构化数据，含表头
分析目标/思路/业务知识	自然语言	如"按SOP七维度分析拣运成本"
	PDF/Word/TXT/MD	业务规则/分析规范/字段定义

示例数据（典型场景）

场景	必需列示例	说明
归因分析	月份+渠道+GMV	至少2期+1个分组维度
经营体检	条线+省区+场地+月份+单位成本+总成本+操作量	5000行以上，含多维度
过程诊断	主表(场地+单位成本) + 过程表(场地+人效+出勤率+临时工占比)	两表通过key关联
AB测试	用户ID+组别+转化值	随机分流数据
漏斗分析	UV→点击→下单→支付 各步骤数值	顺序数值列

前置要求

Python 3.8+ + pandas numpy scipy scikit-learn statsmodels matplotlib openpyxl

---

快速决策树

遇到分析需求时，按顺序问：

① 你想知道什么？

目标	类型	调用
哪个因子导致变化	归因	ds.attribution_analysis()
活动/政策真实有效吗	因果	ds.did_analysis()
用户怎么分层	分群	ds.clustering_analysis()
两组差异显著吗	对比	ds.ab_test()
多个组织/群体横向对比	分层对比	ds.stratified_comparison() 或 B3路由
哪个渠道最关键	帕累托	ds.pareto_analysis()
转化哪里漏了	漏斗	ds.funnel_analysis()
时间趋势怎么样	时序	ds.stl_decomposition()
有没有异常值	异常	ds.anomaly_detection()
经营健康吗	体检	storytelling.generate_health_check_report()
过程指标根因	诊断	ProcessDiagnosis().process_diagnosis()
谁在末位	亮灯	storytelling.tail_ranking_with_light()

不确定选哪个 → ds.analyze(df, goal="一句话描述问题") 自动路由

② 是单点分析还是全面体检？

场景	推荐路径
回答一个具体问题	L1便捷方法 → L3引擎 → L4可视化
全面经营状况评估	generate_health_check_report() 四Section报告
定位某个指标的根因	ProcessDiagnosis 过程指标诊断

③ 数据准备好了吗？

必做前置检查（跳过可能导致错误结论）：

1. 数据量 < 30行 → t检验等统计方法不可靠，提示用户补充数据
2. 缺失率 > 30% 的列 → 自动剔除或提示，否则结果偏差大
3. 零方差列 → 无法做归因/回归，提前过滤
4. 时间列 只有一期 → 无法做环比/归因，需要至少2期数据

check = ds.run_precheck(df)
if not check['pass']:
    # 先处理数据质量问题，再分析
    print(check)

④ 注意分析结论的边界

情况	正确做法
p<0.05 但效应量小	报告"统计显著但业务意义有限"
样本量很大	几乎任何差异都会显著，必须看效应量
非正态分布	用 Mann-Whitney U / Kruskal-Wallis 而非 t检验
多个指标同时检验	做 Bonferroni 校正，否则假阳性飙升
DID平行趋势未通过	不应报告DID结论，改用其他因果方法或标注"结论存疑"

---

安装

pip install pandas numpy scipy scikit-learn statsmodels matplotlib openpyxl

---

快速开始

基础分析

from data_scientist_core import DataScientistCore

ds = DataScientistCore()

# 自动路由（推荐新手）
result = ds.analyze(
    df=df,
    goal="分析GMV下降原因",
    params={'value_col': 'gmv', 'group_col': 'channel', 'period_col': 'month'}
)

# 指定分析类型
result = ds.attribution_analysis(df, value_col='gmv', group_col='channel', period_col='month')
print(result['data'])     # 分析结果表
print(result['insight'])  # 洞察文本
print(result['chart'])    # 图表路径

经营体检报告（v1.9新能力）

from l4_storytelling import Storytelling

s = Storytelling(output_dir='./output')

config = {
    'dimensions': ['条线', '省区', '场地'],      # 下探维度（逐级下钻）
    'metrics': ['单位成本', '总成本', '操作量'],   # 核心指标
    'period_col': '月份',
    'current_period': '2026-03',
    'prev_period': '2026-02',
    'red_light_rules': [
        {'metric': '单位成本', 'direction': 'up', 'threshold': 0.05}
    ],
}

result = s.generate_health_check_report(data=df, config=config)
# result = {
#   'html_content': '<html>...</html>',  # 完整HTML报告
#   'html_path': './output/health_check_report.html',
#   'sections': ['条线总览', '末位分析', '横向对标', '预警清单']
# }

过程指标诊断（v1.9新能力）

from l3_engine import ProcessDiagnosis

pd_engine = ProcessDiagnosis()
result = pd_engine.process_diagnosis(
    main_df=cost_df,           # 主表（成本数据）
    process_df=process_df,     # 过程表（人效/出勤/临时工等）
    main_key='场地编码',
    process_key='场地编码',
    main_metric='单位成本',
    process_metrics=['人效', '出勤率', '临时工占比']
)
# result['entity_diagnosis'] — 每个实体的诊断结论
# result['action_priorities'] — 按严重度排序的行动建议

SVG可视化（v1.9新能力）

from l4_storytelling import Storytelling
s = Storytelling()

# 折线图（返回SVG字符串，可直接嵌入HTML）
svg = s.svg_line_chart(data=df, x_col='月份', y_col='成本', title='成本趋势')

# 柱状图（支持分组）
svg = s.svg_bar_chart(data=df, category_col='省区', value_col='成本', group_col='条线')

# 热力图（相关性矩阵等）
svg = s.svg_heatmap(data_matrix=corr_matrix, row_labels=labels, col_labels=labels)

# 漏斗图
svg = s.svg_funnel_chart(steps=[1000,750,500,200], labels=['访问','注册','下单','付费'])

末位排名亮灯（v1.9新能力）

from l4_storytelling import Storytelling
s = Storytelling()

ranking = s.tail_ranking_with_light(
    data=df,
    dimension='省区',
    metric='单位成本',
    current_period='2026-03',
    prev_period='2026-02',
    period_col='月份',
    top_n=5
)
# ranking['rankings'] = [
#   {'rank':1, 'entity':'西南', 'value':4.5, 'deviation_pct': 25.3, 'light': '🔴', ...},
#   ...
# ]

html_table = s.render_tail_ranking(ranking_result=ranking)

---

四层架构

用户输入
  ↓
L1 业务场景（14个便捷入口）
  ↓
L2 分析导航（27个语义路由模式，BM25+关键词混合匹配）
  ↓
L3 度量引擎（12个模块，43个方法）
  ↓
L4 数据叙事（22个方法：matplotlib可视化 + SVG引擎 + 经营体检报告 + 过程诊断渲染）

文件结构

scripts/
├── data_scientist_core.py  (342行) — L1 便捷入口
├── l2_router.py            (682行) — L2 语义路由（BM25+关键词混合）
├── l3_engine.py            (919行) — L3 分析引擎（12模块43方法）
├── l4_storytelling.py     (1685行) — L4 可视化+报告+SVG引擎
├── eda_profiler.py         (662行) — EDA数据画像
└── test_all.py             (725行) — 测试套件（含v1.9冒烟测试）

test-prompts/
└── test-prompts.json       — 达尔文评估测试用例（5个典型场景）

import方式：

# 完整入口（推荐）
from data_scientist_core import DataScientistCore
ds = DataScientistCore()

# 直接用某一层
import sys; sys.path.insert(0, 'scripts目录')
from l3_engine import ProcessDiagnosis, Attribution  # L3模块
from l4_storytelling import Storytelling              # L4叙事
from l2_router import SemanticRouter                   # L2路由

---

L2 分析导航（27个模式）

代码	分析模式	适用场景	L3方法
A 归因分析
A1	Delta维度拆解	"哪个因子贡献了多少变化"	delta_attribution
A2	LMDI乘法因子归因	"量增还是价增"	lmdi_decompose
A3	链式序贯归因	"因果传导路径"	chain_attribution
A4	组间组内分解	"总体变化中组间/组内各自贡献"	delta_attribution
A5	分层归因	"分层内部各自归因"	stratified_attribution
B 对比分析
B1	Welch t检验	"两组均值差异"	ttest_independent
B2	帕累托分析	"主要矛盾/ABC分类"	pareto_analysis
B3	分层对比	"控制混淆后的组间对比"	stratified_comparison
C 漏斗分析
C1	线性链路漏斗	"线性转化路径"	funnel_conversion
C2	分支漏斗	"带分支选择的路径"	funnel_conversion
C3	正逆向双向漏斗	"正向+逆向漏斗"	funnel_conversion
D 用户研究
D1	同期群分析	"用户留存矩阵"	retention_cohort
D2	K-Means分群	"自动分群"	kmeans_clustering
D3	流失预测	"流失概率"	kmeans_clustering
D4	RFM价值分层	"按R/F/M分层"	rfm_analysis
E 因果推断
E1	A/B测试	"两组差异显著性"	ab_test_ttest
E2	DID双重差分	"政策/活动的真实因果"	difference_in_differences
E3	PSM倾向得分匹配	"匹配后估算ATT"	psm_matching
F 时序分析
F1	STL趋势分解	"趋势+季节+残差"	stl_decomposition
F2	异常检测	"IQR/Z-score异常"	anomaly_detection
G 经营决策
G1	杜邦ROE拆解	"ROE三因子"	dupont_roe
G2	波士顿矩阵	"四象限定位"	boston_matrix
G3	盈亏平衡	"回本点"	break_even
G4	帕累托ABC经营	"经营资源分级"	pareto_analysis
H 预测建模
H1	随机森林分类	"分类+特征重要性"	random_forest_with_importance
H2	线性回归+VIF	"线性关系+共线性"	linear_regression_with_vif
H3	ROC/AUC评估	"模型评估"	logistic_regression

---

L3 度量引擎（43方法，12模块）

关键方法返回值格式

📖 点击展开返回值结构

delta_attribution → {'data': DataFrame[group, before, after, change, contribution_pct], 'total_change': float}

difference_in_differences → {'did_estimate': float, 'means': dict, 'parallel_trend_test': {'p_value': float, 'pass': bool}, 'control_diff': float, 'treatment_diff': float}

kmeans_clustering → {'labels': array, 'centers': array, 'summary': {cluster_id: {feature: mean, 'count': int, 'pct': float}}, 'silhouette_score': float, 'optimal_k': int}

process_diagnosis → {'entity_diagnosis': [{entity, main_metric_value, process_metrics: dict, correlation_with_main: dict, diagnosis: str}], 'global_findings': str, 'action_priorities': [{entity, metric, direction, severity, suggestion}]}

generate_health_check_report → {'html_content': str, 'html_path': str, 'sections': ['条线总览', '末位分析', '横向对标', '预警清单']}

tail_ranking_with_light → {'dimension': str, 'metric': str, 'benchmark': float, 'rankings': [{rank, entity, value, prev_value, change_pct, deviation_pct, light, light_label}]}

Precheck — 数据前置检查（4方法）

方法	功能	关键参数
check_missing	缺失值检测	threshold=0.3
check_variance	零方差/常量列	—
check_sample_size	样本量充足性	min_sample=30
check_distribution	偏度/峰度检验	—

Attribution — 归因分析（4方法）

方法	功能	适用场景
delta_attribution	Delta贡献度（加法）	总量→维度拆解
lmdi_decompose	LMDI乘法因子分解	量×价分解
chain_attribution	链式序贯归因	漏斗路径归因
stratified_attribution	分层归因	控制分层层级

FunnelAnalysis — 漏斗分析（2方法）

方法	功能
funnel_conversion	漏斗转化+瓶颈定位
retention_cohort	同期群留存矩阵

Comparison — 对比分析（9方法）

方法	功能
ttest_independent	Welch t检验 + Cohen's d
pareto_analysis	帕累托ABC分类
stratified_comparison	分层组间对比
mann_whitney_u_test	Mann-Whitney U检验
kruskal_wallis_test	Kruskal-Wallis检验
anova_oneway	单因素方差分析
anova_twoway	双因素方差分析
chi_square_independence	卡方独立性检验
multiple_comparison_correction	多重比较校正（Bonferroni）

CausalInference — 因果推断（3方法）

方法	功能
difference_in_differences	DID + 平行趋势检验
psm_matching	PSM-ATT估计
uplift_modeling	Uplift增益建模（S-learner）

UserResearch — 用户研究（3方法）

方法	功能
kmeans_clustering	K-Means + 自动选K + 轮廓系数
rfm_analysis	RFM价值分层
cohort_retention	同期群留存率矩阵

Prediction — 预测建模（3方法）

方法	功能
linear_regression_with_vif	线性回归 + VIF共线性诊断
random_forest_with_importance	随机森林 + 特征重要性
logistic_regression	逻辑回归 + Odds Ratio

ABTest — A/B测试（3方法）

方法	功能
ab_test_ttest	t检验 + 置信区间 + 提升率
ab_test_chisquare	卡方检验（比例差异）
ab_test_power	功效分析 + MDE计算

TimeSeries — 时序分析（2方法）

方法	功能
stl_decomposition	STL趋势分解
anomaly_detection	IQR/Z-score异常检测

Business — 经营决策（3方法）

方法	功能
boston_matrix	BCG矩阵（明星/现金牛/问题/瘦狗）
dupont_roe	杜邦ROE三因子
break_even	盈亏平衡 + 边际贡献率

CrossValidation — 交叉验证（2方法）

方法	功能
validate_attribution	归因稳健性（贡献率≈100%）
validate_clustering	聚类有效性（最小簇+轮廓系数）

ProcessDiagnosis — 过程指标诊断（3方法，v1.9新增）

方法	功能	说明
process_diagnosis	综合过程诊断	关联主表+过程表，定位根因
process_correlation_analysis	过程指标相关性	Pearson r + 显著性（纯numpy）
process_decompose_gap	差距分解	实体 vs 标杆的指标差距贡献

---

L4 数据叙事（22方法）

matplotlib可视化（4方法）

方法	输出
plot_attribution	归因双图（贡献量+贡献率）
plot_did	DID平行趋势图
plot_clustering	聚类雷达图
plot_pareto	帕累托双轴图

洞察生成（3方法）

方法	输出
generate_insight_attribution	归因洞察（核心结论+驱动因素+行动建议）
generate_insight_did	DID洞察（净效果+置信度+平行趋势）
generate_insight_clustering	分群洞察（簇标签+策略建议）

SVG可视化引擎（4方法，v1.9新增）

方法	说明
svg_line_chart	折线图（多系列+tooltip）
svg_bar_chart	柱状图（分组+水平/垂直）
svg_heatmap	热力图（蓝→白→红梯度）
svg_funnel_chart	漏斗图（居中梯形+转化率）

纯字符串拼接，零外部依赖，可直接嵌入HTML。颜色：蓝#3B82F6 绿#10B981 红#EF4444 橙#F59E0B 紫#8B5CF6

经营体检报告（6方法，v1.9新增）

方法	功能
generate_health_check_report	主入口 — 生成四Section HTML报告
_render_section_overview	Section 1：条线总览（KPI卡片+趋势图+红绿灯）
_render_section_tail_analysis	Section 2：末位分析（逐级下探+亮灯）
_render_section_benchmark	Section 3：横向对标（vs标杆差距分解）
_render_section_alerts	Section 4：预警清单（折叠展开）
_build_html_report	HTML组装（暖色极简CSS+亮暗主题toggle）

过程诊断+末位亮灯（3方法，v1.9新增）

方法	功能
render_process_diagnosis	过程诊断HTML（相关性热力图+诊断卡片）
tail_ranking_with_light	末位排名+红黄绿灯（🟢<10% 🟡10-20% 🔴>20%）
render_tail_ranking	末位排名HTML表格

综合报告（1方法）

方法	功能
generate_report	单维度分析报告入口（attribution/did/clustering/pareto）

---

便捷方法速查（L1，14个）

ds = DataScientistCore()

# 归因
ds.attribution_analysis(df, value_col='gmv', group_col='channel', period_col='month')

# DID因果
ds.did_analysis(df, outcome_col='gmv', group_col='group', period_col='period',
                treatment_value='A', control_value='B')

# 用户分群
ds.clustering_analysis(df, feature_cols=['r','f','m'], n_clusters=4)

# A/B测试
ds.ab_test(df, value_col='gmv', group_col='version', method='ttest')

# 漏斗分析
ds.funnel_analysis(df, step_cols=['uv','click','order','pay'])

# 波士顿矩阵
ds.boston_analysis(df, product_col='sku', market_growth_col='growth',
                  market_share_col='share', revenue_col='gmv')

# 杜邦ROE
ds.dupont_analysis(df, net_profit_col='profit', revenue_col='revenue',
                   assets_col='assets', equity_col='equity')

# 盈亏平衡
ds.break_even_analysis(df, fixed_cost_col='fc', variable_cost_col='vc', price_col='price')

# 时序分解
ds.stl_decomposition(df, date_col='date', value_col='gmv', period=12)

# 异常检测
ds.anomaly_detection(df, value_col='gmv', method='iqr')

# 帕累托
ds.pareto_analysis(df, value_col='revenue', category_col='product')

# 自动路由（不确定用哪个时）
ds.analyze(df, goal="你的问题", analysis_type=None)

---

数据格式要求

分析类型	必需列
attribution	value_col + group_col + period_col
funnel	step_cols（步骤数值列）
comparison	value_col + group_col
pareto	value_col + category_col
did	outcome_col + group_col + period_col
clustering	feature_cols（数值特征）
regression/rf	target_col + feature_cols
ab_ttest	value_col + group_col
ab_chisquare	conversion_col(0/1) + group_col
stl	date_col + value_col
boston	product_col + growth + share + revenue
dupont	profit + revenue + assets + equity
health_check	dimensions + metrics + period_col + periods
process_diagnosis	main_df + process_df + keys + metrics

---

⚠️ 避坑必读

分析前必做：

check = ds.run_precheck(df)
if not check['pass']:
    print("数据异常:", check)
    # ⚠️ 不要强行分析！先处理数据质量问题
    # 常见修复：剔除高缺失列(df.dropna(axis=1, thresh=len(df)*0.7))
    #           删除零方差列
    #           补充数据量

常见误区：

• ❌ p<0.05 ≠ 有业务价值（还须看效应量Cohen's d）
• ❌ 转化率用t检验 → 应用卡方检验
• ❌ DID前必须做平行趋势检验
• ❌ 聚类前必须标准化特征
• ❌ VIF>10的变量必须处理后再回归
• ❌ 多重比较必须做Bonferroni校正
• ❌ 非正态分布用t检验 → 考虑Mann-Whitney U或Kruskal-Wallis

经营体检报告注意事项：

• ⚠️ config必须包含至少2期数据（current_period + prev_period），否则环比计算为空
• ⚠️ dimensions 建议按粒度从粗到细排列（如 ['条线','省区','场地']），确保下探逻辑正确
• ⚠️ red_light_rules 的 direction='up' 表示指标上升为异常（适用于成本类），direction='down' 适用于收入类
• ⚠️ 当数据量 < 50条时，末位分析统计意义有限，建议提示用户

---

与LangChain/Agent框架集成

from langchain.agents import initialize_agent, Tool
from data_scientist_core import DataScientistCore

ds = DataScientistCore()

analysis_tool = Tool(
    name="数据分析",
    func=lambda input: str(ds.analyze(
        df=pd.read_csv(input['file']),
        goal=input['goal'],
        analysis_type=input.get('type')
    )),
    description="当用户提供了CSV数据并询问分析问题时使用。"
)

agent = initialize_agent(
    [analysis_tool],
    llm=your_llm,
    agent="zero-shot-react-description"
)

---

版本历史

v1.9.1（2026-05-08）— 达尔文优化

• 🆕 TL;DR 60秒速览表
• 🆕 执行原则：直接给方案而非索要数据
• 🆕 4个检查点（数据范围/方法选择/异常结论/数据质量确认）
• 🆕 示例数据表（5个典型场景的必需列）
• 🆕 输出简洁性约束（3000字以内）
• 🆕 B3分层对比路由显式行
• 🆕 precheck错误恢复路径
• 📊 达尔文评分：69.5 → 84.5（+15分）
• 📊 维度8实测（GPT-5.5）：5/5 prompt全通过，18.5/25

v1.9（2026-04-16）— 经营体检系统

• 🆕 SVG可视化引擎：4种纯SVG图表（折线/柱状/热力图/漏斗），零依赖
• 🆕 经营体检报告：四Section HTML（条线总览→末位分析→横向对标→预警）
• 🆕 过程指标诊断：L3新增ProcessDiagnosis模块（相关性分析+差距分解+根因定位）
• 🆕 末位排名亮灯：红黄绿灯三级预警（🟢🟡🔴）
• 🆕 路由增强：A1/B2/B3关键词补充，3个路由失败case修复
• 🆕 L2路由：27个Pattern + METHOD_MAP映射
• 📊 L3：12模块43方法，919行
• 📊 L4：22方法，1663行

v1.8（2026-04-16）

• 洞察深度升级（severity标注+归因假设+行动优先级P0/P1/P2）
• 报告叙事结构重构（分层HTML渲染）
• 新增3个可视化方法（漏斗图/留存热力图/特征重要性图）
• Bug修复：路由缺失/优先级格式/参数顺序

v1.5（2026-04-13）

• 修复generate_report() bug
• 新增stl_decomposition/anomaly_detection便捷方法
• 新增load_goal()支持PDF/TXT/MD/Word
• L2分析导航补全至27个模式

v1.4（2026-04-08）

• 快速决策树（11种场景入口）
• LangChain集成示例

v1.3（2026-04-04）

• FunnelAnalysis/ABTest/TimeSeries/Business四大模块
• 链式归因/分层归因/PSM/Uplift/STL/异常检测/波士顿/杜邦/盈亏平衡