huashu-excel：让AI算出的每个数字都经得起追问的Excel全流程技能包
> 一个让AI从脏表到交付全流程可信的Excel数据分析与对账技能包，跨Agent通用，仅依赖openpyxl。
## 为什么需要huashu-excel？
在AI辅助办公的浪潮中，一个尴尬的现状是：AI能写Python脚本、能调pandas、能生成漂亮的图表，但当你把一份真实的业务Excel丢给它，要求它完成“清洗→分析→对账→交付”时，结果往往令人失望——要么表头混乱导致字段识别错误，要么数据里有合并单元格、公式残留、单位不一致等脏数据，要么分析逻辑与业务口径对不上，最致命的是：AI算出来的数字，你不敢直接拿去汇报，因为你无法追问“这个数是怎么来的”。
huashu-excel正是为解决这个痛点而生。它不是又一个数据分析库，而是一套**标准化的Excel处理工作流**，以“技能包”（skill）的形式封装了从数据体检、清洗、需求对齐、分析、对账到交付的全流程方法论，并配套了可执行的Python代码模板。它的核心承诺是：**让AI输出的每一个数字都有据可查、可复算、可追溯**。
## 项目定位与核心思想
项目名“huashu”取自“华数”或“话术”的谐音，隐含“把数据说清楚”之意。它解决的问题不是“如何用Python操作Excel”（openpyxl、pandas早已解决），而是**“如何让AI在无人监督的情况下，输出符合业务逻辑、经得起财务审计的数据结果”**。
其核心设计哲学有三条：
1. **流程强制化**：不允许AI跳过“体检”直接“分析”。先摸清数据底细，再动手。
2. **口径显性化**：所有分析假设、业务规则、字段映射必须显式写入配置或注释，杜绝“黑盒计算”。
3. **结果可追溯**：输出结果必须附带生成逻辑说明，支持对账（即用另一条独立路径验证结果）。
## 解决的具体痛点
### 痛点一：脏表无人认领
真实业务中的Excel表往往来自多个部门、多个系统导出，存在：
- 表头合并单元格、多级表头
- 同一列混有文本和数字（如“1,200元”、“1200 ”）
- 空行空列、重复行、隐藏行
- 公式残留（显示值但底层是公式）
- 编码混乱（GBK/UTF-8混杂）
常规做法是让AI“看着办”，但AI经常看走眼。huashu-excel的第一步就是**强制体检**，输出一份“数据体检报告”，列出上述所有问题，并给出严重级别。这一步相当于医院的“全身体检”，不体检不上手术台。
### 痛点二：需求理解偏差
用户说“分析一下销售情况”，AI可能做出10种不同理解。huashu-excel要求**先对齐需求**，将模糊需求拆解为：
- 分析维度（按时间？按地区？按产品？）
- 指标定义（销售额是含税还是不含税？毛利率怎么算？）
- 输出格式（表格？图表？摘要？）
- 对账要求（需要与哪个系统数字核对？）
这些以结构化表单（如JSON或Markdown模板）固化，AI必须逐项确认后才能进入分析阶段。
### 痛点三：对账难
财务场景下，AI算出的总销售额必须与ERP系统导出的数字一致，否则就是事故。huashu-excel内置**对账模块**，支持：
- 将AI计算结果与用户提供的“基准数”对比，输出差异明细
- 差异超过阈值时自动报警并列出可能原因（如漏行、重复、口径不同）
- 提供“反向计算”验证：从结果倒推原始数据，检查是否可还原
### 痛点四：交付物不可解释
很多AI生成的Excel分析报告，用户只得到一个“最终数字”，无法向领导解释计算过程。huashu-excel要求每次交付必须附带：
- 数据清洗日志（删除了哪些行、修改了哪些值）
- 计算步骤说明（每一步的输入、输出、公式）
- 异常数据清单（哪些数据不符合规则但保留）
## 安装与快速上手
### 安装
项目本身是纯Python包，依赖仅openpyxl（用于读写Excel），无其他重型依赖。安装方式：
bash
pip install openpyxl
# 克隆项目
git clone https://github.com/alchaincyf/huashu-excel.git
cd huashu-excel
注意：项目以“skill”形式存在，意味着它不是传统库，而是**一套可被LLM（大语言模型）调用的工具集**。你可以将它作为提示词模板+Python函数库结合使用。
### 基本使用示例
假设你有一张名为`sales.xlsx`的脏表，包含合并表头、缺失值和文本数字。
#### 第一步：数据体检
python
from huashu_excel.inspect import inspect_excel
report = inspect_excel("sales.xlsx")
print(report)
# 输出：
# {
# "filename": "sales.xlsx",
# "sheet_names": ["Sheet1"],
# "dimensions": {"rows": 150, "cols": 6},
# "issues": [
# {"type": "merged_cells", "count": 3, "locations": ["A1:C1", "A2:A5"]},
# {"type": "empty_rows", "count": 2, "locations": [12, 45]},
# {"type": "mixed_types", "column": "C", "examples": ["1,200元", "1200", "N/A"]}
# ],
# "severity": "high"
# }
#### 第二步：自动清洗
python
from huashu_excel.clean import clean_excel
cleaned_df = clean_excel("sales.xlsx",
rules={
"remove_empty_rows": True,
"strip_whitespace": True,
"parse_numbers": {"column": "C", "format": "remove_comma_and_unit"},
"fill_missing": {"strategy": "ffill", "columns": ["A"]}
})
cleaned_df.to_excel("sales_clean.xlsx", index=False)
#### 第三步：需求对齐模板
项目提供`requirement_template.md`，AI需按模板填写：
markdown
## 分析需求
- 目标：计算2024年各区域销售额总和及同比
- 维度：区域（列B），时间（列D，格式YYYY-MM-DD）
- 指标：销售额（列C，已清洗为数字）
- 过滤条件：剔除状态为“取消”的订单（列E）
- 输出：一张汇总表+一张柱状图
- 对账基准：财务系统2024年总销售额为 12,345,678 元
#### 第四步：执行分析并自动对账
python
from huashu_excel.analyze import analyze
from huashu_excel.reconcile import reconcile
result = analyze(cleaned_df, requirement=requirement_dict)
# 返回包含计算结果和解释的字典
recon_report = reconcile(calculated=result["total_sales"],
benchmark=12345678,
tolerance=0.001)
print(recon_report)
# {
# "match": False,
# "difference": 1234.56,
# "difference_pct": 0.01%,
# "possible_causes": ["过滤条件不一致", "存在重复行未删除"]
# }
#### 第五步：生成交付报告
python
from huashu_excel.deliver import generate_report
generate_report(result, recon_report, output_path="delivery_report.md")
# 自动生成包含数据源、清洗日志、计算步骤、对账结果、结论的完整报告
## 核心亮点深度解析
### 1. 跨Agent通用性
项目设计为**与具体LLM无关**。无论你用的是Claude、ChatGPT、通义千问还是本地Llama，只需将`skill`目录下的提示词模板（如`system_prompt.md`）和Python函数库一起提供给AI，它就能遵循这套流程。这意味着团队可以统一标准，不因换模型而改变输出质量。
### 2. 依赖极简，审计友好
仅依赖openpyxl，这意味着：
- 安装零负担，适合内网环境
- 代码可读，审计人员能轻松理解每一步操作
- 无pandas、numpy等重型依赖，减少版本冲突风险
但这也意味着它不做复杂的数据变换（如pivot、groupby需自己写Python），它更关注**流程正确性**而非**计算能力**。
### 3. 对账模块是最大差异化
大多数Excel处理工具只关注“如何算”，不关注“算得对不对”。huashu-excel将对账提升为一等公民，并且支持**多路径对账**：
- 与外部基准对账
- 与自身重复计算对账（用不同方法计算同一指标）
- 与上游明细对账（汇总数=明细数之和）
### 4. 强调“可解释性”输出
每个分析结果都附带`explanation`字段，详细描述计算逻辑。例如：
python
{
"metric": "total_sales_2024",
"value": 12345678.0,
"explanation": "从sales_clean.xlsx中筛选D列日期在2024-01-01至2024-12-31之间的行，剔除E列为'取消'的行，对C列求和。共1203行参与计算。"
}
这在财务审计、业务汇报中至关重要。
## 适用场景
### 财务与会计
- 月度对账（银行流水 vs 账面记录）
- 预算与实际对比分析
- 税务数据整理（多表合并、口径统一）
### 销售与运营
- 销售日报/周报自动生成
- 渠道数据清洗与合并（CRM导出+手工表）
- 库存盘点差异分析
### 数据分析外包/咨询
- 交付给客户的数据分析报告，需要附上完整的数据处理过程
- 多客户重复性数据清洗任务标准化
### AI Agent开发
- 如果你在构建一个“数据分析Agent”，可以将huashu-excel作为其内置技能，避免Agent自由发挥导致结果不可控。
## 同类项目对比
| 项目 | 定位 | 核心差异 |
|------|------|----------|
| **pandas** | 数据分析库 | 提供所有计算原语，但不关心流程和可解释性。huashu-excel是建立在类似pandas能力之上的流程框架。 |
| **OpenPyXL** | Excel读写库 | 只负责IO，不负责逻辑。huashu-excel使用它作为底层IO。 |
| **Excel公式/宏** | 传统办公自动化 | 不适用于AI驱动场景，且难以实现复杂清洗逻辑。 |
| **AutoGen/等Agent框架** | 多Agent协作 | 它们是“大脑”，huashu-excel是“手”——提供标准化的数据处理动作。 |
| **DataCleaner等商业工具** | 图形化清洗 | 需要人工操作，无法被AI调用。huashu-excel是纯代码，可嵌入任何AI流程。 |
**一句话总结对比**：pandas是“菜刀”，openpyxl是“砧板”，huashu-excel是“菜谱+厨师流程”——它不教你切菜，但保证你按步骤做出来的菜能端上宴会桌。
## 局限性与改进空间
1. **不支持xlsx以外的格式**（如xls、csv需先转换），但考虑到现代办公场景，xlsx已是主流。
2. **对复杂Excel功能（如数据透视表、图表对象）支持有限**，它更聚焦于数据内容和结构。
3. **对账模块需要用户提供“基准数”**，如果没有基准，则只能做内部一致性检查。
4. **目前Stars为335，社区生态尚小**，但项目结构清晰，适合二次开发。
## 总结评价
huashu-excel不是那种“惊艳”的项目，它不炫技，不追求算力，而是回归数据分析的本质——**可靠**。在AI生成内容泛滥、数字造假成本极低的今天，它提供了一种“反脆弱”的设计：即使AI完全不可信，只要它遵循这套流程，输出的结果就能被验证、被追问、被审计。
对于以下人群，强烈推荐尝试：
- 财务/运营分析师，每天与Excel打交道且需要向领导解释数字来源
- AI应用开发者，正在构建数据分析类Agent，需要标准化数据处理模块
- 咨询顾问，需要向客户交付可验证的数据分析结果
项目地址：[https://github.com/alchaincyf/huashu-excel](https://github.com/alchaincyf/huashu-excel)
如果你厌倦了“AI给个数字你不敢用”的窘境，这个项目值得你花一个下午研究并集成到你的工作流中。