# 面向客服/售后/前台/智能座舱的高响应 Agent 技术方案

## 1. 文档目标

本文档用于设计一套可落地的 Agent 系统，满足以下核心诉求：

- 响应快：用户发起操作后，系统能够在极短时间内给出首响应或执行反馈。
- 执行准：对高频业务请求识别准确，对复杂请求可拆解、可校验、可执行。
- 可多轮：支持上下文记忆、槽位补全、断点续跑和任务恢复。
- 可扩展：适配客服、售后、前台接待、智能座舱等不同业务场景。
- 可运营：意图、槽位、规则、话术、插件均支持配置化管理。

本方案不是单纯的问答机器人，而是一个“可理解用户意图、可生成执行计划、可调用业务能力完成任务”的 Agent 平台。

## 2. 目标场景

### 2.1 客服场景

- 查询订单、物流、退款进度
- 识别催单、投诉、转人工、取消订单等诉求
- 多轮追问补全订单号、手机号、收货人等信息

### 2.2 售后场景

- 退货、换货、维修、预约上门
- 收集故障描述、图片、时间、地址等槽位
- 根据政策规则决定是否可直接处理、升级或转人工

### 2.3 前台场景

- 来访登记、会议室预约、路线引导、通知被访人
- 识别身份、预约信息、时间、地点等关键字段
- 支持多步骤任务执行和结果确认

### 2.4 智能座舱场景

- 导航、空调、车窗、音乐、电话、座椅等车控指令
- 识别复合指令，如“打开空调并导航去公司”
- 在驾驶场景下保证低延迟、强确定性和安全边界

## 3. 总体设计原则

### 3.1 快慢分层

高频、标准化、可确定执行的请求走“快路径”；复杂、低频、跨任务、带条件逻辑的请求走“慢路径”。

- 快路径：小模型分类 + 规则校验 + 直接执行
- 慢路径：RAG 召回 + LLM 精判 + 工作流生成 + 插件执行

这样可以同时满足“响应速度”和“复杂理解能力”。

### 3.2 LLM 不直接控制业务

LLM 只负责：

- 意图识别与精判
- 多意图拆分
- 槽位提取
- 执行计划生成
- 回复文案生成

真正的业务执行由规则引擎、状态管理器和插件执行器完成，避免 LLM 幻觉带来的误操作。

### 3.3 会话状态中心是核心

多轮对话不能依赖模型“记忆”，必须建设独立的 Session State。

状态中心负责：

- 保存当前会话上下文
- 保存已识别意图和已填充槽位
- 保存当前任务状态和执行进度
- 记录待补充信息和断点恢复位置

### 3.4 配置优先、插件扩展

以下能力尽量配置化，而不是写死在代码中：

- 意图定义
- 槽位定义
- 规则表达式
- 反问话术
- 权限与风控限制
- 插件路由关系

## 4. 建设目标

### 4.1 业务目标

- 支持不少于 100 个可配置意图
- 支持单意图、多意图、条件意图三类输入
- 支持跨轮补充槽位并继续执行
- 支持知识问答、事务办理、设备控制三类能力

### 4.2 体验目标

- 首字响应时间小于 800ms
- 高频标准请求平均响应时间 500ms 到 1500ms
- 复杂规划请求平均响应时间 1500ms 到 3500ms
- 多轮槽位补全过程中保持上下文一致

### 4.3 质量目标

- 高频意图识别准确率大于 95%
- 槽位抽取 F1 大于 90%
- 高风险动作误执行率接近 0
- 转人工触发符合业务策略并可追踪

## 5. 能力边界与功能点

### 5.1 核心能力

- 意图识别：识别用户到底要做什么
- 槽位提取：提取时间、地点、金额、对象、设备等参数
- 多意图拆分：识别一句话中多个任务
- 逻辑解析：识别顺序、条件、重试、并行关系
- 会话管理：跟踪当前任务、历史轮次和上下文变量
- 任务执行：调用业务接口、设备控制接口或人工服务接口
- 结果回复：结构化返回执行结果，必要时生成自然语言

### 5.2 平台能力

- 意图知识库管理
- 规则与话术配置平台
- 插件注册中心
- 会话状态存储
- 指标监控与日志追踪
- 安全审计与权限控制

### 5.3 场景化能力

- 客服：FAQ、工单、订单操作、转人工
- 售后：退换修、预约、故障诊断、流程推进
- 前台：访客接待、通知、预约、引导
- 智能座舱：设备控制、导航、多设备联动、安全确认

## 6. 系统总体架构

```text
用户输入
  -> 接入层（Web/App/语音/车机）
  -> 预处理层（ASR/文本归一化/敏感词/语言检测）
  -> 路由层
      -> 快路径：意图分类模型 + 规则匹配 + 插件执行
      -> 慢路径：向量召回 + LLM 精判 + Workflow 生成
  -> 状态中心（Session/Context/Slots/Current Step）
  -> 执行引擎（规则引擎 + 插件调度 + 断点恢复）
  -> 回复生成层（模板/LLM）
  -> 用户
```

## 7. 核心处理链路

### 7.1 快路径

适用于客服、前台、座舱中的高频标准请求，例如：

- “查一下我的订单”
- “打开空调”
- “帮我通知张三来前台”

执行流程：

1. 对输入做标准化与轻量实体提取
2. 进入轻量意图分类模型
3. 命中高置信度意图后，进行槽位校验
4. 槽位齐全则直接调用插件执行
5. 槽位缺失则触发反问并记录状态

优势：

- 延迟低
- 成本低
- 可控性强

### 7.2 慢路径

适用于复杂请求，例如：

- “帮我查一下订单，如果还没发货就取消”
- “导航去公司，然后把空调调到 22 度，再给我播放轻音乐”
- “我要退货，若超过 7 天就帮我转人工”

执行流程：

1. 向量召回 Top-K 候选意图
2. LLM 对候选意图做精判
3. 对输入做多意图拆分
4. 生成结构化 Workflow JSON
5. 执行引擎按步骤调度插件
6. 缺槽位时暂停并反问
7. 用户补充后从断点恢复执行

## 8. 推荐的多层 Agent 架构

### 8.1 第 1 层：输入理解层

职责：

- 文本清洗
- 口语归一化
- 同义词映射
- 设备指令别名统一
- 敏感/危险指令预过滤

### 8.2 第 2 层：意图路由层

职责：

- 判断是否命中高频快路径
- 判断是否需要进入复杂规划链路
- 判断是问答类、事务类还是控制类任务

推荐策略：

- 高频意图使用专门分类器
- 低频和新增意图使用向量召回
- 复杂指令交给 LLM 做精判和拆解

### 8.3 第 3 层：会话状态层

核心数据：

- session_id
- user_id / device_id
- current_intent
- current_workflow
- completed_steps
- pending_slots
- business_context
- risk_level

### 8.4 第 4 层：执行编排层

职责：

- 执行工作流
- 管理步骤状态
- 根据规则判断分支
- 调用插件
- 处理重试、超时和回滚

### 8.5 第 5 层：能力插件层

插件示例：

- 查询订单插件
- 取消订单插件
- 创建售后工单插件
- 访客登记插件
- 通知员工插件
- 导航插件
- 空调控制插件
- 音乐控制插件

### 8.6 第 6 层：回复生成层

优先级建议：

- 优先模板化返回
- 复杂解释场景再用 LLM 生成自然语言
- 高风险动作必须做明确确认和结果回执

## 9. 意图、槽位、工作流设计

### 9.1 意图设计

建议每个意图至少包含：

- intent_id
- intent_name
- domain
- description
- examples
- boundary
- required_slots
- optional_slots
- execution_plugin
- risk_level

示例：

```json
{
  "intent_id": "cabin_set_ac_temperature",
  "intent_name": "设置空调温度",
  "domain": "cabin_control",
  "required_slots": ["temperature"],
  "optional_slots": ["zone"],
  "execution_plugin": "ac_control_plugin",
  "risk_level": "low"
}
```

### 9.2 槽位设计

每个槽位建议配置：

- 名称
- 类型
- 是否必填
- 默认值
- 校验规则
- 提问模板
- 错误提示
- 来源优先级

### 9.3 Workflow 设计

复杂请求最终统一转成结构化执行计划。

示例：

```json
{
  "workflow_id": "wf_1001",
  "logic_type": "sequence",
  "steps": [
    {
      "step": 1,
      "intent": "query_order_status",
      "slots": {
        "order_id": "A123"
      }
    },
    {
      "step": 2,
      "condition": "order_status == 'pending_shipment'",
      "intent": "cancel_order"
    }
  ]
}
```

## 10. 多轮对话设计

### 10.1 多轮的本质

多轮不是每一轮都重新做完整识别，而是：

- 首轮生成任务或命中任务
- 后续轮次只做补槽位、确认、修正、继续执行

### 10.2 状态机设计

建议会话状态包括：

- `idle`：空闲
- `understanding`：理解中
- `waiting_slot`：等待用户补充信息
- `ready_to_execute`：准备执行
- `executing`：执行中
- `paused`：中断等待
- `completed`：完成
- `fallback`：兜底或转人工

### 10.3 断点续跑

示例：

1. 用户说“我要退货”
2. 系统识别退货意图，但缺少订单号
3. 系统反问“请提供订单号”
4. 用户回复“A123”
5. 系统只做槽位提取，不重新做全量规划
6. 系统恢复原任务继续执行

### 10.4 多轮省略恢复与上下文改写

参考车机场景的公开方案，多轮对话不能只靠“读取上一轮状态”，还应增加“相邻轮改写”和“高频缓存命中”能力。

适用场景：

- “音量调大” -> “再大一点”
- “导航去公司” -> “不要高速”
- “查一下北京天气” -> “上海呢”

建议新增一层 `context rewrite engine`，位于 `Session State` 和 `Router` 之间：

1. 读取上一轮已确认的主任务、领域和关键槽位
2. 将“当前轮短句 + 上一轮已确认语义”送入高频缓存引擎查询
3. 若命中缓存模板，直接改写为完整指令
4. 若缓存未命中，再使用轻量改写模型生成补全后的标准句
5. 改写后再进入意图识别与槽位提取

示例：

- 上一轮：`空调调高`
- 当前轮：`再高一点`
- 改写后：`把空调温度再调高一点`

缓存建议：

- key：`previous_intent + current_utterance_pattern`
- value：`rewritten_text / target_intent / slot_delta`
- 数据来源：高频真实语料、线上点击日志、人工标注样本

收益：

- 显著提升省略表达、连续调节、改口表达的识别率
- 避免每一轮都走完整大模型规划
- 将多轮短句场景时延压缩到接近单轮快路径

## 11. 模型方案

### 11.1 选型原则

- 高频场景优先低延迟
- 复杂场景优先理解能力
- 高风险场景优先可控和可审计
- 模型职责必须拆开，不要一个模型包打天下

### 11.2 推荐模型组合

#### A. 轻量意图识别模型

用途：

- 高频标准请求分类
- 第一时间做快路径路由

推荐方向：

- BERT / RoBERTa 中文分类模型
- 小型指令模型蒸馏版
- ONNX / TensorRT 部署后的轻量分类模型

适合场景：

- 客服高频查询
- 前台固定流程
- 座舱高频控制

#### B. 向量召回模型

用途：

- 动态意图库检索
- 召回候选意图与候选技能

推荐方向：

- BGE-M3
- BCE Embedding
- text-embedding 系列中文向量模型

#### C. 主 LLM

用途：

- 候选意图精判
- 多意图拆分
- 槽位抽取
- Workflow 生成
- 自然语言回复

推荐方向：

- 通义千问系列
- DeepSeek 系列
- GLM 系列
- GPT 类模型

建议：

- 线上使用支持函数调用、结构化输出、低温度推理的模型
- 对复杂规划与多轮状态更新使用 JSON schema 约束输出

#### D. ASR / TTS 模型

用于前台语音交互和智能座舱：

- ASR：语音转文本
- TTS：语音播报反馈
- VAD：语音活动检测，提升交互流畅度

### 11.3 推荐模型职责拆分

- 小模型：意图分类、风险识别、简单槽位抽取
- 向量模型：候选意图召回
- 大模型：复杂理解、规划和自然语言生成
- 规则引擎：确定性判断与业务约束

这是兼顾速度、成本和准确性的最佳组合。

### 11.4 端云协同模型分工

要达到接近车机助手的体验，必须采用“本地优先、云端增强、结果融合”的模型架构，而不是所有请求都走一个远端大模型。

建议分工如下：

- 本地 ASR / 文本归一化：负责第一时间得到稳定文本或拼音特征
- 本地快分支 1：关键词/规则/Trie 高频模式匹配
- 本地快分支 2：轻量 BERT 意图分类模型
- 本地快分支 3：多轮缓存改写 + 连续调节识别
- 本地快分支 4：轻量检索或 FAQ 命中
- 云端慢分支：复杂语义理解、多意图拆分、条件规划、知识问答、RAG、API 预测

融合原则：

- 本地结果若达到最高置信等级，则直接触发首响应与本地执行
- 云端结果若在可接受时间窗口内返回，则可覆盖或补充本地结果
- 对高风险动作，云端只能提供建议，最终执行仍由规则与插件层裁决

### 11.5 声学语义大模型的落地方式

参考公开专利中的“声学编码 + 字符转写 + 检索增强 + 大模型”思路，后续如果要做语音版车机，不建议继续把 ASR、NLU、知识检索和 API 预测完全割裂成独立长链路。

推荐两阶段落地：

- 第一期：保留模块化工程架构，但缩短串行链路，做到 `ASR -> local router -> plugin/cloud planner`
- 第二期：引入端到端语音语义模型，使其直接输出：
  - intent
  - slots
  - candidate_api
  - reject / clarify / execute decision

这样可以同时保留工程可控性和后续车机语音体验的升级空间。

## 12. 技术栈建议

### 12.1 服务端

- Python：适合快速构建 AI 编排、模型接入、规则处理
- FastAPI：提供高性能 API 服务
- Celery / 队列系统：处理异步任务和外部接口调用

如果团队更偏 Java，也可使用：

- Java + Spring Boot
- LangChain4j 或自研 Agent 编排层

### 12.2 检索与存储

- Redis：会话状态、热点缓存、限流计数
- PostgreSQL：业务数据、配置中心、日志审计
- Elasticsearch：检索与日志分析
- Qdrant / Milvus：向量检索与意图知识库召回

### 12.3 Agent 编排与规则

- 自研 Workflow Engine 或基于状态机的编排引擎
- JSON Schema：约束结构化输出
- 规则引擎：表达式解析、条件判断、路由控制

### 12.4 前端与接入

- Web 前端 / App SDK
- 呼叫中心接入
- 企业 IM 接入
- 车机系统接入
- 语音网关接入

### 12.5 可观测与运维

- Prometheus + Grafana：监控
- OpenTelemetry：链路追踪
- Loki / ELK：日志采集与分析

## 13. 响应速度优化方案

这是本系统成败的关键。

### 13.1 低延迟设计

- 高频意图前置分类，不直接把所有请求都交给 LLM
- 热门意图和常用知识走缓存
- 首响应和最终响应分离，先反馈“正在处理”
- LLM 使用流式输出
- 复杂任务异步执行，前台先返回受理状态

### 13.2 结构化提速

- 只给 LLM 候选意图，不让模型自由发散
- 后续轮次只做槽位提取，不重复做全流程规划
- 采用模板化回复代替不必要的长文本生成

### 13.3 工程提速

- 模型服务常驻内存
- Embedding 批量化和缓存
- 插件接口超时控制与降级
- 预加载高频配置与词典

### 13.4 参考车机方案的极速响应架构

为了逼近“小鹏 P7 类”体验，建议在当前快慢路径基础上，升级为“本地多支路并发 + 结果分级融合 + 云端延迟覆盖”的架构。

```text
用户输入
  -> 并发启动本地多支路
      -> Branch A: keyword / rule / trie
      -> Branch B: local bert classifier
      -> Branch C: context rewrite + cache engine
      -> Branch D: retrieval matcher
  -> 结果分级器
      -> high grade: 直接首响应 / 直接执行
      -> medium grade: 等待 100~300ms 观察其他分支
      -> low grade: 进入云端理解
  -> 云端 planner / rag / llm
  -> 融合器输出目标结果
```

分级融合建议使用以下特征：

- ASR 置信度 / 清晰度
- 本地意图分类置信度
- 领域置信度
- 槽位完备度
- 是否命中高频缓存
- 是否命中历史会话上下文
- 是否属于高风险动作

推荐时延预算：

- 0~150ms：文本标准化、关键词、Trie、缓存改写
- 150~350ms：本地 BERT / 本地检索 / 本地槽位提取
- 350~600ms：返回首响应或执行简单任务
- 600~1500ms：云端补充复杂理解或条件规划结果

首响应策略：

- 能本地直接执行的，优先回短反馈，如“好的，正在导航”
- 需要云端复杂规划的，先回受理反馈，如“收到，我先帮你确认一下”
- 云端超时不阻塞首响应，必要时走兜底或稍后补充结果

该策略是实现 `<1s` 体验的关键，不要求所有任务都在 1 秒内完成，但要求绝大多数任务在 1 秒内给出可感知反馈。

## 14. 准确率与执行可靠性设计

### 14.1 准确率保障

- 高频意图单独建模
- 意图边界描述清晰化
- 引入负样本和相似意图对比训练
- 使用 RAG 缩小候选范围后再让 LLM 精判

### 14.2 执行可靠性保障

- 高风险动作必须二次确认
- 插件执行前后都记录审计日志
- 核心步骤支持幂等、重试和回滚
- 输出必须是结构化结果，禁止自由文本直接驱动操作

### 14.3 风控策略

- 敏感词和危险动作拦截
- 用户身份和权限校验
- 场景安全等级区分
- 智能座舱中行车状态下限制高风险控制动作

### 14.4 多命令拆分与任务栈

为了支持“打开空调并导航去公司，再播放轻音乐”这一类车机复合指令，建议在路由层之后增加 `command splitter` 和 `task stack manager`。

输出结构建议：

```json
{
  "task_id": "task_001",
  "logic_type": "sequence",
  "commands": [
    {"intent": "cabin_set_ac", "slots": {"temperature": 22}},
    {"intent": "cabin_nav_to", "slots": {"destination": "公司"}},
    {"intent": "cabin_play_music", "slots": {"genre": "轻音乐"}}
  ]
}
```

执行要求：

- 简单并列命令支持顺序执行
- 需要条件判断的命令转为 workflow condition
- 允许用户在执行中打断、改口和取消后续任务
- 为每个任务保留任务栈、当前步骤和已完成步骤

打断策略：

- 新请求与当前任务冲突时，允许暂停旧任务并保存上下文
- 明确打断词出现时，清空当前任务栈或清理对应子任务上下文
- 对高风险动作，打断后不得默认自动恢复

### 14.5 拒答、澄清与简短反馈策略

要实现“反馈迅速而简短，不会的内容有合适拒绝话术”，不能只靠模型生成，应建设统一的 `response policy layer`。

回复规则：

- 简单执行成功：一句话短反馈，长度优先控制在 8~20 个字
- 缺槽位：只追问一个最关键槽位，不一次性问太多
- 不支持的请求：明确说明边界并给出可做事项
- 风险动作：先确认再执行
- 云端失败：给出降级反馈，不暴露内部错误

建议内置 5 类模板：

- `ack`：收到，马上处理
- `clarify`：信息不够，请补一个关键字段
- `confirm`：高风险动作确认
- `reject`：能力边界拒答
- `fallback`：系统忙或结果不稳定时的兜底

示例：

- `ack`：`好的，正在为你导航`
- `clarify`：`请告诉我订单号`
- `confirm`：`确认要取消这个订单吗`
- `reject`：`这个我暂时做不了，但我可以帮你导航、查订单或调空调`
- `fallback`：`我先记下你的需求，稍后再试一次`

核心原则：

- 首反馈短
- 首反馈稳
- 不会就明确拒答
- 不确定就先澄清
- 不让模型自由发挥高风险话术

## 15. 配置化设计

建议把以下内容全部放入配置中心：

- 意图定义
- 槽位定义
- 规则表达式
- 反问模板
- 插件映射
- 风险等级
- 转人工策略
- 场景开关

这样新增业务时，尽量做到“不改核心代码，只加配置和插件”。

## 16. 效果预期

### 16.1 对业务的价值

- 降低人工客服和前台重复劳动
- 提升售后处理自动化比例
- 提高智能座舱交互的自然度和完成率
- 缩短用户从提问到执行完成的路径

### 16.2 对用户的体验

- 回答更快
- 多轮更顺
- 执行更稳
- 出错可解释
- 失败可转人工

### 16.3 可量化指标

- 首响应耗时
- 请求完成率
- 单轮解决率
- 多轮补槽成功率
- 插件执行成功率
- 转人工率
- 用户满意度

## 17. 分阶段落地建议

### 17.1 第一阶段：POC

目标：

- 先验证快路径和多轮补槽是否可用

范围：

- 10 到 20 个高频意图
- 单领域试点，如客服或智能座舱

方案：

- 轻量分类模型 + Redis 状态中心 + 少量插件 + 模板回复

### 17.2 第二阶段：商用 MVP

目标：

- 覆盖主要业务链路，支持转人工和监控闭环

范围：

- 50 到 100 个意图
- 问答 + 事务 + 执行三类能力

方案：

- 分类模型 + 向量召回 + LLM 精判 + 执行引擎 + 配置中心

### 17.3 第三阶段：平台化

目标：

- 多场景复用，支持客服、售后、前台、座舱统一底座

范围：

- 多租户、多场景、多插件

方案：

- 插件平台、规则平台、意图库平台、评测平台、可观测平台全面建设

## 18. 最终建议

对于“回答迅速且执行准确”的 Agent，不建议直接用单一大模型硬做，而应采用以下混合架构：

- 高频请求：小模型分类直达执行
- 动态意图：向量召回缩小范围
- 复杂请求：LLM 做拆分、精判和工作流生成
- 多轮会话：状态中心负责记忆与恢复
- 最终执行：插件和规则引擎负责落地

一句话总结：

这是一个“快路径保证速度、慢路径保证理解、状态中心保证多轮、插件执行保证结果”的 Agent 架构。

如果后续继续推进，下一步建议补两份文档：

- 一份《系统架构图 + 时序图》
- 一份《意图表、槽位表、插件表、接口协议表》

## 19. 系统架构图

### 19.1 总体架构图

```mermaid
flowchart LR
    A[用户<br/>App / Web / 呼叫中心 / 车机] --> B[接入层<br/>API Gateway / WS / 语音网关]
    B --> C[预处理层<br/>ASR / 文本归一化 / 安全过滤 / 语言识别]
    C --> D[意图路由层]

    D --> E[快路径<br/>轻量分类模型 + 规则匹配]
    D --> F[慢路径<br/>向量召回 + LLM 精判 + Workflow 生成]

    E --> G[槽位校验]
    F --> H[复杂任务解析]

    G --> I[状态中心<br/>Session / Slots / Context / Current Step]
    H --> I

    I --> J[执行引擎<br/>状态机 / 规则引擎 / 插件调度]
    J --> K[插件层<br/>订单 / 售后 / 前台 / 座舱 / 转人工]

    K --> L[业务系统<br/>CRM / ERP / 工单 / 地图 / IoT / 车控]
    J --> M[回复生成层<br/>模板回复 / LLM 润色 / TTS]
    M --> N[用户反馈]

    I --> O[Redis]
    J --> P[PostgreSQL]
    F --> Q[向量库 Qdrant / Milvus]
    J --> R[监控审计<br/>日志 / Trace / Metrics]
```

### 19.2 模块职责说明

- 接入层：统一承接文本、语音、车机和 IM 渠道请求。
- 预处理层：负责 ASR、文本标准化、敏感词过滤、别名归一。
- 意图路由层：判断进入快路径还是慢路径。
- 状态中心：保存会话、槽位、上下文和当前执行进度。
- 执行引擎：按规则与工作流调度插件，控制暂停、恢复、重试和回滚。
- 插件层：承接具体业务动作，保证执行可控和可审计。

## 20. 核心时序图

### 20.1 高频请求快路径时序图

适用场景：

- “打开空调”
- “查询订单”
- “通知张三到前台”

```mermaid
sequenceDiagram
    participant U as 用户
    participant G as 接入层
    participant R as 路由层
    participant C as 轻量分类模型
    participant S as 状态中心
    participant E as 执行引擎
    participant P as 业务插件
    participant B as 业务系统

    U->>G: 发起请求
    G->>R: 预处理后的文本
    R->>C: 意图分类
    C-->>R: 高频意图 + 置信度
    R->>S: 读取/更新会话状态
    R->>E: 发起执行请求
    E->>P: 调用目标插件
    P->>B: 调用业务接口
    B-->>P: 返回结果
    P-->>E: 执行结果
    E->>S: 更新步骤状态
    E-->>G: 结构化结果
    G-->>U: 返回执行结果
```

### 20.2 复杂请求慢路径时序图

适用场景：

- “查订单，如果没发货就取消”
- “导航去公司，再把空调调到 22 度”

```mermaid
sequenceDiagram
    participant U as 用户
    participant G as 接入层
    participant R as 路由层
    participant V as 向量召回
    participant L as LLM
    participant S as 状态中心
    participant E as 执行引擎
    participant P as 插件层

    U->>G: 发起复杂请求
    G->>R: 预处理后的输入
    R->>V: 召回候选意图 Top-K
    V-->>R: 候选意图列表
    R->>L: 候选意图 + 用户输入
    L-->>R: 精判结果 + Workflow JSON
    R->>S: 保存 workflow 和 slots
    R->>E: 启动执行
    E->>P: 按步骤调度插件
    P-->>E: 每步执行结果
    E->>S: 更新 current_step / context
    E-->>G: 汇总结果
    G-->>U: 返回执行反馈
```

### 20.3 多轮补槽与断点续跑时序图

适用场景：

- “我要退货”
- “帮我预约维修”
- “导航去机场，走高速”

```mermaid
sequenceDiagram
    participant U as 用户
    participant G as 接入层
    participant R as 路由层
    participant L as LLM/抽取模型
    participant S as 状态中心
    participant E as 执行引擎
    participant P as 插件层

    U->>G: 我要退货
    G->>R: 首轮请求
    R->>L: 识别意图并抽取槽位
    L-->>R: 退货意图，缺少 order_id
    R->>S: 保存 pending_slots=order_id
    R-->>G: 生成追问
    G-->>U: 请提供订单号

    U->>G: A123456
    G->>S: 带 session_id 读取上下文
    S-->>G: 返回待补槽位信息
    G->>L: 仅做槽位提取
    L-->>G: order_id=A123456
    G->>S: 更新槽位并置为 ready_to_execute
    G->>E: 从断点恢复执行
    E->>P: 调用退货插件
    P-->>E: 返回结果
    E->>S: 更新为 completed
    E-->>G: 执行成功
    G-->>U: 已为你提交退货申请
```

## 21. 场景执行图

### 21.1 智能座舱复合指令执行图

示例指令：

- “打开空调到 22 度，导航去公司，再播放轻音乐”

```mermaid
flowchart TD
    A[用户输入复合指令] --> B[意图拆分]
    B --> C1[设置空调]
    B --> C2[导航到公司]
    B --> C3[播放轻音乐]

    C1 --> D[槽位校验 temperature=22]
    C2 --> E[槽位校验 destination=公司]
    C3 --> F[槽位校验 genre=轻音乐]

    D --> G[空调插件]
    E --> H[导航插件]
    F --> I[音乐插件]

    G --> J[更新座舱上下文]
    H --> J
    I --> J
    J --> K[统一反馈执行结果]
```

### 21.2 客服售后条件流程图

示例指令：

- “帮我查订单，如果还没发货就取消”

```mermaid
flowchart TD
    A[用户输入] --> B[识别查询订单 + 取消订单]
    B --> C[生成条件工作流]
    C --> D[执行查询订单插件]
    D --> E{是否已发货}
    E -- 否 --> F[执行取消订单插件]
    E -- 是 --> G[返回不可取消说明]
    F --> H[返回取消成功]
    G --> I[结束]
    H --> I
```

## 22. 时序图对应的工程说明

### 22.1 为什么要先路由再规划

- 不是所有请求都需要 LLM。
- 高频请求先经过快路径，能够显著降低响应延迟和调用成本。
- 复杂请求才进入召回与规划链路，保证资源集中用在真正困难的问题上。

### 22.2 为什么多轮只做补槽不重规划

- 这样可以减少模型重复推理，显著缩短第二轮及后续轮次响应时间。
- 可以避免上下文漂移，保证任务持续围绕原始目标推进。
- 更适合客服、售后、前台、座舱这类明确任务型交互。

### 22.3 为什么执行一定要经过状态中心

- 执行过程需要可追踪、可暂停、可恢复。
- 插件失败、超时、用户打断等情况都需要状态中心统一管理。
- 后续做审计、风控、会话分析时，也必须依赖完整状态记录。

## 23. 下一步详细设计建议

在当前架构图和时序图基础上，建议下一步输出以下内容：

1. 意图清单：按客服、售后、前台、座舱四大域拆分。
2. 槽位字典：定义每个意图所需字段、校验规则和追问模板。
3. 插件接口表：定义入参、出参、幂等键、超时与错误码。
4. MVP 范围：先选 10 到 20 个高频意图，构建第一版闭环。

## 24. 意图清单初稿

### 24.1 字段说明

建议每个意图至少包含以下字段：

- `intent_id`：意图唯一标识
- `intent_name`：意图名称
- `domain`：所属业务域
- `type`：问答 / 事务 / 控制
- `priority`：优先级
- `risk_level`：风险等级
- `entry_path`：快路径 / 慢路径
- `required_slots`：必填槽位
- `plugin_id`：执行插件标识

### 24.2 客服域意图表

| intent_id | intent_name | type | risk_level | entry_path | required_slots | plugin_id |
| --- | --- | --- | --- | --- | --- | --- |
| cs_query_order | 查询订单状态 | 事务 | low | 快路径 | order_id | plugin.order.query |
| cs_query_logistics | 查询物流 | 事务 | low | 快路径 | order_id | plugin.logistics.query |
| cs_cancel_order | 取消订单 | 事务 | medium | 快路径 | order_id | plugin.order.cancel |
| cs_refund_status | 查询退款进度 | 事务 | low | 快路径 | refund_id/order_id | plugin.refund.query |
| cs_transfer_human | 转人工 | 事务 | low | 快路径 | reason | plugin.service.transfer_human |
| cs_complaint_submit | 提交投诉 | 事务 | medium | 慢路径 | complaint_type, content | plugin.ticket.complaint |

### 24.3 售后域意图表

| intent_id | intent_name | type | risk_level | entry_path | required_slots | plugin_id |
| --- | --- | --- | --- | --- | --- | --- |
| af_apply_return | 申请退货 | 事务 | medium | 快路径 | order_id, reason | plugin.aftersale.return |
| af_apply_exchange | 申请换货 | 事务 | medium | 慢路径 | order_id, reason | plugin.aftersale.exchange |
| af_apply_repair | 申请维修 | 事务 | medium | 慢路径 | product_id, fault_desc | plugin.aftersale.repair |
| af_book_service | 预约上门服务 | 事务 | medium | 慢路径 | address, time_range, phone | plugin.aftersale.booking |
| af_query_ticket | 查询工单进度 | 事务 | low | 快路径 | ticket_id | plugin.ticket.query |
| af_upload_material | 补充售后材料 | 事务 | low | 快路径 | ticket_id, material_type | plugin.ticket.material |

### 24.4 前台域意图表

| intent_id | intent_name | type | risk_level | entry_path | required_slots | plugin_id |
| --- | --- | --- | --- | --- | --- | --- |
| front_visitor_register | 来访登记 | 事务 | medium | 慢路径 | visitor_name, phone, host_name | plugin.frontdesk.visitor_register |
| front_notify_host | 通知被访人 | 事务 | low | 快路径 | host_name | plugin.frontdesk.notify_host |
| front_book_meeting_room | 预约会议室 | 事务 | medium | 慢路径 | room_name, start_time, end_time | plugin.frontdesk.book_room |
| front_route_guide | 路线引导 | 问答 | low | 快路径 | destination | plugin.frontdesk.route_guide |
| front_check_appointment | 查询预约信息 | 事务 | low | 快路径 | phone/appointment_id | plugin.frontdesk.query_appointment |
| front_print_badge | 打印访客证 | 控制 | medium | 快路径 | visitor_name, company | plugin.frontdesk.print_badge |

### 24.5 智能座舱域意图表

| intent_id | intent_name | type | risk_level | entry_path | required_slots | plugin_id |
| --- | --- | --- | --- | --- | --- | --- |
| cabin_nav_to | 导航到目的地 | 控制 | medium | 快路径 | destination | plugin.cabin.navigation |
| cabin_set_ac | 设置空调 | 控制 | low | 快路径 | temperature | plugin.cabin.ac_control |
| cabin_window_control | 控制车窗 | 控制 | medium | 快路径 | position, action | plugin.cabin.window_control |
| cabin_play_music | 播放音乐 | 控制 | low | 快路径 | song/genre | plugin.cabin.music_play |
| cabin_call_contact | 拨打电话 | 控制 | high | 慢路径 | contact_name | plugin.cabin.call_contact |
| cabin_multi_command | 复合指令执行 | 控制 | medium | 慢路径 | workflow | plugin.cabin.workflow_executor |

### 24.6 通用兜底意图

| intent_id | intent_name | type | risk_level | entry_path | required_slots | plugin_id |
| --- | --- | --- | --- | --- | --- | --- |
| common_faq | 知识问答 | 问答 | low | 快路径 | 无 | plugin.knowledge.faq |
| common_clarify | 澄清意图 | 问答 | low | 慢路径 | 无 | plugin.dialog.clarify |
| common_reject | 拒绝执行 | 问答 | high | 快路径 | 无 | plugin.guard.reject |
| common_fallback | 兜底处理 | 问答 | low | 慢路径 | 无 | plugin.dialog.fallback |

## 25. 槽位字典初稿

### 25.1 通用槽位表

| slot_name | type | required | example | validate_rule | ask_template | used_by |
| --- | --- | --- | --- | --- | --- | --- |
| order_id | string | 是 | A123456 | 长度 6-32，字母数字 | 请提供订单号 | 客服、售后 |
| refund_id | string | 否 | R2025001 | 长度 6-32 | 请提供退款单号 | 客服 |
| ticket_id | string | 是 | T90001 | 长度 4-32 | 请提供工单号 | 售后 |
| appointment_id | string | 否 | AP2026001 | 长度 4-32 | 请提供预约编号 | 前台 |
| product_id | string | 是 | SKU12345 | 长度 4-64 | 请提供商品编号或设备编号 | 售后 |
| reason | string | 是 | 不想要了 | 长度 2-200 | 请说明原因 | 客服、售后 |
| fault_desc | string | 是 | 无法开机 | 长度 5-300 | 请描述故障现象 | 售后 |
| complaint_type | enum | 是 | 服务问题 | 枚举校验 | 请问是商品问题、物流问题还是服务问题 | 客服 |
| content | string | 是 | 客服态度差 | 长度 5-500 | 请描述具体情况 | 客服 |
| phone | string | 是 | 13800138000 | 手机号格式 | 请提供手机号 | 售后、前台 |
| time_range | string | 是 | 明天下午 2 点到 4 点 | 可解析时间范围 | 请提供预约时间 | 售后、前台 |
| address | string | 是 | 上海浦东新区 XX 路 | 长度 5-200 | 请提供服务地址 | 售后 |
| material_type | enum | 是 | 故障图片 | 枚举校验 | 请说明要补充的材料类型 | 售后 |
| visitor_name | string | 是 | 张三 | 长度 2-50 | 请提供来访人姓名 | 前台 |
| host_name | string | 是 | 李经理 | 长度 2-50 | 请问要拜访谁 | 前台 |
| company | string | 否 | 某某科技 | 长度 2-100 | 请提供访客单位名称 | 前台 |
| room_name | string | 是 | 3F-A01 | 会议室编码格式 | 请提供会议室名称或编号 | 前台 |
| start_time | datetime | 是 | 2026-05-10 14:00 | 标准时间格式 | 请提供开始时间 | 前台 |
| end_time | datetime | 是 | 2026-05-10 15:00 | 晚于开始时间 | 请提供结束时间 | 前台 |
| destination | string | 是 | 公司/虹桥机场 | POI 或地址可解析 | 请告诉我要去哪里 | 前台、座舱 |
| temperature | number | 是 | 22 | 16-30 | 请问要设置多少度 | 座舱 |
| position | enum | 是 | 主驾窗 | 枚举校验 | 请问要控制哪个车窗 | 座舱 |
| action | enum | 是 | 打开/关闭 | 枚举校验 | 请问要打开还是关闭 | 座舱 |
| song | string | 否 | 夜曲 | 长度 1-100 | 请问要播放哪首歌 | 座舱 |
| genre | string | 否 | 轻音乐 | 长度 1-50 | 请问要听什么类型的音乐 | 座舱 |
| contact_name | string | 是 | 王总 | 长度 2-50 | 请问要拨打给谁 | 座舱 |
| workflow | json | 是 | 复合动作 JSON | JSON Schema 校验 | 正在解析复合指令 | 座舱 |

### 25.2 槽位配置建议

每个槽位建议增加如下元数据：

- `normalize_fn`：归一化方法，例如金额、时间、地址标准化
- `source_priority`：优先从用户当前输入、历史会话还是业务上下文中取值
- `confirm_required`：是否需要用户确认
- `risk_binding`：是否与风险动作绑定
- `rewrite_prompt`：槽位识别失败时的重试提示

### 25.3 槽位提取策略

- 首轮请求：意图识别与槽位提取同时进行
- 补槽轮次：只提取 `pending_slots`
- 高风险槽位：提取后必须二次确认
- 可继承槽位：如 `phone`、`host_name`，可从历史会话或用户档案中补全

## 26. 插件接口规范初稿

### 26.1 插件统一接口

所有业务插件建议遵循统一接口，便于执行引擎调度：

```json
{
  "plugin_id": "plugin.order.cancel",
  "request_id": "req_001",
  "session_id": "sess_001",
  "user_id": "user_001",
  "intent_id": "cs_cancel_order",
  "slots": {
    "order_id": "A123456",
    "reason": "不想要了"
  },
  "context": {
    "channel": "app",
    "trace_id": "trace_001"
  }
}
```

统一响应格式建议如下：

```json
{
  "success": true,
  "code": "OK",
  "message": "订单取消成功",
  "data": {
    "order_id": "A123456",
    "status": "cancelled"
  },
  "need_confirm": false,
  "need_more_slots": [],
  "retryable": false
}
```

### 26.2 插件表初稿

| plugin_id | plugin_name | domain | input_slots | output_fields | timeout_ms | retry_policy | idempotent_key |
| --- | --- | --- | --- | --- | --- | --- | --- |
| plugin.order.query | 查询订单 | 客服 | order_id | order_status, pay_status | 1500 | 失败重试 1 次 | session_id + order_id |
| plugin.logistics.query | 查询物流 | 客服 | order_id | logistics_status, trace_list | 1500 | 失败重试 1 次 | session_id + order_id |
| plugin.order.cancel | 取消订单 | 客服 | order_id, reason | cancel_status | 2000 | 不自动重试 | session_id + order_id |
| plugin.service.transfer_human | 转人工 | 客服 | reason | queue_no, wait_time | 1000 | 不自动重试 | session_id + reason |
| plugin.aftersale.return | 申请退货 | 售后 | order_id, reason | return_ticket_id | 2000 | 不自动重试 | session_id + order_id |
| plugin.aftersale.repair | 申请维修 | 售后 | product_id, fault_desc | repair_ticket_id | 2500 | 不自动重试 | session_id + product_id |
| plugin.aftersale.booking | 上门预约 | 售后 | address, time_range, phone | booking_id | 2500 | 失败重试 1 次 | session_id + phone + time_range |
| plugin.frontdesk.visitor_register | 来访登记 | 前台 | visitor_name, phone, host_name | visit_id, qr_code | 2000 | 不自动重试 | session_id + phone |
| plugin.frontdesk.notify_host | 通知被访人 | 前台 | host_name | notify_status | 1000 | 失败重试 1 次 | session_id + host_name |
| plugin.frontdesk.book_room | 预约会议室 | 前台 | room_name, start_time, end_time | booking_status, booking_id | 2000 | 不自动重试 | session_id + room_name + start_time |
| plugin.cabin.navigation | 导航 | 座舱 | destination | route_id, eta | 1200 | 失败重试 1 次 | session_id + destination |
| plugin.cabin.ac_control | 空调控制 | 座舱 | temperature | ac_status | 800 | 不自动重试 | session_id + temperature |
| plugin.cabin.window_control | 车窗控制 | 座舱 | position, action | window_status | 800 | 不自动重试 | session_id + position + action |
| plugin.cabin.music_play | 音乐播放 | 座舱 | song/genre | play_status, media_id | 1000 | 失败重试 1 次 | session_id + song + genre |

### 26.3 插件错误码建议

| code | meaning | action |
| --- | --- | --- |
| OK | 执行成功 | 正常返回 |
| MISSING_SLOT | 缺少必要槽位 | 转为追问流程 |
| INVALID_SLOT | 槽位不合法 | 触发重试提示 |
| NEED_CONFIRM | 需要用户确认 | 进入确认节点 |
| NO_PERMISSION | 权限不足 | 拒绝执行并解释原因 |
| RISK_BLOCKED | 风险拦截 | 终止执行并记录审计 |
| BIZ_TIMEOUT | 下游超时 | 可重试或降级 |
| BIZ_FAILED | 业务失败 | 给出失败原因 |
| SYSTEM_ERROR | 系统异常 | 兜底或转人工 |

### 26.4 插件开发约束

- 插件必须无状态，状态统一交给状态中心管理。
- 插件必须返回结构化结果，不能只返回自然语言。
- 高风险插件必须支持 `need_confirm` 控制。
- 写操作类插件必须支持幂等键。
- 插件必须记录 trace_id，支持全链路审计。

## 27. 接口协议建议

### 27.1 对话入口接口

`POST /api/v1/agent/chat`

请求示例：

```json
{
  "session_id": "sess_001",
  "user_id": "user_001",
  "channel": "app",
  "input_text": "帮我查一下订单，如果没发货就取消",
  "input_type": "text",
  "metadata": {
    "device_id": "dev_001",
    "tenant_id": "tenant_a"
  }
}
```

响应示例：

```json
{
  "session_id": "sess_001",
  "reply_type": "workflow_result",
  "reply_text": "已为你查询订单，当前未发货，正在为你取消。",
  "intent": "cs_cancel_order",
  "status": "executing",
  "pending_slots": [],
  "workflow_id": "wf_001",
  "trace_id": "trace_001"
}
```

### 27.2 补槽接口

`POST /api/v1/agent/fill-slots`

请求示例：

```json
{
  "session_id": "sess_001",
  "user_id": "user_001",
  "input_text": "订单号是 A123456"
}
```

响应示例：

```json
{
  "session_id": "sess_001",
  "status": "ready_to_execute",
  "filled_slots": {
    "order_id": "A123456"
  },
  "pending_slots": [],
  "reply_text": "收到，正在继续为你处理。"
}
```

### 27.3 管理后台接口建议

- `GET /api/v1/intents`
- `POST /api/v1/intents`
- `GET /api/v1/slots`
- `POST /api/v1/plugins/register`
- `GET /api/v1/sessions/{session_id}`
- `GET /api/v1/traces/{trace_id}`

## 28. MVP 一期范围建议

### 28.1 一期目标

目标不是一开始覆盖所有场景，而是优先打通一条“能快速响应、能多轮补槽、能真正执行”的闭环。

### 28.2 推荐一期场景

建议先选两个最有代表性的场景：

- 客服：查询订单、查物流、取消订单、转人工
- 智能座舱：导航、空调控制、音乐播放、复合指令

这样可以同时覆盖：

- 标准事务型任务
- 高实时控制型任务
- 多轮补槽能力
- 复杂复合指令能力

### 28.3 一期推荐意图

建议第一期先落 12 个意图：

| domain | intent_id | intent_name | priority |
| --- | --- | --- | --- |
| 客服 | cs_query_order | 查询订单状态 | P0 |
| 客服 | cs_query_logistics | 查询物流 | P0 |
| 客服 | cs_cancel_order | 取消订单 | P0 |
| 客服 | cs_transfer_human | 转人工 | P0 |
| 售后 | af_apply_return | 申请退货 | P1 |
| 售后 | af_query_ticket | 查询工单进度 | P1 |
| 前台 | front_notify_host | 通知被访人 | P1 |
| 前台 | front_route_guide | 路线引导 | P1 |
| 座舱 | cabin_nav_to | 导航到目的地 | P0 |
| 座舱 | cabin_set_ac | 设置空调 | P0 |
| 座舱 | cabin_play_music | 播放音乐 | P0 |
| 座舱 | cabin_multi_command | 复合指令执行 | P0 |

### 28.4 一期必须具备的能力

- 会话状态中心
- 快路径意图分类
- 基础槽位提取
- 补槽追问与断点恢复
- 插件统一协议
- 至少 8 个可执行插件
- 基础监控和审计日志

### 28.5 一期不建议过早投入的能力

- 全量复杂规则平台
- 多租户运营后台
- 自动训练平台
- 端到端自主规划型 Agent

### 28.6 一期验收标准

| metric | target |
| --- | --- |
| 高频快路径平均响应时间 | <= 1.5s |
| 复杂慢路径平均响应时间 | <= 3.5s |
| 多轮补槽成功率 | >= 85% |
| 插件执行成功率 | >= 95% |
| 高频意图识别准确率 | >= 95% |
| 高风险误执行率 | 0 |

## 29. 开发拆分建议

### 29.1 服务拆分

- `gateway-service`：统一接入与鉴权
- `nlu-service`：分类、抽取、召回、精判
- `session-service`：会话状态管理
- `orchestrator-service`：工作流执行与插件调度
- `plugin-service`：业务插件实现
- `ops-console`：配置与观测后台

### 29.2 迭代顺序

1. 先做会话状态中心和统一协议。
2. 再做快路径分类与基础插件闭环。
3. 然后接入向量召回和 LLM 精判。
4. 最后补复合指令、多轮恢复、监控审计。

### 29.3 人员建议

- 后端工程师：2 人
- AI/NLP 工程师：1 到 2 人
- 前端或客户端工程师：1 人
- 测试工程师：1 人
- 产品经理：1 人

## 30. 下一步建议

基于当前文档，下一步最适合继续补的是：

1. 数据库表结构设计
2. Redis Session 结构设计
3. Workflow JSON Schema
4. 插件 SDK 规范
5. 评测集与测试用例设计

## 31. 数据库表结构设计

### 31.1 设计原则

- 业务配置与运行态数据分离。
- 高并发状态放 Redis，持久化和审计放 PostgreSQL。
- 配置表优先满足可运营、可灰度、可版本化。
- 运行表优先满足可追踪、可排障、可回放。

### 31.2 核心表清单

| table_name | purpose |
| --- | --- |
| intents | 意图定义表 |
| intent_examples | 意图示例语料表 |
| slots | 槽位定义表 |
| intent_slot_bindings | 意图和槽位绑定表 |
| plugins | 插件注册表 |
| plugin_routes | 意图到插件路由表 |
| workflow_templates | 工作流模板表 |
| sessions | 会话主表 |
| session_messages | 会话消息表 |
| task_executions | 任务执行表 |
| task_steps | 任务步骤表 |
| plugin_calls | 插件调用日志表 |
| audit_logs | 审计日志表 |
| evaluation_cases | 评测样本表 |

### 31.3 关键表字段示例

#### intents

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| intent_id | varchar(64) unique | 意图唯一标识 |
| intent_name | varchar(128) | 意图名称 |
| domain | varchar(64) | 业务域 |
| type | varchar(32) | 问答/事务/控制 |
| risk_level | varchar(16) | 风险等级 |
| entry_path | varchar(16) | 快路径/慢路径 |
| enabled | boolean | 是否启用 |
| version | int | 配置版本 |
| description | text | 说明 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

#### slots

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| slot_name | varchar(64) unique | 槽位名称 |
| slot_type | varchar(32) | string/number/enum/json |
| required | boolean | 是否必填 |
| validate_rule | varchar(256) | 校验规则 |
| ask_template | varchar(256) | 追问模板 |
| normalize_fn | varchar(64) | 归一化方法 |
| confirm_required | boolean | 是否需要确认 |
| enabled | boolean | 是否启用 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

#### intent_slot_bindings

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| intent_id | varchar(64) | 意图标识 |
| slot_name | varchar(64) | 槽位名称 |
| required | boolean | 对该意图是否必填 |
| priority | int | 提问优先级 |
| source_priority | varchar(128) | 来源优先级 |
| created_at | timestamp | 创建时间 |

#### plugins

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| plugin_id | varchar(128) unique | 插件标识 |
| plugin_name | varchar(128) | 插件名称 |
| domain | varchar(64) | 所属域 |
| endpoint | varchar(256) | 插件地址或服务名 |
| timeout_ms | int | 超时时间 |
| retry_policy | varchar(64) | 重试策略 |
| idempotent_rule | varchar(128) | 幂等规则 |
| enabled | boolean | 是否启用 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

#### sessions

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| session_id | varchar(64) unique | 会话标识 |
| user_id | varchar(64) | 用户标识 |
| channel | varchar(32) | 渠道 |
| current_intent | varchar(64) | 当前意图 |
| current_status | varchar(32) | 当前状态 |
| current_workflow_id | varchar(64) | 当前工作流 |
| risk_level | varchar(16) | 当前风险等级 |
| last_message_at | timestamp | 最后活跃时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

#### session_messages

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| session_id | varchar(64) | 会话标识 |
| role | varchar(16) | user/assistant/system |
| message_text | text | 文本内容 |
| structured_payload | jsonb | 结构化载荷 |
| trace_id | varchar(64) | 链路标识 |
| created_at | timestamp | 创建时间 |

#### task_executions

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| task_id | varchar(64) unique | 任务标识 |
| session_id | varchar(64) | 会话标识 |
| workflow_id | varchar(64) | 工作流标识 |
| status | varchar(32) | pending/running/paused/completed/failed |
| current_step | int | 当前步骤 |
| context_snapshot | jsonb | 上下文快照 |
| error_code | varchar(64) | 错误码 |
| error_message | varchar(256) | 错误信息 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

#### task_steps

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| task_id | varchar(64) | 任务标识 |
| step_no | int | 步骤号 |
| intent_id | varchar(64) | 步骤意图 |
| plugin_id | varchar(128) | 插件标识 |
| status | varchar(32) | 步骤状态 |
| input_payload | jsonb | 入参 |
| output_payload | jsonb | 出参 |
| started_at | timestamp | 开始时间 |
| ended_at | timestamp | 结束时间 |

#### plugin_calls

| field | type | desc |
| --- | --- | --- |
| id | bigint pk | 主键 |
| trace_id | varchar(64) | 链路标识 |
| task_id | varchar(64) | 任务标识 |
| plugin_id | varchar(128) | 插件标识 |
| request_payload | jsonb | 请求内容 |
| response_payload | jsonb | 响应内容 |
| success | boolean | 是否成功 |
| latency_ms | int | 调用耗时 |
| created_at | timestamp | 创建时间 |

### 31.4 建表索引建议

- `intents(intent_id)` 唯一索引
- `slots(slot_name)` 唯一索引
- `plugins(plugin_id)` 唯一索引
- `sessions(session_id)` 唯一索引
- `sessions(user_id, updated_at)` 组合索引
- `session_messages(session_id, created_at)` 组合索引
- `task_executions(session_id, status)` 组合索引
- `plugin_calls(trace_id)` 普通索引

## 32. Redis Session 结构设计

### 32.1 设计目标

- 支持毫秒级读取会话状态
- 支持多轮补槽和断点恢复
- 支持任务并发控制和幂等去重
- 支持热点上下文缓存

### 32.2 Key 设计

| key_pattern | type | purpose | ttl |
| --- | --- | --- | --- |
| `agent:session:{session_id}` | Hash | 会话主状态 | 24h |
| `agent:slots:{session_id}` | Hash | 当前已填槽位 | 24h |
| `agent:pending:{session_id}` | List | 待补槽位队列 | 24h |
| `agent:workflow:{session_id}` | String | 当前 Workflow JSON | 24h |
| `agent:context:{session_id}` | String | 上下文快照 JSON | 24h |
| `agent:lock:{session_id}` | String | 会话执行锁 | 30s |
| `agent:idempotent:{key}` | String | 幂等去重键 | 10m |
| `agent:cache:intent:{text_hash}` | String | 高频意图缓存 | 30m |

### 32.3 Session Hash 示例

Key: `agent:session:sess_001`

```json
{
  "session_id": "sess_001",
  "user_id": "user_001",
  "channel": "app",
  "status": "waiting_slot",
  "current_intent": "af_apply_return",
  "workflow_id": "wf_001",
  "current_step": "1",
  "risk_level": "medium",
  "last_active_at": "2026-05-09T10:00:00Z"
}
```

### 32.4 Slots Hash 示例

Key: `agent:slots:sess_001`

```json
{
  "order_id": "A123456",
  "reason": "不想要了"
}
```

### 32.5 Pending Slots List 示例

Key: `agent:pending:sess_001`

```json
[
  "order_id",
  "reason"
]
```

### 32.6 Context JSON 示例

Key: `agent:context:sess_001`

```json
{
  "biz_context": {
    "order_status": "pending_shipment"
  },
  "history_summary": "用户发起退货申请",
  "plugin_results": {
    "plugin.order.query": {
      "success": true,
      "status": "pending_shipment"
    }
  }
}
```

### 32.7 Redis 操作建议

- 进入执行前对 `agent:lock:{session_id}` 加分布式锁。
- 每次补槽后同时更新 `session`、`slots`、`pending`。
- 工作流执行完成后，可保留短时缓存用于追问和结果追溯。
- 长会话可异步落盘 PostgreSQL 后缩短 Redis TTL。

## 33. Workflow JSON Schema 设计

### 33.1 设计目标

- 让 LLM 输出严格受控
- 让执行引擎易于解析
- 支持单步、顺序、条件、并行和补槽暂停

### 33.2 Workflow 顶层结构

```json
{
  "workflow_id": "wf_001",
  "workflow_type": "sequence",
  "domain": "customer_service",
  "intent_id": "cs_cancel_order",
  "status": "ready",
  "risk_level": "medium",
  "slots": {
    "order_id": "A123456"
  },
  "missing_slots": [],
  "steps": [],
  "meta": {
    "source": "llm_planner",
    "version": "1.0"
  }
}
```

### 33.3 Step 结构

```json
{
  "step": 1,
  "step_id": "step_001",
  "intent_id": "cs_query_order",
  "plugin_id": "plugin.order.query",
  "action": "query_order",
  "status": "pending",
  "depends_on": [],
  "slots": {
    "order_id": "A123456"
  },
  "on_success": "next",
  "on_failure": "fallback",
  "timeout_ms": 1500
}
```

### 33.4 条件步骤结构

```json
{
  "step": 2,
  "step_id": "step_002",
  "type": "condition",
  "condition": {
    "expr": "context.order_status == 'pending_shipment'"
  },
  "if_true": {
    "intent_id": "cs_cancel_order",
    "plugin_id": "plugin.order.cancel"
  },
  "if_false": {
    "action": "reply",
    "message": "订单已发货，暂时无法取消。"
  }
}
```

### 33.5 补槽暂停结构

```json
{
  "status": "waiting_slot",
  "missing_slots": [
    {
      "slot_name": "order_id",
      "ask_template": "请提供订单号",
      "priority": 1
    }
  ]
}
```

### 33.6 JSON Schema 示例

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AgentWorkflow",
  "type": "object",
  "required": ["workflow_id", "workflow_type", "intent_id", "status", "steps"],
  "properties": {
    "workflow_id": {
      "type": "string"
    },
    "workflow_type": {
      "type": "string",
      "enum": ["single", "sequence", "conditional", "parallel"]
    },
    "domain": {
      "type": "string"
    },
    "intent_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": ["ready", "waiting_slot", "running", "completed", "failed"]
    },
    "risk_level": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    },
    "slots": {
      "type": "object"
    },
    "missing_slots": {
      "type": "array"
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["step", "step_id"],
        "properties": {
          "step": {
            "type": "integer"
          },
          "step_id": {
            "type": "string"
          },
          "intent_id": {
            "type": "string"
          },
          "plugin_id": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "depends_on": {
            "type": "array"
          },
          "slots": {
            "type": "object"
          }
        }
      }
    },
    "meta": {
      "type": "object"
    }
  }
}
```

### 33.7 约束建议

- LLM 只能从候选意图和候选插件中选择，不能自由生成未知标识。
- 所有工作流必须通过 JSON Schema 校验后才能进入执行引擎。
- 高风险动作必须显式输出 `risk_level` 和 `need_confirm`。
- 补槽状态和执行状态必须严格区分，避免重复执行。

## 34. 开工建议

在完成以上设计后，建议按以下顺序正式开工：

1. 初始化后端项目骨架。
2. 实现配置模型、会话模型和 Workflow Schema。
3. 打通 `/chat` 和 `/fill-slots` 两个核心接口。
4. 先接入 mock 插件，完成完整闭环。
5. 再逐步接入真实业务系统和模型服务。

## 35. 多标签 Detector 过渡方案

### 35.1 背景

当前多意图链路已经具备以下结构：

- `clause split` 负责切分明显并列或条件语句
- `clause classifier` 负责对单个子句提供语义补偿
- `multi_intent_detector` 负责在整句粒度提供多标签先验
- `planner fusion` 负责合并 heuristic、classifier 和 detector 的信号

现阶段的问题不在 `planner` 主骨架，而在 detector 的训练方式。当前 detector 基于单标签分类头的 logits 做 sigmoid 解释，只能作为过渡信号，不能代表真正学到的“多标签共现关系”。

### 35.2 迁移目标

本阶段的目标不是重写规划器，而是把 detector 从“推理时解释型多标签”升级成“训练时显式监督的多标签模型”。

迁移后应满足：

- `planner` 继续消费 `detector_prior`，主骨架保持稳定
- detector 使用独立模型目录，不与单标签 classifier 共享分类头
- 训练样本显式表达一个句子对应多个 intent 的监督关系
- 评测指标从单一准确率升级为多标签指标
- 为下一阶段 `NER / token classification` 提供更稳定的候选意图集合

### 35.3 数据格式

保留现有单标签训练数据：

```json
{"text": "打开车窗", "intent_id": "cabin_window_open"}
```

新增多标签训练数据：

```json
{"text": "打开车窗并播放音乐", "intent_ids": ["cabin_window_open", "cabin_play_music"]}
```

约束建议：

- 单标签样本可以直接提升为 `intent_ids` 长度为 1 的多标签样本
- 多标签样本优先覆盖座舱高频并列控制场景
- `__social__` 与 `__out_of_scope__` 不作为多标签共现目标，避免污染业务动作组合学习
- 多标签语料要覆盖口语连接词、顺序词、弱连接和省略表达

### 35.4 模型与训练

建议为 detector 使用独立训练脚本和独立输出目录：

- 训练脚本：`scripts/train_local_bert_multi_intent.py`
- 评测脚本：`scripts/eval_local_bert_multi_intent.py`
- 模型目录：`models/local_bert_multi_intent/`

训练方式：

- 底座继续使用本地 MacBERT
- 任务类型设置为 `multi_label_classification`
- 标签为多热向量，损失函数为 `BCEWithLogitsLoss`
- 输出为每个意图的独立概率，不再依赖单标签 softmax 头的副产物

### 35.5 运行时接入

运行时只替换 detector 的模型来源和解释方式，不改 `planner` 主逻辑。

接入原则：

- `classifier` 继续服务单子句语义分类
- `multi_intent_detector` 独立加载多标签模型
- detector 输出仍然是 `candidates -> detector_prior`
- detector 默认屏蔽 `__social__` 和 `__out_of_scope__`
- 当 detector 不可用时，planner 仍可退化到 `clause split + clause classifier + heuristic`

### 35.6 与 NER 的衔接

在真正多标签 detector 稳定前，不建议直接推进 `NER / token classification` 作为主增量。

原因：

- NER 擅长抽取边界，不擅长先决定整句有几个意图
- 如果上游 detector 仍是假多标签，NER 很容易围绕错误意图做精细抽取
- 先把多标签 detector 训练扎实，可以让 NER 在“候选意图集合已收敛”的前提下工作

因此推荐顺序固定为：

1. 真正多标签 detector
2. detector 线上评测和阈值稳定
3. NER / token classification

### 35.7 本阶段验收标准

本阶段完成后至少应满足：

- detector 支持独立训练、独立加载、独立评测
- 对典型并列座舱指令，`recall@k` 和 `micro_f1` 明显优于现有 sigmoid 解释方案
- `planner` 主骨架无需改写，现有 fusion 逻辑保持兼容
- 后续引入 NER 时，只需增加边界抽取模块，不必再次调整 detector 接口

## 36. Joint NLU 升级方案

### 36.1 目标

本阶段不再继续扩旧的 heuristic 槽位提取逻辑，而是把本地 NLU 快链路升级成真正的 `Joint Intent + Slot` 联合识别。

升级目标：

- 用一个共享编码器同时完成意图识别和槽位抽取
- 替换当前 `HeuristicSlotExtractor` 的主路径职责
- 保留 `planner / workflow / session / response policy` 主骨架
- 多意图整句仍走 `clause split + multi-intent detector + planner`
- 单句或单 clause 的语义理解改为 `JointBERT`

### 36.2 为什么不直接推倒整条链

当前系统已经有稳定的上层编排能力：

- `fusion` 负责 `execute / clarify / reject / route_to_cloud`
- `planner` 负责 `sequence / conditional workflow`
- `workflow executor` 负责多步执行、条件判断、确认和补槽

这些能力并不是 `JointBERT` 能替代的。

因此本次升级只替换本地理解层，不重写上层编排层。

### 36.3 新架构边界

升级后的本地链路定义为：

```text
text
-> rewrite
-> Joint NLU
   - intent head
   - slot tagging head
-> fusion / planner
-> workflow executor
```

新的职责划分：

- `JointBERT`：单句或单 clause 的 intent + slot
- `multi-intent detector`：整句多标签先验
- `planner`：多意图、条件句、多步骤 workflow
- `workflow executor`：补槽、确认、执行、汇总

### 36.4 Joint NLU 数据格式

新增联合训练数据，采用 span 标注格式：

```json
{
  "text": "把空调调到22度",
  "intent_id": "cabin_set_ac",
  "slots": [
    {"slot_name": "temperature", "value": "22度", "start": 6, "end": 9}
  ]
}
```

说明：

- 单条样本只标注一个主意图
- 多意图句在训练阶段优先拆成 clause 级样本
- 无槽位意图的 `slots` 为空数组
- 运行时将 span 转换为 token-level BIO 标签

### 36.5 模型结构

采用共享编码器的双头结构：

- 编码器：`MacBERT`
- 意图头：句级单标签分类
- 槽位头：token classification，输出 BIO 标签

第一版先不引入复杂的 slot-gate，先保证：

- 共享编码器
- 联合训练
- 意图与槽位共享语义表征

在当前项目里，这已经比“句分类 + 规则抽槽”前进一步。

### 36.6 接入方式

运行时新增 `JointNLU` 服务，供两处复用：

1. `classifier backend = joint_bert`
   - 用联合模型的 intent head 输出意图分数
2. `slot_extractor backend = joint_bert`
   - 用联合模型的 slot head 输出槽位

要求：

- 两个 backend 共享同一个模型实例，避免重复冷启动
- 对同一文本允许做短时预测缓存，避免一次请求重复前向
- 若联合模型不可用，直接报错或显式 fallback，不继续隐式走旧 heuristic 逻辑

### 36.7 与多意图链路的关系

`JointBERT` 不直接负责整句多意图 workflow 规划。

多意图流程保持：

1. `multi-intent detector` 对整句给出多标签先验
2. `planner` 进行 clause split
3. 每个 clause 用 `Joint NLU` 做 intent + slot
4. `planner` 汇总 clause 结果为 workflow

这样做的原因：

- 经典 JointBERT 更适合单句单意图
- 当前系统已经有成熟的 clause-level planner 骨架
- 直接让一个单模型接管整句多步骤规划，风险更高

### 36.8 替换原则

本次升级的明确原则：

- 默认主链路不再依赖 `HeuristicSlotExtractor`
- planner 内部的 clause slots 也优先改为 `Joint NLU`
- 原 heuristic 抽槽只保留为测试对照或应急兜底，不再作为主路径

### 36.9 验收标准

升级完成后至少满足：

- 单步任务的槽位抽取来自 `Joint NLU`
- 缺槽位逻辑、确认逻辑、多步 workflow 逻辑保持兼容
- `router` 和 `planner` 都能读取联合模型输出
- 本地常见控制句的槽位抽取精度高于旧 heuristic
- 冷启动通过 warmup 控制，首轮推理不发生首次懒加载抖动
