前言¶

AI 写代码出错时会抛异常，AI 做数据分析出错时什么都不会发生。

一份标题占了前两行、表头分两级、地区列用合并单元格、中间夹着「华东小计」、金额带千分位的 Excel，用 pd.read_excel() 读进来直接求和，README 里给出的对比结果是：总额误差 +161.0%，均值误差 +117.5%，零报错、零 NaN、零警告。错的三处没有任何一处能被 Python 感知到——合计行被当成一家门店、小计行被当成一家门店、一行粘贴事故造成的完全重复被算了两次。这个数字交付出去时，和正确答案长得一模一样。

huashu-excel 就是为这件事准备的。它先读原始单元格再动 pandas，把表里自带的「合计」行当成免费的校验和，交付前跑一遍 master check，对不上就不把数字交出去。下面介绍它的定位、能力、安装方式和用法。

这是什么¶

huashu-excel 是 alchaincyf 维护的一个数据分析与 Excel 全流程 skill，同时是 DeepSeek Harness（DSH）插件，分类在目录页标为「工作流」。

GitHub 数据（截至 2026-11-06）：stars 456，forks 70，License 为 MIT，主要语言 Python，包版本 1.1.0。仓库说明写的是：体检脏表、清洗、对齐需求、分析、对账、交付，让 AI 算出来的数字经得起追问，跨 agent 通用，依赖仅 openpyxl。

需要先说明的是，它不是一个 Excel 库，也不是一个调教你动手算数的提示词合集。它是一套把「这个数你怎么算的」变成可回答问题的流程，脚本负责验算，agent 负责判断。

核心功能¶

八步流程¶

README 给出的标准作业流程是固定的八步：

1  体检   这张表长什么样 —— 结构、类型、脏点。先看再算
2  清洗   变成规范分析表，每一步可追溯可回放
3  对齐   摸底 → 查外部基准 → 告诉用户 → 问清他要什么 → 定口径
4  分析   扫陷阱，走配方，每条发现都推到「所以呢」
5  对账   行数守恒、总和守恒、与表内合计交叉验证
6  交付   Excel / 图表 / 报告，口径随数字一起交付
7  验图   渲染出来看画错了没有
8  质控   另派一个没参与创作的 agent 从原始数据重算，拆你的台

其中第 3 步「对齐」值得单独拿出来讲。用户开口时往往不知道自己要什么，因为他也没看过这份数据长什么样。「帮我分析一下」是他此刻最诚实的表述，直接追问「你想看哪些维度」只会让他瞎猜。所以澄清被放在已经看懂数据、并且用户也能看懂摸底描述之后：先给一行人话摸底（几行几列、有哪些维度和指标、分布形态、一到两个已经能看到的现象），再问他要回答什么问题、分析拿去做什么决定、有没有从数据里看不出来的背景，然后停下来等回答。

八个脚本各管一段¶

每个步骤基本对应一个脚本，职责和调用时机：

依赖只有 openpyxl（读写 .xlsx 时）。CSV 路径和报告生成连它都不用，纯标准库；不用 pandas、不用绘图库、不用 LibreOffice、不联网，也不依赖任何 agent 平台特性，不需要 subagent、不需要沙盒。README 特别说明这不是为了炫技，而是因为体检要在「还没决定用什么工具处理这张表」的时刻就能跑，所以它自己必须几乎没有前置条件。

三个和常见做法不一样的地方¶

先看原始单元格，再动 pandas。 pd.read_excel() 读进来的那一刻，合并单元格、单元格格式、原始类型就全丢了，现有工具往往在信息已经损毁之后才开始判断。体检脚本先用 openpyxl 读原始格子，逐列报出类型问题，例如把数字存成文本导致 sum() 变成字符串拼接、缺失值写成「—」「无」「N/A」、日期格式混了四种。

把表里的「合计」行当校验和。 大多数工具把汇总行当噪音过滤掉，但那是原表作者用公式算出来的真值。拿清洗后的明细自己求和去对它，对不上就说明至少有一方错了。README 里的例子是在 E 列「1月」与第 12 行「华东小计」对账时一致，F 列「2月」时表内写 6,490,430.00、明细算得 6,490,420.00，差 10.00，脚本直接输出 MASTER CHECK：不通过，在解决之前不允许把这些数字写进任何交付物。这个错是造测试数据的人手填小计时填错的，相对误差 0.00%，肉眼发现不了。这一做法对应 ICAEW《Financial Modelling Code》(2024) 里的 Include a master check。

默认给五数概括，不给均值。 业务数据几乎总是右偏的，均值在偏态分布下描述的不是任何一个真实对象。默认输出 min/Q1/中位数/Q3/max + IQR，也就是 Tukey 的抗差统计，而不是 df.describe() 把 mean/std 放在最前面的那套。

另外 scan_traps.py 管的是另一类对账抓不到的问题：辛普森悖论、幽灵分组、小基数、时间断点、双峰分布、极端集中。数字全算对了，结论照样可以是错的。

图表与报告¶

图表部分继承 Gene Zelazny《用图表说话》的律条，先确定要传达的信息再选形式，并补了两条实证约束。make_chart.py 在类别超过 3 个时会拒绝生成饼图，理由是饼图靠角度和面积编码，在 Cleveland & McGill (1984) 的图形感知精度阶梯上排第 3 和第 4，而条形图的长度编码排第 2。生成时自动执行诚实性检查：柱形图数值轴强制从 0（折线图不强制，因为它编码的是位置和斜率）、坐标轴用整刻度、类别按值排序、单系列去图例、不完整的最后一期画虚线、套用色盲友好色板。

报告部分，HTML 报告是直接写 HTML/CSS，不从模板里挑，也不内置风格。落地要求包括自包含（无 CDN、无外部字体、图表用内联 SVG）、口径声明在前分析边界在后、图表诚实性等。sidebar 里还注明幻灯片和 PPT 不在本 skill 做，需要时转 huashu-design。

安装与启用¶

DSH 桌面端用户在「插件 → 添加插件」里填 GitHub 仓库地址即可。命令行方式：

dsh plugin --profile desktop add github:alchaincyf/huashu-excel

桌面端的 profile 叫 desktop，网页版换成 web。命令行安装之前，桌面端要先打开过一次并且完全退出，装完再打开 DSH，插件才会加载。

卸载：

dsh plugin --profile desktop remove huashu-excel

DSH 桌面端自带 Python 和 pandas、openpyxl，不用另装任何东西。另外它同时是一个跨 agent 通用的 skill，其他 runtime 也可以用通用方式安装：

npx skills add alchaincyf/huashu-excel

装完就可以用自然语言直接说需求，比如「帮我分析下这份销售表」走完整八步，「这两个数怎么对不上」跑体检加对账，「这个数你怎么算出来的」跑对账加口径回溯。

典型用法¶

脱离 agent，脚本本身也能跑。README 给出的命令：

python3 scripts/profile_table.py 你的表.xlsx      # 算数字之前先看清楚
python3 scripts/verify_numbers.py 你的表.xlsx     # 退出码 1 = 有对不上的
python3 scripts/verify_visual.py  报告.html        # 退出码 1 = 图画错了
python3 scripts/verify_docx.py    报告.docx       # 退出码 1 = Word 换台机器就走样

退出码 1 就是有问题的信号，可以直接接进 CI 或者你自己的分析链路里。

也可以完全不装，把 SKILL.md 当成一份数据分析的方法论文档直接读。

适用场景与注意¶

适合的场景比较明确：拿到的 Excel 来源不可靠、表头位置和级数不确定、里面混着小计和合计行、合并单元格不少、之前用脚本算过数但没人敢信的那些活儿。它的价值在于交付前能找到口径差异和脏数据，而不是把图做得更漂亮。

几点需要注意：

1. 插件以当前 DSH 进程的权限运行。安装前建议先检查仓库源码与许可证，本仓库是 MIT，但还是自己过一遍再引入团队工作流。
2. 它验的是「算得对」，不是「结论对」。一份内部对账分毫不差的报告，可以整体错一个财年，只要那一列的列名不是它字面的意思。这一步要人来判。
3. 脚本是眼睛不是大脑。README 里写死了一条判据：如果跑完脚本之后下一步动作和跑之前计划的一模一样，说明没有真的在看那个输出。每跑完一个脚本，先回答「我看到了什么 / 这意味着什么 / 下一步要查什么」再往下走。

结尾¶

huashu-excel 做的事情归结起来是一句话：不替你做分析判断，但保证你交出去的数字能回溯到源单元格，对不上就不交。在智能体能力越来越强、一次性跑出一份报告越来越容易的当下，这道闸门反而是少见的克制。

目录页：https://www.skillhub.cn/plugins/alchaincyf/huashu-excel

GitHub：https://github.com/alchaincyf/huashu-excel