Honghurumeng/oc_sdk_ppt skill 本地安装使用教程(新手)

先别把 Honghurumeng/oc_sdk_ppt 当成“输入一句话，马上吐出完美 PPTX”的小脚本。它真正有用的地方，是把 PPT 生成拆成几个可回头检查的环节：先在网页里填主题、页数、受众和约束，后端用 @opencode-ai/sdk 调 LLM 生成大纲初稿，再开新会话做大纲精修，确认后才进入 HTML slides 和 deck.pptx 构建。

这个仓库更适合想在本机掌控生成过程的人：大纲能改，HTML 能预览，失败日志能看，单页还能做版本切换。它也有一个明显边界：任务会写进本地 workspace/jobs//，模型密钥放在本机 opencode.json，不适合原封不动丢到无状态 serverless 上当多人服务。

先判断它是不是你要的那类 PPT 工具

oc_sdk_ppt 的主线不是“替你写几页幻灯片文字”这么简单。README 里写得很清楚，它会先生成大纲，再让前端保留“初稿 / 精修版 / 当前编辑内容”几个状态，确认后才把每页转成 HTML。这样做的好处是，PPT 还没生成前，结构已经能人工拦一下，不用等到最后才发现整套 deck 跑偏。

它的另一个特点是不用额外生成插图素材。大纲阶段会注入内容生成和视觉设计约束，让输出里带有 ## Visual System 和每页 Visual: 描述；后续 HTML slides 尽量用原生 HTML/CSS 做图表、流程、卡片和对比结构。想要“所有页面都可在浏览器里先看一遍”的工作流，这个设计比直接生成二进制 PPTX 更容易排查。

本地先把模型列表跑出来

新手第一步不要急着填主题。先准备 Node.js 20+，再在仓库根目录执行 npm install 和 npm run dev，打开 http://localhost:3000。如果页面模型下拉框显示为空，优先检查 opencode.json 是否存在。

仓库提供了 opencode.example.json，可以先复制成 opencode.json，再填 provider、baseURL、apiKey 和 models。也可以点页面右上角“LLM 配置”，通过接口写入本地配置；这里的 apiKey 不回显，留空表示保留旧值。内嵌 opencode server 默认走 127.0.0.1:5937，端口被占用时会按配置继续尝试后续端口。

第一次试跑先选预览，不要直接赌 PPTX

首页表单里至少填主题、语言、页数、受众和语气。页数填 0 时，后端会让模型在 3 到 20 页之间自己判断；固定页数则会被限制在合理范围内。更稳的第一次试跑，是先生成大纲，等状态进入 awaiting_approval 后，在前端切换初稿、精修版和当前编辑内容，确认大纲没有跑偏，再选择生成 HTML 预览。

预览模式只生成 HTML slides，不马上构建 PPTX。源码里会检查每页 HTML 的 body 是否接近 720pt × 405pt 对应的 960 × 540 CSS 像素，并确认没有横向或纵向溢出。这里过了，再点渲染或下载 PPTX，失败成本会低很多。

跑通后看这些产物，别只看下载按钮

一个任务默认落在 workspace/jobs//。大纲初稿是 outline.initial.md，精修后大纲是 outline.md，每页 HTML 在 slides/01.html、slides/02.html 这一类文件里，最终 PPTX 是 deck.pptx。任务状态、日志、输入和结果会进 job.json，所以页面支持用 jobId 恢复任务。

如果想把它接到自己的页面或脚本里，核心接口也比较直观：POST /api/ppt/jobs 创建任务，GET /api/ppt/jobs/ 查状态，POST /api/ppt/jobs//approve 确认大纲并生成，POST /api/ppt/jobs//slides/adjust 按意见改 HTML，POST /api/ppt/jobs//render 用当前 HTML 重新构建 PPTX。单页版本切换则走 slides/activate，适合反复微调某一页。

这些坑提前避开，省掉半小时排查

第一，opencode.json 通常带 API key，仓库已经把它放进 .gitignore，不要顺手提交。第二，转换脚本优先依赖 Chrome 或 Playwright 运行环境，macOS 上建议先装 Google Chrome；没有浏览器环境，HTML 校验和构建会在本地卡住。第三，它不是多人协作后台，默认任务都写本机目录，部署时要重新设计存储、鉴权和任务队列。

还要注意 HTML slide 的约束。构建脚本会把 slides/*.html 交给 pptx/scripts/html2pptx.js，再由 pptxgenjs 写出文件；页面尺寸、溢出、图片引用和 CSS 写法都可能影响转换。第一次小稿建议用 3 到 5 页、短主题、少量参考内容，确认大纲、HTML 预览、版本切换、重新渲染、PPTX 下载这条链路都通了，再拿复杂长材料来试。

如果你的目标是“完全自动、无人工确认、直接批量出 PPTX”，oc_sdk_ppt 不是最省事的路线；如果你更在意每一步能看见、能改、能回滚，它的价值就出来了。把模型配置和浏览器环境先跑通，再从预览模式的小任务开始，基本能最快看清这套 Agent 的边界。