PPT-PRO-MAX v1.2.0：AI排版智能修复 + 兼容输出

⚠️ 开始前请注意

🚀 快速上手（两种方式）

方式一：一键修复（推荐 🆕）

python scripts/run.py 你的文件.pptx
# 自动完成: 解包 → 检测 → 修复 → 验证 → 打包 → 兼容输出

如果电脑没装 Office，跳过兼容输出：

python scripts/run.py 你的文件.pptx --skip-compat

方式二：分步执行

# 1. 解包
python skills/pptx/scripts/office/unpack.py 你的文件.pptx unpacked/

# 2. 检测 + 修复（一步到位）
python scripts/layout_check.py unpacked/ > issues.json
python scripts/auto_fix.py unpacked/ --issues issues.json

# 3. 打包 + 生成兼容版
python skills/pptx/scripts/office/pack.py unpacked/ 输出.pptx
python scripts/compat_output.py 输出.pptx --dpi 150

没有现成文件？生成一个试试

python scripts/demo_generate.py
# 生成 assets/demo.pptx（7页，含各种排版问题，可立刻上手）

📖 完整示例：修复一份工作汇报 PPT

> 假设你有一份 quarterly_report.pptx，在自己电脑的 WPS 中排版正常，
> 但发到领导用 PowerPoint 打开时文字溢出、图表标注错位。

场景

quarterly_report.pptx (10 页)
├── 第1页:  封面 —— "2026年Q1部门工作汇报"（40pt，安全）
├── 第2页:  目录 —— "业绩回顾 / 重点项目 / 问题与对策 / 下季度计划"
├── 第3-5页: 业绩数据 —— 正文 14pt，文字框偏窄，PowerPoint 中溢出
├── 第6页:   项目详情 —— 图表标注距左边缘 0.15 英寸（低于 0.5 英寸安全边距）
├── 第7页:   问题分析 —— 多段落文字框高度不足，PowerPoint 中截断
├── 第8-9页: 计划与展望 —— 排版正常
└── 第10页:  结束页 —— 正常

🔧 一键修复

$ python scripts/run.py quarterly_report.pptx --dpi 150

输出过程：

========================================================
  PPT-PRO-MAX v1.2.0 一键修复流程
  文件: quarterly_report.pptx
========================================================

  第1步 解包 PPTX... ✅
  第2步 检测排版问题... ✅
    发现 6 个问题，涉及 5 页幻灯片
  第3步 自动修复... ✅
    修改 6 处，0 处需手动处理（修复率 100%）
  第4步 验证修复效果... ✅ (无残留问题)
  第5步 打包修复文件... ✅
    输出: quarterly_report_fixed.pptx

  第6步 生成兼容版... ✅
    兼容版: quarterly_report_fixed_compat.pptx

========================================================
  🎉 修复完成！
  可编辑版: quarterly_report_fixed.pptx
  兼容版:   quarterly_report_fixed_compat.pptx  ← 在任何软件打开排版都不乱
========================================================

搞定。把 quarterly_report_fixed.pptx 发给同事编辑，把 _compat.pptx 发给领导演示——排版永远不会乱。

📋 参考：分步命令一览

详细流程指南

Step 1: Create or Edit PPT

使用内置 pptx skill：
- 从零创建（推荐）：pptxgenjs Node.js 库
- 基于模板：解包 → 编辑 XML → 打包
- 编辑已有：解包 → 编辑 XML → 打包

⚠️ pptxgenjs v4 注意：
- 形状名用字符串："rect", "ellipse", "roundRect" — 不要用 pres.ShapeType.xxx
- pres.addSlide() 返回 Slide 对象，不是 presentation
- 默认布局 LAYOUT_16x9 (10" × 5.625")
- 中文字体用 "Microsoft YaHei"

Step 2: Layout Check

python scripts/layout_check.py unpacked/

检测结果：

• 标题栏内元素自动跳过边距检查
• 标题+副标题自然堆叠不会被误报为重叠

Step 3: Auto Fix

python scripts/auto_fix.py unpacked/ --issues issues.json

修复策略：

> 📌 修复前会输出预检报告，展示可修复/不可修复数量和预估修复率。

Step 4: Pack

python skills/pptx/scripts/office/pack.py unpacked/ 输出.pptx --original 原文件.pptx

--original 保留未修改内容，自动验证修复。

Step 5: Compat Output

python scripts/compat_output.py 输出.pptx --dpi 150

引擎检测（WPS 和 MS Office 平等对待）：
1. WPS 演示 — 中国大陆电脑最常见
2. Microsoft PowerPoint — 广泛使用
3. LibreOffice — 免费开源最后备选

原理：每页通过 COM 导出为高清图片 → 组装为图片化 PPTX → 任何软件打开效果完全一致。

设计指南

字号建议

文本框安全

中文字符宽度约为拉丁字符 2 倍，混合编排留 15-20% 余量：

所需宽度 ≈ (中文字数 + 拉丁字数 × 0.55) × 字号pt × 12700 EMU

跨软件兼容

• 避免 SmartArt（WPS/PowerPoint 渲染不一致）
• 尽量嵌入字体
• 用标准 16:9 (12192000 × 6858000 EMU)
• 避免半透明叠加
• 兼容输出是终极保障

🔍 常见问题与避坑指南

> 按问题分类编排。使用 Ctrl+F 搜索关键词快速定位。

索引

Q1 · 兼容输出提示"没有检测到 Office"

原因：电脑没有安装 WPS 或 Microsoft PowerPoint。

解决：

• 安装 WPS（免费）：访问 https://www.wps.cn 下载个人免费版
• 安装 Office：通过 Microsoft 365 订阅或购买
• 备选方案：安装免费 LibreOffice https://www.libreoffice.org

不需要兼容输出？ 跳过即可——布局检测和修复功能不需要 Office，只影响"在所有软件打开都不乱"的兼容版功能。

Q2 · 自动修复报"无法读取问题文件"

原因：Windows 上直接用 > 重定向保存的问题文件可能是 UTF-16 编码，而不是 JSON 标准 UTF-8。

解决（三选一）：

✅ 推荐：使用 run.py，一切自动处理

python scripts/run.py 文件.pptx

✅ 手动方法：保存为 UTF-8

python -c "import sys,json; json.dump(json.load(sys.stdin), open('issues.json','w',encoding='utf-8'), ensure_ascii=False, indent=2)" < 输入 > issues.json

✅ 管道传递（用 Python 而非 PowerShell 管道）：

import subprocess, json
r = subprocess.run(['python', 'layout_check.py', 'unpacked/'],
                   capture_output=True, text=True, encoding='utf-8')
issues = json.loads(r.stdout)

Q3 · PowerShell 管道连接报编码错误

原因：PowerShell 的 | 会用 UTF-16 改写文本流。

解决：

✅ 用 --issues 参数 + 中间文件（不用管道）
✅ 或直接用 run.py 一键执行，它内部处理了所有编码问题

Q4 · 有些溢出显示"无法自动修复"怎么办？

原因：溢出率超过 300%，缩小字号到最低 6pt 仍然溢出。

解决：
1. 缩减文字：演示文稿中一页不宜放太多字，精简到核心要点
2. 拆分页面：把内容拆分到多页，每页讲一个重点
3. 扩大文本框：调整布局让文本框占更多空间
4. 改用列表/图表：用可视化方式代替大段文字

Q5 · 自动修复后字号变得太小

原因：原文本框太窄，只能不停缩小字号才能避免溢出。最低会降到 6pt。

解决：
- 如果需要更小字号 → 手动在 WPS/PowerPoint 中调整（不推荐，低于 6pt 阅读困难）
- 更好的做法 → 扩大文本框宽度，或精简文字内容
- 用 --dry-run 先预览效果再做决定

Q6 · 打包后 PPTX 文件比原文件小很多

原因：pack.py 压缩 XML 比 pptxgenjs 更激进。

这是正常的，不表示数据丢失。验证方法：检查页数和内容是否一致。

Q7 · 修复后标题被移出了标题栏区域

v1.2.0 已自动处理：auto_fix 会检测幻灯片顶部的标题装饰条，跳过其中元素的边距修正。

如果仍有问题，可能标题栏未被识别——在 WPS/PowerPoint 中手动拖回即可。

Q8 · pptxgenjs 报 "addShape is not a function"

原因：pptxgenjs v4 的 API 变了。

解决：
- ❌ pres.ShapeType.rect → ✅ "rect"
- ❌ pres.ShapeType.ellipse → ✅ "ellipse"
- ❌ pres.ShapeType.roundRect → ✅ "roundRect"

文件结构

ppt-pro/
├── SKILL.md                     # 本文档
├── scripts/
│   ├── run.py                   # 🆕 一键执行脚本
│   ├── layout_check.py          # 布局问题检测引擎
│   ├── auto_fix.py              # 自动修复引擎
│   ├── compat_output.py         # 兼容输出引擎
│   └── demo_generate.py         # 演示文件生成器
└── assets/
    └── demo.pptx                # 预生成的演示文件

依赖说明