Wisely Read PPT

解析 PPT(.pptx) 或 PDF 文件（或两者同时提供），逐页生成结构化的 docx 解析文档。每页固定包含：整页截图、可编辑文字整理、插图描述（文字中以行内标记形式嵌入）。当用户需要：把演示文稿或 PDF 转成可编辑的逐页 Word 文档、提取 PPT 内容为文字稿、做 PPT/PDF 的图文解析稿、'逐页解析'、'生成解析文件'、'转 docx'、'PPT 解析'、'PDF 解析'时使用。

PPT / PDF 逐页结构化解析 -> docx

把演示文稿或 PDF 按页拆解，生成一份以文字为主、标记符号系统表达图片位置与内容的 Word 文档。文档能以纯文字形式“说出”每页 PPT 有什么内容，同时嵌入整页截图供核对。

⚠️ 维护提醒：本 skill 的标记符号系统、输出模板在 SKILL.md 和 reference/subagent-workflow.md 中各有一份完整副本。修改任一处时，必须同步更新另一处。

---

处理模式

场景	方式
单文件 ≤10 页	主代理直接完成全部三阶段
单文件 >10 页 或 多文件	spawn 子代理并行处理（每个文件一个），主代理逐个复核

为什么：子代理继承主代理模型，能力相同。小文件直接处理更高效；大文件或多文件时并行才划算。

---

目录结构（相对当前工作区，不写死路径）

text

<当前工作区>/
├── ppt-parse-working/           ← 工作目录（初稿 + 素材）
│   └── <任务名>/
│       ├── 初稿_<文件名>.docx
│       └── 初稿_<文件名>_assets/ ← 脚本提取的素材
└── ppt-parse-final/             ← 复核后成品目录
    └── <文件名>_解析稿.docx

---

环境依赖

PPT 输入必须有 LibreOffice 渲染器，PDF 输入不需要。

快速检测：

bash

which pdftoppm    # PDF 必需
which soffice     # PPT 必需

如果缺 LibreOffice，按系统安装（Ubuntu: apt install libreoffice-core libreoffice-impress poppler-utils，CentOS: dnf install libreoffice poppler-utils）。无 root 权限时，请用户将 PPT 导出为 PDF。

Python 依赖由脚本自动安装，也可手动：

bash

pip install python-pptx pdfplumber pymupdf python-docx Pillow pytesseract

---

输入判定

输入	处理
仅 .pptx	必须有 LibreOffice；渲染截图 + python-pptx 提取文字/图片
仅 .pdf	无需 LibreOffice；pdftoppm/pymupdf 转图 + 文字提取
两者都有	按“来源文件”分节，各自逐页解析

---

主代理工作流程

前置准备

1. 确认模型具备识图能力（通过 read 工具读取本地图片文件识别内容）。如当前模型无法识图，停止并告知用户。
2. 创建工作目录：mkdir -p ppt-parse-working ppt-parse-final

单文件 ≤10 页：直接处理

1. 运行 parse.py 提取素材
2. 逐页 read 整页截图校准文字、read extracted_pics 原图识别信息图
3. 逐页自检复核
4. 保存到 ppt-parse-final/

单文件 >10 页 或 多文件：子代理分工

步骤一：spawn 子代理

对每个文件 spawn 一个子代理：

text

sessions_spawn(
  task="你有一个 PPT/PDF 解析任务，请严格按照 reference 文件中的步骤执行。

【任务信息】
- 任务名：<任务名>
- 输入文件：<绝对路径>
- 输出根目录：<当前工作区绝对路径>/ppt-parse-working
- skill 脚本路径：<skill目录绝对路径>/scripts/parse.py
- reference 手册：<skill目录绝对路径>/reference/subagent-workflow.md

【要求】
1. 先完整阅读 reference 手册
2. 你负责阶段一（脚本提取）+ 阶段二（逐页视觉校准），不做复核
3. 用 read 工具读取本地图片文件进行视觉识别
4. 完成后回报初稿路径和素材目录路径",
  taskName="ppt_parse_<任务名>",
  runtime="subagent",
  context="isolated",
  sandbox="inherit",
  cwd="<当前工作区路径>"
)

多文件时同时 spawn N 个子代理，然后 sessions_yield 等待完成。

步骤二：主代理复核

强制要求：所有初稿必须经复核才能交付。抱着“大概率有遗漏/错误”的纠错心态逐页检查，而不是走过场。

子代理回报后，逐个取出初稿和素材进行复核：

1. read 整页截图，对照文字检查漏字、错字、顺序
2. 核心信息图 read extracted_pics 原图，核对逐字转录
3. 检查图片标记数量与 extracted_text.json 的 images 数组是否一致
4. 检查是否有应作为信息图但只做了简述的情况
5. 检查图文绑定是否正确
6. 特别关注带 <!-- 批注：... --> 的页面
7. 修正后保存到 ppt-parse-final/

交付检查点：如果没有完成全页复核，绝对不能交付文件。

步骤三：交付

确认 ppt-parse-final/ 下文件无误后交付。ppt-parse-working/ 保留作为审计回溯。

---

阶段分工一览

阶段	内容	单文件≤10页	多文件/大文件
阶段一	脚本提取文字、图片、整页截图	主代理	子代理
阶段二	逐页视觉校准：文字重排、图片标记、信息图逐字转录	主代理	子代理
阶段三	全页复核、纠错、终稿输出	主代理自检	主代理复核

脚本提取仅完成 30% 工作量。70% 靠视觉核对 + 复核。绝对不能跑完脚本就交付。

---

标记符号系统

所有标记用 /.../ 包裹。

图片标记

标记	适用场景	要求	示例
/[pic NN：简述]/	辅助配图：logo、照片、报纸/杂志版面、网页截图、弱相关密集文字长图、装饰图	一句话简述，不读小字	/[pic 01：微信logo]/、/[pic 02：每日新报终刊版面]/
/[pic NN]*** ... ***/	核心信息图：图表、流程图、架构图、数据图等	逐字转录所有可见文字	见下方格式

块级标记格式：

text

/[pic 04]***
图表类型：柱状图
标题：2020-2025年中国对外直接投资规模
横轴：年份（2020-2025）
纵轴：投资金额（亿美元）
数据：
- 2020年：1329亿美元
- 2021年：1452亿美元
图例：对外直接投资金额、同比增速
***/

编号规则

• 每页独立编号，按从左上到右下顺序
• 编号数量与脚本 images 数组长度一致
• 无嵌入图片的页面不加任何 /[pic 标记

文字部分

• 无标记文字 = PPT/PDF 可编辑文本（经视觉核对顺序）
• 块级标记内文字 = 视觉识别/OCR 结果
• 整页截图嵌入 docx，放在每页标题下方

---

输出模板

开头注释：

text

<!-- 本文档解析自文件：[文件名]，合计 X 页。
标记说明：
  /[pic NN：简述]/   -> 行内小图（logo/照片/截图）
  /[pic NN]*** ... ***/  -> 块级大图（图表/脑图/流程图，需细读）
  无标记文字 -> PPT/PDF 可编辑文本（经视觉核对顺序）
  每页开头嵌入整页截图供核对 -->

每页结构：

text

page N
【此处插入整页截图】
[文字内容按逻辑顺序排列，图片标记紧贴对应文字]

正确示例

示例一（文本组成的图表，无嵌入图片，全是可编辑形状文字）：

text

page 4
组织架构
A 技术部
研发组 / 测试组 / 运维组
（前端、后端、算法、数据）
B 产品部
产品经理 / 设计师
C 运营部
内容运营 / 用户运营 / 活动运营

示例二（文字为主+logo辅助）：

text

page 6
B. 自媒体及其平台
自媒体舆情监测重点平台
第一梯队 /[pic 01：微信]/ /[pic 02：微博]/ /[pic 03：抖音]/
第二梯队 /[pic 04：快手]/ /[pic 05：B站]/ /[pic 06：小红书]/

错误示例

• 跑完脚本直接交付，没有逐页视觉核对
• 子代理交了初稿就直接交付，没有主代理复核
• 文本组成的图表页加了 /[pic 01] 标记（框图是 PPT 形状不是嵌入图片）
• 把紧挨在一起的名称拆成独立条目（视觉上紧挨在一起的多个名称是对上方的举例，应归为一组，不要拆成独立条目跟分类并列）
• 图文分离（先写完文字再统一列图片说明）
• 核心数据图表只写简述，没有逐字转录
• 小文件还 spawn 子代理（≤10 页直接处理更高效）
• 工作路径写死（必须相对当前工作区）
• 识别困难处不添加批注（应标注 <!-- 批注：... --> 提醒复核）

---

脚本使用

bash

python <skill目录>/scripts/parse.py <input.pptx|input.pdf> [more files...] \
  --out "<输出路径>.docx" --keep

参数	说明
--out	输出 docx 路径（默认：解析结果.docx）
--dpi	截图 DPI（默认 150）
--assets-dir	素材输出目录（默认：输出文件名_assets）
--keep	保留中间临时文件
--no-install	不自动安装 Python 依赖
--allow-no-renderer	允许无 LibreOffice 时继续（仅提取文字和图片，无截图）

脚本输出

• 输出.docx：阶段一 docx（含整页截图 + 原始文字）
• 输出_assets/<源文件名>/extracted_text.json：结构化数据
• 输出_assets/<源文件名>/page_NN.png：每页整页截图
• 输出_assets/<源文件名>/extracted_pics/page_NN_pic_NN.png：提取的内嵌图片