sn-da-excel-workflow

Excel 数据分析工作流

用于结构化 Excel 分析的端到端工作流。每个步骤都对应一个能力子技能，可按需加载以查看详细模式。

工作流

步骤 1 — 统计所有工作表的行数（轻量级，无需完整加载）

无需将数据加载到内存中，统计每个工作表的行数。使用 openpyxl 的 read_only 模式——无论文件大小如何，都适用。

import openpyxl, gc

wb = openpyxl.load_workbook(file_path, read_only=True, data_only=True)
total_rows = 0
sheet_info = {}
for name in wb.sheetnames:
    ws = wb[name]
    row_count = sum(1 for _ in ws.iter_rows(min_row=2, values_only=True))
    total_rows += row_count
    sheet_info[name] = row_count
    print(f"Sheet '{name}': {row_count} rows")
wb.close()
print(f"总行数={total_rows}")

⚠️ 不要使用 pd.read_excel() 统计行数——它会将所有数据加载到 内存中，大文件会导致内存溢出。

→ 能力：excel-reading/multi-sheet-reading

步骤 2 — 大文件判断（关键——根据行数选择策略）

total_rows	策略	操作
< 10k	直接读取	df = pd.read_excel(file_path, sheet_name=target_sheet)
10k – 100k	Parquet 缓存	运行一次 pd.read_excel() → df.to_parquet() → 后续读取全部使用 Parquet
>= 100k	停止。加载 sn-da-large-file-analysis 技能	阅读其 SKILL.md，然后遵循其流式读取 + Parquet 模式。完全不要使用 pd.read_excel()——对于 100k 行及以上的数据，它会导致内存溢出或超时。

对于 >= 100k 行：

read_file(path="<skills_base>/sn-da-large-file-analysis/SKILL.md")

然后使用该技能中的 stream_excel_to_parquet()——它通过 openpyxl 的 iter_rows 按每块 50k 行读取，内存占用恒定。

仅适用于 10k – 100k 行：

import pandas as pd
parquet_path = "/tmp/_auto_parquet.parquet"
df = pd.read_excel(file_path, sheet_name=target_sheet)
df.to_parquet(parquet_path, engine="pyarrow")
del df; gc.collect()
df = pd.read_parquet(parquet_path)

→ 能力：excel-reading/large-excel-reading

步骤 3 — 检查架构和数据类型

预览目标工作表结构。对于大文件（>= 10k 行），只读取少量样本—— 切勿仅为了检查而完整加载数据。

# For any file size — read only first N rows for inspection
df_head = pd.read_excel(file_path, sheet_name=target_sheet, nrows=20)
print(f"Columns: {df_head.columns.tolist()}")
print(f"Dtypes:\n{df_head.dtypes}")
print(df_head.head(10))

→ 能力：excel-reading/range-reading

步骤 4 — 数据清理

处理缺失值、规范化文本、清除无效字符。

# Missing values
null_count = df[col].isna().sum()

# Text cleaning: keep only Chinese characters
import re
def clean_text(val):
    if pd.isna(val): return val
    return "".join(re.findall(r"[\u4e00-\u9fff]", str(val))) or ""

df[col] = df[col].apply(clean_text)

⚠️ 大文件规则：当 total_rows >= 100k 时，不要使用 df.apply(lambda...)。 改用向量化操作或 np.where()。向量化速查表见 sn-da-large-file-analysis 技能。

→ 能力：

• excel-data-cleaning/missing-value-handling
• excel-data-cleaning/invalid-data-cleaning
• excel-data-cleaning/text-normalization

步骤 5 — 筛选与提取

应用条件或类别筛选，并汇总结果。

# Condition filter
mask = df[col].astype(str).str.strip() == target_value
filtered = df[mask]

# Category extraction (for headerless layouts)
df_raw = pd.read_excel(file_path, sheet_name=sheet, header=None)
# Walk rows to find category markers, collect items until next marker

→ 能力：

• excel-data-filtering/condition-filtering
• excel-data-filtering/category-filtering
• excel-data-filtering/threshold-filtering

步骤 6 — 导出结果

将筛选/清理后的数据保存为 Excel 或 CSV，并提供下载链接。

output_path = "/mnt/data/result.xlsx"
result_df.to_excel(output_path, index=False)
print(f"[Download](sandbox:{output_path})")

→ 能力：

• excel-result-export/single-sheet-export
• excel-result-export/formatted-export

关键规则

• 始终先统计行数——以 10k 为阈值决定是否启用大文件逻辑。
• >= 100k 行 → 必须加载 sn-da-large-file-analysis 技能——不要尝试使用 pd.read_excel() 处理。
• 列名可能包含空格（例如 '是否通 过'）——使用精确的字符串索引。
• 无表头的工作表——使用 header=None 和位置索引。
• 大文件（>= 100k 行）中禁止：
  • 使用 pd.read_excel() 完整加载（改用流式读取 → Parquet）
  • 使用 df.apply(lambda...) 或 df.iterrows()（改用向量化操作或 itertuples()）
  • 使用 fc-list、find ... fonts、subprocess 搜索字体，或使用 pip install（改用下方的固定字体路径）
  • 输出所有唯一值或完整 DataFrame（改用 .head()、.value_counts().head()）

CJK 字体设置（生成图表时必须设置）

使用 matplotlib 生成图表时，按原样复制此代码块。不要搜索字体。

import os
import matplotlib
import matplotlib.pyplot as plt
import matplotlib.font_manager as fm

_FONT_PATHS = [
    '/mnt/afs_agents/SimHei.ttf',
    '/mnt/afs_agents/mnt/data/SimHei.ttf',
    os.path.expanduser('~/.fonts/SimHei.ttf'),
    '/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc',
    '/usr/share/fonts/SimHei.ttf',
]
for _p in _FONT_PATHS:
    if os.path.exists(_p):
        fm.fontManager.addfont(_p)
        matplotlib.rcParams['font.family'] = fm.FontProperties(fname=_p).get_name()
        break
matplotlib.rcParams['axes.unicode_minus'] = False

如何加载子技能

每个工作流步骤都引用了一个或多个能力子技能。需要查看某个步骤的详细代码模式时，按需加载相应子技能：

read_file(path="<base_path>/<category>/<sub-skill-name>/SKILL.md")

规则：

• 仅加载当前步骤所需的子技能。
• 不要一次性加载所有子技能——这会浪费上下文。
• 顶层工作流（此文件）为你提供指引；子技能则提供详细的实现模式。

可用的能力子技能

基础路径：<skills_root>/sn-da-excel-workflow/capability/{category}/{sub-skill}/SKILL.md

excel-reading — 读取与解析

Sub-skill	功能
single-sheet-reading	读取单个工作表，支持合并单元格处理、交叉分析及多维度可视化
multi-sheet-reading	读取多工作表，动态评估数据量启用Parquet优化，支持正则清洗、分类汇总与线性拟合
range-reading	特定区域数据提取，根据数据量动态选择处理策略
large-excel-reading	大型Excel文件处理，支持Parquet转换提速，生成带条件高亮的格式化报告
multi-file-reading	多文件读取与统计，支持大文件Parquet转换与可视化报告
specific-sheet-reading	跨Sheet特定字段统计、数据清洗与交叉分析，生成带下载链接的汇总报告
structured-header-reading	动态识别目标列进行统计，正则清洗文本字段提取中文字符

excel-data-cleaning — 数据清洗

Sub-skill	功能
missing-value-handling	多Sheet智能清洗、跨表核对与可视化分析
duplicate-removal	多Sheet去重统计，生成摘要与明细报表
invalid-data-cleaning	正则清洗指定文本列（如保留中文字符），大文件自动Parquet加速
text-normalization	文本标准化清洗（去除异常前缀、提取纯中文字符等）
numeric-format-normalization	数值格式标准化，支持关键指标合计核对与结果文件导出
outlier-detection	IQR异常值检测，结合偏度/峰度分析数据分布，适用于非正态数据预处理

excel-data-filtering — 数据筛选

Sub-skill	功能
condition-filtering	根据数据规模动态选择处理策略进行条件筛选
category-filtering	自定义分类统计、交叉分析，支持文本长度/术语密度/正则匹配等综合评分与分级
range-filtering	根据多维数值条件筛选并导出，支持大规模数据自动性能优化
threshold-filtering	数值列清洗、条件过滤，使用openpyxl对符合条件的单元格进行样式标记

excel-data-analysis — 数据分析

Sub-skill	功能
comparison-analysis	两类分类数据对比分析，统计数量差异与比例关系并生成可视化
group-by-analysis	多Sheet数据清洗及分组聚合分析，生成带样式标记的统计表与图表
kpi-metric-analysis	提取关键指标进行单位一致性验证与排序分析
pivot-table-analysis	交叉表与热力图进行多维度占比分析，适用于奖项分布/绩效评估/市场占有率
time-series-analysis	时间序列趋势分析、百分比清洗、绩效分级建模与预测，生成高分辨率可视化报告
trend-analysis	多维度分级评估与趋势预测，差异化增长率计算，适用于绩效评估/目标设定

excel-data-statistics — 统计计算

Sub-skill	功能
basic-statistics	基础统计，支持按条件筛选计算均值，指定行区间提取数据去重求和
category-statistics	各类别数量与占比统计，生成柱状图/饼图等组合可视化报告
grouped-statistics	多Sheet数据合并与前向填充，分组统计
percentage-calculation	逐行扫描或列匹配提取关键指标并计算占比/均值，输出结构化报告及图表

excel-data-visualization — 数据可视化

Sub-skill	功能
bar-chart-visualization	处理合并单元格，交叉分组统计，生成支持中英文字体的美化柱状图
histogram-visualization	数值型分布分析与异常值检测，支持正则提取误差项，生成箱线图与直方图
line-chart-visualization	特征清洗与聚类分析，生成趋势对比/分布特征/参数敏感性多维度图表
pie-chart-visualization	分类汇总统计，自动识别关键字段生成包含占比/数值的美化饼图
scatter-plot-visualization	多维度统计分析与散点图可视化
stacked-chart-visualization	百分比字符串数据处理，补全缺失维度，生成堆叠柱状图展示构成变化趋势

excel-cell-coloring — 单元格着色

Sub-skill	功能
category-coloring	提取目标指标计算最大值，对特定行进行高亮标注
duplicate-value-coloring	对比多表中的特定系数并对异常值进行颜色标记
outlier-coloring	识别超限数值与错误单元格并进行高亮标注
threshold-cell-coloring	计算时间序列平均值，使用openpyxl输出带条件格式（如低于均值标绿）的报告
top-value-coloring	根据数据规模动态选择策略，多表合并、统计筛选，关键指标自动化样式高亮

excel-conditional-formatting — 条件格式

Sub-skill	功能
data-bar-formatting	从带单位字符串列提取数值并清洗，生成直方图/饼图/条形图/累积分布图

excel-result-export — 结果导出

Sub-skill	功能
single-sheet-export	多Sheet数据探查与条件过滤导出，重命名字段后生成带下载链接的Excel
formatted-export	条件筛选记录并以整行标红格式导出Excel
chart-embedded-export	分类分布清洗与统计，生成多维度交叉分析与高分辨率嵌入式图表报告
report-generation-export	从Excel提取多类型数据，生成包含可视化图表与下载链接的综合分析报告

excel-table-styling — 表格样式

Sub-skill	功能
table-theme-styling	大文件Parquet加速读取，条件筛选/分类汇总与结果导出