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-template-dir-parameter/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-02-add-template-dir-parameter/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02
--- 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
@@ -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 明确性
+
+**权衡**: 破坏性变更，不向后兼容
+
+**理由**:
+- 隐式默认行为是问题的根源
+- 明确性比兼容性更重要
+- 影响范围可控（只影响使用模板的用户）
+- 修复成本低（只需添加一个参数）
--- 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
@@ -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
+```
--- 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
@@ -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** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）"
--- 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
@@ -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`，正常处理
--- 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
@@ -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 上验证路径处理的跨平台兼容性