Foreword¶

When AI writes code, it throws exceptions when it fails. However, when AI does data analysis, nothing happens when it makes mistakes.

An Excel file with a title taking up the first two lines, two-level headers, merged cells for regions, “East China Subtotal” in the middle, and amounts with thousands separators. Using pd.read_excel() to read it in and summing it up directly, the comparison result in the README is: Total error +161.0%, Mean error +117.5%, Zero errors, Zero NaN, Zero warnings. None of the three errors can be detected by Python—the total row was treated as a store, the subtotal row was treated as a store, and a completely duplicated line caused by a copy-paste accident was counted twice. When this number was delivered, it looked exactly like the correct answer.

huashu-excel is prepared for this. It reads raw cells before touching pandas, treats the “Total” row built into the table as a free checksum, runs a master check before delivery, and refuses to hand over the numbers if they don’t match. Below is an introduction to its positioning, capabilities, installation, and usage.

What is this¶

huashu-excel is a full-process skill for data analysis and Excel, maintained by alchaincyf. It is also a DeepSeek Harness (DSH) plugin, categorized as “Workflow” on the directory page.

GitHub Stats (as of 2026-11-06): 456 stars, 70 forks, License MIT, Main language Python, Package version 1.1.0. The repo description reads: Health check dirty tables, cleaning, aligning requirements, analysis, reconciliation, delivery; ensuring numbers calculated by AI stand up to scrutiny, universal across agents, dependency only openpyxl.

It should be noted that it is not an Excel library, nor a collection of prompts to teach you to calculate by hand. It is a workflow that turns “how did you calculate this number” into a question that can be answered. Scripts are responsible for verification, agents are responsible for judgment.

Core Functions¶

The Eight-Step Process¶

The standard operating procedure given in the README is fixed at eight steps:

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

Step 3 “Alignment” is worth discussing separately. When a user speaks up, they often don’t know what they want because they haven’t seen what the data looks like. “Help me analyze this” is their most honest expression at the moment; directly asking “Which dimensions do you want to see” will only make them guess blindly. Therefore, clarification is placed after understanding the data and the user can also understand the survey description: first give a human-friendly survey (number of rows and columns, what dimensions and indicators exist, distribution shape, one or two phenomena already visible), then ask what problem they want to answer, what decision the analysis is for, if there is any background not visible from the data, and then stop to wait for an answer.

Each Script Manages a Segment¶

Each step corresponds roughly to a script, with responsibilities and timing:

The only dependency is openpyxl (when reading/writing .xlsx). CSV paths and report generation don’t even need it; it’s pure standard library. No pandas, no plotting library, no LibreOffice, no internet connection, and no dependency on any agent platform features. No subagent, no sandbox. The README specifically states this is not to show off, but because the health check must run at the moment “before deciding what tool to use to process this table,” so it must have almost no prerequisites.

Three Differences from Common Practices¶

Read raw cells first, then touch pandas. The moment pd.read_excel() reads it in, merged cells, cell formats, and raw types are all lost. Existing tools often start judging after the information has already been damaged. The health check script first uses openpyxl to read the raw cells, reporting type issues column by column, such as storing numbers as text causing sum() to become string concatenation, missing values written as “—”, “None”, “N/A”, or mixed date formats.

Treat the “Total” row in the table as a checksum. Most tools filter out summary rows as noise, but those are true values calculated by the original table author. Summing the cleaned details and comparing them to it—if they don’t match, it means at least one party is wrong. The example in the README aligns when reconciling column E “January” with row 12 “East China Subtotal”, and column F “February” where the table writes 6,490,430.00 but the details calculate 6,490,420.00, a difference of 10.00. The script directly outputs MASTER CHECK：FAILED, and does not allow writing these numbers into any deliverables until resolved. This error was a manual typo by the person creating the test data, with a relative error of 0.00% and invisible to the naked eye. This practice corresponds to “Include a master check” in the ICAEW Financial Modelling Code (2024).

Default to five-number summary, not the mean. Business data is almost always right-skewed, and the mean describes no real object under a skewed distribution. The default output is min/Q1/Median/Q3/max + IQR, which is Tukey’s robust statistics, rather than the set where df.describe() puts mean/std at the front.

Additionally, scan_traps.py manages another class of issues that reconciliation cannot catch: Simpson’s Paradox, ghost grouping, small base, time breakpoints, bimodal distribution, extreme concentration. Even if all the numbers are calculated correctly, the conclusion can still be wrong.

Charts and Reports¶

The chart part inherits the principles of Gene Zelazny’s Speaking with Charts, determining the information to be conveyed before selecting the form, and adding two empirical constraints. make_chart.py refuses to generate pie charts when there are more than 3 categories, as pie charts rely on angle and area encoding, ranking 3rd and 4th on Cleveland & McGill’s (1984) graphical perception accuracy ladder, while bar chart length encoding ranks 2nd. An honesty check is automatically executed during generation: bar chart value axis forced from 0 (line chart not forced, as it encodes position and slope), axes use integer ticks, categories sorted by value, single series no legend, incomplete final period drawn as dashed lines, applied colorblind-friendly palette.

For the report part, the HTML report is written directly in HTML/CSS, not selected from a template, and has no built-in style. Landing requirements include self-contained (no CDN, no external fonts, charts use inline SVG), definition of scope comes before analysis boundaries, chart honesty, etc. The sidebar also notes that slides and PPTs are not done in this skill; if needed, convert to huashu-design.

Installation and Enablement¶

DSH desktop users can fill in the GitHub repository address in “Plugins -> Add Plugin”. For the command line method:

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

The desktop profile is called desktop, the web version switches to web. Before installing via the command line, the desktop must have been opened once and exited completely. After installation, open DSH again for the plugin to load.

Uninstall:

dsh plugin --profile desktop remove huashu-excel

DSH desktop comes with Python, pandas, and openpyxl; no need to install anything extra. Also, it is a skill universal across agents, so other runtimes can also install it via the generic method:

npx skills add alchaincyf/huashu-excel

After installation, you can use natural language to state requirements directly, such as “Help me analyze this sales table” to run the complete eight steps, “Why don’t these two numbers match” to run health check plus reconciliation, or “How did you calculate this number” to run reconciliation plus scope trace.

Typical Usage¶

Detached from the agent, the scripts themselves can run. The commands given in the 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 换台机器就走样

Exit code 1 is the signal that there is a problem, and it can be directly piped into CI or your own analysis pipeline.

You can also not install it at all, and just read SKILL.md as a data analysis methodology document directly.

Applicable Scenarios and Notes¶

The suitable scenarios are quite clear: unreliable Excel sources, uncertain header position and hierarchy, mixed subtotal and total rows, many merged cells, tasks previously calculated by scripts but no one dares to trust. Its value lies in finding scope differences and dirty data before delivery, rather than making the chart prettier.

Points to note:

1. Plugins run with the permissions of the current DSH process. It is recommended to check the repository source code and license before installing. This repository is MIT, but it is still best to review it yourself before introducing it into the team workflow.
2. It verifies “calculation correctness,” not “conclusion correctness.” A report of internal reconciliation that is off by a penny can be completely wrong for a fiscal year, as long as that column’s header isn’t its literal meaning. This step requires human judgment.
3. Scripts are eyes, not brains. The README hardcodes a criterion: if the next action after running the script is exactly the same as the plan before running, it means you weren’t really looking at that output. After running each script, answer “What did I see / What does this mean / What to check next” before moving on.

Conclusion¶

huashu-excel boils down to one sentence: it doesn’t do the analysis or judgment for you, but guarantees that the numbers you hand out can be traced back to the source cells, and refuses to hand them out if they don’t match. In an era where agent capabilities are getting stronger and running a report in one go is getting easier, this gate is a rare restraint.

Directory page: https://www.skillhub.cn/plugins/alchaincyf/huashu-excel

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