docs: update README and REQUIREMENTS to reflect current architecture (knowledge base + schema + renderer)
This commit is contained in:
李进
+46
-99
@@ -1,115 +1,62 @@
|
||||
# HTML to PPTX 导出引擎
|
||||
# html2pptx 项目文档
|
||||
|
||||
## 背景
|
||||
## 项目定位
|
||||
|
||||
DashiAI PPT Skill 中包含一个 `html-deck-to-pptx` 导出子包，能将 HTML 演示文稿导出为可编辑的 PPTX 文件。该子包目前为专有组件（非开源），但其核心逻辑可复刻。
|
||||
一套通用 PPT 生成基础设施。核心价值在于**翻译引擎**——把标准 JSON 描述翻译成可编辑的 PPTX 文件。
|
||||
|
||||
我们需要一个独立、可控的导出引擎，集成到现有工作流中。凡是 Hermes/Agogent 生成的 HTML PPT，都能一键导出为**文字可编辑、布局可还原**的 PPTX 文件。
|
||||
|
||||
---
|
||||
|
||||
## 需求
|
||||
|
||||
### 输入
|
||||
|
||||
- 一个 HTML 文件（含完整 CSS 内联或外联），结构为横向翻页的演示文稿
|
||||
- 每页用 `<section>` 或特定容器标识
|
||||
- 样式通过 CSS 定义（font-size, color, font-weight, text-align, background-color 等）
|
||||
|
||||
### 输出
|
||||
|
||||
- 一个标准的 `.pptx` 文件，可用 Microsoft PowerPoint / WPS / Keynote 打开
|
||||
- **文字必须可编辑**（双击修改字体、大小、颜色）
|
||||
- **形状/框线/背景色保持矢量**（可拖动、缩放）
|
||||
- **排版布局按原始位置还原**（x, y, width, height 尽可能一致）
|
||||
|
||||
### 可放弃的特性（第一期不做）
|
||||
|
||||
- JS 图表（ECharts/Chart.js）→ 导出为截图占位或忽略
|
||||
- CSS 渐变/阴影/圆角 → 简化或忽略
|
||||
- 入场/翻页动画 → 忽略
|
||||
- Web 字体 → 映射为 Office 相近字体
|
||||
- 响应式布局 → 固定一宽高比
|
||||
|
||||
---
|
||||
|
||||
## 技术方案
|
||||
|
||||
### 架构
|
||||
## 架构
|
||||
|
||||
```
|
||||
HTML 文件
|
||||
↓
|
||||
启动本地 HTTP 服务（Node.js http-server 或 express）
|
||||
↓
|
||||
Chrome headless（通过 playwright）打开页面
|
||||
↓
|
||||
遍历 DOM，提取每页每个元素：
|
||||
- 位置（offsetLeft, offsetTop, offsetWidth, offsetHeight）
|
||||
- 文字内容（innerText）
|
||||
- 样式（font-size, color, font-weight, text-align, background-color 等）
|
||||
↓
|
||||
pptxgenjs 按页创建 slide，按坐标绘制 TextBox / Shape
|
||||
↓
|
||||
输出 .pptx 文件
|
||||
输入（任意来源） 中间层 输出
|
||||
━━━━━━━━━━━━━━━ ━━━━━━━━━━━ ━━━━━
|
||||
AI 直接输出 标准 JSON PPTX 文件
|
||||
HTML 提取 → JSON → Schema 校验 → 翻译引擎
|
||||
截图识别 → JSON （机械映射） pptxgenjs
|
||||
Markdown → JSON
|
||||
```
|
||||
|
||||
### 核心依赖
|
||||
### 三层
|
||||
|
||||
| 依赖 | 用途 | 备注 |
|
||||
|------|------|------|
|
||||
| `playwright` | 控制 Chrome headless 渲染页面、提取 DOM 信息 | 你的环境已有 Chrome |
|
||||
| `pptxgenjs` | 生成 PPTX 文件（OOXML） | 纯 JS，不依赖 Office |
|
||||
| `http-server` 或 express | 本地静态文件服务 | |
|
||||
| 层 | 内容 | 状态 |
|
||||
|---|------|------|
|
||||
| **知识库** (`reference/`) | pptxgenjs 完整参数表，每个参数的类型/取值范围/默认值 | ✅ 已完成 |
|
||||
| **Schema** (`schema/`) | JSON Schema 定义 + 多种场景的示例文件 | ✅ 已完成 |
|
||||
| **翻译引擎** (`renderer/`) | JSON → pptxgenjs API 调用的机械映射代码 | ✅ 已验收 |
|
||||
|
||||
### 可选升级
|
||||
### 前端处理器（待开发）
|
||||
|
||||
- 支持 PNG/JPEG 图片的提取与还原
|
||||
- 表格结构识别（`<table>` → PPT 表格）
|
||||
- 列表识别（`<ul>/<ol>` → PPT 列表）
|
||||
- CSS 圆角/边框映射
|
||||
- 批量导出（多 HTML 文件）
|
||||
"输入 → 标准 JSON"这层目前没有稳定的通用方案。试验过以下方向：
|
||||
|
||||
---
|
||||
| 方案 | 结论 |
|
||||
|------|------|
|
||||
| 多模态截图识别（Mimo v2.5） | ❌ 坐标和字号不够精确 |
|
||||
| LLM 直接读 HTML+CSS 源码 | ❌ 样式映射不准确 |
|
||||
| playwright 全量 DOM 提取 | ⚠️ 数据精确但分页和元素筛选不稳定 |
|
||||
|
||||
目前推荐的做法：**AI 直接按 Schema 输出 JSON**，不经过中间提取步骤。
|
||||
|
||||
## 翻译引擎使用
|
||||
|
||||
```javascript
|
||||
const { render, renderFile } = require('./renderer/index');
|
||||
|
||||
// 从 JSON 对象生成
|
||||
const pptx = render(specObject);
|
||||
pptx.writeFile({ fileName: 'output.pptx' });
|
||||
|
||||
// 从 JSON 文件生成
|
||||
await renderFile('./spec.json', 'output.pptx');
|
||||
```
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. **输入一个 10 页的 HTML PPT**，导出 PPTX 后在 PowerPoint 中打开
|
||||
2. **每一页的标题、正文文字可双击编辑**
|
||||
3. **文字字体、大小、颜色、粗体与原 HTML 一致**
|
||||
4. **布局位置基本还原**（不要求像素级，但段落不应错位到其他区域）
|
||||
5. **执行时间不超过 30 秒**（10 页）
|
||||
- 输入标准 JSON（符合 Schema）→ 输出可编辑的 PPTX
|
||||
- 文字可双击编辑（非图片）
|
||||
- 支持：文字、形状、表格、图片、图表
|
||||
- 颜色、字号、位置精确还原
|
||||
|
||||
---
|
||||
## 已知限制
|
||||
|
||||
## 工作流集成
|
||||
|
||||
```bash
|
||||
# 命令行调用
|
||||
html2pptx input.html output.pptx
|
||||
|
||||
# 或
|
||||
html2pptx input.html -o output.pptx
|
||||
|
||||
# 或指定端口
|
||||
html2pptx input.html -o output.pptx -p 8080
|
||||
```
|
||||
|
||||
输出文件路径直接返回给用户，用户双击或在 PowerPoint 中打开即可。
|
||||
|
||||
---
|
||||
|
||||
## 第一版范围（MVP）
|
||||
|
||||
- [ ] 基础架构：HTTP 服务 + Chrome headless 渲染 + DOM 提取
|
||||
- [ ] 文字提取：位置、内容、font-size、color、font-weight、text-align
|
||||
- [ ] PPTX 生成：pptxgenjs 建 slide，画 TextBox
|
||||
- [ ] 分页识别：按 `<section>` 或 `[data-slide]` 切割
|
||||
- [ ] 背景色还原：slide 背景色
|
||||
- [ ] 对齐方式：left/center/right
|
||||
|
||||
第一版不做的：
|
||||
- 图片提取
|
||||
- 表格识别
|
||||
- 列表识别
|
||||
- 渐变/阴影/圆角
|
||||
- 翻译引擎不做样式推断——JSON 里有什么就画什么
|
||||
- 前端处理器（HTML/截图→JSON）尚无稳定方案
|
||||
- 渐变、阴影等高级 CSS 效果依赖 pptxgenjs 支持程度
|
||||
|
||||
Reference in New Issue
Block a user