name: generate-data-report-ppt description: > 通用数据报告 PPT 生成器。输入任意 Excel 数据文件，自动探查数据结构、计算指标、通过六项用户确认后生成高质量 PPT 报告。图表使用原生 python-pptx 可编辑 Chart 对象（非 matplotlib PNG 插入）。

内置质量自检引擎，自动检测布局/视觉/内容/数据问题并迭代修复至理想效果。

通用数据报告 PPT 生成器

输入任意 Excel 文件，自动生成高质量可编辑数据报告 PPT。

工作流程

接收 Excel 文件：用户提供任意格式的 Excel 数据文件。
数据探查：scripts/data_profiler.py 自动检测 Schema、统计特征、数据质量及字段语义。
智能分析与推荐：scripts/agent_analyzer.py 基于探查结果生成指标推荐、页面结构建议及可视化方案。
用户确认（六项）：生成 PPT 前必须与用户确认以下内容：
- 报告周期与页数范围
- 核心指标集
- 受众与决策场景
- 视觉风格与配色方向
- 页面结构与模板方案
- （合计六项确认内容）
生成 PPT：scripts/ppt_builder.py 按用户确认的配置，动态选择布局模板、应用主题配色、插入原生可编辑图表。
质量自检与修复：scripts/quality_inspector.py 检查四类 25 项质量标准，发现问题自动修复，迭代至阈值达标。
输出：保存 .pptx 文件。所有图表和表格均可在 PowerPoint 中编辑。

目录结构

generate-data-report-ppt/
├── SKILL.md
├── scripts/
│   ├── data_loader.py              # Excel 加载与数据清洗（保留原有兼容）
│   ├── data_profiler.py            # 通用数据探查引擎（新增）
│   ├── report_config.py            # ReportConfig 数据模型定义（新增）
│   ├── theme_manager.py            # 多主题配色与模板管理（新增）
│   ├── agent_analyzer.py           # LLM 智能分析与推荐（新增）
│   ├── metrics_calculator.py       # KPI 计算引擎（新增通用计算函数）
│   ├── chart_factory.py            # 原生可编辑图表创建
│   ├── page_layouts.py             # 动态页面布局引擎（新增）
│   ├── quality_rules.py            # 质量检查规则定义（新增）
│   ├── quality_inspector.py        # 质量自检与自动修复引擎（新增）
│   ├── ppt_builder.py              # PPT 组装编排器（build_report / quality_assured_build）
├── references/
│   ├── data-schema.md              # Excel 字段映射与校验规则
│   ├── report-structures.md        # 日报/周报/月报页面结构
│   ├── chart-specs.md              # 原生图表类型、配色、数据绑定
│   ├── visual-style-guide.md       # 布局、字体、配色方案
│   └── professional-data-analyst-playbook.md # 专业数据分析师洞察标准
└── assets/
    ├── report-master.pptx          # 日报模板（封面、内容页、目录、尾页）
    ├── weekly-master.pptx          # 周报模板
    └── monthly-master.pptx         # 月报模板

新增核心模块

ReportConfig（report_config.py）

通用数据模型，定义报告配置的所有要素：

ReportConfig：报告标题、周期、数据来源、主题、页数范围、质量阈值、最大修复迭代次数
MetricDef：指标名称、列映射、聚合方式、数值格式、单位、指标类型
PageDef：页面类型、标题、结论标题、布局模板、可选图表类型、选中状态
PeriodType 枚举：DAILY / WEEKLY / MONTHLY / CUSTOM
ChartType 枚举：BAR / LINE / PIE / DOUGHNUT / FUNNEL / TABLE / AUTO

数据探查（data_profiler.py）

自动分析任意 Excel 数据结构：

Schema 检测：列名、类型推断、缺失率、唯一值统计
统计特征提取：数值列的 min/max/mean/std/分位数，分类列的分布/基数
语义推断：自动识别时间列、分类列、数值列、ID 列
数据质量评分：完整性、唯一性、合理性三维度评分

多主题管理（theme_manager.py）

5 套预设主题：商务经典（默认）、清新简约、科技蓝调、暖橙活力、暗夜深邃
每套主题包含：主色、辅色、强调色、背景色、文字色、系列色盘
支持自定义配色覆盖
theme_to_rgb_colors() 一键转换为 pptx RGBColor 对象
新增 extract_theme_from_template() 从用户上传的模板母版自动提取主题色和字体
新增 ThemePreset.FROM_TEMPLATE 使用模板自带配色方案

智能分析（agent_analyzer.py）

自动识别可量化的数值指标
推荐可视化方案（图表类型、配色、数据准备方式）
生成页面结构建议（含结论标题和洞察文案模板）
所有推荐需经用户确认后注入 ReportConfig

生成指标推荐、页面结构、每页洞察、总结页、预测页或质量复核时，必须参考 references/professional-data-analyst-playbook.md。Agent 的角色是专业数据分析师，而不是模板填充器：

每个分析页必须包含业务判断、数据证据、对比关系、原因假设或机制解释、风险/机会、行动建议中的至少三项。
从第 4 页开始尤其禁止只做数据总结；必须写出结构、趋势、集中度、转化、缺口、异常、风险和下一步动作。
长分类列表不得塞进 KPI 值或正文段落；使用 Top N + 其余汇总。

页面布局引擎（page_layouts.py）

预定义布局模板：KPI 网格、图表左+洞察右、两栏、两行、卡片网格、全宽
calculate_content_area() 计算可用内容区域
calculate_fill_ratio() 计算页面内容填充率
ensure_safe_position() 确保元素在页面安全区域内
新增 LayoutContext：封装模板实际尺寸（宽/高/边距/内容区），支持 16:9、4:3 等任意尺寸模板

自定义模板解析（template_parser.py）

解析任意 .pptx 模板，自动识别母版页类型（封面/内容/目录/尾页）
提取占位符列表，支持别名映射（如 {report_title} / {标题}）
自动检测主题色、字体、幻灯片尺寸、安全边距、内容区域
输出 TemplateProfile，供 ppt_builder.py 动态选择母版页和适配布局
内置模板与用户模板走同一套解析流程，保证接口一致

质量自检（quality_rules.py + quality_inspector.py）

四类 25 项检查规则：

类别	检查项	自动修复
layout（布局）	元素飞出边界（4方向）、图文重叠、占位符未替换、元素紧贴边缘	✅
visual（视觉）	字体不一致、字号过小/过大、颜色对比度不足、图片拉伸变形	✅
content（内容）	页面留白过多、KPI数值为空、图表无数据、文本截断、分析文本过短、缺少标题	✅
data（数据）	图表与文本矛盾、页码错乱、数据来源缺失、表格列宽不合理、图表刻度异常	部分

迭代修复机制：

生成 PPT → 执行全量检查 → 报告问题
对可自动修复的问题执行修复 → 重新检查
重复至无严重/主要问题或达最大迭代次数
计算质量评分（0-100），评分 ≥ 阈值（默认 85）输出

质量评分计算：

严重问题：-20 分/页
主要问题：-10 分/页
次要问题：-3 分/页
加权归一化到 100 分制

报告类型（配置驱动）

日报

结构：封面 → KPI总览 → 趋势图 → 分布/排行 → 异常告警 → 总结
页数：配置驱动

周报
结构：封面 → 周汇总 → 7日趋势 → 环比分析 → 分布/排行 → 总结
页数：配置驱动

月报
结构：封面 → 目录 → 月度总览 → 趋势/分布 → 排行/绩效 → 预测规划 → 尾页
页数：配置驱动

执行示例

from scripts.ppt_builder import build_report, quality_assured_build
from scripts.report_config import ReportConfig, PageDef, MetricDef, PeriodType

config = ReportConfig(
    title='销售数据报告',
    period_type=PeriodType.MONTHLY,
    source_label='销售部',
    theme='business_classic',
    quality_threshold=85,
    max_fix_iterations=3,
)
# config 需经用户确认后填充 metrics 和 pages

build_report('any_data.xlsx', config, 'output.pptx')

# === 使用自定义模板 ===
config = ReportConfig(
    title='销售数据报告',
    period_type='monthly',
    source_label='销售部',
    template_path='my-template.pptx',   # 用户上传的模板
    use_template_theme=True,             # 自动应用模板提取的配色
    quality_threshold=85,
    max_fix_iterations=3,
)
build_report('any_data.xlsx', config, 'output_custom.pptx')

# === 带质量保证的方式（推荐）===
prs, issues = quality_assured_build('any_data.xlsx', config, 'output_qa.pptx')

V2 generation contract

Before calling build_report or quality_assured_build, fill and validate the six user confirmations:

报告周期与页数范围
核心指标集
受众与决策场景
视觉风格与配色方向
页面结构与模板方案
数据范围与字段映射

Use ConfirmationSpec on ReportConfig.user_confirmation to record completion. Generic builds default to require_six_confirmations=True; missing confirmations or invalid metric-to-column mappings must stop generation before any PPT is written.

Data profiling serves the confirmed business intent. It should map the confirmed metrics and dimensions to actual Excel columns, then select feasible pages and layouts. It must not invent a different business focus when the user has already confirmed the core metrics.

For visual quality, treat master PPTX files as style assets, not rigid page contracts. If a template placeholder cannot be populated, remove the whole placeholder component. If a KPI grid consumes the available vertical space, do not add bottom insight text; use a later analysis page or a different layout instead.

For analytical quality, load references/professional-data-analyst-playbook.md before generating or reviewing report narratives. A page that only restates totals, rankings, or category names without comparison, diagnosis, implication, or action is not acceptable even if layout quality passes.

自定义模板规范

用户可提供自定义 .pptx 模板，skill 自动解析并按其样式生成报告。

母版页结构（建议）

母版页	建议包含的占位符	用途
封面页	`{report_title}`, `{date}`, `{department}`	报告封面
目录页	`{chapter1_title}`, `{chapter1_desc}`, ...	目录/导航页
内容页	`{page_title}`, `{source}`, `{period}`	正文页（图表、洞察）
尾页	`{report_title}`	结束页

占位符规则

使用 {} 包裹，如 {report_title}
不强制要求全部占位符，缺少的会自动跳过或智能补充
支持中文别名：{标题}, {日期}, {部门}, {页面标题}, {数据来源}, {页码} 等

样式设计建议

主题色：在母版中设置主题颜色，agent 会自动提取并应用到图表、卡片、文本
字体：在母版中分别设置标题和正文字体，agent 会识别并统一应用
背景：纯色、渐变或图片背景均可，复制时会完整保留
尺寸：支持 16:9、4:3 等任意尺寸，布局引擎自动适配
页眉/页脚：已有的页眉页脚图形会保留，agent 自动检测避免重复添加

配色优先级

用户显式配置 config.theme（最高优先级）
模板提取的配色（use_template_theme=True 时生效）
默认商务经典主题（兜底）

关键缺陷与修复记录

封面页速查 — quality_inspector 自动检测以下问题（V006/C012），无需手动排查：

_duplicate_slide() 不用 source_slide.slide_layout → 背景/Logo 丢失 ✅ 代码已修复

keep_shapes=False 用于封面 → 占位符被删除 ✅ 代码已修复

占位符文字浅色但位置在白色背景区域 → V006 自动检测+修复

封面占位符仍为模板默认文字 → C012 自动检测，阻断输出

`_build_cover_page()` 双阶段占位符填充 — idx 兜底机制 (2026-05-25)

症状: 模板封面无 {report_title} 等文本标记时，封面显示空白。

修复: 两阶段策略：

Pass 1: _replace_all_placeholders() 文本模式匹配（兼容内置模板）
Pass 2: placeholder_format.idx 兜底直填（兼容 Wuling 等无标记模板）

# idx 映射：0=TITLE, 10=SUBTITLE, 21/22=BODY quarter-size
if ph.idx == 0:   _set_para_text(p, config.title, C_PRIMARY, Pt(36))
elif ph.idx == 21: _set_para_text(p, date_text, C_PRIMARY, Pt(18))
elif ph.idx == 22: _set_para_text(p, dept_text, C_TEXT_GRAY, Pt(12))

⚠️ 文字颜色始终用深色：很多模板封面只有上半部有彩色 banner，title 在白色区域。

`_duplicate_slide()` — 核心修复 (2026-05-25)

两条关键修复，已应用到全代码库：

修复	问题	方案
用 `source_slide.slide_layout` 代替 `blank_layout`	切到错误 Master，丢失背景/Logo	`new_slide = prs.slides.add_slide(source_layout)`
增加 `keep_shapes` 参数	封面/目录/尾页占位符被删除	`keep_shapes=True` 保留 layout 占位符

OOXML 三层继承链：Theme → Slide Master(背景+Logo) → Slide Layout(占位符) → Slide(内容)

python-pptx 装饰图形陷阱 (2026-05-25)

add_slide(layout) 只创建占位符，不复制 layout 中的非占位符装饰图形（渐变矩形、Logo 等）。这些图形存在于 layout XML 的 <p:spTree> 中，PowerPoint 打开时从 layout 继承渲染，但 python-pptx 不保证引用正确 → 装饰图形可能丢失。

工具函数: copy_layout_decorative_shapes(slide, layout) — 从 layout XML deepcopy 所有无 <p:ph> 的 <p:sp> 到 slide XML。

SKILL.md 14 KB Bezpośredni odnośnik Historia Czysty