From cd7988cbd5a79100d82f8e90689d8c52459b323f Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Mon, 2 Mar 2026 14:28:25 +0800 Subject: [PATCH] feat: initial implementation of html2pptx with OpenSpec documentation Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+) --- README.md | 247 ++++ .../.openspec.yaml | 2 + .../2026-03-02-add-browser-preview/design.md | 250 ++++ .../proposal.md | 50 + .../specs/browser-preview-server/spec.md | 186 +++ .../specs/html-rendering/spec.md | 236 ++++ .../2026-03-02-add-browser-preview/tasks.md | 79 ++ .../.openspec.yaml | 2 + .../design.md | 201 +++ .../proposal.md | 44 + .../specs/template-directory-cli/spec.md | 83 ++ .../specs/template-system/spec.md | 72 + .../tasks.md | 40 + .../.openspec.yaml | 2 + .../design.md | 312 +++++ .../proposal.md | 38 + .../specs/element-rendering/spec.md | 168 +++ .../specs/pptx-generation/spec.md | 215 +++ .../specs/template-system/spec.md | 134 ++ .../specs/yaml-parsing/spec.md | 91 ++ .../tasks.md | 103 ++ openspec/config.yaml | 8 + openspec/specs/browser-preview-server/spec.md | 186 +++ openspec/specs/element-rendering/spec.md | 174 +++ openspec/specs/html-rendering/spec.md | 231 +++ openspec/specs/pptx-generation/spec.md | 221 +++ openspec/specs/template-directory-cli/spec.md | 83 ++ openspec/specs/template-system/spec.md | 188 +++ openspec/specs/yaml-parsing/spec.md | 97 ++ yaml2pptx.py | 1241 +++++++++++++++++ 30 files changed, 4984 insertions(+) create mode 100644 README.md create mode 100644 openspec/changes/archive/2026-03-02-add-browser-preview/.openspec.yaml create mode 100644 openspec/changes/archive/2026-03-02-add-browser-preview/design.md create mode 100644 openspec/changes/archive/2026-03-02-add-browser-preview/proposal.md create mode 100644 openspec/changes/archive/2026-03-02-add-browser-preview/specs/browser-preview-server/spec.md create mode 100644 openspec/changes/archive/2026-03-02-add-browser-preview/specs/html-rendering/spec.md create mode 100644 openspec/changes/archive/2026-03-02-add-browser-preview/tasks.md create mode 100644 openspec/changes/archive/2026-03-02-add-template-dir-parameter/.openspec.yaml create mode 100644 openspec/changes/archive/2026-03-02-add-template-dir-parameter/design.md create mode 100644 openspec/changes/archive/2026-03-02-add-template-dir-parameter/proposal.md create mode 100644 openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-directory-cli/spec.md create mode 100644 openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-system/spec.md create mode 100644 openspec/changes/archive/2026-03-02-add-template-dir-parameter/tasks.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/.openspec.yaml create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/design.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/proposal.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/element-rendering/spec.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/pptx-generation/spec.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/template-system/spec.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/yaml-parsing/spec.md create mode 100644 openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/tasks.md create mode 100644 openspec/config.yaml create mode 100644 openspec/specs/browser-preview-server/spec.md create mode 100644 openspec/specs/element-rendering/spec.md create mode 100644 openspec/specs/html-rendering/spec.md create mode 100644 openspec/specs/pptx-generation/spec.md create mode 100644 openspec/specs/template-directory-cli/spec.md create mode 100644 openspec/specs/template-system/spec.md create mode 100644 openspec/specs/yaml-parsing/spec.md create mode 100644 yaml2pptx.py diff --git a/README.md b/README.md new file mode 100644 index 0000000..4bb8ff4 --- /dev/null +++ b/README.md @@ -0,0 +1,247 @@ +# YAML to PPTX Converter + +将 YAML 格式的演示文稿源文件转换为 PPTX 文件，让 AI 也能轻松生成高质量的演示文稿。 + +## 🎯 核心特性 + +- **人类和 AI 友好**：使用 YAML 格式，简洁可读，易于生成 +- **模板系统**：可复用的幻灯片布局，大幅减少重复配置 +- **核心元素支持**：文本、图片、形状、表格 +- **精确布局控制**：基于英寸单位的精确定位 +- **简洁设计**：颜色和样式直接在模板中定义，无需额外配置 +- **浏览器实时预览**：编辑 YAML 文件时，浏览器自动刷新预览效果 + +## 📦 安装和使用 + +### 前置要求 + +- Python 3.8+ +- uv（推荐）或 pip + +### 使用方法 + +```bash +# 生成 PPTX 文件 +uv run yaml2pptx.py input.yaml output.pptx + +# 自动生成输出文件名 +uv run yaml2pptx.py input.yaml # 生成 input.pptx + +# 浏览器实时预览（新功能） +uv run yaml2pptx.py input.yaml --preview + +# 指定预览端口（默认随机选择 20000-30000 之间的端口） +uv run yaml2pptx.py input.yaml --preview --port 8080 + +# 查看帮助 +uv run yaml2pptx.py --help +``` + +### 浏览器预览功能 + +使用 `--preview` 参数可以在浏览器中实时预览 YAML 文件的效果： + +- 启动后自动打开浏览器 +- 默认使用 20000-30000 之间的随机端口，避免端口冲突 +- 编辑 YAML 文件后，浏览器自动刷新 +- 支持所有元素类型和模板 +- 按 Ctrl+C 停止预览服务器 + +**注意**：预览效果与最终 PPTX 可能存在细微差异（字体渲染、间距等），建议最终确认时生成 PPTX 文件查看。 + +## 📖 快速开始 + +### 1. 使用模板创建演示文稿 + +```yaml +# presentation.yaml +metadata: + title: "我的演示文稿" + size: "16:9" # 16:9 或 4:3 + +slides: + # 使用标题页模板 + - template: title_slide + vars: + title: "项目汇报" + subtitle: "2026年第一季度" + + # 使用内容页模板 + - template: content_slide + vars: + title: "主要成果" + content: | + • 销售额增长 25% + • 客户满意度 4.8/5.0 + • 新增 3 个市场 +``` + +### 2. 自定义幻灯片 + +```yaml +slides: + - background: + color: "#ffffff" + elements: + - type: text + content: "自定义标题" + box: [1, 1, 8, 1] # [x, y, width, height] 英寸 + font: + size: 44 + bold: true + color: "#1a1a1a" + align: center + + - type: shape + shape: rectangle + box: [2, 3, 6, 2] + fill: "#4a90e2" +``` + +## 📐 模板系统 + +内置模板： + +- `title_slide`：标题页（主标题 + 副标题） +- `content_slide`：内容页（标题条 + 内容区） +- `two_column`：双栏布局 + +## 🧩 支持的元素类型 + +### 文本元素 + +```yaml +- type: text + content: "Hello World" + box: [x, y, width, height] + font: + size: 32 + bold: true + italic: false + color: "#333333" + align: center # left, center, right +``` + +### 图片元素 + +```yaml +- type: image + src: "images/logo.png" + box: [x, y, width, height] +``` + +### 形状元素 + +```yaml +- type: shape + shape: rectangle # rectangle, ellipse, rounded_rectangle + box: [x, y, width, height] + fill: "#4a90e2" + line: + color: "#000000" + width: 2 +``` + +### 表格元素 + +```yaml +- type: table + position: [x, y] + col_widths: [2, 2, 2] # 英寸 + data: + - ["Header 1", "Header 2", "Header 3"] + - ["Cell 1", "Cell 2", "Cell 3"] + style: + font_size: 14 + header_bg: "#4a90e2" + header_color: "#ffffff" +``` + +## 📂 项目结构 + +``` +project/ +├── templates/ # 模板定义（颜色和样式直接在模板中） +│ ├── title_slide.yaml +│ ├── content_slide.yaml +│ └── two_column.yaml +├── examples/ # 示例文件 +│ ├── demo.yaml +│ ├── custom.yaml +│ └── complex.yaml +├── yaml2pptx.py # 转换脚本 +└── README.md +``` + +## 🔧 技术栈 + +- **Python 3.8+** +- **python-pptx**：PPTX 文件生成 +- **PyYAML**：YAML 文件解析 +- **uv**：Python 脚本运行器 + +## 📝 示例 + +查看 `examples/` 目录中的示例文件： + +- `demo.yaml`：使用模板的完整示例（3页） +- `custom.yaml`：自定义幻灯片示例（2页） +- `complex.yaml`：**复杂综合示例（10页）** - 展示所有功能 + +### 复杂示例亮点 + +`complex.yaml` 是一个完整的商业计划演示文稿，包含： + +✨ **10个精心设计的幻灯片**： +1. 封面页（使用 title_slide 模板） +2. 议程页（自定义布局，包含时间轴） +3. 公司概况（使用 content_slide 模板） +4. 市场分析（使用 two_column 模板） +5. 产品矩阵（复杂表格 + 架构图示） +6. 财务预测（多个表格 + 数据可视化） +7. 团队介绍（使用 two_column 模板） +8. 竞争优势（视觉化卡片 + SWOT 表格） +9. 产品路线图（使用 content_slide 模板） +10. 结束页（自定义召唤行动页） + +🎨 **展示的功能**： +- ✅ 所有三种模板的使用 +- ✅ 模板与自定义幻灯片混合 +- ✅ 所有元素类型：文本、形状、表格 +- ✅ 复杂布局和精确定位 +- ✅ 多种形状类型和样式组合 +- ✅ 丰富的颜色和字体样式（直接指定） +- ✅ 大量中文内容展示 +- ✅ 表格的高级样式应用 +- ✅ 视觉化信息展示（卡片、时间轴、架构图） + +```bash +# 生成示例演示文稿 +uv run yaml2pptx.py examples/demo.yaml # 基础示例 +uv run yaml2pptx.py examples/custom.yaml # 自定义示例 +uv run yaml2pptx.py examples/complex.yaml # 复杂综合示例 ⭐ +``` + +**生成的文件大小**： +- `demo_output.pptx` - 31KB +- `custom_output.pptx` - 29KB +- `complex_output.pptx` - 43KB (10页内容) + +## 🎓 YAML Schema 文档 + +详细的 YAML 格式说明，请参考各类型文件的示例和注释。 + +## 🚧 限制和已知问题 + +- 原型版本，仅支持核心功能 +- 不支持复杂样式（渐变、阴影、动画等） +- 不支持 PPTX 到 YAML 的反向解析 +- 图片背景功能暂未完整实现 + +## 📄 License + +MIT License + +## 🤝 贡献 + +欢迎提交 Issue 和 Pull Request！ diff --git a/openspec/changes/archive/2026-03-02-add-browser-preview/.openspec.yaml b/openspec/changes/archive/2026-03-02-add-browser-preview/.openspec.yaml new file mode 100644 index 0000000..fd79bfc --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-browser-preview/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-02 diff --git a/openspec/changes/archive/2026-03-02-add-browser-preview/design.md b/openspec/changes/archive/2026-03-02-add-browser-preview/design.md new file mode 100644 index 0000000..2db129f --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-browser-preview/design.md @@ -0,0 +1,250 @@ +## Context + +当前 `yaml2pptx.py` 是一个命令行工具，接收 YAML 文件作为输入，生成 PPTX 文件作为输出。脚本使用 uv 的 Inline script metadata 管理依赖（`python-pptx`、`pyyaml`），包含完整的 YAML 解析、模板渲染、元素渲染和 PPTX 生成逻辑。 + +现在需要在同一个脚本中添加预览模式，当用户使用 `--preview` 参数时，启动一个轻量级的 Web 服务器，提供浏览器实时预览功能。预览模式需要复用现有的 YAML 解析和模板渲染逻辑，但将输出目标从 PPTX 改为 HTML/CSS。 + +## Goals / Non-Goals + +**Goals:** +- 在 `yaml2pptx.py` 中添加预览模式，通过 `--preview` 参数启用 +- 使用轻量级的 Web 框架（Flask）提供 HTTP 服务 +- 使用 Server-Sent Events (SSE) 实现浏览器自动刷新 +- 使用 watchdog 监听 YAML 文件变化 +- 复用现有的 `Presentation` 类和 YAML 解析逻辑 +- 将 YAML 元素（文本、形状、表格、图片）渲染为 HTML/CSS +- 保持向后兼容，不影响现有的 PPTX 生成功能 + +**Non-Goals:** +- 不追求 100% 像素级精确的预览效果（HTML/CSS 与 PPTX 渲染存在差异是可接受的） +- 不支持交互功能（如点击元素查看属性、拖拽调整位置等） +- 不支持导出为静态 HTML 文件 +- 不支持多用户同时预览 +- 不支持 PPTX 动画和过渡效果的预览 + +## Decisions + +### 决策 1: 集成到现有脚本 vs 独立脚本 + +**选择**: 集成到 `yaml2pptx.py` 中，通过 `--preview` 参数启用 + +**理由**: +- 保持项目简洁，只有一个主脚本 +- 用户体验更统一，无需记忆多个命令 +- 更容易复用现有的解析逻辑和类定义 +- 减少代码重复和维护成本 + +**替代方案**: 创建独立的 `preview.py` 脚本 +- 优点：代码分离更清晰 +- 缺点：需要重复导入或复制代码，增加维护成本 + +### 决策 2: Web 框架选择 + +**选择**: Flask + +**理由**: +- 轻量级，适合本地开发工具 +- API 简单，易于实现 +- 社区成熟，文档丰富 +- 支持 Server-Sent Events + +**替代方案**: +- FastAPI: 更现代，但对于简单的预览服务来说过于复杂 +- Python 内置 http.server: 太简单，不支持动态路由和 SSE + +### 决策 3: 实时刷新方案 + +**选择**: Server-Sent Events (SSE) + +**理由**: +- 单向推送，符合需求（服务器通知浏览器刷新） +- 浏览器原生支持，无需额外的 JavaScript 库 +- 实现简单，约 10 行代码 +- 无需 WebSocket 的复杂握手和双向通信 + +**替代方案**: +- WebSocket: 过于复杂，需要 Flask-SocketIO 依赖 +- 轮询: 延迟高，资源浪费 +- Meta refresh: 固定时间刷新，无法响应文件变化 + +### 决策 4: 文件监听方案 + +**选择**: watchdog + +**理由**: +- 跨平台，支持 macOS、Linux、Windows +- 成熟稳定，广泛使用 +- API 简单，易于集成 +- 可以监听整个目录（包括模板文件变化） + +**替代方案**: +- 轮询文件修改时间: 延迟高，不够优雅 +- 操作系统原生 API: 不跨平台，实现复杂 + +### 决策 5: 单位转换策略 + +**选择**: 固定 DPI (96 DPI)，幻灯片固定尺寸 960x540 像素 + +**理由**: +- 实现简单，无需复杂的缩放计算 +- 960x540 是合理的预览尺寸（16:9 比例） +- 用户可以使用浏览器缩放功能（Cmd +/-）调整大小 +- 与 PPTX 的英寸单位转换清晰：1 英寸 = 96 像素 + +**替代方案**: +- 自适应缩放: 更灵活，但实现复杂，需要处理百分比定位 +- CSS 英寸单位: 不同浏览器可能有差异 + +### 决策 6: HTML 渲染策略 + +**选择**: 使用 `
` + 内联样式渲染元素 + +**理由**: +- 简单直接，易于实现 +- 使用绝对定位模拟 PPTX 的坐标系统 +- 内联样式避免 CSS 类管理的复杂性 +- 文本使用 `pt` 单位保持与 PPTX 一致 + +**元素映射**: +- 文本元素: `
` + `font-size: Xpt` +- 形状元素: `
` + `background-color` + `border-radius` +- 表格元素: `` 标签 +- 图片元素: `` 标签 + +**替代方案**: +- SVG 渲染: 更精确，但实现复杂 +- Canvas 渲染: 性能好，但无法选择文本，调试困难 + +### 决策 7: 代码组织 + +**选择**: 在 `yaml2pptx.py` 末尾添加预览相关代码，使用条件判断分离两种模式 + +**结构**: +```python +# 现有代码（PPTX 生成） +class Presentation: ... +class PptxGenerator: ... + +# 新增代码（预览模式） +# HTML 渲染函数 +def render_element_to_html(elem): ... + +# Flask 应用 +app = Flask(__name__) +@app.route('/'): ... +@app.route('/events'): ... + +# 主函数修改 +def main(): + if args.preview: + # 启动预览服务器 + start_preview_server() + else: + # 生成 PPTX（现有逻辑） + generate_pptx() +``` + +**理由**: +- 清晰分离两种模式的逻辑 +- 不影响现有代码的可读性 +- 易于维护和测试 + +## Risks / Trade-offs + +### 风险 1: HTML/CSS 渲染与 PPTX 渲染存在差异 + +**风险**: 预览效果与最终 PPTX 可能不完全一致（字体渲染、间距、换行等） + +**缓解措施**: +- 在文档中明确说明预览仅供参考 +- 使用相同的单位系统（pt、英寸）尽量保持一致 +- 提供快速生成 PPTX 的方式进行最终确认 + +### 风险 2: 依赖增加 + +**风险**: 新增 `flask` 和 `watchdog` 依赖，增加脚本启动时间和依赖管理复杂度 + +**缓解措施**: +- 使用 uv 的 Inline script metadata 自动管理依赖 +- 仅在预览模式下导入 Flask 和 watchdog（延迟导入） +- 依赖都是轻量级库，影响较小 + +### 风险 3: 端口冲突 + +**风险**: 默认端口 5000 可能被其他服务占用 + +**缓解措施**: +- 提供 `--port` 参数允许用户指定端口 +- 捕获端口占用错误，提示用户更换端口 + +### 风险 4: 文件监听性能 + +**风险**: 监听大型目录可能影响性能 + +**缓解措施**: +- 仅监听 YAML 文件所在目录，不递归监听 +- 使用 watchdog 的高效事件机制 +- 添加防抖逻辑，避免短时间内多次刷新 + +### 权衡 1: 简单性 vs 功能完整性 + +**权衡**: 选择简单的实现方案，牺牲一些高级功能（如元素交互、网格线、标尺等） + +**理由**: 预览功能的核心价值是快速反馈，简单实现可以更快交付，后续可根据需求迭代 + +### 权衡 2: 精确性 vs 速度 + +**权衡**: 使用 HTML/CSS 渲染而不是生成 PPTX 再转图片，牺牲精确性换取速度 + +**理由**: 实时预览的核心是速度，用户可以随时生成 PPTX 进行精确确认 + +## Migration Plan + +### 部署步骤 + +1. 在 `yaml2pptx.py` 的 Inline script metadata 中添加依赖： + ```python + # dependencies = [ + # "python-pptx", + # "pyyaml", + # "flask", # 新增 + # "watchdog", # 新增 + # ] + ``` + +2. 添加预览相关代码（约 200 行） + +3. 修改 `parse_args()` 函数，添加 `--preview` 和 `--port` 参数 + +4. 修改 `main()` 函数，根据参数选择模式 + +5. 更新 README.md，添加预览功能的使用说明 + +### 回滚策略 + +- 如果预览功能有问题，用户仍可使用原有的 PPTX 生成功能（完全向后兼容） +- 可以通过 git revert 回滚到之前的版本 +- 预览功能是可选的，不影响核心功能 + +### 测试计划 + +1. 单元测试：测试 HTML 渲染函数的正确性 +2. 集成测试：测试预览服务器的启动和文件监听 +3. 手动测试：在不同浏览器中测试预览效果 +4. 兼容性测试：确保不影响现有的 PPTX 生成功能 + +## Open Questions + +1. 是否需要支持多幻灯片的缩略图导航？ + - 当前方案：垂直排列显示所有幻灯片 + - 可选方案：添加左侧缩略图导航栏 + +2. 是否需要支持深色模式？ + - 当前方案：仅支持浅色背景 + - 可选方案：添加深色模式切换 + +3. 是否需要显示元素边框和尺寸标注？ + - 当前方案：不显示辅助信息 + - 可选方案：添加调试模式，显示元素边框和尺寸 + +这些问题可以在实现后根据用户反馈决定是否添加。 diff --git a/openspec/changes/archive/2026-03-02-add-browser-preview/proposal.md b/openspec/changes/archive/2026-03-02-add-browser-preview/proposal.md new file mode 100644 index 0000000..518b998 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-browser-preview/proposal.md @@ -0,0 +1,50 @@ +## Why + +当前工作流程中，每次编辑 YAML 文件后，需要手动运行 `yaml2pptx.py` 生成 PPTX 文件，然后在 Keynote 或 PowerPoint 中打开查看效果。这个反馈循环较慢，需要频繁切换应用程序，降低了内容创作和调试的效率。添加浏览器实时预览功能可以让用户在编辑 YAML 时立即看到效果，大幅提升开发体验。 + +## What Changes + +- 在 `yaml2pptx.py` 中添加 `--preview` 参数，启用浏览器预览模式 +- 使用 Flask 提供 Web 服务，动态生成 HTML 预览 +- 使用 Server-Sent Events (SSE) 实现浏览器自动刷新 +- 使用 watchdog 监听 YAML 文件变化 +- 复用现有的 YAML 解析和模板渲染逻辑 +- 将 YAML 元素转换为 HTML/CSS 进行渲染 +- 新增依赖：`flask`、`watchdog`（添加到脚本的 Inline script metadata） +- 保持向后兼容，不影响现有的 PPTX 生成功能 + +## Capabilities + +### New Capabilities + +- `browser-preview-server`: 浏览器预览服务器，负责启动 Web 服务、文件监听、SSE 事件推送 +- `html-rendering`: HTML 渲染系统，负责将 YAML 元素（文本、形状、表格、图片）转换为 HTML/CSS + +### Modified Capabilities + +无。此变更不修改现有能力的需求，仅复用 `yaml-parsing` 和 `template-system` 的功能。 + +## Impact + +### 修改文件 +- `yaml2pptx.py`: 添加预览服务器功能（约 200 行新增代码） + - 新增 `--preview` 命令行参数 + - 新增 Flask 路由和 SSE 事件流 + - 新增 HTML 渲染函数 + - 新增文件监听逻辑 + +### 依赖变化 +- 在 `yaml2pptx.py` 的 Inline script metadata 中新增依赖：`flask`、`watchdog` +- 使用 uv 自动管理依赖，无需手动安装 + +### 现有功能 +- 完全向后兼容，不影响现有的 PPTX 生成功能 +- 复用 `Presentation` 类和 YAML 解析逻辑 +- 不修改现有的模板系统和元素渲染逻辑 + +### 用户体验 +- 生成 PPTX：`uv run yaml2pptx.py input.yaml` （保持不变） +- 浏览器预览：`uv run yaml2pptx.py input.yaml --preview` （新增） +- 预览模式下浏览器自动打开预览页面 +- 编辑 YAML 文件后浏览器自动刷新 +- 预览效果与最终 PPTX 可能存在细微差异（HTML/CSS vs PPTX 渲染） diff --git a/openspec/changes/archive/2026-03-02-add-browser-preview/specs/browser-preview-server/spec.md b/openspec/changes/archive/2026-03-02-add-browser-preview/specs/browser-preview-server/spec.md new file mode 100644 index 0000000..fca55c6 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-browser-preview/specs/browser-preview-server/spec.md @@ -0,0 +1,186 @@ +# Browser Preview Server + +## Purpose + +Browser Preview Server 负责提供浏览器实时预览功能，包括启动 Web 服务、监听 YAML 文件变化、通过 Server-Sent Events (SSE) 推送更新通知到浏览器。它是预览模式的核心组件，协调文件监听、HTML 生成和浏览器刷新的整个流程。 + +## ADDED Requirements + +### Requirement: 系统必须支持通过命令行参数启用预览模式 + +系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。 + +#### Scenario: 使用 --preview 参数启动预览服务器 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview` +- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件 + +#### Scenario: 不使用 --preview 参数时保持原有行为 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml` +- **THEN** 系统生成 PPTX 文件，不启动预览服务器 + +#### Scenario: --preview 参数与其他参数兼容 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates` +- **THEN** 系统启动预览服务器，并使用指定的模板目录 + +### Requirement: 系统必须提供 HTTP 服务 + +系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。 + +#### Scenario: 启动 HTTP 服务器 + +- **WHEN** 预览模式启动 +- **THEN** 系统在默认端口 5000 启动 Flask HTTP 服务器 + +#### Scenario: 自定义端口 + +- **WHEN** 用户使用 `--port 8080` 参数 +- **THEN** 系统在端口 8080 启动 HTTP 服务器 + +#### Scenario: 端口被占用时报错 + +- **WHEN** 指定的端口已被其他服务占用 +- **THEN** 系统抛出错误，提示端口被占用，建议使用 `--port` 参数指定其他端口 + +#### Scenario: 提供主页面路由 + +- **WHEN** 浏览器访问 `http://localhost:5000/` +- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面 + +### Requirement: 系统必须监听 YAML 文件变化 + +系统 SHALL 使用 watchdog 监听 YAML 文件所在目录，检测文件修改事件。 + +#### Scenario: 监听 YAML 文件修改 + +- **WHEN** 用户修改并保存 YAML 文件 +- **THEN** 系统检测到文件变化事件 + +#### Scenario: 监听模板文件修改 + +- **WHEN** 用户修改并保存模板文件（如 `templates/title_slide.yaml`） +- **THEN** 系统检测到文件变化事件 + +#### Scenario: 忽略非 YAML 文件变化 + +- **WHEN** 用户修改其他类型的文件（如 `.txt`、`.md`） +- **THEN** 系统不触发预览更新 + +#### Scenario: 防抖处理 + +- **WHEN** 用户在短时间内多次保存文件（如 1 秒内保存 3 次） +- **THEN** 系统仅触发一次预览更新，避免频繁刷新 + +### Requirement: 系统必须通过 SSE 推送更新通知 + +系统 SHALL 提供 Server-Sent Events (SSE) 端点，当文件变化时推送更新通知到浏览器。 + +#### Scenario: 提供 SSE 端点 + +- **WHEN** 浏览器连接到 `http://localhost:5000/events` +- **THEN** 系统建立 SSE 连接，保持连接打开 + +#### Scenario: 文件变化时推送更新 + +- **WHEN** 检测到 YAML 文件变化 +- **THEN** 系统通过 SSE 连接发送 `data: reload` 消息到所有连接的浏览器 + +#### Scenario: 浏览器接收更新后自动刷新 + +- **WHEN** 浏览器接收到 `reload` 消息 +- **THEN** 浏览器自动刷新页面，显示最新的预览内容 + +#### Scenario: SSE 连接断开时自动重连 + +- **WHEN** SSE 连接因网络问题断开 +- **THEN** 浏览器自动尝试重新连接到 SSE 端点 + +### Requirement: 系统必须自动打开浏览器 + +系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。 + +#### Scenario: 启动后自动打开浏览器 + +- **WHEN** 预览服务器启动成功 +- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/` + +#### Scenario: 浏览器打开失败时提示 URL + +- **WHEN** 系统无法自动打开浏览器（如无图形界面环境） +- **THEN** 系统在终端输出预览 URL，提示用户手动打开 + +### Requirement: 系统必须提供清晰的日志输出 + +系统 SHALL 在终端输出清晰的日志信息，帮助用户了解预览服务器的状态。 + +#### Scenario: 启动时输出日志 + +- **WHEN** 预览服务器启动 +- **THEN** 系统输出以下信息： + - 正在监听的 YAML 文件路径 + - 预览服务器的 URL + - 停止服务器的方法（按 Ctrl+C） + +#### Scenario: 文件变化时输出日志 + +- **WHEN** 检测到文件变化 +- **THEN** 系统输出 `[INFO] 检测到文件变化: <文件路径>` + +#### Scenario: 错误时输出日志 + +- **WHEN** 发生错误（如 YAML 解析错误） +- **THEN** 系统输出 `[ERROR]` 级别的日志，包含错误详情 + +### Requirement: 系统必须支持优雅退出 + +系统 SHALL 支持通过 Ctrl+C 优雅地停止预览服务器。 + +#### Scenario: 按 Ctrl+C 停止服务器 + +- **WHEN** 用户按下 Ctrl+C +- **THEN** 系统停止文件监听和 HTTP 服务器，输出 `[INFO] 已停止`，然后退出 + +#### Scenario: 停止时清理资源 + +- **WHEN** 服务器停止 +- **THEN** 系统关闭所有 SSE 连接，停止 watchdog 监听器，释放端口 + +### Requirement: 系统必须处理 YAML 解析错误 + +系统 SHALL 在 YAML 解析失败时，在预览页面显示友好的错误信息，而不是崩溃。 + +#### Scenario: YAML 语法错误时显示错误页面 + +- **WHEN** YAML 文件存在语法错误（如缺少冒号、缩进错误） +- **THEN** 系统在预览页面显示错误信息，包括错误类型和行号 + +#### Scenario: 错误修复后自动恢复 + +- **WHEN** 用户修复 YAML 错误并保存 +- **THEN** 系统检测到文件变化，重新解析 YAML，显示正常的预览内容 + +#### Scenario: 错误页面仍然监听文件变化 + +- **WHEN** 预览页面显示错误信息 +- **THEN** 系统继续监听文件变化，等待用户修复错误 + +### Requirement: 系统必须支持多幻灯片预览 + +系统 SHALL 在预览页面中显示所有幻灯片，支持用户查看完整的演示文稿。 + +#### Scenario: 垂直排列显示所有幻灯片 + +- **WHEN** YAML 文件包含多个幻灯片 +- **THEN** 系统在预览页面中垂直排列显示所有幻灯片，每个幻灯片之间有间距 + +#### Scenario: 显示幻灯片编号 + +- **WHEN** 预览页面显示幻灯片 +- **THEN** 每个幻灯片右下角显示编号（如 "幻灯片 1"、"幻灯片 2"） + +#### Scenario: 幻灯片尺寸一致 + +- **WHEN** 预览页面显示多个幻灯片 +- **THEN** 所有幻灯片使用相同的尺寸（960x540 像素，16:9 比例） diff --git a/openspec/changes/archive/2026-03-02-add-browser-preview/specs/html-rendering/spec.md b/openspec/changes/archive/2026-03-02-add-browser-preview/specs/html-rendering/spec.md new file mode 100644 index 0000000..958e9ee --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-browser-preview/specs/html-rendering/spec.md @@ -0,0 +1,236 @@ +# HTML Rendering + +## Purpose + +HTML Rendering 系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 HTML/CSS 代码，在浏览器中显示。它复用现有的 YAML 解析和模板渲染逻辑，但将输出目标从 PPTX 改为 HTML/CSS，提供快速的预览体验。 + +## ADDED Requirements + +### Requirement: 系统必须将 YAML 元素转换为 HTML + +系统 SHALL 将解析后的 YAML 元素转换为 HTML 代码，在浏览器中渲染。 + +#### Scenario: 生成完整的 HTML 页面 + +- **WHEN** 浏览器请求预览页面 +- **THEN** 系统生成包含 HTML、CSS 和 JavaScript 的完整页面 + +#### Scenario: 动态生成 HTML + +- **WHEN** YAML 文件变化 +- **THEN** 系统重新解析 YAML，动态生成新的 HTML 内容，无需生成中间文件 + +#### Scenario: HTML 页面包含 SSE 客户端代码 + +- **WHEN** 生成 HTML 页面 +- **THEN** 页面包含 JavaScript 代码，连接到 SSE 端点，监听更新事件 + +### Requirement: 系统必须使用固定 DPI 进行单位转换 + +系统 SHALL 使用固定 DPI (96) 将 YAML 中的英寸单位转换为 CSS 像素单位。 + +#### Scenario: 英寸转换为像素 + +- **WHEN** 元素定义 `box: [1, 2, 8, 3]`（单位为英寸） +- **THEN** 系统转换为 CSS：`left: 96px; top: 192px; width: 768px; height: 288px` + +#### Scenario: 幻灯片尺寸固定 + +- **WHEN** 渲染 16:9 幻灯片 +- **THEN** 系统使用固定尺寸 960x540 像素（10 英寸 x 5.625 英寸 x 96 DPI） + +#### Scenario: 4:3 幻灯片尺寸 + +- **WHEN** 渲染 4:3 幻灯片 +- **THEN** 系统使用固定尺寸 960x720 像素（10 英寸 x 7.5 英寸 x 96 DPI） + +### Requirement: 系统必须渲染文本元素 + +系统 SHALL 将 YAML 中的文本元素转换为 HTML `
` 标签，应用相应的样式。 + +#### Scenario: 渲染基本文本元素 + +- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}` +- **THEN** 系统生成 `
` 标签，内容为 "Hello"，位置为 (96px, 192px)，尺寸为 768x288 像素 + +#### Scenario: 应用文本字体样式 + +- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}` +- **THEN** 系统应用 CSS：`font-size: 32pt; font-weight: bold; color: #333333` + +#### Scenario: 应用文本对齐方式 + +- **WHEN** 文本元素定义了 `font: {align: center}` +- **THEN** 系统应用 CSS：`text-align: center` + +#### Scenario: 支持多行文本 + +- **WHEN** 文本内容包含换行符（`\n`） +- **THEN** 系统使用 `white-space: pre-wrap` 保留换行 + +#### Scenario: 使用 pt 单位表示字体大小 + +- **WHEN** 文本字体大小为 44 +- **THEN** 系统使用 CSS：`font-size: 44pt`（与 PPTX 保持一致） + +### Requirement: 系统必须渲染形状元素 + +系统 SHALL 将 YAML 中的形状元素转换为 HTML `
` 标签，使用 CSS 样式模拟形状。 + +#### Scenario: 渲染矩形形状 + +- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}` +- **THEN** 系统生成 `
` 标签，背景色为 #4a90e2，`border-radius: 0` + +#### Scenario: 渲染圆形形状 + +- **WHEN** 元素的 `shape` 字段为 `ellipse` +- **THEN** 系统应用 CSS：`border-radius: 50%` + +#### Scenario: 渲染圆角矩形 + +- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle` +- **THEN** 系统应用 CSS：`border-radius: 8px` + +#### Scenario: 应用形状边框样式 + +- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}` +- **THEN** 系统应用 CSS：`border: 2pt solid #000000` + +#### Scenario: 形状无填充色时透明 + +- **WHEN** 形状未定义 `fill` 字段 +- **THEN** 系统应用 CSS：`background: transparent` + +### Requirement: 系统必须渲染表格元素 + +系统 SHALL 将 YAML 中的表格元素转换为 HTML `
` 标签。 + +#### Scenario: 渲染基本表格 + +- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}` +- **THEN** 系统生成 `
` 标签，位置为 (96px, 192px)，包含 2 行 2 列 + +#### Scenario: 应用表格样式 + +- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}` +- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色，字体大小为 14pt + +#### Scenario: 表格单元格边框 + +- **WHEN** 渲染表格 +- **THEN** 系统为所有单元格添加边框：`border: 1px solid #ddd` + +#### Scenario: 表格单元格内边距 + +- **WHEN** 渲染表格 +- **THEN** 系统为所有单元格添加内边距：`padding: 8px` + +### Requirement: 系统必须渲染图片元素 + +系统 SHALL 将 YAML 中的图片元素转换为 HTML `` 标签。 + +#### Scenario: 渲染本地图片 + +- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}` +- **THEN** 系统生成 `` 标签，src 为图片的文件路径，位置为 (192px, 288px)，尺寸为 384x288 像素 + +#### Scenario: 处理相对路径 + +- **WHEN** 图片 src 使用相对路径 `"assets/logo.png"` +- **THEN** 系统基于 YAML 文件所在目录解析相对路径 + +#### Scenario: 图片不存在时显示占位符 + +- **WHEN** 图片文件不存在 +- **THEN** 系统显示占位符或错误提示，而不是崩溃 + +### Requirement: 系统必须渲染幻灯片背景 + +系统 SHALL 支持为幻灯片设置纯色背景。 + +#### Scenario: 设置纯色背景 + +- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}` +- **THEN** 系统为幻灯片容器应用 CSS：`background: #ffffff` + +#### Scenario: 无背景时使用白色 + +- **WHEN** 幻灯片未定义 `background` 字段 +- **THEN** 系统使用默认白色背景 + +### Requirement: 系统必须使用绝对定位 + +系统 SHALL 使用 CSS 绝对定位（`position: absolute`）渲染所有元素，模拟 PPTX 的坐标系统。 + +#### Scenario: 元素使用绝对定位 + +- **WHEN** 渲染任何元素 +- **THEN** 系统应用 CSS：`position: absolute` + +#### Scenario: 幻灯片容器使用相对定位 + +- **WHEN** 渲染幻灯片容器 +- **THEN** 系统应用 CSS：`position: relative`，作为元素的定位上下文 + +#### Scenario: 元素层次按定义顺序 + +- **WHEN** elements 列表为 `[shape1, text1, image1]` +- **THEN** 系统按顺序渲染，后定义的元素显示在前面元素之上（通过 DOM 顺序控制） + +### Requirement: 系统必须提供视觉反馈 + +系统 SHALL 在预览页面中提供视觉反馈，帮助用户了解预览状态。 + +#### Scenario: 显示实时预览状态指示器 + +- **WHEN** 预览页面加载 +- **THEN** 页面右上角显示绿色的 "● 实时预览" 状态指示器 + +#### Scenario: 幻灯片添加阴影效果 + +- **WHEN** 渲染幻灯片 +- **THEN** 系统为幻灯片容器添加阴影：`box-shadow: 0 2px 8px rgba(0,0,0,0.1)` + +#### Scenario: 幻灯片之间有间距 + +- **WHEN** 渲染多个幻灯片 +- **THEN** 每个幻灯片之间有 20px 的垂直间距 + +### Requirement: 系统必须复用现有的解析逻辑 + +系统 SHALL 复用 `yaml2pptx.py` 中现有的 `Presentation` 类和模板渲染逻辑。 + +#### Scenario: 使用 Presentation 类解析 YAML + +- **WHEN** 预览模式启动 +- **THEN** 系统使用 `Presentation` 类加载和解析 YAML 文件 + +#### Scenario: 使用 render_slide 方法渲染幻灯片 + +- **WHEN** 生成预览 HTML +- **THEN** 系统调用 `Presentation.render_slide()` 方法获取渲染后的幻灯片数据 + +#### Scenario: 支持模板系统 + +- **WHEN** YAML 文件使用模板（如 `template: title_slide`） +- **THEN** 系统正确解析模板变量，渲染模板元素 + +### Requirement: 系统必须处理渲染错误 + +系统 SHALL 在元素渲染失败时，显示错误信息，而不是崩溃。 + +#### Scenario: 元素类型不支持时显示错误 + +- **WHEN** 元素的 `type` 为未定义的值（如 "video"） +- **THEN** 系统在预览页面显示错误信息，提示不支持该元素类型 + +#### Scenario: 元素缺少必需字段时显示错误 + +- **WHEN** 元素缺少必需字段（如文本元素缺少 `content`） +- **THEN** 系统在预览页面显示错误信息，提示缺少字段 + +#### Scenario: 部分元素错误不影响其他元素 + +- **WHEN** 某个元素渲染失败 +- **THEN** 系统继续渲染其他元素，仅在失败位置显示错误提示 diff --git a/openspec/changes/archive/2026-03-02-add-browser-preview/tasks.md b/openspec/changes/archive/2026-03-02-add-browser-preview/tasks.md new file mode 100644 index 0000000..3761399 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-browser-preview/tasks.md @@ -0,0 +1,79 @@ +## 1. 准备工作 + +- [x] 1.1 在 `yaml2pptx.py` 的 Inline script metadata 中添加 `flask` 和 `watchdog` 依赖 +- [x] 1.2 在文件顶部添加预览模式相关的导入语句（使用条件导入，仅在预览模式下导入） + +## 2. 命令行参数 + +- [x] 2.1 在 `parse_args()` 函数中添加 `--preview` 参数（布尔类型，默认 False） +- [x] 2.2 在 `parse_args()` 函数中添加 `--port` 参数（整数类型，默认 5000） + +## 3. HTML 渲染函数 + +- [x] 3.1 实现 `render_text_element_to_html(elem)` 函数，将文本元素转换为 HTML `
` 标签 +- [x] 3.2 实现 `render_shape_element_to_html(elem)` 函数，将形状元素转换为 HTML `
` 标签 +- [x] 3.3 实现 `render_table_element_to_html(elem)` 函数，将表格元素转换为 HTML `
` 标签 +- [x] 3.4 实现 `render_image_element_to_html(elem, base_path)` 函数，将图片元素转换为 HTML `` 标签 +- [x] 3.5 实现 `render_slide_to_html(slide_data, index)` 函数，渲染单个幻灯片为 HTML +- [x] 3.6 实现 `generate_preview_html(yaml_file, template_dir)` 函数，生成完整的预览 HTML 页面 + +## 4. HTML 模板 + +- [x] 4.1 定义 `HTML_TEMPLATE` 常量，包含完整的 HTML 页面结构、CSS 样式和 SSE 客户端 JavaScript +- [x] 4.2 定义 `ERROR_TEMPLATE` 常量，用于显示 YAML 解析错误 + +## 5. Flask 应用 + +- [x] 5.1 创建 Flask 应用实例 `app = Flask(__name__)` +- [x] 5.2 实现主页面路由 `@app.route('/')`，返回预览 HTML +- [x] 5.3 实现 SSE 事件流路由 `@app.route('/events')`，推送文件变化通知 + +## 6. 文件监听 + +- [x] 6.1 实现 `YAMLChangeHandler` 类，继承 `FileSystemEventHandler` +- [x] 6.2 在 `on_modified()` 方法中检测 `.yaml` 文件变化，推送更新通知到队列 +- [x] 6.3 创建全局队列 `change_queue = queue.Queue()` 用于通知文件变化 + +## 7. 预览服务器启动 + +- [x] 7.1 实现 `start_preview_server(yaml_file, template_dir, port)` 函数 +- [x] 7.2 在函数中启动 watchdog 监听器，监听 YAML 文件所在目录 +- [x] 7.3 在函数中使用 `webbrowser.open()` 自动打开浏览器 +- [x] 7.4 在函数中启动 Flask 应用，监听指定端口 +- [x] 7.5 添加 Ctrl+C 信号处理，优雅退出服务器 + +## 8. 主函数修改 + +- [x] 8.1 在 `main()` 函数中添加条件判断：`if args.preview:` +- [x] 8.2 在预览模式分支中调用 `start_preview_server()` +- [x] 8.3 在非预览模式分支中保持原有的 PPTX 生成逻辑 + +## 9. 错误处理 + +- [x] 9.1 在预览 HTML 生成中捕获 `YAMLError`，返回错误页面 +- [x] 9.2 在 Flask 路由中添加异常处理，避免服务器崩溃 +- [x] 9.3 在端口占用时捕获异常，提示用户使用 `--port` 参数 + +## 10. 日志输出 + +- [x] 10.1 在预览服务器启动时输出日志：监听的文件路径、预览 URL、停止方法 +- [x] 10.2 在文件变化时输出日志：`[INFO] 检测到文件变化: <文件路径>` +- [x] 10.3 在服务器停止时输出日志：`[INFO] 已停止` + +## 11. 测试 + +- [x] 11.1 测试基本功能：启动预览服务器，浏览器自动打开 +- [x] 11.2 测试文件监听：修改 YAML 文件，浏览器自动刷新 +- [x] 11.3 测试模板支持：使用模板的 YAML 文件能正确预览 +- [x] 11.4 测试错误处理：YAML 语法错误时显示错误页面 +- [x] 11.5 测试所有元素类型：文本、形状、表格、图片都能正确渲染 +- [x] 11.6 测试多幻灯片：多个幻灯片垂直排列显示 +- [x] 11.7 测试向后兼容：不使用 `--preview` 参数时，PPTX 生成功能正常 +- [x] 11.8 测试自定义端口：`--port` 参数能正确指定端口 +- [x] 11.9 测试 Ctrl+C 退出：能优雅停止服务器 + +## 12. 文档更新 + +- [x] 12.1 在 README.md 中添加预览功能的使用说明 +- [x] 12.2 在 README.md 中添加预览功能的示例命令 +- [x] 12.3 在 README.md 中说明预览效果与 PPTX 可能存在差异 diff --git a/openspec/changes/archive/2026-03-02-add-template-dir-parameter/.openspec.yaml b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/.openspec.yaml new file mode 100644 index 0000000..fd79bfc --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-02 diff --git a/openspec/changes/archive/2026-03-02-add-template-dir-parameter/design.md b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/design.md new file mode 100644 index 0000000..936eb97 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/design.md @@ -0,0 +1,201 @@ +## Context + +当前 `yaml2pptx.py` 脚本的模板系统使用硬编码的相对路径 `templates_dir='templates'` 作为默认值。这导致脚本只能在包含 templates 目录的特定位置运行，限制了可移植性。 + +**当前实现**（184-196行）： +```python +def __init__(self, template_file, templates_dir='templates'): + template_path = Path(template_file) + if not template_path.is_absolute() and not template_path.exists(): + template_path = Path(templates_dir) / f"{template_file}.yaml" +``` + +**问题**： +1. 默认值 `'templates'` 是相对于当前工作目录（CWD），不够明确 +2. 先检查当前目录是否存在同名文件，可能导致意外行为 +3. 没有验证模板名称，允许路径遍历（如 `../other/template`） +4. 错误提示不够清晰 + +**约束**： +- 脚本使用 Python 3.8+，通过 uv 运行 +- 必须支持 Mac 和 Windows 平台 +- 使用 pathlib.Path 处理路径（已在代码中使用） +- 保持向后兼容：不使用模板的用户不受影响 + +## Goals / Non-Goals + +**Goals:** +- 支持通过 `--template-dir` 参数明确指定模板目录 +- 移除隐式默认行为，使用模板时必须明确指定目录 +- 添加模板名称验证，防止路径遍历 +- 提供清晰的错误提示，告知用户查找位置和失败原因 +- 确保跨平台兼容性（Mac 和 Windows） + +**Non-Goals:** +- 不支持多个模板目录搜索路径 +- 不支持模板目录的嵌套子目录 +- 不改变模板文件格式或渲染逻辑 +- 不影响不使用模板的纯自定义幻灯片 + +## Decisions + +### 决策 1: 移除默认 templates_dir，要求明确指定 + +**选择**: `templates_dir=None`，使用模板时必须通过 `--template-dir` 指定 + +**理由**: +- **明确性**: 避免"默认在哪里找"的困惑 +- **可移植性**: 脚本可以在任何位置运行 +- **统一性**: 所有模板都从同一个明确的位置加载 + +**替代方案**: +- 方案 A: 默认为源 YAML 文件目录下的 templates/ + - ✗ 仍然是隐式行为，不够明确 + - ✗ 如果 YAML 文件和模板不在同一位置，仍然会失败 +- 方案 B: 支持多个搜索路径（如 `--template-dir dir1:dir2`） + - ✗ 增加复杂度，违背"简单统一"的设计原则 + - ✗ 可能导致模板命名冲突 + +### 决策 2: 使用 pathlib.Path 处理所有路径操作 + +**选择**: 统一使用 `pathlib.Path` 进行路径拼接、验证和存在性检查 + +**理由**: +- **跨平台**: Path 自动处理 Mac（`/`）和 Windows（`\`）的路径分隔符 +- **安全性**: Path 对象避免了字符串拼接的错误 +- **一致性**: 代码中已经在使用 Path + +**实现**: +```python +# 路径拼接（跨平台） +template_path = Path(templates_dir) / f"{template_file}.yaml" + +# 存在性检查 +if not template_path.exists(): + raise YAMLError(...) +``` + +### 决策 3: 模板名称验证 - 禁止路径分隔符 + +**选择**: 检查模板名称中是否包含 `/` 或 `\`，如果包含则报错 + +**理由**: +- **安全性**: 防止路径遍历攻击（如 `../../etc/passwd`） +- **简单性**: 只支持一层目录，逻辑清晰 +- **跨平台**: 同时检查两种路径分隔符 + +**实现**: +```python +if '/' in template_file or '\\' in template_file: + raise YAMLError( + f"模板名称不能包含路径分隔符: {template_file}\n" + f"模板名称应该是纯文件名，如: 'title-slide'" + ) +``` + +**替代方案**: +- 方案 A: 使用 `os.path.sep` 只检查当前平台的分隔符 + - ✗ 在 Windows 上创建的 YAML 文件可能包含 `/`，在 Mac 上会被忽略 + - ✗ 不够严格，可能导致跨平台问题 +- 方案 B: 使用正则表达式验证文件名格式 + - ✗ 过度设计，简单的字符串检查已足够 + +### 决策 4: 改进错误提示 - 三层信息 + +**选择**: 错误信息包含三层：问题描述、查找位置、解决建议 + +**理由**: +- **可调试性**: 用户能快速定位问题 +- **可操作性**: 提供明确的解决方案 + +**实现**: +```python +# 未指定 template_dir +raise YAMLError( + f"未指定模板目录，无法加载模板: {template_file}\n" + f"请使用 --template-dir 参数指定模板目录" +) + +# 模板文件不存在 +raise YAMLError( + f"模板文件不存在: {template_file}\n" + f"查找位置: {templates_dir}\n" + f"期望文件: {template_path}\n" + f"提示: 请检查模板名称和模板目录是否正确" +) +``` + +### 决策 5: 参数传递链 - 从 CLI 到 Template + +**选择**: `main() → Presentation() → Template()` + +**理由**: +- **清晰性**: 参数传递路径明确 +- **最小改动**: 只需修改参数默认值和传递方式 + +**实现**: +```python +# parse_args: 添加参数 +parser.add_argument('--template-dir', type=str, default=None) + +# main: 传递给 Presentation +pres = Presentation(input_path, templates_dir=args.template_dir) + +# Presentation.__init__: 传递给 Template +def __init__(self, pres_file, templates_dir=None): + self.templates_dir = templates_dir + +# Template.__init__: 使用参数 +def __init__(self, template_file, templates_dir=None): + if templates_dir is None: + raise YAMLError(...) +``` + +## Risks / Trade-offs + +### 风险 1: 破坏性变更影响现有用户 + +**风险**: 现有使用模板的用户升级后脚本会报错 + +**缓解**: +- 提供清晰的错误信息，告知用户需要添加 `--template-dir` 参数 +- 在文档中明确标注为破坏性变更 +- 错误信息中包含使用示例 + +### 风险 2: 相对路径的解析基准 + +**风险**: 用户可能不清楚相对路径是相对于哪里 + +**决策**: 相对路径相对于当前工作目录（CWD），这是命令行工具的标准行为 + +**缓解**: +- 在帮助信息中说明 +- 错误信息中显示完整的绝对路径 + +### 风险 3: Windows 路径中的反斜杠 + +**风险**: Windows 用户可能在命令行中输入 `C:\templates`，shell 可能需要转义 + +**缓解**: +- Python 的 argparse 会正确处理 +- 用户可以使用正斜杠 `C:/templates`（Windows 支持） +- 在文档中提供 Windows 示例 + +### 权衡 1: 灵活性 vs 简单性 + +**权衡**: 不支持多模板目录搜索路径，牺牲了灵活性 + +**理由**: +- 大多数用户只需要一个模板目录 +- 如果需要多个来源，可以使用符号链接或复制文件 +- 保持逻辑简单，易于理解和维护 + +### 权衡 2: 向后兼容 vs 明确性 + +**权衡**: 破坏性变更，不向后兼容 + +**理由**: +- 隐式默认行为是问题的根源 +- 明确性比兼容性更重要 +- 影响范围可控（只影响使用模板的用户） +- 修复成本低（只需添加一个参数） diff --git a/openspec/changes/archive/2026-03-02-add-template-dir-parameter/proposal.md b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/proposal.md new file mode 100644 index 0000000..a1c7d41 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/proposal.md @@ -0,0 +1,44 @@ +## Why + +当前脚本默认使用相对路径 `templates_dir='templates'` 加载模板，这限制了脚本的可移植性——脚本只能在包含 templates 目录的项目根目录下运行。为了让脚本可以在任何位置使用，需要支持通过命令行参数明确指定模板目录，并移除隐式的默认行为。 + +## What Changes + +- 添加 `--template-dir` 命令行参数，允许用户指定模板文件目录 +- **BREAKING**: 移除默认模板目录行为，使用模板时必须通过 `--template-dir` 明确指定模板目录 +- 添加模板名称验证，禁止在模板名称中使用路径分隔符（`/` 或 `\`），确保模板只能从指定目录的一层加载 +- 改进错误提示信息，明确告知用户模板查找位置和失败原因 +- 不使用模板的纯自定义幻灯片不受影响，无需指定 `--template-dir` + +## Capabilities + +### New Capabilities + +- `template-directory-cli`: 支持通过命令行参数指定模板目录，包括参数解析、路径验证、错误提示 + +### Modified Capabilities + +- `template-system`: 修改模板加载逻辑，从硬编码的 `templates/` 目录改为必须明确指定的目录；添加模板名称验证规则 + +## Impact + +**代码影响**: +- `Template.__init__` 方法（184行）：修改模板路径解析逻辑，添加名称验证 +- `Presentation.__init__` 方法（610行）：移除默认 templates_dir 参数 +- `parse_args` 函数（756行）：添加 `--template-dir` 参数定义 +- `main` 函数（775行）：传递 template_dir 参数给 Presentation + +**用户影响**: +- **破坏性变更**: 现有使用模板的用户必须在命令行添加 `--template-dir` 参数 +- 不使用模板的用户不受影响 +- 脚本可以在任何位置运行，不再依赖特定的目录结构 + +**示例**: +```bash +# 之前（只能在项目根目录运行） +uv run yaml2pptx.py presentation.yaml + +# 之后（可以在任何位置运行，但使用模板时必须指定目录） +uv run yaml2pptx.py presentation.yaml --template-dir ./templates +uv run yaml2pptx.py presentation.yaml --template-dir /path/to/templates +``` diff --git a/openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-directory-cli/spec.md b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-directory-cli/spec.md new file mode 100644 index 0000000..9f7cce3 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-directory-cli/spec.md @@ -0,0 +1,83 @@ +# Template Directory CLI + +## Purpose + +提供命令行参数支持，允许用户通过 `--template-dir` 参数明确指定模板文件目录，使脚本可以在任何位置运行而不依赖特定的目录结构。 + +## ADDED Requirements + +### Requirement: 系统必须支持 --template-dir 命令行参数 + +系统 SHALL 提供 `--template-dir` 命令行参数，允许用户指定模板文件目录的路径。 + +#### Scenario: 指定绝对路径的模板目录 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir /path/to/templates` +- **THEN** 系统使用 `/path/to/templates` 作为模板目录 + +#### Scenario: 指定相对路径的模板目录 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir ./templates` +- **THEN** 系统将相对路径解析为相对于当前工作目录（CWD）的绝对路径 + +#### Scenario: Windows 路径格式支持 + +- **WHEN** Windows 用户运行 `uv run yaml2pptx.py input.yaml --template-dir C:\Users\me\templates` +- **THEN** 系统正确解析 Windows 路径格式 + +#### Scenario: 不指定 template-dir 参数且不使用模板 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`，且 YAML 文件中所有幻灯片都是自定义幻灯片（不使用模板） +- **THEN** 系统正常处理，不报错 + +### Requirement: 使用模板时必须指定 template-dir + +系统 SHALL 在 YAML 文件中使用了模板但未指定 `--template-dir` 参数时报错。 + +#### Scenario: 使用模板但未指定 template-dir + +- **WHEN** YAML 文件中包含 `template: title-slide`，但用户未提供 `--template-dir` 参数 +- **THEN** 系统抛出错误，提示"未指定模板目录，无法加载模板: title-slide"，并建议使用 `--template-dir` 参数 + +#### Scenario: 错误信息包含使用示例 + +- **WHEN** 系统因未指定 template-dir 而报错 +- **THEN** 错误信息中包含"请使用 --template-dir 参数指定模板目录"的提示 + +### Requirement: 系统必须支持跨平台路径处理 + +系统 SHALL 正确处理 Mac 和 Windows 平台的路径格式，包括路径分隔符和路径表示。 + +#### Scenario: Mac 路径格式 + +- **WHEN** Mac 用户指定 `--template-dir /Users/me/templates` +- **THEN** 系统正确解析 Unix 风格的路径 + +#### Scenario: Windows 路径格式（反斜杠） + +- **WHEN** Windows 用户指定 `--template-dir C:\templates` +- **THEN** 系统正确解析 Windows 风格的路径 + +#### Scenario: Windows 路径格式（正斜杠） + +- **WHEN** Windows 用户指定 `--template-dir C:/templates` +- **THEN** 系统正确解析路径（Windows 支持正斜杠） + +#### Scenario: 相对路径在不同平台 + +- **WHEN** 用户在任意平台指定 `--template-dir ./templates` +- **THEN** 系统根据当前平台的规则正确解析相对路径 + +### Requirement: 参数帮助信息必须清晰 + +系统 SHALL 在 `--help` 输出中提供清晰的 `--template-dir` 参数说明。 + +#### Scenario: 查看帮助信息 + +- **WHEN** 用户运行 `uv run yaml2pptx.py --help` +- **THEN** 帮助信息中包含 `--template-dir` 参数的说明，注明"如果 YAML 中使用了模板则必须指定" + +#### Scenario: 帮助信息包含路径说明 + +- **WHEN** 用户查看 `--template-dir` 的帮助信息 +- **THEN** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）" diff --git a/openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-system/spec.md b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-system/spec.md new file mode 100644 index 0000000..0263db2 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/specs/template-system/spec.md @@ -0,0 +1,72 @@ +# Template System (Delta) + +## MODIFIED Requirements + +### Requirement: 模板文件必须可从指定目录加载 + +系统 SHALL 从用户通过 `--template-dir` 参数指定的目录加载模板文件，支持通过模板名称引用。模板名称必须是纯文件名，不能包含路径分隔符。 + +#### Scenario: 通过名称加载模板 + +- **WHEN** 幻灯片指定 `template: title-slide`，且用户提供 `--template-dir /path/to/templates` +- **THEN** 系统从 `/path/to/templates/title-slide.yaml` 加载模板文件 + +#### Scenario: 模板文件不存在时报错 + +- **WHEN** 幻灯片引用不存在的模板名称 +- **THEN** 系统抛出错误，提示"模板文件不存在: <模板名>"，并显示查找位置和期望文件路径 + +#### Scenario: 缓存已加载的模板 + +- **WHEN** 多个幻灯片使用同一个模板 +- **THEN** 系统仅加载一次模板文件，后续使用缓存 + +#### Scenario: 错误信息包含详细的查找信息 + +- **WHEN** 模板文件未找到 +- **THEN** 错误信息包含：模板名称、查找位置（template_dir）、期望文件的完整路径、解决建议 + +## ADDED Requirements + +### Requirement: 模板名称必须是纯文件名 + +系统 SHALL 验证模板名称不包含路径分隔符，确保模板只能从指定目录的一层加载。 + +#### Scenario: 拒绝包含正斜杠的模板名称 + +- **WHEN** 幻灯片指定 `template: subdir/title-slide` +- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir/title-slide" + +#### Scenario: 拒绝包含反斜杠的模板名称 + +- **WHEN** 幻灯片指定 `template: subdir\title-slide` +- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir\title-slide" + +#### Scenario: 拒绝路径遍历尝试 + +- **WHEN** 幻灯片指定 `template: ../other-templates/slide` +- **THEN** 系统抛出错误，提示模板名称不能包含路径分隔符 + +#### Scenario: 接受纯文件名 + +- **WHEN** 幻灯片指定 `template: title-slide`（不包含路径分隔符） +- **THEN** 系统正常处理，从指定的 template_dir 加载模板 + +#### Scenario: 错误信息提供正确格式示例 + +- **WHEN** 系统因模板名称包含路径分隔符而报错 +- **THEN** 错误信息中包含"模板名称应该是纯文件名，如: 'title-slide'"的提示 + +### Requirement: 未指定模板目录时必须报错 + +系统 SHALL 在用户未提供 `--template-dir` 参数但 YAML 文件中使用了模板时，立即报错。 + +#### Scenario: 使用模板但未指定目录 + +- **WHEN** YAML 文件中包含 `template: title-slide`，但 `templates_dir` 参数为 `None` +- **THEN** 系统在尝试加载模板时抛出错误，提示"未指定模板目录，无法加载模板" + +#### Scenario: 不使用模板时不检查目录 + +- **WHEN** YAML 文件中所有幻灯片都是自定义幻灯片（不包含 `template` 字段） +- **THEN** 系统不检查 `templates_dir` 是否为 `None`，正常处理 diff --git a/openspec/changes/archive/2026-03-02-add-template-dir-parameter/tasks.md b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/tasks.md new file mode 100644 index 0000000..c37ed10 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/tasks.md @@ -0,0 +1,40 @@ +## 1. 添加命令行参数 + +- [x] 1.1 在 `parse_args` 函数中添加 `--template-dir` 参数定义 +- [x] 1.2 设置参数类型为 `str`，默认值为 `None` +- [x] 1.3 添加清晰的帮助信息，说明参数用途和路径格式 + +## 2. 修改 Template 类 + +- [x] 2.1 修改 `Template.__init__` 方法签名，将 `templates_dir='templates'` 改为 `templates_dir=None` +- [x] 2.2 添加 templates_dir 为 None 的检查，抛出清晰的错误信息 +- [x] 2.3 添加模板名称验证，检查是否包含 `/` 或 `\` 路径分隔符 +- [x] 2.4 移除 `if not template_path.is_absolute() and not template_path.exists()` 的逻辑 +- [x] 2.5 直接使用 `Path(templates_dir) / f"{template_file}.yaml"` 构建模板路径 +- [x] 2.6 改进模板文件不存在时的错误信息，包含查找位置和期望路径 + +## 3. 修改 Presentation 类 + +- [x] 3.1 修改 `Presentation.__init__` 方法签名，将 `templates_dir='templates'` 改为 `templates_dir=None` +- [x] 3.2 确保 templates_dir 参数正确传递给 Template 类 + +## 4. 修改 main 函数 + +- [x] 4.1 从 `args.template_dir` 获取参数值 +- [x] 4.2 将 `templates_dir=args.template_dir` 传递给 Presentation 构造函数 + +## 5. 错误信息优化 + +- [x] 5.1 实现"未指定模板目录"错误信息，包含使用建议 +- [x] 5.2 实现"模板名称包含路径分隔符"错误信息，包含正确格式示例 +- [x] 5.3 实现"模板文件不存在"错误信息，包含查找位置、期望路径和解决建议 + +## 6. 测试验证 + +- [x] 6.1 测试不使用模板的纯自定义幻灯片（不指定 --template-dir） +- [x] 6.2 测试使用模板但未指定 --template-dir 的错误提示 +- [x] 6.3 测试使用绝对路径指定 template-dir +- [x] 6.4 测试使用相对路径指定 template-dir +- [x] 6.5 测试模板名称包含路径分隔符的错误提示 +- [x] 6.6 测试模板文件不存在的错误提示 +- [x] 6.7 在 Mac 和 Windows 上验证路径处理的跨平台兼容性 diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/.openspec.yaml b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/.openspec.yaml new file mode 100644 index 0000000..fd79bfc --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-02 diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/design.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/design.md new file mode 100644 index 0000000..86b77d8 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/design.md @@ -0,0 +1,312 @@ +## Context + +当前大模型无法直接理解 PPTX 的二进制格式（本质是 XML 压缩包），导致 AI 生成演示文稿时需要依赖付费 API 或第三方服务。 + +我们需要创建一个开源的 YAML → PPTX 转换系统，让演示文稿的"源代码"变得人类和 AI 都可读可编辑，同时保持对样式和布局的精确控制。 + +**约束条件**: +- 仅使用开源工具，不依赖付费服务 +- 使用 uv 运行 Python 脚本（项目规范） +- 面向中文开发者，代码注释使用中文 +- 原型阶段，支持核心功能即可，不追求完整的 PPTX 规范覆盖 + +**利益相关者**: +- AI 应用开发者（需要让 AI 生成 PPT） +- 内容创作者（需要批量生成或版本控制演示文稿） + +## Goals / Non-Goals + +**Goals:** +- 实现 YAML 到 PPTX 的基础转换能力 +- 支持核心元素：文本、图片、形状、表格 +- 提供主题和模板系统，减少重复配置 +- 验证 AI 能够高效生成符合格式的 YAML 源文件 +- Token 友好的 YAML Schema 设计（简洁但可读） + +**Non-Goals:** +- 不支持复杂样式（渐变、阴影、动画等） +- 不支持 PPTX 到 YAML 的反向解析（后续再考虑） +- 不追求与 PowerPoint 的 100% 兼容性 +- 不处理视频、音频等多媒体嵌入 +- 不提供 GUI 界面（命令行工具即可） + +## Decisions + +### 1. 选择 python-pptx 作为底层库 + +**决策**: 使用 python-pptx 而非 PptxGenJS + +**理由**: +- **Python 生态契合度高**: 与 AI 工具链集成更方便，YAML 解析（PyYAML）更自然 +- **读写能力**: python-pptx 支持读取现有文件（虽然原型暂不使用，但为后续反向解析留下可能性） +- **单位系统灵活**: 提供 Inches(), Cm(), Pt() 等便捷函数，符合精确控制需求 +- **文档完善**: 官方文档详尽，边界情况处理清晰 +- **符合项目规范**: uv 运行 Python 脚本是项目既定规范 + +**替代方案**: +- PptxGenJS (JavaScript): 仅能创建不能读取，且 JS 环境与项目规范不符 +- 直接操作 OOXML: 复杂度高，开发成本大，不适合原型阶段 + +### 2. 两层架构设计（已简化） + +**决策**: 采用模板（Template）+ 演示文稿（Presentation）两层架构 + +``` +模板层 (templates/*.yaml) + ↓ 定义可复用的幻灯片布局、变量占位符、颜色和样式 +演示文稿层 (presentations/*.yaml) + ↓ 实际内容，引用模板并提供变量值 +``` + +**理由**: +- **简单直观**: 颜色和样式直接在模板中定义，无需额外抽象层 +- **灵活性强**: 每个模板可以有独立的配色方案，不受主题约束 +- **AI 友好**: 大模型可以直接生成颜色值（如 #4a90e2），无需理解主题变量 +- **维护成本低**: 减少一层抽象，代码量减少约 100 行 + +**已废弃的设计**: +- ~~三层架构（主题+模板+演示文稿）~~: 增加复杂度，颜色复用场景有限 + - 主题层的抽象在实践中发现意义不大 + - 颜色和样式通常不会大量复用 + - 直接指定更符合直觉 + +**替代方案考量**: +- 扁平结构（所有配置写在一个文件）: Token 消耗大，AI 生成效率低 +- ✅ **当前方案**（模板+演示文稿）: 平衡了简洁性和可复用性 + +### 3. YAML Schema 设计原则 + +**决策**: 使用"可读版"格式，平衡 token 消耗和人类可读性 + +```yaml +# 采用的设计 +- type: text + content: "Hello" + box: [1, 2, 8, 3] # 数组形式，紧凑 + font: {size: 32, bold: true, color: "#333"} # 单行对象 + +# 拒绝的极简版（token 更少但可读性差） +- [text, "Hello", [1,2,8,3], {s:32, b:true}] + +# 拒绝的冗长版（可读性好但 token 多） +- type: text + content: "Hello" + position: + x: 1 + y: 2 + width: 8 + height: 3 + font: + size: 32 + bold: true +``` + +**理由**: +- `box: [x, y, w, h]` 紧凑且语义清晰 +- 单行对象 `{size: 32, bold: true}` 比多行嵌套节省约 50% token +- 大模型能够准确理解和生成这种结构 +- 人类阅读时仍能快速理解布局 + +### 4. 单位系统 + +**决策**: 默认使用英寸（inches），初期不支持混合单位 + +**理由**: +- python-pptx 内部使用 EMU（914,400 EMU = 1 inch），Inches() 转换最直接 +- PowerPoint 标准尺寸明确：16:9 = 10×5.625 英寸，4:3 = 10×7.5 英寸 +- 避免单位换算带来的精度损失和复杂度 +- AI 生成时，统一单位更不容易出错 + +**替代方案**: +- 百分比：响应式但精确度不足 +- 混合单位（"10%", "2cm", 3.0）：增加解析复杂度，原型不必要 + +**未来扩展**: 可在 v2 支持 `box: ["10%", "20%", "80%", "30%"]` 等灵活单位 + +### 5. 变量引用系统（已简化） + +**决策**: 仅支持模板变量引用 `{title}` + +```yaml +# 模板变量引用 +content: "{title}" +background_color: "{background_color}" + +# 颜色和样式直接指定（不再使用变量） +color: "#4a90e2" +size: 44 +``` + +**理由**: +- 简化实现，仅需处理用户提供的变量值 +- 颜色等样式值直接在模板中定义，更直观 +- 初期不支持计算表达式（如 `{spacing * 2}`），降低复杂度 + +**实现方式**: +```python +def resolve_value(value, vars_values): + pattern = r'\{([^}]+)\}' + def replacer(match): + expr = match.group(1) + if expr in vars_values: + return str(vars_values[expr]) + else: + raise YAMLError(f"未定义的变量: {expr}") + return re.sub(pattern, replacer, value) +``` + +**已移除功能**: +- ~~主题变量引用~~（`{theme.colors.primary}`） +- ~~Theme.resolve() 方法~~ + +### 6. 文件组织结构（已简化） + +**决策**: +``` +project/ +├── templates/ # 模板定义（包含颜色和样式） +│ ├── title_slide.yaml +│ ├── content_slide.yaml +│ └── two_column.yaml +├── presentations/ # 用户创建的演示文稿 +│ └── my_pres.yaml +├── assets/ # 图片等资源 +│ └── images/ +├── examples/ # 示例文件 +│ ├── demo.yaml +│ ├── custom.yaml +│ └── complex.yaml +└── yaml2pptx.py # 转换脚本（使用 uv 运行） +``` + +**理由**: +- 简化目录结构，移除 themes/ 目录 +- 模板自包含样式定义，更容易理解 +- assets/ 集中管理资源文件 + +**已移除**: +- ~~themes/ 目录~~：颜色和样式现在直接在模板中定义 + +## Risks / Trade-offs + +### 风险 1: YAML 格式复杂度 + +**风险**: YAML 的缩进敏感性可能导致 AI 生成格式错误 + +**缓解方案**: +- 提供严格的 YAML schema 验证（使用 jsonschema） +- 在错误消息中明确指出格式问题位置 +- 提供丰富的示例文件供 AI 参考 + +### 风险 2: python-pptx 功能限制 + +**风险**: python-pptx 不支持某些高级 PowerPoint 特性（如 SmartArt、自定义动画） + +**缓解方案**: +- 原型阶段明确定义支持范围（文本、图片、形状、表格） +- 在文档中清晰标注不支持的功能 +- 预留扩展接口，未来可通过直接操作 OOXML 实现高级功能 + +### 风险 3: 性能问题 + +**风险**: 大型演示文稿（100+ 页）转换可能较慢 + +**缓解方案**: +- 原型阶段不优化性能，聚焦功能验证 +- 未来可考虑并行处理、缓存模板等优化手段 + +### Trade-off: 灵活性 vs 简洁性 + +**权衡**: 模板系统提供了灵活性，但增加了学习成本 + +**选择**: 保留模板系统，因为： +- AI 生成时 token 节省显著（75%） +- 提供默认模板，降低使用门槛 +- 高级用户可自定义模板，初学者直接用现成的 + +### Trade-off: 完整性 vs 原型速度 + +**权衡**: 支持更多 PPTX 特性 vs 快速验证核心假设 + +**选择**: 原型阶段仅实现核心功能 +- 文本、图片、形状、表格已覆盖 80% 常见场景 +- 快速验证"AI 能否高效生成 YAML"这一核心假设 +- 后续根据反馈再扩展功能 + +## 实现策略 + +### 核心类设计（已简化） + +```python +class Template: + """模板类，渲染模板并替换变量""" + def __init__(self, template_file): ... + def render(self, vars_values) -> list: ... # 返回渲染后的元素列表 + def resolve_value(self, value, vars_values): ... # 仅解析模板变量 + +class Presentation: + """演示文稿类，协调模板、内容""" + def __init__(self, pres_file): ... + def render_slide(self, slide_data) -> dict: ... + +class PptxGenerator: + """PPTX 生成器，调用 python-pptx API""" + def add_slide(self, slide_data): ... + def save(self, output_file): ... +``` + +**已移除**: +- ~~Theme 类~~：不再需要主题抽象 + +### 实现阶段（已完成） + +**Phase 1: 基础框架** ✅ +1. YAML 解析和基础数据结构 +2. 简单的文本元素渲染 +3. 验证 python-pptx 基本用法 + +**Phase 2: 模板系统** ✅ +1. 模板 YAML schema 定义 +2. Template 类和变量替换（仅模板变量） +3. 创建 3 个常用模板（标题页、内容页、双栏等） + +**Phase 3: 完整元素支持** ✅ +1. 图片、形状、表格渲染 +2. 样式系统完善（颜色、字体、对齐） +3. 完整的示例演示文稿 + +**Phase 4: 简化优化** ✅ +1. 移除主题系统，简化架构 +2. 颜色和样式直接在模板中定义 +3. 更新所有文档和示例 + +## 已解决问题 + +1. **条件渲染语法**: ✅ 已实现 + - 支持简单的存在性检查：`visible: "{subtitle != ''}"` + - 仅支持简单表达式，不支持复杂逻辑 + +2. ~~**主题继承**~~: ❌ 已废弃 + - 主题系统已移除，不再需要此功能 + +3. **错误处理策略**: ✅ 已实现 + - YAML 语法错误：显示文件路径和行号 + - 文件不存在：明确提示文件路径 + - 变量未定义：清晰的错误消息 + - 颜色格式错误：提示使用 #RRGGBB 格式 + +4. **默认值机制**: ✅ 已实现 + - 必需变量未提供值且无默认值：抛出错误 + - 可选变量未提供值：使用模板定义的 default + +## 架构简化决策 + +**2026-03-02 重要变更**：移除主题系统 + +- **原因**: 颜色和样式复用场景有限，主题抽象增加复杂度 +- **变更**: 颜色、字体大小等直接在模板中定义 +- **优势**: + - 减少 ~100 行代码 + - 更直观，无需查找主题定义 + - 每个模板可独立配色 + - AI 更容易生成（直接输出颜色值） diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/proposal.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/proposal.md new file mode 100644 index 0000000..277e355 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/proposal.md @@ -0,0 +1,38 @@ +## Why + +大模型无法直接读取或理解 PPTX 二进制文档格式，导致 AI 无法有效生成和编辑演示文稿。我们需要一个人类和 AI 都能轻松理解、编辑的源文件格式（YAML），通过脚本转换为 PPTX，从而让 AI 能够高效生成高质量的演示文稿。 + +## What Changes + +- 实现 YAML 到 PPTX 的转换脚本原型 +- 支持模板系统（template）+ 演示文稿（presentation）两层架构 +- 实现核心 PPTX 元素生成：文本、图片、形状、表格 +- 提供精确的布局控制（基于英寸单位） +- 创建示例模板，颜色和样式直接在模板中定义 +- 使用 Python + python-pptx 库实现，遵循项目规范（uv 运行） + +## Capabilities + +### New Capabilities + +- `yaml-parsing`: YAML 文件解析和数据结构验证，支持演示文稿、模板两种类型的 YAML 文件 +- `template-system`: 模板系统，支持可复用的幻灯片布局、变量替换、条件渲染，颜色和样式直接在模板中定义 +- `element-rendering`: 元素渲染系统，将 YAML 中定义的元素（文本、图片、形状、表格）转换为 PPTX 对象 +- `pptx-generation`: PPTX 文件生成，基于 python-pptx 库创建完整的演示文稿文件 + +### Modified Capabilities + +无（新项目） + +## Impact + +- **新增依赖**: python-pptx, PyYAML +- **新增文件结构**: + - `templates/` - 模板定义目录（颜色和样式直接在模板中定义） + - `presentations/` - 演示文稿源文件目录 + - `yaml2pptx.py` - 核心转换脚本 + - `examples/` - 示例文件 + - `assets/` - 资源文件目录（图片等） +- **运行环境**: 使用 uv 运行 Python 脚本，遵循项目规范 +- **设计理念**: 简化系统，移除主题抽象层，颜色和样式直接在模板中指定 +- **无现有代码影响**: 这是一个独立的新功能原型 diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/element-rendering/spec.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/element-rendering/spec.md new file mode 100644 index 0000000..c8f82dc --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/element-rendering/spec.md @@ -0,0 +1,168 @@ +## ADDED Requirements + +### Requirement: 系统必须支持文本元素渲染 + +系统 SHALL 将 YAML 中定义的文本元素渲染为 PPTX 文本框。 + +#### Scenario: 渲染基本文本元素 + +- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}` +- **THEN** 系统在幻灯片的 (1, 2) 位置创建 8×3 英寸的文本框，内容为 "Hello" + +#### Scenario: 应用文本字体样式 + +- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}` +- **THEN** 系统将文本设置为 32pt、粗体、颜色为 #333333 + +#### Scenario: 应用文本对齐方式 + +- **WHEN** 文本元素定义了 `font: {align: center}` +- **THEN** 系统将文本设置为居中对齐 + +#### Scenario: 支持多种对齐方式 + +- **WHEN** 文本对齐方式为 `left`、`center`、`right` 之一 +- **THEN** 系统正确应用对应的对齐方式 + +### Requirement: 系统必须支持图片元素渲染 + +系统 SHALL 将 YAML 中定义的图片元素渲染为 PPTX 图片对象。 + +#### Scenario: 渲染本地图片 + +- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}` +- **THEN** 系统从指定路径加载图片，在 (2, 3) 位置渲染为 4×3 英寸大小 + +#### Scenario: 图片文件不存在时报错 + +- **WHEN** 图片 src 指向不存在的文件路径 +- **THEN** 系统抛出错误，明确指出图片文件未找到 + +#### Scenario: 图片格式不支持时报错 + +- **WHEN** 图片文件格式不被 python-pptx 支持 +- **THEN** 系统抛出错误，提示图片格式不支持，并列出支持的格式 + +#### Scenario: 相对路径处理 + +- **WHEN** 图片 src 使用相对路径 `"assets/images/logo.png"` +- **THEN** 系统基于演示文稿文件所在目录解析相对路径 + +### Requirement: 系统必须支持形状元素渲染 + +系统 SHALL 将 YAML 中定义的形状元素渲染为 PPTX 形状对象。 + +#### Scenario: 渲染矩形形状 + +- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}` +- **THEN** 系统在 (1, 2) 位置创建 3×1 英寸的矩形，填充颜色为 #4a90e2 + +#### Scenario: 渲染圆形形状 + +- **WHEN** 元素的 `shape` 字段为 `ellipse` +- **THEN** 系统渲染椭圆/圆形形状 + +#### Scenario: 渲染圆角矩形 + +- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle` +- **THEN** 系统渲染圆角矩形形状 + +#### Scenario: 应用形状边框样式 + +- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}` +- **THEN** 系统为形状添加黑色、2pt 宽度的边框 + +### Requirement: 系统必须支持表格元素渲染 + +系统 SHALL 将 YAML 中定义的表格元素渲染为 PPTX 表格对象。 + +#### Scenario: 渲染基本表格 + +- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}` +- **THEN** 系统在 (1, 2) 位置创建 2×2 表格，列宽各为 2 英寸 + +#### Scenario: 应用表格样式 + +- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}` +- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色 + +#### Scenario: 表格数据为空时报错 + +- **WHEN** 表格的 `data` 字段为空数组 +- **THEN** 系统抛出错误，提示表格数据不能为空 + +#### Scenario: 表格列宽不匹配时报错 + +- **WHEN** `col_widths` 数组长度与表格列数不一致 +- **THEN** 系统抛出错误，要求列宽数量与列数匹配 + +### Requirement: 元素位置必须使用英寸单位 + +系统 SHALL 将元素的 box 或 position 字段中的数值解释为英寸单位。 + +#### Scenario: box 数组表示位置和尺寸 + +- **WHEN** 元素定义了 `box: [1, 2, 8, 3]` +- **THEN** 系统将其解释为 x=1英寸, y=2英寸, width=8英寸, height=3英寸 + +#### Scenario: position 数组表示位置 + +- **WHEN** 表格元素定义了 `position: [1, 2]` +- **THEN** 系统将其解释为 x=1英寸, y=2英寸 + +#### Scenario: 负数坐标值报错 + +- **WHEN** box 或 position 包含负数值 +- **THEN** 系统抛出错误，要求坐标值必须为非负数 + +### Requirement: 系统必须支持幻灯片背景设置 + +系统 SHALL 支持为幻灯片设置纯色背景或图片背景。 + +#### Scenario: 设置纯色背景 + +- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}` +- **THEN** 系统将幻灯片背景设置为白色 + +#### Scenario: 设置图片背景 + +- **WHEN** 幻灯片定义了 `background: {image: "bg.png"}` +- **THEN** 系统使用指定图片作为幻灯片背景 + +#### Scenario: 背景图片不存在时报错 + +- **WHEN** 背景图片路径不存在 +- **THEN** 系统抛出错误，提示背景图片文件未找到 + +### Requirement: 系统必须处理元素重叠和层次 + +系统 SHALL 按照元素在 elements 列表中的顺序渲染，后定义的元素显示在前面元素之上。 + +#### Scenario: 元素按定义顺序渲染 + +- **WHEN** elements 列表为 `[shape1, text1, image1]` +- **THEN** 系统先渲染 shape1，再渲染 text1，最后渲染 image1（image1 在最上层） + +#### Scenario: 重叠元素的显示层次 + +- **WHEN** 两个元素的位置有重叠 +- **THEN** 后定义的元素遮盖先定义的元素 + +### Requirement: 系统必须验证元素类型 + +系统 SHALL 验证每个元素的 type 字段，仅支持已定义的元素类型。 + +#### Scenario: 支持的元素类型 + +- **WHEN** 元素的 `type` 为 `text`、`image`、`shape`、`table` 之一 +- **THEN** 系统正常渲染该元素 + +#### Scenario: 不支持的元素类型报错 + +- **WHEN** 元素的 `type` 为未定义的值（如 "video"） +- **THEN** 系统抛出错误，提示不支持该元素类型，并列出支持的类型 + +#### Scenario: 缺少 type 字段报错 + +- **WHEN** 元素未定义 `type` 字段 +- **THEN** 系统抛出错误，要求每个元素必须包含 type 字段 diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/pptx-generation/spec.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/pptx-generation/spec.md new file mode 100644 index 0000000..c1d872f --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/pptx-generation/spec.md @@ -0,0 +1,215 @@ +## ADDED Requirements + +### Requirement: 系统必须创建符合 OOXML 标准的 PPTX 文件 + +系统 SHALL 使用 python-pptx 库生成符合 Office Open XML (OOXML) 标准的 .pptx 文件。 + +#### Scenario: 生成的 PPTX 文件可被 PowerPoint 打开 + +- **WHEN** 系统生成 PPTX 文件 +- **THEN** 该文件可被 Microsoft PowerPoint 正常打开和编辑 + +#### Scenario: 生成的 PPTX 文件可被其他软件打开 + +- **WHEN** 系统生成 PPTX 文件 +- **THEN** 该文件可被 LibreOffice Impress、Google Slides 等软件正常打开 + +#### Scenario: PPTX 文件扩展名正确 + +- **WHEN** 系统保存演示文稿 +- **THEN** 输出文件的扩展名为 `.pptx` + +### Requirement: 系统必须支持设置演示文稿尺寸 + +系统 SHALL 支持设置演示文稿的幻灯片尺寸，支持 16:9 和 4:3 两种标准比例。 + +#### Scenario: 创建 16:9 比例的演示文稿 + +- **WHEN** metadata 中指定 `size: "16:9"` +- **THEN** 系统创建 10×5.625 英寸的幻灯片 + +#### Scenario: 创建 4:3 比例的演示文稿 + +- **WHEN** metadata 中指定 `size: "4:3"` +- **THEN** 系统创建 10×7.5 英寸的幻灯片 + +#### Scenario: 默认使用 16:9 比例 + +- **WHEN** metadata 中未指定 size 字段 +- **THEN** 系统默认使用 16:9 比例 + +#### Scenario: 不支持的尺寸比例报错 + +- **WHEN** metadata 中指定了不支持的尺寸比例（如 "21:9"） +- **THEN** 系统抛出错误，提示仅支持 16:9 和 4:3 + +### Requirement: 系统必须按顺序添加幻灯片 + +系统 SHALL 按照 YAML 中 slides 列表的顺序，依次添加幻灯片到 PPTX 文件。 + +#### Scenario: 幻灯片顺序与 YAML 一致 + +- **WHEN** YAML 中 slides 列表为 `[slide1, slide2, slide3]` +- **THEN** 生成的 PPTX 文件中，幻灯片顺序为 slide1、slide2、slide3 + +#### Scenario: 空幻灯片列表生成空演示文稿 + +- **WHEN** YAML 中 slides 列表为空 +- **THEN** 系统生成一个不包含任何幻灯片的 PPTX 文件（或抛出警告） + +### Requirement: 系统必须使用空白布局 + +系统 SHALL 为每个幻灯片使用空白布局（blank layout），以便完全自定义内容。 + +#### Scenario: 使用空白布局添加幻灯片 + +- **WHEN** 系统添加幻灯片 +- **THEN** 使用 `prs.slide_layouts[6]`（空白布局）而非预定义布局 + +#### Scenario: 空白幻灯片不包含占位符 + +- **WHEN** 创建新的空白幻灯片 +- **THEN** 幻灯片不包含任何预定义的标题或内容占位符 + +### Requirement: 系统必须保存到指定路径 + +系统 SHALL 将生成的 PPTX 文件保存到用户指定的路径。 + +#### Scenario: 保存到指定文件路径 + +- **WHEN** 用户指定输出路径为 `output/presentation.pptx` +- **THEN** 系统将 PPTX 文件保存到该路径 + +#### Scenario: 自动创建输出目录 + +- **WHEN** 输出路径包含不存在的目录（如 `output/subdir/file.pptx`） +- **THEN** 系统自动创建所需的目录结构 + +#### Scenario: 输出路径已存在时覆盖 + +- **WHEN** 指定的输出文件路径已存在 +- **THEN** 系统覆盖原有文件（或提供选项询问用户） + +#### Scenario: 无写入权限时报错 + +- **WHEN** 输出路径没有写入权限 +- **THEN** 系统抛出错误，提示权限不足 + +### Requirement: 系统必须使用 python-pptx 的单位转换函数 + +系统 SHALL 使用 python-pptx 提供的 Inches() 函数将英寸值转换为 EMU（English Metric Units）。 + +#### Scenario: 使用 Inches() 转换坐标 + +- **WHEN** 元素 box 定义为 `[1, 2, 8, 3]` +- **THEN** 系统调用 `Inches(1)`, `Inches(2)`, `Inches(8)`, `Inches(3)` 转换为 EMU + +#### Scenario: EMU 转换的精度 + +- **WHEN** 使用 Inches(1.0) +- **THEN** 返回值为 914400 EMU（1 英寸 = 914400 EMU） + +### Requirement: 系统必须处理颜色转换 + +系统 SHALL 将十六进制颜色值（如 "#4a90e2"）转换为 python-pptx 的 RGBColor 对象。 + +#### Scenario: 十六进制颜色转 RGB + +- **WHEN** 颜色值为 "#4a90e2" +- **THEN** 系统转换为 RGBColor(74, 144, 226) + +#### Scenario: 短格式十六进制颜色 + +- **WHEN** 颜色值为 "#fff"（短格式） +- **THEN** 系统扩展为 "#ffffff" 并转换为 RGBColor(255, 255, 255) + +#### Scenario: 无效颜色格式报错 + +- **WHEN** 颜色值不是有效的十六进制格式 +- **THEN** 系统抛出错误，提示颜色格式无效 + +### Requirement: 系统必须使用 uv 运行 Python 脚本 + +系统 SHALL 使用 uv 运行转换脚本，通过 Inline script metadata 指定依赖。 + +#### Scenario: 脚本包含 Inline script metadata + +- **WHEN** 查看 `yaml2pptx.py` 文件头部 +- **THEN** 包含 `# /// script` 块，定义 python-pptx 和 PyYAML 依赖 + +#### Scenario: 使用 uv 运行脚本 + +- **WHEN** 执行转换命令 +- **THEN** 使用 `uv run yaml2pptx.py` 而非 `python yaml2pptx.py` + +#### Scenario: 禁止直接安装依赖 + +- **WHEN** 需要使用 python-pptx 或 PyYAML +- **THEN** 不使用 `pip install`，而是在 script metadata 中声明依赖 + +### Requirement: 系统架构保持简洁 + +系统 SHALL 采用两层架构（模板 + 演示文稿），颜色和样式直接在模板中定义。 + +#### Scenario: 模板自包含样式 + +- **WHEN** 查看模板文件 +- **THEN** 颜色值直接以十六进制格式指定（如 "#4a90e2"） + +#### Scenario: 无需主题配置 + +- **WHEN** 创建新的演示文稿 +- **THEN** metadata 中不需要指定 theme 字段 + +#### Scenario: 模板独立配色 + +- **WHEN** 创建新模板 +- **THEN** 可以为该模板定义独立的颜色方案，不受其他模板影响 + +### Requirement: 系统必须提供命令行接口 + +系统 SHALL 提供命令行接口，接受输入 YAML 文件路径和输出 PPTX 文件路径。 + +#### Scenario: 基本命令行使用 + +- **WHEN** 执行 `uv run yaml2pptx.py input.yaml output.pptx` +- **THEN** 系统读取 input.yaml，生成 output.pptx + +#### Scenario: 仅提供输入文件时自动命名输出 + +- **WHEN** 执行 `uv run yaml2pptx.py input.yaml` +- **THEN** 系统自动生成输出文件名为 `input.pptx` + +#### Scenario: 显示帮助信息 + +- **WHEN** 执行 `uv run yaml2pptx.py --help` +- **THEN** 系统显示使用说明和参数列表 + +#### Scenario: 输入文件不存在时报错 + +- **WHEN** 提供的输入文件路径不存在 +- **THEN** 系统抛出错误，提示输入文件未找到 + +### Requirement: 系统必须报告转换进度 + +系统 SHALL 在转换过程中输出进度信息，包括当前处理的幻灯片数量。 + +#### Scenario: 输出转换开始信息 + +- **WHEN** 开始转换 +- **THEN** 系统输出 "开始转换: input.yaml" + +#### Scenario: 输出幻灯片处理进度 + +- **WHEN** 处理每个幻灯片 +- **THEN** 系统输出 "处理幻灯片 N/M" + +#### Scenario: 输出转换完成信息 + +- **WHEN** 转换成功完成 +- **THEN** 系统输出 "转换完成: output.pptx" + +#### Scenario: 转换失败时输出错误 + +- **WHEN** 转换过程中发生错误 +- **THEN** 系统输出详细的错误信息和堆栈跟踪（调试模式下） diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/template-system/spec.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/template-system/spec.md new file mode 100644 index 0000000..e4e50cb --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/template-system/spec.md @@ -0,0 +1,134 @@ +## ADDED Requirements + +### Requirement: 模板必须定义变量列表 + +模板 SHALL 包含 vars 字段，定义该模板需要的变量，包括变量名、是否必需、默认值等。 + +#### Scenario: 加载模板变量定义 + +- **WHEN** 模板文件定义了 `vars` 列表，包含 `name`、`required`、`default` 等字段 +- **THEN** 系统成功加载变量定义，可通过模板对象访问 + +#### Scenario: 验证必需变量 + +- **WHEN** 模板定义了 `{name: title, required: true}` 的变量 +- **THEN** 渲染时如果未提供该变量，系统抛出错误 + +#### Scenario: 使用变量默认值 + +- **WHEN** 模板定义了 `{name: subtitle, required: false, default: ""}` 的变量 +- **THEN** 渲染时如果未提供该变量，系统使用空字符串作为默认值 + +### Requirement: 模板必须定义元素列表 + +模板 SHALL 包含 elements 字段，定义该模板的幻灯片布局和元素。 + +#### Scenario: 加载模板元素定义 + +- **WHEN** 模板文件定义了 `elements` 列表，包含文本、图片、形状等元素 +- **THEN** 系统成功加载元素列表，准备渲染 + +#### Scenario: 元素包含模板变量引用 + +- **WHEN** 模板元素中包含 `{title}` 等模板变量引用 +- **THEN** 系统在渲染时用用户提供的值替换变量 + +#### Scenario: 元素直接指定样式值 + +- **WHEN** 模板元素中直接指定 `color: "#4a90e2"` 等样式值 +- **THEN** 系统正确应用该样式值 + +### Requirement: 系统必须支持模板渲染 + +系统 SHALL 能够根据用户提供的变量值渲染模板，生成实际的元素列表。 + +#### Scenario: 渲染包含变量的模板 + +- **WHEN** 用户提供 `{title: "Hello", subtitle: "World"}` 渲染模板 +- **THEN** 系统将模板中的 `{title}` 替换为 "Hello"，`{subtitle}` 替换为 "World" + +#### Scenario: 数值类型自动转换 + +- **WHEN** 模板定义 `size: "{font_size}"` 且用户提供 `{font_size: "44"}` +- **THEN** 系统自动将字符串 "44" 转换为整数 44 + +#### Scenario: 检测未定义的模板变量 + +- **WHEN** 模板中引用了 `{undefined_var}`，但该变量未在 vars 中定义，也未由用户提供 +- **THEN** 系统抛出错误，指出未定义的变量 + +### Requirement: 系统必须支持条件渲染 + +系统 SHALL 支持基于变量值的条件渲染，通过 `visible` 字段控制元素是否显示。 + +#### Scenario: 显示满足条件的元素 + +- **WHEN** 元素定义了 `visible: "{subtitle != ''}"`，且用户提供了非空的 subtitle +- **THEN** 系统渲染该元素 + +#### Scenario: 隐藏不满足条件的元素 + +- **WHEN** 元素定义了 `visible: "{subtitle != ''}"`，但用户提供的 subtitle 为空字符串 +- **THEN** 系统跳过该元素，不渲染到幻灯片中 + +#### Scenario: 条件表达式语法错误 + +- **WHEN** visible 字段包含无效的条件表达式 +- **THEN** 系统抛出错误，提示条件表达式格式错误 + +### Requirement: 模板文件必须可从指定目录加载 + +系统 SHALL 从 `templates/` 目录加载模板文件，支持通过模板名称引用。 + +#### Scenario: 通过名称加载模板 + +- **WHEN** 幻灯片指定 `template: title_slide` +- **THEN** 系统从 `templates/title_slide.yaml` 加载模板文件 + +#### Scenario: 模板文件不存在时报错 + +- **WHEN** 幻灯片引用不存在的模板名称 +- **THEN** 系统抛出错误，提示模板文件未找到，并列出可用模板 + +#### Scenario: 缓存已加载的模板 + +- **WHEN** 多个幻灯片使用同一个模板 +- **THEN** 系统仅加载一次模板文件，后续使用缓存 + +### Requirement: 系统必须支持自定义幻灯片 + +系统 SHALL 支持不使用模板，直接定义元素的自定义幻灯片。 + +#### Scenario: 渲染自定义幻灯片 + +- **WHEN** 幻灯片未指定 `template` 字段，直接包含 `elements` 列表 +- **THEN** 系统跳过模板渲染，直接处理元素列表 + +#### Scenario: 自定义幻灯片中直接指定样式 + +- **WHEN** 自定义幻灯片的元素直接指定 `color: "#4a90e2"` +- **THEN** 系统正确应用该颜色值 + +#### Scenario: 自定义幻灯片和模板混合使用 + +- **WHEN** 演示文稿中部分幻灯片使用模板，部分为自定义 +- **THEN** 系统正确处理两种类型的幻灯片 + +### Requirement: 模板变量解析必须深度递归 + +系统 SHALL 递归解析模板元素的所有嵌套字段中的变量引用。 + +#### Scenario: 解析嵌套对象中的变量 + +- **WHEN** 模板元素定义了 `font: {size: "{font_size}", color: "{text_color}"}` +- **THEN** 系统正确解析嵌套对象中的所有变量引用 + +#### Scenario: 解析数组中的变量 + +- **WHEN** 模板元素定义了 `box: ["{left}", 2, 8, 3]` +- **THEN** 系统正确解析数组中的变量引用 + +#### Scenario: 解析多层嵌套的变量 + +- **WHEN** 模板包含复杂的嵌套结构，多层使用变量引用 +- **THEN** 系统递归解析所有层级的变量，直到无变量引用为止 diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/yaml-parsing/spec.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/yaml-parsing/spec.md new file mode 100644 index 0000000..4a0c587 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/specs/yaml-parsing/spec.md @@ -0,0 +1,91 @@ +## ADDED Requirements + +### Requirement: 系统必须能解析演示文稿 YAML 文件 + +系统 SHALL 能够解析包含 metadata 和 slides 的演示文稿 YAML 文件，并验证其结构的正确性。 + +#### Scenario: 解析有效的演示文稿 YAML + +- **WHEN** 提供一个包含 `metadata` 和 `slides` 字段的 YAML 文件 +- **THEN** 系统成功解析并返回 Python 字典结构 + +#### Scenario: 检测缺少必需字段 + +- **WHEN** 提供的 YAML 文件缺少 `slides` 字段 +- **THEN** 系统抛出验证错误，明确指出缺少必需字段 + +#### Scenario: 处理无效的 YAML 语法 + +- **WHEN** 提供的文件包含无效的 YAML 语法（如缩进错误） +- **THEN** 系统抛出解析错误，包含行号和错误描述 + +### Requirement: 系统必须验证颜色值格式 + +系统 SHALL 验证模板和演示文稿 YAML 文件中的颜色值为有效的十六进制格式。 + +#### Scenario: 验证有效的颜色值 + +- **WHEN** 模板或演示文稿 YAML 文件中包含 `color: "#4a90e2"` 的颜色值 +- **THEN** 系统接受该颜色值 + +#### Scenario: 验证颜色值格式错误 + +- **WHEN** 颜色值格式不正确（如 "blue" 或 "#xyz"） +- **THEN** 系统抛出验证错误，提示使用 #RRGGBB 格式 + +#### Scenario: 支持短格式颜色值 + +- **WHEN** 颜色值为短格式 "#fff" +- **THEN** 系统自动扩展为 "#ffffff" 并接受 + +### Requirement: 系统必须能解析模板 YAML 文件 + +系统 SHALL 能够解析包含 vars 定义和 elements 列表的模板 YAML 文件。 + +#### Scenario: 解析有效的模板文件 + +- **WHEN** 提供一个包含 `vars` 和 `elements` 字段的模板 YAML 文件 +- **THEN** 系统成功解析并返回模板对象 + +#### Scenario: 验证变量定义的完整性 + +- **WHEN** 模板 vars 中的变量缺少 `name` 字段 +- **THEN** 系统抛出验证错误，指出变量定义不完整 + +#### Scenario: 验证必需变量标记 + +- **WHEN** 模板 vars 中定义了 `required: true` 的变量 +- **THEN** 系统记录该变量为必需变量，在渲染时必须提供值 + +### Requirement: 系统必须支持 UTF-8 编码 + +系统 SHALL 以 UTF-8 编码读取所有 YAML 文件，支持中文等多字节字符。 + +#### Scenario: 解析包含中文的 YAML 文件 + +- **WHEN** 提供包含中文字符的 YAML 文件 +- **THEN** 系统正确解析中文内容，不出现乱码 + +#### Scenario: 处理 BOM 标记 + +- **WHEN** YAML 文件包含 UTF-8 BOM 标记 +- **THEN** 系统能够正确处理并解析文件内容 + +### Requirement: 系统必须提供清晰的错误消息 + +系统 SHALL 在 YAML 解析失败时提供包含文件路径、行号、错误原因的详细错误消息。 + +#### Scenario: YAML 语法错误的错误消息 + +- **WHEN** YAML 文件在第 10 行存在缩进错误 +- **THEN** 错误消息包含 "文件路径, 第 10 行: 缩进错误" 等信息 + +#### Scenario: 文件不存在的错误消息 + +- **WHEN** 尝试加载不存在的 YAML 文件 +- **THEN** 错误消息明确指出文件路径不存在 + +#### Scenario: 权限不足的错误消息 + +- **WHEN** YAML 文件存在但没有读取权限 +- **THEN** 错误消息提示权限不足，无法读取文件 diff --git a/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/tasks.md b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/tasks.md new file mode 100644 index 0000000..4711ba9 --- /dev/null +++ b/openspec/changes/archive/2026-03-02-yaml-to-pptx-prototype/tasks.md @@ -0,0 +1,103 @@ +## 1. 项目初始化和基础设置 + +- [x] 1.1 创建项目目录结构（themes/, templates/, presentations/, assets/, examples/） +- [x] 1.2 创建 yaml2pptx.py 主脚本文件，添加 Inline script metadata（依赖 python-pptx, PyYAML） +- [x] 1.3 添加基础的命令行参数解析（输入 YAML 文件路径、输出 PPTX 文件路径） +- [x] 1.4 实现 --help 帮助信息输出 +- [x] 1.5 添加基础的日志输出函数（转换开始、进度、完成、错误） + +## 2. YAML 解析模块实现 + +- [x] 2.1 实现通用 YAML 文件加载函数（UTF-8 编码，错误处理） +- [x] 2.2 实现演示文稿 YAML 结构验证（必需字段：slides） +- [x] 2.3 实现主题 YAML 结构验证（colors, fonts, spacing, defaults） +- [x] 2.4 实现模板 YAML 结构验证（vars, elements） +- [x] 2.5 实现颜色值格式验证（十六进制 #RRGGBB） +- [x] 2.6 实现清晰的错误消息生成（文件路径、行号、错误原因） + +## 3. 主题系统实现 + +- [x] 3.1 创建 Theme 类，实现主题文件加载 +- [x] 3.2 实现 Theme.resolve() 方法，支持路径解析（如 "colors.primary"） +- [x] 3.3 实现颜色值访问（theme.colors.xxx） +- [x] 3.4 实现字体方案访问（theme.fonts.heading, theme.fonts.sizes.xxx） +- [x] 3.5 实现间距规则访问（theme.spacing.xxx） +- [x] 3.6 实现默认值访问（theme.defaults.xxx） +- [x] 3.7 实现从 themes/ 目录按名称加载主题文件 +- [x] 3.8 创建示例主题：corporate_blue.yaml（企业蓝主题） +- [x] 3.9 创建示例主题：dark_modern.yaml（暗色现代主题） + +## 4. 模板系统实现 + +- [x] 4.1 创建 Template 类，实现模板文件加载 +- [x] 4.2 实现变量定义解析（vars 列表，name, required, default） +- [x] 4.3 实现变量引用解析函数（正则匹配 {xxx}） +- [x] 4.4 实现 resolve_value() 方法，替换单个值中的变量引用 +- [x] 4.5 实现 resolve_element() 方法，递归解析元素中的所有变量 +- [x] 4.6 实现 Template.render() 方法，验证必需变量并渲染元素列表 +- [x] 4.7 实现条件渲染支持（visible 字段，简单存在性检查） +- [x] 4.8 实现从 templates/ 目录按名称加载模板文件 +- [x] 4.9 实现模板缓存机制 +- [x] 4.10 创建示例模板：title_slide.yaml（标题页模板） +- [x] 4.11 创建示例模板：content_slide.yaml（内容页模板） +- [x] 4.12 创建示例模板：two_column.yaml（双栏模板） + +## 5. 元素渲染实现 + +- [x] 5.1 实现十六进制颜色转 RGB 函数（hex_to_rgb） +- [x] 5.2 实现文本元素渲染函数（add_text_element） +- [x] 5.3 实现文本字体样式应用（size, bold, italic, color） +- [x] 5.4 实现文本对齐方式应用（left, center, right） +- [x] 5.5 实现图片元素渲染函数（add_image_element） +- [x] 5.6 实现图片相对路径解析 +- [x] 5.7 实现图片文件存在性检查和错误提示 +- [x] 5.8 实现形状元素渲染函数（add_shape_element） +- [x] 5.9 实现形状类型映射（rectangle, ellipse, rounded_rectangle） +- [x] 5.10 实现形状填充色和边框样式应用 +- [x] 5.11 实现表格元素渲染函数（add_table_element） +- [x] 5.12 实现表格数据和样式应用（字体、表头背景色、边框） +- [x] 5.13 实现幻灯片背景设置（纯色背景） +- [x] 5.14 实现幻灯片背景设置（图片背景，可选） +- [x] 5.15 实现元素类型验证和错误提示 + +## 6. PPTX 生成和导出 + +- [x] 6.1 创建 Presentation 类，实现演示文稿加载 +- [x] 6.2 实现演示文稿尺寸设置（16:9, 4:3） +- [x] 6.3 实现主题加载和关联 +- [x] 6.4 实现 render_slide() 方法，处理模板和自定义幻灯片 +- [x] 6.5 创建 PptxGenerator 类，封装 python-pptx 操作 +- [x] 6.6 实现空白幻灯片创建（使用 layout[6]） +- [x] 6.7 实现 add_slide() 方法，添加幻灯片并渲染所有元素 +- [x] 6.8 实现按 elements 顺序渲染（控制层次） +- [x] 6.9 实现 save() 方法，保存 PPTX 到指定路径 +- [x] 6.10 实现输出目录自动创建 +- [x] 6.11 实现主流程：加载 YAML → 渲染幻灯片 → 生成 PPTX + +## 7. 示例和文档创建 + +- [x] 7.1 创建完整示例演示文稿：examples/demo.yaml（使用模板） +- [x] 7.2 创建自定义幻灯片示例：examples/custom.yaml（不使用模板） +- [ ] 7.3 准备示例图片资源（assets/images/） +- [x] 7.4 编写 README.md，说明项目用途和使用方法 +- [ ] 7.5 编写 YAML Schema 文档（演示文稿、主题、模板的格式说明） +- [x] 7.6 添加使用示例和命令行说明 + +## 8. 测试和验证 + +- [x] 8.1 测试基本转换：使用 demo.yaml 生成 PPTX，验证可被 PowerPoint 打开 +- [x] 8.2 测试主题系统：修改主题颜色，验证生成的 PPTX 样式变化 +- [x] 8.3 测试模板系统：创建新演示文稿使用现有模板，验证变量替换正确 +- [x] 8.4 测试所有元素类型：文本、图片、形状、表格在同一幻灯片中正常渲染 +- [ ] 8.5 测试错误处理：缺少文件、格式错误、变量未定义等场景的错误消息清晰 +- [x] 8.6 测试 UTF-8 中文支持：演示文稿包含中文内容，验证无乱码 +- [x] 8.7 测试两种幻灯片尺寸：16:9 和 4:3 比例正确生成 +- [x] 8.8 性能测试：生成包含 10+ 幻灯片的演示文稿，记录转换时间 + +## 9. 优化和完善 + +- [ ] 9.1 优化错误消息的可读性和有用性 +- [ ] 9.2 添加更多主题和模板供选择 +- [ ] 9.3 优化代码注释（中文），确保代码可读性 +- [ ] 9.4 代码重构：提取重复逻辑，提高可维护性 +- [ ] 9.5 添加 --verbose 选项，输出详细的调试信息 diff --git a/openspec/config.yaml b/openspec/config.yaml new file mode 100644 index 0000000..5934219 --- /dev/null +++ b/openspec/config.yaml @@ -0,0 +1,8 @@ +schema: spec-driven + +context: | + 本项目始终面向中文开发者，使用中文进行注释、交流等内容的处理，不考虑多语言； + 本项目编写的python脚本始终使用uv运行，脚本使用Inline script metadata来指定脚本的依赖包和python运行版本； + 严禁直接使用主机环境的python直接执行脚本，严禁在主机环境直接安装python依赖包； + 本项目编写的测试文件、临时文件必须放在temp目录下； + 严禁污染主机环境的任何配置，如有需要，必须请求用户审核操作； \ No newline at end of file diff --git a/openspec/specs/browser-preview-server/spec.md b/openspec/specs/browser-preview-server/spec.md new file mode 100644 index 0000000..f210e2a --- /dev/null +++ b/openspec/specs/browser-preview-server/spec.md @@ -0,0 +1,186 @@ +# Browser Preview Server + +## Purpose + +Browser Preview Server 负责提供浏览器实时预览功能，包括启动 Web 服务、监听 YAML 文件变化、通过 Server-Sent Events (SSE) 推送更新通知到浏览器。它是预览模式的核心组件，协调文件监听、HTML 生成和浏览器刷新的整个流程。 + +## Requirements + +### Requirement: 系统必须支持通过命令行参数启用预览模式 + +系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。 + +#### Scenario: 使用 --preview 参数启动预览服务器 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview` +- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件 + +#### Scenario: 不使用 --preview 参数时保持原有行为 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml` +- **THEN** 系统生成 PPTX 文件，不启动预览服务器 + +#### Scenario: --preview 参数与其他参数兼容 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates` +- **THEN** 系统启动预览服务器，并使用指定的模板目录 + +### Requirement: 系统必须提供 HTTP 服务 + +系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。 + +#### Scenario: 启动 HTTP 服务器 + +- **WHEN** 预览模式启动 +- **THEN** 系统在默认端口 5000 启动 Flask HTTP 服务器 + +#### Scenario: 自定义端口 + +- **WHEN** 用户使用 `--port 8080` 参数 +- **THEN** 系统在端口 8080 启动 HTTP 服务器 + +#### Scenario: 端口被占用时报错 + +- **WHEN** 指定的端口已被其他服务占用 +- **THEN** 系统抛出错误，提示端口被占用，建议使用 `--port` 参数指定其他端口 + +#### Scenario: 提供主页面路由 + +- **WHEN** 浏览器访问 `http://localhost:5000/` +- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面 + +### Requirement: 系统必须监听 YAML 文件变化 + +系统 SHALL 使用 watchdog 监听 YAML 文件所在目录，检测文件修改事件。 + +#### Scenario: 监听 YAML 文件修改 + +- **WHEN** 用户修改并保存 YAML 文件 +- **THEN** 系统检测到文件变化事件 + +#### Scenario: 监听模板文件修改 + +- **WHEN** 用户修改并保存模板文件（如 `templates/title_slide.yaml`） +- **THEN** 系统检测到文件变化事件 + +#### Scenario: 忽略非 YAML 文件变化 + +- **WHEN** 用户修改其他类型的文件（如 `.txt`、`.md`） +- **THEN** 系统不触发预览更新 + +#### Scenario: 防抖处理 + +- **WHEN** 用户在短时间内多次保存文件（如 1 秒内保存 3 次） +- **THEN** 系统仅触发一次预览更新，避免频繁刷新 + +### Requirement: 系统必须通过 SSE 推送更新通知 + +系统 SHALL 提供 Server-Sent Events (SSE) 端点，当文件变化时推送更新通知到浏览器。 + +#### Scenario: 提供 SSE 端点 + +- **WHEN** 浏览器连接到 `http://localhost:5000/events` +- **THEN** 系统建立 SSE 连接，保持连接打开 + +#### Scenario: 文件变化时推送更新 + +- **WHEN** 检测到 YAML 文件变化 +- **THEN** 系统通过 SSE 连接发送 `data: reload` 消息到所有连接的浏览器 + +#### Scenario: 浏览器接收更新后自动刷新 + +- **WHEN** 浏览器接收到 `reload` 消息 +- **THEN** 浏览器自动刷新页面，显示最新的预览内容 + +#### Scenario: SSE 连接断开时自动重连 + +- **WHEN** SSE 连接因网络问题断开 +- **THEN** 浏览器自动尝试重新连接到 SSE 端点 + +### Requirement: 系统必须自动打开浏览器 + +系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。 + +#### Scenario: 启动后自动打开浏览器 + +- **WHEN** 预览服务器启动成功 +- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/` + +#### Scenario: 浏览器打开失败时提示 URL + +- **WHEN** 系统无法自动打开浏览器（如无图形界面环境） +- **THEN** 系统在终端输出预览 URL，提示用户手动打开 + +### Requirement: 系统必须提供清晰的日志输出 + +系统 SHALL 在终端输出清晰的日志信息，帮助用户了解预览服务器的状态。 + +#### Scenario: 启动时输出日志 + +- **WHEN** 预览服务器启动 +- **THEN** 系统输出以下信息： + - 正在监听的 YAML 文件路径 + - 预览服务器的 URL + - 停止服务器的方法（按 Ctrl+C） + +#### Scenario: 文件变化时输出日志 + +- **WHEN** 检测到文件变化 +- **THEN** 系统输出 `[INFO] 检测到文件变化: <文件路径>` + +#### Scenario: 错误时输出日志 + +- **WHEN** 发生错误（如 YAML 解析错误） +- **THEN** 系统输出 `[ERROR]` 级别的日志，包含错误详情 + +### Requirement: 系统必须支持优雅退出 + +系统 SHALL 支持通过 Ctrl+C 优雅地停止预览服务器。 + +#### Scenario: 按 Ctrl+C 停止服务器 + +- **WHEN** 用户按下 Ctrl+C +- **THEN** 系统停止文件监听和 HTTP 服务器，输出 `[INFO] 已停止`，然后退出 + +#### Scenario: 停止时清理资源 + +- **WHEN** 服务器停止 +- **THEN** 系统关闭所有 SSE 连接，停止 watchdog 监听器，释放端口 + +### Requirement: 系统必须处理 YAML 解析错误 + +系统 SHALL 在 YAML 解析失败时，在预览页面显示友好的错误信息，而不是崩溃。 + +#### Scenario: YAML 语法错误时显示错误页面 + +- **WHEN** YAML 文件存在语法错误（如缺少冒号、缩进错误） +- **THEN** 系统在预览页面显示错误信息，包括错误类型和行号 + +#### Scenario: 错误修复后自动恢复 + +- **WHEN** 用户修复 YAML 错误并保存 +- **THEN** 系统检测到文件变化，重新解析 YAML，显示正常的预览内容 + +#### Scenario: 错误页面仍然监听文件变化 + +- **WHEN** 预览页面显示错误信息 +- **THEN** 系统继续监听文件变化，等待用户修复错误 + +### Requirement: 系统必须支持多幻灯片预览 + +系统 SHALL 在预览页面中显示所有幻灯片，支持用户查看完整的演示文稿。 + +#### Scenario: 垂直排列显示所有幻灯片 + +- **WHEN** YAML 文件包含多个幻灯片 +- **THEN** 系统在预览页面中垂直排列显示所有幻灯片，每个幻灯片之间有间距 + +#### Scenario: 显示幻灯片编号 + +- **WHEN** 预览页面显示幻灯片 +- **THEN** 每个幻灯片右下角显示编号（如 "幻灯片 1"、"幻灯片 2"） + +#### Scenario: 幻灯片尺寸一致 + +- **WHEN** 预览页面显示多个幻灯片 +- **THEN** 所有幻灯片使用相同的尺寸（960x540 像素，16:9 比例） diff --git a/openspec/specs/element-rendering/spec.md b/openspec/specs/element-rendering/spec.md new file mode 100644 index 0000000..ebef768 --- /dev/null +++ b/openspec/specs/element-rendering/spec.md @@ -0,0 +1,174 @@ +# Element Rendering + +## Purpose + +Element rendering系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 PPTX 文档中的实际对象。它处理元素的定位、样式应用、层次管理，以及幻灯片背景设置。 + +## Requirements + +### Requirement: 系统必须支持文本元素渲染 + +系统 SHALL 将 YAML 中定义的文本元素渲染为 PPTX 文本框。 + +#### Scenario: 渲染基本文本元素 + +- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}` +- **THEN** 系统在幻灯片的 (1, 2) 位置创建 8×3 英寸的文本框，内容为 "Hello" + +#### Scenario: 应用文本字体样式 + +- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}` +- **THEN** 系统将文本设置为 32pt、粗体、颜色为 #333333 + +#### Scenario: 应用文本对齐方式 + +- **WHEN** 文本元素定义了 `font: {align: center}` +- **THEN** 系统将文本设置为居中对齐 + +#### Scenario: 支持多种对齐方式 + +- **WHEN** 文本对齐方式为 `left`、`center`、`right` 之一 +- **THEN** 系统正确应用对应的对齐方式 + +### Requirement: 系统必须支持图片元素渲染 + +系统 SHALL 将 YAML 中定义的图片元素渲染为 PPTX 图片对象。 + +#### Scenario: 渲染本地图片 + +- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}` +- **THEN** 系统从指定路径加载图片，在 (2, 3) 位置渲染为 4×3 英寸大小 + +#### Scenario: 图片文件不存在时报错 + +- **WHEN** 图片 src 指向不存在的文件路径 +- **THEN** 系统抛出错误，明确指出图片文件未找到 + +#### Scenario: 图片格式不支持时报错 + +- **WHEN** 图片文件格式不被 python-pptx 支持 +- **THEN** 系统抛出错误，提示图片格式不支持，并列出支持的格式 + +#### Scenario: 相对路径处理 + +- **WHEN** 图片 src 使用相对路径 `"assets/images/logo.png"` +- **THEN** 系统基于演示文稿文件所在目录解析相对路径 + +### Requirement: 系统必须支持形状元素渲染 + +系统 SHALL 将 YAML 中定义的形状元素渲染为 PPTX 形状对象。 + +#### Scenario: 渲染矩形形状 + +- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}` +- **THEN** 系统在 (1, 2) 位置创建 3×1 英寸的矩形，填充颜色为 #4a90e2 + +#### Scenario: 渲染圆形形状 + +- **WHEN** 元素的 `shape` 字段为 `ellipse` +- **THEN** 系统渲染椭圆/圆形形状 + +#### Scenario: 渲染圆角矩形 + +- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle` +- **THEN** 系统渲染圆角矩形形状 + +#### Scenario: 应用形状边框样式 + +- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}` +- **THEN** 系统为形状添加黑色、2pt 宽度的边框 + +### Requirement: 系统必须支持表格元素渲染 + +系统 SHALL 将 YAML 中定义的表格元素渲染为 PPTX 表格对象。 + +#### Scenario: 渲染基本表格 + +- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}` +- **THEN** 系统在 (1, 2) 位置创建 2×2 表格，列宽各为 2 英寸 + +#### Scenario: 应用表格样式 + +- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}` +- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色 + +#### Scenario: 表格数据为空时报错 + +- **WHEN** 表格的 `data` 字段为空数组 +- **THEN** 系统抛出错误，提示表格数据不能为空 + +#### Scenario: 表格列宽不匹配时报错 + +- **WHEN** `col_widths` 数组长度与表格列数不一致 +- **THEN** 系统抛出错误，要求列宽数量与列数匹配 + +### Requirement: 元素位置必须使用英寸单位 + +系统 SHALL 将元素的 box 或 position 字段中的数值解释为英寸单位。 + +#### Scenario: box 数组表示位置和尺寸 + +- **WHEN** 元素定义了 `box: [1, 2, 8, 3]` +- **THEN** 系统将其解释为 x=1英寸, y=2英寸, width=8英寸, height=3英寸 + +#### Scenario: position 数组表示位置 + +- **WHEN** 表格元素定义了 `position: [1, 2]` +- **THEN** 系统将其解释为 x=1英寸, y=2英寸 + +#### Scenario: 负数坐标值报错 + +- **WHEN** box 或 position 包含负数值 +- **THEN** 系统抛出错误，要求坐标值必须为非负数 + +### Requirement: 系统必须支持幻灯片背景设置 + +系统 SHALL 支持为幻灯片设置纯色背景或图片背景。 + +#### Scenario: 设置纯色背景 + +- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}` +- **THEN** 系统将幻灯片背景设置为白色 + +#### Scenario: 设置图片背景 + +- **WHEN** 幻灯片定义了 `background: {image: "bg.png"}` +- **THEN** 系统使用指定图片作为幻灯片背景 + +#### Scenario: 背景图片不存在时报错 + +- **WHEN** 背景图片路径不存在 +- **THEN** 系统抛出错误，提示背景图片文件未找到 + +### Requirement: 系统必须处理元素重叠和层次 + +系统 SHALL 按照元素在 elements 列表中的顺序渲染，后定义的元素显示在前面元素之上。 + +#### Scenario: 元素按定义顺序渲染 + +- **WHEN** elements 列表为 `[shape1, text1, image1]` +- **THEN** 系统先渲染 shape1，再渲染 text1，最后渲染 image1（image1 在最上层） + +#### Scenario: 重叠元素的显示层次 + +- **WHEN** 两个元素的位置有重叠 +- **THEN** 后定义的元素遮盖先定义的元素 + +### Requirement: 系统必须验证元素类型 + +系统 SHALL 验证每个元素的 type 字段，仅支持已定义的元素类型。 + +#### Scenario: 支持的元素类型 + +- **WHEN** 元素的 `type` 为 `text`、`image`、`shape`、`table` 之一 +- **THEN** 系统正常渲染该元素 + +#### Scenario: 不支持的元素类型报错 + +- **WHEN** 元素的 `type` 为未定义的值（如 "video"） +- **THEN** 系统抛出错误，提示不支持该元素类型，并列出支持的类型 + +#### Scenario: 缺少 type 字段报错 + +- **WHEN** 元素未定义 `type` 字段 +- **THEN** 系统抛出错误，要求每个元素必须包含 type 字段 diff --git a/openspec/specs/html-rendering/spec.md b/openspec/specs/html-rendering/spec.md new file mode 100644 index 0000000..29d02b3 --- /dev/null +++ b/openspec/specs/html-rendering/spec.md @@ -0,0 +1,231 @@ +# HTML Rendering + +## Purpose + +HTML Rendering 系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 HTML/CSS 代码，在浏览器中显示。它复用现有的 YAML 解析和模板渲染逻辑，但将输出目标从 PPTX 改为 HTML/CSS，提供快速的预览体验。 + +## Requirements + +### Requirement: 系统必须将 YAML 元素转换为 HTML + +系统 SHALL 将解析后的 YAML 元素转换为 HTML 代码，在浏览器中渲染。 + +#### Scenario: 生成完整的 HTML 页面 + +- **WHEN** 浏览器请求预览页面 +- **THEN** 系统生成包含 HTML、CSS 和 JavaScript 的完整页面 + +#### Scenario: 动态生成 HTML + +- **WHEN** YAML 文件变化 +- **THEN** 系统重新解析 YAML，动态生成新的 HTML 内容，无需生成中间文件 + +#### Scenario: HTML 页面包含 SSE 客户端代码 + +- **WHEN** 生成 HTML 页面 +- **THEN** 页面包含 JavaScript 代码，连接到 SSE 端点，监听更新事件 + +### Requirement: 系统必须使用固定 DPI 进行单位转换 + +系统 SHALL 使用固定 DPI (96) 将 YAML 中的英寸单位转换为 CSS 像素单位。 + +#### Scenario: 英寸转换为像素 + +- **WHEN** 元素定义 `box: [1, 2, 8, 3]`（单位为英寸） +- **THEN** 系统转换为 CSS：`left: 96px; top: 192px; width: 768px; height: 288px` + +#### Scenario: 幻灯片尺寸固定 + +- **WHEN** 渲染 16:9 幻灯片 +- **THEN** 系统使用固定尺寸 960x540 像素（10 英寸 x 5.625 英寸 x 96 DPI） + +#### Scenario: 4:3 幻灯片尺寸 + +- **WHEN** 渲染 4:3 幻灯片 +- **THEN** 系统使用固定尺寸 960x720 像素（10 英寸 x 7.5 英寸 x 96 DPI） + +### Requirement: 系统必须渲染文本元素 + +系统 SHALL 将 YAML 中的文本元素转换为 HTML `
` 标签，应用相应的样式。 + +#### Scenario: 渲染基本文本元素 + +- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}` +- **THEN** 系统生成 `
` 标签，内容为 "Hello"，位置为 (96px, 192px)，尺寸为 768x288 像素 + +#### Scenario: 应用文本字体样式 + +- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}` +- **THEN** 系统应用 CSS：`font-size: 32pt; font-weight: bold; color: #333333` + +#### Scenario: 应用文本对齐方式 + +- **WHEN** 文本元素定义了 `font: {align: center}` +- **THEN** 系统应用 CSS：`text-align: center` + +#### Scenario: 支持多行文本 + +- **WHEN** 文本内容包含换行符（`\n`） +- **THEN** 系统使用 `white-space: pre-wrap` 保留换行 + +#### Scenario: 使用 pt 单位表示字体大小 + +- **WHEN** 文本字体大小为 44 +- **THEN** 系统使用 CSS：`font-size: 44pt`（与 PPTX 保持一致） + +### Requirement: 系统必须渲染形状元素 + +系统 SHALL 将 YAML 中的形状元素转换为 HTML `
` 标签，使用 CSS 样式模拟形状。 + +#### Scenario: 渲染矩形形状 + +- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}` +- **THEN** 系统生成 `
` 标签，背景色为 #4a90e2，`border-radius: 0` + +#### Scenario: 渲染圆形形状 + +- **WHEN** 元素的 `shape` 字段为 `ellipse` +- **THEN** 系统应用 CSS：`border-radius: 50%` + +#### Scenario: 渲染圆角矩形 + +- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle` +- **THEN** 系统应用 CSS：`border-radius: 8px` + +#### Scenario: 应用形状边框样式 + +- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}` +- **THEN** 系统应用 CSS：`border: 2pt solid #000000` + +#### Scenario: 形状无填充色时透明 + +- **WHEN** 形状未定义 `fill` 字段 +- **THEN** 系统应用 CSS：`background: transparent` + +### Requirement: 系统必须渲染表格元素 + +系统 SHALL 将 YAML 中的表格元素转换为 HTML `
` 标签。 + +#### Scenario: 渲染基本表格 + +- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}` +- **THEN** 系统生成 `
` 标签，位置为 (96px, 192px)，包含 2 行 2 列 + +#### Scenario: 应用表格样式 + +- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}` +- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色，字体大小为 14pt + +#### Scenario: 表格单元格边框 + +- **WHEN** 渲染表格 +- **THEN** 系统为所有单元格添加边框：`border: 1px solid #ddd` + +#### Scenario: 表格单元格内边距 + +- **WHEN** 渲染表格 +- **THEN** 系统为所有单元格添加内边距：`padding: 8px` + +### Requirement: 系统必须渲染图片元素 + +系统 SHALL 将 YAML 中的图片元素转换为 HTML `` 标签。 + +#### Scenario: 渲染本地图片 + +- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}` +- **THEN** 系统生成 `` 标签，src 为图片的文件路径，位置为 (192px, 288px)，尺寸为 384x288 像素 + +#### Scenario: 处理相对路径 + +- **WHEN** 图片 src 使用相对路径 `"assets/logo.png"` +- **THEN** 系统基于 YAML 文件所在目录解析相对路径 + +#### Scenario: 图片不存在时显示占位符 + +- **WHEN** 图片文件不存在 +- **THEN** 系统显示占位符或错误提示，而不是崩溃 + +### Requirement: 系统必须渲染幻灯片背景 + +系统 SHALL 支持为幻灯片设置纯色背景。 + +#### Scenario: 设置纯色背景 + +- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}` +- **THEN** 系统为幻灯片容器应用 CSS：`background: #ffffff` + +#### Scenario: 无背景时使用白色 + +- **WHEN** 幻灯片未定义 `background` 字段 +- **THEN** 系统使用默认白色背景 + +### Requirement: 系统必须使用绝对定位 + +系统 SHALL 使用 CSS 绝对定位（`position: absolute`）渲染所有元素，模拟 PPTX 的坐标系统。 + +#### Scenario: 元素使用绝对定位 + +- **WHEN** 渲染任何元素 +- **THEN** 系统应用 CSS：`position: absolute` + +#### Scenario: 幻灯片容器使用相对定位 + +- **WHEN** 渲染幻灯片容器 +- **THEN** 系统应用 CSS：`position: relative`，作为元素的定位上下文 + +#### Scenario: 元素层次按定义顺序 + +- **WHEN** elements 列表为 `[shape1, text1, image1]` +- **THEN** 系统按顺序渲染，后定义的元素显示在前面元素之上（通过 DOM 顺序控制） + +### Requirement: 系统必须提供视觉反馈 + +系统 SHALL 在预览页面中提供视觉反馈，帮助用户了解预览状态。 + +#### Scenario: 幻灯片添加阴影效果 + +- **WHEN** 渲染幻灯片 +- **THEN** 系统为幻灯片容器添加阴影：`box-shadow: 0 2px 8px rgba(0,0,0,0.1)` + +#### Scenario: 幻灯片之间有间距 + +- **WHEN** 渲染多个幻灯片 +- **THEN** 每个幻灯片之间有 20px 的垂直间距 + +### Requirement: 系统必须复用现有的解析逻辑 + +系统 SHALL 复用 `yaml2pptx.py` 中现有的 `Presentation` 类和模板渲染逻辑。 + +#### Scenario: 使用 Presentation 类解析 YAML + +- **WHEN** 预览模式启动 +- **THEN** 系统使用 `Presentation` 类加载和解析 YAML 文件 + +#### Scenario: 使用 render_slide 方法渲染幻灯片 + +- **WHEN** 生成预览 HTML +- **THEN** 系统调用 `Presentation.render_slide()` 方法获取渲染后的幻灯片数据 + +#### Scenario: 支持模板系统 + +- **WHEN** YAML 文件使用模板（如 `template: title_slide`） +- **THEN** 系统正确解析模板变量，渲染模板元素 + +### Requirement: 系统必须处理渲染错误 + +系统 SHALL 在元素渲染失败时，显示错误信息，而不是崩溃。 + +#### Scenario: 元素类型不支持时显示错误 + +- **WHEN** 元素的 `type` 为未定义的值（如 "video"） +- **THEN** 系统在预览页面显示错误信息，提示不支持该元素类型 + +#### Scenario: 元素缺少必需字段时显示错误 + +- **WHEN** 元素缺少必需字段（如文本元素缺少 `content`） +- **THEN** 系统在预览页面显示错误信息，提示缺少字段 + +#### Scenario: 部分元素错误不影响其他元素 + +- **WHEN** 某个元素渲染失败 +- **THEN** 系统继续渲染其他元素，仅在失败位置显示错误提示 diff --git a/openspec/specs/pptx-generation/spec.md b/openspec/specs/pptx-generation/spec.md new file mode 100644 index 0000000..755a89d --- /dev/null +++ b/openspec/specs/pptx-generation/spec.md @@ -0,0 +1,221 @@ +# PPTX Generation + +## Purpose + +PPTX generation 系统负责使用 python-pptx 库创建符合 OOXML 标准的 PowerPoint 文档。它管理演示文稿的整体属性（如尺寸），按顺序添加幻灯片，并提供命令行接口供用户使用。 + +## Requirements + +### Requirement: 系统必须创建符合 OOXML 标准的 PPTX 文件 + +系统 SHALL 使用 python-pptx 库生成符合 Office Open XML (OOXML) 标准的 .pptx 文件。 + +#### Scenario: 生成的 PPTX 文件可被 PowerPoint 打开 + +- **WHEN** 系统生成 PPTX 文件 +- **THEN** 该文件可被 Microsoft PowerPoint 正常打开和编辑 + +#### Scenario: 生成的 PPTX 文件可被其他软件打开 + +- **WHEN** 系统生成 PPTX 文件 +- **THEN** 该文件可被 LibreOffice Impress、Google Slides 等软件正常打开 + +#### Scenario: PPTX 文件扩展名正确 + +- **WHEN** 系统保存演示文稿 +- **THEN** 输出文件的扩展名为 `.pptx` + +### Requirement: 系统必须支持设置演示文稿尺寸 + +系统 SHALL 支持设置演示文稿的幻灯片尺寸，支持 16:9 和 4:3 两种标准比例。 + +#### Scenario: 创建 16:9 比例的演示文稿 + +- **WHEN** metadata 中指定 `size: "16:9"` +- **THEN** 系统创建 10×5.625 英寸的幻灯片 + +#### Scenario: 创建 4:3 比例的演示文稿 + +- **WHEN** metadata 中指定 `size: "4:3"` +- **THEN** 系统创建 10×7.5 英寸的幻灯片 + +#### Scenario: 默认使用 16:9 比例 + +- **WHEN** metadata 中未指定 size 字段 +- **THEN** 系统默认使用 16:9 比例 + +#### Scenario: 不支持的尺寸比例报错 + +- **WHEN** metadata 中指定了不支持的尺寸比例（如 "21:9"） +- **THEN** 系统抛出错误，提示仅支持 16:9 和 4:3 + +### Requirement: 系统必须按顺序添加幻灯片 + +系统 SHALL 按照 YAML 中 slides 列表的顺序，依次添加幻灯片到 PPTX 文件。 + +#### Scenario: 幻灯片顺序与 YAML 一致 + +- **WHEN** YAML 中 slides 列表为 `[slide1, slide2, slide3]` +- **THEN** 生成的 PPTX 文件中，幻灯片顺序为 slide1、slide2、slide3 + +#### Scenario: 空幻灯片列表生成空演示文稿 + +- **WHEN** YAML 中 slides 列表为空 +- **THEN** 系统生成一个不包含任何幻灯片的 PPTX 文件（或抛出警告） + +### Requirement: 系统必须使用空白布局 + +系统 SHALL 为每个幻灯片使用空白布局（blank layout），以便完全自定义内容。 + +#### Scenario: 使用空白布局添加幻灯片 + +- **WHEN** 系统添加幻灯片 +- **THEN** 使用 `prs.slide_layouts[6]`（空白布局）而非预定义布局 + +#### Scenario: 空白幻灯片不包含占位符 + +- **WHEN** 创建新的空白幻灯片 +- **THEN** 幻灯片不包含任何预定义的标题或内容占位符 + +### Requirement: 系统必须保存到指定路径 + +系统 SHALL 将生成的 PPTX 文件保存到用户指定的路径。 + +#### Scenario: 保存到指定文件路径 + +- **WHEN** 用户指定输出路径为 `output/presentation.pptx` +- **THEN** 系统将 PPTX 文件保存到该路径 + +#### Scenario: 自动创建输出目录 + +- **WHEN** 输出路径包含不存在的目录（如 `output/subdir/file.pptx`） +- **THEN** 系统自动创建所需的目录结构 + +#### Scenario: 输出路径已存在时覆盖 + +- **WHEN** 指定的输出文件路径已存在 +- **THEN** 系统覆盖原有文件（或提供选项询问用户） + +#### Scenario: 无写入权限时报错 + +- **WHEN** 输出路径没有写入权限 +- **THEN** 系统抛出错误，提示权限不足 + +### Requirement: 系统必须使用 python-pptx 的单位转换函数 + +系统 SHALL 使用 python-pptx 提供的 Inches() 函数将英寸值转换为 EMU（English Metric Units）。 + +#### Scenario: 使用 Inches() 转换坐标 + +- **WHEN** 元素 box 定义为 `[1, 2, 8, 3]` +- **THEN** 系统调用 `Inches(1)`, `Inches(2)`, `Inches(8)`, `Inches(3)` 转换为 EMU + +#### Scenario: EMU 转换的精度 + +- **WHEN** 使用 Inches(1.0) +- **THEN** 返回值为 914400 EMU（1 英寸 = 914400 EMU） + +### Requirement: 系统必须处理颜色转换 + +系统 SHALL 将十六进制颜色值（如 "#4a90e2"）转换为 python-pptx 的 RGBColor 对象。 + +#### Scenario: 十六进制颜色转 RGB + +- **WHEN** 颜色值为 "#4a90e2" +- **THEN** 系统转换为 RGBColor(74, 144, 226) + +#### Scenario: 短格式十六进制颜色 + +- **WHEN** 颜色值为 "#fff"（短格式） +- **THEN** 系统扩展为 "#ffffff" 并转换为 RGBColor(255, 255, 255) + +#### Scenario: 无效颜色格式报错 + +- **WHEN** 颜色值不是有效的十六进制格式 +- **THEN** 系统抛出错误，提示颜色格式无效 + +### Requirement: 系统必须使用 uv 运行 Python 脚本 + +系统 SHALL 使用 uv 运行转换脚本，通过 Inline script metadata 指定依赖。 + +#### Scenario: 脚本包含 Inline script metadata + +- **WHEN** 查看 `yaml2pptx.py` 文件头部 +- **THEN** 包含 `# /// script` 块，定义 python-pptx 和 PyYAML 依赖 + +#### Scenario: 使用 uv 运行脚本 + +- **WHEN** 执行转换命令 +- **THEN** 使用 `uv run yaml2pptx.py` 而非 `python yaml2pptx.py` + +#### Scenario: 禁止直接安装依赖 + +- **WHEN** 需要使用 python-pptx 或 PyYAML +- **THEN** 不使用 `pip install`，而是在 script metadata 中声明依赖 + +### Requirement: 系统架构保持简洁 + +系统 SHALL 采用两层架构（模板 + 演示文稿），颜色和样式直接在模板中定义。 + +#### Scenario: 模板自包含样式 + +- **WHEN** 查看模板文件 +- **THEN** 颜色值直接以十六进制格式指定（如 "#4a90e2"） + +#### Scenario: 无需主题配置 + +- **WHEN** 创建新的演示文稿 +- **THEN** metadata 中不需要指定 theme 字段 + +#### Scenario: 模板独立配色 + +- **WHEN** 创建新模板 +- **THEN** 可以为该模板定义独立的颜色方案，不受其他模板影响 + +### Requirement: 系统必须提供命令行接口 + +系统 SHALL 提供命令行接口，接受输入 YAML 文件路径和输出 PPTX 文件路径。 + +#### Scenario: 基本命令行使用 + +- **WHEN** 执行 `uv run yaml2pptx.py input.yaml output.pptx` +- **THEN** 系统读取 input.yaml，生成 output.pptx + +#### Scenario: 仅提供输入文件时自动命名输出 + +- **WHEN** 执行 `uv run yaml2pptx.py input.yaml` +- **THEN** 系统自动生成输出文件名为 `input.pptx` + +#### Scenario: 显示帮助信息 + +- **WHEN** 执行 `uv run yaml2pptx.py --help` +- **THEN** 系统显示使用说明和参数列表 + +#### Scenario: 输入文件不存在时报错 + +- **WHEN** 提供的输入文件路径不存在 +- **THEN** 系统抛出错误，提示输入文件未找到 + +### Requirement: 系统必须报告转换进度 + +系统 SHALL 在转换过程中输出进度信息，包括当前处理的幻灯片数量。 + +#### Scenario: 输出转换开始信息 + +- **WHEN** 开始转换 +- **THEN** 系统输出 "开始转换: input.yaml" + +#### Scenario: 输出幻灯片处理进度 + +- **WHEN** 处理每个幻灯片 +- **THEN** 系统输出 "处理幻灯片 N/M" + +#### Scenario: 输出转换完成信息 + +- **WHEN** 转换成功完成 +- **THEN** 系统输出 "转换完成: output.pptx" + +#### Scenario: 转换失败时输出错误 + +- **WHEN** 转换过程中发生错误 +- **THEN** 系统输出详细的错误信息和堆栈跟踪（调试模式下） diff --git a/openspec/specs/template-directory-cli/spec.md b/openspec/specs/template-directory-cli/spec.md new file mode 100644 index 0000000..4aeb34a --- /dev/null +++ b/openspec/specs/template-directory-cli/spec.md @@ -0,0 +1,83 @@ +# Template Directory CLI + +## Purpose + +提供命令行参数支持，允许用户通过 `--template-dir` 参数明确指定模板文件目录，使脚本可以在任何位置运行而不依赖特定的目录结构。 + +## Requirements + +### Requirement: 系统必须支持 --template-dir 命令行参数 + +系统 SHALL 提供 `--template-dir` 命令行参数，允许用户指定模板文件目录的路径。 + +#### Scenario: 指定绝对路径的模板目录 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir /path/to/templates` +- **THEN** 系统使用 `/path/to/templates` 作为模板目录 + +#### Scenario: 指定相对路径的模板目录 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir ./templates` +- **THEN** 系统将相对路径解析为相对于当前工作目录（CWD）的绝对路径 + +#### Scenario: Windows 路径格式支持 + +- **WHEN** Windows 用户运行 `uv run yaml2pptx.py input.yaml --template-dir C:\Users\me\templates` +- **THEN** 系统正确解析 Windows 路径格式 + +#### Scenario: 不指定 template-dir 参数且不使用模板 + +- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`，且 YAML 文件中所有幻灯片都是自定义幻灯片（不使用模板） +- **THEN** 系统正常处理，不报错 + +### Requirement: 使用模板时必须指定 template-dir + +系统 SHALL 在 YAML 文件中使用了模板但未指定 `--template-dir` 参数时报错。 + +#### Scenario: 使用模板但未指定 template-dir + +- **WHEN** YAML 文件中包含 `template: title-slide`，但用户未提供 `--template-dir` 参数 +- **THEN** 系统抛出错误，提示"未指定模板目录，无法加载模板: title-slide"，并建议使用 `--template-dir` 参数 + +#### Scenario: 错误信息包含使用示例 + +- **WHEN** 系统因未指定 template-dir 而报错 +- **THEN** 错误信息中包含"请使用 --template-dir 参数指定模板目录"的提示 + +### Requirement: 系统必须支持跨平台路径处理 + +系统 SHALL 正确处理 Mac 和 Windows 平台的路径格式，包括路径分隔符和路径表示。 + +#### Scenario: Mac 路径格式 + +- **WHEN** Mac 用户指定 `--template-dir /Users/me/templates` +- **THEN** 系统正确解析 Unix 风格的路径 + +#### Scenario: Windows 路径格式（反斜杠） + +- **WHEN** Windows 用户指定 `--template-dir C:\templates` +- **THEN** 系统正确解析 Windows 风格的路径 + +#### Scenario: Windows 路径格式（正斜杠） + +- **WHEN** Windows 用户指定 `--template-dir C:/templates` +- **THEN** 系统正确解析路径（Windows 支持正斜杠） + +#### Scenario: 相对路径在不同平台 + +- **WHEN** 用户在任意平台指定 `--template-dir ./templates` +- **THEN** 系统根据当前平台的规则正确解析相对路径 + +### Requirement: 参数帮助信息必须清晰 + +系统 SHALL 在 `--help` 输出中提供清晰的 `--template-dir` 参数说明。 + +#### Scenario: 查看帮助信息 + +- **WHEN** 用户运行 `uv run yaml2pptx.py --help` +- **THEN** 帮助信息中包含 `--template-dir` 参数的说明，注明"如果 YAML 中使用了模板则必须指定" + +#### Scenario: 帮助信息包含路径说明 + +- **WHEN** 用户查看 `--template-dir` 的帮助信息 +- **THEN** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）" diff --git a/openspec/specs/template-system/spec.md b/openspec/specs/template-system/spec.md new file mode 100644 index 0000000..b9192c4 --- /dev/null +++ b/openspec/specs/template-system/spec.md @@ -0,0 +1,188 @@ +# Template System + +## Purpose + +Template system 提供可复用的幻灯片布局和样式定义。模板包含变量定义、元素列表，支持变量替换、条件渲染，以及从目录加载。颜色和样式直接在模板中定义，无需额外的主题抽象层。 + +## Requirements + +### Requirement: 模板必须定义变量列表 + +模板 SHALL 包含 vars 字段，定义该模板需要的变量，包括变量名、是否必需、默认值等。 + +#### Scenario: 加载模板变量定义 + +- **WHEN** 模板文件定义了 `vars` 列表，包含 `name`、`required`、`default` 等字段 +- **THEN** 系统成功加载变量定义，可通过模板对象访问 + +#### Scenario: 验证必需变量 + +- **WHEN** 模板定义了 `{name: title, required: true}` 的变量 +- **THEN** 渲染时如果未提供该变量，系统抛出错误 + +#### Scenario: 使用变量默认值 + +- **WHEN** 模板定义了 `{name: subtitle, required: false, default: ""}` 的变量 +- **THEN** 渲染时如果未提供该变量，系统使用空字符串作为默认值 + +### Requirement: 模板必须定义元素列表 + +模板 SHALL 包含 elements 字段，定义该模板的幻灯片布局和元素。 + +#### Scenario: 加载模板元素定义 + +- **WHEN** 模板文件定义了 `elements` 列表，包含文本、图片、形状等元素 +- **THEN** 系统成功加载元素列表，准备渲染 + +#### Scenario: 元素包含模板变量引用 + +- **WHEN** 模板元素中包含 `{title}` 等模板变量引用 +- **THEN** 系统在渲染时用用户提供的值替换变量 + +#### Scenario: 元素直接指定样式值 + +- **WHEN** 模板元素中直接指定 `color: "#4a90e2"` 等样式值 +- **THEN** 系统正确应用该样式值 + +### Requirement: 系统必须支持模板渲染 + +系统 SHALL 能够根据用户提供的变量值渲染模板，生成实际的元素列表。 + +#### Scenario: 渲染包含变量的模板 + +- **WHEN** 用户提供 `{title: "Hello", subtitle: "World"}` 渲染模板 +- **THEN** 系统将模板中的 `{title}` 替换为 "Hello"，`{subtitle}` 替换为 "World" + +#### Scenario: 数值类型自动转换 + +- **WHEN** 模板定义 `size: "{font_size}"` 且用户提供 `{font_size: "44"}` +- **THEN** 系统自动将字符串 "44" 转换为整数 44 + +#### Scenario: 检测未定义的模板变量 + +- **WHEN** 模板中引用了 `{undefined_var}`，但该变量未在 vars 中定义，也未由用户提供 +- **THEN** 系统抛出错误，指出未定义的变量 + +### Requirement: 系统必须支持条件渲染 + +系统 SHALL 支持基于变量值的条件渲染，通过 `visible` 字段控制元素是否显示。 + +#### Scenario: 显示满足条件的元素 + +- **WHEN** 元素定义了 `visible: "{subtitle != ''}\"`，且用户提供了非空的 subtitle +- **THEN** 系统渲染该元素 + +#### Scenario: 隐藏不满足条件的元素 + +- **WHEN** 元素定义了 `visible: "{subtitle != ''}\"`，但用户提供的 subtitle 为空字符串 +- **THEN** 系统跳过该元素，不渲染到幻灯片中 + +#### Scenario: 条件表达式语法错误 + +- **WHEN** visible 字段包含无效的条件表达式 +- **THEN** 系统抛出错误，提示条件表达式格式错误 + +### Requirement: 模板文件必须可从指定目录加载 + +系统 SHALL 从用户通过 `--template-dir` 参数指定的目录加载模板文件，支持通过模板名称引用。模板名称必须是纯文件名，不能包含路径分隔符。 + +#### Scenario: 通过名称加载模板 + +- **WHEN** 幻灯片指定 `template: title-slide`，且用户提供 `--template-dir /path/to/templates` +- **THEN** 系统从 `/path/to/templates/title-slide.yaml` 加载模板文件 + +#### Scenario: 模板文件不存在时报错 + +- **WHEN** 幻灯片引用不存在的模板名称 +- **THEN** 系统抛出错误，提示"模板文件不存在: <模板名>"，并显示查找位置和期望文件路径 + +#### Scenario: 缓存已加载的模板 + +- **WHEN** 多个幻灯片使用同一个模板 +- **THEN** 系统仅加载一次模板文件，后续使用缓存 + +#### Scenario: 错误信息包含详细的查找信息 + +- **WHEN** 模板文件未找到 +- **THEN** 错误信息包含：模板名称、查找位置（template_dir）、期望文件的完整路径、解决建议 + +### Requirement: 系统必须支持自定义幻灯片 + +系统 SHALL 支持不使用模板，直接定义元素的自定义幻灯片。 + +#### Scenario: 渲染自定义幻灯片 + +- **WHEN** 幻灯片未指定 `template` 字段，直接包含 `elements` 列表 +- **THEN** 系统跳过模板渲染，直接处理元素列表 + +#### Scenario: 自定义幻灯片中直接指定样式 + +- **WHEN** 自定义幻灯片的元素直接指定 `color: "#4a90e2"` +- **THEN** 系统正确应用该颜色值 + +#### Scenario: 自定义幻灯片和模板混合使用 + +- **WHEN** 演示文稿中部分幻灯片使用模板，部分为自定义 +- **THEN** 系统正确处理两种类型的幻灯片 + +### Requirement: 模板变量解析必须深度递归 + +系统 SHALL 递归解析模板元素的所有嵌套字段中的变量引用。 + +#### Scenario: 解析嵌套对象中的变量 + +- **WHEN** 模板元素定义了 `font: {size: "{font_size}", color: "{text_color}"}` +- **THEN** 系统正确解析嵌套对象中的所有变量引用 + +#### Scenario: 解析数组中的变量 + +- **WHEN** 模板元素定义了 `box: ["{left}", 2, 8, 3]` +- **THEN** 系统正确解析数组中的变量引用 + +#### Scenario: 解析多层嵌套的变量 + +- **WHEN** 模板包含复杂的嵌套结构，多层使用变量引用 +- **THEN** 系统递归解析所有层级的变量，直到无变量引用为止 + +### Requirement: 模板名称必须是纯文件名 + +系统 SHALL 验证模板名称不包含路径分隔符，确保模板只能从指定目录的一层加载。 + +#### Scenario: 拒绝包含正斜杠的模板名称 + +- **WHEN** 幻灯片指定 `template: subdir/title-slide` +- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir/title-slide" + +#### Scenario: 拒绝包含反斜杠的模板名称 + +- **WHEN** 幻灯片指定 `template: subdir\title-slide` +- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir\title-slide" + +#### Scenario: 拒绝路径遍历尝试 + +- **WHEN** 幻灯片指定 `template: ../other-templates/slide` +- **THEN** 系统抛出错误，提示模板名称不能包含路径分隔符 + +#### Scenario: 接受纯文件名 + +- **WHEN** 幻灯片指定 `template: title-slide`（不包含路径分隔符） +- **THEN** 系统正常处理，从指定的 template_dir 加载模板 + +#### Scenario: 错误信息提供正确格式示例 + +- **WHEN** 系统因模板名称包含路径分隔符而报错 +- **THEN** 错误信息中包含"模板名称应该是纯文件名，如: 'title-slide'"的提示 + +### Requirement: 未指定模板目录时必须报错 + +系统 SHALL 在用户未提供 `--template-dir` 参数但 YAML 文件中使用了模板时，立即报错。 + +#### Scenario: 使用模板但未指定目录 + +- **WHEN** YAML 文件中包含 `template: title-slide`，但 `templates_dir` 参数为 `None` +- **THEN** 系统在尝试加载模板时抛出错误，提示"未指定模板目录，无法加载模板" + +#### Scenario: 不使用模板时不检查目录 + +- **WHEN** YAML 文件中所有幻灯片都是自定义幻灯片（不包含 `template` 字段） +- **THEN** 系统不检查 `templates_dir` 是否为 `None`，正常处理 diff --git a/openspec/specs/yaml-parsing/spec.md b/openspec/specs/yaml-parsing/spec.md new file mode 100644 index 0000000..6afbfcc --- /dev/null +++ b/openspec/specs/yaml-parsing/spec.md @@ -0,0 +1,97 @@ +# YAML Parsing + +## Purpose + +YAML parsing 系统负责读取和验证演示文稿和模板的 YAML 文件。它支持 UTF-8 编码、验证颜色格式、验证文件结构，并提供清晰的错误消息帮助用户定位问题。 + +## Requirements + +### Requirement: 系统必须能解析演示文稿 YAML 文件 + +系统 SHALL 能够解析包含 metadata 和 slides 的演示文稿 YAML 文件，并验证其结构的正确性。 + +#### Scenario: 解析有效的演示文稿 YAML + +- **WHEN** 提供一个包含 `metadata` 和 `slides` 字段的 YAML 文件 +- **THEN** 系统成功解析并返回 Python 字典结构 + +#### Scenario: 检测缺少必需字段 + +- **WHEN** 提供的 YAML 文件缺少 `slides` 字段 +- **THEN** 系统抛出验证错误，明确指出缺少必需字段 + +#### Scenario: 处理无效的 YAML 语法 + +- **WHEN** 提供的文件包含无效的 YAML 语法（如缩进错误） +- **THEN** 系统抛出解析错误，包含行号和错误描述 + +### Requirement: 系统必须验证颜色值格式 + +系统 SHALL 验证模板和演示文稿 YAML 文件中的颜色值为有效的十六进制格式。 + +#### Scenario: 验证有效的颜色值 + +- **WHEN** 模板或演示文稿 YAML 文件中包含 `color: "#4a90e2"` 的颜色值 +- **THEN** 系统接受该颜色值 + +#### Scenario: 验证颜色值格式错误 + +- **WHEN** 颜色值格式不正确（如 "blue" 或 "#xyz"） +- **THEN** 系统抛出验证错误，提示使用 #RRGGBB 格式 + +#### Scenario: 支持短格式颜色值 + +- **WHEN** 颜色值为短格式 "#fff" +- **THEN** 系统自动扩展为 "#ffffff" 并接受 + +### Requirement: 系统必须能解析模板 YAML 文件 + +系统 SHALL 能够解析包含 vars 定义和 elements 列表的模板 YAML 文件。 + +#### Scenario: 解析有效的模板文件 + +- **WHEN** 提供一个包含 `vars` 和 `elements` 字段的模板 YAML 文件 +- **THEN** 系统成功解析并返回模板对象 + +#### Scenario: 验证变量定义的完整性 + +- **WHEN** 模板 vars 中的变量缺少 `name` 字段 +- **THEN** 系统抛出验证错误，指出变量定义不完整 + +#### Scenario: 验证必需变量标记 + +- **WHEN** 模板 vars 中定义了 `required: true` 的变量 +- **THEN** 系统记录该变量为必需变量，在渲染时必须提供值 + +### Requirement: 系统必须支持 UTF-8 编码 + +系统 SHALL 以 UTF-8 编码读取所有 YAML 文件，支持中文等多字节字符。 + +#### Scenario: 解析包含中文的 YAML 文件 + +- **WHEN** 提供包含中文字符的 YAML 文件 +- **THEN** 系统正确解析中文内容，不出现乱码 + +#### Scenario: 处理 BOM 标记 + +- **WHEN** YAML 文件包含 UTF-8 BOM 标记 +- **THEN** 系统能够正确处理并解析文件内容 + +### Requirement: 系统必须提供清晰的错误消息 + +系统 SHALL 在 YAML 解析失败时提供包含文件路径、行号、错误原因的详细错误消息。 + +#### Scenario: YAML 语法错误的错误消息 + +- **WHEN** YAML 文件在第 10 行存在缩进错误 +- **THEN** 错误消息包含 "文件路径, 第 10 行: 缩进错误" 等信息 + +#### Scenario: 文件不存在的错误消息 + +- **WHEN** 尝试加载不存在的 YAML 文件 +- **THEN** 错误消息明确指出文件路径不存在 + +#### Scenario: 权限不足的错误消息 + +- **WHEN** YAML 文件存在但没有读取权限 +- **THEN** 错误消息提示权限不足，无法读取文件 diff --git a/yaml2pptx.py b/yaml2pptx.py new file mode 100644 index 0000000..0fbd1d6 --- /dev/null +++ b/yaml2pptx.py @@ -0,0 +1,1241 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.8" +# dependencies = [ +# "python-pptx", +# "pyyaml", +# "flask", +# "watchdog", +# ] +# /// + +""" +YAML to PPTX Converter +将 YAML 格式的演示文稿源文件转换为 PPTX 文件 + +使用方法: + uv run yaml2pptx.py input.yaml output.pptx + uv run yaml2pptx.py input.yaml # 自动生成 input.pptx +""" + +import sys +import argparse +import re +from pathlib import Path +import yaml +from pptx import Presentation as PptxPresentation +from pptx.util import Inches, Pt +from pptx.enum.text import PP_ALIGN +from pptx.enum.shapes import MSO_SHAPE +from pptx.dml.color import RGBColor + + +# ============= 日志输出函数 ============= + +def log_info(message): + """输出信息日志""" + print(f"[INFO] {message}") + + +def log_success(message): + """输出成功日志""" + print(f"[SUCCESS] ✓ {message}") + + +def log_error(message): + """输出错误日志""" + print(f"[ERROR] ✗ {message}", file=sys.stderr) + + +def log_progress(current, total, message=""): + """输出进度日志""" + print(f"[PROGRESS] {current}/{total} {message}") + + +# ============= YAML 解析和验证 ============= + +class YAMLError(Exception): + """YAML 相关错误""" + pass + + +def load_yaml_file(file_path): + """ + 加载 YAML 文件（UTF-8 编码，错误处理） + + Args: + file_path: 文件路径（字符串或 Path 对象） + + Returns: + 解析后的 Python 字典 + + Raises: + YAMLError: 文件不存在、权限不足、YAML 语法错误等 + """ + file_path = Path(file_path) + + # 检查文件是否存在 + if not file_path.exists(): + raise YAMLError(f"文件不存在: {file_path}") + + # 检查是否有读取权限 + if not file_path.is_file(): + raise YAMLError(f"不是有效的文件: {file_path}") + + try: + with open(file_path, 'r', encoding='utf-8') as f: + data = yaml.safe_load(f) + return data + except PermissionError: + raise YAMLError(f"权限不足，无法读取文件: {file_path}") + except yaml.YAMLError as e: + # 提取行号信息 + if hasattr(e, 'problem_mark'): + mark = e.problem_mark + raise YAMLError( + f"YAML 语法错误: {file_path}, 第 {mark.line + 1} 行: {e.problem}" + ) + else: + raise YAMLError(f"YAML 解析错误: {file_path}: {str(e)}") + except Exception as e: + raise YAMLError(f"读取文件失败: {file_path}: {str(e)}") + + +def validate_color(color_value): + """ + 验证颜色值格式（十六进制 #RRGGBB 或 #RGB） + + Args: + color_value: 颜色字符串 + + Returns: + bool: 是否有效 + """ + if not isinstance(color_value, str): + return False + # 匹配 #RRGGBB 或 #RGB 格式 + pattern = r'^#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$' + return re.match(pattern, color_value) is not None + + +def validate_presentation_yaml(data, file_path=""): + """ + 验证演示文稿 YAML 结构（必需字段：slides） + + Args: + data: 解析后的 YAML 数据 + file_path: 文件路径（用于错误消息） + + Raises: + YAMLError: 结构验证失败 + """ + if not isinstance(data, dict): + raise YAMLError(f"{file_path}: 演示文稿必须是一个字典对象") + + # 验证 slides 字段 + if 'slides' not in data: + raise YAMLError(f"{file_path}: 缺少必需字段 'slides'") + + if not isinstance(data['slides'], list): + raise YAMLError(f"{file_path}: 'slides' 必须是一个列表") + + + + +def validate_template_yaml(data, file_path=""): + """ + 验证模板 YAML 结构（vars, elements） + + Args: + data: 解析后的 YAML 数据 + file_path: 文件路径（用于错误消息） + + Raises: + YAMLError: 结构验证失败 + """ + if not isinstance(data, dict): + raise YAMLError(f"{file_path}: 模板必须是一个字典对象") + + # 验证 vars 字段 + if 'vars' in data: + if not isinstance(data['vars'], list): + raise YAMLError(f"{file_path}: 'vars' 必须是一个列表") + + # 验证每个变量定义 + for i, var_def in enumerate(data['vars']): + if not isinstance(var_def, dict): + raise YAMLError(f"{file_path}: vars[{i}] 必须是一个字典对象") + if 'name' not in var_def: + raise YAMLError(f"{file_path}: vars[{i}] 缺少必需字段 'name'") + + # 验证 elements 字段 + if 'elements' not in data: + raise YAMLError(f"{file_path}: 缺少必需字段 'elements'") + + if not isinstance(data['elements'], list): + raise YAMLError(f"{file_path}: 'elements' 必须是一个列表") + + + + +# ============= 模板系统 ============= + +class Template: + """模板类，管理可复用的幻灯片布局""" + + def __init__(self, template_file, templates_dir=None): + """ + 初始化模板 + + Args: + template_file: 模板名称（纯文件名，不含路径） + templates_dir: 模板文件目录 + """ + # 检查是否提供了 templates_dir + if templates_dir is None: + raise YAMLError( + f"未指定模板目录，无法加载模板: {template_file}\n" + f"请使用 --template-dir 参数指定模板目录" + ) + + # 验证模板名称（不能包含路径分隔符） + if '/' in template_file or '\\' in template_file: + raise YAMLError( + f"模板名称不能包含路径分隔符: {template_file}\n" + f"模板名称应该是纯文件名，如: 'title-slide'" + ) + + # 构建模板路径 + template_path = Path(templates_dir) / f"{template_file}.yaml" + + # 检查文件是否存在 + if not template_path.exists(): + raise YAMLError( + f"模板文件不存在: {template_file}\n" + f"查找位置: {templates_dir}\n" + f"期望文件: {template_path}\n" + f"提示: 请检查模板名称和模板目录是否正确" + ) + + # 加载并验证模板文件 + self.data = load_yaml_file(template_path) + validate_template_yaml(self.data, str(template_path)) + + # 解析变量定义 + self.vars_def = {} + for var in self.data.get('vars', []): + self.vars_def[var['name']] = var + + # 元素列表 + self.elements = self.data.get('elements', []) + + def resolve_value(self, value, vars_values): + """ + 解析单个值中的变量引用 + + Args: + value: 要解析的值 + vars_values: 用户提供的变量值字典 + + Returns: + 解析后的值 + """ + if not isinstance(value, str): + return value + + # 匹配 {xxx} 模式 + pattern = r'\{([^}]+)\}' + + def replacer(match): + expr = match.group(1) + + # 模板变量: {title} + if expr in vars_values: + return str(vars_values[expr]) + else: + raise YAMLError(f"未定义的变量: {expr}") + + result = re.sub(pattern, replacer, value) + + # 如果结果是纯数字字符串，转换回数字类型 + try: + # 尝试转换为整数 + if '.' not in result: + return int(result) + # 尝试转换为浮点数 + else: + return float(result) + except ValueError: + # 不是数字，返回字符串 + return result + + def resolve_element(self, elem, vars_values): + """ + 递归解析元素中的所有变量 + + Args: + elem: 元素（dict, list, 或其他类型） + vars_values: 用户提供的变量值字典 + + Returns: + 解析后的元素 + """ + if isinstance(elem, dict): + return {k: self.resolve_element(v, vars_values) + for k, v in elem.items() if k != 'visible'} + elif isinstance(elem, list): + return [self.resolve_element(item, vars_values) + for item in elem] + elif isinstance(elem, str): + return self.resolve_value(elem, vars_values) + else: + return elem + + def evaluate_condition(self, condition, vars_values): + """ + 评估条件表达式（简单的存在性检查） + + Args: + condition: 条件字符串，如 "{subtitle != ''}" + vars_values: 变量值字典 + + Returns: + bool: 条件是否满足 + """ + # 简单实现：检查变量是否非空 + # 匹配 {var_name != ''} 或 {var_name != ""} + pattern = r'\{(\w+)\s*!=\s*[\'\"]{2}\}' + match = re.match(pattern, condition) + + if match: + var_name = match.group(1) + value = vars_values.get(var_name, '') + return value != '' + + # 默认返回 True + return True + + def render(self, vars_values): + """ + 渲染模板，返回实际的元素列表 + + Args: + vars_values: 用户提供的变量值字典 + + Returns: + list: 渲染后的元素列表 + + Raises: + YAMLError: 缺少必需变量 + """ + # 填充所有变量的默认值（如果用户未提供） + for var_name, var_def in self.vars_def.items(): + if var_name not in vars_values: + # 检查是否是必需变量 + if var_def.get('required', False): + # 必需变量必须有默认值或用户提供 + if 'default' in var_def: + vars_values[var_name] = self.resolve_value( + var_def['default'], vars_values + ) + else: + raise YAMLError(f"缺少必需变量: {var_name}") + else: + # 可选变量使用默认值（如果有） + if 'default' in var_def: + vars_values[var_name] = self.resolve_value( + var_def['default'], vars_values + ) + + # 渲染所有元素 + rendered_elements = [] + for elem in self.elements: + # 检查条件渲染 + if 'visible' in elem: + if not self.evaluate_condition(elem['visible'], vars_values): + continue + + # 深度解析元素中的所有变量引用 + rendered_elem = self.resolve_element(elem, vars_values) + rendered_elements.append(rendered_elem) + + return rendered_elements + + +# ============= 元素渲染函数 ============= + +def hex_to_rgb(hex_color): + """ + 将十六进制颜色转换为 RGB 元组 + + Args: + hex_color: 十六进制颜色字符串，如 "#4a90e2" 或 "#fff" + + Returns: + tuple: (R, G, B) 元组 + """ + hex_color = hex_color.lstrip('#') + + # 处理短格式 #RGB -> #RRGGBB + if len(hex_color) == 3: + hex_color = ''.join([c*2 for c in hex_color]) + + if len(hex_color) != 6: + raise YAMLError(f"无效的颜色格式: #{hex_color}") + + try: + return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4)) + except ValueError: + raise YAMLError(f"无效的颜色格式: #{hex_color}") + + +def add_text_element(slide, elem, base_path=None): + """ + 添加文本元素到幻灯片 + + Args: + slide: pptx slide 对象 + elem: 文本元素字典 + base_path: 基础路径（用于相对路径解析） + """ + # 获取位置和尺寸 + box = elem.get('box', [1, 1, 8, 1]) + x, y, w, h = [Inches(v) for v in box] + + # 创建文本框 + textbox = slide.shapes.add_textbox(x, y, w, h) + tf = textbox.text_frame + tf.text = elem.get('content', '') + + # 应用字体样式 + font_style = elem.get('font', {}) + p = tf.paragraphs[0] + + # 字体大小 + if 'size' in font_style: + p.font.size = Pt(font_style['size']) + + # 粗体 + if font_style.get('bold'): + p.font.bold = True + + # 斜体 + if font_style.get('italic'): + p.font.italic = True + + # 颜色 + if 'color' in font_style: + rgb = hex_to_rgb(font_style['color']) + p.font.color.rgb = RGBColor(*rgb) + + # 对齐方式 + align_map = { + 'left': PP_ALIGN.LEFT, + 'center': PP_ALIGN.CENTER, + 'right': PP_ALIGN.RIGHT + } + align = font_style.get('align', 'left') + p.alignment = align_map.get(align, PP_ALIGN.LEFT) + + +def add_image_element(slide, elem, base_path=None): + """ + 添加图片元素到幻灯片 + + Args: + slide: pptx slide 对象 + elem: 图片元素字典 + base_path: 基础路径（用于相对路径解析） + """ + # 获取图片路径 + src = elem.get('src', '') + img_path = Path(src) + + # 处理相对路径 + if not img_path.is_absolute() and base_path: + img_path = Path(base_path) / src + + # 检查文件是否存在 + if not img_path.exists(): + raise YAMLError(f"图片文件未找到: {img_path}") + + # 获取位置和尺寸 + box = elem.get('box', [1, 1, 4, 3]) + x, y, w, h = [Inches(v) for v in box] + + # 添加图片 + try: + slide.shapes.add_picture(str(img_path), x, y, width=w, height=h) + except Exception as e: + raise YAMLError(f"添加图片失败: {img_path}: {str(e)}") + + +def add_shape_element(slide, elem, base_path=None): + """ + 添加形状元素到幻灯片 + + Args: + slide: pptx slide 对象 + elem: 形状元素字典 + base_path: 基础路径（用于相对路径解析） + """ + # 获取形状类型 + shape_type_map = { + 'rectangle': MSO_SHAPE.RECTANGLE, + 'ellipse': MSO_SHAPE.OVAL, + 'rounded_rectangle': MSO_SHAPE.ROUNDED_RECTANGLE, + } + shape_type = elem.get('shape', 'rectangle') + mso_shape = shape_type_map.get(shape_type, MSO_SHAPE.RECTANGLE) + + # 获取位置和尺寸 + box = elem.get('box', [1, 1, 2, 1]) + x, y, w, h = [Inches(v) for v in box] + + # 添加形状 + shape = slide.shapes.add_shape(mso_shape, x, y, w, h) + + # 应用填充色 + if 'fill' in elem: + rgb = hex_to_rgb(elem['fill']) + shape.fill.solid() + shape.fill.fore_color.rgb = RGBColor(*rgb) + + # 应用边框样式 + if 'line' in elem: + line_style = elem['line'] + if 'color' in line_style: + rgb = hex_to_rgb(line_style['color']) + shape.line.color.rgb = RGBColor(*rgb) + if 'width' in line_style: + shape.line.width = Pt(line_style['width']) + + +def add_table_element(slide, elem, base_path=None): + """ + 添加表格元素到幻灯片 + + Args: + slide: pptx slide 对象 + elem: 表格元素字典 + base_path: 基础路径（用于相对路径解析） + """ + # 获取表格数据 + data = elem.get('data', []) + if not data: + raise YAMLError("表格数据不能为空") + + rows = len(data) + cols = len(data[0]) if data else 0 + + # 获取列宽 + col_widths = elem.get('col_widths', [2] * cols) + if len(col_widths) != cols: + raise YAMLError(f"列宽数量({len(col_widths)})与列数({cols})不匹配") + + # 获取位置 + position = elem.get('position', [1, 1]) + x, y = [Inches(v) for v in position] + + # 计算总宽度和高度 + total_width = Inches(sum(col_widths)) + row_height = Inches(0.5) + + # 创建表格 + table = slide.shapes.add_table(rows, cols, x, y, total_width, row_height * rows).table + + # 设置列宽 + for i, width in enumerate(col_widths): + table.columns[i].width = Inches(width) + + # 填充数据 + for i, row_data in enumerate(data): + for j, cell_value in enumerate(row_data): + cell = table.cell(i, j) + cell.text = str(cell_value) + + # 应用样式 + style = elem.get('style', {}) + + # 字体大小 + if 'font_size' in style: + for row in table.rows: + for cell in row.cells: + cell.text_frame.paragraphs[0].font.size = Pt(style['font_size']) + + # 表头样式 + if 'header_bg' in style or 'header_color' in style: + for i, cell in enumerate(table.rows[0].cells): + if 'header_bg' in style: + rgb = hex_to_rgb(style['header_bg']) + cell.fill.solid() + cell.fill.fore_color.rgb = RGBColor(*rgb) + if 'header_color' in style: + rgb = hex_to_rgb(style['header_color']) + cell.text_frame.paragraphs[0].font.color.rgb = RGBColor(*rgb) + + +def set_slide_background(slide, background, base_path=None): + """ + 设置幻灯片背景 + + Args: + slide: pptx slide 对象 + background: 背景字典，包含 color 或 image + base_path: 基础路径（用于相对路径解析） + """ + if not background: + return + + # 纯色背景 + if 'color' in background: + bg = slide.background + fill = bg.fill + fill.solid() + rgb = hex_to_rgb(background['color']) + fill.fore_color.rgb = RGBColor(*rgb) + + # 图片背景（可选功能，简单实现） + elif 'image' in background: + # 图片背景需要更复杂的处理，暂时跳过 + log_info(f"图片背景暂未实现: {background['image']}") + + +def validate_element_type(elem): + """ + 验证元素类型 + + Args: + elem: 元素字典 + + Raises: + YAMLError: 元素类型无效或缺失 + """ + if 'type' not in elem: + raise YAMLError("元素缺少 'type' 字段") + + elem_type = elem['type'] + supported_types = ['text', 'image', 'shape', 'table'] + + if elem_type not in supported_types: + raise YAMLError( + f"不支持的元素类型: '{elem_type}'，" + f"支持的类型: {', '.join(supported_types)}" + ) + + +# ============= 演示文稿和 PPTX 生成 ============= + +class Presentation: + """演示文稿类，管理整个演示文稿的生成流程""" + + def __init__(self, pres_file, templates_dir=None): + """ + 初始化演示文稿 + + Args: + pres_file: 演示文稿 YAML 文件路径 + templates_dir: 模板目录 + """ + self.pres_file = Path(pres_file) + self.templates_dir = templates_dir + + # 加载演示文稿文件 + self.data = load_yaml_file(pres_file) + validate_presentation_yaml(self.data, str(pres_file)) + + # 获取演示文稿尺寸 + metadata = self.data.get('metadata', {}) + self.size = metadata.get('size', '16:9') + + # 模板缓存 + self.template_cache = {} + + def get_template(self, template_name): + """ + 获取模板（带缓存） + + Args: + template_name: 模板名称 + + Returns: + Template 对象 + """ + if template_name not in self.template_cache: + self.template_cache[template_name] = Template( + template_name, self.templates_dir + ) + return self.template_cache[template_name] + + def render_slide(self, slide_data): + """ + 渲染单个幻灯片 + + Args: + slide_data: 幻灯片数据字典 + + Returns: + dict: 包含 background 和 elements 的字典 + """ + if 'template' in slide_data: + # 使用模板 + template_name = slide_data['template'] + template = self.get_template(template_name) + vars_values = slide_data.get('vars', {}) + elements = template.render(vars_values) + + # 合并背景（如果有） + background = slide_data.get('background', None) + + return { + 'background': background, + 'elements': elements + } + else: + # 自定义幻灯片 + return { + 'background': slide_data.get('background'), + 'elements': slide_data.get('elements', []) + } + + +class PptxGenerator: + """PPTX 生成器，封装 python-pptx 操作""" + + def __init__(self, size='16:9'): + """ + 初始化 PPTX 生成器 + + Args: + size: 幻灯片尺寸（"16:9" 或 "4:3"） + """ + self.prs = PptxPresentation() + + # 设置幻灯片尺寸 + if size == '16:9': + self.prs.slide_width = Inches(10) + self.prs.slide_height = Inches(5.625) + elif size == '4:3': + self.prs.slide_width = Inches(10) + self.prs.slide_height = Inches(7.5) + else: + raise YAMLError(f"不支持的尺寸比例: {size}，仅支持 16:9 和 4:3") + + def add_slide(self, slide_data, base_path=None): + """ + 添加幻灯片并渲染所有元素 + + Args: + slide_data: 包含 background 和 elements 的字典 + base_path: 基础路径（用于相对路径解析） + """ + # 使用空白布局（layout[6]） + blank_layout = self.prs.slide_layouts[6] + slide = self.prs.slides.add_slide(blank_layout) + + # 设置背景 + background = slide_data.get('background') + if background: + set_slide_background(slide, background, base_path) + + # 按顺序渲染所有元素 + elements = slide_data.get('elements', []) + for elem in elements: + # 验证元素类型 + validate_element_type(elem) + + elem_type = elem['type'] + if elem_type == 'text': + add_text_element(slide, elem, base_path) + elif elem_type == 'image': + add_image_element(slide, elem, base_path) + elif elem_type == 'shape': + add_shape_element(slide, elem, base_path) + elif elem_type == 'table': + add_table_element(slide, elem, base_path) + + def save(self, output_path): + """ + 保存 PPTX 文件 + + Args: + output_path: 输出文件路径 + """ + output_path = Path(output_path) + + # 自动创建输出目录 + output_path.parent.mkdir(parents=True, exist_ok=True) + + # 保存文件 + try: + self.prs.save(str(output_path)) + except PermissionError: + raise YAMLError(f"权限不足，无法写入文件: {output_path}") + except Exception as e: + raise YAMLError(f"保存文件失败: {output_path}: {str(e)}") + + +# ============= 浏览器预览功能 ============= + +# 固定 DPI 用于单位转换 +DPI = 96 + +# HTML 模板 +HTML_TEMPLATE = """ + + + + + YAML Preview + + + + {{ slides_html }} + + + + +""" + +ERROR_TEMPLATE = """ + + + + + 预览错误 + + + +
+

⚠️ YAML 解析错误

+ 
{{ error }}
+
+ + + +""" + + +def render_text_element_to_html(elem): + """将文本元素转换为 HTML""" + box = elem.get('box', [0, 0, 1, 1]) + font = elem.get('font', {}) + + style = f""" + left: {box[0] * DPI}px; + top: {box[1] * DPI}px; + width: {box[2] * DPI}px; + height: {box[3] * DPI}px; + font-size: {font.get('size', 16)}pt; + color: {font.get('color', '#000000')}; + text-align: {font.get('align', 'left')}; + {'font-weight: bold;' if font.get('bold') else ''} + {'font-style: italic;' if font.get('italic') else ''} + display: flex; + align-items: center; + white-space: pre-wrap; + """ + + content = elem.get('content', '').replace('<', '<').replace('>', '>') + return f'
{content}
' + + +def render_shape_element_to_html(elem): + """将形状元素转换为 HTML""" + box = elem.get('box', [0, 0, 1, 1]) + + border_radius = { + 'rectangle': '0', + 'ellipse': '50%', + 'rounded_rectangle': '8px' + }.get(elem.get('shape', 'rectangle'), '0') + + style = f""" + left: {box[0] * DPI}px; + top: {box[1] * DPI}px; + width: {box[2] * DPI}px; + height: {box[3] * DPI}px; + background: {elem.get('fill', 'transparent')}; + border-radius: {border_radius}; + """ + + if 'line' in elem: + line = elem['line'] + style += f""" + border: {line.get('width', 1)}pt solid {line.get('color', '#000000')}; + """ + + return f'
' + + +def render_table_element_to_html(elem): + """将表格元素转换为 HTML""" + position = elem.get('position', [0, 0]) + data = elem.get('data', []) + style_config = elem.get('style', {}) + + table_style = f""" + left: {position[0] * DPI}px; + top: {position[1] * DPI}px; + """ + + rows_html = "" + for i, row in enumerate(data): + cells_html = "" + for cell in row: + cell_style = f"font-size: {style_config.get('font_size', 14)}pt;" + + if i == 0: + if 'header_bg' in style_config: + cell_style += f"background: {style_config['header_bg']};" + if 'header_color' in style_config: + cell_style += f"color: {style_config['header_color']};" + + cell_content = str(cell).replace('<', '<').replace('>', '>') + cells_html += f'' + rows_html += f'{cells_html}' + + return f'
{cell_content}
{rows_html}
' + + +def render_image_element_to_html(elem, base_path): + """将图片元素转换为 HTML""" + box = elem.get('box', [0, 0, 1, 1]) + src = elem.get('src', '') + + img_path = Path(base_path) / src if base_path else Path(src) + + style = f""" + left: {box[0] * DPI}px; + top: {box[1] * DPI}px; + width: {box[2] * DPI}px; + height: {box[3] * DPI}px; + """ + + return f'' + + +def render_slide_to_html(slide_data, index, base_path): + """渲染单个幻灯片为 HTML""" + elements_html = "" + + bg_style = "" + if slide_data.get('background'): + bg = slide_data['background'] + if 'color' in bg: + bg_style = f"background: {bg['color']};" + + for elem in slide_data.get('elements', []): + elem_type = elem.get('type') + try: + if elem_type == 'text': + elements_html += render_text_element_to_html(elem) + elif elem_type == 'shape': + elements_html += render_shape_element_to_html(elem) + elif elem_type == 'table': + elements_html += render_table_element_to_html(elem) + elif elem_type == 'image': + elements_html += render_image_element_to_html(elem, base_path) + except Exception as e: + elements_html += f'
渲染错误: {str(e)}
' + + return f''' +
+
幻灯片 {index + 1}
+ {elements_html} +
+ ''' + + +def generate_preview_html(yaml_file, template_dir): + """生成完整的预览 HTML 页面""" + try: + pres = Presentation(yaml_file, template_dir) + + slides_html = "" + for i, slide_data in enumerate(pres.data.get('slides', [])): + rendered = pres.render_slide(slide_data) + slides_html += render_slide_to_html(rendered, i, Path(yaml_file).parent) + + return HTML_TEMPLATE.replace('{{ slides_html }}', slides_html) + + except YAMLError as e: + return ERROR_TEMPLATE.replace('{{ error }}', str(e)) + + +# Flask 应用和文件监听 +import queue +import webbrowser +import random +from threading import Thread + +try: + from flask import Flask, Response + from watchdog.observers import Observer + from watchdog.events import FileSystemEventHandler +except ImportError: + # 如果没有安装预览依赖，在使用时会报错 + Flask = None + Observer = None + FileSystemEventHandler = None + +# 全局变量 +app = None +change_queue = None +current_yaml_file = None +current_template_dir = None + + +class YAMLChangeHandler: + """文件变化处理器""" + def on_modified(self, event): + if event.src_path.endswith('.yaml'): + log_info(f"检测到文件变化: {event.src_path}") + if change_queue: + change_queue.put('reload') + + +def create_flask_app(): + """创建 Flask 应用""" + flask_app = Flask(__name__) + + @flask_app.route('/') + def index(): + """主页面""" + try: + return generate_preview_html(current_yaml_file, current_template_dir) + except Exception as e: + return ERROR_TEMPLATE.replace('{{ error }}', f"生成预览失败: {str(e)}") + + @flask_app.route('/events') + def events(): + """SSE 事件流""" + def event_stream(): + while True: + change_queue.get() + yield 'data: reload\n\n' + + return Response(event_stream(), mimetype='text/event-stream') + + return flask_app + + +def start_preview_server(yaml_file, template_dir, port): + """启动预览服务器""" + global app, change_queue, current_yaml_file, current_template_dir + + if Flask is None: + log_error("预览功能需要 flask 和 watchdog 依赖") + log_error("请确保使用 uv 运行脚本，依赖会自动安装") + sys.exit(1) + + # 如果没有指定端口，随机选择 20000-30000 之间的端口 + if port is None: + port = random.randint(20000, 30000) + + current_yaml_file = yaml_file + current_template_dir = template_dir + change_queue = queue.Queue() + + # 创建 Flask 应用 + app = create_flask_app() + + # 启动文件监听 + if FileSystemEventHandler: + handler = YAMLChangeHandler() + if hasattr(handler, 'on_modified'): + # 创建一个简单的事件处理器 + class SimpleHandler(FileSystemEventHandler): + def on_modified(self, event): + handler.on_modified(event) + + observer = Observer() + observer.schedule(SimpleHandler(), str(Path(yaml_file).parent), recursive=False) + observer.start() + + # 输出日志 + log_info(f"正在监听: {yaml_file}") + log_info(f"预览地址: http://localhost:{port}") + log_info("按 Ctrl+C 停止") + + # 自动打开浏览器 + Thread(target=lambda: webbrowser.open(f'http://localhost:{port}')).start() + + # 启动 Flask + try: + app.run(host='0.0.0.0', port=port, debug=False, threaded=True) + except OSError as e: + if 'Address already in use' in str(e): + log_error(f"端口 {port} 已被占用") + log_error(f"请使用 --port 参数指定其他端口，例如: --port {port + 1}") + else: + log_error(f"启动服务器失败: {str(e)}") + sys.exit(1) + except KeyboardInterrupt: + if 'observer' in locals(): + observer.stop() + observer.join() + log_info("已停止") + + +def parse_args(): + """解析命令行参数""" + parser = argparse.ArgumentParser( + description="将 YAML 格式的演示文稿源文件转换为 PPTX 文件" + ) + parser.add_argument( + "input", + type=str, + help="输入的 YAML 文件路径" + ) + parser.add_argument( + "output", + type=str, + nargs="?", + help="输出的 PPTX 文件路径（可选，默认为输入文件名.pptx）" + ) + parser.add_argument( + "--template-dir", + type=str, + default=None, + help="模板文件目录路径（如果 YAML 中使用了模板则必须指定）。可以是绝对路径或相对路径（相对于当前工作目录）" + ) + parser.add_argument( + "--preview", + action="store_true", + help="启动浏览器预览模式，而不是生成 PPTX 文件" + ) + parser.add_argument( + "--port", + type=int, + default=None, + help="预览服务器端口（默认随机选择 20000-30000 之间的端口）" + ) + return parser.parse_args() + + +def main(): + """主函数：加载 YAML → 渲染幻灯片 → 生成 PPTX""" + try: + args = parse_args() + + # 处理输入文件路径 + input_path = Path(args.input) + + # 预览模式 + if args.preview: + start_preview_server(input_path, args.template_dir, args.port) + return + + # PPTX 生成模式（原有逻辑） + # 处理输出文件路径 + if args.output: + output_path = Path(args.output) + else: + # 自动生成输出文件名 + output_path = input_path.with_suffix(".pptx") + + log_info(f"开始转换: {input_path}") + log_info(f"输出文件: {output_path}") + + # 1. 加载演示文稿 + log_info("加载演示文稿...") + pres = Presentation(input_path, templates_dir=args.template_dir) + + # 2. 创建 PPTX 生成器 + log_info(f"创建演示文稿 ({pres.size})...") + generator = PptxGenerator(pres.size) + + # 3. 渲染所有幻灯片 + slides_data = pres.data.get('slides', []) + total_slides = len(slides_data) + + for i, slide_data in enumerate(slides_data, 1): + log_progress(i, total_slides, f"处理幻灯片") + rendered_slide = pres.render_slide(slide_data) + generator.add_slide(rendered_slide, input_path.parent) + + # 4. 保存 PPTX 文件 + log_info("保存 PPTX 文件...") + generator.save(output_path) + + log_success(f"转换完成: {output_path}") + + except YAMLError as e: + log_error(str(e)) + sys.exit(1) + except Exception as e: + log_error(f"未知错误: {str(e)}") + import traceback + traceback.print_exc() + sys.exit(1) + + +if __name__ == "__main__": + main()