yiqxie/ppt-agent skill 本地使用教程：Azure、LibreOffice 和前端入口配置

本地启动 yiqxie/ppt-agent 时，如果只盯着前端页面，很容易误判问题。它不是一个只靠浏览器就能跑的 PPT 工具，而是一套前后端加云端服务的 Web 应用：上传 PPT 后，后端要调用 LibreOffice、Poppler、Azure OpenAI、Azure Storage 和 PostgreSQL，任意一环缺了，页面都可能看起来“没反应”。

这套项目适合把 PPT 页转成可检索、可复用的 slide 设计资产：每页会生成截图、标题、摘要、tag、style 结构和 prompt JSON，再通过 React UI 搜索、预览和编辑。真正的新手难点不是按钮在哪里，而是判断自己要跑“本地开发版”还是“Azure 部署版”，再把依赖和环境变量一次补齐。

后端处理链路和健康检查

项目的处理路径很长：POST /api/jobs/upload 接收 PPT，Storage 先保存原文件，LibreOffice 把 PPT 转成 PDF，Poppler 再把 PDF 渲染成 PNG，Azure OpenAI 视觉模型分析每一页，后端把截图和 JSON 写进 Blob，把任务、slide、tag、style 写进 PostgreSQL。前端只是把这些结果组织起来，并不是全部能力都在浏览器里完成。

所以第一轮不要拿几十页 PPT 压测。先准备一份 2 到 3 页的小文件，确认后端健康检查能返回 {"status":"ok"}，再走上传。只要后端已经拿到任务，GET /api/jobs 应该能看到 job；处理过程中，WS /ws/progress?job_id=... 会推送进度；完成后，GET /api/slides 应该能查到对应 slide。

环境变量少一个，上传按钮就可能像坏了一样

本地后端至少要准备 Python、PostgreSQL、Azure Storage、Azure OpenAI。仓库的 backend/.env.example 已经列出关键项：DATABASE_URL 指向 PostgreSQL，AZURE_STORAGE_CONNECTION_STRING 或 Storage 账户配置负责文件存储，AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY、AZURE_OPENAI_VISION_DEPLOYMENT 负责视觉分析。开发时可以先把 AUTH_ENABLED=false 保持关闭，避免一开始就被 Microsoft Entra ID 登录配置拦住。

git clone https://github.com/yiqxie/ppt-agent.git
cd ppt-agent/backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

Windows 上还要特别看两个系统工具。PPT 渲染依赖 LibreOffice，PDF 转图片依赖 Poppler；如果后端报找不到 soffice 或 Poppler，可在环境里补 SOFFICE_BIN 和 POPPLER_PATH。Docker 镜像里已经安装了 libreoffice-impress、poppler-utils 和 Noto CJK 字体，本地裸跑时这些东西不会自动出现。

前端入口和 slide 处理状态

前端是 React + Vite + MUI，开发态默认访问 http://localhost:5173，并把 /api 和 /ws 代理到 http://localhost:8000。启动方式很直接：

cd ../frontend
npm install
cp .env.example .env
npm run dev

前端页面能打开后，检查 VITE_BACKEND_URL 是否指向后端。项目路由包括首页、上传页、slide 列表页、slide 详情页和系统配置页；上传只是第一步，真正要看的成功信号是 job 状态从 pending 到 running 再到 completed，并且 processed_slides 能追上 total_slides。

如果列表页查不到内容，按三处排查：第一，Storage 的 uploads、screenshots、prompts 容器里是否有文件；第二，PostgreSQL 的 jobs 和 slides 记录是否写入；第三，Azure OpenAI 调用是否因 endpoint、key、deployment 名称不一致而失败。只看浏览器报错容易绕远，沿着这三处能更快定位。

Docker 路径适合想一次验证完整镜像的人，仓库根目录可构建 ppt-agent:dev，容器内同时托管 FastAPI 后端和构建后的前端静态文件。但 Docker 仍然需要数据库、Storage、Azure OpenAI 这些外部配置；如果这些值没填好，换成容器也不会让上传流程自动成功。

yiqxie/ppt-agent 的价值在于把 PPT 变成可搜索、可编辑、可复用的 slide 资产库。第一次跑通时别追求大文件和完整登录保护，先关掉认证、用小 PPT、看健康检查、看 job 进度、看 slide 记录和 Blob 文件。只要这条链路通了，再接 Microsoft Entra ID、Azure App Service 和生产镜像会顺很多。