ppt-style-matcher

v4.1: 全局色板提取+智能采样颜色多样性+P0-P3验证+深色适配+sldIdLst重建法

PPT风格匹配技能 v4.1

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

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

---

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

#	规则	说明
R1	颜色锁定	只允许使用从原PPT提取的5色+2文字色，禁止编造hex
R2	字体锁定	三级分工（标题/正文/注释），禁止换字体
R3	布局计算先行	禁止凭感觉填坐标，所有位置必须从公式计算
R4	只用形状+文本	禁止外部图片、禁止pptxgenjs（它会丢中文和关系）
R5	间距保护	分栏间距0.6-1.0cm，内容距底≥0.15cm
R6	每页≥20个shape	低于此数为简单文本页，需重设计
R7	验证读回	生成完毕必须用python-pptx读回+validate_layout()检查

---

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

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

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

---

第二步：风格分析

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

bash

python3 scripts/analyze_style.py <ppt路径> [--verbose]

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

2.1 5色锁定色板

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

text

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）

---

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

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

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

python

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

双栏布局公式

python

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

三栏布局公式

python

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)]

卡片内部结构

python

# 左装饰条
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的标准代码

python

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 中文字体处理方案（必做！）

python

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 中的 <p:sldIdLst> 控制。 不能用 addprevious/addnext 连续操作（索引会变导致顺序错乱）。 唯一可靠方法：清空sldIdLst → 按新顺序append。

python

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 模板残留修复

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

python

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 自动验证（脚本）

python

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 分级标准

级别	类型	检查项	不通过后果
P0	阻断级	越界/图片shape/shape<20/残留关键词	不交付
P1	功能级	颜色一致性/底部留白/文字溢出	需修复
P2	品质级	间距均匀/对齐/标题统一	建议修复
P3	润色级	节奏感/信息密度/装饰元素	可选

---

v4.1 修复/改进清单

问题	修复	影响
智能采样只看shape数量，选出的页颜色偏红	新增颜色多样性加分+贪心算法确保颜色覆盖	色板无偏差
色板提取只用采样页频率（采样偏差）	PRIMARY等核心角色改用全局颜色频率	色板准确
validate_color_usage缩进bug（只检查最后一个slide）	for循环体修正缩进	P1颜色验证生效
SKILL.md sldIdLst API过时	改为完全重建法 + prs.part._element.find()	代码可运行
深色PPT TEXT色被识别为强调色	检测深色主题后TEXT优先选浅色	色板正确
SECONDARY/ACCENT角色倒挂	SECONDARY优先中性色，ACCENT优先高饱和色	角色语义正确
默认采样4页中3页是简单页	智能采样：优先shape≥20的设计良好页+颜色多样性	色板质量提升
简单页布局参数误导	shape<10标记为简单页，清空布局参数	避免误导
浅色PPT报"连续37页浅色=视觉疲劳"	浅色PPT切换为结构节奏检测	不误报
缺少参考页推荐	analyze_ppt自动输出参考页	免手动选择
validate_layout坐标计算bug	改为Emu(left + width)	越界检测准确
design-patterns.md缺sldIdLst操作指南	新增第十节：清空+按序重建法	最少踩坑

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

问题	修复	影响
全屏背景色块被误判为"顶部装饰条"	新增 _is_fullscreen_shape() 过滤	布局参数准确
节奏感警告重复	滑动窗口找最长连续区间	输出简洁
5色色板PRIMARY和TEXT重复	区分填充色和文字色角色	色板可用
ACCENT提取到极浅色	bg_colors排除 + 亮度>240跳过	强调色有意义
字体三级分工只有1个字体	按字号范围推断三级	信息完整
底部装饰条全部0.0	降低检测阈值	可检测到
validate_layout不存在	新增完整函数	可用
PP_PARAGRAPH_ALIGNMENT用法未说明	新增代码模板	避免枚举错误
shape位置为None时崩溃	统一过滤None位置shape	稳定

---

文件结构

text

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

analyze_style.py 导出函数

函数	用途
analyze_ppt(path, pages, verbose)	完整风格分析（入口函数，含参考页推荐）
extract_color_palette(prs, pages)	5色锁定色板提取（v4：深色适配+角色修正）
analyze_layout_ratios(slide, prs)	单页布局比例参数（v4：简单页跳过）
analyze_rhythm(prs, pages)	节奏感检测（v4：浅色PPT结构节奏）
validate_color_usage(prs, palette, indices)	颜色一致性验证（v4：修复缩进bug）
validate_layout(prs, indices, palette, keywords)	P0-P3分级质检
_is_dark_ppt(prs, pages)	判断深色主题
_pick_best_sample_pages(prs, count)	智能采样（优先设计良好页）
set_ea_font(run, font_name)	设置东亚字体（辅助）
set_line_spacing(paragraph, pt, ratio)	设置行距（辅助）
clean_shape(shape)	清理自动样式（辅助）