DEMO-AGENT/docs/详细设计/skill/模板字段映射加载Skill.md

模板字段映射加载Skill 设计

1. Skill 定位

模板字段映射加载Skill 负责加载 Word 模板占位符与统一字段池字段之间的映射关系。

英文实现标识建议使用 TemplateFieldMappingLoadSkill。

2. 输入

@dataclass
class TemplateFieldMappingLoadInput:
    template_id: str
    template_file_path: Path

3. 输出

@dataclass
class TemplateFieldMappingLoadOutput:
    template_id: str
    mapping_version: str
    mappings: list[dict]
    missing_placeholders: list[str]
    extra_placeholders: list[str]

4. 核心方法

4.1 run(input) -> TemplateFieldMappingLoadOutput

主入口方法。

4.2 load_mapping(template_id) -> dict

读取映射规则。

4.3 scan_placeholders(template_file) -> list[str]

扫描模板占位符。

4.4 validate_mapping(mapping, placeholders) -> MappingValidationResult

校验映射完整性。

5. 技术实现

使用技术：

1. YAML
2. python-docx
3. Pydantic

6. 异常处理

1. 映射不存在：任务失败。
2. 必填占位符缺失：任务失败。
3. 模板存在未映射占位符：标记警告。

7. 测试要点

1. 映射加载成功。
2. 模板占位符能扫描。
3. 缺失必填映射时报错。