allengaoo/ppt-agent skill 本地安装使用教程

allengaoo/ppt-agent skill 本地安装使用教程：先确认它是 Web 服务，不是单次命令脚本。 这个仓库容易被误读成“输入一句话马上得到成品 PPT”的轻量工具，实际边界更重：它是一个基于 FastAPI、LangGraph、python-pptx 和 OpenAI 兼容模型接口的多阶段 PPT 生成服务，运行时会在大纲和内容两处停下来等待确认，最后再把设计方案转成 PPTX。

它的价值在于把“需求澄清、大纲审阅、内容审阅、设计渲染、后续修改”串成同一个会话流程，适合愿意在本地跑服务、愿意检查每个阶段结果的人。第一个限制也很明确：没有可用的模型 API、依赖没有装好，或者把可选的记忆服务当成必需服务一起硬开，第一次运行通常会停在配置层，而不是 PPT 美化层。

这个仓库解决什么问题

allengaoo/ppt-agent 的 README 把项目定位为“自然语言驱动的多智能体 PPT 生成系统”。它不是只把 Markdown 套进模板，而是先解析主题、受众、风格、页数等意图，再规划幻灯片大纲；大纲确认后才逐页写内容；内容确认后再生成设计决策、中间表示层和最终 PPTX。

这种设计对咨询汇报、内部方案、管理层简报更友好，因为它允许人在关键节点改大纲和正文，而不是等整份 PPT 出来以后再倒回去重做。仓库还提供自然语言修改入口，例如生成完成后继续提交“把第 3 页改成对比表格”一类请求，由编辑流程识别修改范围并重新渲染。

适合谁先试

更适合已经能接受本地服务、REST API、环境变量和 Python 依赖的人。项目入口是 main.py，Web UI 默认访问 http://localhost:8000，API 前缀是 /api/v1，生成文件默认落在 ./output。如果只是想找一个复制到 Claude 或 Codex 目录里的轻量 skill，这个仓库不是那种安装方式。

它也适合研究 PPT Agent 架构的人。目录里能看到 app/agents、app/api、app/engine、app/memory 等模块：前者负责意图、大纲、内容、设计和修改，后者负责把中间表示层交给 pptx_executor.py，再通过 python-pptx 生成文件。

本地安装和配置

先准备 Python 环境，再从 GitHub 克隆仓库：

git clone https://github.com/allengaoo/ppt-agent.git
cd ppt-agent
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

依赖清单里有 fastapi、uvicorn、langgraph、langchain-openai、python-pptx、Pillow 等包。也就是说，首次排错重点检查 Python 包、模型接口和服务端口三件事，而不是直接怀疑 PPT 模板。

复制环境变量示例，然后填入 OpenAI 兼容接口：

cp .env.example .env

LLM_API_KEY=sk-your-key-here
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o
APP_PORT=8000
OUTPUT_DIR=./output

README 里也给了 Gemini OpenAI 兼容接口示例。实际使用时只需要保证 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL 三项能连通同一个服务。记忆系统默认可以关闭；只有需要持久保存风格偏好时，才继续处理 MEMORIA_ENABLED、MEMORIA_API_URL、Embedding 和 MatrixOne。

第一次运行怎么检查

仓库提供了统一服务脚本，README 给出的启动方式是：

bash scripts/service.sh start all
bash scripts/service.sh status

如果只想先跑主服务，可以按 README 的服务说明启动 ppt-agent。服务起来后，打开 http://localhost:8000 看 Web UI，再访问健康接口确认后端可用：

curl http://localhost:8000/api/v1/health

返回状态正常后，再走一次最小生成请求：

curl -X POST http://localhost:8000/api/v1/generate 
  -H "Content-Type: application/json" 
  -d '{"prompt":"为管理层制作 AI 战略规划汇报，8页，深蓝商务风格，含市场数据对比表格"}'

这个接口会返回 task_id 和 session_id。接着轮询任务状态：

curl http://localhost:8000/api/v1/tasks/{task_id}

正常流程不是一路直接到 completed。项目会先进入 awaiting_outline_review，此时需要确认大纲；随后进入 awaiting_content_review，此时需要确认内容；确认后才会进入设计、IR 构建和 PPTX 渲染。

两个确认接口别跳过

大纲确认接口用于继续内容生成：

curl -X POST http://localhost:8000/api/v1/sessions/{session_id}/outline/confirm 
  -H "Content-Type: application/json" 
  -d '{"outline_markdown":null}'

内容确认接口用于继续最终生成：

curl -X POST http://localhost:8000/api/v1/sessions/{session_id}/content/confirm 
  -H "Content-Type: application/json" 
  -d '{"content_markdown":null}'

null 表示沿用服务生成的 Markdown；如果已经在前端或接口里改过大纲、正文，就把修改后的 Markdown 传回去。这个设计让人能在“骨架”和“文字”两个阶段介入，适合严肃汇报材料，但也意味着它不是完全无人看管的流水线。

生成后怎么确认成品

任务到 completed 后，看返回里的输出文件名，或者直接检查 ./output 目录。项目的渲染执行器会基于 PresentationIR 写入 PPTX，并把标题、作者、主题等元信息写进文件属性。

如果生成后继续修改，使用会话修改接口：

curl -X POST http://localhost:8000/api/v1/sessions/{session_id}/modify 
  -H "Content-Type: application/json" 
  -d '{"prompt":"把第3页的要点缩减到3条，换成对比表格布局"}'

修改不是直接编辑已有 PPTX 文件，而是基于当前会话里的中间表示层重新走补丁和渲染。想做更细的排错，还能查看或提交会话 IR：仓库路由里有 GET /sessions/{session_id}/ir 和 PUT /sessions/{session_id}/ir。

需要提前接受的边界

第一，它依赖模型输出结构化结果，模型质量会影响大纲、内容和设计决策。第二，PPTX 渲染由 python-pptx 和项目模板控制，复杂动画、母版级精修、品牌字体一致性仍要人工检查。第三，Memoria、MatrixOne、Ollama 或 Embedding 不是每次试用都必须打开；先关闭记忆系统跑通主服务，往往更容易定位问题。

把 allengaoo/ppt-agent 当成本地 PPT 生成服务来试，会比把它当成轻量目录 skill 更准确。第一次跑通的判断标准也很具体：Web UI 能打开，健康接口返回正常，任务能停在大纲和内容审阅状态，最终在 ./output 里拿到 PPTX。