## Why 当前外部模板系统使用文件夹+文件名的方式存储和查询模板,与内联模板的字典查询方式不一致。这种不一致导致以下问题: 1. 模板名称受文件命名规则限制(不能包含路径分隔符) 2. 查询逻辑不统一(外部模板通过文件系统查找,内联模板通过字典键查找) 3. 外部模板分散在多个文件中,难以管理和分发 重构为统一的模板库格式后,外部模板和内联模板将使用相同的数据结构和查询逻辑,提高系统一致性。 ## What Changes - **BREAKING**: 命令行参数 `--template-dir` 改为 `--template`,指定单个 YAML 文件而非文件夹 - **BREAKING**: 外部模板文件格式从单个模板的 YAML 改为包含多个模板的模板库 YAML - 移除外部模板的缓存机制 (`template_cache`) - 统一资源路径解析:所有图片元素的相对路径在渲染前都解析为绝对路径 - 自定义元素和内联模板元素:相对于文档 YAML 所在目录 - 外部模板元素:相对于模板库文件所在目录 - 模板库文件支持元数据字段(description、version、author 等) - 优化错误提示:区分模板库文件不存在、模板名称不存在两种错误 - 同名冲突处理:内联和外部模板同名时发出 WARNING,优先使用内联模板 ## Capabilities ### New Capabilities - `template-library`: 模板库文件的加载、验证和管理 - 模板库文件必须包含 `templates` 字段(字典类型) - 支持元数据字段(description、version、author) - 递归验证每个模板的结构(vars、elements) - 提供模板库文件级别的错误提示 ### Modified Capabilities - `template-system`: 模板查询和引用逻辑 - 外部模板查询从文件系统查找改为从模板库字典查找 - 统一内联模板和外部模板的查询接口 - 同名冲突时返回 WARNING 级别的验证问题 ## Impact ### 受影响的代码模块 - `yaml2pptx.py`: 命令行参数修改 - `core/presentation.py`: 模板加载逻辑重构,移除 `template_cache` - `core/template.py`: `from_data` 增加 `base_dir` 参数,`render` 中解析图片路径 - `loaders/yaml_loader.py`: 新增 `validate_template_library_yaml` 函数 - `validators/resource.py`: 修改模板验证逻辑,区分三种错误类型 - `validators/validator.py`: 参数 `template_dir` 改为 `template_file` - `preview/server.py`: 参数 `template_dir` 改为 `template_file` - `tests/`: 更新相关测试用例 ### API 变更 **命令行参数**: ```bash # 旧方式 yaml2pptx.py convert input.yaml --template-dir /path/to/templates/ # 新方式 yaml2pptx.py convert input.yaml --template /path/to/templates.yaml ``` **模板库文件格式**: ```yaml # 新格式 (templates.yaml) description: "公司标准模板库" version: "1.0.0" templates: title-slide: vars: ... elements: ... content-slide: vars: ... elements: ... ``` ### 依赖变更 无新增依赖。 ### 兼容性 - 不向后兼容:现有使用 `--template-dir` 的脚本需要更新为 `--template` - 现有的单文件模板需要迁移到模板库格式