ai-robot-core/spec/metadata-role-separation/requirements.md

---
feature_id: "MRS"
title: "元数据职责分层优化"
status: "draft"
version: "0.1.0"
active_version: "0.1.0"
version_history:
  - version: "0.1.0"
    ac_range: "AC-MRS-01~16"
    description: "元数据字段职责分层、槽位模型独立化、工具协同改造与管理端配置能力"
owners:
  - "product"
  - "backend"
  - "frontend"
last_updated: "2026-03-05"
source:
  type: "conversation"
  ref: "元数据职责过载问题优化需求"
---

# 元数据职责分层优化（MRS）

## 1. 背景与目标

### 1.1 背景

当前系统中元数据字段承担了多种隐式职责，导致以下问题：

1. **职责混淆**：同一字段（如 `grade`）同时用于资源过滤、运行时槽位、提示词变量和路由信号，但系统无法区分其具体用途
2. **工具耦合**：`kb_search_dynamic`、`memory_recall`、`intent_hint`、`high_risk_check` 等工具全量消费元数据字段，无法按需筛选
3. **槽位语义模糊**：槽位与元数据字段概念混淆，缺少独立的槽位定义模型
4. **配置不可视**：管理端无法按职责视角查看和配置字段

### 1.2 目标

- 为元数据字段引入显式的 `field_roles` 职责分层
- 建立独立的槽位定义模型，与元数据字段解耦但可复用
- 改造工具链按职责角色消费字段，实现精准消费
- 提供管理端按角色配置和查看的能力

### 1.3 非目标（Out of Scope）

- 不处理历史数据迁移，允许删除重建配置
- 不新增元数据字段类型（保持 string/number/boolean/enum/array_enum）
- 不替换向量引擎或 LLM 供应商
- 不覆盖渠道端具体实现

## 2. 模块边界（Scope）

- 覆盖：元数据字段职责分层、槽位定义模型、工具协同改造、管理端配置能力
- 不覆盖：历史数据迁移、向量引擎替换、模型切换、渠道端实现

## 3. 依赖盘点（Dependencies）

- `metadata-governance` 模块：元数据字段定义基础能力
- `intent-driven-mid-platform` 模块：中台运行时工具链
- `ai-service-admin` 前端：管理端配置界面

## 4. 用户故事（User Stories）

- [US-MRS-01] 作为系统架构师，我希望元数据字段有明确的职责角色标记，以便工具能按需消费。
- [US-MRS-02] 作为后端开发者，我希望通过接口按角色查询字段定义，以便精准获取所需字段。
- [US-MRS-03] 作为运营配置人员，我希望在管理端按角色过滤查看字段，以便快速定位配置。
- [US-MRS-04] 作为对话系统开发者，我希望槽位有独立的定义模型，以便管理运行时槽位语义。
- [US-MRS-05] 作为工具开发者，我希望 `kb_search_dynamic` 只消费资源过滤角色字段，以便避免无关字段干扰。
- [US-MRS-06] 作为工具开发者，我希望 `memory_recall` 只消费槽位角色字段，以便精准管理对话槽位。
- [US-MRS-07] 作为工具开发者，我希望 `intent_hint/high_risk_check` 只消费路由信号角色字段，以便精准路由决策。
- [US-MRS-08] 作为提示词工程师，我希望 prompt 渲染只消费提示词变量角色字段，以便控制注入范围。

## 5. 验收标准（Acceptance Criteria, EARS）

### 5.1 字段职责分层

- [AC-MRS-01] WHEN 管理员创建或编辑元数据字段 THEN 系统 SHALL 支持 `field_roles` 多选配置，可选值为 `resource_filter`、`slot`、`prompt_var`、`routing_signal`。
- [AC-MRS-02] WHEN 保存字段定义时 `field_roles` 为空 THEN 系统 SHALL 允许保存（默认无职责）。
- [AC-MRS-03] WHEN 字段定义包含多个 `field_roles` THEN 系统 SHALL 正确存储并返回所有角色。

### 5.2 分层视图能力

- [AC-MRS-04] WHEN 调用 `GET /admin/metadata-schemas/by-role?role=resource_filter` THEN 系统 SHALL 返回所有 `field_roles` 包含 `resource_filter` 的活跃字段定义。
- [AC-MRS-05] WHEN 调用按角色查询接口且角色参数无效 THEN 系统 SHALL 返回 400 错误并提示有效角色列表。
- [AC-MRS-06] WHEN 管理端请求字段列表 THEN 系统 SHALL 支持按 `field_roles` 过滤展示。

### 5.3 槽位模型

- [AC-MRS-07] WHEN 管理员创建槽位定义 THEN 系统 SHALL 支持 `slot_key`、`type`、`required`、`extract_strategy`、`validation_rule`、`ask_back_prompt` 属性配置。
- [AC-MRS-08] WHEN 槽位定义的 `slot_key` 与已有元数据字段 `field_key` 相同 THEN 系统 SHALL 允许创建并建立关联关系。
- [AC-MRS-09] WHEN 运行时读取槽位值 THEN 系统 SHALL 返回 `source`（来源）、`confidence`（置信度）、`updated_at`（更新时间）属性。
- [AC-MRS-10] WHEN 调用 `GET /mid/slots/by-role?role=slot` THEN 系统 SHALL 返回所有 `field_roles` 包含 `slot` 的字段定义及关联的槽位定义。

### 5.4 工具协同改造

- [AC-MRS-11] WHEN `kb_search_dynamic` 构建过滤器 THEN 系统 SHALL 仅使用 `field_roles` 包含 `resource_filter` 的字段。
- [AC-MRS-12] WHEN `memory_recall` 召回槽位 THEN 系统 SHALL 仅使用 `field_roles` 包含 `slot` 的字段。
- [AC-MRS-13] WHEN `intent_hint` 或 `high_risk_check` 进行路由判断 THEN 系统 SHALL 仅使用 `field_roles` 包含 `routing_signal` 的字段。
- [AC-MRS-14] WHEN 模板引擎渲染 prompt THEN 系统 SHALL 仅使用 `field_roles` 包含 `prompt_var` 的字段。

### 5.5 管理端可配置能力

- [AC-MRS-15] WHEN 管理员在元数据字段编辑界面 THEN 系统 SHALL 显示 `field_roles` 多选配置组件。
- [AC-MRS-16] WHEN 管理员删除字段或槽位定义 THEN 系统 SHALL 允许删除且无需考虑历史数据兼容性。

## 6. 追踪映射（Traceability）

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-MRS-01 | /admin/metadata-schemas | POST | createMetadataSchema | field_roles 配置 |
| AC-MRS-01 | /admin/metadata-schemas/{id} | PUT | updateMetadataSchema | field_roles 配置 |
| AC-MRS-02 | /admin/metadata-schemas | POST | createMetadataSchema | 空角色允许 |
| AC-MRS-03 | /admin/metadata-schemas | POST | createMetadataSchema | 多角色存储 |
| AC-MRS-04 | /admin/metadata-schemas/by-role | GET | getMetadataSchemasByRole | 按角色查询 |
| AC-MRS-05 | /admin/metadata-schemas/by-role | GET | getMetadataSchemasByRole | 无效角色校验 |
| AC-MRS-06 | /admin/metadata-schemas | GET | listMetadataSchemas | 按角色过滤 |
| AC-MRS-07 | /admin/slot-definitions | POST | createSlotDefinition | 槽位定义创建 |
| AC-MRS-08 | /admin/slot-definitions | POST | createSlotDefinition | 关联元数据字段 |
| AC-MRS-09 | /mid/slots/{slot_key} | GET | getSlotValue | 运行时槽位值 |
| AC-MRS-10 | /mid/slots/by-role | GET | getSlotsByRole | 按角色获取槽位 |
| AC-MRS-11 | 内部调用 | - | kb_search_dynamic | resource_filter 消费 |
| AC-MRS-12 | 内部调用 | - | memory_recall | slot 消费 |
| AC-MRS-13 | 内部调用 | - | intent_hint/high_risk_check | routing_signal 消费 |
| AC-MRS-14 | 内部调用 | - | template_engine | prompt_var 消费 |
| AC-MRS-15 | 前端页面 | - | - | field_roles 配置组件 |
| AC-MRS-16 | /admin/metadata-schemas/{id} | DELETE | deleteMetadataSchema | 删除无需兼容 |
| AC-MRS-16 | /admin/slot-definitions/{id} | DELETE | deleteSlotDefinition | 删除无需兼容 |

## 7. 字段角色定义

| 角色标识 | 中文名称 | 用途说明 | 消费工具 |
|---------|---------|---------|---------|
| `resource_filter` | 资源过滤 | 用于 KB 文档检索时的元数据过滤 | `kb_search_dynamic` |
| `slot` | 运行时槽位 | 对话流程中的结构化槽位，用于信息收集 | `memory_recall` |
| `prompt_var` | 提示词变量 | 注入到 LLM Prompt 中的变量 | `template_engine` |
| `routing_signal` | 路由信号 | 用于意图路由和风险判断的信号 | `intent_hint`, `high_risk_check` |

## 8. 槽位定义属性

| 属性 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| `slot_key` | string | 是 | 槽位键名，可与 field_key 关联 |
| `type` | enum | 是 | 槽位类型：string/number/boolean/enum/array_enum |
| `required` | boolean | 是 | 是否必填槽位 |
| `extract_strategy` | enum | 否 | 提取策略：rule/llm/user_input |
| `validation_rule` | string | 否 | 校验规则（正则或 JSON Schema） |
| `ask_back_prompt` | string | 否 | 追问提示语模板 |
| `default_value` | any | 否 | 默认值 |
| `linked_field_id` | uuid | 否 | 关联的元数据字段 ID |

## 9. 运行时槽位值属性

| 属性 | 类型 | 说明 |
|-----|------|------|
| `key` | string | 槽位键名 |
| `value` | any | 槽位值 |
| `source` | enum | 来源：user_confirmed/rule_extracted/llm_inferred/default |
| `confidence` | float | 置信度 0.0~1.0 |
| `updated_at` | datetime | 最后更新时间 |