PPTAgent Skill 实战指南：为 Claude Code / Codex / OpenCode 安装并生成可编辑 PPTX

本文是 PPTAgent 开源仓库根目录 README.md 的技术解读与实战扩展。PPTAgent 是一个面向反射式 PowerPoint 生成的 Agentic 框架，而本篇聚焦于其中可直接落地的一环：PPTAgent Skill——让 Claude Code、Codex CLI、OpenCode 等编码 Agent 具备「编写 → 渲染 → 视觉审查 → 导出可编辑 PPTX」的完整演示文稿生产能力。读完本文，你将掌握 Skill 的安装注册、Atria Dawn Preview 接入、文本模式视觉审查配置、从一句话需求到 answer.pptx 的全流程，以及其背后的 CLI 命令链与证据校验机制。

一、PPTAgent Skill 是什么

PPTAgent Skill 是仓库 skills/pptagent/ 目录下的一个可安装技能包，其核心思路来自 SKILL.md 中定义的工作流：宿主 Agent 负责研究与撰写幻灯片内容，CLI 负责渲染、可编辑转换与一致性校验，视觉模型负责审查渲染结果。

能力	说明
✍️ 与 Agent 协作	复用 Claude Code / Codex / OpenCode 已有的模型与研究工具，把 brief 和素材转成幻灯片
🖼️ 审查结果	检查渲染后的幻灯片与导出的 PPTX，先改内容再确认效果，最后交付
📊 保持可编辑	交付可编辑的 answer.pptx 与 HTML 幻灯片源码，供后续请求继续修改

从源码看，这套能力由 scripts/pptagent.py 提供一组 JSON 输出的 CLI 命令（doctor、init、scaffold、review-slides、record-slide-review、build、review-deck、record-deck-review、finalize），底层逻辑在 scripts/pptagent_runtime/core.py 与 scripts/pptagent_runtime/config.py 中实现。

[!TIP] 需要复现 EMNLP 2025 论文《PPTAgent: Generating and Evaluating Presentations Beyond Text-to-Slides》（代码版本 v0.2.0）或 ACL 2026 的 DeepPresenter（代码版本 v1.1.38）时，请使用对应的 pinned 版本，而不是当前开发分支。

二、环境要求与系统依赖

安装 PPTAgent Skill 需要满足以下前置条件：

• 编码 Agent：Claude Code、Codex CLI 或 OpenCode 之一；
• 操作系统：Linux（含 WSL）或 macOS；
• 工具链：uv、npm，以及位于 PATH 中的 libreoffice 命令；macOS 上转换器还依赖已安装的 Google Chrome。

Linux（Debian/Ubuntu）

sudo apt-get install npm libreoffice-impress

macOS（Homebrew）

macOS 的 Homebrew 提供的是 soffice 命令，而运行时会通过 libreoffice 这个名字调用它，因此需要建立符号链接：

brew install node
brew install --cask libreoffice google-chrome
ln -sf "$(command -v soffice)" "$(brew --prefix)/bin/libreoffice"

之所以强制要求 libreoffice 可执行，是因为 scripts/pptagent_runtime/core.py 中的 render_deck 直接以 libreoffice --headless --convert-to pdf:impress_pdf_Export 将 answer.pptx 转为 PDF，再用 PyMuPDF 把每页渲染成 JPG 联系表（contact sheet）。

三、安装运行时并注册 Skill

1. 克隆仓库并安装依赖

git clone https://github.com/icip-cas/PPTAgent.git
cd PPTAgent/skills/pptagent

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt
.venv/bin/python -m playwright install --with-deps chromium

Python 依赖声明在 skills/pptagent/requirements.txt（pptagent==1.1.37、playwright==1.62.0、PyYAML、Pillow、PyMuPDF、fastmcp），Node 依赖声明在 skills/pptagent/package.json（playwright、pptxgenjs、sharp、fast-glob、minimist），安装脚本通过 npm ci 安装 Node 依赖。

2. 注册到你的编码 Agent

从 skills/pptagent/ 目录执行注册命令，三选一：

# Claude Code
.venv/bin/python scripts/install.py --client claude

# Codex CLI
.venv/bin/python scripts/install.py --client codex

# OpenCode
.venv/bin/python scripts/install.py --client opencode

从 scripts/install.py 源码可见注册路径：

客户端	注册位置	注册方式
Claude Code	~/.claude/skills/pptagent	符号链接到 Skill 目录
Codex CLI	~/.agents/skills/pptagent	符号链接到 Skill 目录
OpenCode	~/.config/opencode/skills/pptagent	生成一个轻量入口（SKILL.md + .pptagent-source 标记文件），指向真实 Skill 目录

注册完成后保持仓库目录原地不动（符号链接依赖它），然后运行体检命令：

.venv/bin/python scripts/pptagent.py doctor

doctor 会逐项检查 Python 版本（需 ≥3.11）、yaml/PIL/pymupdf/playwright/deeppresenter 模块、libreoffice 与 node 命令、Python/Node 两侧 Playwright 版本一致性、Chromium 是否安装，以及文本模式下视觉端点配置是否完整——它不会发起 API 请求，真正的端点检查发生在第一次 review-slides 调用时。上述检查逻辑可见 scripts/pptagent.py。

注意：OpenCode 客户端在注册后需要重启才能发现 Skill；重启前可用 opencode debug skill 确认发现结果。OpenCode 的完整配置流程见下文「七、OpenCode 专项配置」与 OpenCode setup guide。

四、快速开始：接入 Atria Dawn Preview

Atria Dawn Preview 是上海人工智能实验室联合多家机构发布的 Agentic 模型。它的文本工作流非常适合演示：Atria 撰写 HTML → Skill 渲染图片 → 外部视觉模型审查 → Atria 修复问题。可先在 Discovery 或 Atria 申请免费 Token Plan，并在 Atria console 创建 API Key。

1. 验证 Atria API Key

在启动客户端所用的终端里导出 Key，并发送最小请求：

export ATRIA_API_KEY="<your-atria-api-key>"

curl -X POST https://api.atria-asi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn-Preview",
    "messages": [{"role": "user", "content": "hi"}]
  }'

确认响应中 choices[0].message.content 包含助手回复即可。Atria 同时支持三种 API 格式，客户端不同则配置的 Base URL 不同：

客户端	API 格式	需配置的 Base URL
curl 示例	Chat Completions	https://api.atria-asi.ai/v1
Claude Code	Messages	https://api.atria-asi.ai
Codex CLI	Responses	https://api.atria-asi.ai/v1

模型 ID 必须保持精确为 Atria-Dawn-Preview。

2. Claude Code 接入

# 注册 Skill（已注册可跳过）
.venv/bin/python scripts/install.py --client claude

将以下字段合并进 ~/.claude/settings.json（保留原有配置）：

{
  "model": "Atria-Dawn-Preview",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.atria-asi.ai"
  }
}

在设置了 ATRIA_API_KEY 的终端里，把 Key 映射为 Claude Code 的网关凭据并启动新会话：

export ANTHROPIC_AUTH_TOKEN="$ATRIA_API_KEY"
mkdir -p ~/pptagent-demo
cd ~/pptagent-demo
claude

3. Codex CLI 接入

.venv/bin/python scripts/install.py --client codex

将以下配置合并进 ~/.codex/config.toml。model 与 model_provider 必须放在顶层、任何 [section] 表头之前，且要更新已有条目而不是重复添加：

model = "Atria-Dawn-Preview"
model_provider = "atria"

[model_providers.atria]
name = "Atria"
base_url = "https://api.atria-asi.ai/v1"
env_key = "ATRIA_API_KEY"
wire_api = "responses"

然后在同一终端启动：

mkdir -p ~/pptagent-demo
cd ~/pptagent-demo
codex

Codex 会请求 /v1/responses，并从环境变量 ATRIA_API_KEY 读取 Key。

4. OpenCode 接入

OpenCode 通过常规 provider 设置配置 Atria，再用下文「七」中的 OpenCode setup guide 连接视觉审查工具。

五、文本模式视觉审查配置（核心配置）

由于 Atria 是纯文本模型，必须先为它配置一个外部多模态视觉模型来审查渲染出的幻灯片。推荐通过端砚（Duanyan）Token Plan申请多模态模型的 API Token，推荐的审查模型为 deepseek-v4-flash-vision。

1. 生成配置文件

首次配置文本模式时，从 skills/pptagent/ 目录执行；若已有本地配置则直接编辑，不要覆盖：

cp config.example.yaml config.yaml
cp .env.example .env
chmod 600 .env

2. 修改 config.yaml

将 base_url 替换为端砚控制台显示的 OpenAI 兼容 API Base URL：

mode: text

visual:
  base_url: "<OpenAI-compatible API base URL from the Duanyan console>"
  model: "deepseek-v4-flash-vision"
  api_key_env: VISUAL_API_KEY
  timeout_seconds: 300

delivery:
  mode: strict

3. 写入 API Key

在 Skill 的 .env 中保存端砚 API Key：

VISUAL_API_KEY=<your-duanyan-api-key>

参数与底层行为说明

• base_url：必须是 API 前缀（需要 /v1 时带上），Skill 会自动追加 /chat/completions——从 scripts/pptagent_runtime/visual.py 可见，请求目标为 base_url + "/chat/completions"。端砚 Token Plan 页面打开的是服务控制台而非 API 端点，不要填入网页 URL；
• model：如果控制台给出的模型 ID 与 deepseek-v4-flash-vision 不同，以控制台为准。审查模型必须能通过 OpenAI 兼容的 Chat Completions API 接收图片输入；
• api_key_env：指明存放 Key 的环境变量名；CLI 会先读取 Skill 的 .env，已存在的环境变量优先于 .env（见 scripts/pptagent_runtime/config.py 的 setdefault 语义）；
• timeout_seconds：视觉 API 调用超时，默认 300 秒；
• delivery.mode：strict（默认）要求交付必须通过全部审查且与当前源码一致；best-effort 仅在用户明确接受不完整草稿时允许带未通过项交付。

配置完成后重新运行 doctor 确认配置完整。审查的响应格式（verdict、summary、issues）详见 文本模式指南：响应必须包含 verdict（pass/fail/unjudgeable）、非空 summary 和 issues 列表；每条 issue 需有 severity（blocker/major/minor）、正整数 slide、description 与 suggested_fix；带 major 或 blocker 问题的 pass 会被拒绝。响应解析与校验实现在 scripts/pptagent_runtime/visual.py，测试用例见 test_workflow.py（含「矛盾性 pass 被拒绝」「无效 JSON 不被静默修复」等回归）。

六、创建你的第一份演示文稿

在 Atria 驱动的会话中发送以下请求：

Use the pptagent skill to create a 6-slide presentation about how our
engineering team can adopt AI coding assistants. Use a clean 16:9 layout.
Render and visually review the slides and the exported deck, then deliver
an editable answer.pptx.

也可以显式调用 Skill：Claude Code 中使用 /pptagent，Codex 中使用 $pptagent，OpenCode 中直接要求使用 pptagent skill。在同一会话中继续迭代修改：

Turn slide 3 into a workflow diagram and shorten the recommendations.
Keep the deck at 6 slides, rebuild it, and review the updated PPTX.

交付物是 answer.pptx。任务文件夹中同时保留：

• slides/slideNN.html：可编辑的 HTML 幻灯片源码（从 1 开始编号）；
• assets/：本地图片、CSS、字体等资源；
• qa/：渲染出的幻灯片 JPG 与 PPTX 联系表；
• workspace-state.json：渲染、审查、构建的证据记录（CLI 管理）；
• final-report.json：最终验收结果。

支持画布为 16:9（1280×720）、4:3（960×720）与 A1（2244×3178），完整目录契约见 任务与源码契约。

七、OpenCode 专项配置

OpenCode 通过一个本地 stdio MCP 服务器暴露视觉审查工具。先完成 Quick Start（使用 --client opencode），确认 Skill 被发现：

opencode debug skill

文本模式宿主需先配置好上文「五」的视觉端点，然后初始化一个独立的演示工作区：

.venv/bin/python scripts/pptagent.py init \
  --workspace /absolute/path/to/pptagent-demo \
  --slides 6

在工作区创建 opencode.json，替换三处绝对路径：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pptagent-visual": {
      "type": "local",
      "command": [
        "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python",
        "/absolute/path/to/PPTAgent/skills/pptagent/scripts/visual_mcp.py",
        "--workspace",
        "/absolute/path/to/pptagent-demo"
      ],
      "enabled": true,
      "timeout": 1800000
    }
  }
}

然后在该工作区启动 OpenCode 并验证服务器：

cd /absolute/path/to/pptagent-demo
opencode mcp list
opencode

生成过程中，OpenCode 应依次调用 review_slides、修复问题、构建 answer.pptx、调用 review_deck 并执行 finalize。该 MCP 是本地 stdio 适配器，不开放网络端口；它读取 Skill 目录下的 config.yaml 与 .env，需要时可改用 --config 与 --env 指定其他文件。服务器实现见 scripts/visual_mcp.py，其两个工具（review_slides、review_deck）的暴露在 test_visual_mcp.py 中有回归验证。

八、从 brief 到 deck：工作流与原理

Skill 的标准流程分为四步，SKILL.md 对其中的命令链有明确约定：

步骤	发生什么	对应命令
Write	宿主 Agent 撰写内容并编写 HTML 幻灯片	init / scaffold
Review	宿主检查渲染图，或文本模式下外部视觉模型审查	review-slides + record-slide-review
Export	转换器生成可编辑 PowerPoint 并校验格式约束	build
Deliver	审查导出的 deck，CLI 校验其与当前源码一致	review-deck + record-deck-review → finalize

关键约束（来自源码与测试）

• 渲染前路由拦截：open_slide 通过 Playwright 的 page.route 拦截所有请求，只放行 file:// 且属于任务快照内的资源，任何未跟踪的远程资源（如外部 CSS）都会导致渲染失败（untracked render resources）——见 core.py 与 test_browser.py；
• 画布尺寸：HTML 的 body 必须在默认 1280×720 视口中解析为请求的像素尺寸，推荐在行内或本地 CSS 中写显式宽高；依赖 100vw 之类的视口单位会被 build 拒绝（dimensions 错误）——见 test_browser.py；
• 共享资源哈希：assets/ 与 slides/ 下的非 HTML 资源会整体做 SHA-256 快照，改动任一共享资源会使所有幻灯片审查失效——test_workflow.py 验证了「共享 CSS 变更 → review 失效 → 无法 finalize」；
• 证据链防伪：审查记录必须对应当前渲染与构建产物（render_current 校验图片存在且哈希一致）；重新审查修改后的 HTML 不会让旧的 PPTX 变为 current；直接改 answer.pptx 也要求重新渲染 deck——见 test_workflow.py；
• 交付门禁：finalize 检查六项（HTML 数量、幻灯片审查是否最新、answer.pptx 是否存在、PPTX 结构与画布、构建是否当前、deck 审查是否当前），complete=true 才可交付；best-effort 模式下 delivery_ready=true 允许带已披露的未通过项交付，但不会声称 complete——见 core.py 与 test_workflow.py。

HTML 写作约束（可复制到实际任务）

• 正文优先使用 p、h1–h6 或列表元素；背景、边框、阴影放在包裹的 div 上；
• 每个文本元素内容尽量保持在一行内（导出可能保留浏览器折叠前的换行）；
• 给定位文本容器留出显式宽度与余量，尤其对中英混排标题——PPTX 导出后的字体度量可能不同，浏览器里刚好放下、导出后可能折行并压到下一元素；因此导出的 deck 与 HTML 渲染都要检查。模板可参考 slide-template.html。

九、可选增强：MinerU 文档解析与检索工具

对于从论文、扫描报告或含复杂表格公式的 PDF 出发的演示任务，MinerU 能显著提升素材质量；检索工具则补充最新事实与图片来源。二者均为可选，短 brief 或现成 Markdown 直接用宿主的文件读取工具即可。

MinerU（文档转 Markdown）

安装的 pptagent 包内含 deeppresenter.tools.any2markdown MCP 服务器，其 convert_to_markdown 工具对 PDF 使用 MinerU：

设置	用途
MINERU_API_KEY	托管 MinerU API token；PDF 会上传到该服务解析
MINERU_API_URL	可选的自托管解析端点；适配器以 multipart pdf 字段上传并期望返回解析文件的 ZIP

两者都设置时托管 Key 优先；都不设置时回退到标准 MarkItDown。也可以在外部解析后把 Markdown 与图片放进任务文件夹。

检索工具（网页与图片搜索）

deeppresenter.tools.search 暴露 search_web、search_images、fetch_url、download_file：

Provider	设置	用途
Tavily	TAVILY_API_KEY	网页结果与图片
SerpAPI	SERPAPI_KEY	Google 网页与图片搜索

配置一个即可，SerpAPI 同时存在时优先；两者都缺失时该服务器只提供 URL 抓取与下载。宿主模型负责规划查询与综合结果，因此 Skill 中没有 search.model 设置。

在 Claude Code / Codex 中挂接

这些 MCP 服务器使用 Quick Start 安装的 Python 环境。在演示任务文件夹中先导出工作区与所选服务的 Key：

export WORKSPACE="$PWD"
export MINERU_API_KEY="<your-mineru-api-key>"
export TAVILY_API_KEY="<your-tavily-api-key>"

这些 MCP 服务器读取自己的环境变量；只把 Key 写进 Skill 的 .env 不会配置它们。切换任务文件夹时要更新 WORKSPACE。

Claude Code：把以下内容合并进任务文件夹的 .mcp.json，将 Python 路径替换为 Skill 解释器的绝对路径（Claude Code 会展开 ${...} 环境引用）：

{
  "mcpServers": {
    "pptagent-docs": {
      "type": "stdio",
      "command": "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python",
      "args": ["-m", "deeppresenter.tools.any2markdown"],
      "env": {
        "WORKSPACE": "${WORKSPACE}",
        "MINERU_API_KEY": "${MINERU_API_KEY}"
      }
    },
    "pptagent-search": {
      "type": "stdio",
      "command": "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python",
      "args": ["-m", "deeppresenter.tools.search"],
      "env": {
        "WORKSPACE": "${WORKSPACE}",
        "TAVILY_API_KEY": "${TAVILY_API_KEY}"
      }
    }
  }
}

Codex：在 ~/.codex/config.toml 添加服务器表（替换 Python 路径），env_vars 从启动 Codex 的环境中转发变量：

[mcp_servers.pptagent-docs]
command = "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python"
args = ["-m", "deeppresenter.tools.any2markdown"]
env_vars = ["WORKSPACE", "MINERU_API_KEY"]
startup_timeout_sec = 30
tool_timeout_sec = 1800

[mcp_servers.pptagent-search]
command = "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python"
args = ["-m", "deeppresenter.tools.search"]
env_vars = ["WORKSPACE", "TAVILY_API_KEY"]
startup_timeout_sec = 30
tool_timeout_sec = 120

自托管 MinerU 或 SerpAPI 时，把导出与 MCP 配置中的对应 Key 名替换为 MINERU_API_URL 或 SERPAPI_KEY。Claude Code 处理大 PDF 时可在启动前 export MCP_TOOL_TIMEOUT=1800000（毫秒）。启动新会话后在 /mcp 中确认工具出现，并先用小文件/简单查询验证，再投入大规模素材。

十、配置项速查表

配置项	取值	默认	说明
mode	multimodal / text	multimodal	多模态模式用宿主模型看图；文本模式走外部视觉端点
visual.base_url	OpenAI 兼容 API 前缀	空	Skill 自动追加 /chat/completions
visual.model	模型 ID	空	如 deepseek-v4-flash-vision
visual.api_key_env	环境变量名	VISUAL_API_KEY	存放视觉 API Key 的变量
visual.timeout_seconds	正整数	300	视觉 API 调用超时
delivery.mode	strict / best-effort	strict	严格交付 / 用户接受草稿时的尽力交付

字段解析逻辑见 scripts/pptagent_runtime/config.py：mode 或 delivery.mode 非法会直接抛错；delivery.output 被固定为 answer.pptx，不允许修改。完整示例参考 config.example.yaml。

十一、进一步阅读

• Skill instructions：宿主 Agent 遵循的工作流；
• Task and source contract：工作区布局与 HTML 转换约束；
• External visual review：文本模式审查响应格式；
• Configuration example：全部可用设置；
• PPTAgent 项目主页：发布历史、安装与论文信息。

安装或使用中遇到问题，先运行 .venv/bin/python scripts/pptagent.py --help 查看全部命令参数；所有命令接受 --workspace（绝对路径）并以 JSON 输出，doctor 与 finalize 的失败会以非零退出码返回。