ppt-style-matcher

PPT风格匹配技能 v4.1

核心思路：分析原PPT风格 → 锁定配色/字体/布局参数 → 用python-pptx生成新页面 → 完全重建sldIdLst → P0-P3分级验证

⚠️ v4.1关键改进：色板提取用全局颜色频率（不再依赖采样页偏差）、智能采样增加颜色多样性、深色PPT文字色修正

---

⛔ 强制约束（7条，不可跳过）

---

第一步：需求澄清（6问法，借鉴guizang）

在动手之前，先回答6个问题。不回答完不开始。

1. 目标页：修改哪些页？（页码范围）
2. 修改类型：新增页？替换页？还是美化已有页？
3. 内容来源：内容是已存在的还是需要我搜索整理？
4. 风格参考：是否有参考页？（如"像第8页那样的风格"）
5. 特殊要求：有无特殊布局需求？（如"数据要突出""要有流程图"）
6. 输出路径：修改后的文件保存到哪里？

---

第二步：风格分析

运行 scripts/analyze_style.py 提取风格参数：

python3 scripts/analyze_style.py  [--verbose]

必须确认以下参数后再继续（防幻觉）：

2.1 5色锁定色板

脚本自动提取，输出格式：

COLOR_PRIMARY: #22C55E   ← 主色，最高频非白非黑填充色
COLOR_SECONDARY: #374151  ← 辅色，中性色优先（深灰/深蓝/深绿）
COLOR_ACCENT: #C00000     ← 强调色，高饱和色优先（红/橙/蓝）
COLOR_BG: #FFFFFF          ← 背景色
COLOR_TEXT: #1F2937        ← 主文字色（浅色PPT选深色，深色PPT选浅色）
COLOR_TEXT_LIGHT: #4B5563  ← 辅文字色
IS_DARK_THEME: False       ← 是否深色主题

⚠️ v4改进：

• 深色PPT自动检测，TEXT色适配（选白色/浅灰而非红色）
• SECONDARY优先中性色，ACCENT优先高饱和色，不再角色倒挂
• 默认采样改为智能选择设计良好的页面（shape≥20优先）

2.2 字体三级分工

按字号范围推断：

• 标题字体：≥20pt 的最高频字体
• 正文字体：14-19pt 的最高频字体
• 注释字体：<14pt 的最高频字体

⚠️ 如果三个级别是同一字体（常见于中文PPT），标题用加粗、正文用常规即可。

2.3 布局参数

从 --verbose 输出中提取：

• MARGIN_L / MARGIN_R：左右安全边距
• HEADER_H：标题区高度
• FOOTER_H：底部装饰条高度
• CONTENT_X/Y/W/H：内容区范围
• has_left_right_split：是否左右分栏及比例
• is_simple_page：是否简单页（shape<10，布局参数无参考价值）

⚠️ v4改进：简单页（shape<10）的布局参数自动清空，避免误导。参考页推荐在分析结果末尾输出。

2.4 节奏感

脚本自动检测节奏，根据PPT类型切换策略：

• 深色/混合PPT：检测连续深/浅色页面，≥3页连续报视觉疲劳
• 浅色PPT（>85%浅色页）：检测章节分隔页间距和连续稀疏页，不再误报"连续浅色"

⚠️ v4改进：浅色PPT不再报"连续37页浅色=视觉疲劳"，改用结构节奏检测。

---

第三步：内容确定

1. 用python-pptx读取目标页的纯文本内容
2. 如需新增内容，搜索整理后写入
3. 按内容量选择合适的布局模式（见 design-patterns.md）

---

第四步：布局计算（核心！）

所有坐标必须从公式算出，禁止硬编码。

基础参数（从第二步提取）

SLIDE_W = 33.87  # cm, 从分析结果
SLIDE_H = 19.05  # cm
MARGIN_L = 2.1
MARGIN_R = 1.8
HEADER_H = 3.5   # 标题区
FOOTER_H = 3.0   # 底部装饰条（如有）

CONTENT_X = MARGIN_L
CONTENT_Y = HEADER_H + 0.5  # 标题下方0.5cm
CONTENT_W = SLIDE_W - MARGIN_L - MARGIN_R
CONTENT_H = SLIDE_H - CONTENT_Y - FOOTER_H - 0.3

双栏布局公式

GAP = 0.8  # 分栏间距，0.6-1.0cm范围

# 根据内容量选择比例
# 文字密集 → 0.58 | 适中 → 0.6 | 精简 → 0.5
ratio_left = 0.6

LEFT_W  = (CONTENT_W - GAP) * ratio_left
RIGHT_W = (CONTENT_W - GAP) * (1 - ratio_left)
LEFT_X  = CONTENT_X
RIGHT_X = CONTENT_X + LEFT_W + GAP

# ⚠️ 验证：LEFT_X + LEFT_W + GAP + RIGHT_W 应 ≈ CONTENT_X + CONTENT_W

三栏布局公式

COL3_GAP = 0.6
COL3_W = (CONTENT_W - 2 * COL3_GAP) / 3
COL3_X = [CONTENT_X + i * (COL3_W + COL3_GAP) for i in range(3)]

卡片内部结构

# 左装饰条
DECOR_W = 0.2  # cm
decor_x = card_x
decor_w = DECOR_W
decor_h = card_h

# 标题
title_x = card_x + DECOR_W + 0.2
title_w = card_w - DECOR_W - 0.4
title_pt = 14  # 三级标题

# 描述
desc_x = title_x
desc_w = title_w
desc_pt = 12  # 注释字号

---

第五步：节奏感规划

参考第二步的节奏感检测结果：

• 如果目标页前后都是浅色页，考虑给新页加一个深色强调元素
• 连续新增多页时，交替使用深色和浅色背景
• 深色页定义：深色面积占比 > 25%

---

第六步：python-pptx创建新页面

6.1 创建shape的标准代码

from pptx import Presentation
from pptx.util import Cm, Pt, Emu
from pptx.enum.text import PP_PARAGRAPH_ALIGNMENT
from pptx.dml.color import RGBColor

# ⚠️ PP_PARAGRAPH_ALIGNMENT 用法：
# PP_PARAGRAPH_ALIGNMENT.LEFT    左对齐
# PP_PARAGRAPH_ALIGNMENT.CENTER  居中
# PP_PARAGRAPH_ALIGNMENT.RIGHT   右对齐
# PP_PARAGRAPH_ALIGNMENT.JUSTIFY 两端对齐
# 不要用 pp.ALIGN_LEFT 等旧写法！

def add_shape(slide, left, top, width, height, fill_color=None):
    """添加矩形shape"""
    shape = slide.shapes.add_shape(
        1,  # MSO_SHAPE.RECTANGLE
        Cm(left), Cm(top), Cm(width), Cm(height)
    )
    shape.line.fill.background()  # 无边框
    
    if fill_color:
        shape.fill.solid()
        shape.fill.fore_color.rgb = RGBColor.from_string(fill_color)
    
    return shape

def add_textbox(slide, left, top, width, height, text, font_name='Noto Sans SC',
                font_size=14, bold=False, color='1F2937', align='left'):
    """添加文本框"""
    txBox = slide.shapes.add_textbox(
        Cm(left), Cm(top), Cm(width), Cm(height)
    )
    tf = txBox.text_frame
    tf.word_wrap = True
    
    p = tf.paragraphs[0]
    p.text = text
    
    # 对齐方式
    align_map = {
        'left': PP_PARAGRAPH_ALIGNMENT.LEFT,
        'center': PP_PARAGRAPH_ALIGNMENT.CENTER,
        'right': PP_PARAGRAPH_ALIGNMENT.RIGHT,
        'justify': PP_PARAGRAPH_ALIGNMENT.JUSTIFY,
    }
    p.alignment = align_map.get(align, PP_PARAGRAPH_ALIGNMENT.LEFT)
    
    run = p.runs[0]
    run.font.name = font_name
    run.font.size = Pt(font_size)
    run.font.bold = bold
    run.font.color.rgb = RGBColor.from_string(color)
    
    # ⚠️ 设置东亚字体（解决中文渲染问题）
    set_ea_font(run, font_name)
    
    return txBox

6.2 中文字体处理方案（必做！）

from scripts.analyze_style import set_ea_font, set_line_spacing, clean_shape

# 每个文字run都必须设置东亚字体
run.font.name = "Noto Sans SC"  # 西文字体
set_ea_font(run, "Noto Sans SC")  # 东亚字体（必做！）

# 显式设置行距
p = tf.paragraphs[0]
set_line_spacing(p, font_size_pt=14, ratio=1.35)

# 创建shape后清理自动样式
shape = add_shape(...)
clean_shape(shape)

⚠️ 踩坑记录：PP_PARAGRAPH_ALIGNMENT 是枚举类，不是模块常量。正确写法是 PP_PARAGRAPH_ALIGNMENT.LEFT，不是 PP_PARAGRAPH_ALIGNMENT.LEFT 从 pptx.enum 直接导入。

---

第七步：替换、排序、残留修复

7.1 sldIdLst操作（⚠️ 最大坑！必须用完全重建法）

python-pptx 的 slide 顺序由 presentation.xml 中的 `` 控制。 不能用 addprevious/addnext 连续操作（索引会变导致顺序错乱）。 唯一可靠方法：清空sldIdLst → 按新顺序append。

from lxml import etree

# ✅ 正确的API（python-pptx没有 prs.presentation.sldIdLst 属性！）
ns = '{http://schemas.openxmlformats.org/presentationml/2006/main}'
sldIdLst = prs.part._element.find(f'{ns}sldIdLst')

# 1. 创建新slide（python-pptx会自动追加到末尾）
for i in range(4):  # 4页新slide
    prs.slides.add_slide(prs.slide_layouts[6])

# 2. 记录当前sldIdLst的所有元素
all_ids = list(sldIdLst)

# 3. 确定新的页面顺序
# 假设：原PPT有63页，新4页在末尾（-4），要替换第2-5页（index 1-4）
new_ids = all_ids[-4:]          # 新页面
keep_ids = [all_ids[0]] + all_ids[5:-4]  # 第1页 + 第6-63页

desired_order = keep_ids[:1] + new_ids + keep_ids[1:]
# 结果：[原1, 新1, 新2, 新3, 新4, 原6, 原7, ..., 原63]

# 4. 完全重建sldIdLst（⚠️ 不要用addprevious/addnext！）
for sid in list(sldIdLst):
    sldIdLst.remove(sid)
for sid in desired_order:
    sldIdLst.append(sid)

# 5. 保存
prs.save(output_path)

⚠️ 常见错误：

• prs.presentation.sldIdLst → API不存在，必须用 prs.part._element.find()
• sldIdLst.insert(idx, elem) → lxml虽然支持，但连续insert索引会变
• 只删除sldId但不删除底层slide part → 文件会膨胀（目前未自动清理）

7.2 模板残留修复

扫描所有页文字，替换模板残留关键词：

RESIDUAL_KEYWORDS = ['OPPO', 'Tony', 'Alen', '逍遥子', '逍遥子班']
REPLACEMENTS = {
    'OPPO': '国药太极',
    'Tony': '导师A',
    'Alen': '导师B',
    '逍遥子班': '领航班',
    '逍遥子': '领航',
}

for slide in prs.slides:
    for shape in slide.shapes:
        if shape.has_text_frame:
            for para in shape.text_frame.paragraphs:
                for run in para.runs:
                    for old, new in REPLACEMENTS.items():
                        if old in run.text:
                            run.text = run.text.replace(old, new)

---

第八步：P0-P3分级质检

8.1 自动验证（脚本）

from scripts.analyze_style import validate_layout

result = validate_layout(
    prs,
    slide_indices=[1, 2, 3, 4],  # 新增/修改的页索引（0-based）
    palette=palette,              # 5色色板
    residual_keywords=['OPPO', 'Tony', 'Alen'],  # 残留关键词
)

print(f"P0通过: {result['passed']}")
for level in ['P0', 'P1', 'P2', 'P3']:
    if result[level]:
        print(f"\n{level}问题:")
        for issue in result[level]:
            print(f"  - {issue}")

8.2 分级标准

---

v4.1 修复/改进清单

v3.1 修复清单（已包含在v4中）

---

文件结构

ppt-style-matcher/
├── SKILL.md                      # 本文件 (v4)
├── scripts/
│   └── analyze_style.py          # 风格分析工具 v4
└── references/
    └── design-patterns.md        # 设计模式参考

analyze_style.py 导出函数