ppt-image-extract

> 读取 PPT 内容（含图片识别）：导出每页为 PNG + 调用多模态模型识图。

触发场景

• 用户说「读取 PPT 内容」「识别 PPT 里的图」「把 PPT 转成文字」
• PPT 包含梯形图、电路图、实物图、流程图等无法用纯文本提取的内容
• 需要把图片中的知识点整理为文字

前置条件

1. Windows 系统（用 WPS/PowerPoint COM 导出图片）
2. 已安装 tiangong-wps-ppt-automation skill（提供 COM 自动化基础）
3. 已安装 pywin32：pip install pywin32
4. 多模态模型（用于识图，任选其一）：
   - qclaw/pool-minimax-m3（已验证可用）
   - qclaw/kimi2.6（已验证可用）
   - 其他支持图片输入的模型

核心流程

PPT (.ppt/.pptx)
    ↓ 步骤1: COM 自动化导出每页为 PNG
slides/<ppt名>/slide_001.png ~ slide_NNN.png
    ↓ 步骤2: 多模态模型逐张识图
识别结果（结构化文字）
    ↓ 步骤3: 汇总成文档
output.docx / output.md

步骤 1：导出 PPT 每页为 PNG

1.1 用 WPS COM（推荐，支持 .ppt 旧格式）

import os
import win32com.client

def export_ppt_to_png(ppt_path, output_dir):
    """用 WPS 演示 COM 把 PPT 每页导出为 PNG"""
    assert os.path.exists(ppt_path), f'PPT not found: {ppt_path}'

    ppt_name = os.path.splitext(os.path.basename(ppt_path))[0]
    out_folder = os.path.join(output_dir, ppt_name)
    os.makedirs(out_folder, exist_ok=True)

    print(f'PPT: {ppt_path}')
    print(f'Output: {out_folder}')

    # 优先用 WPS（支持 .ppt 旧格式），fallback 到 PowerPoint
    try:
        app = win32com.client.Dispatch('KWPP.Application')
    except:
        app = win32com.client.Dispatch('PowerPoint.Application')

    app.Visible = True  # WPS 必须可见

    try:
        pres = app.Presentations.Open(ppt_path, ReadOnly=True, WithWindow=False)
        total = pres.Slides.Count
        print(f'Total slides: {total}')

        for i, slide in enumerate(pres.Slides, 1):
            out_path = os.path.join(out_folder, f'slide_{i:03d}.png')
            slide.Export(out_path, 'PNG', 1920, 1080)
            if i % 20 == 0:
                print(f'  exported {i}/{total}')

        pres.Close()
        print(f'✅ Done: {total} slides exported to {out_folder}')
        return out_folder, total
    finally:
        app.Quit()

1.2 批量处理多个 PPT

def export_all_ppts(folder, output_root='slides'):
    """批量导出文件夹下所有 PPT"""
    ppts = [f for f in os.listdir(folder) if f.lower().endswith(('.ppt', '.pptx'))]
    print(f'Found {len(ppts)} PPTs')

    results = {}
    for ppt in ppts:
        ppt_path = os.path.join(folder, ppt)
        out_folder, count = export_ppt_to_png(ppt_path, output_root)
        results[ppt] = (out_folder, count)

    return results

1.3 验证导出

def verify_exports(results):
    """验证每个 PPT 的导出数量"""
    for ppt_name, (folder, expected) in results.items():
        actual = len([f for f in os.listdir(folder) if f.endswith('.png')])
        status = '✅' if actual == expected else '❌'
        print(f'{status} {ppt_name}: expected {expected}, got {actual}')

步骤 2：多模态模型识图

2.1 单张图识别（在主会话中用 read 工具）

重要：模型必须支持图片输入。当前验证可用的模型：
- qclaw/pool-minimax-m3（MiniMax M3，原生多模态）
- qclaw/kimi2.6（Kimi K2.6，视觉理解）

调用方式（在 agent 主循环中）：

# 用 read 工具读取 PNG，模型会自动识别图片内容
read(path="C:/path/to/slide_001.png")

注意：read 工具对图片返回的是模型识图结果，不是文件二进制。需要模型本身支持多模态。

2.2 批量识图策略

不要在主会话中逐张识图（会污染上下文 + 速度慢）。

推荐方式：派子 AGENT 处理，主会话只接收汇总结果。

sessions_spawn(
  task=<识图任务描述，包含图片路径清单 + 期望输出格式>,
  model="qclaw/pool-minimax-m3",
  runtime="subagent",
  mode="run"
)

2.3 子 AGENT 识图任务模板

# 任务：识别 PPT 图片内容

## 图片清单
- C:/path/to/slides/plc第七讲/slide_011.png — PLC 三段等效电路
- C:/path/to/slides/plc第七讲/slide_013.png — 核心转换案例
...（列出所有要识别的图）

## 输出要求
对每张图输出：
1. 图片标题（来自 slide 编号）
2. 图片类型（电路图/梯形图/实物图/文字说明/混合）
3. 关键内容描述（200-400 字）
   - 电路图：列出主要元件 + 连接关系
   - 梯形图：列出 LD/AND/OR/OUT 等指令 + 梯形图结构
   - 实物图：列出设备型号 + 关键特征
   - 文字说明：直接摘录关键文字
4. 对应考点（如适用）

## 输出格式
Markdown 文档，每张图一段：

### slide_NNN.png
- **类型**：电路图
- **描述**：...
- **考点**：考点 4

2.4 进度控制

• 每个子 AGENT 处理 10-20 张图（避免上下文超限）
• 多个子 AGENT 可并行（OpenClaw 支持 maxConcurrent: 8）
• 主会话用 sessions_yield 等待全部完成

步骤 3：汇总成文档

3.1 收集子 AGENT 结果

子 AGENT 完成后会把识别结果写文件或返回报告。主会话：

import glob

results = []
for f in glob.glob(r'C:\path\to\work\*_result.md'):
    with open(f, 'r', encoding='utf-8') as fp:
        results.append(fp.read())

final = '\n\n---\n\n'.join(results)

3.2 生成 docx（可选）

如果需要嵌入图片 + 文字到 docx：

from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()

for item in image_results:
    doc.add_heading(item['title'], level=2)

    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.add_run().add_picture(item['image_path'], width=Inches(5.5))

    cap = doc.add_paragraph()
    cap.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = cap.add_run(f"图：{item['caption']}")
    run.italic = True
    run.font.size = Pt(9)
    run.font.color.rgb = RGBColor(0x55, 0x55, 0x55)

    doc.add_paragraph(item['description'])

doc.save(output_path)

常见问题

Q1: WPS COM 启动失败

• 确认 WPS Office 已安装
• 试 KWPP.Application（WPS）→ PowerPoint.Application（Microsoft）→ wpp.Application（WPS 新版）
• WPS 必须设为 Visible=True（COM 限制）

Q2: .ppt 旧格式导出失败

• WPS 支持 .ppt，Microsoft PowerPoint 需要先另存为 .pptx
• 也可以先用 LibreOffice soffice --convert-to pptx 转换

Q3: 模型不支持图片识别

• 当前 qclaw/pool-glm-5.2（默认模型）不支持图片识别
• 必须切换到多模态模型：qclaw/pool-minimax-m3 或 qclaw/kimi2.6
• 用 sessions_spawn(model="qclaw/pool-minimax-m3") 指定子 AGENT 的模型

Q4: 子 AGENT 识图超时

• 单个子 AGENT 处理图片数 ≤ 20 张
• 大批量（>50 张）拆成多个子 AGENT 并行
• 用 mode="run" 让子 AGENT 后台运行

Q5: 识别结果不准确

• 提供清晰的图片标题/上下文（"这是 PLC 第七讲第 13 页，主题是核心转换案例"）
• 对关键图可以多次识别取共识
• 识别后让用户校对

文件路径约定

<工作目录>/
├── slides/                       # 导出的 PNG
│   ├── <PPT名1>/
│   │   ├── slide_001.png
│   │   ├── slide_002.png
│   │   └── ...
│   └── <PPT名2>/
│       └── ...
├── _recognize_results/           # 子 AGENT 输出
│   ├── batch1_result.md
│   └── batch2_result.md
└── output.docx                   # 最终汇总文档

依赖 skill

• tiangong-wps-ppt-automation（提供 PPT COM 自动化基础，但不含图片识别）
• 本 skill 补充了「图片识别」能力

限制

• 仅 Windows（依赖 WPS/PowerPoint COM）
• 识图精度依赖多模态模型，复杂梯形图可能漏细节
• 大批量 PPT（>500 页）耗时较长，建议分批处理
• 导出的 PNG 分辨率默认 1920×1080，可调整