---
feature_id: "AISVC"
title: "Python AI 中台需求规范"
status: "in-progress"
version: "0.8.0"
active_version: "0.7.0-0.8.0"
version_history:
  - version: "0.8.0"
    ac_range: "AC-AISVC-111~AC-AISVC-125"
    description: "意图识别混合路由优化"
    spec_path: "spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/"
  - version: "0.7.0"
    ac_range: "AC-AISVC-91~AC-AISVC-110"
    description: "测试与监控系统"
  - version: "0.6.0"
    ac_range: "AC-AISVC-51~AC-AISVC-90"
    description: "智能客服增强"
owners:
  - "product"
  - "backend"
last_updated: "2026-03-08"
source:
  type: "conversation"
  ref: ""
---

# Python AI 中台（ai-service）需求规范（AISVC）

## 1. 背景与目标

### 1.1 背景
主框架（Java）需要通过统一的 HTTP 接口调用 Python AI 中台完成对话回复生成，并支持：
- 多租户隔离（tenant 一套知识库/索引、会话与元数据隔离）。
- 流式输出（Java → Python 主通道采用 SSE）。
- RAG 检索增强（检索命中/不中均有明确兜底逻辑与置信度策略）。
- AI 侧上下文与记忆管理（Java 侧仅传 `sessionId + metadata`，`history` 可选）。

### 1.2 目标
- 提供稳定的 Provider API（至少对齐 `java/openapi.deps.yaml` 中 `/ai/chat` 与 `/ai/health` 的契约需求）。
- 在 MVP 期实现可用的对话能力 + 可控的上下文/记忆 + 基础 RAG。
- 预留 GraphRAG/HybridRAG 扩展口（非 MVP 必须项，但接口与模块边界需支持可插拔）。

### 1.3 非目标（Out of Scope）
- 主框架侧的降级策略与超时处理的业务编排实现（由 Java 侧完成；AI 中台只需返回明确错误语义，便于上游处理）。
- 知识图谱构建与 GraphRAG/HybridRAG 的具体算法实现（仅预留扩展点）。
- 渠道接入、用户身份体系、工单/坐席系统等业务系统实现。

## 2. 模块边界（Scope）

### 2.1 覆盖
- 对话生成服务：支持 non-streaming JSON 与 streaming SSE。
- 多租户隔离：知识库（检索范围）、会话历史、元数据读写隔离。
- 上下文管理：基于 `sessionId` 的会话持久化与加载；支持可选 `history`。
- 基础 RAG：检索、拼装上下文、生成与置信度/转人工建议。

### 2.2 不覆盖
- 业务侧路由、工单流转与最终转人工执行。
- Java 侧调用超时与降级策略的实现细节。

## 3. 依赖盘点（Dependencies）

### 3.1 调用方依赖（Consumer）
- Java 主框架调用 AI 中台：依赖契约见 `java/openapi.deps.yaml`。

### 3.2 AI 中台内部可能依赖（实现阶段确定，规范阶段仅声明）
- 向量库：Qdrant 或 Milvus（二选一）。
- 会话存储：PostgreSQL 或 MySQL。
- 缓存（可选）：Redis。
- LLM 提供方（可插拔）：OpenAI / 兼容 OpenAI 的网关 / 本地模型。

## 4. 术语与约定（Definitions）
- `tenantId`：租户标识，用于隔离知识库、会话与元数据。必须贯穿请求与存储分区。
- `sessionId`：会话标识，用于定位同一会话下的对话记忆。
- `history`：调用方提供的历史消息列表（可选）。AI 中台可结合 AI 侧持久化会话一起构建上下文。
- SSE：Server-Sent Events，HTTP 单向流式推送（`text/event-stream`）。

## 5. 用户故事（User Stories）
- [US-AISVC-01] 作为 Java 主框架，我希望通过统一 HTTP 接口调用 AI 中台生成回复，以便对外提供智能对话能力。
- [US-AISVC-02] 作为平台运营者，我希望不同租户的数据严格隔离，以便满足多租户安全与合规要求。
- [US-AISVC-03] 作为终端用户，我希望 AI 回复可以流式呈现，以便更快看到内容并提升交互体验。
- [US-AISVC-04] 作为终端用户，我希望 AI 能结合知识库检索回答问题，并在检索不足时有稳健兜底，以便减少"胡编"。
- [US-AISVC-05] 作为系统维护者，我希望 AI 中台可被健康检查探测，以便稳定运维。

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

> 说明：
> - Java 侧既有验收标准以 `AC-MCA-*` 表示（来自依赖契约描述）；本模块新增以 `AC-AISVC-*` 表示。
> - 本模块的 Provider API 必须对齐 `java/openapi.deps.yaml` 中的 `/ai/chat` 与 `/ai/health` 约束。

### 6.1 对齐 Java 契约：/ai/chat（HTTP POST + Response Schema）

- [AC-AISVC-01] WHEN Java 主框架通过 HTTP `POST /ai/chat` 发送包含 `sessionId`、`currentMessage`、`channelType` 的请求 THEN AI 中台 SHALL 返回 200 并给出业务回复结果（兼容 non-streaming JSON）。
  - 对齐：AC-MCA-04（HTTP POST 调用）。

- [AC-AISVC-02] WHEN AI 中台成功生成回复 THEN 响应体（non-streaming） SHALL 至少包含 `reply`、`confidence`、`shouldTransfer` 字段，且字段类型与语义满足 Java 依赖契约。
  - 对齐：AC-MCA-05（Response Schema）。

- [AC-AISVC-03] WHEN 请求参数缺失或格式非法 THEN AI 中台 SHALL 返回 400 且返回结构化错误（至少包含 `code` 与 `message`）。

- [AC-AISVC-04] WHEN AI 中台发生未预期内部错误 THEN AI 中台 SHALL 返回 500 且返回结构化错误（至少包含 `code` 与 `message`）。

- [AC-AISVC-05] WHEN AI 中台暂不可用（例如依赖 LLM/向量库不可用导致无法服务） THEN AI 中台 SHALL 返回 503 且返回结构化错误（至少包含 `code` 与 `message`）。

### 6.2 SSE 流式输出（主通道）

- [AC-AISVC-06] WHEN 调用方以流式方式调用 `POST /ai/chat`（例如通过 `Accept: text/event-stream` 或 `stream=true` 参数） THEN AI 中台 SHALL 以 SSE 推送事件流，直到生成结束或发生错误。

- [AC-AISVC-07] WHEN AI 中台产生可增量输出的回复内容 THEN AI 中台 SHALL 多次发送 `event: message` 事件，每次携带本次增量文本（delta），以便调用方逐步渲染。
  - 返回时机：模型生成过程中持续发送。

- [AC-AISVC-08] WHEN AI 中台完成本次生成（正常结束） THEN AI 中台 SHALL 发送一次 `event: final` 事件，携带最终结构化结果，且其字段集合至少包含 `reply`、`confidence`、`shouldTransfer`（与 non-streaming 响应同构）。
  - 返回时机：生成完成后立即发送，并随后关闭 SSE 连接（或发送结束标记后关闭）。

- [AC-AISVC-09] WHEN 处理过程中发生可判定错误（参数错误/内部错误/依赖不可用等） THEN AI 中台 SHALL 发送 `event: error` 事件，携带结构化错误（至少 `code`、`message`，可含 `details`），并终止事件流。
  - 返回时机：错误发生后立即发送，并关闭连接。

### 6.3 多租户隔离（tenantId）

- [AC-AISVC-10] WHEN 请求的 `metadata` 中包含 `tenantId` THEN AI 中台 SHALL 将 `tenantId` 作为一级隔离维度贯穿：知识库检索范围、会话读写、元数据读写均必须在该 `tenantId` 分区内进行。

- [AC-AISVC-11] WHEN 不同 `tenantId` 的请求使用相同 `sessionId` THEN AI 中台 SHALL 视为两个互相隔离的会话空间，禁止跨租户读取/写入对话历史与记忆。

- [AC-AISVC-12] WHEN 请求缺失 `tenantId`（或 `tenantId` 非法/空） THEN AI 中台 SHALL 按契约返回 400（参数错误），并在错误中明确缺失字段。

### 6.4 上下文管理（sessionId 持久化；history 可选）

- [AC-AISVC-13] WHEN AI 中台收到 `sessionId` THEN AI 中台 SHALL 在服务端持久化该会话的对话记录与必要的摘要/记忆，并可在后续同一 `tenantId + sessionId` 请求中加载用于上下文构建。

- [AC-AISVC-14] WHEN Java 调用方未提供 `history` THEN AI 中台 SHALL 仅基于服务端持久化会话历史（若存在）与本次 `currentMessage` 构建上下文完成生成。

- [AC-AISVC-15] WHEN Java 调用方提供了 `history` THEN AI 中台 SHALL 将其作为"外部补充历史"参与上下文构建，并以确定性的去重/合并规则避免与服务端历史冲突（规则在 design.md 明确）。

### 6.5 RAG 检索（命中/不中的兜底与置信度阈值）

- [AC-AISVC-16] WHEN 请求触发知识库检索（RAG） THEN AI 中台 SHALL 在 `tenantId` 对应的知识库范围内进行检索，并将检索结果用于回答生成。

- [AC-AISVC-17] WHEN 检索结果为空或低质量（定义为：未达到最小命中文档数或相关度阈值，阈值在配置中可调整） THEN AI 中台 SHALL 执行兜底逻辑：
  1) 生成"基于通用知识/无法从知识库确认"的稳健回复（避免编造具体事实），并
  2) 下调 `confidence`，并
  3) 视阈值策略可将 `shouldTransfer=true`（例如用户强诉求或关键信息缺失）。

- [AC-AISVC-18] WHEN 生成完成后计算得到的 `confidence` 低于阈值 `T_low` THEN AI 中台 SHALL 将 `shouldTransfer` 置为 `true` 或提供 `transferReason`，以便上游决定是否转人工。
  - 说明：阈值 `T_low` 为可配置；MVP 可先采用经验值并在 design.md 中定义默认值与可配置项。

- [AC-AISVC-19] WHEN 检索命中且证据充分（达到相关度与覆盖度阈值） THEN AI 中台 SHALL 提升 `confidence`（相对兜底场景）并优先基于检索证据回答；如回答包含事实性结论，应以检索证据为主。

### 6.6 健康检查

- [AC-AISVC-20] WHEN 调用方请求 `GET /ai/health` THEN AI 中台 SHALL 在健康时返回 200 且包含可解析的 `status` 字段；在不健康时返回 503。

## 7. 需求追踪映射（Traceability）

> 说明：本表用于把验收标准映射到 Provider 端点（以及未来的 operationId）。
> 在下一步生成 `openapi.provider.yaml` 时，应保证：
> - `/ai/chat` 的 non-streaming 响应 schema 对齐 Java deps（reply/confidence/shouldTransfer）。
> - streaming SSE 的事件模型在 provider 契约中明确（可作为 `text/event-stream` 响应体描述）。

| AC ID | 对齐外部 AC | Endpoint | 方法 | operationId（拟） | 备注 |
|------|-------------|----------|------|------------------|------|
| AC-AISVC-01 | AC-MCA-04 | /ai/chat | POST | generateReply | HTTP POST 调用对齐 Java deps |
| AC-AISVC-02 | AC-MCA-05 | /ai/chat | POST | generateReply | non-streaming 响应字段对齐（reply/confidence/shouldTransfer） |
| AC-AISVC-03 |  | /ai/chat | POST | generateReply | 400 参数错误 + ErrorResponse |
| AC-AISVC-04 |  | /ai/chat | POST | generateReply | 500 内部错误 |
| AC-AISVC-05 |  | /ai/chat | POST | generateReply | 503 不可用 |
| AC-AISVC-06 |  | /ai/chat | POST | generateReplyStream | SSE 入口（同路径不同协商方式） |
| AC-AISVC-07 |  | /ai/chat | POST | generateReplyStream | event: message |
| AC-AISVC-08 |  | /ai/chat | POST | generateReplyStream | event: final |
| AC-AISVC-09 |  | /ai/chat | POST | generateReplyStream | event: error |
| AC-AISVC-10 |  | /ai/chat | POST | generateReply | tenantId 贯穿隔离 |
| AC-AISVC-11 |  | /ai/chat | POST | generateReply | tenantId + sessionId 组合隔离 |
| AC-AISVC-12 |  | /ai/chat | POST | generateReply | 缺 tenantId 返回 400（本模块约束） |
| AC-AISVC-13 |  | /ai/chat | POST | generateReply | session 持久化 |
| AC-AISVC-14 |  | /ai/chat | POST | generateReply | history 可选 |
| AC-AISVC-15 |  | /ai/chat | POST | generateReply | history 合并规则（design 明确） |
| AC-AISVC-16 |  | /ai/chat | POST | generateReply | RAG 检索 |
| AC-AISVC-17 |  | /ai/chat | POST | generateReply | 检索不中兜底 + 下调置信度 |
| AC-AISVC-18 |  | /ai/chat | POST | generateReply | 置信度阈值触发 shouldTransfer |
| AC-AISVC-19 |  | /ai/chat | POST | generateReply | 证据充分提升 confidence |
| AC-AISVC-20 |  | /ai/health | GET | healthCheck | 健康检查对齐 deps |

## 8. 约束与待澄清（Open Questions）
- `tenantId` 的承载方式：本规范要求在请求 `metadata.tenantId` 中提供；后续 `openapi.provider.yaml` 需将其提升为明确字段（是否提升为顶层字段需评审）。
- streaming 协商方式：`Accept: text/event-stream` vs `stream=true` 参数；下一阶段在 provider OpenAPI 中确定主方案。
- `confidence` 计算方式与默认阈值：MVP 先给默认值与可配置项，后续可基于日志/评测迭代。
- `shouldTransfer` 的策略：AI 中台提供"建议"，最终转人工编排由上游业务实现。

## 9. 迭代需求：前后端联调真实对接（v0.2.0）

> 说明：本节为 v0.2.0 迭代新增，用于支持 ai-service-admin 前端与后端的真实对接，替换原有 Mock 实现。

### 9.1 知识库管理真实对接

- [AC-AISVC-21] WHEN 前端通过 `POST /admin/kb/documents` 上传文档 THEN AI 中台 SHALL 将文档存储到本地文件系统，创建 Document 实体记录，并返回 `jobId` 用于追踪索引任务。

- [AC-AISVC-22] WHEN 文档上传成功后 THEN AI 中台 SHALL 异步启动索引任务，将文档内容分块并向量化存储到 Qdrant（按 tenantId 隔离 Collection）。

- [AC-AISVC-23] WHEN 前端通过 `GET /admin/kb/documents` 查询文档列表 THEN AI 中台 SHALL 从 PostgreSQL 数据库查询 Document 实体，支持按 kbId、status 过滤和分页。

- [AC-AISVC-24] WHEN 前端通过 `GET /admin/kb/index/jobs/{jobId}` 查询索引任务状态 THEN AI 中台 SHALL 返回任务状态（pending/processing/completed/failed）、进度百分比及错误信息。

### 9.2 RAG 实验室真实对接

- [AC-AISVC-25] WHEN 前端通过 `POST /admin/rag/experiments/run` 触发 RAG 实验 THEN AI 中台 SHALL 调用 VectorRetriever 进行真实向量检索，返回检索结果列表（content、score、source）及最终拼接的 Prompt。

- [AC-AISVC-26] WHEN RAG 实验检索失败（如 Qdrant 不可用）THEN AI 中台 SHALL 返回 fallback 结果而非抛出异常，确保前端可正常展示。

### 9.3 会话监控真实对接

- [AC-AISVC-27] WHEN 前端通过 `GET /admin/sessions` 查询会话列表 THEN AI 中台 SHALL 从 PostgreSQL 数据库查询 ChatSession 实体，支持按 status、时间范围过滤和分页，并关联统计消息数量。

- [AC-AISVC-28] WHEN 前端通过 `GET /admin/sessions/{sessionId}` 查询会话详情 THEN AI 中台 SHALL 返回该会话的所有消息记录及追踪信息（trace）。

### 9.4 需求追踪映射（迭代追加）

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-AISVC-21 | /admin/kb/documents | POST | uploadDocument | 文档上传真实存储 |
| AC-AISVC-22 | /admin/kb/documents | POST | uploadDocument | 异步索引任务 |
| AC-AISVC-23 | /admin/kb/documents | GET | listDocuments | 文档列表真实查询 |
| AC-AISVC-24 | /admin/kb/index/jobs/{jobId} | GET | getIndexJob | 索引任务状态查询 |
| AC-AISVC-25 | /admin/rag/experiments/run | POST | runRagExperiment | RAG 真实检索 |
| AC-AISVC-26 | /admin/rag/experiments/run | POST | runRagExperiment | 检索失败 fallback |
| AC-AISVC-27 | /admin/sessions | GET | listSessions | 会话列表真实查询 |
| AC-AISVC-28 | /admin/sessions/{sessionId} | GET | getSessionDetail | 会话详情真实查询 |

## 10. 迭代需求：嵌入模型可插拔与文档解析支持（v0.3.0）

> 说明：本节为 v0.3.0 迭代新增，用于支持嵌入模型的灵活配置与多格式文档解析。

### 10.1 嵌入模型可插拔设计

- [AC-AISVC-29] WHEN 系统需要生成文本嵌入向量 THEN 系统 SHALL 通过统一的 `EmbeddingProvider` 抽象接口调用，支持运行时动态切换不同的嵌入模型实现。

- [AC-AISVC-30] WHEN 管理员通过配置或界面指定嵌入模型类型（如 `ollama`、`openai`、`local`）THEN 系统 SHALL 自动加载对应的 EmbeddingProvider 实现，无需修改代码。

- [AC-AISVC-31] WHEN 管理员通过界面配置嵌入模型参数（如 API 地址、模型名称、维度等）THEN 系统 SHALL 动态应用配置，支持热更新（无需重启服务）。

- [AC-AISVC-32] WHEN 嵌入模型调用失败 THEN 系统 SHALL 返回明确的错误信息，并支持配置 fallback 策略（如降级到备用模型或返回错误）。

### 10.2 文档解析服务

- [AC-AISVC-33] WHEN 用户上传 PDF 格式文档 THEN 系统 SHALL 使用文档解析服务提取纯文本内容，用于后续分块和向量化。

- [AC-AISVC-34] WHEN 用户上传 Word（.docx）格式文档 THEN 系统 SHALL 使用文档解析服务提取纯文本内容，保留段落结构。

- [AC-AISVC-35] WHEN 用户上传 Excel（.xlsx）格式文档 THEN 系统 SHALL 使用文档解析服务提取表格内容，转换为结构化文本格式。

- [AC-AISVC-36] WHEN 文档解析失败（如文件损坏、格式不支持）THEN 系统 SHALL 返回明确的错误信息，并标记文档索引任务为 failed 状态。

- [AC-AISVC-37] WHEN 用户上传不支持的文件格式 THEN 系统 SHALL 在上传阶段拒绝并返回 400 错误，提示支持的格式列表。

### 10.3 嵌入模型管理 API

- [AC-AISVC-38] WHEN 前端通过 `GET /admin/embedding/providers` 查询可用的嵌入模型提供者 THEN 系统 SHALL 返回所有已注册的提供者列表及其配置参数定义。

- [AC-AISVC-39] WHEN 前端通过 `GET /admin/embedding/config` 查询当前嵌入模型配置 THEN 系统 SHALL 返回当前激活的提供者及其参数配置。

- [AC-AISVC-40] WHEN 前端通过 `PUT /admin/embedding/config` 更新嵌入模型配置 THEN 系统 SHALL 验证配置有效性，更新配置并返回成功状态。

- [AC-AISVC-41] WHEN 前端通过 `POST /admin/embedding/test` 测试嵌入模型连接 THEN 系统 SHALL 调用嵌入模型生成测试向量，返回连接状态和向量维度信息。

### 10.4 需求追踪映射（迭代追加）

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-AISVC-29 | - | - | - | EmbeddingProvider 抽象接口设计 |
| AC-AISVC-30 | - | - | - | 工厂模式动态加载 |
| AC-AISVC-31 | /admin/embedding/config | PUT | updateEmbeddingConfig | 配置热更新 |
| AC-AISVC-32 | - | - | - | 错误处理与 fallback |
| AC-AISVC-33 | /admin/kb/documents | POST | uploadDocument | PDF 解析支持 |
| AC-AISVC-34 | /admin/kb/documents | POST | uploadDocument | Word 解析支持 |
| AC-AISVC-35 | /admin/kb/documents | POST | uploadDocument | Excel 解析支持 |
| AC-AISVC-36 | /admin/kb/documents | POST | uploadDocument | 解析失败处理 |
| AC-AISVC-37 | /admin/kb/documents | POST | uploadDocument | 格式校验 |
| AC-AISVC-38 | /admin/embedding/providers | GET | listEmbeddingProviders | 提供者列表 |
| AC-AISVC-39 | /admin/embedding/config | GET | getEmbeddingConfig | 当前配置查询 |
| AC-AISVC-40 | /admin/embedding/config | PUT | updateEmbeddingConfig | 配置更新 |
| AC-AISVC-41 | /admin/embedding/test | POST | testEmbedding | 连接测试 |

---

## 11. 迭代需求：LLM 模型配置与 RAG 调试输出（v0.4.0）

> 说明：本节为 v0.4.0 迭代新增，用于支持 LLM 模型的界面配置及 RAG 实验室的 AI 输出调试。

### 11.1 LLM 模型配置管理

- [AC-AISVC-42] WHEN 前端通过 `GET /admin/llm/providers` 获取 LLM 提供者列表 THEN 系统 SHALL 返回所有支持的 LLM 提供者及其配置参数定义。

- [AC-AISVC-43] WHEN 前端通过 `GET /admin/llm/config` 获取当前 LLM 配置 THEN 系统 SHALL 返回当前激活的 LLM 提供者及其配置参数（敏感字段脱敏）。

- [AC-AISVC-44] WHEN 前端通过 `PUT /admin/llm/config` 更新 LLM 配置 THEN 系统 SHALL 验证配置有效性，更新配置并立即生效。

- [AC-AISVC-45] WHEN 前端通过 `POST /admin/llm/test` 测试 LLM 连接 THEN 系统 SHALL 调用 LLM 生成测试回复，返回响应内容、Token 消耗和延迟统计。

- [AC-AISVC-46] WHEN LLM 连接测试失败 THEN 系统 SHALL 返回详细错误信息，帮助用户排查配置问题。

### 11.2 RAG 实验室 AI 输出增强

- [AC-AISVC-47] WHEN 前端通过 `POST /admin/rag/experiments/run` 运行 RAG 实验 THEN 系统 SHALL 返回检索结果、最终 Prompt 和 AI 回复。

- [AC-AISVC-48] WHEN 前端通过 `POST /admin/rag/experiments/stream` 运行 RAG 实验 THEN 系统 SHALL 以 SSE 流式输出 AI 回复。

- [AC-AISVC-49] WHEN RAG 实验生成 AI 回复 THEN 系统 SHALL 返回 Token 消耗统计和响应耗时。

- [AC-AISVC-50] WHEN RAG 实验请求指定 `llm_provider` THEN 系统 SHALL 使用指定的 LLM 提供者生成回复。

### 11.3 追踪映射（v0.4.0 迭代）

| AC ID | Endpoint | 方法 | Operation | 描述 |
|-------|----------|------|-----------|------|
| AC-AISVC-42 | /admin/llm/providers | GET | listLLMProviders | LLM 提供者列表 |
| AC-AISVC-43 | /admin/llm/config | GET | getLLMConfig | 当前 LLM 配置查询 |
| AC-AISVC-44 | /admin/llm/config | PUT | updateLLMConfig | LLM 配置更新 |
| AC-AISVC-45 | /admin/llm/test | POST | testLLM | LLM 连接测试 |
| AC-AISVC-46 | /admin/llm/test | POST | testLLM | LLM 测试失败处理 |
| AC-AISVC-47 | /admin/rag/experiments/run | POST | runRagExperiment | RAG 实验含 AI 输出 |
| AC-AISVC-48 | /admin/rag/experiments/stream | POST | runRagExperimentStream | RAG 实验流式输出 |
| AC-AISVC-49 | /admin/rag/experiments/run | POST | runRagExperiment | Token 统计 |
| AC-AISVC-50 | /admin/rag/experiments/run | POST | runRagExperiment | 指定 LLM 提供者 |

---

## 12. 迭代需求：智能客服增强 — Prompt 模板化 + 多知识库 + 规则引擎 + 输出护栏（v0.6.0）

> 说明：本节为 v0.6.0 迭代新增。目标是将 AI 中台从"单知识库 + 硬编码 Prompt"升级为可配置的拟人客服中台，支持：
> - Prompt 模板数据库驱动（按租户配置人设、语气、禁忌词）
> - 多知识库分类管理与智能路由
> - 意图识别 + 话术流程引擎（固定步骤引导）
> - 输出护栏（禁词检测、敏感内容过滤）
> - 智能 RAG 增强（Query 改写、上下文感知检索、分层知识优先级）

### 12.1 Prompt 模板化（数据库驱动）

- [AC-AISVC-51] WHEN 系统启动或租户首次请求 THEN 系统 SHALL 从数据库加载该租户的 Prompt 模板配置（人设名称、语气风格、角色描述、系统指令），替代硬编码的 `SYSTEM_PROMPT`。

- [AC-AISVC-52] WHEN 管理员通过 `POST /admin/prompt-templates` 创建 Prompt 模板 THEN 系统 SHALL 存储模板内容（含模板名称、场景标签、系统指令、变量占位符列表），并返回模板 ID。

- [AC-AISVC-53] WHEN 管理员通过 `PUT /admin/prompt-templates/{tplId}` 更新模板 THEN 系统 SHALL 创建新版本（版本号自增），保留历史版本，且同一时间仅一个版本为"已发布"状态。

- [AC-AISVC-54] WHEN 管理员通过 `POST /admin/prompt-templates/{tplId}/publish` 发布指定版本 THEN 系统 SHALL 将该版本标记为"已发布"，旧版本自动降级为"历史版本"，发布后立即生效（热更新）。

- [AC-AISVC-55] WHEN 管理员通过 `POST /admin/prompt-templates/{tplId}/rollback` 回滚 THEN 系统 SHALL 将指定历史版本重新标记为"已发布"。

- [AC-AISVC-56] WHEN Orchestrator 构建 Prompt 时 THEN 系统 SHALL 从已发布的模板中读取系统指令，并替换内置变量（如 `{{persona_name}}`、`{{current_time}}`、`{{channel_type}}`），最终拼接为 LLM 的 system message。

- [AC-AISVC-57] WHEN 管理员通过 `GET /admin/prompt-templates` 查询模板列表 THEN 系统 SHALL 返回该租户下所有模板（含场景标签、当前发布版本号、更新时间），支持按场景筛选。

- [AC-AISVC-58] WHEN 管理员通过 `GET /admin/prompt-templates/{tplId}` 查询模板详情 THEN 系统 SHALL 返回模板所有版本列表及当前发布版本的完整内容。

### 12.2 多知识库分类管理

- [AC-AISVC-59] WHEN 管理员通过 `POST /admin/kb/knowledge-bases` 创建知识库 THEN 系统 SHALL 创建独立的知识库实体，包含名称、类型（`product` 产品知识 / `faq` 常见问题 / `script` 话术模板 / `policy` 政策规范 / `general` 通用）、描述、优先级权重，并在 Qdrant 中初始化对应的 Collection。

- [AC-AISVC-60] WHEN 管理员通过 `GET /admin/kb/knowledge-bases` 查询知识库列表 THEN 系统 SHALL 返回该租户下所有知识库（含文档数量、索引状态统计、类型、优先级）。

- [AC-AISVC-61] WHEN 管理员通过 `PUT /admin/kb/knowledge-bases/{kbId}` 更新知识库 THEN 系统 SHALL 支持修改名称、描述、类型、优先级权重、启用/禁用状态。

- [AC-AISVC-62] WHEN 管理员通过 `DELETE /admin/kb/knowledge-bases/{kbId}` 删除知识库 THEN 系统 SHALL 删除知识库实体、关联文档记录，并清理 Qdrant 中对应的 Collection 数据。

- [AC-AISVC-63] WHEN 文档上传时指定 `kbId` THEN 系统 SHALL 将文档索引到指定知识库对应的 Qdrant Collection（替代原有的 `kb_default` 硬编码）。

- [AC-AISVC-64] WHEN Orchestrator 执行 RAG 检索 THEN 系统 SHALL 根据意图路由结果选择目标知识库集合进行检索，而非全库搜索。若未命中意图规则，则按知识库优先级权重依次检索。

### 12.3 意图识别与规则引擎

- [AC-AISVC-65] WHEN 管理员通过 `POST /admin/intent-rules` 创建意图规则 THEN 系统 SHALL 存储规则（含意图名称、关键词列表、正则模式列表、优先级、响应类型 `flow` / `rag` / `fixed` / `transfer`、关联的知识库 ID 列表或话术流程 ID 或固定回复内容）。

- [AC-AISVC-66] WHEN 管理员通过 `GET /admin/intent-rules` 查询意图规则列表 THEN 系统 SHALL 返回该租户下所有规则（含命中统计、启用状态），支持按意图名称和响应类型筛选。

- [AC-AISVC-67] WHEN 管理员通过 `PUT /admin/intent-rules/{ruleId}` 更新规则 THEN 系统 SHALL 支持修改关键词、正则、优先级、响应类型、关联资源，更新后立即生效。

- [AC-AISVC-68] WHEN 管理员通过 `DELETE /admin/intent-rules/{ruleId}` 删除规则 THEN 系统 SHALL 删除规则并立即生效。

- [AC-AISVC-69] WHEN 用户消息进入 Orchestrator THEN 系统 SHALL 在 RAG 检索之前执行意图识别：按优先级遍历规则，依次进行关键词匹配和正则匹配。命中规则后根据 `response_type` 路由：
  - `fixed`：直接返回固定回复，跳过 LLM 调用。
  - `flow`：进入话术流程引擎，按步骤推进。
  - `rag`：使用规则关联的知识库集合进行定向检索。
  - `transfer`：直接设置 `shouldTransfer=true` 并返回转人工话术。

- [AC-AISVC-70] WHEN 所有规则均未命中 THEN 系统 SHALL 回退到默认 RAG pipeline（按知识库优先级检索），行为与现有逻辑一致。

### 12.4 话术流程引擎（状态机）

- [AC-AISVC-71] WHEN 管理员通过 `POST /admin/script-flows` 创建话术流程 THEN 系统 SHALL 存储流程定义（含流程名称、触发条件描述、步骤列表），每个步骤包含：步骤序号、话术内容（支持变量占位符）、等待用户输入标志、超时秒数、超时后动作（重复/跳过/转人工）、下一步条件（关键词匹配或无条件推进）。

- [AC-AISVC-72] WHEN 管理员通过 `GET /admin/script-flows` 查询流程列表 THEN 系统 SHALL 返回该租户下所有流程（含步骤数、启用状态、关联意图规则数）。

- [AC-AISVC-73] WHEN 管理员通过 `PUT /admin/script-flows/{flowId}` 更新流程 THEN 系统 SHALL 支持修改流程步骤、触发条件、启用/禁用状态。

- [AC-AISVC-74] WHEN 意图识别命中 `flow` 类型规则 THEN 系统 SHALL 为当前会话创建流程执行实例（关联 `session_id` + `flow_id`），从第一步开始执行，返回第一步的话术内容。

- [AC-AISVC-75] WHEN 会话存在进行中的流程实例 THEN 系统 SHALL 优先处理流程逻辑：根据用户输入匹配当前步骤的下一步条件，推进到下一步骤并返回对应话术。若用户输入不匹配任何条件，则重复当前步骤话术或按配置处理。

- [AC-AISVC-76] WHEN 流程执行到最后一步或用户触发退出条件 THEN 系统 SHALL 标记流程实例为"已完成"，后续消息恢复正常 RAG pipeline 处理。

- [AC-AISVC-77] WHEN 流程步骤超时（用户在指定时间内未回复） THEN 系统 SHALL 按步骤配置执行超时动作（重复当前话术 / 跳到下一步 / 转人工）。注：超时检测由调用方（Java 侧）触发，AI 中台提供查询流程状态的接口。

### 12.5 输出护栏（禁词检测与内容过滤）

- [AC-AISVC-78] WHEN 管理员通过 `POST /admin/guardrails/forbidden-words` 添加禁词 THEN 系统 SHALL 存储禁词（含词语、类别 `competitor` / `sensitive` / `political` / `custom`、替换策略 `mask` 星号替换 / `replace` 替换为指定文本 / `block` 拦截整条回复并返回兜底话术）。

- [AC-AISVC-79] WHEN 管理员通过 `GET /admin/guardrails/forbidden-words` 查询禁词列表 THEN 系统 SHALL 返回该租户下所有禁词（支持按类别筛选），含命中统计。

- [AC-AISVC-80] WHEN 管理员通过 `PUT /admin/guardrails/forbidden-words/{wordId}` 更新禁词 THEN 系统 SHALL 支持修改词语、类别、替换策略、启用/禁用状态。

- [AC-AISVC-81] WHEN 管理员通过 `DELETE /admin/guardrails/forbidden-words/{wordId}` 删除禁词 THEN 系统 SHALL 删除禁词并立即生效。

- [AC-AISVC-82] WHEN LLM 生成回复后（non-streaming 和 streaming 均适用） THEN 系统 SHALL 执行后置过滤：扫描回复内容中的禁词，按替换策略处理：
  - `mask`：将禁词替换为等长星号（如"竞品A" → "***"）。
  - `replace`：将禁词替换为配置的替换文本。
  - `block`：丢弃整条回复，返回预配置的兜底话术（如"抱歉，让我换个方式回答您"），并在 metadata 中标记 `guardrail_triggered=true`。

- [AC-AISVC-83] WHEN 用户输入包含禁词（前置检测） THEN 系统 SHALL 在 metadata 中记录 `input_flagged=true` 及命中的禁词类别，但不阻断请求处理（仅记录，不拦截用户输入）。

- [AC-AISVC-84] WHEN 管理员通过 `POST /admin/guardrails/behavior-rules` 添加行为规则 THEN 系统 SHALL 存储行为约束（如"不允许承诺具体赔偿金额"、"不允许透露内部流程"），这些规则将被注入到 Prompt 模板的系统指令中作为 LLM 的行为约束。

- [AC-AISVC-85] WHEN 管理员通过 `GET /admin/guardrails/behavior-rules` 查询行为规则列表 THEN 系统 SHALL 返回该租户下所有行为规则。

### 12.6 智能 RAG 增强

- [AC-AISVC-86] WHEN Orchestrator 执行 RAG 检索前 THEN 系统 SHALL 对用户 Query 进行改写增强：结合对话历史解析指代词（如"它"、"这个"指代上文提到的产品），补全查询语义，生成优化后的检索 Query。Query 改写通过 LLM 调用实现（使用简短的改写 Prompt）。

- [AC-AISVC-87] WHEN 多知识库检索返回结果后 THEN 系统 SHALL 按知识库优先级对结果进行分层排序：`script`（话术模板）> `faq`（常见问题）> `product`（产品知识）> `policy`（政策规范）> `general`（通用），同层内按相似度分数排序。高优先级知识库的命中结果优先进入 LLM 上下文。

- [AC-AISVC-88] WHEN 检索结果中存在 `script` 类型知识库的高分命中（score > 配置阈值） THEN 系统 SHALL 优先使用话术模板内容作为回复参考，引导 LLM 生成贴近标准话术的回复。

### 12.7 数据预处理扩展点（架构预留）

- [AC-AISVC-89] WHEN 系统设计文档解析服务时 THEN 系统 SHALL 在 `DocumentParser` 抽象接口中预留 `AudioParser`（语音转文字）和 `VideoParser`（视频提取音轨转文字）的扩展点，但 v0.6.0 不实现具体解析逻辑。

- [AC-AISVC-90] WHEN 系统设计知识库索引服务时 THEN 系统 SHALL 在 `KnowledgeIndexer` 中预留"对话记录结构化导入"接口（接受结构化 JSON 格式的对话记录，按轮次分块索引），但 v0.6.0 不实现具体导入逻辑。

### 12.8 追踪映射（v0.6.0 迭代）

| AC ID | Endpoint | 方法 | Operation | 描述 |
|-------|----------|------|-----------|------|
| AC-AISVC-51 | - | - | - | Prompt 模板数据库驱动加载 |
| AC-AISVC-52 | /admin/prompt-templates | POST | createPromptTemplate | 创建 Prompt 模板 |
| AC-AISVC-53 | /admin/prompt-templates/{tplId} | PUT | updatePromptTemplate | 更新模板（版本化） |
| AC-AISVC-54 | /admin/prompt-templates/{tplId}/publish | POST | publishPromptTemplate | 发布模板版本 |
| AC-AISVC-55 | /admin/prompt-templates/{tplId}/rollback | POST | rollbackPromptTemplate | 回滚模板版本 |
| AC-AISVC-56 | - | - | - | Prompt 变量替换与拼接 |
| AC-AISVC-57 | /admin/prompt-templates | GET | listPromptTemplates | 模板列表查询 |
| AC-AISVC-58 | /admin/prompt-templates/{tplId} | GET | getPromptTemplate | 模板详情查询 |
| AC-AISVC-59 | /admin/kb/knowledge-bases | POST | createKnowledgeBase | 创建知识库 |
| AC-AISVC-60 | /admin/kb/knowledge-bases | GET | listKnowledgeBases | 知识库列表 |
| AC-AISVC-61 | /admin/kb/knowledge-bases/{kbId} | PUT | updateKnowledgeBase | 更新知识库 |
| AC-AISVC-62 | /admin/kb/knowledge-bases/{kbId} | DELETE | deleteKnowledgeBase | 删除知识库 |
| AC-AISVC-63 | /admin/kb/documents | POST | uploadDocument | 文档指定知识库上传 |
| AC-AISVC-64 | - | - | - | 多知识库智能路由检索 |
| AC-AISVC-65 | /admin/intent-rules | POST | createIntentRule | 创建意图规则 |
| AC-AISVC-66 | /admin/intent-rules | GET | listIntentRules | 意图规则列表 |
| AC-AISVC-67 | /admin/intent-rules/{ruleId} | PUT | updateIntentRule | 更新意图规则 |
| AC-AISVC-68 | /admin/intent-rules/{ruleId} | DELETE | deleteIntentRule | 删除意图规则 |
| AC-AISVC-69 | - | - | - | 意图识别与路由执行 |
| AC-AISVC-70 | - | - | - | 未命中规则回退默认 RAG |
| AC-AISVC-71 | /admin/script-flows | POST | createScriptFlow | 创建话术流程 |
| AC-AISVC-72 | /admin/script-flows | GET | listScriptFlows | 话术流程列表 |
| AC-AISVC-73 | /admin/script-flows/{flowId} | PUT | updateScriptFlow | 更新话术流程 |
| AC-AISVC-74 | - | - | - | 流程实例创建与首步执行 |
| AC-AISVC-75 | - | - | - | 流程步骤推进 |
| AC-AISVC-76 | - | - | - | 流程完成与恢复 |
| AC-AISVC-77 | - | - | - | 流程超时处理 |
| AC-AISVC-78 | /admin/guardrails/forbidden-words | POST | addForbiddenWord | 添加禁词 |
| AC-AISVC-79 | /admin/guardrails/forbidden-words | GET | listForbiddenWords | 禁词列表 |
| AC-AISVC-80 | /admin/guardrails/forbidden-words/{wordId} | PUT | updateForbiddenWord | 更新禁词 |
| AC-AISVC-81 | /admin/guardrails/forbidden-words/{wordId} | DELETE | deleteForbiddenWord | 删除禁词 |
| AC-AISVC-82 | - | - | - | LLM 输出后置禁词过滤 |
| AC-AISVC-83 | - | - | - | 用户输入前置禁词检测 |
| AC-AISVC-84 | /admin/guardrails/behavior-rules | POST | addBehaviorRule | 添加行为规则 |
| AC-AISVC-85 | /admin/guardrails/behavior-rules | GET | listBehaviorRules | 行为规则列表 |
| AC-AISVC-86 | - | - | - | Query 改写增强 |
| AC-AISVC-87 | - | - | - | 多知识库分层排序 |
| AC-AISVC-88 | - | - | - | 话术模板优先匹配 |
| AC-AISVC-89 | - | - | - | 音视频解析扩展点预留 |
| AC-AISVC-90 | - | - | - | 对话记录导入扩展点预留 |

---

## 13. 迭代需求：对话流程测试与监控 API（v0.7.0）

> 说明：本节为 v0.7.0 迭代新增，为前端测试与监控功能提供后端 API 支持。

### 13.1 Dashboard 统计增强 API

- [AC-AISVC-91] WHEN 前端通过 `GET /admin/dashboard/stats` 请求 Dashboard 统计数据 THEN 系统 SHALL 在现有统计基础上新增以下字段：
  - `intentRuleHitRate`: 意图规则命中率（命中次数/总对话次数）
  - `intentRuleHitCount`: 意图规则总命中次数
  - `promptTemplateUsageCount`: Prompt 模板使用次数
  - `scriptFlowActivationCount`: 话术流程激活次数
  - `guardrailBlockCount`: 护栏拦截次数

- [AC-AISVC-92] WHEN 前端通过 `GET /admin/dashboard/stats` 请求并指定时间范围参数（`start_time`, `end_time`）THEN 系统 SHALL 返回该时间范围内的统计数据。

### 13.2 完整流程测试 API

- [AC-AISVC-93] WHEN 前端通过 `POST /admin/test/flow-execution` 提交测试请求 THEN 系统 SHALL 执行完整的 12 步生成流程，并返回每一步的详细执行结果，包含：
  - `step`: 步骤编号（1-12）
  - `name`: 步骤名称
  - `status`: 执行状态（success/failed/skipped）
  - `duration_ms`: 执行耗时（毫秒）
  - `input`: 步骤输入数据
  - `output`: 步骤输出数据
  - `error`: 错误信息（如果失败）
  - `metadata`: 步骤元数据（如命中的规则、使用的模板等）

- [AC-AISVC-94] WHEN 测试请求包含对比配置参数（如不同的 Prompt 模板 ID、知识库 ID 列表）THEN 系统 SHALL 并行执行多个配置的测试，并返回对比结果数组。

- [AC-AISVC-95] WHEN 测试执行过程中某一步失败 THEN 系统 SHALL 记录失败原因，并继续执行后续步骤（尽力而为模式），最终返回完整的执行链路。

### 13.3 意图规则测试与监控 API

- [AC-AISVC-96] WHEN 前端通过 `POST /admin/intent-rules/{ruleId}/test` 提交测试消息 THEN 系统 SHALL 返回测试结果：
  - `matched`: 是否命中该规则（boolean）
  - `matchedKeywords`: 匹配的关键词列表
  - `matchedPatterns`: 匹配的正则表达式列表
  - `priority`: 规则优先级
  - `priorityRank`: 在所有规则中的优先级排名
  - `conflictRules`: 同时命中的其他规则列表（优先级冲突检测）
  - `reason`: 未命中原因（如果未命中）

- [AC-AISVC-97] WHEN 前端通过 `GET /admin/monitoring/intent-rules` 查询意图规则监控统计 THEN 系统 SHALL 返回规则统计列表：
  - `ruleId`: 规则 ID
  - `ruleName`: 规则名称
  - `hitCount`: 命中次数
  - `hitRate`: 命中率（命中次数/总对话次数）
  - `avgResponseTime`: 平均响应时间（毫秒）
  - `lastHitTime`: 最近命中时间
  - `responseType`: 响应类型

- [AC-AISVC-98] WHEN 前端通过 `GET /admin/monitoring/intent-rules/{ruleId}/hits` 查询规则命中记录 THEN 系统 SHALL 返回该规则的详细命中记录列表（支持分页）：
  - `conversationId`: 对话 ID
  - `sessionId`: 会话 ID
  - `userMessage`: 用户消息
  - `matchedKeywords`: 匹配的关键词
  - `matchedPatterns`: 匹配的正则表达式
  - `responseType`: 响应类型
  - `executionResult`: 执行结果（成功/失败）
  - `hitTime`: 命中时间

### 13.4 Prompt 模板测试与监控 API

- [AC-AISVC-99] WHEN 前端通过 `POST /admin/prompt-templates/{tplId}/preview` 提交预览请求（含变量测试值）THEN 系统 SHALL 返回预览结果：
  - `templateId`: 模板 ID
  - `templateName`: 模板名称
  - `version`: 版本号
  - `rawContent`: 原始模板内容（含变量占位符）
  - `variables`: 变量列表及当前值
  - `renderedContent`: 渲染后的完整 Prompt 内容
  - `estimatedTokens`: 预估 Token 数量

- [AC-AISVC-100] WHEN 前端通过 `GET /admin/monitoring/prompt-templates` 查询 Prompt 模板监控统计 THEN 系统 SHALL 返回模板统计列表：
  - `templateId`: 模板 ID
  - `templateName`: 模板名称
  - `scene`: 场景标签
  - `usageCount`: 使用次数
  - `avgTokens`: 平均 Token 消耗
  - `avgPromptTokens`: 平均 Prompt Token 消耗
  - `avgCompletionTokens`: 平均 Completion Token 消耗
  - `lastUsedTime`: 最近使用时间

### 13.5 话术流程测试与监控 API

- [AC-AISVC-101] WHEN 前端通过 `POST /admin/script-flows/{flowId}/simulate` 提交模拟执行请求 THEN 系统 SHALL 创建模拟会话并返回首步话术：
  - `simulationId`: 模拟会话 ID
  - `flowId`: 流程 ID
  - `flowName`: 流程名称
  - `currentStep`: 当前步骤编号
  - `stepContent`: 当前步骤话术内容
  - `waitForInput`: 是否等待用户输入
  - `nextConditions`: 下一步条件列表

- [AC-AISVC-102] WHEN 前端通过 `POST /admin/script-flows/{flowId}/simulate/{simulationId}/next` 提交用户模拟输入 THEN 系统 SHALL 根据下一步条件推进流程，并返回下一步话术或流程结束标志。

- [AC-AISVC-103] WHEN 前端通过 `GET /admin/monitoring/script-flows` 查询话术流程监控统计 THEN 系统 SHALL 返回流程统计列表：
  - `flowId`: 流程 ID
  - `flowName`: 流程名称
  - `activationCount`: 激活次数
  - `completionCount`: 完成次数
  - `completionRate`: 完成率（完成次数/激活次数）
  - `avgCompletionTime`: 平均完成时长（秒）
  - `interruptionCount`: 中断次数
  - `interruptionRate`: 中断率

- [AC-AISVC-104] WHEN 前端通过 `GET /admin/monitoring/script-flows/{flowId}/executions` 查询流程执行记录 THEN 系统 SHALL 返回该流程的详细执行记录列表（支持分页）：
  - `executionId`: 执行实例 ID
  - `sessionId`: 会话 ID
  - `activationTime`: 激活时间
  - `currentStep`: 当前步骤
  - `status`: 执行状态（in_progress/completed/interrupted）
  - `interruptionReason`: 中断原因（如果中断）
  - `completionTime`: 完成时间

### 13.6 输出护栏测试与监控 API

- [AC-AISVC-105] WHEN 前端通过 `POST /admin/guardrails/test` 提交测试文本 THEN 系统 SHALL 返回护栏检测结果：
  - `originalText`: 原始文本
  - `processedText`: 处理后文本
  - `detectedWords`: 检测到的禁词列表（含词语、类别、位置、策略）
  - `isBlocked`: 是否被拦截（boolean）
  - `blockReason`: 拦截原因（如果被拦截）

- [AC-AISVC-106] WHEN 前端通过 `GET /admin/monitoring/guardrails` 查询输出护栏监控统计 THEN 系统 SHALL 返回护栏统计列表：
  - `wordId`: 禁词 ID
  - `word`: 禁词内容
  - `category`: 类别
  - `blockCount`: 拦截次数
  - `replaceCount`: 替换次数
  - `maskCount`: 掩码次数
  - `lastBlockTime`: 最近拦截时间

- [AC-AISVC-107] WHEN 前端通过 `GET /admin/monitoring/guardrails/{wordId}/blocks` 查询禁词拦截记录 THEN 系统 SHALL 返回该禁词的详细拦截记录列表（支持分页）：
  - `blockId`: 拦截记录 ID
  - `sessionId`: 会话 ID
  - `originalText`: 原始文本
  - `processedText`: 处理后文本
  - `strategy`: 应用的策略（mask/replace/block）
  - `blockTime`: 拦截时间

### 13.7 对话追踪 API

- [AC-AISVC-108] WHEN 前端通过 `GET /admin/monitoring/conversations` 查询对话追踪列表 THEN 系统 SHALL 返回对话记录列表（支持分页和筛选）：
  - `conversationId`: 对话 ID
  - `sessionId`: 会话 ID
  - `userMessage`: 用户消息
  - `aiReply`: AI 回复
  - `triggeredRules`: 触发的意图规则列表
  - `usedTemplate`: 使用的 Prompt 模板
  - `usedFlow`: 使用的话术流程
  - `executionTime`: 执行耗时（毫秒）
  - `createdAt`: 创建时间

- [AC-AISVC-109] WHEN 前端通过 `GET /admin/monitoring/conversations/{conversationId}` 查询对话执行链路详情 THEN 系统 SHALL 返回该对话的完整 12 步执行链路数据（与测试 API 返回格式一致）。

- [AC-AISVC-110] WHEN 前端通过 `POST /admin/monitoring/conversations/export` 提交导出请求（含筛选条件）THEN 系统 SHALL 生成导出文件（JSON/CSV 格式），并返回下载链接或直接返回文件流。

### 13.8 追踪映射（v0.7.0 迭代）

| AC ID | Endpoint | 方法 | Operation | 描述 |
|-------|----------|------|-----------|------|
| AC-AISVC-91 | /admin/dashboard/stats | GET | getDashboardStats | Dashboard 统计增强 |
| AC-AISVC-92 | /admin/dashboard/stats | GET | getDashboardStats | 时间范围筛选 |
| AC-AISVC-93 | /admin/test/flow-execution | POST | testFlowExecution | 完整流程测试 |
| AC-AISVC-94 | /admin/test/flow-execution | POST | testFlowExecution | 对比测试 |
| AC-AISVC-95 | /admin/test/flow-execution | POST | testFlowExecution | 失败容错处理 |
| AC-AISVC-96 | /admin/intent-rules/{ruleId}/test | POST | testIntentRule | 意图规则测试 |
| AC-AISVC-97 | /admin/monitoring/intent-rules | GET | getIntentRuleStats | 意图规则监控统计 |
| AC-AISVC-98 | /admin/monitoring/intent-rules/{ruleId}/hits | GET | getIntentRuleHits | 规则命中记录 |
| AC-AISVC-99 | /admin/prompt-templates/{tplId}/preview | POST | previewPromptTemplate | Prompt 模板预览 |
| AC-AISVC-100 | /admin/monitoring/prompt-templates | GET | getPromptTemplateStats | Prompt 模板监控统计 |
| AC-AISVC-101 | /admin/script-flows/{flowId}/simulate | POST | simulateScriptFlow | 话术流程模拟执行 |
| AC-AISVC-102 | /admin/script-flows/{flowId}/simulate/{simulationId}/next | POST | simulateScriptFlowNext | 流程模拟推进 |
| AC-AISVC-103 | /admin/monitoring/script-flows | GET | getScriptFlowStats | 话术流程监控统计 |
| AC-AISVC-104 | /admin/monitoring/script-flows/{flowId}/executions | GET | getScriptFlowExecutions | 流程执行记录 |
| AC-AISVC-105 | /admin/guardrails/test | POST | testGuardrail | 输出护栏测试 |
| AC-AISVC-106 | /admin/monitoring/guardrails | GET | getGuardrailStats | 输出护栏监控统计 |
| AC-AISVC-107 | /admin/monitoring/guardrails/{wordId}/blocks | GET | getGuardrailBlocks | 禁词拦截记录 |
| AC-AISVC-108 | /admin/monitoring/conversations | GET | getConversations | 对话追踪列表 |
| AC-AISVC-109 | /admin/monitoring/conversations/{conversationId} | GET | getConversationDetail | 对话执行链路详情 |
| AC-AISVC-110 | /admin/monitoring/conversations/export | POST | exportConversations | 对话记录导出 |

---

## 14. 迭代需求：意图识别混合路由优化（v0.8.0）

> 说明：本节为 v0.8.0 迭代新增，目标是将意图识别从"单一规则匹配"升级为"规则+语义+LLM"三路混合路由，提升意图识别准确率与召回率。
> 详细规范见：[spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/](./iterations/v0.8.0-intent-hybrid-routing/)

### 14.1 混合路由三路打分

- [AC-AISVC-111] WHEN 用户消息进入意图识别 THEN 系统 SHALL 并行执行三路匹配：
  - RuleMatcher：关键词+正则匹配，输出 `rule_score`（命中=1.0，未命中=0.0）
  - SemanticMatcher：向量语义匹配，输出 `semantic_score`（0.0~1.0 相似度）
  - LlmJudge：仅在触发条件满足时执行，输出 `llm_score`（0.0~1.0 置信度）

- [AC-AISVC-112] WHEN RuleMatcher 命中规则 THEN 系统 SHALL 输出匹配结果包含：
  - `rule_id`：命中的规则 ID
  - `match_type`："keyword" | "regex"
  - `matched_text`：匹配的关键词或模式
  - `rule_score`：1.0（命中）或 0.0（未命中）

- [AC-AISVC-113] WHEN SemanticMatcher 执行 THEN 系统 SHALL：
  - 将用户消息向量化（复用现有 EmbeddingProvider）
  - 与意图规则的语义向量进行相似度计算
  - 返回 Top-N 候选意图及 `semantic_score`
  - 若无语义向量配置的规则，跳过此路并记录日志

- [AC-AISVC-114] WHEN SemanticMatcher 执行 THEN 系统 SHALL 支持两种语义匹配模式：
  - 模式 A：基于规则预置的 `intent_vector` 直接计算相似度
  - 模式 B：基于规则的 `semantic_examples`（示例句列表）动态计算平均相似度

### 14.2 融合决策输出

- [AC-AISVC-115] WHEN 三路匹配完成后 THEN 系统 SHALL 执行 FusionPolicy 融合决策，输出：
  - `final_intent`：最终意图（IntentMatchResult 或 None）
  - `final_confidence`：最终置信度（0.0~1.0）
  - `decision_reason`：决策原因（如 "rule_high_confidence" | "semantic_override" | "llm_judge" | "no_match"）
  - `route_trace`：路由追踪信息（三路打分详情）

- [AC-AISVC-116] WHEN 融合决策计算置信度 THEN 系统 SHALL 使用可配置的融合公式：
  ```
  final_confidence = w_rule * rule_score + w_semantic * semantic_score + w_llm * llm_score
  ```
  默认权重：`w_rule=0.5, w_semantic=0.3, w_llm=0.2`

- [AC-AISVC-117] WHEN 融合决策判定意图 THEN 系统 SHALL 按以下优先级：
  1. 若 RuleMatcher 命中且 `rule_score=1.0`，优先采用规则意图
  2. 若 RuleMatcher 未命中但 SemanticMatcher 高置信（>semantic_threshold），采用语义意图
  3. 若存在冲突或低置信，触发 LlmJudge 仲裁
  4. 若三路均低置信，返回 `no_match`（回退默认 RAG）

### 14.3 LLM Judge 触发条件

- [AC-AISVC-118] WHEN 以下任一条件满足 THEN 系统 SHALL 触发 LlmJudge：
  - **冲突场景**：RuleMatcher 与 SemanticMatcher 命中不同意图，且两者置信度差值 < conflict_threshold（默认 0.2）
  - **灰区场景**：最高置信度 < gray_zone_threshold（默认 0.6）且 > min_trigger_threshold（默认 0.3）
  - **多意图场景**：SemanticMatcher 返回多个候选意图且 Top-2 置信度差值 < multi_intent_threshold（默认 0.15）

- [AC-AISVC-119] WHEN LlmJudge 执行 THEN 系统 SHALL：
  - 构建仲裁 Prompt（包含用户消息、候选意图列表、规则描述）
  - 调用 LLM 返回最终意图判定及置信度
  - 记录 LLM 调用耗时与 Token 消耗
  - 若 LLM 调用失败，回退到 SemanticMatcher 结果

- [AC-AISVC-120] WHEN LlmJudge 配置为禁用 THEN 系统 SHALL 跳过 LLM 调用，仅使用 RuleMatcher + SemanticMatcher 融合决策。

### 14.4 澄清触发条件

- [AC-AISVC-121] WHEN 融合决策后 `final_confidence < clarify_threshold`（默认 0.4）THEN 系统 SHALL 在响应中设置 `need_clarify=true` 并提供候选意图列表供用户确认。

### 14.5 路由追踪日志

- [AC-AISVC-122] WHEN 意图识别完成 THEN 系统 SHALL 在 `route_trace` 字段记录：
  - `rule_match`：RuleMatcher 结果（rule_id, match_type, matched_text, score, duration_ms）
  - `semantic_match`：SemanticMatcher 结果（top_candidates, scores, duration_ms）
  - `llm_judge`：LlmJudge 结果（triggered, intent, score, duration_ms, tokens）
  - `fusion`：融合决策结果（weights, final_confidence, decision_reason）

- [AC-AISVC-123] WHEN 路由追踪日志写入 THEN 系统 SHALL 复用现有监控 API 的 trace 字段格式，支持 `GET /admin/monitoring/conversations/{id}` 查询。

### 14.6 多租户隔离要求

- [AC-AISVC-124] WHEN 意图混合路由执行 THEN 系统 SHALL 确保：
  - 所有规则查询按 `tenant_id` 过滤
  - 语义向量索引按 `tenant_id` 隔离（Qdrant Collection 或 payload filter）
  - LlmJudge 调用携带 `tenant_id` 用于计费与审计
  - 路由追踪日志按 `tenant_id` 隔离存储

### 14.7 性能约束

- [AC-AISVC-125] WHEN 意图混合路由执行 THEN 系统 SHALL 满足以下性能约束：
  - RuleMatcher 延迟 < 10ms（内存缓存命中）
  - SemanticMatcher 延迟 < 100ms（向量计算 + 相似度检索）
  - LlmJudge 延迟 < 2000ms（仅在触发时执行）
  - P95 总增量延迟 < 500ms（不含 LlmJudge）
  - P95 总增量延迟 < 2500ms（含 LlmJudge）

### 14.8 追踪映射（v0.8.0 迭代）

| AC ID | Endpoint | 方法 | Operation | 描述 |
|-------|----------|------|-----------|------|
| AC-AISVC-111 | - | - | - | 三路并行匹配 |
| AC-AISVC-112 | - | - | - | RuleMatcher 输出 |
| AC-AISVC-113 | - | - | - | SemanticMatcher 执行 |
| AC-AISVC-114 | - | - | - | 语义匹配模式 |
| AC-AISVC-115 | - | - | - | 融合决策输出 |
| AC-AISVC-116 | - | - | - | 融合公式 |
| AC-AISVC-117 | - | - | - | 意图判定优先级 |
| AC-AISVC-118 | - | - | - | LLM Judge 触发条件 |
| AC-AISVC-119 | - | - | - | LLM Judge 执行 |
| AC-AISVC-120 | - | - | - | LLM Judge 禁用 |
| AC-AISVC-121 | - | - | - | 澄清触发条件 |
| AC-AISVC-122 | - | - | - | 路由追踪日志 |
| AC-AISVC-123 | /admin/monitoring/conversations/{id} | GET | getConversationDetail | 追踪日志查询 |
| AC-AISVC-124 | - | - | - | 多租户隔离 |
| AC-AISVC-125 | - | - | - | 性能约束 |
