前言¶

跑完 SQL、甚至已經出了圖，最後一步往往還是手工拼 HTML 或 PPT：表格、矩陣、篩選器和說明文字各寫各的，導出格式也不統一。若希望 Agent 按固定結構生成「能交付」的報告，並在真實數據上用統計方法產出洞察，而不是口頭編造結論，就需要在 Skill 層把報告組件和導出流程寫清楚。下面介紹 SkillHub 上的 SQL Report Generator 的定位與用法。

這是什麼¶

SQL Report Generator（slug：sql-report-generator）是一個面向數據分析流水線的 報告層 Skill：把 SQL 查詢結果、已有圖表或 DataFrame 組織成生產級報告，支持多種交互組件與 HTML / JSON / PDF 導出，並提供基於 pandas 的自動洞察模塊（不依賴外部大模型 API）。

在 SkillHub 社區中，該 Skill 歸類爲 data-analysis，下載約 984 次，評分 97207（平臺指標）。當前可通過 SkillHub 安裝包 @indiv-yaoyao/sql-report-generator，版本 1.0.0。任務線索中的官方地址爲：

https://api.skillhub.cn/user_64e5b706/sql-report-generator

（該 API 頁面在抓取時不可用；安裝與文檔以 SkillHub CLI 解析到的 @indiv-yaoyao/sql-report-generator 爲準。）Skill 詳情頁：https://skillhub.cn/skills/sql-report-generator。

它與 sql-master（數據層）、sql-dataviz（可視化層）可串聯，也可在已有數據/圖表時單獨使用。

核心功能¶

以下能力均來自 Skill 自帶的 SKILL.md 與腳本說明。

報告組件與導出¶

• 8 種交互組件：表格、矩陣、切片器、按鈕導航、圖像視覺對象、文本框與形狀、分頁報表、報告生成器（ReportBuilder）。
• 導出格式：HTML（推薦）、JSON（集成與二次渲染）、PDF（需額外安裝 reportlab、pypdf2）。
• 看板模板：dashboard_templates.py 定義 17 個行業、36 個預設模板；templates/ 下 .md 可由 scripts/generate_templates.py 生成或更新。

自動洞察（scripts/ai_insights.py）¶

基於 純統計分析（pandas / numpy / scipy），無需外部 AI API，可從 DataFrame 生成結構化洞察與運營建議，並輸出 Markdown、HTML 或 JSON。文檔列出的分析類型包括：異常檢測（Z-score、IQR、環比突變）、趨勢（線性迴歸）、相關性（Pearson）、TOP N / 帕累托、分佈、季節性、對比分析等。

Skill 明確要求：接入 真實數據 時，洞察與建議須通過上述分析得出，禁止手寫「看起來像分析」的文案；對外表述宜用「洞察分析」「統計分析」等中性用語。

協作模式¶

無 Python 依賴時的降級能力¶

若無法安裝依賴，Skill 仍可提供報告結構建議、場景模板推薦與展示規範；不能生成表格/矩陣/切片器、不能導出 HTML/PDF、不能運行自動洞察或與 sql-master / sql-dataviz 聯動。

安裝與啓用¶

1、安裝 SkillHub CLI（若尚未安裝）¶

按 SkillHub 官方安裝說明檢查或安裝 CLI：

command -v skillhub && skillhub --version

未安裝時可執行（完整安裝，含默認 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

2、將 Skill 裝到當前 Agent 的 skills 目錄¶

安裝時必須用 --dir 指向當前環境會被識別的 skills 目錄，否則默認落在 ./skills/ 可能無法加載。常用路徑示例（摘自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

安裝 SQL Report Generator：

skillhub install sql-report-generator --namespace indiv-yaoyao --dir ~/.cursor/skills/

將 ~/.cursor/skills/ 換成你當前使用的 Agent 路徑即可。社區頁亦提示可參考 https://skillhub.cn/install/skillhub.md 安裝 @indiv-yaoyao/sql-report-generator。

3、安裝 Python 依賴¶

Skill 首次使用前需要 Python 3 與 pip。推薦在 Skill 目錄或項目環境中執行：

pip install -r requirements.txt

requirements.txt 核心依賴爲：pandas>=1.5.0、numpy>=1.21.0、matplotlib>=3.5.0、jinja2>=3.1.0；文檔另建議按需安裝 scipy，PDF 導出需 reportlab、pypdf2。

Skill 文檔還提供一鍵命令（依賴 skillhub_install 工具鏈，若你環境中已配置）：

skillhub_install install_skill sql-report-generator

裝好後在 Cursor 等客戶端中 重新加載或重啓，以便發現新 Skill。

典型用法¶

用 ReportBuilder 生成 HTML 報告¶

這一步演示最小閉環：元數據、標題正文、表格、導出 HTML。

from sql_report_generator.scripts.interactive_components import (
    ReportBuilder, TableChart
)

report = ReportBuilder()
report.set_metadata(
    title='月度業績報告',
    author='數據分析團隊',
    date='2026-03-26'
)

report.add_title('月度業績報告', level=1)
report.add_text('本報告彙總了本月的關鍵業績指標。')

table = TableChart()
table_b64 = table.create({
    'columns': ['訂單ID', '客戶', '金額', '日期'],
    'rows': [
        ['ORD001', '張三', '¥1,000', '2026-03-26'],
        ['ORD002', '李四', '¥2,500', '2026-03-25']
    ],
    'title': '訂單列表'
})
report.add_table('訂單數據', table_b64)

report.export_html('report.html')

對 DataFrame 做自動洞察¶

在已有查詢結果或 CSV 讀入的 DataFrame 上，調用洞察模塊生成可嵌入報告的段落：

from scripts.ai_insights import quick_insights

report = quick_insights(df, date_col="date", value_cols=["sales", "quantity"])
print(report.to_markdown())
print(report.to_html())

交付 HTML/PDF 前，Skill 要求自行檢查：圖表是否渲染、中文與數字是否正常、KPI 與圖表是否一致、是否殘留模板佔位符（如 {s:,.0f}）等。

選用行業看板模板¶

需要按行業快速對齊報告結構時，可走模板 API：

from sql_report_generator.scripts.dashboard_templates import DashboardGenerator

generator = DashboardGenerator()
template = generator.get_template("電商", "ecommerce_overview")
md = generator.generate_dashboard_markdown(template)

更新本地 templates/*.md 時，在 Skill 包內執行：

python scripts/generate_templates.py

適用場景與注意¶

適合誰

• 已用 Agent 做 SQL 或可視化，需要穩定產出 HTML/JSON（及可選 PDF）報告的數據分析、運營、財務等角色。
• 希望報告裏表格、矩陣、切片器與導航組件用法統一，並複用多行業預設模板的團隊。

限制與注意

• 完整能力依賴 Python 環境；無依賴時僅爲文檔級輔助。
• 與 sql-master、sql-dataviz 的串聯示例在 SKILL.md 中給出，相關 Skill 需單獨安裝，本 Skill 不替代查詢與製圖。
• PDF、部分統計能力需額外包裝；性能表（如「5 圖約 500ms」）來自 Skill 自述，實際取決於數據量與運行環境。
• SKILL.md 文末聯繫郵箱與 GitHub 爲佔位示例，不作爲官方支持渠道依據。

結尾¶

SQL Report Generator 把「查詢/圖表之後」的排版、組件、統計洞察和導出收成一套可複用流程，並與 sql-master、sql-dataviz 形成可選的三段式流水線。若要從 SkillHub 獲取包體與更新，可使用上文安裝命令，並訪問 Skill 頁 https://skillhub.cn/skills/sql-report-generator；線索中的 API 地址爲 https://api.skillhub.cn/user_64e5b706/sql-report-generator。