feat: 添加模板变量验证功能

- 在 ResourceValidator 中添加 validate_template_vars 方法
- 在验证阶段检查用户是否提供了模板所需的必需变量
- 缺少必需变量时返回 ERROR 级别错误
- 添加 9 个单元测试用例验证功能
- 同步更新 OpenSpec 规格文档

openspec/changes/archive/2026-03-03-add-template-variable-validation/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02

openspec/changes/archive/2026-03-03-add-template-variable-validation/design.md

@@ -0,0 +1,46 @@
+## Context
+
+当前验证器 (`validators/validator.py`) 已具备以下验证能力：
+- YAML 结构验证（slides 字段）
+- 元素类型和属性验证
+- 几何验证（元素位置和尺寸）
+- 资源验证（图片文件、模板文件存在性）
+
+但缺少对模板变量完整性的验证。当 YAML 使用模板时，如果用户没有提供模板所需的必需变量（如 `title`），验证器仍会返回成功，直到转换阶段才发现问题。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 在验证阶段检查用户是否提供了模板所需的必需变量
+- 当缺少必需变量时返回 ERROR 级别错误，阻止转换
+- 提供清晰的错误信息，指出缺少哪个必需变量
+
+**Non-Goals:**
+- 不验证模板变量值的类型正确性（由渲染阶段处理）
+- 不验证模板变量值的业务逻辑有效性
+- 不修改现有的验证错误格式
+
+## Decisions
+
+### 方案：在 ResourceValidator 中添加 validate_template_vars 方法
+
+**选择理由：**
+1. ResourceValidator 已负责模板相关的验证（validate_template），职责匹配
+2. 可以复用现有的模板加载逻辑
+3. 对主验证器的影响最小，只需在现有验证流程中调用新方法
+
+**替代方案考虑：**
+- 在主验证器中直接实现：会导致主验证器代码膨胀
+- 新增专门的 TemplateVarValidator：增加复杂度，与现有架构不符
+
+### 实现要点：
+1. 在 ResourceValidator 中添加 `validate_template_vars` 方法
+2. 加载模板文件后，检查模板的 `vars` 字段中的 `required: true` 变量
+3. 从幻灯片数据中获取 `vars` 字段，与模板要求的必需变量对比
+4. 缺少必需变量时，添加 ERROR 级别问题
+
+## Risks / Trade-offs
+
+**潜在风险：**
+- [风险] 重复加载模板文件 → [缓解] ResourceValidator 已在 validate_template 中加载一次，可复用加载结果或缓存
+- [风险] vars 字段嵌套层级复杂 → [缓解] 仅检查顶层 vars 字段，不处理嵌套引用

openspec/changes/archive/2026-03-03-add-template-variable-validation/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+当前验证器（`yaml2pptx.py check` 命令）只验证 YAML 语法和元素有效性，但不验证模板变量的完整性。用户在使用模板时如果缺少必需变量（如 title），验证器仍然返回成功，导致用户在转换阶段才发现问题。需要在验证阶段提前发现这类问题，提升用户体验。
+
+## What Changes
+
+在 `validators/validator.py` 的验证流程中添加模板变量验证功能：
+1. 检测 YAML 是否使用模板（检查 `slides[].template` 字段）
+2. 加载模板定义（读取模板 YAML 文件）
+3. 检查模板中的必需变量是否在 `vars` 中提供
+4. 如缺少必需变量，添加验证错误
+
+## Capabilities
+
+### New Capabilities
+- `template-variable-validation`: 验证器在检查阶段验证模板必需变量是否提供
+
+### Modified Capabilities
+- `yaml-validation`: 需要扩展验证范围，加入模板变量完整性检查（新增需求，不是修改现有需求）
+
+## Impact
+
+- 主要影响：`validators/validator.py` 的验证逻辑
+- 次要影响：可能需要调整验证错误信息的格式
+- 无 API 变更，仅内部验证逻辑增强

openspec/changes/archive/2026-03-03-add-template-variable-validation/specs/template-variable-validation/spec.md

@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: 验证器必须检查模板必需变量
+
+当 YAML 使用模板时，系统 SHALL 验证用户是否提供了模板所需的必需变量。
+
+#### Scenario: 提供所有必需变量
+
+- **WHEN** 模板定义了 `vars: [{name: title, required: true}]`，且用户 YAML 提供了 `vars: {title: "Hello"}`
+- **THEN** 验证通过，不报错
+
+#### Scenario: 缺少必需变量
+
+- **WHEN** 模板定义了 `vars: [{name: title, required: true}]`，但用户 YAML 的 `vars` 中没有提供 `title`
+- **THEN** 验证器报告 ERROR 级别错误："缺少模板必需变量: title"
+
+#### Scenario: 多个必需变量部分缺失
+
+- **WHEN** 模板定义了 `vars: [{name: title, required: true}, {name: subtitle, required: true}]`，但用户只提供了 `vars: {title: "Hello"}`
+- **THEN** 验证器报告 ERROR 级别错误，包含所有缺少的必需变量
+
+#### Scenario: 可选变量缺失
+
+- **WHEN** 模板定义了 `vars: [{name: subtitle, required: false}]`，用户没有提供该变量
+- **THEN** 验证通过，不报错
+
+#### Scenario: 提供默认值时缺少可选变量
+
+- **WHEN** 模板定义了 `vars: [{name: subtitle, required: false, default: ""}]`，用户没有提供该变量
+- **THEN** 验证通过，不报错（使用默认值）
+
+### Requirement: 验证器必须支持多幻灯片模板变量检查
+
+系统 SHALL 检查每个使用模板的幻灯片，确保其提供了模板所需的必需变量。
+
+#### Scenario: 不同幻灯片使用不同模板
+
+- **WHEN** 幻灯片 1 使用模板 A（需要变量 title），幻灯片 2 使用模板 B（需要变量 image）
+- **THEN** 验证器分别检查每个幻灯片的变量，提供独立的错误信息
+
+#### Scenario: 多个幻灯片使用同一模板
+
+- **WHEN** 幻灯片 1 和幻灯片 2 都使用同一模板，都缺少必需变量
+- **THEN** 验证器报告两个错误，分别对应各自的幻灯片位置
+
+### Requirement: 验证器必须提供清晰的错误位置信息
+
+当缺少必需变量时，验证器 SHALL 在错误信息中包含幻灯片位置。
+
+#### Scenario: 错误信息包含幻灯片位置
+
+- **WHEN** 幻灯片 2 使用模板但缺少必需变量
+- **THEN** 错误信息包含位置："幻灯片 2: 缺少模板必需变量: title"

openspec/changes/archive/2026-03-03-add-template-variable-validation/tasks.md

@@ -0,0 +1,19 @@
+## 1. 扩展 ResourceValidator
+
+- [x] 1.1 在 ResourceValidator 中添加 `validate_template_vars` 方法
+- [x] 1.2 实现加载模板 vars 定义逻辑
+- [x] 1.3 实现检查用户提供的 vars 是否满足模板必需变量逻辑
+- [x] 1.4 返回缺少必需变量的验证错误
+
+## 2. 集成到主验证器
+
+- [x] 2.1 在 Validator.validate() 中调用 validate_template_vars 方法
+- [x] 2.2 确保在模板文件验证通过后再进行变量验证
+
+## 3. 测试
+
+- [x] 3.1 编写单元测试：提供所有必需变量时验证通过
+- [x] 3.2 编写单元测试：缺少必需变量时验证失败并返回错误
+- [x] 3.3 编写单元测试：多个必需变量部分缺失时报告所有缺失变量
+- [x] 3.4 编写单元测试：可选变量缺失时验证通过
+- [x] 3.5 编写集成测试：运行 yaml2pptx.py check 命令验证功能

openspec/specs/template-variable-validation/spec.md

@@ -0,0 +1,59 @@
+# Template Variable Validation
+
+## Purpose
+
+验证器在检查阶段验证模板必需变量是否提供。当 YAML 使用模板时，系统验证用户是否提供了模板所需的必需变量，避免在转换阶段才发现问题。
+
+## Requirements
+
+### Requirement: 验证器必须检查模板必需变量
+
+当 YAML 使用模板时，系统 SHALL 验证用户是否提供了模板所需的必需变量。
+
+#### Scenario: 提供所有必需变量
+
+- **WHEN** 模板定义了 `vars: [{name: title, required: true}]`，且用户 YAML 提供了 `vars: {title: "Hello"}`
+- **THEN** 验证通过，不报错
+
+#### Scenario: 缺少必需变量
+
+- **WHEN** 模板定义了 `vars: [{name: title, required: true}]`，但用户 YAML 的 `vars` 中没有提供 `title`
+- **THEN** 验证器报告 ERROR 级别错误："缺少模板必需变量: title"
+
+#### Scenario: 多个必需变量部分缺失
+
+- **WHEN** 模板定义了 `vars: [{name: title, required: true}, {name: subtitle, required: true}]`，但用户只提供了 `vars: {title: "Hello"}`
+- **THEN** 验证器报告 ERROR 级别错误，包含所有缺少的必需变量
+
+#### Scenario: 可选变量缺失
+
+- **WHEN** 模板定义了 `vars: [{name: subtitle, required: false}]`，用户没有提供该变量
+- **THEN** 验证通过，不报错
+
+#### Scenario: 提供默认值时缺少可选变量
+
+- **WHEN** 模板定义了 `vars: [{name: subtitle, required: false, default: ""}]`，用户没有提供该变量
+- **THEN** 验证通过，不报错（使用默认值）
+
+### Requirement: 验证器必须支持多幻灯片模板变量检查
+
+系统 SHALL 检查每个使用模板的幻灯片，确保其提供了模板所需的必需变量。
+
+#### Scenario: 不同幻灯片使用不同模板
+
+- **WHEN** 幻灯片 1 使用模板 A（需要变量 title），幻灯片 2 使用模板 B（需要变量 image）
+- **THEN** 验证器分别检查每个幻灯片的变量，提供独立的错误信息
+
+#### Scenario: 多个幻灯片使用同一模板
+
+- **WHEN** 幻灯片 1 和幻灯片 2 都使用同一模板，都缺少必需变量
+- **THEN** 验证器报告两个错误，分别对应各自的幻灯片位置
+
+### Requirement: 验证器必须提供清晰的错误位置信息
+
+当缺少必需变量时，验证器 SHALL 在错误信息中包含幻灯片位置。
+
+#### Scenario: 错误信息包含幻灯片位置
+
+- **WHEN** 幻灯片 2 使用模板但缺少必需变量
+- **THEN** 错误信息包含位置："幻灯片 2: 缺少模板必需变量: title"