alchaincyf/huashu-excel

解决的问题

huashu-excel 解决了 AI 驱动的数据分析中「静默错误」这一关键问题。标准方法（如使用 pd.read_excel()）往往无法检测结构异常——例如合并单元格、多级标题或合计行与原始数据混杂——导致数学上错误的结果看似有效。本项目提供了一套严格、可审计的工作流程，确保从原始 Excel 单元格到最终报告的数据完整性和可追溯性。

如何工作

该项目作为一个与代理无关的「技能」（兼容 Claude Code、Cursor 等），实现严格的八步标准操作程序：

1. 物理检查：使用 openpyxl 在加载到 pandas 之前检查原始单元格，识别结构“脏数据”（合并单元格、标题等）。
2. 清理：将数据转换为可追溯审计路径的整洁格式。
3. 对齐：在理解数据后，与用户明确定义和基准。
4. 分析：扫描统计陷阱（如辛普森悖论、虚假分组）。
5. 再核对：使用 Excel 表格自身的「总计」行作为校验和，验证计算结果。
6. 交付：生成 HTML、XLSX 或 DOCX 格式的报告。
7. 视觉验证：检查图表是否存在误导性元素（例如，确保条形图的坐标轴从 0 开始）。
8. 质量控制：使用独立代理从原始数据重新计算结果，进行独立验证。

适用人群

专为需要专业级数据分析、准确性不容妥协的 AI 代理和用户设计，尤其适用于处理包含人工输入合计和复杂格式的现实世界业务电子表格的用户。

特色亮点

• 原始单元格优先：在 pandas 处理前，通过 openpyxl 检查原始 Excel 结构，防止信息丢失。
• 校验和集成：将电子表格中现有的「总计」行视为真实验证点，而非噪声。
• 感知准确性：基于克利夫兰-麦吉尔感知层级选择图表（例如，拒绝超过 3 个类别的饼图）。
• 稳健统计：默认使用五数概括（图基的抗干扰统计）而非均值，以应对偏斜的业务数据。
• 最小依赖：核心检查脚本仅需 openpyxl 或标准库，确保在受限环境中也能运行。