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

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

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

处理模式

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

目录结构(相对当前工作区,不写死路径)

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

环境依赖

PDF 输入只需 poppler（pdftoppm），无需渲染器。PPT 输入需要渲染器把 PPTX 转为 PDF，按以下流程检测和配置。

PPT 渲染器检测流程

检测结果记录到 local-env.json（见「本地环境配置」章节），下次直接读取配置跳过检测。

阶段 1：检测已有渲染器

Windows：

1. 检测 WPS（pywin32 + COM Kwpp.Application）+ 有头环境 -> COM 转换 PPTX 为 PDF，结束
2. 检测 LibreOffice（soffice）-> 无头转换，结束
3. 都没有 -> 进入阶段 2

Linux：

1. 检测 LibreOffice（which soffice）-> 无头转换，结束
2. 没有 LibreOffice -> 进入阶段 2（不管是否已有 WPS，都优先安装 LibreOffice）

Mac / 其他：

1. 检测 LibreOffice（which soffice）-> 无头转换，结束
2. 没有 -> 进入阶段 2

阶段 2：自动安装 LibreOffice

# Ubuntu / Debian
apt install libreoffice-core libreoffice-impress poppler-utils
# CentOS / RHEL
dnf install libreoffice poppler-utils
# macOS（方案 A：Homebrew）
brew install --cask libreoffice
brew install poppler  # 可选，缺失时 fallback 到 pymupdf

macOS 无 Homebrew 或 sudo 被拒时，使用无 sudo 方案（详见 reference/macos-install.md）：

# 简要步骤（完整指南见 reference/macos-install.md）
curl -L -o ~/Downloads/LibreOffice.dmg <官方下载链接>  # 按 CPU 架构选择
hdiutil attach ~/Downloads/LibreOffice.dmg -nobrowse
cp -R "/Volumes/LibreOffice/LibreOffice.app" ~/Applications/
ln -sf ~/Applications/LibreOffice.app/Contents/MacOS/soffice ~/.local/bin/soffice

macOS 安装后 soffice 可能不在 PATH 中，需软链接到 ~/.local/bin 或 /usr/local/bin。详见 reference/macos-install.md。

• 安装成功 -> 记录配置，无头转换，结束
• 安装失败 -> 进入阶段 3

阶段 3：WPS 兜底（仅 Linux）

pywpsrpc 需要 WPS Office for Linux 11.1.0.9080+ 和有头环境（X 桌面），无头环境跳过。

• Linux + 有 WPS（which wpp 或 which wps）+ 有头环境 -> pip install pywpsrpc，RPC 转换 PPTX 为 PDF
  • 转换失败 / pywpsrpc 安装失败 -> 进入阶段 4
• Linux + 无 WPS / 无头环境 -> 进入阶段 4
• Windows / Mac -> 进入阶段 4

阶段 4：用户问询

• 有头环境 -> 问用户能否安装 WPS，或直接提供 PDF 版本
  • 用户同意安装 WPS -> 安装后回到阶段 1（Windows）或阶段 3（Linux）
  • 用户拒绝 -> 请用户提供 PDF
• 无头环境 -> 请用户提供 PDF
• 所有「请用户提供 PDF」的情况 -> 记录配置（标注本地限制），下次不重复尝试

本地环境配置

首次检测完成后，将结果写入 local-env.json（位于 skill 目录下）：

{
  "platform": "linux",
  "hasDisplay": true,
  "renderer": "libreoffice",
  "sofficePath": "/usr/bin/soffice",
  "wpsAvailable": false,
  "notes": ""
}

• renderer："libreoffice" / "wps-com" / "wps-rpc" / "user-pdf"（用户自行提供 PDF）
• notes：记录限制说明，如「LibreOffice 安装失败，用户拒绝安装 WPS，需提供 PDF」
• 后续运行时优先读取此配置，跳过检测流程；配置不存在或为空时才执行检测

PDF 输入依赖

which pdftoppm    # 首选，缺失时 fallback 到 pymupdf

poppler（pdftoppm）为首选 PDF 渲染器。未安装时 parse.py 自动 fallback 到 pymupdf，功能等价。

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

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

输入判定

如果 local-env.json 中 renderer 为 "user-pdf"，则仅接受 PDF 输入，PPT 输入时提示用户先自行导出 PDF。

主代理工作流程

前置准备

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

单文件 ≤10 页：直接处理

1. 运行 parse.py 提取素材（默认 150 DPI）
2. 逐页 read 整页截图校准文字、read extracted_pics 原图识别信息图
3. 遇到矢量脑图/架构图/密集文字页，默认截图模糊看不清时，重新运行 parse.py --dpi 300 生成高分辨率整页截图再识别（按「高 DPI 重渲染规则」执行）
4. 逐页自检复核（抱着"大概率有遗漏/错误"的纠错心态逐页检查），检查出的问题罗列为待改清单，逐项通过 read 图片核对修正（可能需要 read extracted_pics 原图或重新生成高 DPI 截图），确认全部完成后保存
5. 保存到 ppt-parse-final/
6. 交付与汇报（见下方"交付与汇报"章节）

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

步骤一：spawn 子代理

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

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. **标点符号保真**:extracted_text.json 中的文字只能重排顺序,不能改写。禁止更改任何标点符号(特别是中英文引号不得互换),原文是什么就是什么
5. 完成后回报初稿路径和素材目录路径",
  taskName="ppt_parse_<任务名>",
  runtime="subagent",
  context="isolated",
  sandbox="inherit",
  cwd="<当前工作区路径>"
)

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

步骤二：主代理复核

强制要求：所有初稿（无论自检还是子代理初稿）必须经复核才能交付。抱着"大概率有遗漏/错误"的纠错心态逐页检查，而不是走过场。

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

检查阶段：

1. read 整页截图，对照文字检查漏字、错字、顺序
2. 核心信息图 read extracted_pics 原图，核对逐字转录
3. 遇到矢量脑图/架构图/密集文字页，子代理标注模糊或你自己发现看不清时，重新运行 parse.py --dpi 300 生成高分辨率整页截图，再核对细节
4. 检查图片标记数量与 extracted_text.json 的 images 数组是否一致
5. 检查是否有应作为信息图但只做了简述的情况
6. 检查图文绑定是否正确
7. 特别关注带 <!-- 批注：... --> 的页面

修正阶段：

8. 将第 1-7 步检查中发现的所有问题罗列为待改清单（逐条记录页码、问题类型、具体内容）
9. 逐项完成待改清单中的修正——每项修正都必须通过 read 对应页面的图片来核对：可能需要 read extracted_pics 原图核对细节，或重新运行 parse.py --dpi 300 生成高分辨率截图再识别，确保修正内容准确无误
10. 确认待改清单全部完成后，保存到 ppt-parse-final/

交付检查点：必须完成全页复核且待改清单全部修正，否则不能交付文件。

交付与汇报（两种模式共用）

无论 ≤10 页直接处理还是 >10 页子代理分工，交付时都必须执行此步骤。

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

⚠️ 强制汇报：交付时必须向用户提交一份任务汇报，内容如下：

## PPT/PDF 解析任务汇报

### 基本信息
- 输入文件：<文件名>
- 总页数：X 页
- 处理模式：直接处理 / 子代理分工

### 三阶段完成情况
1. **阶段一（脚本提取）**：✅/❌ <说明>
2. **阶段二（逐页视觉校准）**：✅/❌ <说明，包括处理了多少页、多少图片标记>
3. **阶段三（全页复核）**：✅/❌ <说明，包括复核了多少页、待改清单条目数、逐项修正情况、最终验证结果>

### 复核质量自评
- 复核页数：X / X 页
- 待改清单：共 X 条（逐条列出问题及修正方式）
- 修正后重新验证：X / X 条已验证
- 遗留问题（如有）：逐条列出
- 未复核的页面（如有）：逐条列出原因

### 交付文件
- 最终文件路径：<路径>

如果阶段三未完成或未全部复核，不得声称"已完成"，必须在汇报中如实标注遗留问题。

阶段分工一览

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

⚠️ 标点符号保真(绝对规则):extracted_text.json 中的文字是原始文本,只能重排顺序,不能改写。禁止更改任何标点符号(特别是中英文引号不得互换),禁止增添/删除/替换任何字符。原文是什么,就是什么。

标记符号系统

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

图片标记

块级标记格式:

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

编号规则

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

文字部分

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

输出模板

开头注释:

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

每页结构:

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

正确示例

示例一(文本组成的图表,无嵌入图片,全是可编辑形状文字):

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

示例二(文字为主+logo辅助):

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

错误示例

• 跑完脚本直接交付,没有逐页视觉核对
• 子代理交了初稿就直接交付,没有主代理复核
• 文本组成的图表页加了 /[pic 01] 标记(框图是 PPT 形状不是嵌入图片)
• 把紧挨在一起的名称拆成独立条目(视觉上紧挨在一起的多个名称是对上方的举例,应归为一组,不要拆成独立条目跟分类并列)
• 图文分离(先写完文字再统一列图片说明)
• 核心数据图表只写简述,没有逐字转录
• 小文件还 spawn 子代理(≤10 页直接处理更高效)
• 工作路径写死(必须相对当前工作区)
• 识别困难处不添加批注(应标注 <!-- 批注:... --> 提醒复核)
• 篡改标点符号:把原文的中文引号改成英文引号,或反过来;把原文的逗号/句号/分号等改成其他标点;增添或删除标点(原文是什么就是什么,只能重排顺序,不能改写)
• 跳过复核直接交付:没有完成全页复核就交付文件
• 交付时不汇报:交付文件但没有提交任务汇报(三阶段完成情况 + 复核质量自评)

脚本使用

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

高 DPI 重渲染规则（当整页截图看不清时）

当遇到以下情况，默认 150 DPI 整页截图里文字/结构模糊：

• PPT/PDF 原生绘制的复杂脑图、架构图、流程图（矢量文本+形状，不是嵌入图片，extracted_pics 里无对应文件）
• 整页文字密集、字号过小

处理步骤：

1. 保留原有素材目录，重新运行 parse.py 加上 --dpi 300 参数（脚本会自动覆盖 page_NN.png 整页截图，extracted_pics 原图和 extracted_text.json 不受影响，无需重新提取）
2. 读取高分辨率版本的 page_NN.png 识别细节
3. 如果 300 DPI 仍然看不清，才添加 <!-- 批注：整页截图 300 DPI 下仍然模糊，无法准确转录 --> 说明

⚠️ extracted_pics 里的嵌入图片是从源文件直接提取的原始分辨率文件，本身就是最高清，不需要通过调高 DPI 重新生成。

脚本输出

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