1
0

feat: 添加内联模板支持

支持在 YAML 源文件中直接定义模板,无需单独的模板文件。
简化单文档编写流程,降低模板系统使用门槛。

核心功能:
- 在 YAML 顶层新增 templates 字段定义内联模板
- 支持变量替换、条件渲染、默认值等完整模板功能
- 内联模板优先于外部模板查找
- 同名冲突检测:禁止内联和外部模板同名
- 相互引用检测:禁止内联模板之间相互引用
- 完整的错误处理和验证机制

代码变更:
- core/template.py: 新增 from_data() 类方法
- core/presentation.py: 支持内联模板查找和冲突检测
- loaders/yaml_loader.py: 新增 validate_templates_yaml() 验证
- validators/: 扩展验证器支持内联模板

测试:
- 新增 9 个内联模板专项测试
- 修复 1 个变量验证测试
- 所有 333 个测试通过

文档:
- README.md: 添加内联模板使用指南和最佳实践
- README_DEV.md: 说明实现细节和设计决策

完全向后兼容,不使用 templates 字段时行为不变。
This commit is contained in:
2026-03-03 15:59:55 +08:00
parent 2ba1bd7272
commit 01eacb0b97
15 changed files with 1277 additions and 25 deletions

View File

@@ -0,0 +1,41 @@
## Why
当前外部模板系统虽然功能完整,但需要单独管理模板文件,使用门槛较高。项目中没有任何实际使用的案例,说明用户体验有待改善。通过支持在 YAML 源文件中内联定义模板,可以在不需要跨文档复用的情况下,大幅简化单文档的编写流程,提升开发效率。
## What Changes
- 在 YAML 文件中新增 `templates` 字段,允许在源文件中定义模板
- 修改 `Presentation.get_template()` 方法,支持内联模板和外部模板的查找,内联模板优先
-`Template` 类中新增 `from_data()` 类方法,支持从字典创建模板实例
-`yaml_loader` 中新增 `validate_templates_yaml()` 函数,验证 templates 字段结构
- 修改现有模板验证逻辑,支持内联模板和外部模板共存
- 添加完整的错误处理机制,包括模板定义错误、引用错误、变量传递错误和循环引用检测
## Capabilities
### New Capabilities
- `inline-templates`: 支持 YAML 源文件中定义和使用内联模板,包括模板定义、变量替换、条件渲染等功能
### Modified Capabilities
无。此变更为新增功能,不修改现有功能的需求行为。
## Impact
**受影响的代码模块**:
- `core/presentation.py`: 修改 `__init__` 保存 templates 字段,修改 `get_template()` 支持内联模板查找
- `core/template.py`: 新增 `from_data()` 类方法,支持从字典创建模板
- `loaders/yaml_loader.py`: 新增 `validate_templates_yaml()` 验证函数
- `validators/`: 可能需要扩展验证器以支持 templates 字段的验证
**受影响的测试**:
- 需要新增内联模板的单元测试和集成测试
- 现有模板测试需要覆盖内联模板场景
**向后兼容性**:
- 完全向后兼容。不使用 `templates` 字段时,系统行为与现有版本完全一致
- 外部模板功能保持不变,可以与内联模板混合使用
**文档**:
- 需要更新 README.md 和 README_DEV.md说明内联模板的语法和使用方法