html2pptx/REQUIREMENTS.md

html2pptx 项目文档

项目定位

一套通用 PPT 生成基础设施。核心价值在于翻译引擎——把标准 JSON 描述翻译成可编辑的 PPTX 文件。

架构

输入（任意来源）                 中间层                      输出
━━━━━━━━━━━━━━━                 ━━━━━━━━━━━               ━━━━━
AI 直接输出                      标准 JSON                   PPTX 文件
HTML 提取 → JSON         →     Schema 校验          →     翻译引擎
截图识别 → JSON                 （机械映射）                pptxgenjs
Markdown → JSON

三层

层	内容	状态
知识库 (reference/)	pptxgenjs 完整参数表，每个参数的类型/取值范围/默认值	✅ 已完成
Schema (schema/)	JSON Schema 定义 + 多种场景的示例文件	✅ 已完成
翻译引擎 (renderer/)	JSON → pptxgenjs API 调用的机械映射代码	✅ 已验收

前端处理器（待开发）

"输入 → 标准 JSON"这层目前没有稳定的通用方案。试验过以下方向：

方案	结论
多模态截图识别（Mimo v2.5）	❌ 坐标和字号不够精确
LLM 直接读 HTML+CSS 源码	❌ 样式映射不准确
playwright 全量 DOM 提取	⚠️ 数据精确但分页和元素筛选不稳定

目前推荐的做法：AI 直接按 Schema 输出 JSON，不经过中间提取步骤。

翻译引擎使用

const { render, renderFile } = require('./renderer/index');

// 从 JSON 对象生成
const pptx = render(specObject);
pptx.writeFile({ fileName: 'output.pptx' });

// 从 JSON 文件生成
await renderFile('./spec.json', 'output.pptx');

验收标准

• 输入标准 JSON（符合 Schema）→ 输出可编辑的 PPTX
• 文字可双击编辑（非图片）
• 支持：文字、形状、表格、图片、图表
• 颜色、字号、位置精确还原

已知限制

• 翻译引擎不做样式推断——JSON 里有什么就画什么
• 前端处理器（HTML/截图→JSON）尚无稳定方案
• 渐变、阴影等高级 CSS 效果依赖 pptxgenjs 支持程度