huashu-excel 是一个让 AI 代理（Agent）具备专业数据分析与 Excel 全流程处理能力的通用技能包，覆盖脏表体检、数据清洗、需求对齐、深度分析、对账核验与交付报告六大环节，依赖仅 openpyxl，跨 Agent 即插即用。

一、痛点：AI 算数快，但算得“不靠谱”

在过去两年里，AI 辅助数据分析已经不是什么新鲜事。你可以在 ChatGPT、Claude 或各类国产大模型里直接丢一个 CSV 文件，让它“帮我分析一下销售趋势”，几秒钟后就能得到一段漂亮的文字总结。

但问题来了：你敢把这份总结直接发给老板吗？

大多数情况下不敢。因为 AI 的分析结果往往存在以下致命伤：

1. 脏数据识别缺失：Excel 里常见的合并单元格、空行、重复表头、文本型数字、日期格式错乱、公式残留，AI 往往视而不见，直接拿脏数据算平均数，结果自然离谱。
2. 需求理解表面化：你说“分析一下业绩”，AI 就给你算个总和和平均值，但你要的可能是同比、环比、贡献度、异常值检测、Top/Bottom 排名、结构占比。
3. 结果不可追溯：AI 给出的数字，你无法快速验证它到底怎么算出来的。如果老板追问“这个 3.2% 是怎么来的？”，你只能一脸茫然。
4. 对账环节缺失：财务场景下，数据必须两边对得上。AI 不会主动帮你做差异核对，更不会告诉你哪些行对不上、差在哪。
5. 交付格式不规范：AI 生成的 Excel 往往格式混乱，没有标题样式、没有颜色标注、没有数据透视表，甚至打开就报错。

huashu-excel 正是为了解决这些问题而生。 它不是一个简单的“Excel 操作库”，而是一套完整的、可嵌入任何 AI Agent 的 数据分析工作流技能包。

二、项目概览：一个 skill，六大环节

项目地址：https://github.com/alchaincyf/huashu-excel

作者将整个数据分析流程拆解为六个标准步骤，每个步骤对应一个独立的 skill 文件（即 Python 模块），Agent 可以按需调用：

阶段	功能	对应文件
体检	检查表格结构、脏数据、异常值	1_examine.py
清洗	标准化数据、去重、补全	2_clean.py
对齐	明确分析目标、确认口径	3_align.py
分析	执行统计、透视、趋势分析	4_analyze.py
对账	双重校验、差异定位	5_reconcile.py
交付	生成规范 Excel 报告	6_deliver.py

整个项目仅依赖 openpyxl 一个第三方库，Python 标准库即可完成其余工作。这意味着它可以在任何 Python 环境中运行，无论是本地脚本、FastAPI 服务、还是 LangChain / AutoGen / CrewAI 等 Agent 框架。

三、安装与快速上手

3.1 安装

bash
pip install openpyxl

或使用 uv（推荐）

uv add openpyxl

然后将项目克隆或下载到本地，导入对应的 skill 模块即可：

python
import sys
sys.path.append('/path/to/huashu-excel')

from huashu_excel.examine import examine_excel
from huashu_excel.clean import clean_excel
from huashu_excel.analyze import analyze_excel

3.2 最小示例：体检一张脏表

假设你有一张名为 sales.xlsx 的销售表，里面包含合并单元格、空行、文本数字等问题：

python
from huashu_excel.examine import examine_excel

第一步：体检

report = examine_excel('sales.xlsx')
print(report)

输出示例：

{

'sheet_name': 'Sheet1',

'rows': 105, 'cols': 8,

'merged_cells': 3, 'empty_cells': 12,

'text_numbers': 5, 'duplicate_rows': 2,

'date_format_issues': 1,

'suggestions': ['合并单元格需取消', '文本数字需转数值', ...]

}

3.3 完整流程：从脏表到交付报告

python
from huashu_excel.examine import examine_excel
from huashu_excel.clean import clean_excel
from huashu_excel.align import align_requirements
from huashu_excel.analyze import analyze_excel
from huashu_excel.reconcile import reconcile_data
from huashu_excel.deliver import deliver_report

1. 体检

exam = examine_excel('raw_sales.xlsx')

2. 清洗（自动处理体检发现的问题）

clean_path = clean_excel('raw_sales.xlsx', exam)

3. 对齐需求（传入用户的问题描述）

req = "按月份和产品类别统计销售额，同时计算环比增长率"
aligned = align_requirements(clean_path, req)

4. 分析

table = analyze_excel(clean_path, aligned)

5. 对账（用原始数据交叉验证）

recon = reconcile_data(clean_path, table)

6. 交付

deliver_report(table, 'final_report.xlsx')

整个流程跑完后，final_report.xlsx 是一份格式规范、带有数据透视表、颜色标注和结论摘要的专业报告。

四、核心亮点深度拆解

4.1 体检：像老会计一样“扫一眼”就知道哪里脏

examine_excel 函数做得非常细致，它会检查：

• 合并单元格：合并单元格会导致数据读取错位，必须检测并给出处理建议
• 空行/空列：影响 pandas 或 openpyxl 的读取范围
• 重复表头：两行表头是 Excel 里的常见坑
• 文本型数字：比如 '123' 存成字符串，求和时会被忽略
• 日期格式混乱：2024/1/1、2024-01-01、20240101 混在一列
• 异常值：比如销售额出现负数、单价为 0、超过 3σ 的离群点
• 重复行：完全相同的记录可能是重复导入

体检结果以 JSON 形式返回，同时附上每条问题的修复建议，Agent 可以直接调用 clean_excel 自动修复，或者向用户确认后再处理。

4.2 清洗：不改变原始数据，生成清洗后的副本

clean_excel 会读取原始文件，生成一个 _cleaned.xlsx 副本，所有操作都在副本上进行，原始数据永远安全。清洗操作包括：

• 取消合并单元格（填充或留空，可配置）
• 删除完全重复的行
• 将文本型数字转为数值类型
• 统一日期格式为 YYYY-MM-DD
• 填充缺失值（均值/中位数/前向填充/后向填充，可配置）
• 去除首尾空格、统一列名大小写

4.3 对齐：让 AI 少“猜”你的意思

这是 huashu-excel 最有特色的环节。align_requirements 接收用户的自然语言描述，将其解析为结构化的分析意图，包括：

• 指标：销售额、利润、数量、单价等
• 维度：时间（年/月/日）、产品、地区、渠道、客户等
• 统计方法：求和、平均、中位数、标准差、最大最小、TopN、占比、同比、环比
• 筛选条件：时间范围、特定产品/地区

对齐结果会返回给 Agent，Agent 可以再次向用户确认：“您要的环比是按月环比还是按季度环比？” 这一步极大减少了 AI 自作主张导致的错误。

4.4 分析：不止是算数，还有业务洞察

analyze_excel 内置了常用的分析模式：

• 描述性统计：均值、中位数、标准差、四分位数
• 趋势分析：时间序列的移动平均、增长率、季节性指数
• 结构分析：帕累托分析（80/20 法则）、占比、贡献度
• 对比分析：同比、环比、分组对比
• 异常检测：基于 Z-score 或 IQR 的离群点标记

分析结果会以结构化表格返回，每一行都有对应的计算逻辑注释，方便 Agent 生成解释文本。

4.5 对账：这是其他工具几乎不做的事

reconcile_data 是 huashu-excel 的杀手锏。它会：

1. 用原始清洗后的数据重新计算一遍核心指标
2. 与 analyze_excel 的结果做逐项对比
3. 如果差异超过阈值（默认 0.01%），则定位到具体行和列
4. 生成差异报告，说明差异原因（如：清洗时删除了 2 行导致合计不同）

这对于财务、审计场景至关重要。AI 算错不可怕，可怕的是算错了还发现不了。 对账环节让 AI 的结果具备可验证性。

4.6 交付：专业级 Excel 报告

deliver_report 生成的 Excel 文件包含：

• 标题行（带加粗和背景色）
• 自动列宽调整
• 数据透视表（自动创建）
• 关键指标用条件格式标红/标绿
• 结论摘要放在第一个 sheet 顶部
• 所有 sheet 命名规范（如“数据”“透视”“结论”）

打开就能直接用，不需要二次美化。

五、适用场景

huashu-excel 适用于以下典型场景：

1. 财务对账：月度账单核对、银行流水对账、发票核验。对账功能直接命中刚需。
2. 运营报表：每周/每月的销售、用户、流量数据整理与趋势分析。
3. 数据清洗外包：把脏乱差的 Excel 交给 AI Agent，让它先清洗再分析，减少人工劳动。
4. 自动化报告生成：接入定时任务，每天自动拉取数据、分析、生成报告邮件。
5. 企业内部 AI 助手：部署在公司私有化环境中，员工通过聊天机器人上传 Excel，获得专业分析结果。
6. 教学与审计：帮助学生或审计人员快速验证 AI 计算结果的正确性。

六、同类项目对比

特性	huashu-excel	pandas + 手动代码	Microsoft Copilot in Excel	其他 Excel Agent 库（如 excel-agent）
工作流完整性	✅ 六大环节闭环	❌ 需要自己写	✅ 但仅限微软生态	⚠️ 部分覆盖
脏数据检测	✅ 内置 10+ 规则	❌ 需自行实现	⚠️ 有限	⚠️ 有限
对账核验	✅ 独有功能	❌ 无	❌ 无	❌ 无
跨 Agent 通用	✅ 纯 Python 模块	✅ 任何环境	❌ 仅 Copilot	⚠️ 依赖特定框架
依赖轻量	✅ 仅 openpyxl	❌ pandas 重依赖	❌ 闭源	⚠️ 可能依赖 pandas
可定制性	✅ 源码可改	✅ 完全可控	❌ 黑盒	⚠️ 部分可改
学习成本	低（有文档和示例）	高（需熟悉 pandas）	低（但能力受限）	中

对比结论：

• 如果你只想在本地用 pandas 处理数据，不需要 AI 介入，那 huashu-excel 不是你的菜。
• 如果你在用 AI Agent（如 LangChain、Dify、Coze）开发数据分析功能，huashu-excel 是目前最轻量、最完整的“插件式”技能包。
• 相比微软 Copilot，它不依赖云端闭源服务，数据完全本地化，适合金融、政务等敏感场景。

七、技术细节与扩展性

7.1 为什么只用 openpyxl？

作者刻意避免 pandas，原因有三：

1. 轻量：pandas 依赖 numpy，安装包体积大，在 Serverless 或边缘环境部署困难。
2. 可控性：openpyxl 直接操作单元格，每一步逻辑都透明，方便对账和调试。
3. 兼容性：openpyxl 对 Excel 的格式保留更好，不会像 pandas 那样丢失样式、公式或图表。

7.2 如何接入自己的 Agent？

以 LangChain 为例，只需将每个 skill 包装成 Tool：

python
from langchain.tools import Tool
from huashu_excel.examine import examine_excel
from huashu_excel.clean import clean_excel

tools = [
Tool(name="examine_excel", func=examine_excel, description="检查Excel文件脏数据"),
Tool(name="clean_excel", func=clean_excel, description="清洗Excel文件"),
# ... 其他工具
]

然后交给 Agent 使用

任何支持工具调用的 Agent 框架（OpenAI Function Calling、Claude Tool Use、Coze Plugin）都可以同理接入。

7.3 扩展方向

• 支持更多文件格式：目前仅支持 .xlsx，未来可加入 .xls、.csv
• 可视化图表：可以基于 openpyxl 的 chart 模块生成柱状图、折线图
• 规则自定义：脏数据检测规则可配置（如自定义异常值阈值）
• 多语言支持：分析结论可输出中英文

八、总结评价

优点：

• 设计思路清晰，六大环节覆盖了数据分析的全生命周期，尤其是“对账”和“对齐”两个环节，直击 AI 数据分析的信任痛点。
• 代码简洁、无重型依赖，阅读和二次开发成本低。
• 输出结构化，方便 Agent 理解和继续处理。

不足：

• 目前不支持 .csv 和 .xls 格式，限制了部分场景。
• 清洗规则虽然覆盖了常见问题，但面对极端复杂的嵌套表头、多 sheet 关联，仍需手动扩展。
• 项目尚在早期阶段（Stars 335），社区和文档还有提升空间。

适合人群：

• 正在用 AI Agent 做数据分析的开发者
• 企业内部工具开发人员，需要快速实现“上传 Excel → AI 分析 → 输出报告”的流程
• 对数据可信度有高要求的财务、审计场景从业者

如果你厌倦了 AI 给你一张“看似完美但经不起追问”的分析表，不妨试试 huashu-excel 这套流程——它让每一个数字都有来源，每一步计算都有记录，每一份报告都经得起老板的盘问。

项目地址：alchaincyf/huashu-excel