DEMO-AGENT/docs/详细设计/skill/统一字段池写入Skill.md

统一字段池写入Skill 设计

1. Skill 定位

统一字段池写入Skill 负责将标准化后的字段候选写入统一字段池，并为每个字段选择推荐值、保留候选值和来源证据。

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

2. 输入

@dataclass
class UnifiedFieldPoolWriteInput:
    batch_id: int
    normalized_candidates: list[NormalizedFieldCandidate]
    field_definitions: list[FieldDefinition]
    source_priority: dict

3. 输出

@dataclass
class UnifiedFieldPoolWriteOutput:
    field_pool_items: list[FieldPoolItem]
    candidate_records: list[dict]
    manual_review_fields: list[dict]
    write_status: str

4. 推荐值选择规则

1. 优先选择高置信候选。
2. 同置信度时按来源优先级选择。
3. 来源优先级一致时选择规则抽取结果。
4. 多候选值明显不同则标记 conflict_candidate。
5. 待人工复核字段不作为无条件回填值。

5. 核心方法

5.1 run(input) -> UnifiedFieldPoolWriteOutput

主入口方法。

5.2 group_candidates_by_field(candidates) -> dict

按 field_key 分组。

5.3 select_recommended_value(field_key, candidates, priority) -> FieldPoolItem

选择推荐值。

5.4 persist_field_pool_item(item) -> RegistrationFieldPoolItem

写入字段池。

5.5 persist_field_candidates(item, candidates) -> None

保留所有候选值。

6. 技术实现

使用技术：

1. Django ORM
2. JSONField
3. 批量写入
4. 唯一约束：batch + field_key

7. 异常处理

1. 没有候选值：写入空字段并标记待复核。
2. 数据库写入失败：任务失败并写审计。
3. 字段重复写入：更新字段池版本或覆盖当前批次结果。
4. 候选冲突：保留候选并标记冲突候选。

8. 测试要点

1. 高置信候选被选为推荐值。
2. 来源优先级生效。
3. 冲突候选被保留。
4. 可回填字段标记正确。