docs: update README and REQUIREMENTS to reflect current architecture (knowledge base + schema + renderer)
This commit is contained in:
李进
@@ -1,37 +1,94 @@
|
|||||||
# html2pptx
|
# html2pptx
|
||||||
|
|
||||||
HTML to editable PPTX export engine.
|
HTML / 截图 → 标准 JSON → 可编辑 PPTX
|
||||||
|
|
||||||
将 HTML 演示文稿导出为**文字可编辑、布局可还原**的 PPTX 文件。
|
将任何格式的演示文稿描述转化为**文字可编辑、布局可还原**的 PPTX 文件。
|
||||||
|
|
||||||
## 原理
|
## 架构
|
||||||
|
|
||||||
```
|
```
|
||||||
HTML 文件 → HTTP 服务 → Chrome headless 渲染 → DOM 遍历提取位置/样式 → pptxgenjs 生成 PPTX
|
输入（任意来源） 中间层 输出
|
||||||
|
━━━━━━━━━━━━━━━ ━━━━━━━━━━━ ━━━━━
|
||||||
|
AI 生成的描述 标准 JSON PPTX 文件
|
||||||
|
HTML 提取的结构 → Schema 校验 → pptxgenjs 渲染
|
||||||
|
多模态识别结果 ↓
|
||||||
|
Markdown / 其他 翻译引擎（机械映射）
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 三层结构
|
||||||
|
|
||||||
|
| 层 | 目录 | 说明 |
|
||||||
|
|---|------|------|
|
||||||
|
| **知识库** | `reference/` | pptxgenjs 完整参数表，每个参数的类型/取值范围/默认值。给 AI 用的操作手册 |
|
||||||
|
| **Schema** | `schema/` | JSON Schema 定义 + 示例。AI 输出符合此 Schema 的 JSON 即可驱动 PPT 生成 |
|
||||||
|
| **翻译引擎** | `renderer/` | JSON → pptxgenjs API 调用的机械映射。不做逻辑判断，只做参数透传 |
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 从 JSON 生成 PPTX
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const { render } = require('./renderer/index');
|
||||||
|
const pptx = render(jsonObject);
|
||||||
|
pptx.writeFile({ fileName: 'output.pptx' });
|
||||||
|
```
|
||||||
|
|
||||||
|
### 从 JSON 文件生成
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const { renderFile } = require('./renderer/index');
|
||||||
|
renderFile('./schema/examples/ui-dashboard.json', 'output.pptx');
|
||||||
|
```
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
reference/ ← 知识库：每个元素的完整参数表
|
||||||
|
text.md 文字参数
|
||||||
|
shape.md 形状参数
|
||||||
|
table.md 表格参数
|
||||||
|
image.md 图片参数
|
||||||
|
chart.md 图表参数
|
||||||
|
slide.md 页面参数
|
||||||
|
master.md 母版参数
|
||||||
|
output.md 输出参数
|
||||||
|
coordinate.md 坐标换算
|
||||||
|
|
||||||
|
schema/ ← JSON Schema 定义
|
||||||
|
presentation.schema.json
|
||||||
|
examples/
|
||||||
|
basic.json 基础示例（2页）
|
||||||
|
full.json 全功能示例
|
||||||
|
ui-dashboard.json UI 看板示例
|
||||||
|
ui-advanced.json 精细化 UI 示例
|
||||||
|
|
||||||
|
renderer/ ← 翻译引擎
|
||||||
|
index.js 主入口
|
||||||
|
text-renderer.js 文字渲染
|
||||||
|
shape-renderer.js 形状渲染
|
||||||
|
table-renderer.js 表格渲染
|
||||||
|
image-renderer.js 图片渲染
|
||||||
|
chart-renderer.js 图表渲染
|
||||||
|
slide-renderer.js 页面属性
|
||||||
|
|
||||||
|
PPTXGENJS_API.md ← pptxgenjs v4.0.1 完整 API 参考
|
||||||
|
```
|
||||||
|
|
||||||
|
## 设计原则
|
||||||
|
|
||||||
|
- **翻译引擎是纯机械映射** — 不做样式推断，不做逻辑判断。JSON 里有什么就画什么
|
||||||
|
- **Schema 是 AI 友好** — 字段名直观，不暴露 pptxgenjs 内部命名
|
||||||
|
- **知识库是完整参考** — 每个参数都有类型+取值范围+默认值，不需要 AI 去猜
|
||||||
|
|
||||||
## 依赖
|
## 依赖
|
||||||
|
|
||||||
- Node.js 18+
|
|
||||||
- Chrome / Chromium / Edge（用于渲染页面）
|
|
||||||
|
|
||||||
## 使用
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 安装
|
|
||||||
npm install
|
|
||||||
|
|
||||||
# 导出
|
|
||||||
node bin/html2pptx input.html output.pptx
|
|
||||||
```
|
|
||||||
|
|
||||||
## 核心依赖
|
|
||||||
|
|
||||||
| 包 | 用途 |
|
| 包 | 用途 |
|
||||||
|---|------|
|
|---|------|
|
||||||
| playwright | 控制 Chrome headless 渲染页面 |
|
| pptxgenjs | 生成 PPTX 文件（OOXML） |
|
||||||
| pptxgenjs | 生成 PPTX 文件 |
|
|
||||||
| http-server | 本地静态文件服务（可选） |
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
+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）
|
AI 直接输出 标准 JSON PPTX 文件
|
||||||
↓
|
HTML 提取 → JSON → Schema 校验 → 翻译引擎
|
||||||
Chrome headless（通过 playwright）打开页面
|
截图识别 → JSON （机械映射） pptxgenjs
|
||||||
↓
|
Markdown → JSON
|
||||||
遍历 DOM，提取每页每个元素：
|
|
||||||
- 位置（offsetLeft, offsetTop, offsetWidth, offsetHeight）
|
|
||||||
- 文字内容（innerText）
|
|
||||||
- 样式（font-size, color, font-weight, text-align, background-color 等）
|
|
||||||
↓
|
|
||||||
pptxgenjs 按页创建 slide，按坐标绘制 TextBox / Shape
|
|
||||||
↓
|
|
||||||
输出 .pptx 文件
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 核心依赖
|
### 三层
|
||||||
|
|
||||||
| 依赖 | 用途 | 备注 |
|
| 层 | 内容 | 状态 |
|
||||||
|------|------|------|
|
|---|------|------|
|
||||||
| `playwright` | 控制 Chrome headless 渲染页面、提取 DOM 信息 | 你的环境已有 Chrome |
|
| **知识库** (`reference/`) | pptxgenjs 完整参数表，每个参数的类型/取值范围/默认值 | ✅ 已完成 |
|
||||||
| `pptxgenjs` | 生成 PPTX 文件（OOXML） | 纯 JS，不依赖 Office |
|
| **Schema** (`schema/`) | JSON Schema 定义 + 多种场景的示例文件 | ✅ 已完成 |
|
||||||
| `http-server` 或 express | 本地静态文件服务 | |
|
| **翻译引擎** (`renderer/`) | JSON → pptxgenjs API 调用的机械映射代码 | ✅ 已验收 |
|
||||||
|
|
||||||
### 可选升级
|
### 前端处理器（待开发）
|
||||||
|
|
||||||
- 支持 PNG/JPEG 图片的提取与还原
|
"输入 → 标准 JSON"这层目前没有稳定的通用方案。试验过以下方向：
|
||||||
- 表格结构识别（`<table>` → PPT 表格）
|
|
||||||
- 列表识别（`<ul>/<ol>` → PPT 列表）
|
|
||||||
- CSS 圆角/边框映射
|
|
||||||
- 批量导出（多 HTML 文件）
|
|
||||||
|
|
||||||
---
|
| 方案 | 结论 |
|
||||||
|
|------|------|
|
||||||
|
| 多模态截图识别（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 中打开
|
- 输入标准 JSON（符合 Schema）→ 输出可编辑的 PPTX
|
||||||
2. **每一页的标题、正文文字可双击编辑**
|
- 文字可双击编辑（非图片）
|
||||||
3. **文字字体、大小、颜色、粗体与原 HTML 一致**
|
- 支持：文字、形状、表格、图片、图表
|
||||||
4. **布局位置基本还原**（不要求像素级，但段落不应错位到其他区域）
|
- 颜色、字号、位置精确还原
|
||||||
5. **执行时间不超过 30 秒**（10 页）
|
|
||||||
|
|
||||||
---
|
## 已知限制
|
||||||
|
|
||||||
## 工作流集成
|
- 翻译引擎不做样式推断——JSON 里有什么就画什么
|
||||||
|
- 前端处理器（HTML/截图→JSON）尚无稳定方案
|
||||||
```bash
|
- 渐变、阴影等高级 CSS 效果依赖 pptxgenjs 支持程度
|
||||||
# 命令行调用
|
|
||||||
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
|
|
||||||
|
|
||||||
第一版不做的：
|
|
||||||
- 图片提取
|
|
||||||
- 表格识别
|
|
||||||
- 列表识别
|
|
||||||
- 渐变/阴影/圆角
|
|
||||||
|
|||||||
Reference in New Issue
Block a user