203 lines
9.6 KiB
Markdown
203 lines
9.6 KiB
Markdown
---
|
||
feature_id: "IDSMETA"
|
||
title: "多知识库元数据模型与拆解治理（迭代需求）"
|
||
status: "draft"
|
||
version: "0.2.0"
|
||
active_version: "0.1.0-0.2.0"
|
||
version_history:
|
||
- version: "0.2.0"
|
||
ac_range: "AC-IDSMETA-13~22"
|
||
description: "基于已上线元数据配置界面的联动增强与治理闭环"
|
||
- version: "0.1.0"
|
||
ac_range: "AC-IDSMETA-01~12"
|
||
description: "建立多知识库元数据配置与数据拆解治理能力"
|
||
owners:
|
||
- "product"
|
||
- "backend"
|
||
- "frontend"
|
||
- "ops"
|
||
last_updated: "2026-03-02"
|
||
source:
|
||
type: "doc"
|
||
ref: "docs/spec-product-zh.md + spec/contracting.md + spec/intent-driven-script/data-decomposition-methodology.md"
|
||
---
|
||
|
||
# 多知识库元数据模型与拆解治理（IDSMETA）
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 背景
|
||
当前系统已具备 Knowledge Base / Intent Rules / Script Flow / Prompt Template 的录入能力，并支持灵活话术流程。**元数据配置界面已上线**，但在跨模块复用与检索治理层仍存在缺口：
|
||
- 知识录入口径不一致，导致检索命中与召回不稳定
|
||
- 已上线 metadata 配置能力尚未在 KB/Intent/Flow/Prompt 录入链路中完全联动
|
||
- 新增业务文本时，难以稳定判断应录入 KB、Intent、现有 Flow 或新建 Flow
|
||
- 多知识库场景下缺少“意图路由 + metadata 过滤”的标准执行策略
|
||
|
||
### 1.2 目标
|
||
- 在现有 metadata 配置界面基础上，补齐字段生命周期治理（draft/active/deprecated）
|
||
- 在 KB/Intent/Flow/Prompt 管理界面统一联动 metadata 配置与校验
|
||
- 建立“数据拆解方法论”到系统配置对象的落库闭环
|
||
- 提升多知识库检索准确率与可维护性
|
||
|
||
### 1.3 非目标（Out of Scope）
|
||
- 不调整现有 LLM 供应商与模型切换机制
|
||
- 不实现全新的向量引擎或替换 Qdrant
|
||
- 不在本迭代内重构既有全部历史数据，仅提供迁移与增量治理方案
|
||
|
||
---
|
||
|
||
## 2. 模块边界（Scope）
|
||
|
||
### 覆盖
|
||
- 已上线 Metadata Schema 页面的治理增强（字段状态、弃用策略）
|
||
- Admin 录入界面的 metadata 通用组件化联动
|
||
- 多知识库路由策略配置（Intent -> KB + metadata filters）
|
||
- 数据拆解结果标准化输出模板（可由运营/AI生成）
|
||
|
||
### 不覆盖
|
||
- 具体课程内容生产
|
||
- 运营组织流程（培训/排班）
|
||
|
||
---
|
||
|
||
## 3. 依赖盘点（Dependencies）
|
||
|
||
- 依赖模块：
|
||
- Script Flow（`spec/intent-driven-script/requirements.md`）
|
||
- Knowledge Base 文档录入与向量化能力（现有 API）
|
||
- Intent Rule 路由能力（现有 API）
|
||
- 依赖文档：
|
||
- `docs/spec-product-zh.md`
|
||
- `spec/contracting.md`
|
||
- `spec/intent-driven-script/data-decomposition-methodology.md`
|
||
|
||
---
|
||
|
||
## 4. 用户故事（User Stories）
|
||
|
||
- [US-IDSMETA-01] 作为运营配置人员，我希望在后台统一配置 metadata 字段与可选值，以便不同模块复用同一套标签标准。
|
||
- [US-IDSMETA-02] 作为话术与知识库管理人员，我希望录入内容时自动显示适配字段并进行校验，以便减少脏数据。
|
||
- [US-IDSMETA-03] 作为系统路由引擎，我希望根据意图自动选择知识库并附加 metadata 过滤，以便提高召回相关性。
|
||
- [US-IDSMETA-04] 作为产品经理，我希望把“拆解方法论”沉淀为标准输出格式，以便在不同 AI 上下文中稳定复用。
|
||
|
||
---
|
||
|
||
## 5. 验收标准（Acceptance Criteria, EARS）
|
||
|
||
### 📌 当前活跃版本（v0.2.0）
|
||
|
||
#### 5.2 联动增强与治理闭环（v0.2.0）
|
||
|
||
### Phase A：已上线元数据界面的能力固化
|
||
|
||
- [AC-IDSMETA-13] WHEN 管理员在元数据配置界面创建或编辑字段 THEN 系统 SHALL 支持字段级状态管理（draft/active/deprecated）并在列表中可筛选。
|
||
- [AC-IDSMETA-14] WHEN 字段状态为 deprecated THEN 系统 SHALL 禁止其在新建对象中被选择，但历史数据仍可读取。
|
||
|
||
### Phase B：跨模块录入联动
|
||
|
||
- [AC-IDSMETA-15] WHEN 在 KB 文档录入页创建/编辑内容 THEN 系统 SHALL 根据知识库类型与 scope 自动渲染 metadata 字段并执行 required 校验。
|
||
- [AC-IDSMETA-16] WHEN 在 Intent Rule、Script Flow、Prompt Template 页面编辑配置 THEN 系统 SHALL 复用统一 metadata 组件并以一致的数据结构保存。
|
||
- [AC-IDSMETA-17] WHEN 页面切换对象类型（如 FAQ -> Product） THEN 系统 SHALL 保留兼容字段值，并对不兼容字段给出“移除/映射”的显式提示。
|
||
|
||
### Phase C：检索路由与运行时治理
|
||
|
||
- [AC-IDSMETA-18] WHEN 命中 Intent Rule 且 response_type=rag THEN 系统 SHALL 按路由策略选择目标知识库集合（支持多库）。
|
||
- [AC-IDSMETA-19] WHEN 进入 RAG 检索 THEN 系统 SHALL 注入会话上下文提取出的 metadata 过滤条件（至少包含 grade、subject、scene）。
|
||
- [AC-IDSMETA-20] WHEN 路由或过滤后无有效召回 THEN 系统 SHALL 执行兜底策略（fallback kb 或固定话术）并记录结构化原因码。
|
||
|
||
### Phase D：方法论落地
|
||
|
||
- [AC-IDSMETA-21] WHEN 运营或 AI 提交“待录入文本” THEN 系统 SHALL 按固定模板输出拆解结果（归类结论、理由、落库建议、风险冲突）。
|
||
- [AC-IDSMETA-22] WHEN 新增或更新拆解模板 THEN 系统 SHALL 保存模板版本并支持查询最近一次生效版本。
|
||
|
||
---
|
||
|
||
### 📦 历史版本（已归档）
|
||
|
||
<details>
|
||
<summary>v0.1.0：元数据配置能力建立（AC-IDSMETA-01~12）</summary>
|
||
|
||
- [AC-IDSMETA-01] 元数据配置页面支持字段定义创建（field_key、label、type、required、options、default、scope、is_filterable、is_rank_feature、status）。
|
||
- [AC-IDSMETA-02] 保存字段定义时校验 field_key 全局唯一且仅允许小写字母数字下划线。
|
||
- [AC-IDSMETA-03] enum 或 array(enum) 类型要求 options 非空且无重复。
|
||
- [AC-IDSMETA-04] required 且 scope 命中时，录入保存前执行必填校验并返回字段级错误。
|
||
- [AC-IDSMETA-05] KB 文档录入根据知识库类型展示适用 metadata 字段。
|
||
- [AC-IDSMETA-06] Intent Rule / Script Flow / Prompt Template 支持保存结构化 metadata。
|
||
- [AC-IDSMETA-07] 切换对象类型时保留可兼容字段并提示不兼容处理。
|
||
- [AC-IDSMETA-08] Intent 命中后支持按路由选择目标知识库集合。
|
||
- [AC-IDSMETA-09] RAG 检索支持注入关键 metadata 过滤条件。
|
||
- [AC-IDSMETA-10] 无召回时触发兜底并记录原因日志。
|
||
- [AC-IDSMETA-11] 支持按固定结构输出拆解结果。
|
||
- [AC-IDSMETA-12] 支持拆解模板版本保留与回溯。
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 6. 数据规范（Metadata Baseline）
|
||
|
||
### 6.1 全局建议字段（首批）
|
||
- `scene`: pain_point | transition | module_intro | faq | policy | closing
|
||
- `priority`: 1-10
|
||
- `status`: draft | active | deprecated
|
||
- `version`: 语义版本（如 v1.0.0）
|
||
- `owner`: 责任人或团队
|
||
|
||
### 6.2 业务建议字段（首批）
|
||
- `grade`: 7 | 8 | 9 | all
|
||
- `subject`: chinese | math | english | physics | chemistry | all
|
||
- `flow_step`: step1 | step2 | step3 | step4 | step5 | none
|
||
- `intent_type`: ask_grade | ask_weak_point | module_recommend | next_action | faq_answer | compliance
|
||
- `audience`: parent | student | all
|
||
|
||
---
|
||
|
||
## 7. 追踪映射（Traceability）
|
||
|
||
| AC ID | Endpoint | 方法 | operationId（建议） | 备注 |
|
||
|------|----------|------|---------------------|------|
|
||
| AC-IDSMETA-13~14 | /admin/metadata-schemas | POST/PUT/GET | createMetadataSchema/updateMetadataSchema/listMetadataSchemas | 已上线元数据页面能力固化 |
|
||
| AC-IDSMETA-15 | /admin/kb/documents | POST/PUT | createKbDocument/updateKbDocument | 文档 metadata 联动校验 |
|
||
| AC-IDSMETA-16 | /admin/intent-rules | POST/PUT | createIntentRule/updateIntentRule | 意图规则 metadata 联动 |
|
||
| AC-IDSMETA-16 | /admin/script-flows | POST/PUT | createScriptFlow/updateScriptFlow | 流程 metadata 联动 |
|
||
| AC-IDSMETA-16 | /admin/prompt-templates | POST/PUT | createPromptTemplate/updatePromptTemplate | 模板 metadata 联动 |
|
||
| AC-IDSMETA-18~20 | /chat/completions（内部路由） | POST | routeAndRetrieve | 意图路由 + metadata 检索治理 |
|
||
| AC-IDSMETA-21~22 | /admin/data-decomposition/templates | POST/PUT/GET | manageDecompositionTemplate | 拆解模板治理 |
|
||
|
||
> 注：如部分端点尚未存在，本迭代需在 `openapi.provider.yaml` 中新增并声明契约成熟度与 AC 追踪。
|
||
|
||
---
|
||
|
||
## 8. 非功能性需求（NFR）
|
||
|
||
- [NFR-IDSMETA-01] metadata 校验附加延迟 P95 < 100ms（不含向量检索）。
|
||
- [NFR-IDSMETA-02] 路由+过滤策略命中后，RAG 首包延迟不高于现网基线 +10%。
|
||
- [NFR-IDSMETA-03] 关键链路日志完整（路由决策、过滤条件、fallback 原因）。
|
||
- [NFR-IDSMETA-04] 旧数据兼容：无 metadata 的历史记录仍可读取，按默认策略执行。
|
||
|
||
---
|
||
|
||
## 9. 版本化迭代说明
|
||
|
||
- 当前版本：`v0.2.0`（在已上线 metadata 配置界面基础上的联动增强迭代）
|
||
- 后续新增能力按 `docs/spec-product-zh.md` 第 4 节执行：
|
||
- 新 AC 编号连续递增
|
||
- 活跃版本最多保留 2 个展开
|
||
- 历史版本折叠归档
|
||
|
||
---
|
||
|
||
## 10. 发布与验收建议
|
||
|
||
### 10.1 里程碑
|
||
- M1：已上线 metadata 界面能力固化（状态管理/弃用策略）
|
||
- M2：KB/Intent/Flow/Prompt 四处统一接入 metadata 组件与校验
|
||
- M3：意图路由+metadata 检索与 fallback 日志闭环
|
||
- M4：拆解模板版本治理与回溯能力
|
||
|
||
### 10.2 验收样例（建议）
|
||
- 样例 1：录入“初二痛点&方案”，系统输出主归类=KB_PRODUCT，metadata 自动建议（grade=8, scene=pain_point）
|
||
- 样例 2：命中“初二成绩下滑怎么办”意图时，路由至 `product + parent_comm` 且过滤 `grade=8`
|
||
- 样例 3：字段 `flow_step` 被标记 deprecated 后，不可在新建对象选择，但历史对象仍可展示原值
|
||
- 样例 4：无召回时返回 fallback 并记录 `no_recall_after_metadata_filter`
|