DEMO-AGENT/docs/详细设计/skill/字段Schema加载Skill.md

字段Schema加载Skill 设计

1. Skill 定位

字段Schema加载Skill 负责加载注册申报字段 schema，提供字段定义、来源优先级、抽取方式、回填属性和一致性要求。

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

2. 输入

@dataclass
class FieldSchemaLoadInput:
    field_schema_id: str
    target_field_keys: list[str] = field(default_factory=list)

3. 输出

@dataclass
class FieldSchemaLoadOutput:
    field_schema_id: str
    version: str
    fields: list[FieldDefinition]
    source_priority: dict
    validation_warnings: list[dict]

4. 核心方法

4.1 run(input) -> FieldSchemaLoadOutput

主入口方法。

4.2 load_schema_file(field_schema_id) -> dict

从 YAML 读取字段 schema。

4.3 validate_field_schema(raw_schema) -> FieldSchemaValidationResult

校验字段定义。

4.4 select_target_fields(schema, target_field_keys) -> list[FieldDefinition]

筛选目标字段。

5. 技术实现

使用技术：

1. PyYAML
2. Pydantic
3. Django cache

建议路径：

configs/registration/fields/ivd_registration_fields_v1.yaml

6. 异常处理

1. schema 文件不存在：任务失败。
2. 字段定义缺少 field_key：校验失败。
3. 目标字段不存在：返回业务错误。
4. 来源优先级缺失：允许执行，但记录警告。

7. 测试要点

1. schema 加载成功。
2. 目标字段筛选正确。
3. 缺少必填字段时报错。
4. 来源优先级输出正确。