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(+)

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

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 字段

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 `<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** 系统为幻灯片容器添加阴影：`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** 系统继续渲染其他元素，仅在失败位置显示错误提示

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** 系统输出详细的错误信息和堆栈跟踪（调试模式下）

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** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）"

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`，正常处理

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** 错误消息提示权限不足，无法读取文件