dsh-smart-charts

dsh-smart-charts

DeepSeek Harness 的 Smart Charts skill 插件。

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

功能特性

• 32 种图表类型：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 map lines effect_scatter calendar pictorial_bar theme_river，覆盖趋势、对比、占比、分布、相关、流向、转化、词频、集合交叠、层级结构、地理地图等场景。
• 地理地图（map / lines）：内置中国省级（china.json，含港澳台）与世界国家级（world.json）GeoJSON，全离线渲染；--geo china|world 切换内置底图，--geo-path 加载自备 GeoJSON 渲染城市/区县等任意区域。
• 数据画像 --profile：一条命令返回每列 dtype/基数/缺失率/样本/统计、实体粒度、候选洞察信号、疑似非数据行——用户没说想看什么时，agent 先读画像再自行决定选型。
• 环境自检 --doctor：打印 Python/依赖版本矩阵与资产完整性（JSON），版本漂移时先跑它定位问题。
• 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 / --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 层、非表格数据（图片/音视频）。地图市级/区县级等更细区域需自备 GeoJSON（--geo-path），技能不代为下载。

安装

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#<sha>。

本地 tarball

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

验证

dsh --profile web --dump-config

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

使用

1. 把数据文件放进 workspace 目录，启动 DSH 会话。
2. 对 agent 说「分析 sales.csv 并生成柱状图」，或输入 /smart-charts 直接触发。
3. agent 会按 SKILL.md 流程：意图不明确时先跑 --profile 读数据画像 → 自行选型 → 生成 ECharts HTML 到 workspace 输出目录。
4. 首次运行前，agent 会先安装 Python 依赖（需 Python 3.11+）：

pip install -r requirements.txt
python skills/smart-charts/scripts/cli.py --doctor   # 环境自检

依赖（>= 兼容区间）：pandas numpy openpyxl xlrd。

示例数据

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

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

相关平台 / 生态

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

• 腾讯 SkillHub：https://skillhub.cn/skills（搜索 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