huashu-excel：让AI算出的每个数字都经得起追问的Excel全流程技能
> 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](https://github.com/alchaincyf/huashu-excel)