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(+)
2026-03-02 14:28:25 +08:00
parent 6cb422a72a
commit cd7988cbd5
30 changed files with 4984 additions and 0 deletions
--- 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
@@ -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 比例）
--- 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
@@ -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** 系统继续渲染其他元素，仅在失败位置显示错误提示