MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-core/spec/ai-service/requirements.md

44 KiB
Raw Permalink Blame History

feature_id title status version owners last_updated source
AISVC Python AI 中台（ai-service）需求规范 in-progress 0.6.0
product
backend
2026-02-25
type ref
conversation

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 对话记录导出