PPTX/openspec/changes/archive/2026-03-02-add-template-dir-parameter/design.md

## 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 明确性

**权衡**: 破坏性变更，不向后兼容

**理由**:
- 隐式默认行为是问题的根源
- 明确性比兼容性更重要
- 影响范围可控（只影响使用模板的用户）
- 修复成本低（只需添加一个参数）