前言¶
数据分析里常见的一条路径是：SQL 已经跑出结果，下一步要出图给同事或写进报告。手写 matplotlib、再调尺寸和配色，往往比写查询还费时间；若还要和 sql-master、报告类 Skill 串起来，数据格式和输出方式还得自己对齐。
下面介绍 SkillHub 上的 SQL Dataviz（slug：sql-dataviz）。它面向「已有表状/查询结果 → 图表」这一步，用统一的 ChartFactory 生成 base64 PNG，便于嵌进 HTML、Markdown 或邮件；需要交互时可用 Plotly 输出自包含 HTML。
这是什么¶
SQL Dataviz 是 SkillHub 社区中的 data-analysis 类 Agent Skill，将 SQL 或等价表状数据转为生产级可视化。SkillHub 检索摘要写明：集成 Power BI 原生的 50 种视觉对象，覆盖对比、趋势、分布、占比、地理、指标监控、AI 智能分析、统计分析等场景；图表以 base64 编码的 PNG 输出。
社区侧可见数据（截至撰稿时由任务线索提供）：评分约 97114，下载约 1003 次。包标识为 @indiv-yaoyao/sql-dataviz，当前检索版本 1.0.0。
官方入口（页面侧 canonical 为 SkillHub 技能页；任务给出的 API 路径如下，直接 GET 可能返回 405，安装与元数据以 SkillHub CLI 为准）：
- https://skillhub.cn/skills/user_64e5b706/sql-dataviz
- https://api.skillhub.cn/user_64e5b706/sql-dataviz
它与 sql-master（取数/SQL）、sql-report-generator（HTML 报告）在同一流水线中协作，也可在已有 DataFrame/字典数据时单独使用。
核心功能¶
依据已安装的 SKILL.md 与 SkillHub 简介，可核实的能力包括：
-
静态图表（PNG / base64）
通过sql_dataviz.charts.ChartFactory调用各类create_*方法（如簇状柱形图、折线图、饼图、漏斗图、地图与 KPI 等），输出 base64，可写入<img src="data:image/png;base64,...">或解码为.png文件。 -
主题与样式
工厂级set_theme()支持如powerbi、alibaba、tencent、bytedance等；也可用ChartConfig设置宽高、DPI、标题与图例等。 -
交互式 HTML（Plotly）
scripts/interactive_charts.py提供InteractiveChartFactory与DashboardBuilder，文档列出 12 种交互图（折线、柱形、饼图、散点、热力、漏斗、面积、树状图、仪表盘、组合图、表格、KPI 卡片等），主题含powerbi/dark/seaborn/ggplot2。 -
与上下游 Skill 协作
文档描述sql-master → sql-dataviz → sql-report-generator流水线；亦提供UnifiedPipeline链式示例（查询 →interactive_chart→ 报告）。 -
无 Python 依赖时的受限模式
若无法安装依赖，Skill 说明仍可提供图表选型建议、数据格式说明、配色与设计原则；不能生成 PNG/HTML 或与 sql-master、sql-report-generator 联动。
安装与启用¶
1. 安装 Skill 包¶
在已配置 SkillHub CLI 的环境中，从社区安装（与下载 API 使用的 namespace 一致）：
skillhub install sql-dataviz --namespace indiv-yaoyao
安装成功后，Agent 按通用 SKILL.md 规范读取技能说明；Cursor、Claude Code、Codex CLI 等若已接入同一套本地 Skill 目录，启用方式取决于各自对 SkillHub 安装路径的配置，官方 references/INSTALLATION.md 未单独区分各客户端，此处不展开未文档化的路径。
2. 安装 Python 依赖（必做，否则无法出图）¶
Skill 声明首次使用前必须装依赖。推荐一键命令：
skillhub_install install_skill sql-dataviz
手动方式（在 Skill 包目录下）：
pip install -r requirements.txt
requirements.txt 中列出的核心包包括：matplotlib、seaborn、pandas、numpy、pillow、plotly、networkx、wordcloud、scipy 等（版本下限见文件内约束）。文档要求 Python 3.8+、pip 20.0+。
可选能力（地理、树状图等）在 references/INSTALLATION.md 中另有 geopandas、squarify 等说明，按场景追加安装即可。
典型用法¶
基础：从表状数据生成簇状柱形图¶
下列片段来自 Skill 快速开始，展示最小闭环：工厂 → 主题 → 数据字典 → base64 PNG。
from sql_dataviz.charts import ChartFactory
factory = ChartFactory()
factory.set_theme('powerbi')
data = {
'categories': ['Q1', 'Q2', 'Q3', 'Q4'],
'series': [
{'name': '销售额', 'data': [100, 150, 120, 200]},
{'name': '成本', 'data': [60, 80, 70, 100]}
]
}
chart_b64 = factory.create_clustered_column(data)
html = f'<img src="data:image/png;base64,{chart_b64}" />'
与 sql-master 串联¶
先执行 SQL，再把行结果映射为 categories / series，再调用 ChartFactory（见 Skill 文档中的协作示例）。
交互式 HTML¶
from scripts.interactive_charts import InteractiveChartFactory
factory = InteractiveChartFactory(theme="powerbi")
html = factory.create_line(data)
factory.save_html(html, "chart.html")
在对话场景下，可向 Agent 说明「已有 SQL 结果 / CSV，请按 SQL Dataviz 选型并输出 base64 图或 Plotly HTML」，由 Skill 约束选型与数据形状。
适用场景与注意¶
适合谁
- 已用或计划用 sql-master 取数，需要稳定、可嵌入的图表输出。
- 要把图放进 sql-report-generator 或其它 HTML/Markdown 报告。
- 希望在 Agent 对话里用统一工厂 API，而不是每次从零写绘图代码。
限制与注意
- 依赖未安装时只能使用文档中的「降级」指导，不能真正渲染图表。
- 文档内对图表种类数量在不同章节有差异（如能力矩阵、changelog 与 requirements 注释）；以你本机安装的
SKILL.md与方法名为准。 - Skill 文末部分支持链接为占位域名（
example.com），不作为官方支持渠道。 - 实时刷新需自行定时查库并重绘；Skill 给出循环示例，但不替代专门的实时看板基础设施。
结尾¶
SQL Dataviz 把「SQL/表状结果 → 可交付图表」封装成 Agent Skill：静态图走 base64 PNG，交互场景走 Plotly HTML，并可与 sql-master、sql-report-generator 组成完整分析链。若要从社区拉取并配置环境，可从 SkillHub 页面或下列地址进入，并用 skillhub install sql-dataviz --namespace indiv-yaoyao 与 skillhub_install install_skill sql-dataviz 完成技能与依赖安装。
- https://skillhub.cn/skills/user_64e5b706/sql-dataviz
- https://api.skillhub.cn/user_64e5b706/sql-dataviz
