From 39ef4038423873af608a000a18a162a6a082c0d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9D=8E=E8=BF=9B?= <lijin@lijindeMac-mini.local>
Date: Wed, 22 Jul 2026 17:54:46 +0800
Subject: [PATCH] add: requirements doc for HTML-to-PPTX export engine

---
 REQUIREMENTS.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 REQUIREMENTS.md

diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
new file mode 100644
index 0000000..bc2dcbb
--- /dev/null
+++ b/REQUIREMENTS.md
@@ -0,0 +1,115 @@
+# HTML to PPTX 导出引擎
+
+## 背景
+
+DashiAI PPT Skill 中包含一个 `html-deck-to-pptx` 导出子包，能将 HTML 演示文稿导出为可编辑的 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 文件
+```
+
+### 核心依赖
+
+| 依赖 | 用途 | 备注 |
+|------|------|------|
+| `playwright` | 控制 Chrome headless 渲染页面、提取 DOM 信息 | 你的环境已有 Chrome |
+| `pptxgenjs` | 生成 PPTX 文件（OOXML） | 纯 JS，不依赖 Office |
+| `http-server` 或 express | 本地静态文件服务 | |
+
+### 可选升级
+
+- 支持 PNG/JPEG 图片的提取与还原
+- 表格结构识别（`<table>` → PPT 表格）
+- 列表识别（`<ul>/<ol>` → PPT 列表）
+- CSS 圆角/边框映射
+- 批量导出（多 HTML 文件）
+
+---
+
+## 验收标准
+
+1. **输入一个 10 页的 HTML PPT**，导出 PPTX 后在 PowerPoint 中打开
+2. **每一页的标题、正文文字可双击编辑**
+3. **文字字体、大小、颜色、粗体与原 HTML 一致**
+4. **布局位置基本还原**（不要求像素级，但段落不应错位到其他区域）
+5. **执行时间不超过 30 秒**（10 页）
+
+---
+
+## 工作流集成
+
+```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
+
+第一版不做的：
+- 图片提取
+- 表格识别
+- 列表识别
+- 渐变/阴影/圆角