ai-robot-core/docs/progress/ai-service-AISVC-RES-progress.md

---
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"
  openapi_provider: "spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml"
  active_version: "0.1.0"

overall_progress:
  - "[x] Phase 1: Schema与数据模型定义 (100%) [API与校验]"
  - "[x] Phase 2: 策略服务层实现 (100%) [策略层与配置]"
  - "[x] Phase 3: 审计日志与指标埋点 (100%) [观测与灰度验证]"
  - "[x] Phase 4: API端点实现 (100%) [API与校验]"
  - "[x] Phase 5: 单元测试与验证 (100%) [验收]"
  - "[x] Phase 6: 检索策略Pipeline实现 (100%) [检索与嵌入策略]"

current_phase:
  goal: "检索与嵌入策略化改造已完成"
  sub_tasks:
    - "[x] 创建 Schema 模型 (app/schemas/retrieval_strategy.py)"
    - "[x] 创建策略服务层 (app/services/retrieval/strategy_service.py)"
    - "[x] 创建审计日志服务 (app/services/retrieval/strategy_audit.py)"
    - "[x] 创建指标埋点服务 (app/services/retrieval/strategy_metrics.py)"
    - "[x] 创建 API 端点 (app/api/admin/retrieval_strategy.py)"
    - "[x] 创建策略配置模型 (app/services/retrieval/strategy/config.py)"
    - "[x] 实现 DefaultPipeline（复用现有逻辑）"
    - "[x] 实现 EnhancedPipeline（新端到端流程）"
    - "[x] 实现元数据推断统一入口 (MetadataInferenceService)"
    - "[x] 实现 StrategyRouter 和 ModeRouter"
    - "[x] 实现 Dense + Keyword + RRF 组合检索"
    - "[x] 实现可选重排与降级开关"
    - "[x] 实现 RollbackManager（回退与审计）"
    - "[x] 实现策略 API 接口"
    - "[x] 创建单元测试 (tests/test_retrieval_strategy_v2.py)"
    - "[x] 运行单元测试验证 (51 passed)"
  
  next_action:
    immediate: "任务已完成，可进行集成测试"
    details:
      file: "ai-service/app/services/retrieval/strategy/__init__.py:1"
      action: "模块已完整实现，可通过 API 接口测试策略切换功能"
      reference: "http://localhost:8000/docs"
    constraints: "新策略可配置启用，不影响默认策略"

technical_context:
  module_structure: |
    ai-service/app/
    ├── api/admin/retrieval_strategy.py      (API端点)
    ├── schemas/retrieval_strategy.py        (Schema模型)
    └── services/retrieval/
        ├── strategy_service.py              (策略服务)
        ├── strategy_audit.py                (审计日志)
        ├── strategy_metrics.py              (指标埋点)
        └── strategy/                        (新增 - 策略模块)
            ├── __init__.py                  (模块导出)
            ├── config.py                    (策略配置模型)
            ├── pipeline_base.py             (Pipeline基类)
            ├── default_pipeline.py          (默认策略Pipeline)
            ├── enhanced_pipeline.py         (增强策略Pipeline)
            ├── metadata_inference.py        (元数据推断统一入口)
            ├── strategy_router.py           (策略路由器)
            ├── mode_router.py               (模式路由器)
            └── rollback_manager.py          (回退管理器)
    └── tests/
        ├── test_retrieval_strategy.py       (单元测试 - 原有)
        └── test_retrieval_strategy_v2.py    (单元测试 - 新增)
  key_decisions:
    - decision: "使用内存存储策略状态，后续可扩展为持久化"
      reason: "快速实现，满足灰度验证需求"
      impact: "服务重启后策略状态重置为默认值"
    - decision: "审计日志使用结构化日志记录"
      reason: "与现有日志体系一致，便于检索"
      impact: "需要配置日志聚合系统收集审计日志"
    - decision: "API与现有strategy_router.py互补"
      reason: "strategy_router.py负责检索路由逻辑，新增的API负责策略管理"
      impact: "两者协同工作，API提供管理界面"
    - decision: "DefaultPipeline 复用现有 OptimizedRetriever 逻辑"
      reason: "保持线上行为不变，最小化改动风险"
      impact: "新策略与旧策略完全隔离，可独立灰度"
    - decision: "EnhancedPipeline 实现新端到端流程"
      reason: "支持 Dense + Keyword + RRF 组合检索，可选重排"
      impact: "需要配置启用，不影响默认策略"
    - decision: "元数据推断统一入口处理 hard/soft filter"
      reason: "新旧策略共享同一推断逻辑，确保一致性"
      impact: "置信度高用硬过滤，置信度低用软过滤/加权"
  code_snippets: |
    # 使用示例
    from app.services.retrieval.strategy import (
        get_strategy_router,
        get_mode_router,
        get_rollback_manager,
    )
    
    # 策略路由
    router = get_strategy_router()
    decision = await router.route(tenant_id, user_id)
    result = await decision.pipeline.retrieve(ctx)
    
    # 模式路由
    mode_router = get_mode_router()
    mode_decision = mode_router.decide(query, confidence=0.8)
    
    # 回退管理
    rollback = get_rollback_manager()
    rollback.rollback(trigger="manual", reason="测试回退")

session_history:
  - session: "Session #1 (2026-03-10)"
    completed:
      - "创建 Schema 模型 (app/schemas/retrieval_strategy.py)"
      - "创建策略服务层 (app/services/retrieval/strategy_service.py)"
      - "创建审计日志服务 (app/services/retrieval/strategy_audit.py)"
      - "创建指标埋点服务 (app/services/retrieval/strategy_metrics.py)"
      - "创建 API 端点 (app/api/admin/retrieval_strategy.py)"
      - "更新 admin __init__.py 注册新路由"
      - "更新 main.py 注册新路由"
      - "创建单元测试 (tests/test_retrieval_strategy.py)"
      - "运行单元测试验证 (46 passed)"
    changes:
      - "新增: ai-service/app/schemas/retrieval_strategy.py"
      - "新增: ai-service/app/services/retrieval/strategy_service.py"
      - "新增: ai-service/app/services/retrieval/strategy_audit.py"
      - "新增: ai-service/app/services/retrieval/strategy_metrics.py"
      - "新增: ai-service/app/api/admin/retrieval_strategy.py"
      - "修改: ai-service/app/api/admin/__init__.py"
      - "修改: ai-service/app/main.py"
      - "新增: ai-service/tests/test_retrieval_strategy.py"
    status: "✅ 任务完成"
  - session: "Session #2 (2026-03-10) - 检索策略Pipeline实现"
    completed:
      - "实现策略配置模型 (config.py)"
      - "实现 Pipeline 基类 (pipeline_base.py)"
      - "实现 DefaultPipeline（复用现有逻辑）"
      - "实现 EnhancedPipeline（新端到端流程）"
      - "实现 MetadataInferenceService"
      - "实现 StrategyRouter"
      - "实现 ModeRouter"
      - "实现 RollbackManager"
      - "更新模块导出 (__init__.py)"
      - "创建单元测试 (tests/test_retrieval_strategy_v2.py)"
      - "运行单元测试验证 (51 passed)"
    changes:
      - "新增: ai-service/app/services/retrieval/strategy/__init__.py"
      - "新增: ai-service/app/services/retrieval/strategy/config.py"
      - "新增: ai-service/app/services/retrieval/strategy/pipeline_base.py"
      - "新增: ai-service/app/services/retrieval/strategy/default_pipeline.py"
      - "新增: ai-service/app/services/retrieval/strategy/enhanced_pipeline.py"
      - "新增: ai-service/app/services/retrieval/strategy/metadata_inference.py"
      - "新增: ai-service/app/services/retrieval/strategy/strategy_router.py"
      - "新增: ai-service/app/services/retrieval/strategy/mode_router.py"
      - "新增: ai-service/app/services/retrieval/strategy/rollback_manager.py"
      - "新增: ai-service/tests/test_retrieval_strategy_v2.py"
    status: "✅ 任务完成"

startup_guide:
  - "Step 1: 读取本进度文档（了解当前位置与下一步）"
  - "Step 2: 读取 spec_references 中定义的模块规范（了解业务与接口约束）"
  - "Step 3: 通过 API 接口测试策略切换功能"
  - "Step 4: 运行单元测试验证: pytest tests/test_retrieval_strategy_v2.py -v"
---