report-generation

报告生成

此技能使 AI Agent 能够根据结构化输入生成精美的数据驱动报告。Agent 接受 JSON、CSV 或 API 响应格式的数据，应用报告模板，生成叙述性洞察以及表格和图表规范，并以 Markdown、HTML 或 PDF 格式输出最终报告。它支持常见的报告类型，包括冲刺回顾、财务摘要、分析仪表板和事件复盘。

工作流

1. 导入并验证源数据。 接受 JSON、CSV、YAML 或原始 API 响应格式的输入数据文件或负载。验证架构——检查必填字段、数据类型是否正确、是否存在缺失值和异常值。如果数据不完整（例如，冲刺回顾 JSON 缺少速度字段），请标记这一缺口，并选择推断默认值、请求补充缺失值，或在报告中注明该遗漏。统一日期格式、货币符号和单位，确保一致。

2. 选择或自定义报告模板。 根据用户指定的报告类型，将数据与相应的报告模板匹配。内置模板包括：sprint_retrospective、financial_summary、analytics_dashboard、incident_postmortem 和 weekly_status。每个模板都定义了章节顺序、必需的数据映射、图表类型和语气（财务报告采用分析型语气，回顾采用建设性语气，复盘采用紧迫语气）。用户可以通过覆盖章节、添加字段或更改视觉主题来自定义模板。

3. 计算指标并生成洞察。 从原始数据中推导计算指标——百分比变化、平均值、排名、趋势方向和异常标记。对于冲刺回顾，计算速度差异和承诺准确率。对于分析报告，计算转化率和细分级别的明细。然后生成叙述性洞察：不仅要写“转化率为 3.2%”，还要写“转化率较上一周期下降了 0.8 个百分点，主要原因是移动流量减少了 15%。”

4. 填充报告结构。 使用计算得出的指标、叙述性洞察和格式化数据表格填充模板章节。为模板中的每个可视化位置生成图表规范（柱状图、折线图、饼图或表格）。行内表格使用 Markdown 表格语法，可视化图表使用图表规范格式（例如 Mermaid、Vega-Lite 或 Chart.js JSON）。添加章节标题、执行摘要和任何附录。

5. 格式化并渲染输出。 按请求的格式生成最终报告。对于 Markdown，输出包含表格和图表代码块的简洁 .md 文件。对于 HTML，将 Markdown 输出嵌入带有 CSS 的样式模板，以便于打印的方式渲染。对于 PDF，使用无头浏览器或 Puppeteer、WeasyPrint 等工具转换 HTML 版本。确保图表在所有格式中都能正确渲染，且 PDF 中的表格不会跨页断开。

6. 审查并定稿。 执行质量检查：确认报告中的所有数据点都能追溯到源数据，确保没有未解析的模板变量（例如 {{quarter}}），确认洞察有数据支持，并检查报告篇幅是否符合该类型的预期范围。交付报告，并简要总结生成的内容。

用法

向 Agent 提供报告类型、源数据、任何自定义偏好以及所需的输出格式。Agent 将返回一份完整、格式化的报告。

提示词格式：

Generate a [report type] report.
Data source: [path to JSON/CSV file, or inline data]
Time period: [date range or sprint number]
Template: [built-in template name or "custom"]
Output format: [markdown / html / pdf]

示例

示例 1：根据结构化数据生成冲刺回顾报告

输入数据（JSON）：

{
  "sprint": {
    "number": 14,
    "start_date": "2026-01-27",
    "end_date": "2026-02-07",
    "goal": "Ship checkout flow redesign and analytics instrumentation"
  },
  "velocity": {
    "committed": 34,
    "completed": 29,
    "previous_sprints": [31, 28, 33, 30]
  },
  "stories": {
    "total": 12,
    "completed": 10,
    "carried_over": 2,
    "carried_over_items": [
      "CHECKOUT-142: Edge case handling for international addresses",
      "ANALYTICS-89: Cross-domain tracking for subdomain events"
    ]
  },
  "what_went_well": [
    "Checkout redesign shipped 2 days early",
    "Zero P1 bugs in production release",
    "Effective pairing sessions between frontend and backend teams"
  ],
  "what_could_improve": [
    "Sprint scope increased mid-sprint with 3 unplanned tickets",
    "QA bottleneck on Thursday caused idle time for 2 developers",
    "Standup meetings ran over 15 minutes on 3 of 10 days"
  ],
  "action_items": [
    { "owner": "Priya", "action": "Add a mid-sprint scope freeze policy" },
    { "owner": "James", "action": "Schedule a dedicated QA window on Wednesdays" },
    { "owner": "Dana", "action": "Timekeeper rotation for standups" }
  ]
}

输出（Markdown 报告）：

# Sprint 14 Retrospective

**Sprint dates:** January 27 – February 7, 2026
**Sprint goal:** Ship checkout flow redesign and analytics instrumentation

---

## Executive Summary

Sprint 14 delivered 85% of committed story points (29 of 34), slightly below
the team's rolling average velocity of 30.5. The primary sprint goal was
partially met: the checkout redesign shipped ahead of schedule, but two
analytics stories carried over due to mid-sprint scope changes and a QA
bottleneck. Zero P1 bugs were introduced, reflecting strong code quality.

## Velocity

| Metric               | Sprint 14 | 4-Sprint Average |
|----------------------|-----------|------------------|
| Committed            | 34 pts    | 31.0 pts         |
| Completed            | 29 pts    | 30.5 pts         |
| Commitment accuracy  | 85%       | 98%              |

The team over-committed by 3 points relative to the historical average.
The shortfall is attributable to 3 unplanned tickets added mid-sprint,
which consumed approximately 5 story points of capacity.

## Story Completion

- **Completed:** 10 of 12 stories (83%)
- **Carried over:** 2 stories
  - CHECKOUT-142: Edge case handling for international addresses
  - ANALYTICS-89: Cross-domain tracking for subdomain events

Both carried-over stories are estimated at 2-3 points each and will be
prioritized at the top of Sprint 15.

## What Went Well

- Checkout redesign shipped 2 days ahead of the sprint end date, allowing
  extra time for integration testing.
- Zero P1 bugs in the production release — the team's pairing sessions
  caught issues early in development.
- Cross-functional pairing sessions were cited by 3 team members as the
  highlight of the sprint.

## What Could Improve

- **Mid-sprint scope creep:** 3 unplanned tickets were added after sprint
  planning, consuming capacity and contributing to the 2 carried-over stories.
- **QA bottleneck:** All completed stories landed in QA on Thursday, creating
  a pileup that left 2 developers idle on Friday morning.
- **Standup duration:** Standups exceeded 15 minutes on 3 of 10 days.

## Action Items

| Owner | Action                                           | Target Date |
|-------|--------------------------------------------------|-------------|
| Priya | Add a mid-sprint scope freeze policy             | Feb 10      |
| James | Schedule a dedicated QA window on Wednesdays     | Feb 10      |
| Dana  | Implement timekeeper rotation for standups       | Feb 10      |

---

*Report generated from sprint data. Source: sprint-14-retro.json*

示例 2：包含洞察和建议的分析报告

输入：

Generate an analytics report for the marketing website.
Data source: /data/website-analytics-jan-2026.json
Time period: January 2026
Output format: markdown

输出：

# Website Analytics Report — January 2026

**Reporting period:** January 1–31, 2026
**Compared to:** December 2025

---

## Executive Summary

Website traffic increased 12% month-over-month to 284,000 sessions, driven
primarily by organic search growth (+18%). However, overall conversion rate
declined from 4.0% to 3.2%, with the sharpest drop on mobile devices. The
pricing page continues to be the highest-converting entry point, while the
blog showed strong traffic growth but low conversion intent.

## Traffic Overview

| Metric             | January 2026 | December 2025 | Change  |
|--------------------|-------------|---------------|---------|
| Total sessions     | 284,000     | 253,500       | +12.0%  |
| Unique visitors    | 198,600     | 179,400       | +10.7%  |
| Pages per session  | 3.2         | 3.4           | -5.9%   |
| Avg session dur.   | 2m 48s      | 3m 05s        | -9.2%   |
| Bounce rate        | 42%         | 38%           | +4pp    |

## Traffic by Channel

| Channel        | Sessions | Share | MoM Change |
|----------------|----------|-------|------------|
| Organic Search | 142,000  | 50%   | +18.3%     |
| Direct         | 62,500   | 22%   | +5.1%      |
| Paid Search    | 39,800   | 14%   | +8.7%      |
| Social         | 25,600   | 9%    | +2.3%      |
| Referral       | 14,100   | 5%    | -3.8%      |

**Insight:** Organic search growth (+18.3%) was the primary traffic driver,
likely attributable to the 6 new blog posts published in January. However,
the drop in pages-per-session and increased bounce rate suggest this new
organic traffic has lower engagement intent than existing visitors.

## Conversion Funnel

| Stage                  | Visitors | Rate   | MoM Change |
|------------------------|----------|--------|------------|
| Homepage to Pricing    | 84,200   | 29.6%  | -1.2pp     |
| Pricing to Signup      | 15,400   | 18.3%  | -2.1pp     |
| Signup to Activation   | 9,100    | 59.1%  | +0.8pp     |
| **Overall conversion** | **9,100**| **3.2%** | **-0.8pp** |

**Insight:** The conversion drop is concentrated in the Pricing to Signup
step (-2.1pp). A/B test data shows the new pricing page variant (launched
Jan 15) underperforms the control by 1.8pp. Recommendation: revert to the
control pricing page and redesign the variant.

## Recommendations

1. **Revert the pricing page A/B test.** The new variant is underperforming
   by 1.8pp on the key Pricing to Signup conversion step.
2. **Add conversion-intent CTAs to blog posts.** The 18% organic traffic
   growth is not converting. Embed contextual product CTAs within blog
   content to capture high-intent readers.
3. **Investigate mobile conversion drop.** Mobile sessions grew 15% but
   mobile conversion fell 1.2pp. Audit the mobile signup flow for UX
   friction, particularly form field usability and page load speed.
4. **Double down on organic content.** The SEO investment is paying off
   in traffic. Publish 8 posts in February targeting mid-funnel keywords
   with stronger commercial intent.

---

*Report generated from website-analytics-jan-2026.json. Data: Google Analytics.*

最佳实践

• 以执行摘要开篇。 决策者会阅读第一段，并快速浏览其余内容。将最重要的发现和建议放在最前面，不要埋在报告中间。
• 展示对比，而不只是数字。 原始指标缺乏背景信息。务必提供对比基准——上一周期、目标、行业基准或历史平均值——让读者了解数字是好是坏。
• 提供叙述性洞察，而不只是罗列数据。 数字表格需要读者自行分析。每张数据表都应配上一句话，说明数据的含义及其重要性。
• 全文采用一致的格式。 对齐表格列，统一日期格式，并保持标题层级一致。格式不一致会削弱读者对数据的信任。
• 让报告便于快速浏览。 充分使用章节标题、项目符号、加粗的关键数字和留白。在报告中堆砌大段文字，效果与在邮件中堆砌文字一样差。
• 注明数据来源。 在页脚或附录中说明数据来源、提取时间，以及应用的筛选条件或排除项。这样可以确保报告可审计、可复现。

边界情况

• 数据字段不完整或缺失。 如果源数据缺少预期字段，应在报告中明确说明缺口（例如：“速度数据不可用——未计算承诺准确率”），而不是默默省略该部分或编造数字。
• 数据中存在离群值或异常情况。 标记异常数据点（例如，因机器人攻击导致流量激增 10 倍），并说明这些数据是否计入汇总计算。
• 多个数据源相互冲突。 如果两个来源的数据不一致（例如，CRM 显示已成交 120 笔，财务部门显示 118 笔），应注明差异、说明采用了哪个来源，并建议进行核对。
• 数据集非常庞大。 对于包含数千行的数据文件，应按适当粒度（按日、按周或按细分群体）汇总，而不是逐行列出。可应要求提供详细附录。
• 敏感的财务或人事数据。 对生成的报告实施访问控制。在团队级报告中隐藏个人薪酬数据。若报告包含个人身份信息（PII）或财务数据，应标记为限制分发。