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

# ai-service - Progress

---

## 📋 Context

- module: `ai-service`
- feature: `AISVC` (Python AI 中台)
- status: 🔄 进行中

---

## 🔗 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)

- [x] Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
- [x] Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
- [ ] Phase 3: 核心编排（Orchestrator & LLM Adapter） (40%) 🔄
- [ ] Phase 4: 流式响应（SSE 实现与状态机） (0%) ⏳
- [ ] Phase 5: 集成与冒烟测试（Quality Assurance） (0%) ⏳

---

## 🔄 Current Phase

### Goal
实现核心编排层，包括 LLM Adapter 和 Orchestrator 的完整功能。

### Sub Tasks

#### Phase 3: 核心编排（Orchestrator & LLM Adapter）
- [x] T3.1 实现 LLM Adapter：封装 `langchain-openai` 或官方 SDK，支持 `generate` 与 `stream_generate` `[AC-AISVC-02, AC-AISVC-06]` ✅
- [x] T3.2 实现 Orchestrator：实现上下文合并逻辑（H_local + H_ext 的去重与截断策略） `[AC-AISVC-14, AC-AISVC-15]` ✅
- [ ] T3.3 实现 Orchestrator：实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑 `[AC-AISVC-17, AC-AISVC-18, AC-AISVC-19]` ⏳
- [ ] T3.4 实现 Orchestrator：整合 Memory、Retrieval 与 LLM 完成 non-streaming 生成闭环 `[AC-AISVC-01, AC-AISVC-02]` ⏳
- [ ] T3.5 验证 non-streaming 响应字段完全符合 `openapi.provider.yaml` 契约 `[AC-AISVC-02]` ⏳

### Next Action (Must be Specific)

**Immediate**: 执行 T3.3 - 实现 RAG 检索不足时的置信度下调与 `shouldTransfer` 逻辑。

**Details**:
1. 定义"检索不足"的判定条件：
   - `hits.size < minHits`
   - `max(score) < scoreThreshold`
   - evidence token 超限
2. 实现置信度计算策略：
   - 基于检索分数计算 confidence
   - 检索不足时下调 confidence
3. 实现 `shouldTransfer` 逻辑：
   - 当 `confidence < T_low` 时 `shouldTransfer=true`
   - 添加 `transferReason` 说明
4. reference:
   - `spec/ai-service/design.md` Section 4.3 - 检索不中兜底与置信度策略
   - `spec/ai-service/requirements.md` AC-AISVC-17, AC-AISVC-18, AC-AISVC-19

---

## 🏗️ Technical Context

### Module Structure

- `ai-service/`
  - `app/`
    - `api/` - FastAPI 路由层
    - `core/` - 配置、异常、中间件、SSE
    - `models/` - Pydantic 模型和 SQLModel 实体
    - `services/`
      - `llm/` - LLM Adapter 实现 ✅
        - `base.py` - LLMClient 抽象接口
        - `openai_client.py` - OpenAI 兼容客户端
      - `memory.py` - Memory 服务
      - `orchestrator.py` - 编排服务
      - `retrieval/` - 检索层
  - `tests/` - 单元测试

### Key Decisions (Why / Impact)

- decision: LLM Adapter 使用 httpx 而非 langchain-openai
  reason: 更轻量、更可控、减少依赖
  impact: 需要手动处理 OpenAI API 响应解析

- decision: 使用 tenacity 实现重试逻辑
  reason: 简单可靠的重试机制
  impact: 提高服务稳定性

### Code Snippets

```python
# [AC-AISVC-02] LLM Response generation
response = await llm_client.generate(messages, config=LLMConfig(...))

# [AC-AISVC-06] Streaming generation
async for chunk in llm_client.stream_generate(messages):
    yield create_message_event(delta=chunk.delta)
```

---

## 🧾 Session History

### Session #1 (2026-02-24)
- completed:
  - T3.1 实现 LLM Adapter
  - 创建 LLMClient 抽象接口 (base.py)
  - 实现 OpenAIClient (openai_client.py)
  - 编写单元测试 (test_llm_adapter.py)
  - 修复 entities.py JSON 类型问题
- changes:
  - 新增 `app/services/llm/__init__.py`
  - 新增 `app/services/llm/base.py`
  - 新增 `app/services/llm/openai_client.py`
  - 新增 `tests/test_llm_adapter.py`
  - 更新 `app/core/config.py` 添加 LLM 配置
  - 修复 `app/models/entities.py` JSON 列类型

---

## 🚀 Startup Guide

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