PPTX/openspec/changes/archive/2026-03-03-inline-templates/design.md

Context

当前状态:

• 项目已有完整的外部模板系统（core/template.py），包括变量替换、条件渲染等功能
• 模板系统采用文件隔离方式，模板定义在独立的 YAML 文件中
• 通过 template: <name> 引用外部模板，使用 --template-dir 指定模板目录
• 项目中没有任何实际使用模板的案例，说明外部模板的使用门槛较高

问题分析: 通过代码分析和 grep 搜索发现：

1. 整个项目中没有包含 template: 字段的 YAML 文件
2. 所有模板测试用例都是动态生成的，没有真实的用户使用场景
3. 外部模板需要额外的文件管理工作，增加了使用复杂度

项目约束:

• 面向中文开发者，使用中文编写注释和文档
• 使用 uv 运行 Python 脚本，禁止直接使用主机环境 Python
• 测试文件必须放在 temp/ 目录
• 每次功能迭代需要更新 README.md 和 README_DEV.md
• 所有需求必须设计全面、合理的测试内容

Goals / Non-Goals

Goals:

• 支持在 YAML 源文件中定义和使用内联模板
• 保持与外部模板系统的兼容性，允许混合使用
• 禁止内联和外部模板同名，要求模板名称必须唯一
• 提供完整的错误处理和验证机制
• 保持代码向后兼容，不破坏现有功能

Non-Goals:

• 不支持内联模板之间的相互引用
• 不支持内联模板引用外部模板
• 不实现模板继承或组合功能
• 不修改外部模板的现有功能

Decisions

决策 1: 使用 templates 字段定义内联模板

选择: 在 YAML 文件顶层新增 templates 字段，字典类型，键为模板名称，值为模板定义

理由:

• 保持 YAML 结构清晰，与 metadata、slides 字段同级
• 字典结构便于查找和管理
• 不与现有字段冲突，向后兼容

替代方案考虑:

• 方案 A: 在 metadata 中定义 templates - 会造成 metadata 职责混乱
• 方案 B: 使用 YAML 锚点语法 - 无法支持变量替换和条件渲染
• 方案 C: 在每个 slide 中定义内联模板 - 无法实现模板复用

决策 2: 禁止内联和外部模板同名

选择: 当同名模板同时存在于内联和外部时，直接抛出 ERROR 级别错误，不允许使用该模板

理由:

• 显式报错比隐式选择更安全，避免用户意外使用了错误的模板
• 内联和外部模板混合使用的情况较少，同名通常是错误或命名不当
• 强制用户明确模板来源，提升代码清晰度
• 降低调试难度，错误立即暴露而不是隐式选择

实现:

def get_template(self, template_name):
    # 1. 先检查内联模板
    if hasattr(self, 'inline_templates') and template_name in self.inline_templates:
        # 2. 检查外部模板是否也存在同名
        if self._external_template_exists(template_name):
            raise YAMLError(
                f"模板名称冲突: '{template_name}' 同时存在于内联模板和外部模板目录\n"
                f"请使用不同的模板名称以避免冲突"
            )
        inline_data = self.inline_templates[template_name]
        return Template.from_data(inline_data, template_name)
    
    # 3. 回退到外部模板
    if template_name not in self.template_cache:
        self.template_cache[template_name] = Template(
            template_name, self.templates_dir
        )
    return self.template_cache[template_name]

# 辅助方法：检查外部模板是否存在
def _external_template_exists(self, template_name):
    """检查外部模板文件是否存在"""
    if not self.templates_dir:
        return False
    template_path = Path(self.templates_dir) / f"{template_name}.yaml"
    return template_path.exists()

决策 3: 新增 Template.from_data() 类方法

选择: 添加类方法从字典创建模板实例，而不是修改现有的 __init__

理由:

• 保持现有 Template.__init__ 的不变性，专注于外部模板加载
• 区分内联和外部模板的创建路径，降低耦合度
• 类方法语义清晰：Template.from_data(data, name) vs Template(name, dir)

实现:

@classmethod
def from_data(cls, template_data, template_name):
    """从字典创建模板（内联模板）"""
    obj = cls.__new__(cls)
    obj.data = template_data
    obj.vars_def = {}
    for var in template_data.get('vars', []):
        obj.vars_def[var['name']] = var
    obj.elements = template_data.get('elements', [])
    return obj

决策 4: 禁止内联模板相互引用

选择: 在设计阶段明确禁止内联模板相互引用，不在实现中处理此场景

理由:

• 降低实现复杂度，避免循环引用检测逻辑
• 内联模板主要用于单文档简单场景，不需要复杂引用
• 外部模板系统已经支持跨文档复用，复杂场景应使用外部模板

错误处理:

• 如果检测到内联模板引用其他内联模板，抛出 ERROR 级别错误
• 明确在文档中说明此限制

决策 5: 完整的错误处理机制

选择: 实现四层错误处理：模板定义错误、模板引用错误、变量传递错误、循环引用错误

理由:

• 确保用户能够快速定位和修复问题
• 提前发现潜在的错误，避免在渲染时才暴露
• 符合项目现有的错误处理模式（YAMLError 异常）

错误场景:

1. 模板定义错误: templates 不是字典、缺少 elements 字段、变量定义错误
2. 模板引用错误: 引用的内联模板不存在、外部模板不存在
3. 变量传递错误: 缺少必需变量、传递未定义变量
4. 循环引用错误: 内联模板自引用（虽然禁止相互引用，但需要检测自引用）

Risks / Trade-offs

风险 1: 内存占用增加

风险: 内联模板数据保存在内存中，可能增加内存占用

缓解措施:

• 单个模板数据量通常很小（<1KB），内存增加可忽略
• 内联模板不需要缓存（已在内存中），不会重复占用
• 未来可以添加内存监控，如果问题严重再优化

风险 2: YAML 文件可读性下降

风险: 大量的内联模板定义可能使 YAML 文件过长，降低可读性

缓解措施:

• 内联模板适合简单场景，复杂场景建议使用外部模板
• 在文档中提供最佳实践建议
• IDE 的折叠功能可以帮助管理长文件

风险 3: 模板命名冲突强制检测

风险: 内联和外部模板同名时，用户可能期望使用外部模板，但系统直接报错

缓解措施:

• 明确的错误消息，指出模板冲突的具体位置（内联 templates 字段 vs 外部模板目录）
• 在文档中详细说明命名规则，建议使用不同的命名空间或前缀
• 在示例代码中展示正确的命名方式
• 提供 migration 指南，帮助用户解决命名冲突

风险 4: 循环引用误判

风险: 虽然禁止相互引用，但可能存在复杂的循环引用路径

缓解措施:

• 实现简单的循环引用检测（DFS 遍历）
• 在设计阶段就明确规则，降低实现复杂度
• 添加充分的测试用例覆盖边界情况

Open Questions

无。设计阶段已明确所有关键决策。