# 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**，不经过中间提取步骤。

## 翻译引擎使用

```javascript
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 支持程度