质量月报生成技能

SKILL.md

---
name: 质量月报生成技能
slug: quality-monthly-report
displayName: 质量月报生成技能
description: 基于质量月度数据生成专业的质量月报；当用户需要生成质量月报、汇总月度测试成果、进行多月数据对比分析时使用
version: 1.1.0
category: quality
author: org-jaxjwo0r
---
# 质量月报生成器

## 任务目标
- 本 Skill 用于：根据质量月度数据自动生成结构化的质量月报（HTML 格式）
- 能力包含：Excel 多 sheet 解析、多文件整合、整体分析框架、质量指标计算、多月趋势分析、PDCA总结、对比分析、报告大纲确认、HTML 可视化输出
- 触发条件：用户需要"写质量月报"、"生成测试月报"、"多个月份数据对比"时使用

## 前置准备
- 依赖说明：
  - Python 依赖：pandas（Excel 解析）、openpyxl（Excel 读写）
  - 系统依赖：mermaid-cli（用于渲染 Mermaid 图表为 SVG）
  - 首次使用时自动安装，约需 2-3 分钟

## 操作步骤
- 标准流程：
  1. **收集数据**
     - 用户手动提供本月质量数据
     - 或提供 Excel 文件（支持多 sheet）
     - 或提供 JSON 文件（符合 [数据格式规范](references/data_format.md)）
     - 支持多个文件（多个月份数据）
     - 如需对比分析，提供历史月份数据文件
  2. **数据解析与整合（关键步骤）**
     - 调用 `scripts/parse_excel.py` 解析 Excel 文件
     - 自动识别每个 sheet 的数据类型（测试用例/缺陷/工作总结/PDCA）
     - 检查数据完整性和一致性
     - 按月份整合数据，建立数据关联
     - 识别数据缺口，提示用户补充
  3. **建立整体分析框架**
     - 参考 [整体分析框架](references/analysis_framework.md)
     - 确定分析维度：时间维度、内容维度、深度维度
     - 识别关键分析点和对比基准
     - 规划图表类型和展示方式
  4. **计算指标与对比分析**
     - 调用 `scripts/metrics_calculator.py` 计算关键质量指标
     - 脚本支持单月计算或多月对比分析
     - 输入：符合规范的 JSON 数据文件（支持 `--previous-data` 参数传入历史数据）
     - 输出：计算结果 JSON（含指标、对比、趋势）
  5. **生成报告大纲（关键步骤）**
     - **智能体基于分析框架生成报告大纲给用户确认**
     - 大纲包含：章节结构、数据来源说明、关键数据点、图表规划、分析维度
     - **等待用户确认**：是否需要调整章节、增删内容、修改重点
     - 用户确认后，再进入下一步生成完整报告
  6. **生成月报**
     - 智能体基于计算结果和 [月报模板](assets/report_template.md) 生成 Markdown 内容
     - 包含：数据来源说明、月度总览、质量指标分析、PDCA总结、历史对比、趋势图表
  7. **输出交付（HTML 格式）**
     - **生成一个 HTML 格式的完整报告文件**
     - 文件命名：`质量月报_{{month}}.html`
     - 图表自动渲染：Mermaid 图表通过 mermaid-cli 转换为 SVG
     - 交互友好：HTML 可直接在浏览器中打开查看
     - 灵活转换：用户可使用浏览器"打印"功能另存为 PDF
     - 不生成多个分散的文件

### 多文件/多 Sheet 处理流程
- **单文件多 Sheet**：
  1. 解析所有 sheet，自动识别数据类型
  2. 整合不同 sheet 的数据（测试用例 + 缺陷 + 工作总结）
  3. 生成综合报告，标注各数据来源

- **多文件**：
  1. 按月份分类文件
  2. 整合每个文件的所有数据
  3. 建立时间序列，进行趋势分析
  4. 生成多月对比报告

- **混合数据源**：
  1. 统一数据格式（Excel/JSON/手动输入）
  2. 建立数据映射关系
  3. 识别数据缺口，提示用户补充
  4. 生成综合报告

### 连续性处理（同一对话多个月报）
- 智能体在对话中维护"历史数据池"
- 每次用户提交月度数据，智能体自动追加到历史记录
- 生成新报告时，智能体自动提取历史数据进行对比分析
- 用户可随时导出历史数据池为 JSON 文件进行持久化

## 资源索引
- 必要脚本：
  - 见 [scripts/parse_excel.py](scripts/parse_excel.py)
    - 用途：解析 Excel 文件（支持多 sheet），识别数据类型，转换为标准 JSON 格式
    - 参数：`输入文件`、`--output` 输出文件、`--convert` 转换为标准格式、`--analyze-only` 仅分析结构
  - 见 [scripts/metrics_calculator.py](scripts/metrics_calculator.py)
    - 用途：计算质量指标，支持单月计算和多月对比
    - 参数：`--input`（本月数据）、`--previous-data`（历史数据）、`--output`（输出文件）
  - 见 [scripts/md_to_html.py](scripts/md_to_html.py)
    - 用途：将 Markdown 转换为 HTML，自动渲染 Mermaid 图表为 SVG
    - 参数：`输入文件`、`-o` 输出文件（可选）
- 数据规范：见 [references/data_format.md](references/data_format.md)
  - 何时读取：用户提供数据时验证格式
  - 包含：完整字段定义、PDCA格式、多月数据格式
- 整体分析框架：见 [references/analysis_framework.md](references/analysis_framework.md)
  - 何时读取：处理多文件/多 sheet 时参考分析维度和方法
  - 包含：数据整合方法、分析维度构建、报告结构设计
- 月报模板：见 [assets/report_template.md](assets/report_template.md)
  - 用于生成最终月报的 Markdown 内容
  - 包含：标准章节、PDCA章节、趋势图表占位符（Mermaid 语法）
- 大纲模板：见 [reports/outline_template.md](reports/outline_template.md)
  - 用于生成报告大纲供用户确认

## 注意事项
- **必须先确认大纲**：用户确认报告大纲后，才能生成完整报告文件
- **HTML 输出**：仅生成一个 .html 文件，Mermaid 图表自动渲染为 SVG
- **图表格式**：使用 Mermaid 语法，通过 mermaid-cli 自动渲染为矢量图
- **Excel 解析**：自动识别多 sheet 的数据类型，无需用户手动指定
- **多文件处理**：按月份整合数据，建立时间序列，支持趋势分析
- **整体分析框架**：参考 analysis_framework.md，确保分析维度全面
- **数据缺口处理**：识别缺失数据，提示用户补充或标注说明
- **依赖安装**：首次使用时会自动安装 pandas、openpyxl、mermaid-cli，需等待 2-3 分钟
- **浏览器打开**：生成的 HTML 文件可直接在浏览器中打开查看
- **PDF 导出**：用户可在浏览器中使用"打印"功能选择"另存为 PDF"
- **优先使用脚本计算指标**，确保数值准确性
- **智能体负责解读数据**：PDCA分析、趋势解读、文字表述、整体分析框架应用
- 对于连续性数据，智能体会自动维护历史记录并提示用户
- 如数据格式不符合规范，指导用户按 [data_format.md](references/data_format.md) 调整
- PDCA 总结支持多组条目，每个条目包含 Plan/Do/Check/Act 四个阶段

## 使用示例

### 示例 1：单文件多 Sheet 生成报告
- 用户上传：`monthly_data.xlsx`（包含 5 个 sheet）
- 智能体：解析 Excel → 识别 sheet 类型 → 整合数据 → 生成报告大纲
- 大纲内容：
  ```
  数据来源：
    - 测试用例数据（sheet1）
    - 缺陷数据（sheet2）
    - 工作总结（sheet3）
    - PDCA 项目（sheet4）
    - 风险列表（sheet5）
  报告章节：
    1. 数据来源说明
    2. 月度总览
    3. 质量指标分析
    4. 工作总结
    5. PDCA 总结
    6. 风险与问题
    7. 下月计划
  ```
- 用户确认：生成报告
- 智能体：调用计算脚本 → 生成 Markdown → 转换为 HTML
- 输出：`质量月报_2024-01.html`（含所有数据和图表）

### 示例 2：多文件多月对比分析
- 用户上传：`2024-01.xlsx`、`2024-02.xlsx`、`2024-03.xlsx`
- 智能体：解析所有文件 → 按月份整合 → 建立时间序列 → 生成含对比分析的大纲
- 大纲内容：
  ```
  数据来源：
    - 2024年1月数据
    - 2024年2月数据
    - 2024年3月数据
  分析维度：
    - 时间维度：3个月趋势分析
    - 内容维度：测试执行/缺陷分布/工作效能
    - 深度维度：根因分析/效能分析/改进分析
  报告章节：
    1. 数据来源说明
    2. 月度总览（3个月对比）
    3. 趋势分析
    4. 数据洞察
    ...
  ```
- 用户确认：生成报告
- 智能体：计算指标 → 趋势分析 → 生成图表 → 转换为 HTML
- 输出：`质量月报_2024-03.html`（含3个月对比和趋势图表）

### 示例 3：调整大纲后生成
- 用户上传：`./2024-02.xlsx`
- 智能体：生成报告大纲（包含：总览、指标分析、PDCA、对比）
- 用户："增加一个'团队效能'章节，删掉'临时工作'章节，重点分析缺陷分布"
- 智能体：调整大纲 → 增加深度分析 → 再次确认 → 生成 Markdown → 转换为 HTML
- 输出：`质量月报_2024-02.html`（含新增章节和重点分析）

### 示例 4：导出历史数据
- 用户指令："导出历史数据"
- 智能体：将对话中的历史数据池导出为 JSON 文件
- 用户可在下次对话中导入此文件，继续进行对比分析

## TRACE 测评

| 维度 | 评分 | 说明 |
|------|------|------|
| T — 可信任度 | 9/10 | 纯文档/脚本技能，无外部依赖风险，支持中文交互 |
| R — 可靠性 | 10/10 | 有清晰工作流程; 有异常处理说明; 输出格式明确 |
| A — 适用性 | 9/10 | 有适用范围声明; 触发条件明确 |
| C — 规范性 | 10/10 | frontmatter 完整; 文档结构清晰; 内容充分 |
| E — 有效性 | 10/10 | 输出明确; 含使用示例; 文档详尽 |
| **总分** | **48/50** | 通过 |