hherosoul/dsh-smart-charts

dsh-smart-charts

DeepSeek Harness 的 Smart Charts skill 插件。

把数据文件（CSV / Excel / JSON）一键转换为交互式 ECharts HTML：自动识别数据形态、推荐并生成图表，支持多文件合并、LLM 数据转换代码（沙箱安全执行）、完全离线渲染。

功能特性

- 26 种图表类型：line bar area pie scatter radar heatmap treemap graph boxplot waterfall gauge sankey funnel sunburst wordcloud histogram stacked_bar bubble pareto combo venn mindmap orgchart liquid spreadsheet，覆盖趋势、对比、占比、分布、相关、流向、转化、词频、集合交叠、层级结构等场景。
- 3 套主题预设：default / classic / dark，按交付场景一键切换视觉风格。
- 多格式解析：CSV（逗号）/ TSV（制表）/ TXT（自动探测分隔符 ,/\t/;/|）、Excel（.xlsx/.xls）、JSON（数组 + 单层嵌套）；自动检测 UTF-8 / GBK / GB2312 编码。
- 多文件自动合并：最多约 10 个文件；列完全相同 → 纵向拼接（注入 source_file 来源列），≥50% 列重叠 → 横向关联，无共同结构 → 明确报错建议分开分析。
- LLM 数据转换：--transform-code 用 pandas 代码完成列重命名 / 重塑 / 聚合等清洗，由模型按数据语义生成。
- 三层安全沙箱：transform 代码经过「黑名单 + AST 白名单 + 安全 builtins」三重校验；违规返回带 suggestion 的结构化错误，模型可机械修正重试，无需用户介入。
- 多图批量：--charts-file 用 JSON 声明多张图（每图可带独立 transform），一次生成整组图表。
- 统计摘要 + 解读注入：成功时输出 plot_stats（绘图数据完整统计摘要）；--dry-run 只算统计不渲染，--annotation 把 LLM 写的文字解读注入 HTML「图表说明」区块。
- 完全离线：ECharts JS 打包在 assets/ 并内联进每个 HTML，无 CDN、无外部依赖。
- 交互式输出：悬停查数、dataZoom 缩放、超阈值自动横向滚动、标题双击内联编辑、图表可保存为图片。
- 结构化错误：SmartChartsError 统一输出 JSON（code / code_name / suggestion），失败可被 agent 稳定解析并重试。

支持的数据格式

| 格式 | 说明 |
|------|------|
| .csv | 逗号分隔 |
| .tsv | 制表符分隔 |
| .txt | 自动探测分隔符 |
| .xlsx / .xls | 首个非空 sheet（可用 --sheet 指定） |
| .json | 数组格式 + 单层嵌套对象 |

约束：单文件 ≤ 100 MB（推荐 ≤ 50 MB）；不支持数据库（先导出 CSV）、实时流、地理地图、嵌套 JSON > 1 层、非表格数据（图片/音视频）。

安装

GitHub 直装（纯 TS 源码）

dsh plugin --profile web add github:hherosoul/dsh-smart-charts

首次安装会因 pnpm≥10 拒绝运行 git 依赖的 prepare 构建脚本而失败。按 pnpm 打印的提示，把精确包名写进 profile 的 pnpm-workspace.yaml（默认 ~/.dsh/profiles/web/pnpm-workspace.yaml）：

allowBuilds:
dsh-smart-charts: true

然后重新安装：

dsh plugin --profile web add github:hherosoul/dsh-smart-charts

放行 allowBuilds 等于授权该包在安装阶段执行代码，请只对你信任的源码放行，并建议固定 commit：github:hherosoul/dsh-smart-charts#。

本地 tarball

dsh plugin --profile web add ./dsh-smart-charts-8.0.1.tgz

验证

dsh --profile web --dump-config

看到 # == dsh-smart-charts 一层即加载成功。

使用

1. 把数据文件放进 workspace 目录，启动 DSH 会话。
2. 对 agent 说「分析 sales.csv 并生成柱状图」，或输入 /smart-charts 直接触发。
3. agent 会按 SKILL.md 流程：解析数据 → 推荐图表类型 → 生成 ECharts HTML 到 workspace 的 output/。
4. 首次运行前，agent 会先安装 Python 依赖（需 Python 3.11+）：

pip install -r requirements.txt

依赖（== 精确锁定）：pandas numpy openpyxl xlrd。

示例数据

仓库自带示例数据，可快速体验：

- examples/sales_data.csv — 2026 年第一季度销售数据（18 行 × 5 列）
- examples/README.md — 使用说明与示例提示词

相关平台 / 生态

本 skill 同时发布在腾讯 SkillHub（WorkBuddy 生态）：

- 腾讯 SkillHub：（搜索 smart-charts）
- 截至 2026-08-19：SkillHub 累计下载 6.8 万次，在数据分析分类中排名第一
- 在 SkillHub 上的使用方式：上传 CSV / Excel / JSON 数据文件 → 生成交互式图表 HTML，可保存为图片。

目录结构

dsh/
├── package.json         # dsh.bundle.patch 声明
├── cordis.patch.yml     # insert 插件行
├── tsconfig.json
├── src/index.ts         # 唯一入口：mount dsh-skill-filesystem
└── skills/smart-charts/ # skill 本体（SKILL.md + scripts + references + assets）
├── SKILL.md         # skill 指令（frontmatter + 工作流 + 图表类型表）
├── references/      # CLI flags 语义、错误码表、FAQ
├── scripts/         # Python 实现（解析/转换/渲染/沙箱）
└── assets/          # 内联 ECharts JS

License

MIT