ai-robot-core/spec/metadata-governance/design.md

metadata-governance 技术设计（Design）

1. 设计目标

围绕已上线的元数据配置页面，补齐“配置 -> 录入 -> 检索 -> 治理”的闭环：

• 元数据字段生命周期治理（draft/active/deprecated）
• KB/Intent/Flow/Prompt 录入联动与一致性校验
• Intent 路由后 metadata 过滤注入
• 拆解模板版本治理与回溯

2. 架构与职责

2.1 元数据配置层（Admin）

• 提供字段定义管理：field_key/type/options/required/scope/status
• 提供字段状态治理：
  • draft: 可编辑不可生效
  • active: 可用于新建与编辑
  • deprecated: 不可用于新建，历史可读

2.2 录入联动层（Admin Forms）

• 在以下录入页统一挂载 metadata 表单组件：
  • KB 文档
  • Intent Rule
  • Script Flow
  • Prompt Template
• 联动逻辑：对象类型变化时，根据 scope 动态渲染字段
• 校验逻辑：required 字段 + 类型校验 + enum 值校验

2.3 检索治理层（Runtime）

• 路由流程：Intent 命中 -> 目标知识库集合 -> metadata filters -> 向量召回
• metadata 注入来源：会话上下文、已提取槽位（grade/subject/scene）
• 兜底策略：无召回时 fallback（指定库或固定话术）并输出原因码

2.4 模板治理层（Ops）

• 拆解模板持久化与版本管理
• 提供最新生效版本查询能力

3. 数据模型建议

3.1 MetadataSchema

• id
• field_key
• label
• type
• required
• options
• default_value
• scope
• is_filterable
• is_rank_feature
• status
• version
• created_at/updated_at

3.2 MetadataPayload（挂载到业务对象）

• object_type
• object_id
• metadata: key-value
• schema_version

3.3 DecompositionTemplate

• id
• name
• template_content
• version
• status
• created_at/updated_at

4. 关键流程

4.1 配置到生效流程

1. 管理员创建/编辑字段（draft）
2. 审核后切换 active
3. 录入页拉取 active 字段并动态渲染
4. 字段 deprecated 后，新建不可选，历史只读可见

4.2 运行时检索流程

1. Intent Rule 命中 response_type=rag
2. 选择目标知识库（支持多库）
3. 注入 metadata 过滤条件
4. 执行向量检索
5. 无召回走 fallback，并记录原因码

5. 错误与降级策略

• 配置异常：字段配置缺失/冲突 -> 使用系统默认字段集
• 过滤异常：metadata 过滤构造失败 -> 降级为不加过滤检索（记录 warning）
• 无召回：返回 fallback 并记录 no_recall_after_metadata_filter

6. 可观测性

• 关键日志字段：
  • intent_id
  • target_kbs
  • applied_metadata_filters
  • fallback_reason_code
  • latency_ms

7. 与 AC 对齐

• 字段状态治理：AC-IDSMETA-13~14
• 跨模块录入联动：AC-IDSMETA-15~17
• 路由与检索治理：AC-IDSMETA-18~20
• 模板治理：AC-IDSMETA-21~22