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

12 KiB
Raw Blame History

ai-service - Progress

📋 Context

  • module: ai-service
  • feature: AISVC (Python AI 中台)
  • status: 🔄 进行中 (Phase 14 完成)

🔗 Spec References (SSOT)

  • agents: agents.md
  • contracting: spec/contracting.md
  • requirements: spec/ai-service/requirements.md
  • openapi_provider: spec/ai-service/openapi.provider.yaml
  • design: spec/ai-service/design.md
  • tasks: spec/ai-service/tasks.md

📊 Overall Progress (Phases)

  • Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
  • Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
  • Phase 3: 核心编排（Orchestrator & LLM Adapter） (100%) ✅
  • Phase 4: 流式响应（SSE 实现与状态机） (100%) ✅
  • Phase 5: 集成与冒烟测试（Quality Assurance） (100%) ✅
  • Phase 6: 前后端联调真实对接 (100%) ✅
  • Phase 7: 嵌入模型可插拔与文档解析 (100%) ✅
  • Phase 8: LLM 配置与 RAG 调试输出 (100%) ✅
  • Phase 9: 租户管理与 RAG 优化 (100%) ✅
  • Phase 10: Prompt 模板化 (80%) 🔄 (T10.1-T10.8 完成，T10.9-T10.10 待集成阶段)
  • Phase 11: 多知识库管理 (63%) 🔄 (T11.1-T11.5 完成，T11.6-T11.8 待集成阶段)
  • Phase 12: 意图识别与规则引擎 (71%) 🔄 (T12.1-T12.5 完成，T12.6-T12.7 待集成阶段)
  • Phase 13: 话术流程引擎 (86%) 🔄 (T13.1-T13.6 完成，T13.7 单元测试留到集成阶段)
  • Phase 14: 输出护栏 (88%) ✅ (T14.1-T14.7 完成，T14.8 单元测试留到集成阶段)

🔄 Current Phase

Goal

Phase 13 话术流程引擎核心功能已完成 (T13.1-T13.6)，T13.7（单元测试）留到集成阶段。下一阶段：Phase 15 智能 RAG 增强与编排升级。

Completed Tasks (Phase 13)

  • T13.1 定义 ScriptFlow 和 FlowInstance SQLModel 实体，创建数据库表 [AC-AISVC-71, AC-AISVC-74] ✅
  • T13.2 实现 ScriptFlowService：流程定义 CRUD [AC-AISVC-71, AC-AISVC-72, AC-AISVC-73] ✅
  • T13.3 实现 FlowEngine.check_active_flow()：检查会话是否有活跃流程实例 [AC-AISVC-75] ✅
  • T13.4 实现 FlowEngine.start()：创建流程实例，返回第一步话术 [AC-AISVC-74] ✅
  • T13.5 实现 FlowEngine.advance()：根据用户输入匹配条件，推进步骤或重复当前步骤 [AC-AISVC-75, AC-AISVC-76] ✅
  • T13.6 实现话术流程管理 API：POST/GET/PUT /admin/script-flows [AC-AISVC-71, AC-AISVC-72, AC-AISVC-73] ✅

Pending Tasks (Phase 13 - 集成阶段)

  • T13.7 编写话术流程引擎单元测试 [AC-AISVC-71~AC-AISVC-77]

🏗️ Technical Context

Module Structure

  • ai-service/
    • app/
      • api/ - FastAPI 路由层
        • admin/guardrails.py - 护栏管理 API ✅
        • admin/script_flows.py - 话术流程管理 API ✅
      • models/ - Pydantic 模型和 SQLModel 实体
        • entities.py - ForbiddenWord, BehaviorRule, GuardrailResult, InputScanResult, ScriptFlow, FlowInstance, FlowInstanceStatus, TimeoutAction, FlowStep, FlowAdvanceResult 实体 ✅
      • services/
        • guardrail/ - 输出护栏服务 ✅
          • __init__.py - 模块导出
          • word_service.py - 禁词 CRUD、命中统计、缓存
          • behavior_service.py - 行为规则 CRUD、缓存、Prompt 注入格式化
          • input_scanner.py - 用户输入前置检测（仅记录，不阻断）
          • output_filter.py - LLM 输出后置过滤（mask/replace/block）
          • streaming_filter.py - Streaming 滑动窗口检测
        • flow/ - 话术流程引擎 ✅
          • __init__.py - 模块导出
          • flow_service.py - 流程定义 CRUD
          • engine.py - FlowEngine 状态机（check_active_flow、start、advance、handle_timeout、cancel_flow）

Key Decisions (Why / Impact)

  • decision: 三种禁词替换策略 reason: 满足不同场景的内容合规需求 impact: mask 星号替换、replace 指定文本替换、block 拦截整条回复返回兜底话术

  • decision: 输入检测不阻断 reason: 用户输入包含禁词时仍需正常处理，仅记录用于监控分析 impact: InputScanner 返回 flagged 状态和匹配信息，不抛异常

  • decision: Streaming 滑动窗口检测 reason: 流式输出无法预知完整内容，需要缓冲区检测跨 chunk 的禁词 impact: 维护滑动窗口 buffer（默认 50 字符，自动调整到最长禁词长度），检测到禁词后立即停止

  • decision: 行为规则注入 Prompt reason: 行为规则作为 LLM 的行为约束，不进行运行时检测 impact: BehaviorRuleService 提供 format_rules_for_prompt() 方法，追加到系统指令末尾

  • decision: 内存缓存 + TTL 策略 reason: 减少数据库查询，提升过滤性能 impact: 缓存 TTL=60s，CRUD 操作时主动失效

  • decision: FlowEngine 状态机设计 reason: 实现多轮引导对话的固定话术流程 impact: 状态流转 IDLE → ACTIVE → COMPLETED/TIMEOUT/CANCELLED

  • decision: 步骤推进条件匹配 reason: 根据用户输入决定下一步骤 impact: 支持关键词匹配和正则匹配，nextConditions 定义跳转条件

  • decision: 超时处理三种策略 reason: 用户长时间无响应时的不同处理方式 impact: repeat（重复当前步骤）、skip（跳过到指定步骤）、transfer（转人工）

🧾 Session History

Session #11 (2026-02-27)

  • completed:
    • T13.1-T13.6 话术流程引擎核心功能
    • 实现 ScriptFlow 和 FlowInstance 实体
    • 实现 ScriptFlowService（流程定义 CRUD）
    • 实现 FlowEngine 状态机（check_active_flow、start、advance、handle_timeout、cancel_flow）
    • 实现步骤推进逻辑（关键词匹配、正则匹配、nextConditions 条件判断）
    • 实现超时处理（repeat/skip/transfer 三种策略）
    • 实现话术流程管理 API
  • changes:
    • 新增 app/models/entities.py ScriptFlow, FlowInstance, FlowInstanceStatus, TimeoutAction, FlowStep, FlowAdvanceResult 实体
    • 新增 app/services/flow/__init__.py 模块导出
    • 新增 app/services/flow/flow_service.py 流程定义服务
    • 新增 app/services/flow/engine.py FlowEngine 状态机引擎
    • 新增 app/api/admin/script_flows.py 话术流程管理 API
    • 更新 app/api/admin/__init__.py 导出新路由
    • 更新 app/main.py 注册新路由
    • 更新 spec/ai-service/tasks.md 标记任务完成
  • notes:
    • T13.7（单元测试）留到集成阶段
    • FlowEngine 状态机：IDLE → ACTIVE → COMPLETED/TIMEOUT/CANCELLED
    • 步骤推进支持关键词匹配和正则匹配
    • 超时处理支持三种策略：repeat（重复当前步骤）、skip（跳过到指定步骤）、transfer（转人工）

Session #10 (2026-02-27)

  • completed:
    • T14.1-T14.7 输出护栏核心功能
    • 实现 ForbiddenWord 和 BehaviorRule 实体
    • 实现 ForbiddenWordService（CRUD、命中统计、缓存）
    • 实现 BehaviorRuleService（CRUD、缓存、Prompt 注入格式化）
    • 实现 InputScanner（用户输入前置检测，仅记录不阻断）
    • 实现 OutputFilter（LLM 输出后置过滤，mask/replace/block 三种策略）
    • 实现 StreamingGuardrail（Streaming 滑动窗口检测）
    • 实现护栏管理 API（禁词和行为规则 CRUD）
  • changes:
    • 新增 app/models/entities.py ForbiddenWord, BehaviorRule, GuardrailResult, InputScanResult 实体
    • 新增 app/services/guardrail/__init__.py 模块导出
    • 新增 app/services/guardrail/word_service.py 禁词服务
    • 新增 app/services/guardrail/behavior_service.py 行为规则服务
    • 新增 app/services/guardrail/input_scanner.py 输入扫描器
    • 新增 app/services/guardrail/output_filter.py 输出过滤器
    • 新增 app/services/guardrail/streaming_filter.py Streaming 过滤器
    • 新增 app/api/admin/guardrails.py 护栏管理 API
    • 更新 app/api/admin/__init__.py 导出新路由
    • 更新 app/main.py 注册新路由
    • 更新 spec/ai-service/tasks.md 标记任务完成
  • notes:
    • T14.8（单元测试）留到集成阶段
    • 禁词检测三种策略：mask（星号替换）、replace（指定文本替换）、block（拦截返回兜底话术）
    • InputScanner 仅记录命中，不阻断请求
    • OutputFilter 应用 mask/replace/block 策略
    • StreamingGuardrail 使用滑动窗口 buffer（默认 50 字符，自动调整）

Session #9 (2026-02-27)

  • completed:
    • T11.1-T11.5 多知识库管理核心功能
    • 扩展 KnowledgeBase 实体（kb_type、priority、is_enabled、doc_count）
    • 实现 KnowledgeBaseService（CRUD、Collection 初始化/清理、文档计数）
    • 实现知识库管理 API（POST/GET/PUT/DELETE）
    • 升级 Qdrant Collection 命名（kb_{tenantId}_{kbId}，兼容旧格式）
    • 修改文档上传流程（支持 kbId 参数，索引到对应 Collection）
  • changes:
    • 新增 app/models/entities.py KBType 枚举、KnowledgeBaseCreate/Update Schema
    • 新增 app/services/knowledge_base_service.py 知识库 CRUD 服务
    • 更新 app/core/qdrant_client.py 多知识库 Collection 管理方法
    • 更新 app/api/admin/kb.py 知识库管理 API 和文档上传流程
    • 更新 spec/ai-service/tasks.md 标记任务完成
  • notes:
    • T11.6（OptimizedRetriever 多 Collection 检索）、T11.7（kb_default 迁移）、T11.8（单元测试）留待集成阶段
    • 进度文档已写入 ai-service/docs/progress/phase11_multi_kb_progress.md

Session #8 (2026-02-27)

  • completed:
    • T12.1-T12.5 意图识别与规则引擎核心功能
    • 实现 IntentRule 实体（支持关键词、正则、优先级、四种响应类型）
    • 实现 IntentRuleService（CRUD、命中统计、缓存）
    • 实现 IntentRouter 匹配引擎（按优先级 DESC 遍历，先关键词再正则）
    • 实现规则缓存（按 tenant_id 缓存，TTL=60s，CRUD 主动失效）
    • 实现意图规则管理 API（POST/GET/PUT/DELETE）
  • changes:
    • 新增 app/models/entities.py IntentRule, IntentRuleCreate, IntentRuleUpdate, IntentMatchResult 实体
    • 新增 app/services/intent/__init__.py 模块导出
    • 新增 app/services/intent/rule_service.py 规则服务
    • 新增 app/services/intent/router.py 匹配引擎
    • 新增 app/api/admin/intent_rules.py 规则管理 API
    • 更新 app/api/admin/__init__.py 导出新路由
    • 更新 app/main.py 注册新路由
    • 更新 spec/ai-service/tasks.md 标记任务完成
  • notes:
    • T12.6（Orchestrator 集成）和 T12.7（单元测试）留待集成阶段

Session #7 (2026-02-27)

  • completed:
    • T10.1-T10.8 Prompt 模板化核心功能
    • 实现 PromptTemplate 和 PromptTemplateVersion 实体
    • 实现 PromptTemplateService（CRUD、版本管理、发布/回滚、缓存）
    • 实现 VariableResolver 变量替换引擎
    • 实现 Prompt 模板管理 API（CRUD + 发布/回滚）
  • changes:
    • 新增 app/models/entities.py PromptTemplate, PromptTemplateVersion 实体
    • 新增 app/services/prompt/template_service.py 模板服务
    • 新增 app/services/prompt/variable_resolver.py 变量替换引擎
    • 新增 app/api/admin/prompt_templates.py 模板管理 API
    • 更新 app/main.py 注册新路由
    • 更新 spec/ai-service/tasks.md 标记任务完成
  • notes:
    • T10.9（修改 Orchestrator）和 T10.10（单元测试）留待集成阶段

Session #6 (2026-02-25)

  • completed:
    • T9.1-T9.10 租户管理与 RAG 优化功能
    • 实现 Tenant 实体和租户管理 API
    • 实现租户 ID 格式校验与自动创建
    • 实现前端租户选择器
    • 实现文档多编码支持
    • 实现按行分块功能
    • 实现 NomicEmbeddingProvider
    • 实现多维度向量存储
    • 实现 KnowledgeIndexer
  • changes:
    • 新增 app/models/entities.py Tenant 实体
    • 更新 app/core/middleware.py 租户校验逻辑
    • 新增 app/api/admin/tenants.py 租户管理 API
    • 新增 ai-service-admin/src/api/tenant.ts 前端 API
    • 更新 ai-service-admin/src/App.vue 租户选择器
    • 更新 ai-service/app/api/admin/kb.py 多编码支持
    • 新增 app/services/embedding/nomic_provider.py
    • 新增 app/services/retrieval/indexer.py
    • 新增 app/services/retrieval/metadata.py
    • 新增 app/services/retrieval/optimized_retriever.py

🚀 Startup Guide

  1. 读取本进度文档，定位当前 Phase 与 Next Action。
  2. 打开并阅读 Spec References 指向的模块规范。
  3. 直接执行 Next Action；遇到缺口先更新 spec 再编码。