huashu-excel：让 AI 处理 Excel 不再“答非所问”的全流程技能包
> 一个让 AI 对 Excel 数据全流程负责（体检、清洗、分析、对账、交付）的通用技能包，数字经得起追问。
## 一、痛点：AI 算 Excel，总是“看起来对，一追问就崩”
过去两年，用 ChatGPT、Claude 或各类国产大模型处理 Excel 表格，几乎每个深度用户都经历过同样的挫败：
- **数据脏，AI 看不见**：表格里有合并单元格、空行、重复表头、单位混写（“万”和“元”混在一列）、日期格式五花八门。AI 直接读，算出来的均值、汇总全是错的，但它自己不知道。
- **需求模糊，AI 瞎猜**：你说“分析一下销售数据”，AI 不知道你是要同比环比、要 Top10、还是要看地区差异。它给出一个“通用分析”，看起来漂亮，但根本不是你要的。
- **对账无据，AI 不解释**：AI 告诉你“这个月利润是 85 万”，但你问它“这 85 万怎么来的？扣掉退货了吗？含税吗？”——它答不上来，或者开始编。
- **交付不专业**：AI 给的表格没有数据字典、没有校验说明、没有异常标记，你拿不出手给老板或客户。
根源在于：**大多数 AI 工具只把 Excel 当作“文本”来读，而不是当作“数据表”来对待**。它们跳过了数据清洗和需求对齐，直接输出结果，自然经不起推敲。
## 二、huashu-excel 是什么？
一句话：**一套把 Excel 数据分析从“脏数据进、漂亮结论出”变成“脏数据进、干净数据+可追溯结论出”的完整方法论 + 可执行代码**。
它不是又一个 Excel 操作库（不是 pandas 替代品），而是一个 **skill 层** 的封装——它定义了 AI 在处理表格时应遵循的流程（流程），并提供了对应的 Python 工具函数（基于 openpyxl，零重依赖）。
项目名“huashu”取自“华数”（华为数据）或“话术”的谐音，作者意图很明确：**让 AI 的“话术”建立在真实可查的数据上**。
## 三、核心流程：五步走，每一步都留痕
项目把 AI 处理 Excel 的完整过程拆解为五个阶段，每个阶段都有明确的输入、输出和检查点：
### 1. 体检（Health Check）
AI 先对表格做“体检”，就像医生看病人一样，不急着下结论，先查体征。
体检项包括：
- 是否存在合并单元格（这是 Excel 数据的大敌）
- 是否存在空行/空列/空单元格
- 表头是否重复或缺失
- 数据类型是否一致（同一列有没有混着文本和数字）
- 是否有隐藏行/列
- 单元格内是否有换行符、多余空格
**输出**：一份体检报告，列出所有问题及位置（如“第 3 行到第 5 行存在合并单元格，建议拆分”）。
### 2. 清洗（Cleaning）
根据体检报告，AI 自动执行清洗操作，但**每一步清洗都记录在案**：
- 删除空行/空列
- 拆分合并单元格并填充
- 统一日期格式
- 去除首尾空格
- 修正明显的类型错误（如“1,000”转为 1000）
清洗后，AI 会输出一份“清洗日志”，告诉你它动了哪些地方，原始值是什么，新值是什么。**这是后续“经得起追问”的基础**。
### 3. 对齐需求（Requirement Alignment）
这是最被低估但最重要的一步。AI 在分析之前，先向用户确认：
- 你要分析的维度是什么？（时间？地区？产品线？）
- 你要的指标是什么？（销售额？利润？增长率？）
- 你要的口径是什么？（含税/不含税？含退货/不含退货？）
- 你要的对比基准是什么？（环比？同比？预算？）
如果用户没说清楚，AI 会给出几个候选理解，让用户选。**这一步避免了“AI 自嗨式分析”**。
### 4. 分析（Analysis）
基于清洗后的数据和确认过的需求，AI 执行分析。分析过程要求：
- 每一步计算都要有公式或代码可查
- 中间结果要保留（如“先按地区汇总，再按月份汇总”）
- 异常值要标记（如增长率超过 500% 的数据点）
- 结论要附上数据支撑（“2024 年 Q3 华东区销售额 1.2 亿，占全国 34%，主要增长来自新品类 X”）
### 5. 对账与交付（Reconciliation & Delivery）
这是 huashu-excel 的独特之处。AI 在交付前，会主动做“对账”：
- 检查汇总数字是否等于明细之和
- 检查清洗前后的总数差异（如果清洗删除了 100 行，那 100 行是什么？）
- 检查是否有数据在分析中被遗漏（如空值被忽略但占比过高）
最终交付物包括：
- 清洗后的干净 Excel 文件
- 一份 Markdown 格式的分析报告
- 一份“数据字典”（每列的含义、单位、取值规则）
- 一份“疑点清单”（哪些数据不可靠，建议人工复核）
## 四、安装与使用
项目依赖极简：**仅 openpyxl**（以及 Python 3.8+）。安装只需两步：
bash
pip install openpyxl
# 然后克隆仓库或直接复制 skill 文件
更推荐的方式：如果你使用 Claude、ChatGPT 或其他支持 skill/自定义指令的 agent，直接把 `skill.md`（或项目中的 prompt 模板）导入你的 agent 配置中。
以 Claude 的 skill 用法为例（伪代码）：
markdown
# 在 CLAUDE.md 或 skill 配置中引用
当用户要求处理 Excel 文件时，必须执行以下流程：
1. 先调用 `health_check()` 函数体检表格
2. 展示体检报告，等待用户确认或自动清洗
3. 清洗后必须输出清洗日志
4. 询问用户分析需求（维度、指标、口径）
5. 执行分析，保留中间步骤
6. 最终输出必须包含：数据字典 + 疑点清单 + 可复现的计算逻辑
项目提供了 Python 函数库，你也可以直接调用：
python
from huashu_excel import HealthChecker, Cleaner, Analyzer, Reconciler
# 1. 体检
issues = HealthChecker.check("sales.xlsx", sheet_name="Sheet1")
print(issues) # 输出问题列表
# 2. 清洗
clean_df, cleaning_log = Cleaner.clean("sales.xlsx", issues)
print(cleaning_log) # 输出清洗记录
# 3. 分析（需先对齐需求）
results = Analyzer.analyze(clean_df,
dimensions=["region", "month"],
metrics=["sales", "profit"],
filters={"year": 2024})
# 4. 对账
recon_report = Reconciler.reconcile(clean_df, results)
print(recon_report) # 输出对账结果
## 五、核心亮点深度解析
### 亮点 1：跨 Agent 通用
项目不绑定任何特定 AI 平台。它是一套“方法论 + 工具函数”，你可以把它用在：
- Claude（通过 Skill 或自定义 instructions）
- ChatGPT（通过 GPTs 或自定义 prompt）
- 本地 Ollama + LangChain
- 任何支持 Python 代码执行的 agent
这意味着你学一次，到处能用。
### 亮点 2：依赖极简，审计友好
只用 openpyxl，不用 pandas（虽然 pandas 更流行，但 openpyxl 更轻、更接近 Excel 原生结构，且容易审计）。这降低了企业部署的安全风险——不需要安装庞大的数据科学依赖栈。
### 亮点 3：强调“可追溯性”
每个数字都能回溯到原始表格的某个单元格。这是与其他 AI 数据分析工具最大的区别。比如你问“为什么华东区利润是 1200 万？”，AI 会回答：“因为华东区的销售明细共 356 行，每行的利润 = 销售额 - 成本 - 运费，其中运费在第 12 行到第 14 行的备注列有特殊处理（跨省运输加收 5%），具体见清洗日志第 7 条。”
### 亮点 4：内置“对账”环节
很多 AI 工具只做“分析”，不做“对账”。huashu-excel 强制要求 AI 在交付前检查数据一致性。这个环节特别适合财务、审计场景。
## 六、适用场景
1. **财务月报/季报分析**：需要多口径汇总、对账、留痕。
2. **销售数据清洗与分析**：销售表格通常很脏（多级表头、合并单元格、单位不统一）。
3. **运营数据周报**：需要快速产出但又要保证数字准确。
4. **审计准备**：需要每一步处理都有记录，方便复核。
5. **数据迁移前的体检**：在把 Excel 导入数据库前，先用它做数据质量检查。
## 七、同类项目对比
| 维度 | huashu-excel | pandas + ChatGPT | 传统 ETL 工具（如 Power Query） | 商业 BI 工具（如 Tableau） |
|---|---|---|---|---|
| **定位** | AI 技能包/方法论 | 临时性代码生成 | 数据清洗工具 | 可视化分析平台 |
| **数据清洗** | 内置体检+清洗+日志 | 需要自己写代码 | 强，但需手动配置 | 弱，需预先处理 |
| **需求对齐** | **强制**（先问再算） | 靠 prompt 碰运气 | 不适用 | 不适用 |
| **可追溯性** | 极强（清洗日志+对账） | 弱 | 中 | 弱 |
| **交付物** | 干净表+报告+字典+疑点清单 | 只有代码和输出 | 只有清洗后的表 | 只有图表 |
| **依赖** | 仅 openpyxl | pandas 等 | 商业软件 | 商业软件 |
| **适用人群** | AI 重度用户、数据团队 | 数据工程师 | 数据分析师 | 业务人员 |
**核心差异**：pandas + ChatGPT 是“你问它答”，huashu-excel 是“它先体检、再问需求、再算、再对账、再交付”。后者更像一个训练有素的初级分析师，而不是一个“计算器”。
## 八、局限性（客观评价）
- **不适合大规模数据**（>10 万行）：openpyxl 处理大文件性能不如 pandas + 内存优化。
- **需要 AI 模型遵循流程**：如果你用的模型不擅长遵循多步骤指令，效果会打折扣。建议配合 Claude 或 GPT-4 级别模型使用。
- **不提供可视化**：它专注数据准确性和流程，图表需要另外接 matplotlib 或导入 BI 工具。
- **对 Excel 公式支持有限**：如果原表格有复杂公式（如 VLOOKUP 链），openpyxl 读取的是公式字符串而非计算结果，需要额外处理。
## 九、总结
huashu-excel 解决的不是“AI 能不能读 Excel”的问题，而是“AI 读 Excel 后，你敢不敢信它的结果”的问题。它把数据分析中最容易被跳过的脏活累活（体检、清洗、对齐、对账）变成了强制流程，并且每个环节都有日志可查。
对于所有在工作中依赖 AI 处理表格、且对数字准确性有高要求的用户（财务、运营、数据分析师），这个项目值得花一小时研究并接入你的 agent 工作流。它不会让 AI 变得更聪明，但会让 AI 变得更**可靠**。
项目地址：https://github.com/alchaincyf/huashu-excel