Metadata

name: excel-processing
description: 本地 Excel(.xlsx/.xls) 与 CSV 文件的通用处理工具，覆盖探查(probe)、清洗(clean)、数据质量(quality)、统计分析(analyze)、透视(pivot)、合并(merge)、多表一致性校验(validate)、格式化(format)、图表(chart)、HTML 报告(report)、批量处理(batch)十一类能力。当用户要求读取/整理/清洗/校验/分析/透视/合并/格式化/可视化一个或多个本地表格文件（.xlsx/.xls/.csv/.txt 逗号分隔），或希望把表格数据分析成统计结论、图表与报告时使用；也适用于数据清洗去重、按列分组汇总、多表 join、多表关键列一致性校验、生成带图表的 Excel 或自包含 HTML 报告、批量处理多个表格等场景。不用于飞书/豆包在线表格（在线表格请使用 sheet skill）。

Excel 表格处理（excel-processing）

Overview

本地 .xlsx / .xls / .csv 表格文件的深度处理工具集。核心是 scripts/excel_toolkit.py（CLI 入口）+ scripts/toolkit/ 模块包。依赖仅 openpyxl（必需）+ Python 标准库；可选 xlrd 以支持 .xls。

运行方式：

python <skill_root>/excel-processing/scripts/excel_toolkit.py <子命令> [参数]

所有子命令输出人类可读结果到控制台；输入 .xlsx/.xls/.csv 均可，输出统一 .xlsx（report 输出 .html）。CSV 自动探测编码（utf-8-sig→gbk→latin-1）。

环境与依赖

Python 3.8+ 与 openpyxl（必需）：python -m pip install openpyxl
.xls 老格式需 xlrd（可选）：python -m pip install xlrd
运行测试需 pytest（可选）：python -m pip install pytest

工作流决策

用户想要	使用命令
了解文件结构、列类型、缺失、预览	`probe`
去重、去空、补缺失、转类型、正则替换、分列、筛选、重排	`clean`
数据质量体检：缺失/重复/异常值/类型混杂	`quality`
统计指标、分组汇总、TopN、相关、趋势、帕累托、分布	`analyze`
数据透视表（行×列×值）	`pivot`
多文件拼接 / 按 key 关联	`merge`
多表关键列一致性校验（孤儿键/重复键/口径）	`validate`
让表格好看：主题、表头、列宽、冻结、筛选、条件格式	`format`
在 Excel 里嵌入柱/折/饼/散点/面积/雷达图	`chart`
交付分析结论 + 图表 + 表格的 HTML 报告	`report`
对多个文件执行同一操作	`batch`

典型端到端流程：probe → quality（体检）→ clean（清洗）→ analyze（统计）→ pivot/merge（透视/关联）→ format/chart（美化）→ report（交付报告）。

快速开始

# 0. 摸底与体检
python excel_toolkit.py probe 数据.csv --preview 5
python excel_toolkit.py quality 数据.csv --outliers --out 质量报告.xlsx

# 1. 清洗（去重、去空、去空格、补缺失、转类型、正则、筛选）
python excel_toolkit.py clean 数据.csv --out 清洗后.xlsx --drop-duplicates --drop-empty-rows \
    --strip --fill-missing 金额:0,客户:未知 --col-types 数量:int --date-cols 日期 \
    --replace-regex 城市:上海:上海市 --where 金额:gt:100

# 2. 分析（统计 + 分组 + TopN + 相关 + 趋势 + 帕累托）
python excel_toolkit.py analyze 清洗后.xlsx --groupby 城市 --agg 金额:sum,金额:mean,数量:sum \
    --top-by 品类 --corr --trend 日期 --trend-val 金额 --pareto 金额 --outliers --out 分析.xlsx

# 3. 透视与关联
python excel_toolkit.py pivot 清洗后.xlsx --rows 城市 --cols 品类 --values 金额 --agg sum --total
python excel_toolkit.py merge --files 事实表.xlsx,维表.csv --mode left --on 城市 --out 关联.xlsx

# 3.5 多表一致性校验（关联前确认键口径一致、无孤儿/重复键）
python excel_toolkit.py validate --files 事实表.xlsx,维表.csv,区域表.csv --on 城市 --unique-keys --cols 城市,金额 --out 校验.xlsx

# 4. 格式化与图表
python excel_toolkit.py format 清洗后.xlsx --out 展示.xlsx --theme teal --title "销售总览" \
    --header-style --border --zebra --auto-width --freeze A2 --filter --conditional databar
python excel_toolkit.py chart 清洗后.xlsx --type bar --cat 城市 --vals 金额,数量 --stacked

# 5. 交付 HTML 报告（默认离线 SVG；--echarts 启用联网图表）
python excel_toolkit.py report 清洗后.xlsx --out 分析报告.html

# 6. 批量处理
python excel_toolkit.py batch --files a.csv,b.csv --out-dir out/ report

子命令说明

probe — 探查文件

列出 sheet、行列数、每列非空/缺失/唯一/数值列/示例值、重复行、前 N 行预览。

python excel_toolkit.py probe <file> [--sheet 名称|索引] [--preview N] [--json] [--all-sheets]

clean — 清洗数据

按固定顺序执行（仅启用带参数的选项）：重命名 → 删列 → 去空格 → 全半角 → 大小写 → 数值去符号 → 简单替换 → 正则替换 → 删空行 → 行筛选 → 去重 → 填充缺失 → 分列 → 列重排 → 类型转换 → 日期格式化。

python excel_toolkit.py clean <file> [--out 输出.xlsx]
  [--rename 旧:新] [--drop-cols 列A,列B]
  [--strip] [--full-half] [--full-half-cols 列] [--lower 列|--upper 列]
  [--strip-symbols 列]                    # 去货币/百分比符号并转数值
  [--replace 列:旧:新] [--replace-regex 列:正则:替换]
  [--where 列:op:值]                      # eq/ne/contains/gt/gte/lt/lte/isnull/notnull
  [--drop-empty-rows] [--drop-duplicates]
  [--fill-missing-all 值] [--fill-missing 列:值]
  [--split-col 列 --split-delim , --split-names 新列名...]
  [--reorder 列A,列B]
  [--col-types 列:int/float/str/date] [--date-cols 列]
  [--header-row N] [--skip-rows N] [--encoding 编码]

quality — 数据质量报告

逐列检查缺失率、唯一值、全角字符、类型混杂、异常值（IQR/Z），表级检查重复行，输出问题清单。

python excel_toolkit.py quality <file> [--outliers] [--outlier-method iqr|zscore] \
    [--missing-threshold 0.5] [--out 质量.xlsx]

analyze — 统计分析

描述性统计（始终）：count/missing/min/q25/mean/median/mode/q75/max/std/sum
分组聚合：--groupby 列 --agg 列:sum,列:mean（可同列多聚合；sum/mean/median/max/min/count/std/first/nunique）
TopN 频次：--top-by 列 --top N
相关矩阵：--corr
分布直方图：--histogram 列 --hist-bins N
时间趋势：--trend 日期列 --trend-val 数值列（按月聚合）
异常值检测：--outliers --outlier-method iqr|zscore
帕累托：--pareto 数值列 --pareto-top N
--out 写入 xlsx（stats/top_freq/groupby/correlation/trend/outliers/pareto/histogram 各 sheet）

pivot — 数据透视表

python excel_toolkit.py pivot <file> --rows 行字段 [--cols 列字段] --values 值字段 \
    [--agg sum|mean|median|max|min|count] [--total] [--sort asc|desc] [--out 透视.xlsx]

merge — 合并

# 纵向拼接（列取并集，缺失补空）
python excel_toolkit.py merge --files a.csv,b.csv --mode append --out 合并.xlsx
# 横向按 key 连接（inner/left/right/outer，逐行保留）
python excel_toolkit.py merge --files 事实表.xlsx,维表.csv --mode left --on 城市 --out 关联.xlsx

validate — 多表一致性校验

对 2+ 个共享同一关联键的文件做一致性体检：键列存在性、表间键集合一致性（孤儿键）、表内键唯一性、共享列口径（类型）一致性。输出判定 PASS / WARN / FAIL 与可写 xlsx 报告（overview / key_matrix / issues）。

python excel_toolkit.py validate --files a.xlsx,b.csv,c.csv --on 城市
  [--unique-keys]          # 要求各表内键唯一，有重复则 FAIL
  [--cols 列A,列B]          # 检查共享列是否存在、底层类型是否一致
  [--out 校验.xlsx]

典型用途：多表 join/merge 前先校验关联键口径，避免合并出孤儿数据或键重复。

format — 格式化

python excel_toolkit.py format <file> [--out 输出.xlsx]
  [--theme professional|clean|colorful|green|warm|dark|gray|teal|purple|soft]
  [--title "大标题" --title-span 列数 --title-height N]
  [--header-style --header-height N] [--border] [--zebra] [--wrap] [--row-height N]
  [--auto-width] [--freeze A2] [--filter] [--table]
  [--num-format 列:格式] [--align 列:left|center|right]
  [--conditional databar|colorscale|iconset]

注意：--num-format 参数值若形如盘符路径（如 E:...）会被部分命令行环境的安全策略拦截，属环境限制；可改用列号形式或 --theme/--conditional 替代。

chart — 图表

python excel_toolkit.py chart <file> --type bar|line|pie|scatter|area|doughnut|radar
  [--cat 分类列] [--vals 数值列1,数值列2] [--title 标题]
  [--stacked]                      # bar/area 堆叠
  [--combo 叠加列]                 # 柱上叠线 / 线上叠柱
  [--horizontal] [--scatter-x 列]  # 横向条形 / 散点 X 轴
  [--style N --width W --height H --x-axis --y-axis --no-legend]
  [--to-sheet 目标sheet] [--out 输出.xlsx]

多数值列时生成多个图表并排；不指定 --vals 自动取数值列。

report — HTML 分析报告

自包含 HTML：指标卡 + 列概览 + 数值列统计与图表 + 类别 Top10 + 时间趋势 + 异常值提示。默认纯内联 SVG（离线可用）；--echarts 用 ECharts CDN 真正渲染图表（需联网）。

python excel_toolkit.py report <file> [--sheet] [--echarts] [--out 报告.html]

batch — 批量处理

python excel_toolkit.py batch --files a.csv,b.csv [--out-dir out/] <子命令> [子命令参数...]
# 例：对两个文件各生成报告
python excel_toolkit.py batch --files a.csv,b.csv --out-dir out/ report

注意事项

format/chart 未指定 --out 时就地修改原文件；其余命令默认输出新文件。
CSV 读入时自动跳过整行空行、自动探测编码；不隐式转换数值（保留原始文本，避免编号前导零被破坏），数值判定与货币/百分比符号解析在统计/分析时按需进行。
写入 Excel 时数值列保持数值类型（可继续 SUM/AVERAGE），不转字符串。
每个命令对不存在文件/sheet/列给出明确中文报错，不静默失败；缺少必填参数、参数取值非法、未知参数也以中文提示（并附带 usage）。
文件不存在/无权限访问时会附一行操作建议（如检查路径、确认文件已生成）。
merge/validate 为多文件命令，不适用于 batch 的逐文件循环。
复杂任务建议先 probe + quality，确认列名与类型再清洗/分析。

Resources

references/operations.md — 全部子命令完整参数、示例与边界情况。
tests/ — 单元测试（python -m pytest tests/）。

Excel 处理

安装技能