data-analyst — 通用数据分析与可视化

概述

全自动数据分析管线：读取任意 Excel/CSV → 智能清洗 → 多维分析 → 生成 Excel 汇总（含图表）+ 交互式 HTML Dashboard。

核心脚本: scripts/data_pipeline.py

工作流程

Step 1: 获取输入文件

确认用户提供的数据文件路径，支持格式:

.xlsx / .xls (Excel)
.csv (逗号/制表符分隔，自动检测编码)

Step 2: 执行管线

使用 scripts/data_pipeline.py 一次性完成全流程:

PYTHON=/Users/lingyuan/.workbuddy/binaries/python/envs/default/bin/python3
SCRIPT=/Users/lingyuan/.workbuddy/skills/data-analyst/scripts/data_pipeline.py

$PYTHON $SCRIPT <input_file> <output_dir> [options]

常用参数

| 参数 | 说明 | 默认值 | |------|------|--------| | input | 输入文件路径 | 必填 | | output_dir | 输出目录 | 当前目录 | | --group-by | 分组维度，逗号分隔 | 自动检测前5个分类列 | | --value-col | 汇总值列 | 自动检测（优先金额/收入类列） | | --fill-null | 空值填充值 | 0 | | --no-dedup | 不去重 | 默认去重 | | --title | 报告标题 | 从文件名提取 |

最简调用（全自动）

$PYTHON $SCRIPT "销售数据.xlsx" "./output"

指定分析维度和汇总列

$PYTHON $SCRIPT "订单数据.xlsx" "./output" --group-by "区域,产品,销售员" --value-col "金额"

Step 3: 管线执行内容

管线自动执行以下 6 个步骤:

读取数据 — 自动选择第一个有数据的 Sheet，支持 UTF-8/GBK 编码
列类型检测 — 自动识别: 日期列、分类列、数值列、文本列、ID列
数据清洗 — 去除重复行 → 统一日期格式为 YYYY-MM-DD → 空值填充
多维分析 — 按各分类维度汇总 → 月度趋势 → 交叉分析 → 洞察生成
生成 Excel — 多 Sheet 汇总表 + 原生公式 + 柱状图/折线图/饼图
生成 Dashboard — 交互式 HTML（KPI 卡片 + 6种图表 + 数据表格 + Tab 切换）

Step 4: 输出文件

管线产出:

| 文件 | 说明 | |------|------| | <name>_汇总.xlsx | Excel 汇总（多 Sheet + 图表 + 公式） | | <name>_dashboard.html | 交互式 HTML Dashboard | | <name>_analysis.json | 分析结果 JSON（供二次开发） |

Step 5: 展示结果

使用 preview_url 展示 HTML Dashboard
使用 deliver_attachments 交付所有产出文件

列类型检测规则

脚本自动识别列的语义类型，无需手动指定:

| 类型 | 检测条件 | 典型列 | |------|----------|--------| | ID | 列名含"序号/编号/ID" | 订单编号, 序号 | | 日期 | 60%+ 值可解析为日期 | 日期, 创建时间 | | 分类 | 唯一值≤30 或占比<15% | 区域, 产品, 销售员 | | 数值 | numeric 且唯一值>20 | 金额, 数量, 单价 | | 文本 | 其余字符串列 | 备注, 描述 |

高级用法

仅生成 Excel（不要 Dashboard）

$PYTHON $SCRIPT "数据.xlsx" "./output" --no-dashboard

自定义空值填充

$PYTHON $SCRIPT "数据.xlsx" "./output" --fill-null "N/A"

二次分析 / 定制化

如果用户在管线结果基础上提出更精细的需求（如"帮我加一个利润率的计算"、"把区域分成南北方再对比"）:

先用管线生成基础结果
再用 pandas/openpyxl 按用户需求做定制化处理
重新生成 Excel 和 Dashboard

此时应直接写 Python 代码处理，而非重复调用管线。

依赖

pandas, openpyxl, numpy
Python 3.9+ (推荐使用 managed runtime: /Users/lingyuan/.workbuddy/binaries/python/envs/default/bin/python3)

注意事项

汇总值列自动选择优先匹配含"金额/总额/收入/销售/成本/利润"的列名
日期统一仅对自动检测为日期类型的列生效
交叉分析在分类维度 ≥ 2 时自动触发（取前两个维度做透视）
Dashboard 中的 Chart.js 从 CDN 加载，需要网络连接