# 元数据 + 意图识别 + 话术流程关联操作文档

## 1. 目标

本文用于指导运营/配置人员在管理界面完成以下闭环：
1. 配置元数据字段
2. 录入知识库文档并标注元数据
3. 配置意图规则（触发路由）
4. 配置话术流程（多轮推进）
5. 打通“意图 -> 检索/流程 -> 话术生成”

适用对象：产品、运营、实施、测试。

---

## 2. 概念关系（先理解）

- **元数据（Metadata）**：用于“筛选与路由”的标签，如 `grade`、`subject`、`scene`。
- **意图规则（Intent Rule）**：用于判断“用户在说什么、系统该做什么”。
- **话术流程（Script Flow）**：用于处理“多轮引导”，例如收集年级 -> 收集薄弱点 -> 推荐课程。

**执行链路**：

用户消息 -> 意图匹配 -> 
- 命中 `response_type=rag`：进入知识库检索（带 metadata filter）
- 命中 `response_type=flow`：进入话术流程
- 命中 `fixed/transfer`：直接固定回复或转人工

---

## 3. 第一步：配置元数据字段

进入：`元数据配置` 页面 -> 新建字段。

建议首批字段（教育场景）：
- `grade`（枚举）：初一/初二/初三/all
- `subject`（枚举）：语文/数学/英语/物理/化学/综合/all
- `scene`（枚举）：pain_point/transition/module_intro/faq/policy/closing
- `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
- `priority`（数字）：1-10
- `status`（枚举）：draft/active/deprecated

字段配置建议：
- `是否必填`：`grade/subject/scene/status` 建议必填
- `可过滤`：上述字段建议全部开启
- `排序特征`：仅 `priority` 建议开启
- `状态`：配置完成后由 `草稿 -> 激活`

注意：字段标识只用小写字母/数字/下划线，避免后续过滤失败。

---

## 4. 第二步：录入知识库文档并打元数据

进入：`知识库文档` 页面 -> 新增文档。

### 4.1 文档内容规范（你当前按行分块）
- 一行一个知识点
- 每行尽量只表达一个事实或一个建议
- 避免一行过长（建议 20~80 字）

### 4.2 元数据填写规范
示例（初一痛点文档）：
- `grade=初一`
- `subject=综合`
- `scene=pain_point`
- `flow_step=step2`
- `intent_type=ask_weak_point`
- `audience=parent`
- `status=active`
- `priority=8`

### 4.3 无年级、仅学科的数据怎么填
- `grade=all`
- `subject=语文/数学/...`
- 其余按场景填写

不建议因为“无年级”单独新建知识库，优先通过文档+metadata区分。

---

## 5. 第三步：配置意图规则（路由入口）

进入：`意图规则` 页面 -> 新建规则。

### 5.1 必填项
- 名称
- `keywords`（关键词）和/或 `patterns`（正则）
- `response_type`：fixed / rag / flow / transfer
- 优先级

### 5.2 推荐路由策略
- 课程咨询、薄弱点分析 -> `response_type=flow`
- 短问短答（价格、班型） -> `response_type=rag` 或 `fixed`
- 明确转人工 -> `response_type=transfer`

### 5.3 metadata 关联
在意图规则 metadata 中建议填写：
- `scene`
- `grade`（可选）
- `subject`（可选）

用于后续检索过滤增强。

---

## 6. 第四步：配置话术流程（与意图绑定）

进入：`话术流程` 页面 -> 新建或编辑流程。

### 6.1 你当前推荐流程（示例）
- Step1：确认年级
- Step2：年级特点 + 过渡到薄弱点
- Step3：确认薄弱科目/能力点
- Step4：针对薄弱点介绍课程模块
- Step5：给出下一步建议

### 6.2 每步建议配置
- `script_mode = flexible`
- 配置 `intent` / `intent_description`
- 配置 `script_constraints`
- 配置 `fallback content`
- 配置 `expected_variables`（如 `grade`, `weak_points`）

### 6.3 与知识库关联方式
- 在流程步骤中通过 `rag_config.tag_filter` 或上下文变量注入过滤（如 `grade`, `subject`, `scene`）
- Step2 常用 `scene=pain_point`
- Step4 常用 `scene=module_intro`

---

## 7. 第五步：关联关系配置清单（上线前检查）

### 7.1 意图 -> 流程
- 已有意图规则 `response_type=flow`
- `flow_id` 指向正确流程

### 7.2 意图/上下文 -> 检索
- 命中 `response_type=rag` 或流程步骤需要RAG时
- metadata filter 至少包含 `grade/subject/scene` 之一

### 7.3 文档 -> 检索命中
- 文档已 `status=active`
- 文档 metadata 与过滤字段一致（值完全一致）
- 文档内容按行分块且可检索

---

## 8. 验收用例（建议）

### 用例1：初一家长咨询
输入：`孩子刚上初一，成绩上不去怎么办？`
期望：
1. 命中课程咨询意图
2. 进入 flow（或rag+flow）
3. 检索优先命中 `grade=初一` 且 `scene=pain_point` 文档

### 用例2：仅学科问题
输入：`语文阅读理解总是丢分`
期望：
1. 命中学科提升相关意图
2. 检索命中 `subject=语文`、`grade=all` 或当前年级内容

### 用例3：无召回兜底
输入：冷门问题且无相关文档
期望：
1. 返回 fallback 话术
2. 记录无召回原因（便于补文档）

---

## 9. 常见问题与处理

1. **有文档但检索不到**
- 检查 metadata 值是否一致（如“初一” vs “七年级”）
- 检查字段是否可过滤、状态是否 active

2. **命中不准，答非所问**
- 缩小意图规则关键词
- 增加 metadata 过滤条件
- 拆分长行文本为更原子知识点

3. **是否要新增知识库**
- 先不拆库，优先文档+metadata
- 仅当串库严重/权限隔离/规模过大再拆

---

## 10. 运营维护建议

- 每周复盘：
  - 高频命中问题
  - 无召回问题
  - 错召回问题
- 按复盘结果更新：
  - 意图规则关键词与优先级
  - 文档内容与metadata
  - 流程约束与fallback

目标：持续提高“命中率、相关性、可用率”。