智能图表数据可视化工具

从原始数据到交互式图表的转换难题

在数据分析工作流中，将 CSV、Excel 或 JSON 格式的原始数据转化为可视化图表常常面临几个痛点：需要手动编写代码处理数据清洗、选择合适的图表类型、并生成可在浏览器中交互的文件。这个过程不仅耗时，还容易因格式不规范或图表选型不当而产生错误。对于非技术背景的分析人员，这更是一个门槛。smart-charts 旨在自动化这一流程，通过 CLI 工具直接生成基于 ECharts 的交互式 HTML 图表，让分析师能更专注于数据洞察而非编码细节。

核心能力与工作流程

该技能的核心是提供一套完整的 CLI 工作流，主要步骤如下：

• 数据解析与规范化：使用 data_parser.py 处理输入文件（支持 .csv、.xlsx、.json 等），自动检测编码（如 UTF-8、GBK）和分隔符。解析后列名会被规范化（例如转小写、特殊字符转为 _），确保后续操作一致。
• 图表生成与 transform 代码：通过 cli.py 调用，支持 21 种图表类型（如 line、bar、pie、scatter 等）。当数据格式不匹配目标图表时，可以使用 --transform-code 参数注入 LLM 生成的 Python 代码（在沙箱中执行，仅允许 df、pd、np 变量），进行聚合、重塑或过滤操作。例如，将长数据转换为饼图所需格式：

  result = df[df['metric'] == 'revenue'][['category', 'value']].rename(columns={'category': 'name'})
  

• 多文件批量处理：对于需要生成多个图表的场景，推荐使用 --charts-file 传入 JSON 配置文件，避免 shell 转义问题。工具会自动合并文件（基于列重叠率），并生成包含 data_preview（前 10 行数据）和 plot_stats（完整统计摘要）的输出，便于校验聚合口径。
• 交付解读：生成图表后，必须附上由 LLM 基于 plot_stats 编写的文字解读，并通过 --annotation 参数注入 HTML，确保交付物包含数据洞察。

适用边界与注意点

尽管功能强大，使用时仍需注意以下约束：

• 支持范围：单文件最大 100 MB（推荐 50 MB 以下），支持自动编码检测；不支持嵌套超过一层的 JSON、实时流数据或非表格数据（如图片）。多文件合并要求列重叠率 ≥50%。
• CLI 强制工作流：必须遵循 data_parser.py → cli.py 的流程，不得自写脚本替代。列重命名、聚合等操作必须通过 --transform-code 实现，解析层仅处理表头识别。
• transform 沙箱安全：代码执行在沙箱中，禁止 import、open 或类定义；违规会返回结构化错误和修复建议。原始数据已匹配图表格式时，无需 transform。
• 图表选型与口径：工具默认按数据语义自动选择图表类型（如时间序列用 line），并在交付语中列出假设。聚合前需明确“按数据行 vs 按去重实体”，例如统计课程学时应先用 drop_duplicates，避免口径错误。
• 交付规范：每张图表必须附解读，数字必须基于 plot_stats 或 data_preview，不得夸大事实。网络依赖为零——ECharts JS 内联到 HTML 中，图表完全离线渲染。