PPT-Matcher

SKILL.md

---
name: ppt-style-matcher
version: 1.1.0
description: PPT风格分析与匹配工具。提取已有PPT的设计规范（配色/字体/布局/装饰元素），指导新页面或修改页保持风格统一。
  Use when user asks to PPT风格匹配、修改几页风格不一致、分析PPT设计规范、提取PPT配色字体、新页面怎么跟原PPT风格一致、PPT重设计。
  不适用于从头创建全新PPT、不需要保持风格一致的场景、非PPTX格式文件。
---

## 概述

提取已有 PPT 的设计规范，输出风格指南，指导新页面或修改页保持视觉统一。核心能力：自动分析配色/字体/布局/装饰元素 → 输出可执行的风格规范 → 按规范创建或修改页面。

与 `pptx-add-slides` 互补：本 Skill 负责**分析风格 + 设计页面内容**，`pptx-add-slides` 负责**从 XML 模板克隆并插入页面**（如果目标恰好是"新增页面并保持风格"）。

### 功能范围

- 自动提取 PPT 的主色调、文字色、字体、字号层级
- 分析布局结构（页边距、标题区、内容区、底部区、列数）
- 识别装饰元素类型（竖条、卡片、编号、底栏）
- 判断页面布局复杂度（简单/中等/专业）
- 基于风格规范设计新页面内容（提供结构化文字和布局方案）
- 输出可直接交给 `pptx-add-slides` 或 file-agent 执行的内容规格

---

## 使用

### 场景 1：分析 PPT 风格并生成规范

```bash
python3 scripts/analyze_style.py "原PPT路径.pptx" 3,5,7,9
```

输出配色、字体、布局三个维度的分析报告。Agent 据此生成风格规范，指导后续页面设计。

### 场景 2：修改指定页面使之与整体风格一致

**三步走：**

1. **分析风格**：运行 `analyze_style.py` 选择 3-5 页风格统一的页面作为参考
2. **提取目标页内容**：用 python-pptx 读取目标页的所有文本，保留层级结构
3. **重设计并写入**：基于风格规范重新设计页面内容结构，派发给 file-agent 执行：

```
派发 file-agent，task 中描述：
- 原 PPT 路径、目标页码
- 从 analyze_style.py 提取的风格规范（主色/字体/字号/装饰元素）
- 重新设计后的页面内容结构（标题/副标题/要点/底部）
- 要求：删除旧页，在原位置创建新页，风格与参考页一致
```

### 场景 3：为新内容设计统一风格的页面

如果用户要新增页面但不确定怎么写内容结构，先运行 `analyze_style.py`，然后根据 `references/design-patterns.md` 匹配页面类型（介绍页/要点页/流程页/对比页），产出内容结构方案。确认后交给 `pptx-add-slides` 或 file-agent 执行。

### 风格分析脚本参考

| 参数 | 说明 |
|------|------|
| PPTX 路径 | 必填，本地文件绝对路径 |
| 采样页码 | 选填，逗号分隔（如 `3,5,7`），不填则自动选择中间页 |
| 输出 | 控制台打印分析报告（主色调/文字色/字体/复杂度） |

---

## 补充说明

### 依赖安装

```bash
pip install python-pptx
```

### 与 pptx-add-slides 的配合

| 场景 | 使用顺序 |
|------|---------|
| 新增页面 + 保持风格 | 1. ppt-style-matcher 分析风格 → 2. pptx-add-slides 克隆模板插入 |
| 修改已有页面风格 | 1. ppt-style-matcher 分析+设计 → 2. file-agent 执行重写 |
| 仅分析风格规范 | ppt-style-matcher 独立完成 |

### 常见问题

**Q：为什么不能直接通过 pptx-add-slides 克隆模板？**
A：如果页面内容结构与模板差异较大（比如目标页是三栏卡片，模板是单栏文字），直接克隆会导致布局错乱。此时需要本 Skill 先输出设计规范，判断应选哪种页面类型模板。

**Q：analyze_style.py 采样哪些页面？**
A：选择排版最典型的 3-5 页内容页，避开封面/目录页。不传页码时脚本自动跳过前几页选择中间页面。

**Q：分析出的主色调不准确？**
A：脚本排除白色(#FFFFFF)和黑色(#000000)，取填充色中频率最高的非黑白颜色。如果 PPT 本身没有使用填充色（纯白背景），主色调会显示"未识别"，此时手动选择最显眼的强调色即可。

### 已知坑点

1. **不要依赖 ppt_write/ppt_delete**：这些工具不存在。创建和删除 PPT 页面的操作必须派发给 file-agent，或在 `scripts/` 中编写专门的 Python 脚本。
2. **字体名称跨平台不一致**：macOS 和 Windows 上同一 PPT 的字体名称可能不同（如 "微软雅黑" vs "Microsoft YaHei"），分析结果以实际读取到的为准。
3. **python-pptx 对渐变/透明色的支持有限**：`analyze_style.py` 仅统计纯色填充，渐变背景不会被计入。如果 PPT 大量使用渐变，需额外人工确认。