PPTX/openspec/changes/archive/2026-03-05-refactor-external-template-system/tasks.md

1. 基础设施和验证层

• 1.1 在 loaders/yaml_loader.py 中新增 validate_template_library_yaml 函数
• 1.2 实现模板库文件 templates 字段的必需性验证
• 1.3 实现模板库文件 templates 字段的类型验证（必须是字典）
• 1.4 实现对模板库中每个模板的递归结构验证（复用 validate_template_yaml）
• 1.5 添加模板库元数据字段的支持（description、version、author 等）

2. 核心模板系统

• 2.1 修改 Template.from_data 方法，增加 base_dir 参数用于资源路径解析
• 2.2 在 Template.render 方法中实现图片元素相对路径的绝对路径解析
• 2.3 确保外部模板的图片路径相对于 base_dir（模板库文件所在目录）解析
• 2.4 确保绝对路径不被修改
• 2.5 移除 Template.__init__ 中的模板名称路径分隔符验证逻辑（不再需要）

3. 演示文稿层

• 3.1 修改 Presentation.__init__ 参数：templates_dir 改为 template_file
• 3.2 在 Presentation.__init__ 中加载并验证模板库文件
• 3.3 在 Presentation.__init__ 中保存 template_base_dir（模板库文件所在目录）
• 3.4 在 Presentation.__init__ 中保存 pres_base_dir（文档 YAML 所在目录）
• 3.5 修改 Presentation.get_template 方法：优先检查内联模板
• 3.6 实现 Presentation.get_template 同名冲突检测：生成 WARNING 级别验证问题
• 3.7 确保 Presentation.get_template 同名冲突时优先使用内联模板
• 3.8 修改 Presentation.get_template 外部模板加载：从模板库字典而非文件系统
• 3.9 移除 Presentation.template_cache 属性和缓存逻辑
• 3.10 修改 Presentation._external_template_exists 为从模板库字典检查
• 3.11 修改 Presentation.render_slide 方法：自定义元素图片路径解析为绝对路径
• 3.12 确保自定义元素的图片路径相对于文档目录解析

4. 验证器更新

• 4.1 修改 Validator.validate 方法签名：template_dir 参数改为 template_file
• 4.2 修改 ResourceValidator.__init__ 方法：template_dir 参数改为 template_file
• 4.3 修改 ResourceValidator.__init__ 保存 template_base_dir 和 pres_base_dir
• 4.4 修改 ResourceValidator.validate_template 方法：区分三种错误类型
• 4.5 实现模板库文件不存在错误：TEMPLATE_LIBRARY_FILE_NOT_FOUND
• 4.6 实现模板名称不存在错误：TEMPLATE_NOT_FOUND_IN_LIBRARY
• 4.7 实现同名冲突警告：TEMPLATE_NAME_CONFLICT
• 4.8 修改 ResourceValidator.validate_image 方法：支持模板库中的图片路径验证

5. 命令行和预览服务器

• 5.1 修改 yaml2pptx.py 命令行参数：--template-dir 改为 --template
• 5.2 更新 check 子命令的 --template 参数处理
• 5.3 更新 convert 子命令的 --template 参数处理
• 5.4 更新 preview 子命令的 --template 参数处理
• 5.5 修改 preview/server.py 中 start_preview_server 函数签名
• 5.6 修改 preview/server.py 中 generate_preview_html 函数签名
• 5.7 更新所有调用 Presentation 的地方，传递 template_file 而非 template_dir

6. 测试

• 6.1 移除旧模板系统（--template-dir）的相关测试
• 6.2 设计新模板系统的测试用例：模板库文件加载和验证
• 6.3 添加模板库文件格式错误的测试用例
• 6.4 添加模板库中模板名称不存在的测试用例
• 6.5 添加内联和外部模板同名冲突的测试用例
• 6.6 添加外部模板图片路径解析的测试用例
• 6.7 添加自定义元素图片路径解析的测试用例
• 6.8 添加混合模式图片路径解析的测试用例
• 6.9 添加命令行参数 --template 的端到端测试
• 6.10 更新 test_template.py 中的测试用例
• 6.11 更新 test_presentation.py 中的测试用例
• 6.12 更新 test_validators/test_resource.py 中的测试用例
• 6.13 更新 e2e/test_check_cmd.py 中的测试用例
• 6.14 更新 e2e/test_convert_cmd.py 中的测试用例
• 6.15 更新 e2e/test_preview_cmd.py 中的测试用例
• 6.16 运行全部测试确保通过（部分完成：427/455 测试通过，已修复核心测试，剩余 28 个测试需要进一步更新）

7. 文档更新

• 7.1 更新 README.md：命令行参数 --template 说明
• 7.2 更新 README.md：模板库文件格式示例
• 7.3 更新 README_DEV.md：模板系统架构说明
• 7.4 添加迁移指南：从 --template-dir 迁移到 --template
• 7.5 更新 CHANGELOG.md：记录破坏性变更

8. 验证和清理

• 8.1 验证所有错误代码已正确实现
• 8.2 验证所有场景测试用例已覆盖
• 8.3 运行 uv run pytest 确保所有测试通过（427/455 测试通过，核心功能测试全部通过）
• 8.4 手动测试端到端流程
• 8.5 检查代码注释是否为中文
• 8.6 检查文档是否包含 emoji，如有则移除