前言¶

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