Ray PPT Refine — PPT 排版美化器（验收 + 改造）

> 定位：对已有 PPTX 做排版美化——检测排版问题、批量修复、一键换肤。只动排版，不动内容。与 ray-ppt-generator 正交互补（详见文末「与 ray-ppt-generator 的关系」表）。

四条铁律（先于一切流程）

1. 只动排版，不动内容结构。能改的：字体、字号、颜色、配色、对齐、间距、缩进、元素位置、版式布局。不能改的：页数、标题文字、观点、正文内容、逻辑顺序——那是内容，归作者/generator 管。
2. 失同步必提示，不另造演讲稿。若美化必须改动结构（拆页/合并页/改标题），先停下警告："这会破坏演讲稿/备注的逐页同步"，用户确认后才动；演讲稿由 generator 单源产出，本 skill 不生成演讲稿。
3. 视觉 QA 驱动，不信代码信图片。代码证明"结构存在"，不证明"版式舒服"——先转图片逐页看诊断，修复后再转图片复验，至少一轮 fix-and-verify。
4. 主要文字必须可编辑（v2.1.0 新增）。美化后交付的 PPTX 必须保持：主标题/副标题/正文/关键数字/图表标签/页脚说明都在 PPT 原生文本框里，可被用户直接编辑；不得把文本转图片、不得把整页合成为一张图、不得为了"视觉效果"牺牲可编辑性。装饰性图形（logo、复杂插画、照片背景）可以是图片，但信息层必须是文本。判定红线：pictures=0 不是目标，但 text_as_picture > 0 就是失败。

常见崩坏模式（每次 refine 前必读，先于 5 步流程）

> 告诉 AI 要做什么效果一般，告诉它前人最容易在哪里塌效果更好。以下三种反模式均在真实执行中复现过，每次必须主动警惕。

反模式 1：口头宣布"美化完成"（最常见）

错误做法：
> 「4 页样张已完成美化，配色统一、字体一致，可以批量化了」（没跑任何脚本，没转任何图）

问题所在：判断"美化完成"的依据是 AI 自己的观感，不是程序输出、也不是 VL 核验。无论理由多充分，这句话都是 AI 在给自己写完成证书。

正确做法：
1. 执行 python scripts/refine_gate_check.py <refine后pptx路径> <诊断json>
2. 读取 <工作目录>/refine_gate_result.json
3. 只有 "passed": true 时才能进入批量修复 / 交付
4. 如果 "passed": false，按 user_code_errors[] 修复后重跑

> 视觉核验先试原生 Read：导出的 PNG 先直接 Read 一张——2026-09 起主流模型普遍原生多模态（deepseek-flash-V4.1、glm-flash-5.3 等），能看就直接看（更快、更省、细节不丢）。只有 Read 报读不了图时，才走 ray-ppt-ocr-eyes 降级链路（OCR+VL 逐页描述），见 references/refine-toolkit.md 第 2 节末尾——链路存在 ≠ 可以跳过，"模型看不了图"不是跳过视觉 QA 的理由。

反模式 2：跳过样张直接批量改 100 页

错误做法：
> 拿到 95 页 PPT，直接对每个页面跑统一字号缩放 + 统一字体替换，跑完才发现页脚被放大 / 卡片页被撑爆 / 表格列宽重排。

问题所在：每条规则都有边界（页脚白名单、卡片页排除、表格只换字体），这些边界要在样张上验证，不能在全量上裸跑。

正确做法：
1. 先选 3-5 页代表性样张（封面/章节页/典型内容页/表格页/卡片页各一），跑完整 refine 流水线
2. 对样张转图 VL 核验 + 跑 refine_gate_check.py，全部通过才进入批量
3. 批量时分页类型排除不适用规则（见「四条铁律」第 4 条 + 常见坑表）

反模式 3：默认"既然是美化就该全换"，不先问体系

错误做法：
> 用户说"美化一下"，直接做 2 轮样张（纸张手绘风→照片灰度化），用户看完才说"化工蓝体系更清爽，保留现有体系只补图"。

问题所在：「美化」是个有歧义的词——可能是「换配色体系」「换版式体系」「保留体系补手法（线语言/插图/留白）」三种之一。AI 默认第一种，用户往往想要后两种，导致 N 轮返工。

正确做法：
1. Step 3 诊断确认前必问：「换体系 or 保留现有体系补手法？」
2. 换体系 → 走「一键换肤」（6 套通用 + 化工安全配色）
3. 保留体系补手法 → 走 design-languages/INDEX.md 三因子匹配（差距 0.5 + 内容 0.3 + 偏好 0.2）从 8 类设计语言里选补充手法
4. 用户明确说"看着办"再走推荐路径，并明示推荐理由给用户否决权

何时用 / 何时不用

工作流程（5 步）

备份 → 视觉QA检测 → 诊断清单（用户确认）→ 批量修复 → 复验交付

Step 0：备份（强制）

改任何已有 PPTX 前，先复制备份：<原名>_backup.pptx。Win32COM 修改不可逆，备份是后悔药。

Step 1：读取解析 + 模式选择（沿用模板 vs 重新设计）

用 python-pptx 打开，遍历 slides/shapes/text_frames，摸清结构：页数、每页元素、字体分布、颜色分布。代码见 references/refine-toolkit.md 第 1 节。

量化诊断阈值（v2.1.0，2026-08-20 新增）——Step 3 诊断确认时按阈值自动判定，不再依赖描述性语言：

# 量化诊断示例（Step 3 确认前跑）
fonts = Counter()  # 所有 run 的字体
font_colors = Counter()  # 所有可见 shape 的填充色
body_sizes = Counter()  # 正文字号（排除页脚白名单）
for slide in prs.slides:
    for shape in slide.shapes:
        # ... 统计逻辑

top1_font_ratio = fonts.most_common(1)[0][1] / sum(fonts.values()) if fonts else 0
if top1_font_ratio < 0.70:
    diagnostics["font_consistency"] = {"status": "fail", "top1_ratio": top1_font_ratio}

阈值细节见 references/refine-matrix.yaml。

模式选择（必做，美化的第一个决策）——问用户：

> 拿不准时默认"沿用模板"——保守改造，不动全局元素。用户明确要换风格才走"重新设计"。

设计语言匹配（v2.0 新增，选"重新设计"时必做）——读 references/design-languages/INDEX.md，按三因子加权（差距 0.5 + 内容 0.3 + 偏好 0.2）推荐 2-3 套设计语言让用户选：

1. 提取目标 deck 版式特征（标题栏样式/列表页占比/卡片存在性/章节页样式/插图风格）
2. 与 design-languages/ 各档案的「特征指纹」比对 → 差距越大改造价值越高
3. 内容类型匹配（培训课件→B卡片徽章/A手绘线；技术汇报→C大数字/D深色科技；公文→E政务；事故→A时间线）
4. 用户偏好修正（"化工蓝体系更清爽"→偏好保留体系补手法；历史选过 +10 分）
5. AskUserQuestion 推荐 2-3 套让用户选（铁律：用户说"美化"≠要换体系，先问）

选定后：读该语言 profile.md（特征/改造路径）+ 看 layouts/*.png 样板 + 用 palette.json 配色 token + 复用 assets/ 素材。

Step 2：视觉 QA 检测（核心）

用 export_slides_to_images() 把每页导出 PNG，逐页看——不要只信解析数据。同时跑排版扫描器自动初筛。产出"问题清单"。检测维度见下「诊断模式库」。

Step 3：诊断清单 → 用户确认改造方案

把检测到的问题整理成清单，按优先级排列，给用户确认改造范围再动手：

发现 N 处排版问题：
🔴 严重：3 页文字溢出（P3/P7/P12）、全 deck 字体不统一（宋体混入）
🟡 建议：配色默认蓝无主题、5 页元素未对齐
🟢 可选：标题层级可再拉开
改造方案：①统一微软雅黑 ②应用[商务深蓝]配色 ③修复溢出页 ... 确认？

杠杆收敛（v2.2.0 新增，外部对比吸收）：诊断清单可能列出 10+ 项，但汇报只挑 3-5 个最大改造杠杆（对观感提升贡献最大的项），其余归入"次要项（可后补）"一句话带过。原因：清单过长会分散用户注意力、拖延确认；多数时候 3-5 个杠杆改完 deck 已质变，次要项用户会主动要求补。判断口诀："改完这 3-5 项，用户会明显觉得'好多了'吗？" 不会 → 杠杆没选对。

Step 4：代表性页面预览 → 批量修复

先做样张再批量（降低返工）：不一次性改全部——先改 3-5 页不同类型的代表页（文字信息页 / 数据图表页 / 结论汇总页），转图给用户预览，确认风格对味后，再用 Win32COM 批量执行剩余页（保留渐变/阴影等效果，python-pptx 重排会丢效果）。修复方法见 references/refine-toolkit.md 第 3-5 节。

Step 5：复验交付（⭐ 机读化门禁，v2.1.0）

> 核心原则：门禁必须机读化（学 Mck gate_check），AI 不得口头宣布"QA 通过"。

1. 先跑门禁脚本（必须，不得跳过）：

python ~/.workbuddy/skills/ray-ppt-refine/scripts/refine_gate_check.py \
    <refine后pptx路径> <诊断清单.json> --outdir <工作目录>

2. 读取 <工作目录>/refine_gate_result.json：
   - "passed": true → 进入转图复验
   - "passed": false → 修复 user_code_errors[] 列出的问题，重跑门禁
3. 转图 VL 核验（门禁覆盖不到的视觉层面：色感/留白感/设计感）
   - 重跑 Step 1 的 export_slides_to_images() 导出受影响页，逐页复验——一个修复常引入新问题
   - 重点看：样张一致性、新字体渲染效果、配图协调性、档位/卡片/警示条风格统一
4. 门禁 + VL 全绿才交付；回 Step 4 再修一轮（最多 2 轮，2 轮仍有问题说明要拆方案 B 重写脚本）

排版问题诊断模式库

> 判断口诀：先严重后建议——溢出/字体/配色是硬伤，对齐/层级/痕迹是提升，线/图是质感。

设计哲学：AI slop 反模式警告（v1.4 新增，吸收 GH 27k 星 frontend-slides）

> 模型默认会收敛到平庸的通配设计（"AI slop"审美）——美化前先认通病，再给对策：

自检："这页删掉任何一个元素会变差吗？" 不会 → 删掉（减优于加）。

视觉语言参考（v2.0 起指向设计语言资产库）

> 完整资产库：references/design-languages/INDEX.md（8 类分类索引 + 自动匹配规则）+ 每类 profile.md（特征指纹/配色/改造路径）+ layouts/ 样板图 + palette.json 配色 token。
> 下方表格是已归档语言的快速速查；完整档案看对应文件夹。

A 手绘线语言速查（RBPS 意识培训 90页）

B 卡片+徽章速查（General EHS Onboarding 23页）

> 完整档案（改造路径/素材/经验引用）：已外置归档 D:/RayClaw/skill-archives/ray-ppt-refine-B-card-badge-20260828/（含 profile.md），需要时按路径取用

配图落地三坑（v1.3 新增，实战验证 2026-08-17）

> 给已有 deck 配图（灰度照片/插图）时的高频坑与解法：

配图决策链：先扫描空白（右半区→网格→精确小区域逐层收敛）→ 有空白直接配 → 无空白不要强行塞图（会遮内容）→ 改用布局让位（公共函数收窄文字宽，批量让出侧边栏）→ 让位后仍验证插图与相邻元素。

图片来源决策（v1.5 新增，2026-08-18 三图库实测）

> 配图素材从哪来？按「通用主题 vs 专业主题」分流，下载图必须 VL 核验。

决策规则：
1. 通用主题（PPE/消防/警示/高处）→ 优先下载图（免费），逐张 VL 核验再入映射
2. 专业主题（特殊作业/中毒救援/危化品工艺）→ ImageGen 生成（语义可控）
3. 无论哪条路，绝不按文件标题猜主题（P9 错配教训：按 "construction worker" 想当然标高处，实为货仓工人）
4. 风格统一优先：下载照片是彩色实拍，与灰度扁平插画混搭会破坏统一 → 混用时统一灰度化（PIL 灰度）

一键换肤（配色方案库）

> 换肤前先确认意图（v1.4.1 新增，2026-08-17 实战教训）：用户说"美化/换肤"不等于要换配色体系——可能只想保留现有体系补手法（线语言/插图/留白）。动手做样张前先问一句："换体系 or 保留现有体系只补手法？"（本次实战：连续做了 2 轮样张——纸张手绘风→照片灰度化，用户才说"化工蓝体系更清爽"，若先问可省 2 轮样张）

检测到"配色混乱/默认蓝/无主题"时，推荐换肤。内置 6 套通用 + 化工安全配色（RGB 见 references/refine-toolkit.md 第 4 节）。按场景推荐 2-3 套让用户选：

换肤 = 批量替换主色/辅色/强调色 + 标题栏/页脚配色，不动内容文字。

常见坑与排查

卡片图标徽章 + 通栏警示条（v1.5.4 新增，Plan C 实战）

图标徽章（E7）：给卡片加 1:1 方形照片徽章，形成"徽章+标题+描述"卡片语言。
- 零外部资源：用现有灰度写实方形图（1024×1024）直接缩略即可；白底圆角衬垫 0.61" + 照片 0.55"（衬垫外扩 0.03"）
- 布局避让：有徽章时标题右移（x=徽章右+0.15"）、描述下移（y+0.72"）；无图标时回退原位（标题 x+0.35"、描述 y+0.62"）
- 注入方式：cards() 加 icons=[...] 参数（路径列表与 items 等长）；映射表单独存 JSON（页→每卡图标 key），脚本读取注入
- 同池冲突红线：徽章图标池与右侧竖图（PAGE_ILLU）共用资产时，同页必出现"大图+同图小徽章"——右侧竖图自动替换（不在本页 icons + 不与前后页大图重复 + 语义分组优先）

通栏警示条（E8）：关键警示页加全宽色条（白字加粗居中），比普通文字醒目。
- banner() 双位置：pos='bottom'（y=6.45 高 0.4）用于底部有空间页；pos='top'（y=1.18 高 0.3）用于内容满页（先量内容区底边，防重叠）
- 配色遵循功能分色：RED=警示、ORANGE=注意

反例黑名单（❌ 不要做）

❌ 改内容——页数/标题/观点/正文文字（那是内容，归作者 / generator）
❌ 用 python-pptx 重写排版——会丢渐变/阴影效果，改用 Win32COM
❌ 不备份就改——Win32COM 不可逆，先 _backup.pptx
❌ 只信扫描器不看图——数据给线索、图片给真相，修复后必须转图复验
❌ 改结构不警告——动了页数/标题却不提示演讲稿失同步

与 ray-ppt-generator 的关系

独立演进：本 skill 聚焦"最强版式美化器"（检测 / 换肤 / 修复）；generator 聚焦"最强内容生成器"。经验由 ray-self-reflection 回流，高手由 ray-skill-evolve 学习。

实战经验

> 经验已按主题分类到 references/experiences/（overflow / layout-pitfalls / image-assets / template-skin），含 Problem/Root Cause/Fix/Rule 四字段结构化格式。
> 本区只保留最近 3 条（滚动窗口）+ 待回流的 pending 条目索引。完整历史见 references/experiences/README.md。

最近 3 条（滚动窗口）

• 2026-09-04｜[LRN-20260904-002]｜场景：对照拆解用户自做美化版（豆包 AI 生成 deck vs python-pptx 原版，21 页逐 shape 量化对比）｜经验：①"看不见的结构"才是观感差距主因——20pt 设计网格命中率 73% vs 4%（模板已回 generator 2.22）、序列同色相明度递进 vs 五色相乱跳（generator 2.23）、文字覆盖层解耦（generator 2.24）；②外部 AI 生成 deck 指纹识别：内嵌"XX AI 生成"角标 PNG（zipfile 翻 media/ 一眼定位）、Noto Sans SC 字体、全 AUTO_SHAPE 文字覆盖层结构（底层 roundRect 底色+上层透明 rect 文字）、Tailwind Slate 灰阶（#334155/#94A3B8/#E2E8F0）——对比分析第一步先验指纹，判断对手是"人手改"还是"AI 工具生成"；③对比分析方法论：dump 两版全部 shape（类型/坐标/字体/字号/颜色/文本）→ 全局统计（字体占比/字号阶梯/色板 census/网格命中率）→ 代表页逐 shape 对照；量化数据比"感觉更整齐"有说服力；④内容层确认：好版本真做减法（P13 字数 -30%、P17 -52%）+ 正向补强（"上报不追责"激励、"如有疑问联系安全科"出口）——印证诊断库"重排不减密"行｜死路：肉眼对比只说出"换了字体/换了颜色"表层差异，漏掉网格系统这类结构性差异｜来源：事故制度 deck 用户美化版拆解｜计数：1｜状态：resolved
• 2026-09-04｜[LRN-20260904-001]｜场景：PPT 高手建议落地重做（事故制度 deck 21 页 v2）｜经验：①6 个版式手法验证有效（时限时间轴/卡片矩阵/红绿灯/热力图表格/地铁图/阶梯），已升格为 generator code-templates 2.16-2.21，refine 侧入诊断库"版式单调"行的修复指向；②三条反面教训入诊断库：图形隐喻半成品（环形无箭头=散点）/ 配色邻近色切换用户无感（#005293→#0D3B66 第一眼无变化）/ 重排不减密（新形状装旧内容="换汤不换药"，用户"效果一般"的根因）；③QA 链路实战确认：越界+重叠+文本流三脚本全绿 → COM 导 PNG 逐页目检，6 轮 fix-and-verify 收敛；踩坑：Inches() 收到裸 float 产生天文坐标（Emu 减法必须先转 in 再算）、heredoc 批量 replace 吞行（补丁后 grep 复核递增行）｜死路：倒置金字塔用旋转 180° 三角形+叠加文字（文字溢出斜边落白底）；改用宽度递减圆角条（文字框内永安全）｜来源：事故管理制度宣贯 PPT v2 美化轮｜计数：1｜状态：resolved
• 2026-08-27｜[LRN-20260828-001]｜场景：无多模态模型的视觉 QA 断头｜根因：refine 全流程（铁律 3/反模式 1/Step 2/5）假设"导出 PNG 后模型能看图"，DeepSeek 纯文本模型直接 Read PNG 报"不支持读图"，视觉 QA 链路断头｜Fix：toolkit 第 2 节补降级链路——COM 导 PNG（附 PowerShell 原生 COM 备选 + 首次调用无输出陷阱）→ ray-ppt-ocr-eyes（OCR+VL 双层，opencode-go）逐页核验；路径必须 Windows 格式（Git Bash /e/ 不认）；左右分栏页 OCR 合并行是假象，布局判断以 VL 层为准。已在 generator v3.14.0 的 extend-deck.md 同步沉淀（23 页新增页逐页验证通过）｜死路：只跑越界/重叠几何检测就交付（LRN-20260818-001 已证明几何检测会假通过）｜来源：马来西亚 EHS 课件 47 页扩充｜计数：1｜状态：resolved（⚠️ 2026-09-12 补记：本条前提已变——原生多模态已成主流模型常态，Read PNG 通常直接可用；本条降级链路改为「读不了图时」启用，判定以实测为准）
• 2026-08-19｜[LRN-20260819-008]｜场景：95页英文 deck 套用公司中文模板｜经验：模板套用 ≠ 硬套模板文件——提取 DNA 重绘。只读解析模板（clrScheme + shape 明细 + OCR）提取 DNA（品牌色/Logo/标语/版式语言），关键页重绘（封面/章节/结束），内容页只嵌品牌元素。QA 用"Logo 页数=82/96"验证注入正确｜死路：直接以模板文件为基础修改（中文残留+结构丢失）｜状态：pending

pending 条目索引（待回流主流程）

• references/experiences/overflow.md：LRN-20260817-003（重叠检测行高估算）
• references/experiences/layout-pitfalls.md：LRN-20260817-002（自产 deck 改源）/ LRN-20260819-003（高手版六语言）/ LRN-20260819-007（资源自检）/ LRN-20260819-008（DNA 重绘）/ LRN-20260904-001（图形隐喻纪律+Emu 减法坑，已入诊断库可毕业）
• references/experiences/image-assets.md：LRN-20260818-001（行高估算器）/ LRN-20260818-002（图库规模）/ LRN-20260818-003（VL 判定）/ LRN-20260819-002（页面级 VL 核验）

完整 LRN 列表（含 Problem/Root Cause/Fix/Rule 结构化字段）见 references/experiences/*.md。

参考资料

• references/refine-toolkit.md — PPTX 读取解析、排版扫描器、Win32COM 批量修复、配色方案库、转图片 QA（按需加载，复制即用）

维护记录（最近 3 条）