前言¶
數據分析裏常見的一條路徑是：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
