huashu-excel

huashu-excel 是一个专为 AI 代理（Agent）设计的数据分析技能（Skill），解决 AI 在处理 Excel 数据时常见的“静默错误”问题。它不只是一个自动化工具，更是一套严谨的数据分析全流程方法论，涵盖体检、清洗、对齐、分析、对账到交付的八个标准步骤。其核心目标是确保每一个输出的数字都能被追溯到原始单元格，让“这个数你怎么算的？”不再是一个无解的问题。

为什么需要 huashu-excel？

在传统的数据分析中，AI 往往直接调用 pandas.read_excel()，但这会导致大量隐性错误：

• 结构误读：合并单元格、多级表头、标题行错位导致数据偏移。
• 噪音干扰：将“合计”、“小计”行误认为普通数据，导致总额虚高（如案例中误差高达 +161%）。
• 格式陷阱：千分位逗号、文本型数字、非标准日期格式导致计算失败或结果为 0。
• 静默出错：AI 算错时不会报错，错误的结果与正确的结果长得一模一样，极具误导性。

huashu-excel 通过先读原始单元格再动 pandas 的策略，在计算前进行全面的“体检”，并利用表内自带的“合计”行作为免费校验和进行交叉对账，确保数据的绝对准确。

核心工作流：八步标准作业程序 (SOP)

1. 🩺 体检 (Profile)：使用 openpyxl 读取原始单元格，识别表头位置、合并单元格、汇总行、重复行及数据类型异常。不看数据，先看结构。
2. 🧼 清洗 (Clean)：生成可审计、可回放的 pandas 脚本，将非规范数据转化为标准分析表。
3. 🤝 对齐 (Align)：在理解数据分布后，与用户澄清分析目标、口径及外部基准，避免“带着错的问题做完整的分析”。
4. 📊 分析 (Analyze)：扫描辛普森悖论、幽灵分组、小基数等统计陷阱，提供基于中位数和 IQR 的抗差统计，而非默认的均值。
5. ⚖️ 对账 (Reconcile)：将清洗后的明细求和与表内“合计/小计”行进行交叉验证。对不上就不给数字。
6. 📦 交付 (Deliver)：生成 Excel、图表或报告，并附带完整的计算口径说明。
7. 🖼️ 验图 (Verify Visual)：自检 HTML/SVG 渲染效果，防止坐标轴越界、图文重叠等视觉错误。
8. 🛡️ 质控 (Quality Control)：由另一个未参与创作的 Agent 从原始数据重算，进行独立复核，拆解潜在逻辑漏洞。

五大独特优势

快速开始

安装

支持跨 Agent 通用（Claude Code, Cursor, Codex 等）：

npx skills add alchaincyf/huashu-excel

或者手动 Clone 到对应目录：

git clone https://github.com/alchaincyf/huashu-excel ~/.claude/skills/huashu-excel

使用示例

只需使用自然语言指令，huashu-excel 会自动触发相应流程：

• "帮我分析下这份销售表" → 执行完整八步流程。
• "这两个数怎么对不上" → 触发体检 + 对账，查找口径差异。
• "这个数靠谱吗" → 触发对账 + 独立复核。
• "帮我把这份表洗干净" → 触发体检 + 清洗，并输出可审计的 pandas 脚本。

独立脚本使用

即使不使用 Agent，也可单独运行其底层脚本进行数据质检：

python3 scripts/profile_table.py your_file.xlsx      # 表结构体检
python3 scripts/verify_numbers.py your_file.xlsx     # 数字对账（退出码 1 表示有差异）
python3 scripts/verify_visual.py report.html         # 图表渲染自检