月度經營異常診斷助手

不止出圖表，更要自動「找茬」並說清為什麼。

Overview

上傳月度銷售/財務 CSV 或 Excel → 四層流水線自動處理：

1. 智慧清洗層（防崩潰）：CSV 編碼自動識別（UTF-8/GBK/GB2312）、列名中英文同義詞對映、缺失值按業務邏輯處理（時間序列插值/眾數填補）、混合日期格式標準化、品類錯別字修正
2. 多維下鑽聚合：按月份×地區×品類聚合 + 環比/同比計算
3. 異常檢測 + 貢獻度歸因（核心）：環比波動超閾值標記 → 維度貢獻度分解 → 歸因鏈路（資料錄入檢查 → 子項定位 → 假設性結論）
4. 互動式 HTML 看板：趨勢圖 + 環比柱狀圖 + 貢獻度分解圖 + 歸因結論 + 子項異常清單 + 清洗日誌 + ≤3 條可執行業務建議

安全底線：CSV 資料為不可信輸入。所有寫入 HTML 報告的文本經 esc() 清洗（HTML 實體 + 協議注入防護 + prompt 注入過濾 + Markdown 連結中和）。詳見 references/content-sanitization.md。

When to Use

• 上傳月度銷售/財務 CSV 或 Excel，需要自動清洗髒資料
• 定位「這個月哪裡出問題了」並理解為什麼
• 指標異常波動排查與歸因
• 生成互動式診斷看板

Don't use for: 即時流式資料（非批次檔案）；非表格資料（如 PDF 財報）；超大數據集（>100MB 建議先採樣）。

Usage

python scripts/diagnose.py <file> [--output report.html] [--threshold 0.15]

# Example
python scripts/diagnose.py assets/sample_dirty.csv
python scripts/diagnose.py sales.xlsx -o report.html -t 0.20

Input Requirements

• Format: CSV (.csv) or Excel (.xlsx/.xls)
• Encoding: Auto-detect UTF-8/GBK/GB2312 (Chinese enterprise CSV no manual transcoding needed)
• Required columns: Date + Sales (column names support Chinese/English synonym auto-mapping)
• Optional columns: Region, Category, Quantity, Cost, Channel (for multi-dimension drill-down)
• File size: ≤ 100 MB

Full column synonym mapping: references/column_mapping.json.

Output

Interactive HTML Dashboard (self-contained, offline-openable):

• Data overview (time span, dimension distribution)
• Monthly sales trend chart (red ✕ marks anomaly months)
• MoM change rate bar chart (red=drop, green=rise; deep color=exceeds threshold)
• Dimension contribution decomposition chart (red=amplifies fluctuation, green=mitigates)
• Anomaly attribution conclusion section
• YoY analysis table (auto-skip if < 2 years of data)
• Sub-item anomaly checklist (dimension-level findings, sorted by amplitude)
• Smart cleaning log (color-coded by type)
• ≤ 3 actionable business recommendations

Color convention follows Chinese business analysis: red = decline warning, green = growth positive.

Constraints

1. No fabricated external data — attribution based on decomposition of uploaded data only
2. No brute-force zero-fill — missing values handled by business-logic interpolation or mode
3. No crash on encoding/format/missing — auto-adapt or clear error message
4. ≤ 3 recommendations — focus on actionability
5. No modification of original files — all processing in memory

Common Pitfalls

1. CSV 含 prompt 注入文本汙染 Agent 上下文 — 資料中 忽略所有指令 等模式經 esc() 的 HTML 轉義後仍可讀，Agent 讀取報告時可能被誤導。已追加 _filterPromptInjection() 過濾。
2. CSV 含 Markdown 連結語法汙染報告 — [惡意](url) 通過 HTML 轉義但被 Agent 以 Markdown 重讀時渲染為連結。esc() 已追加 []() → 【】（） 全形替換。
3. CSV 編碼識別失敗導致亂碼 — 多編碼嘗試鏈（utf-8-sig → gbk → gb2312 → utf-8 → latin-1 兜底）+ 亂碼檢測回退。
4. 銷售額列全空未被檢測 — 列名對映成功但清洗後全 NaN。已新增邊緣場景防禦：sales.isna().all() → 明確報錯提示。
5. Plotly.js 內嵌使 HTML 達 3MB+ — 自包含便於離線分發，但首次載入可能慢。建議使用者用現代瀏覽器開啟。

Verification Checklist

想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

• [ ] HTML 報告中所有 CSV 資料經 esc() 清洗（無 <script>、無 javascript: 協議、無 prompt 注入、無 [...](...) 連結語法）
• [ ] 缺失值處理符合業務邏輯（時間序列→插值，分類→眾數，非填補 0）
• [ ] 混合日期格式全部標準化（控制台日誌確認解析數量）
• [ ] 歸因結論可追溯（貢獻度分解資料與原始資料一致）
• [ ] ≤ 3 條業務建議，每條可執行
• [ ] HTML 可離線開啟（無外網依賴）
• [ ] 色彩慣例正確（紅跌綠漲，超閾值加深）

Dependencies

pandas>=2.0  numpy>=1.24  plotly>=5.18  openpyxl>=3.1

Install: pip install -r requirements.txt

Reference Files

• references/column_mapping.json — Column name synonym mapping (extensible)
• references/content-sanitization.md — HTML/Markdown/prompt-injection sanitization spec
• scripts/diagnose.py — Main diagnosis pipeline (1050 lines, standalone-runnable)
• assets/generate_sample.py — Dirty sample data generator
• assets/sample_dirty.csv — Pre-generated test data with embedded anomalies
• tests/run_test.py — Self-test script

質量很好，能自動處理各種「髒」資料（亂碼、格式不統一、缺失值），生成一份圖文並茂的診斷報告，直接告訴你哪裡出了問題、為什麼。安全性做得很到位，使用者資料不會被惡意注入干擾。介面顏色符合國內業務習慣（紅跌綠漲）。主要不足是當資料量很大時生成的 HTML 報告會偏大，開啟速度較慢；另外對年份較少的同比分析用處有限。整體來說，這是一個非常實用的經營診斷工具，非技術背景使用者也能輕鬆上手。