lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
3.5 KiB
3.5 KiB
Loaders 模块
loaders/yaml_loader.py 负责 YAML 文件加载和验证。
职责
- YAML 文件加载
- 演示文稿结构验证
- 内联模板验证
- 外部模板验证
包含的内容
YAMLError
自定义异常类：
class YAMLError(Exception):
"""YAML 相关错误"""
pass
load_yaml_file()
加载 YAML 文件：
def load_yaml_file(file_path):
"""加载 YAML 文件并返回解析后的数据"""
try:
with open(file_path, 'r', encoding='utf-8') as f:
data = yaml.safe_load(f)
return data
except yaml.YAMLError as e:
raise YAMLError(f"YAML 语法错误: {e}")
except FileNotFoundError:
raise YAMLError(f"文件不存在: {file_path}")
validate_presentation_yaml()
验证演示文稿结构：
def validate_presentation_yaml(data, file_path):
"""验证演示文稿 YAML 结构"""
# 检查必需字段
if 'metadata' not in data:
raise YAMLError(f"缺少 metadata 字段: {file_path}")
if 'slides' not in data:
raise YAMLError(f"缺少 slides 字段: {file_path}")
# 验证 metadata
metadata = data['metadata']
if 'size' not in metadata:
raise YAMLError(f"metadata 缺少 size 字段: {file_path}")
if metadata['size'] not in ['16:9', '4:3']:
raise YAMLError(f"无效的 size 值: {metadata['size']}")
# 验证内联模板（如果有）
if 'templates' in data:
validate_templates_yaml(data['templates'])
# 验证幻灯片
for slide in data['slides']:
# 验证 enabled 字段
if 'enabled' in slide:
if not isinstance(slide['enabled'], bool):
raise YAMLError(f"enabled 必须是布尔值: {file_path}")
validate_template_yaml()
验证外部模板结构：
def validate_template_yaml(template_data, template_name):
"""验证外部模板结构"""
if 'elements' not in template_data:
raise YAMLError(f"模板缺少 elements 字段: {template_name}")
if 'vars' in template_data:
for var in template_data['vars']:
if 'name' not in var:
raise YAMLError(f"变量缺少 name 字段: {template_name}")
validate_templates_yaml()
验证内联模板结构：
def validate_templates_yaml(templates):
"""验证内联模板结构"""
if not isinstance(templates, dict):
raise YAMLError("templates 必须是字典类型")
for name, template_data in templates.items():
validate_template_yaml(template_data, f"templates.{name}")
# 检测默认值中引用不存在的变量
vars_def = {v['name']: v for v in template_data.get('vars', [])}
for var in template_data.get('vars', []):
if 'default' in var:
# 检查默认值是否引用了不存在的变量
# 实现省略...
内联模板验证
内联模板验证包括：
- 结构验证（是否为字典）
- 元素验证（是否有 elements 字段）
- 变量定义验证（是否有 name 字段）
- 默认值验证（检测循环引用）
enabled 字段验证
验证 enabled 字段必须是布尔值：
if 'enabled' in slide:
if not isinstance(slide['enabled'], bool):
raise YAMLError(f"enabled 必须是布尔值，不能是字符串或条件表达式")