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

191 lines
5.9 KiB
Markdown
Raw Normal View History

feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
# 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%) ✅
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
- [x] Phase 3: 核心编排（Orchestrator & LLM Adapter） (100%) ✅
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
- [ ] Phase 4: 流式响应（SSE 实现与状态机） (0%) ⏳
- [ ] Phase 5: 集成与冒烟测试（Quality Assurance） (0%) ⏳
---
## 🔄 Current Phase
### Goal
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
实现 SSE 流式响应，包括 Accept 头切换、事件生成和状态机管理。
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
### Sub Tasks
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
#### Phase 4: 流式响应（SSE 实现与状态机）
- [ ] T4.1 在 API 层实现基于 `Accept` 头的响应模式自动切换逻辑 `[AC-AISVC-06]`
- [ ] T4.2 实现 SSE 事件生成器：根据 Orchestrator 的增量输出包装 `message` 事件 `[AC-AISVC-07]`
- [ ] T4.3 实现 SSE 状态机：确保 `final` 或 `error` 事件后连接正确关闭，且顺序不乱 `[AC-AISVC-08, AC-AISVC-09]`
- [ ] T4.4 实现流式输出过程中的异常捕获，并转化为 `event: error` 输出 `[AC-AISVC-09]`
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
### Next Action (Must be Specific)
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
**Immediate**: Phase 3 已完成！准备执行 Phase 4。
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
**Note**: Phase 4 的 SSE 功能大部分已在 Phase 1-3 中提前实现：
- Accept 头切换已在 `test_accept_switching.py` 测试
- SSE 状态机已在 `app/core/sse.py` 实现
- SSE 事件生成器已实现
- Orchestrator 流式生成已实现
**建议**: 跳过 Phase 4，直接执行 Phase 5 集成测试。
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
---
## 🏗️ 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 服务
feat(ai-service): implement complete Orchestrator generation pipeline for T3.4 [AC-AISVC-01, AC-AISVC-02] - Integrate Memory, ContextMerger, Retriever, LLMClient, ConfidenceCalculator - Implement 8-step generation pipeline: 1. Load local history from Memory 2. Merge with external history (dedup + truncate) 3. RAG retrieval (optional) 4. Build prompt with context and evidence 5. LLM generation 6. Calculate confidence 7. Save messages to Memory 8. Return ChatResponse - Add GenerationContext dataclass for tracking intermediate results - Implement fallback response mechanism for error handling - Add 21 unit tests for OrchestratorService - All 138 tests passing
2026-02-24 05:47:12 +00:00
- `orchestrator.py` - 编排服务 ✅ (完整实现)
- `context.py` - 上下文合并 ✅
- `confidence.py` - 置信度计算 ✅
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
- `retrieval/` - 检索层
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
- `tests/` - 单元测试 (184 tests)
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
### Key Decisions (Why / Impact)
- decision: LLM Adapter 使用 httpx 而非 langchain-openai
reason: 更轻量、更可控、减少依赖
impact: 需要手动处理 OpenAI API 响应解析
- decision: 使用 tenacity 实现重试逻辑
reason: 简单可靠的重试机制
impact: 提高服务稳定性
feat(ai-service): implement complete Orchestrator generation pipeline for T3.4 [AC-AISVC-01, AC-AISVC-02] - Integrate Memory, ContextMerger, Retriever, LLMClient, ConfidenceCalculator - Implement 8-step generation pipeline: 1. Load local history from Memory 2. Merge with external history (dedup + truncate) 3. RAG retrieval (optional) 4. Build prompt with context and evidence 5. LLM generation 6. Calculate confidence 7. Save messages to Memory 8. Return ChatResponse - Add GenerationContext dataclass for tracking intermediate results - Implement fallback response mechanism for error handling - Add 21 unit tests for OrchestratorService - All 138 tests passing
2026-02-24 05:47:12 +00:00
- decision: Orchestrator 使用依赖注入模式
reason: 便于测试和组件替换
impact: 所有组件可通过构造函数注入
- decision: 使用 GenerationContext 数据类追踪生成流程
reason: 清晰追踪中间结果和诊断信息
impact: 便于调试和问题排查
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
- decision: Pydantic 模型使用 alias 实现驼峰命名
reason: 符合 OpenAPI 契约的 camelCase 要求
impact: JSON 序列化时自动转换字段名
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
### Code Snippets
```python
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
# [AC-AISVC-02] ChatResponse with contract-compliant field names
response = ChatResponse(
reply="AI response",
confidence=0.85,
should_transfer=False,
feat(ai-service): implement complete Orchestrator generation pipeline for T3.4 [AC-AISVC-01, AC-AISVC-02] - Integrate Memory, ContextMerger, Retriever, LLMClient, ConfidenceCalculator - Implement 8-step generation pipeline: 1. Load local history from Memory 2. Merge with external history (dedup + truncate) 3. RAG retrieval (optional) 4. Build prompt with context and evidence 5. LLM generation 6. Calculate confidence 7. Save messages to Memory 8. Return ChatResponse - Add GenerationContext dataclass for tracking intermediate results - Implement fallback response mechanism for error handling - Add 21 unit tests for OrchestratorService - All 138 tests passing
2026-02-24 05:47:12 +00:00
)
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
json_str = response.model_dump_json(by_alias=True)
# Output: {"reply": "AI response", "confidence": 0.85, "shouldTransfer": false, ...}
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
```
---
## 🧾 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 列类型
feat(ai-service): implement complete Orchestrator generation pipeline for T3.4 [AC-AISVC-01, AC-AISVC-02] - Integrate Memory, ContextMerger, Retriever, LLMClient, ConfidenceCalculator - Implement 8-step generation pipeline: 1. Load local history from Memory 2. Merge with external history (dedup + truncate) 3. RAG retrieval (optional) 4. Build prompt with context and evidence 5. LLM generation 6. Calculate confidence 7. Save messages to Memory 8. Return ChatResponse - Add GenerationContext dataclass for tracking intermediate results - Implement fallback response mechanism for error handling - Add 21 unit tests for OrchestratorService - All 138 tests passing
2026-02-24 05:47:12 +00:00
### Session #2 (2026-02-24)
- completed:
- T3.2 实现上下文合并逻辑
- 创建 ContextMerger 类 (context.py)
- 实现消息指纹计算 (SHA256)
- 实现去重和截断策略
- 编写单元测试 (test_context.py)
- changes:
- 新增 `app/services/context.py`
- 新增 `tests/test_context.py`
### Session #3 (2026-02-24)
- completed:
- T3.3 实现置信度计算与转人工逻辑
- 创建 ConfidenceCalculator 类 (confidence.py)
- 实现检索不足判定
- 实现置信度计算策略
- 实现 shouldTransfer 逻辑
- 编写单元测试 (test_confidence.py)
- changes:
- 新增 `app/services/confidence.py`
- 新增 `tests/test_confidence.py`
- 更新 `app/core/config.py` 添加置信度配置
### Session #4 (2026-02-24)
- completed:
- T3.4 实现 Orchestrator 完整生成闭环
- 整合 Memory、ContextMerger、Retriever、LLMClient、ConfidenceCalculator
- 实现 generate() 方法完整流程 (8 步)
- 创建 GenerationContext 数据类追踪生成流程
- 实现 fallback 响应机制
- 编写单元测试 (test_orchestrator.py, 21 tests)
- changes:
- 更新 `app/services/orchestrator.py` 完整实现
- 新增 `tests/test_orchestrator.py`
- tests_passed: 138 tests (all passing)
feat(ai-service): add contract validation tests for T3.5 [AC-AISVC-02] - Verify ChatResponse fields match OpenAPI contract - Test required fields: reply, confidence, shouldTransfer - Test optional fields: transferReason, metadata - Test JSON serialization uses camelCase (by_alias=True) - Test confidence range validation [0.0, 1.0] - Test ChatRequest contract compliance - Test ErrorResponse contract compliance - Test SSEFinalEvent matches ChatResponse structure - Test SSEErrorEvent matches ErrorResponse structure - Add end-to-end contract validation with OrchestratorService - All 184 tests passing
2026-02-24 05:55:17 +00:00
### Session #5 (2026-02-24)
- completed:
- T3.5 验证 non-streaming 响应字段符合 OpenAPI 契约
- 验证 ChatResponse 字段与契约一致性
- 验证 JSON 序列化使用 camelCase
- 验证必填字段和可选字段
- 验证 confidence 范围约束
- 编写契约验证测试 (test_contract.py, 23 tests)
- changes:
- 新增 `tests/test_contract.py`
- tests_passed: 184 tests (all passing)
feat(ai-service): implement SSE event generator for message events [AC-AISVC-07] - Optimize Orchestrator streaming output with LLM client integration - Implement _stream_from_llm() to wrap LLM chunks as message events - Implement _stream_mock_response() for demo/testing - Add SSE event format tests (message/final/error) - Fix by_alias=True for final event JSON output - 79 tests passing
2026-02-24 05:28:10 +00:00
---
## 🚀 Startup Guide
1. 读取本进度文档，定位当前 Phase 与 Next Action。
2. 打开并阅读 Spec References 指向的模块规范。
3. 直接执行 Next Action；遇到缺口先更新 spec 再编码。