ai-robot-core/docs/metadata-slot-prompt-recommendation.md

# AI客服配置参照：元数据字段、槽位、提示词

本文用于指导 AI 中台在客服场景下的配置，帮助你区分：

- 元数据字段（Metadata Field）
- 槽位定义（Slot）
- 提示词变量（Prompt Variable）

并给出可直接落地的推荐配置清单。

---

## 1. 三者定位与关系

### 1.1 元数据字段（平台级字段字典）

用于定义“系统中有哪些标准字段，以及这些字段可用于哪些能力”。

适合做：
- 知识库检索过滤（resource filter）
- 路由信号（routing signal）
- 运行时槽位承载（runtime slot）
- 提示词变量注入（prompt variable）

一句话：**先定义字段能力，再复用到各模块。**

### 1.2 槽位定义（流程级采集任务）

用于定义“对话中要收集什么信息、如何提取、如何校验、缺失如何追问”。

适合做：
- 必填信息采集（如订单号、手机号后四位）
- 提取策略配置（规则/LLM/用户输入）
- 缺失追问与校验

一句话：**槽位是采集动作，不是字段字典。**

### 1.3 提示词变量（生成时上下文）

用于把结构化信息注入模型上下文，提升回答准确率和拟人化质量。

典型变量：
- 用户关键信息：`grade`、`region`、`issue_type`
- 会话信息：`history_summary`、`session_stage`
- 系统能力信息：`available_tools`（系统注入）

一句话：**提示词变量负责“表达给模型看”。**

---

## 2. 推荐的配置顺序（强烈建议）

1. **先建元数据字段**（确定字段标准与角色）
2. **再建槽位定义**（关联元数据字段，配置提取与追问）
3. **最后接提示词模板**（读取变量做自然生成）

这样可以避免“先做槽位后无字段可回写”的混乱。

---

## 3. 元数据字段关键项：适用范围 / 是否必填 / 默认值（必看）

这三个配置项不是可有可无，建议按下面规则配置：

### 3.1 适用范围（必须选）

适用范围决定字段会在哪些模块生效。建议按“最小够用”原则勾选：

- `知识库文档`：仅当该字段用于 KB 文档元数据过滤时勾选
- `意图规则`：用于意图匹配/路由时勾选
- `话术流程`：字段会在流程节点中读写时勾选
- `Prompt模板`：需要把字段注入提示词时勾选

> 不要无脑全选。全选会导致维护复杂、噪声增大。

### 3.2 是否必填（建议谨慎）

建议：
- **元数据字段层面默认不必填**
- **在槽位层/流程层设置必填**（更符合场景化控制）

原因：元数据是全局字典，若字段全局必填，会让无关场景也被强制卡住。

### 3.3 默认值（能不填就不填）

建议：
- 优先留空
- 只有在你有明确兜底语义时才设置默认值
- 对路由类字段（如 `issue_type`、`risk_level`）尤其要慎用默认值，避免误导路由

可接受示例：
- `issue_type` 默认值可用 `unknown`，不要用 `refund` 这类强业务含义值

### 3.4 以 `issue_type` 为例的推荐配置

- 适用范围：`意图规则`、`话术流程`、`Prompt模板`（按需再加 `知识库文档`）
- 字段角色：`路由信号` + `提示词变量`，建议加 `运行时槽位`
- 是否必填：元数据层不勾；在 `slot_issue_type` 上勾必填
- 默认值：留空（或 `unknown`）

### 3.5 以 `order_id` 为例的推荐配置

- 适用范围：`话术流程`、`Prompt模板`（通常不需要 `意图规则`）
- 字段角色：`运行时槽位`（可按需加 `提示词变量`）
- 是否必填：元数据层不勾；在售后相关槽位/流程上设为必填
- 默认值：留空（不要给“假订单号”）

---

## 4. AI客服场景推荐元数据字段（首批）

> 说明：以下为通用模板，字段标识建议小写+下划线。

| 字段标识 | 展示名 | 类型 | 字段角色建议 | 是否可过滤 | 适用范围建议 | 元数据必填 | 默认值建议 | 用途说明 |
|---|---|---|---|---|---|---|---|---|
| `issue_type` | 问题类型 | 文本 | 路由信号、提示词变量、运行时槽位 | 是 | 意图规则、话术流程、Prompt模板 | 否 | 空/unknown | 意图粗分类（咨询/售后/退款/投诉） |
| `risk_level` | 风险等级 | 文本 | 路由信号、提示词变量 | 是 | 意图规则、Prompt模板 | 否 | 空 | 高风险判定联动（投诉、承诺、隐私） |
| `order_id` | 订单号 | 文本 | 运行时槽位、提示词变量 | 否 | 话术流程、Prompt模板 | 否 | 空 | 售后/物流/退款查询关键参数 |
| `phone_last4` | 手机号后四位 | 文本 | 运行时槽位 | 否 | 话术流程 | 否 | 空 | 身份辅助校验参数 |
| `product_line` | 产品线 | 文本 | 资源过滤、路由信号、提示词变量、运行时槽位 | 是 | 知识库文档、意图规则、话术流程、Prompt模板 | 否 | 空 | KB检索过滤与流程分流 |
| `region` | 地区 | 文本 | 资源过滤、提示词变量、运行时槽位 | 是 | 知识库文档、话术流程、Prompt模板 | 否 | 空 | 区域政策与文案差异 |
| `grade` | 年级 | 文本 | 资源过滤、运行时槽位、提示词变量 | 是 | 知识库文档、话术流程、Prompt模板 | 否 | 空 | 教培类场景常用过滤条件 |
| `channel` | 渠道 | 文本 | 路由信号、提示词变量 | 是 | 意图规则、Prompt模板 | 否 | 空 | H5/小程序/企微等渠道差异 |
| `membership_level` | 会员等级 | 文本 | 资源过滤、提示词变量 | 是 | 知识库文档、Prompt模板 | 否 | 空 | 会员权益/优先级策略 |
| `refund_stage` | 退款阶段 | 文本 | 路由信号、提示词变量、运行时槽位 | 是 | 意图规则、话术流程、Prompt模板 | 否 | 空 | 退款流程进度识别与话术选择 |
| `intent_confidence` | 意图置信度 | 数值 | 路由信号 | 否 | 意图规则 | 否 | 空 | 路由保守策略阈值判定 |
| `kb_scene` | 检索场景 | 文本 | 资源过滤 | 是 | 知识库文档 | 否 | （可选） | 区分 同一个知识库内的不同场景,从元数据的kb_scene中获取 等 |

---

## 5. AI客服场景推荐槽位（首批）

| 槽位标识 | 关联字段 | 必填 | 提取策略 | 校验建议 | 追问提示语建议 |
|---|---|---|---|---|---|
| `slot_issue_type` | `issue_type` | 是 | 规则提取 + LLM推断兜底 | 枚举（consult/refund/complaint/other） | “为了更快帮您处理，请问您是咨询、退款还是投诉相关问题呢？” |
| `slot_order_id` | `order_id` | 售后场景必填 | 用户输入优先 | 正则（长度/前缀） | “请提供订单号，我帮您马上查询处理进度。” |
| `slot_phone_last4` | `phone_last4` | 否 | 用户输入 | `^\d{4}$` | “若方便的话，请提供下单手机号后四位用于核对。” |
| `slot_product_line` | `product_line` | 是（多业务线） | 规则提取 | 枚举 | “请问您咨询的是哪条产品线（如课程/会员/硬件）？” |
| `slot_region` | `region` | 否 | 规则提取 + 用户输入 | 行政区字典校验 | “请问您所在地区是哪里？我按当地规则给您说明。” |
| `slot_grade` | `grade` | 教培场景推荐必填 | 规则提取 + 用户输入 | 枚举（初一~高三等） | “孩子目前是几年级？我给您更精准的建议。” |
| `slot_refund_stage` | `refund_stage` | 退款场景可选 | 规则提取 + LLM推断 | 枚举（申请中/审核中/已到账） | “您是刚提交退款，还是想查询退款进度呢？” |

---

## 6. 槽位提取策略怎么选

### 6.1 用户输入（最稳）
适合：订单号、手机号后四位、收货地址等明确值。

### 6.2 规则提取（高确定性）
适合：年级、日期、单号格式、固定关键词分类。

### 6.3 LLM推断（语义复杂）
适合：问题类型、情绪、复杂场景意图。

推荐顺序：
1. 用户输入
2. 规则提取
3. LLM推断兜底

---

## 7. 元数据字段与提示词的联动建议

建议在模板里使用字段变量，但避免过量，优先注入“最影响回答质量的5~8个变量”。

推荐注入变量：
- `issue_type`
- `product_line`
- `region`
- `membership_level`
- `refund_stage`
- `history_summary`

示例（片段）：

```text
用户问题类型：{{issue_type}}
产品线：{{product_line}}
地区：{{region}}
会员等级：{{membership_level}}
退款阶段：{{refund_stage}}
```

---

## 8. 你当前系统的关键保护项（必须遵守）

系统保留变量（受保护，不允许被模板默认值覆盖）：
- `available_tools`
- `query`
- `history`
- `internal_protocol`
- `output_contract`

说明：这些变量由系统运行时注入，用于保证工具调用正确性与安全性。

---

## 9. 推荐的最小可用配置（MVP）

如果你想先快速上线，至少先配：

### 元数据字段（6个）
- `issue_type`
- `order_id`
- `product_line`
- `region`
- `risk_level`
- `refund_stage`

### 槽位（4个）
- `slot_issue_type`
- `slot_order_id`
- `slot_product_line`
- `slot_region`

### 提示词变量
- `issue_type`
- `product_line`
- `region`
- `history_summary`

---

## 10. 常见误区

1. **把槽位当字段字典**：导致复用差，流程间字段不统一。
2. **字段角色乱选**：例如把所有字段都打成路由信号，导致路由噪声。
3. **LLM提取滥用**：高确定性字段不走规则，稳定性会下降。
4. **提示词变量过多**：上下文拥挤，反而影响回答质量。
5. **在元数据层把太多字段设为必填**：导致无关场景被阻塞。
6. **默认值乱填**：路由字段被默认值污染，出现误判。

---

## 11. 最终一句话决策法

- 你在定义“字段能力” → 用**元数据字段**
- 你在定义“对话采集” → 用**槽位定义**
- 你在定义“模型看到什么” → 用**提示词变量**

三者串起来：
**元数据字段（标准） → 槽位采集（取值） → 提示词变量（表达）**