excel-data-analyzer

Excel 数据分析器

概述

分析 Excel 文件，识别数据结构、质量问题、格式不一致和统计模式。生成全面的 Markdown 报告，提供可执行的数据清理和改进建议。

快速开始

只需一条命令即可分析任意 Excel 文件：

cd /path/to/skill/scripts
bun install  # First time only
bun run analyze_excel.ts /path/to/data.xlsx

输出：包含完整分析结果的 Markdown 报告（data_analysis.md）。

核心功能

1. 数据结构检测

自动识别：

• 列名和数据类型（整数、浮点数、字符串、日期、电子邮件、布尔值、混合类型）
• 每个工作表的行数和列数
• 不同值的数量
• 用于快速检查的示例值

2. 数据质量分析

检测质量问题：

• 缺失值： 每列空值的百分比和数量
• 空值过多的列： 标记缺失数据超过 50% 的列
• 混合数据类型： 识别类型不一致的列
• 格式问题： 检测前导/尾随空格、大小写不一致、数字字符串

3. 统计摘要

为数值列生成统计信息：

• 最小值、最大值、平均值、中位数、标准差
• 异常值检测： 超出 3 个标准差的值
• 值分布： 出现频率最高的前 10 个值及其计数

对于文本列：

• 最小/最大/平均长度
• 值频率分布

4. 质量评分

根据以下情况分配质量分数（0-100）：

• 缺少标题：扣 10 分
• 空值比例过高的列：扣 15 分
• 格式不一致：扣 10 分
• 列名重复：扣 15 分

5. 多工作表支持

分析工作簿中的所有工作表：

• 每个工作表的质量分数
• 逐表进行列分析
• 整个工作簿的总体质量分数

用法

基本分析

bun run analyze_excel.ts data.xlsx

生成：data_analysis.md

自定义输出路径

bun run analyze_excel.ts data.xlsx --output reports/audit.md

首次设置

运行分析脚本之前：

cd /path/to/excel-data-analyzer/scripts
bun install

此操作会安装所需依赖项（xlsx 库）。

工作流

用户提供 Excel 文件进行分析时：

1. 运行分析脚本处理提供的文件
2. 阅读生成的报告以了解分析结果
3. 向用户总结关键问题：
   • 总体质量分数
   • 最关键的问题（缺失值、格式问题）
   • 需要关注的列
4. 根据分析结果提供建议：
   • 需要检查的列
   • 建议的清理策略
   • 修复优先级（高/中/低）

报告结构

生成的 Markdown 报告包括：

执行摘要

• 文件元数据（名称、大小、工作表）
• 总体质量分数
• 高层次分析结果

按工作表分析

• 维度（行 × 列）
• 质量分数
• 检测到的问题列表
• 列分析表（类型、不同值、缺失百分比、问题）

详细列信息

对于每一列：

• 数据类型分类
• 缺失值统计
• 示例值
• 格式问题（如有）
• 统计摘要（数值列）
• 值分布

常见数据问题

高优先级问题

混合数据类型：

• 列中包含数字、字符串和日期
• 会妨碍正确分析
• 示例：123、"abc"、2023-01-15

缺失比例过高（>50%）：

• 列中的数据不足
• 考虑删除或填补数据

列名重复：

• 会导致分析含义不明确
• 需要重命名

中优先级问题

数字字符串：

• 数字以文本形式存储："123"，而非 123
• 会妨碍计算

格式不一致：

• 前导/尾随空格：" value "
• 大小写不一致："john"、"JOHN"、"John"
• 日期格式混用："2023-01-15"、"01/15/2023"

异常值：

• 超出 3 个标准差的值
• 可能表示错误或特殊情况
• 需要进一步调查

低优先级问题

缺少标题：

• 列名为空
• 会生成系统化名称（Column_1、Column_2）

文本长度差异：

• 字符串长度范围较大
• 可能表示数据录入不一致

高级模式

如需详细了解数据质量模式和检测方法，请参阅：

references/analysis-patterns.md - 综合指南，涵盖：

• 数据类型问题（混合类型、数字字符串、日期格式）
• 缺失数据模式（缺失率高、数据稀疏、占位符）
• 格式不一致（空白、大小写、分隔符）
• 统计异常（离群值、偏斜分布）
• 结构问题（重复名称、空行／列）
• 特定领域模式（电子邮件、电话号码、日期）
• 编码问题（字符编码、Unicode）

遇到异常模式或需要更深入的分析策略时，请参阅此参考资料。

输出解读

质量分数范围

• 90-100： 优秀 - 问题极少
• 70-89： 良好 - 存在轻微格式问题
• 50-69： 一般 - 存在明显的质量隐患
• 低于 50： 较差 - 存在严重的数据问题

修复优先级

1. 首先： 处理结构问题（重复列、缺少表头）
2. 其次： 修复缺失值较多的列（>50%）
3. 第三： 解决混合数据类型问题
4. 第四： 清理格式不一致问题
5. 第五： 调查离群值

性能

针对大型文件进行了优化：

• Bun 运行时： JavaScript 执行速度快
• 流式处理支持： 高效处理大型数据集，减少内存占用
• xlsx 库： 行业标准的 Excel 解析

典型性能：

• 小型文件（<1MB）：<1 秒
• 中型文件（1-100MB）：1-10 秒
• 大型文件（>100MB）：10-60 秒

限制

• 仅生成分析报告（不执行数据清理）
• 基于文本进行分析（不解读业务上下文）
• 定量分析中的统计方法假定数据为数值型
• 离群值检测采用简单的 3-sigma 规则（非稳健方法）

资源

scripts/

analyze_excel.ts - 主要分析脚本（Bun/TypeScript）

• 使用 xlsx 库解析 Excel 文件
• 检测数据类型和质量问题
• 生成统计摘要
• 生成 Markdown 报告

package.json - Bun 依赖项

• xlsx：用于解析 Excel 文件

references/

analysis-patterns.md - 数据质量模式综合指南

• 详细的检测方法
• 影响评估
• 针对各类问题的建议

assets/

report-template.md - Markdown 报告模板结构

• 展示预期的输出格式
• 用于理解报告各部分的参考资料