sql-report-generator - 生产级报告生成 Skill
⚠️ 使用前必读
本 Skill 需要 Python 依赖。首次使用前必须安装依赖：
skillhub_install install_skill sql-report-generator
工具会自动检测 Python3 环境、pip 可用性，并安装所有依赖。
依赖安装方式
| 方式 | 命令 | 适用场景 |
|---|
| 自动安装（推荐） | skillhub_install install_skill sql-report-generator | 一键安装，自动处理 |
| 手动安装 | pip install -r requirements.txt | 熟悉 Python 环境的用户 |
无依赖使用（受限模式）
如果无法安装依赖，本 Skill 提供以下降级能力：
✅ 可用功能：
- 报告结构设计建议
- 报告模板推荐（基于业务场景）
- 数据展示规范指导
- 报告写作建议
❌ 不可用功能：
- 表格/矩阵/切片器生成
- HTML/PDF 报告导出
- AI 自动洞察生成
- 与 sql-master / sql-dataviz 联动
⚠️ 重要规则（必须遵守）
规则一：洞察与建议必须基于数据分析得出
🚨 严禁在真实数据场景下手动编写洞察和建议
当接入真实数据时，深度洞察和运营建议必须通过数据分析得出结论：
# ✅ 正确做法：使用自动分析
from sql_report_generator.scripts.ai_insights import quick_insights
# 分析数据并生成洞察
report = quick_insights(df, date_col="date", value_cols=["sales"])
insights = report.to_markdown() # 统计分析得出的洞察
recommendations = report.get_recommendations() # 统计分析得出的建议
# ❌ 错误做法：手动硬编码
# insights = "GMV 同比增长 15%，转化率提升..." # 禁止！
注意：
- 输出时不要使用"AI洞察"、"AI分析"等词汇
- 应使用"洞察分析"、"统计分析"、"数据分析"等中性表述
可接受的场景：
规则二：输出文件前必须仔细检查
🚨 每次生成看板文件后，必须先自行检查，确认无错误后再交付
生成 HTML/PDF 文件后，在输出前检查清单：
| 检查项 | 说明 |
|---|
| ✅ 图表是否正确渲染 | 无空白、无报错、无乱码 |
| ✅ 文字是否正常显示 | 中文、数字、符号正确，无 {s:,.0f} 等占位符 |
| ✅ 数据是否一致 | KPI、图表、表格数据匹配 |
| ✅ 交互是否正常 | hover、点击等功能 |
| ✅ 无工具栏/Logo | displayModeBar: false, displaylogo: false |
| ✅ 洞察与建议内容 | 无乱码、无占位符、内容完整 |
常见错误及修复方法：
| 错误类型 | 原因 | 修复 |
|---|
{s:,.0f} | f-string 嵌套错误 | 使用 str() 或预先格式化 |
\u00a5{...} | Unicode 转义错误 | 使用 \u00a5 或 ¥ |
{{}} 乱码 | 双大括号转义问题 | 确保 {{ 在 f-string 外 |
🔗 Skill 协作关系
本 Skill 与 sql-master、sql-dataviz 组成完整的数据分析流水线：
┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐
│ sql-master │ ──► │ sql-dataviz │ ──► │ sql-report-generator │
│ (数据层) │ │ (可视化层) │ │ (报告层) │
└─────────────┘ └──────────────┘ └────────────────────────┘
│ │ │
▼ ▼ ▼
SQL 查询 图表生成 HTML 报告
数据获取 PNG/HTML AI 洞察
格式转换 Dashboard 数据表格
协作模式
| 模式 | 组合 | 适用场景 |
|---|
| 单独使用 | sql-report-generator | 已有图表/数据，仅需组织报告 |
| 可视化报告 | sql-dataviz + sql-report-generator | 图表 → 报告（无 SQL） |
| 数据报告 | sql-master + sql-report-generator | SQL 查询 → 报告（跳过可视化） |
| 完整流程 | sql-master + sql-dataviz + sql-report-generator | 完整数据分析报告 |
🥇 最优使用方式：三 Skill 串联
from scripts.unified_pipeline import UnifiedPipeline
result = (
UnifiedPipeline("销售分析")
.from_file("sales.csv") # sql-master: 数据获取
.query("SELECT region, SUM(sales) as total FROM data GROUP BY region")
.interactive_chart("bar", x_col="region", y_col="total") # sql-dataviz: 可视化
.insights(value_cols=["total"]) # AI 洞察
.report(title="销售报告", output="report.html") # sql-report-generator: 报告
)
决策指南
你需要什么？
├─ 仅报告组织 → sql-report-generator 单独使用
├─ 图表 + 报告（无 SQL）→ sql-dataviz + sql-report-generator
├─ SQL + 报告（跳过可视化）→ sql-master + sql-report-generator
└─ 完整分析报告 → sql-master + sql-dataviz + sql-report-generator ✅ 推荐
新增功能：AI 自动洞察生成模块
scripts/ai_insights.py
纯统计分析（无需外部 AI API），自动从 DataFrame 生成结构化洞察和建议：
from scripts.ai_insights import quick_insights, InsightGenerator
# 一键生成洞察
report = quick_insights(df, date_col="date", value_cols=["sales", "quantity"])
print(report.to_markdown()) # Markdown 格式
print(report.to_html()) # HTML 格式（可嵌入报告）
print(report.to_dict()) # JSON 格式
# 自定义分析
gen = InsightGenerator(df, date_col="date", value_cols=["sales"])
report = gen.generate_all()
# 包含：异常检测 / 趋势 / 相关性 / TOP N / 分布 / 季节性 / 对比
# 自动生成运营建议
7 种洞察类型：异常检测（Z-score + IQR + 环比突变）、趋势检测（线性回归）、
相关性检测（Pearson）、TOP N 分析（帕累托 80/20）、分布检测（偏度/峰度）、
季节性检测、对比分析（分组差异）
3 种输出格式：Markdown / HTML / JSON
安装依赖
pip install -r requirements.txt
或手动安装：
pip install pandas numpy matplotlib jinja2 scipy
概述
将 SQL 查询结果和可视化图表组织成生产级报告。支持表格、矩阵、切片器、交互导航、分页报表等 8 种交互组件，可导出为 HTML、PDF、JSON 等多种格式。
与 sql-master 和 sql-dataviz 无缝协作，形成完整的数据分析流程。
核心能力
1️⃣ 表格与矩阵（2种）
| 组件 | 场景 | 特性 |
|---|
| 表格 | 明细数据展示 | 支持排序、筛选、条件格式 |
| 矩阵 | 跨维度分析 | 支持多级钻取、热力图 |
2️⃣ 交互与筛选（3种）
| 组件 | 场景 | 特性 |
|---|
| 切片器 | 多维度筛选 | 按钮/列表/日期范围样式 |
| 按钮导航 | 报表页面跳转 | 支持书签、URL 跳转 |
| 图像视觉对象 | 品牌 logo、产品图片 | 静态/动态图片嵌入 |
3️⃣ 报告组织（3种）
| 组件 | 场景 | 特性 |
|---|
| 文本框与形状 | 报表标题、说明描述 | 支持动态绑定数据 |
| 分页报表 | 像素级格式化 | 打印-ready、多页面 |
| 报告生成器 | 自动组织内容 | 支持 HTML/PDF/JSON 导出 |
快速开始
基础用法
from sql_report_generator.scripts.interactive_components import (
ReportBuilder, TableChart, MatrixChart, SlicerComponent
)
# 1. 创建报告
report = ReportBuilder()
report.set_metadata(
title='月度业绩报告',
author='数据分析团队',
date='2026-03-26'
)
# 2. 添加内容
report.add_title('月度业绩报告', level=1)
report.add_text('本报告汇总了本月的关键业绩指标。')
# 3. 添加表格
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)
# 4. 导出报告
report.export_html('report.html')
与 sql-dataviz 协作
from sql_dataviz.charts import ChartFactory
from sql_report_generator.scripts.interactive_components import ReportBuilder
# 1. 生成图表
factory = ChartFactory()
factory.set_theme('powerbi')
chart1 = factory.create_line({
'categories': ['Q1', 'Q2', 'Q3', 'Q4'],
'series': [{'name': '销售额', 'data': [100, 150, 120, 200]}]
})
chart2 = factory.create_pie({
'labels': ['北京', '上海', '广州'],
'values': [35, 30, 35]
})
# 2. 组织成报告
report = ReportBuilder()
report.set_metadata(title='季度分析报告')
report.add_title('销售趋势', level=2)
report.add_chart('销售额趋势', chart1, '本季度销售额稳步增长')
report.add_chart('地区占比', chart2, '北京和广州贡献最大')
# 3. 导出
report.export_html('analysis.html')
完整流程：sql-master → sql-dataviz → sql-report-generator
from sql_master import SQLMaster
from sql_dataviz.charts import ChartFactory
from sql_report_generator.scripts.interactive_components import ReportBuilder
# 1. 查询数据
sql = SQLMaster()
sales_data = sql.execute_query("""
SELECT quarter, region, SUM(sales) as total
FROM orders
GROUP BY quarter, region
""")
# 2. 生成可视化
factory = ChartFactory()
factory.set_theme('powerbi')
# 按季度对比
chart = factory.create_clustered_column({
'categories': ['Q1', 'Q2', 'Q3', 'Q4'],
'series': [
{'name': '北京', 'data': [100, 150, 120, 200]},
{'name': '上海', 'data': [80, 120, 100, 180]},
{'name': '广州', 'data': [60, 90, 80, 140]}
]
})
# 3. 组织报告
report = ReportBuilder()
report.set_metadata(
title='年度销售报告',
author='销售部',
date='2026-03-26'
)
report.add_title('年度销售报告', level=1)
report.add_text('本报告总结了全年的销售业绩和地区分析。')
report.add_chart('季度销售对比', chart)
# 4. 导出
report.export_html('annual_sales.html')
文件结构
sql-report-generator/
├── SKILL.md # 本文件
├── scripts/
│ ├── interactive_components.py # 表格、矩阵、切片器、导航、报告生成
│ ├── generate_report.py # 报告生成主程序
│ ├── dashboard_templates.py # 看板模板库（17个行业，36个模板）
│ ├── generate_templates.py # 模板生成脚本（生成 .md 预设模板）
│ ├── ai_insights.py # AI 洞察生成
│ ├── dashboard_tooltips.py # 看板提示配置
│ └── demo.py # 完整演示
├── templates/
│ ├── executive-summary.md # 执行摘要模板
│ ├── monthly-report.md # 月报模板
│ ├── sales-dashboard.md # 销售仪表盘模板
│ └── ...（90+ 预设模板，自动从 dashboard_templates.py 生成）
└── references/
├── chart-guidelines.md # 图表选型指南
├── insight-patterns.md # 洞察模式库
└── templates-index.md # 模板索引
预设模板说明
templates/ 目录下的 .md 预设模板文件由 scripts/generate_templates.py 自动生成，源自 dashboard_templates.py 中的模板定义。
生成/更新预设模板：
# 生成所有预设模板
python scripts/generate_templates.py
# 预览将要执行的操作（不生成文件）
python scripts/generate_templates.py --dry-run
# 仅生成指定行业的模板
python scripts/generate_templates.py --industry 医疗
# 仅生成指定模板
python scripts/generate_templates.py --template-id ecommerce_overview
使用预设模板：
from sql_report_generator.scripts.dashboard_templates import DashboardGenerator
# 创建生成器
generator = DashboardGenerator()
# 获取预设模板
template = generator.get_template("电商", "ecommerce_overview")
# 列出所有可用模板
all_templates = generator.list_all_templates()
for industry, templates in all_templates.items():
print(f"{industry}: {templates}")
# 生成模板 Markdown 文档
md = generator.generate_dashboard_markdown(template)
print(md)
支持的行业和模板数量：
| 行业 | 模板数量 |
|---|
| 电商 | 3 |
| 互联网/APP/游戏 | 3 |
| 金融 | 3 |
| 制造 | 2 |
| 零售 | 2 |
| HR | 2 |
| 财务 | 2 |
| 文娱 | 5 |
| 医疗健康 | 2 |
| 教育 | 2 |
| 餐饮连锁 | 2 |
| 物流供应链 | 1 |
| 能源 | 2 |
| 政务 | 2 |
| 汽车 | 1 |
| 房地产 | 1 |
| 客服运营 | 1 |
| 总计 | 17个行业，36个模板 |
组件详解
表格（Table）
from sql_report_generator.scripts.interactive_components import TableChart
table = TableChart(width=1200, height=600)
table_b64 = table.create({
'columns': ['订单ID', '客户', '金额', '日期', '状态'],
'rows': [
['ORD001', '张三', '¥1,000', '2026-03-26', '已完成'],
['ORD002', '李四', '¥2,500', '2026-03-25', '进行中'],
['ORD003', '王五', '¥1,800', '2026-03-24', '已完成']
],
'title': '订单列表'
})
特性：
- ✓ 交替行颜色，易于阅读
- ✓ 支持任意列数
- ✓ 自动调整列宽
- ✓ 蓝色头部，专业风格
矩阵（Matrix）
from sql_report_generator.scripts.interactive_components import MatrixChart
matrix = MatrixChart(width=1200, height=600)
matrix_b64 = matrix.create({
'rows': ['北京', '上海', '广州', '深圳'],
'columns': ['Q1', 'Q2', 'Q3', 'Q4'],
'values': [
[100, 150, 120, 200],
[80, 120, 100, 180],
[60, 90, 80, 140],
[70, 110, 95, 160]
],
'title': '地区季度销售额'
})
特性：
- ✓ 热力图配色（红黄绿）
- ✓ 数值标签
- ✓ 支持多维度分析
- ✓ 颜色条显示数值范围
切片器（Slicer）
from sql_report_generator.scripts.interactive_components import SlicerComponent
slicer = SlicerComponent(width=300, height=400)
slicer_b64 = slicer.create({
'title': '时间筛选',
'type': 'date',
'options': ['2026-01', '2026-02', '2026-03'],
'selected': '2026-03'
})
特性：
- ✓ 复选框样式
- ✓ 支持多选
- ✓ 选中状态高亮
- ✓ 紧凑布局
按钮导航（Button Navigator）
from sql_report_generator.scripts.interactive_components import ButtonNavigator
navigator = ButtonNavigator(width=1200, height=100)
nav_b64 = navigator.create({
'buttons': [
{'label': '首页', 'active': True},
{'label': '销售分析', 'active': False},
{'label': '财务报表', 'active': False},
{'label': '导出', 'active': False}
]
})
特性：
- ✓ 活跃状态高亮
- ✓ 圆角按钮
- ✓ 支持任意数量按钮
- ✓ 响应式布局
报告生成器（ReportBuilder）
from sql_report_generator.scripts.interactive_components import ReportBuilder
report = ReportBuilder()
# 设置元数据
report.set_metadata(
title='月度业绩报告',
author='数据分析团队',
date='2026-03-26'
)
# 添加内容
report.add_title('月度业绩报告', level=1)
report.add_text('本报告汇总了本月的关键业绩指标。')
report.add_chart('销售趋势', chart_b64, '销售额环比增长 15%')
report.add_table('订单列表', table_b64)
report.add_slicer(slicer_b64)
report.add_page_break()
# 导出
report.export_html('report.html')
report.export_json('report.json')
导出格式
HTML（推荐）
report.export_html('report.html')
优点：
- ✓ 支持所有浏览器
- ✓ 响应式设计
- ✓ 支持打印
- ✓ 文件小
JSON（API 集成）
report.export_json('report.json')
用途：
- ✓ 与其他系统集成
- ✓ 数据交换
- ✓ 版本控制
- ✓ 自定义渲染
PDF（可选）
# 需要安装: pip install reportlab pypdf2
report.export_pdf('report.pdf')
预设模板
sql-report-generator 提供 30+ 预设模板，覆盖常见场景：
业务类
sales-dashboard.md - 销售仪表盘channel-analysis.md - 渠道分析customer-cohort.md - 客户分群product-metrics.md - 产品指标
财务类
financial-ratio.md - 财务比率cash-flow.md - 现金流balance-sheet.md - 资产负债表income-statement.md - 利润表
运营类
kpi-dashboard.md - KPI 仪表盘project-status.md - 项目状态incident-report.md - 事件报告system-health.md - 系统健康度
人力类
hr-overview.md - HR 概览recruitment-report.md - 招聘报告performance-review.md - 绩效评估
技术类
tech-debt.md - 技术债sprint-report.md - Sprint 报告system-health.md - 系统健康
最佳实践
1. 报告结构
report = ReportBuilder()
# 1. 标题与摘要
report.add_title('月度业绩报告', level=1)
report.add_text('本报告总结了本月的关键指标和分析洞察。')
# 2. 关键指标
report.add_title('关键指标', level=2)
report.add_chart('KPI 卡片', kpi_chart)
# 3. 详细分析
report.add_title('详细分析', level=2)
report.add_chart('销售趋势', trend_chart)
report.add_chart('地区对比', comparison_chart)
# 4. 数据表格
report.add_title('明细数据', level=2)
report.add_table('订单列表', table_chart)
# 5. 附录
report.add_page_break()
report.add_title('附录', level=2)
report.add_text('数据来源：销售系统')
2. 数据预处理
import pandas as pd
# 清理数据
df = pd.read_sql(query, conn)
df = df.dropna()
df = df[df['value'] > 0]
# 聚合数据
df_agg = df.groupby('category').agg({
'value': 'sum',
'count': 'count'
}).reset_index()
# 排序
df_agg = df_agg.sort_values('value', ascending=False)
# 转换为表格格式
table_data = {
'columns': df_agg.columns.tolist(),
'rows': df_agg.values.tolist()
}
3. 缓存机制
import hashlib
import json
import os
def get_report_cached(report_config, cache_dir='./cache'):
# 生成缓存键
key = hashlib.md5(json.dumps(report_config).encode()).hexdigest()
cache_file = f"{cache_dir}/report_{key}.html"
# 检查缓存
if os.path.exists(cache_file):
with open(cache_file, 'r') as f:
return f.read()
# 生成新报告
report = ReportBuilder()
# ... 添加内容 ...
html = report._generate_html()
# 保存缓存
os.makedirs(cache_dir, exist_ok=True)
with open(cache_file, 'w') as f:
f.write(html)
return html
常见问题
Q: 如何自定义 HTML 样式？
A: 修改 _generate_html() 方法中的 CSS：
class CustomReportBuilder(ReportBuilder):
def _generate_html(self):
html = super()._generate_html()
# 自定义 CSS
custom_css = """
.container {
max-width: 1400px;
background: linear-gradient(to right, #f5f5f5, white);
}
"""
return html.replace('</style>', custom_css + '</style>')
Q: 如何添加页眉和页脚？
A: 在 HTML 中添加固定定位元素：
def add_header(self, text):
self.sections.insert(0, {
'type': 'header',
'content': text
})
def add_footer(self, text):
self.sections.append({
'type': 'footer',
'content': text
})
Q: 支持多语言吗？
A: 支持。通过配置文件或参数传递：
report = ReportBuilder(language='zh-CN')
# 或
report.set_language('en-US')
性能指标
| 操作 | 耗时 | 文件大小 |
|---|
| 生成 5 图表报告 | ~500ms | ~2MB |
| 生成 10 图表报告 | ~1s | ~4MB |
| 生成 20 图表报告 | ~2s | ~8MB |
| 导出 PDF（10 图） | ~3s | ~5MB |
许可证
MIT License - 生产级可商用
更新日志
- v1.0.0 (2026-03-26) - 初始版本，支持表格、矩阵、切片器、导航、报告生成
- v1.1.0 (计划) - 支持 PDF 导出、自定义模板、多语言
- v2.0.0 (计划) - 支持交互式 HTML、实时数据更新、云端存储
支持与反馈
