ppt-layout-check — PPT 排版格式自检工具
基于 python-pptx 的自动化 PPT 排版/格式检查。扫描 .pptx 文件，输出结构化检查报告。
只读保证：本工具全程只读取 .pptx，从不修改、不重写、不回存被检查的文件——
报告另行输出到 stdout 或 --output 指定路径。它对源文件是零副作用的。
何时使用
- 刚生成完 .pptx，交付前自查排版问题
- 接手他人 PPT，快速评估格式一致性
- 批量检查多个 PPT 文件的排版质量
- 作为生成技能（PPT 生成类）的下游质检环节，生成后自动跑一轮检查
触发词：PPT 检查、PPT 排版检查、PPT 自检、PPT 体检、幻灯片检查、pptx 格式检查、版式问题
检查维度（10 大类）
| # | 维度 | 检测内容 |
|---|---|---|
| 1 | 画布尺寸 | 是否为标准 16:9 / 4:3 / 16:10，比例是否非标 |
| 2 | 字体一致性 | 同段落/同页字体混用、正文字号跨度、极小字号（< 6pt） |
| 3 | 配色一致性 | 文字颜色分散度、单页颜色数、白底对比度（W3C 对比度算法） |
| 4 | 文本框溢出 | 元素越出画布四边界（左/右/上/下）、文本密度超容量 |
| 5 | 对齐问题 | 左/右边缘对齐偏差、相近元素 top 坐标波动 |
| 6 | 间距一致性 | 段落行距波动（方差） |
| 7 | 母版/版式 | 是否使用母版版式、版式分布 |
| 8 | 图片质量 | 拉伸变形（原生像素比 vs 显示比例）、有效分辨率（dpi）不足、越出画布 |
| 9 | 内容密度 | 单页字数、近乎空页、项目符号层级过多 |
| 10 | 页脚/页码 | 页码位置一致性、页码连续性 |
执行方式
python <skills-dir>/ppt-layout-check/scripts/check-pptx.py "<work-dir>/文件.pptx"
可选参数
| 参数 | 说明 |
|---|---|
--output <path> / -o |
输出到文件；目标以 .json 结尾时自动按 JSON 写，否则按所选格式 |
--json |
终端输出 JSON 格式（默认 Markdown） |
--check <维度> / -c |
只检查指定维度（逗号分隔），如 --check fonts,colors |
--threshold <N> |
对齐偏差阈值（像素），默认 10（≈ 100000 EMU） |
可选维度：canvas, fonts, colors, overflow, alignment, spacing, master, images, density, footer
返回码（便于接入流水线 / CI）
| 码 | 含义 |
|---|---|
0 |
通过 —— 无严重问题，且警告 ≤ 5 |
1 |
需关注 —— 警告 > 5 |
2 |
存在问题 —— 存在严重问题（error） |
3 |
运行失败 —— 文件不存在 / 非 .pptx / 检查维度非法 |
深入检查（重叠/遮挡/命名规范等）
python <skills-dir>/ppt-layout-check/scripts/deep-inspect.py "<work-dir>/文件.pptx"
检测普通扫描漏掉的：文本框重叠、Z-order 遮挡（文字被图片压住）、shape 命名规范、
空占位符、文本框内边距分布、项目符号一致性。同样为只读。
输出示例
# 📋 PPT 排版检查报告：示例演示.pptx
## 📐 基本信息
- 幻灯片数：28
- 画布尺寸：16:9 · 13.3" × 7.5" (12192000 × 6858000 EMU)
- 严重/警告/提示：3 / 7 / 4
- 综合评分：72/100
## 🔴 严重问题（3）
| 页 | 类别 | 问题 | 详情 |
|----|------|------|------|
| 5 | overflow | 元素超出画布下边界 | "项目投资规模..." 超出 0.32 英寸 |
| 12 | fonts | 同一段落混用不同字体 | 含字体: {'微软雅黑', '宋体'} |
| 22 | images | 图片被拉伸变形 | 原始 1920×1080 (比例 1.78)，显示比例 1.33，偏差 25% |
## 🟡 警告（7）
| 页 | 类别 | 问题 | 详情 |
|----|------|------|------|
| 3 | alignment | 元素左边缘未对齐（微差） | 相差 1.2mm |
| 7 | images | 图片有效分辨率偏低 | 显示 5.0"×3.0"，原生 100×60px，有效约 20dpi |
## 🟢 通过的维度
- 📐 canvas：未发现问题
- 🔢 footer：未发现问题
## 📊 综合评分：72/100
与 PPT 生成技能的关系
本工具是生成之后的质检环节，不参与内容生成。若与 PPT 生成类技能配合，
推荐流程为：生成 .pptx → 跑 check-pptx.py → 按报告修排版 → 再跑一轮确认评分与返回码。
本工具不评价内容质量、不修改文字、不做投资/数据核算。
测试
pip install python-pptx pytest
pytest -q
测试全部用 python-pptx 现场构造演示文稿，不依赖任何二进制夹具文件，
因此可随包分发并独立复现。
已知局限
- 对比度检查基于白底假设 —— 深色背景/封面上的浅色文字可能误报
- 文字溢出是估算 —— 基于字符密度公式，非精确像素计算
- 不检查动画/视频/音频 —— 仅静态排版属性
deep-inspect.py的 word_wrap 提示偏噪 —— python-pptx 生成的文本框默认
wrap="none"，会被统一报告；真实 PowerPoint 稿件通常不会
依赖
pip install python-pptx
python-pptx 自身已依赖 Pillow，无需单独安装 pillow。
脚本
| 脚本 | 作用 |
|---|---|
scripts/check-pptx.py |
主检查器：10 维度扫描 → Markdown/JSON 报告 + 评分 + 分级返回码 |
scripts/deep-inspect.py |
深层检查：重叠、Z-order 遮挡、命名规范、空占位符、内边距、项目符号 |
tests/ |
回归测试（27 项，纯文本，无二进制夹具） |
许可与使用限制
本技能为专有软件（Proprietary），版权所有，保留所有权利（All rights reserved）。
允许：按本技能设计用途使用——读取 .pptx 并输出排版检查报告。
禁止（未经作者事先书面许可）：
- 修改、改编、二次开发，或创建任何派生作品；
- 再分发、转售、出租、出借或公开传播本技能或其任何部分；
- 反编译、反汇编或逆向工程；
- 去除、篡改版权与署名信息后重新发布；
- 将本技能整体或部分集成进其他产品或服务。
如需定制、集成或二次开发授权，须取得作者书面许可。
