home / skills / apconw / aix-db / report-generation

report-generation skill

safe

/agent/deepagent/skills/report-generation

This skill generates comprehensive data analysis HTML reports by querying data, performing deep cause analysis, and delivering visualizations and insights.

npx playbooks add skill apconw/aix-db --skill report-generation

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

7.8 KB

---
name: report-generation
description: 生成数据分析报告：查询数据 → 深度分析归因 → 输出 HTML 可视化报告
---

# 报告生成技能

## 何时使用

当用户要求生成**报告、分析报告、可视化报告、趋势分析、统计报告**等任何报告时。

## ⚠️ 约束（不可违反）

- **禁止写入本地文件**
- **禁止调用上传工具**（`upload_html_report_to_minio` 等）
- **HTML 必须用分隔符包裹后直接输出到对话中**
- **此技能是指令文档，直接按流程执行，不要说"调用技能"然后停下**

---

## 工作流程（5 步，必须全部完成）

### 第 1 步：理解需求

从用户诉求中提取：
- **报告类型**：销售、用户、产品、运营、财务等
- **关键指标**：总量、增长率、排名、占比等
- **分析维度**：时间、地区、类别、产品等
- **时间范围**：最近一周/月/年等

### 第 2 步：探索数据库 & 查询数据

1. `sql_db_list_tables` → 找到相关表
2. `sql_db_schema` → 查看列名和类型
3. `sql_db_table_relationship` → 查看表关系
4. `sql_db_query` → 执行查询获取数据

**查询原则：**
- 只查必要列，不用 `SELECT *`
- 使用表别名、适当的 JOIN 条件
- 合理使用聚合函数、GROUP BY、ORDER BY
- 默认 LIMIT 100

### 第 3 步：深度分析（⚠️ 必须执行，不可跳过）

**查询到数据后，必须先分析再生成报告。** 以下 4 个分析维度至少完成 3 个：

#### A. 描述性分析 — What happened

- 计算核心指标：总量、均值、中位数、最大/最小值
- 计算增长率：同比（YoY）、环比（MoM）
- 计算占比：各分类在整体中的比例
- 检测异常值：偏离均值超过 2 倍标准差的数据

#### B. 趋势分析 — How is it changing

- 趋势方向：上升/下降/平稳/波动
- 变化速率：加速还是减速
- 拐点识别：趋势逆转的关键时间点
- 周期性模式：季节性、节假日效应

#### C. 归因分析 — Why did it happen（⚠️ 核心，必须完成）

- **维度下钻**：哪个地区/产品/渠道对变化贡献最大？
- **贡献度量化**：各维度对总体变化的贡献百分比
- **对比归因**：表现优于/低于平均水平的类别及原因
- **结构变化**：各维度占比随时间的迁移

#### D. 对比分析 — How does it compare

- 时间对比：同比、环比
- 分组对比：不同地区/产品/渠道间的差异
- 排名分析：Top N 和 Bottom N
- 帕累托分析：头部集中度（80/20 效应）

### 第 4 步：生成 HTML 报告

**⚠️ 第 3 步的所有分析结果必须写入 HTML 报告中，不能只在思考过程中分析而不输出到报告里。**

报告 HTML 的 `<body>` 必须按顺序包含以下 **6 个区块**（缺一不可）：

| # | 区块 | HTML 结构 | 内容要求 |
|---|------|----------|---------|
| 1 | **报告标题** | `<header>` | 报告名称 + 时间范围 |
| 2 | **KPI 统计卡片** | `<section class="kpi-cards">` | 3-5 个关键指标卡片，每个包含：指标名、数值、同比/环比变化（↑绿↓红） |
| 3 | **可视化图表** | `<section class="charts">` | 至少 2 个 Chart.js 图表 |
| 4 | **详细数据表格** | `<section class="data-table">` | 完整数据列表，关键行高亮 |
| 5 | **深度分析与归因** | `<section class="deep-analysis">` | ⚠️ **必须包含，见下方详细结构** |
| 6 | **结论与建议** | `<section class="conclusions">` | 核心发现 + 可操作建议 |

**图表类型选择：**
- 时间趋势 → 折线图/面积图
- 类别对比 → 柱状图
- 占比分析 → 饼图/环形图
- 多指标对比 → 组合图（柱状图 + 折线图）
- 排名展示 → 水平柱状图

---

**⚠️ 第 5 区块「深度分析与归因」HTML 结构（强制）：**

```html
<section class="deep-analysis">
  <h2>深度分析与归因</h2>

  <!-- 5.1 描述性分析 -->
  <div class="analysis-block">
    <h3>数据概览</h3>
    <p>总量/均值/中位数等核心指标描述，标注同比环比变化。</p>
    <!-- 可选：异常值提示卡片 -->
  </div>

  <!-- 5.2 趋势分析 -->
  <div class="analysis-block">
    <h3>趋势分析</h3>
    <p>趋势方向、变化速率、拐点描述。</p>
    <!-- 建议配一个趋势折线图 -->
  </div>

  <!-- 5.3 归因分析（必须） -->
  <div class="analysis-block attribution">
    <h3>归因分析</h3>
    <!-- 贡献度排名表格 -->
    <table>
      <thead><tr><th>维度</th><th>贡献值</th><th>贡献占比</th><th>变化方向</th></tr></thead>
      <tbody>
        <tr><td>[维度A]</td><td>[+/-数值]</td><td>[XX%]</td><td>[↑/↓]</td></tr>
        <!-- 更多行... -->
      </tbody>
    </table>
    <p>核心驱动因素：[维度A] 贡献了整体增长的 XX%，主要原因是...</p>
    <p>主要拖累因素：[维度B] 导致下降 XX%，原因是...</p>
    <!-- 建议配一个堆叠柱状图或瀑布图展示各维度贡献 -->
  </div>

  <!-- 5.4 对比分析 -->
  <div class="analysis-block">
    <h3>对比分析</h3>
    <p>Top N / Bottom N 排名描述，帕累托效应描述。</p>
  </div>

  <!-- 5.5 风险提示 -->
  <div class="risk-alert">
    <h3>⚠️ 风险提示</h3>
    <ul>
      <li>[异常信号1：具体数字 + 影响说明]</li>
      <li>[异常信号2：具体数字 + 影响说明]</li>
    </ul>
  </div>
</section>
```

**第 6 区块「结论与建议」HTML 结构：**

```html
<section class="conclusions">
  <h2>结论与建议</h2>
  <div class="findings">
    <h3>核心发现</h3>
    <ol>
      <li>[发现1，必须带具体数字]</li>
      <li>[发现2，必须带具体数字]</li>
      <li>[发现3，必须带具体数字]</li>
    </ol>
  </div>
  <div class="recommendations">
    <h3>建议</h3>
    <ul>
      <li><strong>短期：</strong>[具体可操作的建议]</li>
      <li><strong>中期：</strong>[具体可操作的建议]</li>
      <li><strong>长期：</strong>[具体可操作的建议]</li>
    </ul>
  </div>
</section>
```

---

**HTML 技术要求：**
- Chart.js via CDN：`https://cdn.jsdelivr.net/npm/chart.js`
- Google Fonts：Inter（正文）+ Playfair Display（标题）
- CSS 变量实现浅色/深色模式（`prefers-color-scheme: dark`）
- 响应式设计，卡片布局，间距一致
- 配色专业（蓝色系为主），对比度 ≥ 4.5:1
- 不使用 emoji 作为图标（⚠️ 和 ↑↓ 在报告正文中允许使用）
- `.analysis-block` 和 `.risk-alert` 使用卡片样式（圆角、阴影、内边距）
- `.attribution table` 使用斑马纹样式，贡献占比列用进度条或色条可视化

### 第 5 步：输出报告

用分隔符包裹 HTML 直接输出：

```
根据查询结果，为您生成数据分析报告：

<!-- REPORT_HTML_START -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>...</head>
<body>...</body>
</html>
<!-- REPORT_HTML_END -->

**报告已生成完毕**，包含：
- [图表1说明]
- [图表2说明]
- 详细数据表格
- 分析结论与洞察

您可以点击「预览报告」查看，或点击「下载报告」保存到本地。
```

**关键：**
- 分隔符必须独占一行
- HTML 必须完整（DOCTYPE + html + head + body）
- 查询数据后必须立即生成报告，不要中途停顿

---

## 常见报告模式速查

| 模式 | 查询策略 | 推荐图表 |
|------|---------|---------|
| 时间趋势 | DATE_TRUNC + GROUP BY 月份 | 折线图 |
| 类别对比 | GROUP BY 类别 + ORDER BY | 柱状图 |
| Top N 排名 | ORDER BY DESC LIMIT N | 水平柱状图 |
| 占比分析 | GROUP BY + 百分比计算 | 饼图/环形图 |
| 增长率分析 | 窗口函数 LAG() | 折线图 + 数据标签 |
| 归因分解 | 多维度 GROUP BY + 增量贡献 | 瀑布图/堆叠柱状图 |
| 异常检测 | 均值 ± 2σ 标记异常 | 折线图 + 红色标注 |
| 帕累托分析 | 累积占比计算 | 组合图（柱状 + 累积线） |

Overview

This skill generates end-to-end data analysis reports: it discovers relevant tables, executes targeted SQL queries, performs deep multi-dimensional analysis, and outputs a complete HTML visualization report wrapped in delimiters. The HTML includes KPI cards, Chart.js visualizations, detailed tables, attribution analysis, and actionable recommendations. It is designed for interactive use where the report HTML is returned directly in the conversation for immediate preview or download by the user.

How this skill works

The skill inspects database schema and table relationships, constructs minimal focused SQL queries (no SELECT *), and retrieves a limited result set for analysis. It then computes descriptive, trend, attribution, and comparison metrics, detects anomalies, and synthesizes findings into an HTML report that follows a fixed structure and styling requirements. The final HTML is printed inline between strict start/end delimiters so it can be rendered or saved by the caller.

When to use it

User requests a sales, product, user, operations, or financial report with visualizations
Need a reproducible HTML report containing KPIs, charts, data tables, and attribution analysis
When you must present root-cause or contribution analysis across regions, products, or channels
When a concise, actionable conclusions-and-recommendations section is required
When interactive preview or immediate download of the report HTML is expected

Best practices

Extract report type, key metrics, dimensions, and time range before querying
Query only needed columns, use aliases and limit results (default LIMIT 100)
Always perform at least three of the four analysis types and include attribution
Embed Chart.js via CDN and follow the required HTML section order and styles
Output the full HTML between delimiter lines; do not attempt to write files or upload

Example use cases

Monthly sales performance: time trend, top products, region attribution, and recommendations
User churn analysis: cohort trends, anomaly detection, and drivers by acquisition channel
Product launch report: adoption trend, contribution by channel, and Top N product ranking
Operational dashboard export: KPIs, exception rows highlighted, and short/medium/long term actions

FAQ

How is the HTML delivered?

The report HTML is returned inline between explicit start/end delimiters so it can be previewed or saved; no local files are written and no upload tools are called.

What analyses are mandatory?

You must perform deep analysis and attribution. At least three of the four analysis types (descriptive, trend, attribution, comparison) should be completed, and attribution is required.