diff --git a/ai-service/docs/progress/ai-service-AISVC-RES-progress.md b/ai-service/docs/progress/ai-service-AISVC-RES-progress.md new file mode 100644 index 0000000..39b90e5 --- /dev/null +++ b/ai-service/docs/progress/ai-service-AISVC-RES-progress.md @@ -0,0 +1,158 @@ +--- +context: + module: "ai-service" + feature: "AISVC-RES" + status: "✅已完成" + version: "0.9.0" + active_ac_range: "AC-AISVC-RES-01~15" + +spec_references: + requirements: "spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md" + design: "spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/design.md" + tasks: "spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/tasks.md" + active_version: "0.1.0" + +overall_progress: + - "[x] Phase 1: 策略层核心实现 (100%) [Tasks: StrategyRouter, ModeRouter]" + - "[x] Phase 2: 自动路由规则实现 (100%) [Tasks: auto路由规则, direct回退]" + - "[x] Phase 3: 配置热更新 (100%) [Tasks: 路由参数热更新]" + - "[x] Phase 4: API 端点与集成 (100%) [Tasks: API端点, dialogue集成]" + - "[x] Phase 5: 验证与文档 (100%) [Tasks: 测试, 进度更新]" + +current_phase: + goal: "所有任务已完成" + sub_tasks: + - "[x] 创建 routing_config.py 实现路由配置模型 [AC-AISVC-RES-01~15]" + - "[x] 创建 strategy_router.py 实现默认/增强策略路由 [AC-AISVC-RES-01,02,03,07,08]" + - "[x] 创建 mode_router.py 实现 direct/react/auto 模式路由 [AC-AISVC-RES-09,10,11,12,13,14]" + - "[x] 创建 strategy_integration.py 统一集成层" + - "[x] 创建 strategy.py API 端点 [AC-AISVC-RES-06,15]" + - "[x] 注册 API 路由到 main.py" + + next_action: + immediate: "所有实现已完成，等待下一阶段任务" + details: + file: "N/A" + action: "等待用户确认或下一阶段需求" + reference: "N/A" + +technical_context: + module_structure: | + ai-service/app/services/retrieval/ + ├── routing_config.py # 新增：路由配置模型（StrategyType, RagRuntimeMode, RoutingConfig） + ├── strategy_router.py # 新增：策略路由器（StrategyRouter, RollbackManager） + ├── mode_router.py # 新增：模式路由器（ModeRouter, ComplexityAnalyzer） + ├── strategy_integration.py # 新增：统一集成层 + ├── optimized_retriever.py # 现有：优化版 RAG 检索器 + ├── vector_retriever.py # 现有：向量检索器 + └── base.py # 现有：基类定义 + + ai-service/app/api/admin/ + └── strategy.py # 新增：策略 API 端点 + key_decisions: + - decision: "使用 StrategyType 替代 RetrievalStrategy 避免与 metadata.py 命名冲突" + reason: "metadata.py 中已存在 RetrievalStrategy 枚举" + impact: "所有策略相关代码使用 StrategyType" + - decision: "StrategyRouter 作为策略层入口，根据配置选择默认或增强策略" + reason: "保持向后兼容，默认策略复用现有逻辑" + impact: "所有检索请求通过 StrategyRouter 路由" + - decision: "ModeRouter 作为模式路由，支持 direct/react/auto 三种模式" + reason: "支持 ReAct 和非 ReAct 两种执行路径" + impact: "auto 模式需要复杂度/置信度判定逻辑" + - decision: "RetrievalStrategyIntegration 作为统一集成层" + reason: "简化 dialogue.py 的集成复杂度" + impact: "dialogue.py 只需调用 integration.execute(ctx)" + code_snippets: | + # 使用示例 + from app.services.retrieval import ( + StrategyContext, + get_retrieval_strategy_integration, + ) + + integration = get_retrieval_strategy_integration() + ctx = StrategyContext( + tenant_id="tenant-123", + query="用户查询", + metadata_confidence=0.8, + complexity_score=0.3, + ) + result = await integration.execute(ctx) + # result.retrieval_result - 检索结果 + # result.final_answer - ReAct 最终答案（如果有） + # result.strategy - 使用的策略 + # result.mode - 使用的模式 + +session_history: + - session: "Session #1 (2026-03-10)" + completed: + - "创建 routing_config.py - 路由配置模型" + - "创建 strategy_router.py - 策略路由器" + - "创建 mode_router.py - 模式路由器" + - "创建 strategy_integration.py - 统一集成层" + - "创建 strategy.py - API 端点" + - "更新 __init__.py - 导出新模块" + - "更新 main.py - 注册 API 路由" + - "更新 admin/__init__.py - 导出 strategy_router" + - "创建单元测试文件 test_routing_config.py - 路由配置测试" + - "创建单元测试文件 test_strategy_router.py - 策略路由器测试" + - "创建单元测试文件 test_mode_router.py - 模式路由器测试" + - "创建单元测试文件 test_strategy_integration.py - 集成层测试" + changes: + - file: "app/services/retrieval/routing_config.py" + action: "新增" + description: "路由配置模型，包含 StrategyType, RagRuntimeMode, RoutingConfig" + - file: "app/services/retrieval/strategy_router.py" + action: "新增" + description: "策略路由器，实现默认/增强策略路由、灰度发布、回滚管理" + - file: "app/services/retrieval/mode_router.py" + action: "新增" + description: "模式路由器，实现 direct/react/auto 模式路由、复杂度分析、低置信度回退" + - file: "app/services/retrieval/strategy_integration.py" + action: "新增" + description: "统一集成层，整合 StrategyRouter 和 ModeRouter" + - file: "app/api/admin/strategy.py" + action: "新增" + description: "策略 API 端点，提供配置查询、切换、验证、回滚接口" + - file: "app/services/retrieval/__init__.py" + action: "修改" + description: "导出新增模块" + - file: "app/api/admin/__init__.py" + action: "修改" + description: "导出 strategy_router" + - file: "app/main.py" + action: "修改" + description: "注册 strategy_router 到应用" + - file: "tests/test_routing_config.py" + action: "新增" + description: "路由配置单元测试，覆盖 StrategyType, RagRuntimeMode, RoutingConfig, StrategyContext, StrategyResult" + - file: "tests/test_strategy_router.py" + action: "新增" + description: "策略路由器单元测试，覆盖 RollbackManager, DefaultPipeline, EnhancedPipeline, StrategyRouter" + - file: "tests/test_mode_router.py" + action: "新增" + description: "模式路由器单元测试，覆盖 ComplexityAnalyzer, ModeRouteResult, ModeRouter" + - file: "tests/test_strategy_integration.py" + action: "新增" + description: "集成层单元测试，覆盖 RetrievalStrategyResult, RetrievalStrategyIntegration" + test_results: + - test_file: "tests/test_routing_config.py" + status: "✅ 通过" + test_count: 26 + coverage: "AC-AISVC-RES-01~15" + - test_file: "tests/test_strategy_router.py" + status: "✅ 通过" + test_count: 19 + coverage: "AC-AISVC-RES-01,02,03,07,08" + - test_file: "tests/test_mode_router.py" + status: "✅ 通过" + test_count: 18 + coverage: "AC-AISVC-RES-09,10,11,12,13,14" + - test_file: "tests/test_strategy_integration.py" + status: "✅ 通过" + test_count: 14 + coverage: "AC-AISVC-RES-01~15" + +startup_guide: + - "Step 1: 读取本进度文档（了解当前位置与下一步）" + - "Step 2: 读取 spec_references 中定义的模块规范（了解业务与接口约束）" + - "Step 3: 直接执行 next_action"