PPTAgent 使用说明

1. 它解决什么问题

多数「文档转 PPT」工具只优化文字内容，忽视视觉设计与结构连贯性。PPTAgent 对标人类工作流，用 两阶段编辑式生成：

1. 分析参考演示稿 — 提取 slide 级功能类型与内容 schema
2. 起草大纲 + 迭代编辑 — 基于参考页生成编辑动作，逐页构建新 Deck

2025/12 起仓库集成 DeepPresenter 大升级：Deep Research、自由视觉设计、自主素材创建、文生图、Docker 沙箱 Agent 环境（20+ 工具）、MCP 服务、PPTX 导出与离线模式。

> 强烈推荐部署微调模型 DeepPresenter-9B（HuggingFace / ModelScope），实验显著优于通用开源模型。

2. 环境要求

macOS CLI 模式可能自动安装 Homebrew、Node.js、Docker、poppler、Playwright、llama.cpp 等依赖。

3. 快速开始（CLI · 推荐首次验证）

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 交互式首次配置（模型、MCP、路径等）
uvx pptagent onboard

# 最小任务：确认环境 OK
uvx pptagent generate "Single Page with Title: Hello World" -o hello.pptx

# 带附件生成
uvx pptagent generate "Q4 Report" \
  -f data.xlsx \
  -f charts.pdf \
  -p "10-12" \
  -o report.pptx

CLI 命令

适合：个人本地最快上手、OpenClaw 集成。

4. 配置文件

CLI 用 pptagent onboard 自动生成；Docker / 源码模式需手动复制：

cp deeppresenter/config.yaml.example deeppresenter/config.yaml
cp deeppresenter/mcp.json.example deeppresenter/mcp.json

可选服务（显著提升质量）

离线模式： 本地部署 MinerU，并在 config.yaml 设 offline_mode: true，避免加载联网搜索等工具。

更多变量见 deeppresenter/utils/constants.py。

5. 三种部署方式

方式 A · CLI（个人 / OpenClaw）

见 §3。依赖最少抽象层，适合快速验证与脚本集成。

方式 B · 源码 + WebUI（开发）

git clone https://github.com/icip-cas/PPTAgent.git
cd PPTAgent
uv pip install -e .
playwright install-deps && playwright install chromium
npm install --prefix deeppresenter/html2pptx
modelscope download forceless/fasttext-language-id

# 拉取 Docker 镜像
docker pull forceless/deeppresenter-sandbox
docker pull forceless/deeppresenter-host
docker tag forceless/deeppresenter-sandbox deeppresenter-sandbox
docker tag forceless/deeppresenter-host deeppresenter-host

python webui.py

方式 C · Docker Compose（服务器）

docker compose up -d

Web UI 默认：http://localhost:7861

国内可用 1ms.run 镜像：docker.1ms.run/forceless/deeppresenter-host 等。

6. 使用示例

CLI Prompt

uvx pptagent generate "请介绍小米 SU7 的外观和价格" -o su7.pptx

uvx pptagent generate "高中课堂课件：解码立法过程与国际关系" -p "12-15" -o lesson.pptx

WebUI 自然语言（Case Study）

• Please present the given document to me.（上传文档后）
• 请介绍小米 SU7 的外观和价格
• 请制作一份高中课堂展示课件，主题为「解码立法过程：理解其对国际关系的影响」

MCP 集成

仓库支持 MCP Server（2025/09 起），配置见仓库 PPTAgent/DOC.md 或 deeppresenter/mcp.json.example，可接入支持 MCP 的 Agent 客户端。

7. 推荐模型

通过 pptagent onboard 或 config.yaml 配置本地推理路径；也可用 pptagent serve 启动本地服务。

8. 工作原理（PPTAgent 核心）

参考 PPT / 模板库
    ↓ 分析 slide 功能类型 + content schema
大纲起草
    ↓ 为每页选择参考 slide + 生成编辑动作
迭代编辑 → 新 slide
    ↓ PPTEval 评估（Content / Design / Coherence）
交付 PPTX

DeepPresenter 在此基础上增加：环境接地反思、沙箱内工具调用、自主检索与素材生成、自由版式视觉设计。

9. 平台支持

10. 适合 / 不适合

✅ 适合

• 长 PDF / Word / Excel 转结构化演示稿
• 需要 Deep Research、联网检索的主题 Deck
• 重视视觉设计与结构连贯性（PPTEval 三维）
• 私有化服务器部署（Docker Compose）
• OpenClaw / MCP 自动化流水线

❌ 不适合

• 无 Docker 的轻量环境
• 纯 Windows 原生（无 WSL）
• 只想在 Chat 里一句话出图、无本地 runtime
• 固定咨询风视觉规范（→ 见 Aham PPT）
• 中文模板填字不改版式（→ 见 GordenPPTSkill）

11. 与其他工具对比

12. 常见问题

Q：必须先 clone 仓库吗？

CLI 模式用 uvx pptagent 即可，无需 clone。开发 / WebUI / 改配置建议 clone。

Q：生成很慢怎么办？

首次需拉 Docker 镜像与模型；配置 offline_mode 可减少联网工具；页数用 -p "10-12" 控制范围。

Q：支持中文吗？

支持。Case Study 含中文课件；语言检测用 fasttext-language-id 模型。

Q：如何引用？

见仓库 README Citation 块（EMNLP 2025 PPTAgent + arXiv DeepPresenter）。

13. 目录结构（速查）

PPTAgent/
├── pptagent/           # PPTAgent 核心包
├── deeppresenter/      # DeepPresenter Agent 环境
│   ├── config.yaml.example
│   ├── mcp.json.example
│   ├── html2pptx/
│   └── docker/
├── webui.py            # Web UI 入口
├── docker-compose.yml  # 服务部署
├── pyproject.toml
├── AGENTS.md / CLAUDE.md
└── resource/           # 资源与示例

14. 延伸阅读

• README.md
• Releases — 含 PPTAgent V2: DeepPresenter Integrated
• Hugging Face Collection
• MCP 配置：仓库内 PPTAgent/DOC.md