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 或標準程式庫，確保在受限環境中也能執行。