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

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