前言¶

跑完 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。