文档类型：开源设计想法 · 非绑定任何内部产品
架构主文档：ppt-architecture.md
Skill 真源：PPTWork · 本地E:\PPTWork
版本：v2.1 · 2026-07
Agent Host（OpenCode / Claude Code / Cursor / Codex）
→ 全局 Skills（ppt + ppt-html-authoring）
→ Node 脚本（ppt/scripts/*.mjs）
→ 工作区 FS（.pptwork/）
→ 可选 UI（读盘 / Canvas / 调 export CLI）
| 层 | 技术 | 职责 |
|---|---|---|
| Agent Host | OpenCode SDK、Claude Code、Cursor Agent、Codex 等 | 加载 Skill、LLM loop、bash 调脚本 |
| Skills | SKILL.md frontmatter 约定 |
编排澄清→规划→创作→导出方法论 |
| 脚本 | Node.js ESM（.mjs）+ lib/ 共享模块 |
Deck CRUD、截图、PPTX 构建 |
| 工作区 FS | 项目根 .pptwork/ |
deck.json + 每页 HTML 真源 |
| 可选 UI | 任意 Web / Desktop 栈 | 读盘、Canvas 改稿、触发 export.mjs |
| Skill | 触发语 | 职责 |
|---|---|---|
ppt |
build a deck / make a presentation / export to PowerPoint | Deck 级流水线：澄清、材料、调研、故事线、脚本调度、导出 |
ppt-html-authoring |
design a slide / draft this page | 单页 design.md + slide.html（1280×720 自包含） |
二者组合：ppt 逐页 delegate 给 ppt-html-authoring；后者也可单独使用。
Skill 参考文档（ppt/references/）：disk-layout.md、story-planning.md、material-digest.md、research.md、visual-qc.md、editable-html-rules.md（可编辑 export 的 HTML 约束）、export-troubleshooting.md。
| 包 | 版本（仓库现行） | 角色 |
|---|---|---|
| playwright-core | ^1.59.1 | Headless Chromium/Edge：渲染 slide.html、截图、editable export 宿主页 |
| html2pptx-pro | ^1.0.0 | 默认可编辑 PPTX：在浏览器内注入，DOM → 可编辑 Office 对象 |
| dom-to-pptx | ^1.1.8 | 备用 editable 引擎；--editable-engine dom-to-pptx，当前仅支持单页诊断 |
| pptxgenjs | ^4.0.1 | Raster 模式：整页 PNG 写入 .pptx（--mode raster） |
cd ppt && npm install # 或 bun install
# 无系统 Chrome/Edge 时：npx playwright install chromium| 入口 | 依赖模块 | 说明 |
|---|---|---|
scripts/deck.mjs |
lib/deck.mjs |
init / init-slide / move / delete / path / list |
scripts/screenshot.mjs |
lib/render.mjs, lib/find-browser.mjs |
slide.html → thumbnail.png |
scripts/export.mjs |
lib/deck.mjs, lib/render.mjs |
见 §5 |
scripts/import-reference.mjs |
— | 未移植；PPTX 模板导入仍依赖外部 plugin 或手动截图 |
lib/deck.mjs：.pptwork/ 路径、readDeck / writeDeck、normalizeExportMode（非 raster 即 editable）。
lib/render.mjs：renderSlideToPng（raster）、renderDeckWithHtml2PptxPro（默认可编辑）、renderSlideWithDomToPptx（备用）。
lib/find-browser.mjs：解析本地 Chrome / Edge；环境变量 PPT_BROWSER_EXECUTABLE 优先；否则 Playwright bundled Chromium。
| 调用 | 引擎 | 适用 |
|---|---|---|
export.mjs <deck> |
html2pptx-pro | 默认；需在 PowerPoint 内改字 |
export.mjs <deck> --mode editable |
html2pptx-pro | 显式指定（与默认相同） |
export.mjs <deck> --mode raster |
playwright PNG + pptxgenjs | 字体/CSS 漂移、要 WYSIWYG 像素契约 |
export.mjs <deck> --editable-engine dom-to-pptx |
dom-to-pptx | 仅单页 deck 诊断 |
deck.json.exportMode 与 CLI --mode 共同决定模式；未指定时 editable。输出默认 .pptwork/<deck>/<deck>.pptx，可用 --output 覆盖。
演讲者备注：从 slide.html 内 <script id="ppt-speaker-notes-json"> 提取，写入 PPTX notes（export 内正则解析，不另开浏览器）。
| 路径 | 格式 | 说明 |
|---|---|---|
.pptwork/<deck>/deck.json |
JSON | slides[] 页序唯一权威；exportMode 默认 editable |
.pptwork/<deck>/outline.md |
Markdown | 可选故事线 |
.pptwork/<deck>/materials/ |
Markdown | 摘要与调研 |
.pptwork/<deck>/<slide>/design.md |
Markdown + frontmatter | Content / Note / Design |
.pptwork/<deck>/<slide>/slide.html |
HTML | 编辑与导出真源；可选 speaker-notes JSON 岛 |
.pptwork/<deck>/<slide>/thumbnail.png |
PNG | screenshot 产出 |
.pptwork/<deck>/<deck>.pptx |
PPTX | export 产出 |
| 类别 | 技术 | 用途 |
|---|---|---|
| 框架 | Vue 3 / React 等 | 侧栏缩略图、Canvas、导出对话框 |
| Canvas | iframe 或封装 editor | 直改 slide.html |
| 缩略图 | 读 thumbnail.png 或浏览器预览 |
侧栏 |
| 刷新 | FS watch 或轮询 | Skill 写盘后更新 |
| 导出 | 子进程调用 node export.mjs |
勿在 UI 进程内嵌 Playwright 全量导出 |
| 模式 | 说明 |
|---|---|
| 最小 | 对话 → Host 加载 Skills → bash 写 .pptwork/ → export.mjs |
| 桥接 | UI 经 HTTP/SSE 提交 prompt；Host 执行 Skill；UI 读 FS |
| 深链 | 应用内 URL 打开 deck/slide（payload 含 workspace 根）；非 OS 级协议 |
cd ppt && npm test # → node test/smoke.mjs临时目录端到端：init → init-slide → 写 slide.html → screenshot → export（验证 editable 主路径）。
- Idea 与契约 → ppt-architecture.md
- 可运行实现 →
E:\PPTWork/ GitHub - 冲突时 以仓库源码与 README 为准
维护说明：依赖版本、export 默认模式或脚本 CLI 变更时，同步更新本文与 architecture 文档。