huashu‑excel：开源AI智能体Excel数据分析Skill

一、huashu‑excel是什么

huashu‑excel 是基于Claude‑Code Skill规范、采用MIT开源协议的AI智能体Excel数据分析能力包。

它并非传统Excel读写库，而是一套面向AI Agent完整的、带对账质控的数据分析工作流，专门解决AI处理真实业务Excel时，因合并单元格、混杂小计汇总行、脏格式导致的计算错误、结果不可信的痛点。

传统AI读取Excel大多直接通过pandas导入，容易丢失原始单元格信息；huashu‑excel优先读取原始单元格，走完体检、清洗、对账、独立复核整套流程，输出可追溯、可核验的分析结果，适配职场真实业务报表场景。

二、功能特色

1. 八步标准化数据分析流程：体检→清洗→对齐业务口径→数据分析→数据对账校验→报告交付→图表校验→独立Agent质控复核，流程按需执行，简单查询可跳过部分环节，完整分析执行全链路。

2. 脏表格强兼容：专门适配国内常见业务表格，支持两级表头、合并单元格、中间夹杂小计行、末尾合计行的非标准化Excel报表，不会直接丢弃原始单元格信息。

3. 对账校验机制：清洗后明细数据自动求和，与表格自带合计、小计交叉比对，主动发现数据偏差，定位计算口径差异问题。

4. 全流程操作留痕可回放：数据清洗、统计计算每一步都留存记录，输出清洗脚本，可追溯每一行数据的变更，方便排查数据异常来源。

5. 多环境自适应执行：自动探测Agent运行环境；支持运行Python脚本做处理；不支持脚本的环境，直接输出Excel手工操作步骤、单元格公式，兼容多种AI智能体框架。

6. 完整交付物输出：输出清洗后Excel文件、可视化图表、完整分析报告，附带业务口径说明，图表环节依赖playwright，缺失依赖会明确提示，不会虚假校验。

三、技术细节

1. 项目架构：遵循Claude‑Code Skill标准目录结构，核心文件包含SKILL.md（指令与元定义）、Python执行脚本、依赖清单，是指令层与执行脚本解耦的模块化能力包。

2. 核心依赖：基础处理仅依赖openpyxl；CSV文件处理仅使用Python标准库，无需第三方库；图表验图功能可选依赖playwright，非强制安装，缺失不会阻断主流程运行。

3. 读取逻辑：不直接使用pandas一次性全量导入表格，优先读取原始单元格对象，先完成表格结构体检，识别表头位置、脏数据、汇总行之后，再开展后续计算，规避pandas读取带来的信息丢失问题。

4. 质控实现：启用独立子Agent，复用原始数据源二次验算分析结果，做交叉复核，降低大模型幻觉带来的数据错误。

5. 兼容性：支持.xlsx、.csv格式；兼容Claude‑Code、WorkBuddy、DeepSeek Harness等多款Agent运行环境；开源协议MIT，允许自由修改、二次分发使用。

四、应用场景

• 职场业务报表分析：销售报表、运营日报月报、财务台账，处理格式混乱的业务Excel，输出可信数据分析报告。

• 脏数据清洗梳理：对表头混乱、夹杂汇总行的表格完成清洗，输出带操作记录的干净数据表。

• 数据核对对账场景：核对报表数值，定位两边数据对不上的原因，区分计算错误和业务口径差异。

• AI Agent内置数据分析能力：为私有部署AI智能体增加Excel处理模块，提升Agent表格分析的可靠性。

• 无代码Agent环境：无法运行Python脚本的AI环境，输出Excel手动操作指引，完成表格分析工作。

五、使用方法

方式1：命令行安装（Skill管理工具）

npx skills add alchaincyf/huashu-excel

方式2：本地克隆部署

将项目仓库克隆到Agent识别Skill的目录下，Agent自动加载该能力包。

方式3：零安装直接调用

无需下载部署，直接将GitHub仓库链接给到AI Agent，指令示例：

读取仓库SKILL.md，使用huashu‑excel，帮我分析上传的这份Excel文件。

安装完成后，上传Excel/CSV文件，直接使用自然语言下发指令，示例指令：

1. 帮我分析这份销售报表，输出完整分析报告

2. 核对表格中总金额数据，看看计算是否存在偏差

3. 将这份脏表格做数据清洗，输出清洗后的文件与脚本

六、竞品对比

选取pandas‑ai、Claude官方xlsx skill两款主流Agent Excel工具进行对比：

七、常见问题解答

huashu‑excel可以直接处理xls格式文件吗？

项目主要针对xlsx与csv，xls旧格式不在原生支持范围内，建议先将xls另存为xlsx格式之后再进行分析。

运行必须要安装playwright吗？

不需要。playwright仅用于图表校验的可选功能，不安装不会影响表格读取、清洗、计算、对账的核心能力，缺少该依赖工具会给出明确提示，不会虚假完成图表校验。

不使用Claude‑Code，其他Agent框架能不能用？

可以，Skill规范具备通用性，WorkBuddy、DeepSeek Harness等Agent都可以使用；环境不能执行Python脚本时，工具会转为输出Excel手工操作步骤。

所有场景都会完整执行八步流程吗？

不会，流程按需执行。如果只是查询单个数值，会精简流程；完整数据分析任务才会走完全部八步链路。

为什么同样一份表格，huashu‑excel结果和pandas直接读取结果不一样？

pandas导入会对合并单元格、小计行做隐式处理，丢失原始表格上下文信息。huashu‑excel先识别表格结构，剔除干扰的汇总小计行再统计，结果会更贴合业务实际口径。

可以修改源码做二次开发吗？

项目采用MIT开源协议，允许自由修改、二次开发，只需要遵守MIT协议相关约束即可。

八、相关链接

• GitHub项目仓库：https://github.com/alchaincyf/huashu-excel

九、总结

huashu‑excel作为面向AI智能体的开源Excel数据分析Skill，跳出传统读写库只做文件解析的定位，把业务场景下表格体检、清洗、对账、质控的完整工作流封装成标准化能力，针对性解决AI处理国内非标准化业务表格容易算错的痛点，兼顾多Agent环境适配，对于需要AI处理真实职场Excel报表的开发者与业务人员，是一套可直接落地、结果可核验的开源方案。