lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity

feat: initial implementation of html2pptx with OpenSpec documentation

Browse Source 
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(+)
This commit is contained in:
兰缘小妖
2026-03-02 14:28:25 +08:00
parent 6cb422a72a
commit cd7988cbd5
30 changed files with 4984 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
openspec/changes/archive/2026-03-02-add-browser-preview/.openspec.yaml Normal file
View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-03-02

250
openspec/changes/archive/2026-03-02-add-browser-preview/design.md Normal file
View File

@@ -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 渲染策略
**选择**: 使用 `<div>` + 内联样式渲染元素
**理由**:
- 简单直接，易于实现
- 使用绝对定位模拟 PPTX 的坐标系统
- 内联样式避免 CSS 类管理的复杂性
- 文本使用 `pt` 单位保持与 PPTX 一致
**元素映射**:
- 文本元素: `<div>` + `font-size: Xpt`
- 形状元素: `<div>` + `background-color` + `border-radius`
- 表格元素: `<table>` 标签
- 图片元素: `<img>` 标签
**替代方案**:
- 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. 是否需要显示元素边框和尺寸标注？
- 当前方案：不显示辅助信息
- 可选方案：添加调试模式，显示元素边框和尺寸
这些问题可以在实现后根据用户反馈决定是否添加。

50
openspec/changes/archive/2026-03-02-add-browser-preview/proposal.md Normal file
View File

@@ -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 渲染）

186
openspec/changes/archive/2026-03-02-add-browser-preview/specs/browser-preview-server/spec.md Normal file
View File

@@ -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 比例）

236
openspec/changes/archive/2026-03-02-add-browser-preview/specs/html-rendering/spec.md Normal file
View File

@@ -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 `<div>` 标签，应用相应的样式。
#### Scenario: 渲染基本文本元素
- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
- **THEN** 系统生成 `<div>` 标签，内容为 "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 `<div>` 标签，使用 CSS 样式模拟形状。
#### Scenario: 渲染矩形形状
- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}`
- **THEN** 系统生成 `<div>` 标签，背景色为 #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 `<table>` 标签。
#### Scenario: 渲染基本表格
- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}`
- **THEN** 系统生成 `<table>` 标签，位置为 (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 `<img>` 标签。
#### Scenario: 渲染本地图片
- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
- **THEN** 系统生成 `<img>` 标签，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** 系统继续渲染其他元素，仅在失败位置显示错误提示

79
openspec/changes/archive/2026-03-02-add-browser-preview/tasks.md Normal file
View File

@@ -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 `<div>` 标签
- [x] 3.2 实现 `render_shape_element_to_html(elem)` 函数，将形状元素转换为 HTML `<div>` 标签
- [x] 3.3 实现 `render_table_element_to_html(elem)` 函数，将表格元素转换为 HTML `<table>` 标签
- [x] 3.4 实现 `render_image_element_to_html(elem, base_path)` 函数，将图片元素转换为 HTML `<img>` 标签
- [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 可能存在差异