name: business-anomaly-diagnosis slug: business-anomaly-diagnosis displayName: 月度经营异常诊断助手 description: Use when analyzing monthly sales/financial CSV or Excel files. Auto-cleans dirty data (encoding detection, column mapping, missing-value interpolation, date standardization, typo correction) → multi-dimension drill-down with MoM/YoY → anomaly detection with contribution decomposition → interactive HTML dashboard with ≤3 actionable recommendations. For business operators doing monthly reviews or anomaly investigation. version: 1.0.0 author: Hermes Agent Community license: MIT metadata: hermes: tags: [business, finance, anomaly-detection, data-cleaning, dashboard, diagnosis, sales-analysis] related_skills: []

月度经营异常诊断助手

不止出图表，更要自动「找茬」并说清为什么。

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

• [ ] 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 报告会偏大，打开速度较慢；另外对年份较少的同比分析用处有限。整体来说，这是一个非常实用的经营诊断工具，非技术背景用户也能轻松上手。