---
title: "feat: AgentKit Phase 4 — 企业级生产化升级"
status: completed
created: 2026-06-06
plan_type: feat
depth: deep
origin: AgentKit 全能力成熟度评估 + GEO 系统集成需求
branch: feat/agentkit-phase4-production
---

# AgentKit Phase 4 — 企业级生产化升级

## Summary

基于 AgentKit 全能力成熟度审计和 GEO 系统集成需求，本计划解决 5 大生产级差距：进化系统执行断裂、记忆系统不可扩展、LLM 单 Provider、核心引擎缺超时/取消、Server 缺实时通信。覆盖 12 个 Implementation Unit，分 3 个交付阶段，以"GEO 系统完美运行"为验收底线。

## Problem Frame

Phase 3 完成了基础设施搭建（持久化、记忆接入、进化设计、SKILL.md、可观测性），但审计发现多个"设计完整但执行断裂"的问题：

### 五大生产级差距

1. **进化系统名存实亡（35% 成熟度）**
   - A/B 测试被禁用（lifecycle.py:172-188），整个验证循环被绕过
   - `_current_module` 从未被设置（lifecycle.py:74），prompt 优化永远短路
   - PromptOptimizer 仅注入 few-shot + 追加失败模式，无 LLM 驱动重写
   - StrategyTuner 纯随机扰动，无代码路径调用
   - ABTester 结果仅内存，进程重启丢失

2. **记忆系统不可扩展（65% 成熟度）**
   - EpisodicMemory 客户端 O(N) 余弦（episodic.py:90-111），>1000 条不可用
   - Episodic 未从配置初始化（app.py:173, config_driven.py:329-332 是 `pass`）
   - 无嵌入缓存，每次 embed() 调 API
   - Enhanced search 首个 KB 404 即全量降级（http_rag.py:198-202）

3. **LLM 仅单 Provider（60% 成熟度）**
   - 仅 OpenAICompatibleProvider，Anthropic/Gemini/文心等无原生实现
   - 无 Provider 级重试/熔断/退避
   - chat_stream() 无 fallback 链
   - HTTP 超时硬编码 60s

4. **核心引擎缺超时/取消（80% 成熟度）**
   - ReAct 循环无超时强制执行，可无限运行
   - 无 CancellationToken 支持
   - BaseAgent.execute() 不读 timeout_seconds
   - Agent 状态更新无锁，并发竞态

5. **Server 缺实时通信（75% 成熟度）**
   - 无 WebSocket，流式响应仅 SSE
   - SSE 创建新 ReActEngine 忽略 Agent 配置
   - SSE 访问私有属性 `_tool_registry`/`_llm_model`
   - 无 Evolution/Memory API 路由

### GEO 系统的关键依赖

GEO 系统以"Mode A"（纯 HTTP API）集成 AgentKit，关键路径：

- **内容生成**：`content_generator` skill → ReAct 引擎 → HttpRAGService 知识库检索 → LLM 生成
- **引用检测**：`citation_detector` skill → custom_handler → 回调 GEO 内部 API
- **GEO 优化**：`geo_optimizer` skill → ReAct 引擎 + 质量门控
- **监控/Schema/竞品/趋势**：各 skill → ReAct/custom 模式

**GEO 的容错模式**：AgentKit 不可用时降级到直接 LLM 调用。这意味着 AgentKit 的价值在于**质量提升**而非**功能可用**——如果 AgentKit 不比直接调用更好，就没有存在意义。

## Requirements

| ID | Requirement | Priority | Source |
|----|-------------|----------|--------|
| R1 | 进化系统可运行：A/B 测试启用、_current_module 自动设置、PromptOptimizer LLM 驱动 | P0 | 进化系统审计 |
| R2 | EpisodicMemory 使用 pgvector 原生搜索，支持百万级数据 | P0 | 记忆系统审计 |
| R3 | EpisodicMemory 从配置自动初始化，Server 和 ConfigDrivenAgent 统一接入 | P0 | 记忆系统审计 |
| R4 | 新增 Anthropic Provider（Messages API 原生实现） | P0 | LLM 审计 + GEO 需求 |
| R5 | ReAct 循环超时强制执行 + CancellationToken 支持 | P0 | 核心引擎审计 |
| R6 | Provider 级重试/熔断/指数退避 | P1 | LLM 审计 |
| R7 | chat_stream() 支持 fallback 链 | P1 | LLM 审计 |
| R8 | WebSocket 端点支持双向实时通信 | P1 | Server 审计 |
| R9 | SSE 流修复：使用 Agent 配置、不访问私有属性 | P1 | Server 审计 |
| R10 | Evolution/Memory API 路由 | P1 | Server 审计 |
| R11 | 嵌入缓存 + Enhanced Search 部分降级修复 | P1 | 记忆系统审计 |
| R12 | 新增 Gemini Provider | P2 | LLM 审计 |
| R13 | Agent 状态锁 + 配置热加载 | P2 | 核心引擎审计 |

## Key Technical Decisions

### KTD-1: 进化系统修复策略 — 修复而非重写

**决策**：在现有 EvolutionMixin 架构上修复断裂点，不引入 GEPA 式遗传算法。

**理由**：
- 现有管线设计完整（reflect → optimize → A/B test → apply/rollback），只需接通
- GEPA 需要"用自然语言反思替代梯度更新"的完整评估管线，当前无评估数据
- GEO 的 8 个 skill 都是 `llm_generate`/`custom` 模式，进化收益有限
- 修复后即可实现"执行轨迹 → LLM 反思 → 质量门控 → 安全应用"的最小闭环

**替代方案**：引入 GEPA 遗传算法 → 需要评估管线 + 统计显著 A/B + 大量执行数据，当前不具备条件

### KTD-2: EpisodicMemory pgvector 原生搜索 — 复用 GEO 数据库

**决策**：EpisodicMemory 直接使用 GEO 共享的 PostgreSQL + pgvector，通过 SQLAlchemy session 执行 `<=>` 操作符。

**理由**：
- docker-compose 已配置 AgentKit 与 GEO 共享 PostgreSQL
- GEO 的 `KnowledgeChunk` 已使用 pgvector `Vector(1536)` + HNSW 索引
- AgentKit 的 `EpisodicMemory` 模型（在 geo/backend/app/models/agent.py）已有 `embedding_id` 字段
- 无需引入新数据库，复用现有基础设施

**替代方案**：独立 pgvector 实例 → 增加运维复杂度，与 GEO 数据不共享

### KTD-3: LLM Provider 架构 — 抽象层 + 原生实现

**决策**：保留 `LLMProvider` ABC，新增 `AnthropicProvider` 和 `GeminiProvider` 原生实现，不依赖 OpenAI 兼容层。

**理由**：
- Anthropic Messages API 格式与 OpenAI 不同（`content` 数组 vs `content` 字符串，`tool_choice` 结构不同）
- Gemini 有独特的 `generateContent` API 和安全设置
- 通过 OpenAI 兼容层适配会丢失原生功能（如 Anthropic 的 extended thinking、Gemini 的 grounding）
- GEO 的 `content_generator` 和 `deai_agent` 对输出质量敏感，原生 API 更可靠

### KTD-4: 超时与取消 — asyncio.wait_for + CancellationToken

**决策**：ReAct 循环使用 `asyncio.wait_for()` 强制超时，新增 `CancellationToken` 支持优雅取消。

**理由**：
- `asyncio.wait_for()` 是 Python 标准库，无额外依赖
- CancellationToken 模式与 GEO 的 `agent_execution_context` 兼容
- Server 的 `cancel_task` 端点已有，只需 ReAct 循环配合

### KTD-5: WebSocket — FastAPI 原生 WebSocket

**决策**：使用 FastAPI 原生 `WebSocket` 端点，不引入 Socket.IO 等第三方库。

**理由**：
- GEO 前端已有 `agents.ts` API 客户端，WebSocket 原生支持即可
- 减少依赖，降低安全风险
- FastAPI WebSocket 与现有路由体系一致

## Scope Boundaries

### In Scope

- 进化系统修复（A/B 测试启用、_current_module 接入、LLM PromptOptimizer）
- EpisodicMemory pgvector 原生搜索 + 配置初始化
- Anthropic Provider + Gemini Provider
- Provider 级重试/熔断
- ReAct 超时 + CancellationToken
- WebSocket 端点
- SSE 流修复
- Evolution/Memory API 路由
- 嵌入缓存 + Enhanced Search 部分降级

### Out of Scope

- GEPA 遗传算法（需评估管线，Phase 5）
- 多 Agent 协作编排（L4 级，Phase 5）
- RAG 自纠错循环（L5 级，Phase 5）
- 配置热加载（P2，可后续）
- Agent 状态锁（P2，可后续）
- 文心/豆包/元宝等国内 Provider（P2，可后续通过社区贡献）

### Deferred to Follow-Up Work

- Contextual Retrieval（Anthropic 2024 突破，需 chunk 处理层）
- 评估管线（Ragas + Phoenix 集成）
- 多 Agent RAG 编排（supervisor-worker 拓扑）
- 配置 Schema 验证（Pydantic 模型）
- 性能基准测试

## High-Level Technical Design

### 架构总览

```
┌─────────────────────────────────────────────────────────────┐
│                    GEO Frontend (Next.js)                    │
│              agents.ts → WebSocket + REST API                │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP / WebSocket
┌────────────────────────▼────────────────────────────────────┐
│                  AgentKit Server (:8001)                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐  │
│  │ REST API │ │WebSocket │ │  SSE     │ │ Evolution API │  │
│  │ (tasks,  │ │ (real-   │ │ (stream) │ │ (/evolution)  │  │
│  │  agents) │ │  time)   │ │          │ │               │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └───────┬───────┘  │
│       │            │            │                │           │
│  ┌────▼────────────▼────────────▼────────────────▼───────┐  │
│  │                    Core Engine                          │  │
│  │  ReActEngine (timeout + cancel)                        │  │
│  │  ConfigDrivenAgent (_current_module auto-set)          │  │
│  │  EvolutionMixin (A/B test enabled + LLM PromptOptimizer)│ │
│  └────┬──────────┬──────────┬──────────┬─────────────────┘  │
│       │          │          │          │                      │
│  ┌────▼───┐ ┌───▼────┐ ┌──▼───┐ ┌───▼──────┐              │
│  │Memory  │ │LLM     │ │Skills│ │Evolution │              │
│  │System  │ │Gateway │ │System│ │System    │              │
│  │        │ │        │ │      │ │          │              │
│  │Working │ │OpenAI  │ │YAML  │ │LLM       │              │
│  │(Redis) │ │Anthropic│ │MD    │ │Reflector │              │
│  │        │ │Gemini  │ │Pipeline│ │ABTester  │              │
│  │Episodic│ │+retry  │ │      │ │(enabled) │              │
│  │(pgvec) │ │+breaker│ │      │ │PromptOpt │              │
│  │        │ │        │ │      │ │(LLM)     │              │
│  │Semantic│ │        │ │      │ │Store     │              │
│  │(RAG)   │ │        │ │      │ │(SQLite)  │              │
│  └────┬───┘ └────────┘ └──────┘ └──────────┘              │
│       │                                                     │
│  ┌────▼──────────────────────────────────────────────────┐  │
│  │              PostgreSQL + pgvector (shared with GEO)   │  │
│  │              Redis (shared with GEO)                   │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 进化系统修复后数据流

```
任务完成
  → TraceRecorder.end_trace() 生成 ExecutionTrace
  → EvolutionMixin.evolve_after_task()
    → Reflector.reflect(trace) → Reflection (LLM 或规则)
    → if reflection.outcome == "should_optimize":
      → PromptOptimizer.optimize(module, trace, reflection)
        → LLM 驱动重写 instruction (新增)
        → 注入 few-shot demos (已有)
      → ABTester.assign_group(task_id) → control/treatment
      → ABTester.record_result(task_id, group, score)
      → if ABTester.is_significant(test_id):
        → apply change (treatment wins) or rollback (control wins)
      → else:
        → keep current, log inconclusive
    → EvolutionStore.persist(event)
```

### EpisodicMemory pgvector 搜索流程

```
MemoryRetriever.retrieve(query)
  → EpisodicMemory.search(query, top_k=5)
    → Embedder.embed(query) → query_embedding (带缓存)
    → SQLAlchemy: SELECT * FROM episodic_memories
        ORDER BY embedding <=> :query_embedding
        LIMIT :top_k
    → 时间衰减混合评分: score = alpha * (1 - cosine_distance) + (1-alpha) * time_decay
    → 返回 top_k 结果
```

### LLM Provider 重试/熔断流程

```
LLMGateway.chat(request)
  → Provider.chat() (primary)
    → CircuitBreaker.allow? → yes
      → RetryPolicy.execute():
        → attempt 1 → fail → backoff 1s
        → attempt 2 → fail → backoff 2s
        → attempt 3 → fail → CircuitBreaker.record_failure()
          → if failures >= threshold: open circuit
    → CircuitBreaker.allow? → no (circuit open)
      → skip to fallback
  → Fallback: try next provider/model in chain
```

---

## Implementation Units

### Phase A: 核心修复（P0 — GEO 运行依赖）

---

### U1. EpisodicMemory pgvector 原生搜索 + 配置初始化

**Goal**: 将 EpisodicMemory 从客户端 O(N) 余弦切换到 pgvector `<=>` 操作符，支持百万级数据；从 Server 和 ConfigDrivenAgent 配置自动初始化。

**Requirements**: R2, R3

**Dependencies**: 无

**Files**:
- `src/agentkit/memory/episodic.py` — 重写 search/retrieve 使用 pgvector
- `src/agentkit/memory/embedder.py` — 新增嵌入缓存
- `src/agentkit/server/app.py` — EpisodicMemory 初始化
- `src/agentkit/core/config_driven.py` — EpisodicMemory 初始化
- `src/agentkit/server/config.py` — Episodic 配置段
- `tests/unit/test_episodic_vector_search.py` — 更新测试
- `tests/unit/test_memory_integration.py` — 更新测试

**Approach**:
1. EpisodicMemory 新增 `session_factory` 参数，search/retrieve 使用 `text("embedding <=> :query_vec")` 原生 pgvector 查询
2. 保留 `_alpha` 混合评分：pgvector 返回 top_k*3 候选，Python 端做时间衰减重排
3. 无 pgvector 时降级到客户端余弦（现有逻辑）
4. Embedder 新增 `EmbeddingCache`（LRU + TTL），避免重复 embed 调用
5. ServerConfig 新增 `memory.episodic` 配置段（session_factory、pgvector_enabled、table_name）
6. create_app() 和 ConfigDrivenAgent 从配置创建 EpisodicMemory

**Patterns to follow**: GEO 的 `HybridRetriever`（pgvector + ILIKE + RRF 融合）

**Test scenarios**:
- pgvector 搜索返回 top_k 结果按相似度排序
- 无 pgvector 时降级到客户端余弦
- 时间衰减重排：近期条目优先
- 嵌入缓存命中/未命中
- 配置初始化 EpisodicMemory 成功/失败降级
- 大数据量（10000+ 条）搜索性能

**Verification**: 全量测试通过 + EpisodicMemory 集成测试覆盖 pgvector 路径

---

### U2. ReAct 超时强制执行 + CancellationToken

**Goal**: ReAct 循环支持超时强制退出和优雅取消，防止任务无限运行。

**Requirements**: R5

**Dependencies**: 无

**Files**:
- `src/agentkit/core/react.py` — 超时 + 取消支持
- `src/agentkit/core/protocol.py` — CancellationToken 类型
- `src/agentkit/core/base.py` — 传递 timeout_seconds
- `src/agentkit/core/config_driven.py` — 传递 timeout
- `src/agentkit/server/routes/tasks.py` — cancel 端点传递 token
- `tests/unit/test_react_engine.py` — 更新测试
- `tests/unit/test_base_agent.py` — 更新测试

**Approach**:
1. 新增 `CancellationToken` 数据类：`is_cancelled: bool`，`cancel()` 方法，`check()` 抛 `TaskCancelledError`
2. ReActEngine.__init__ 新增 `default_timeout: float = 300.0`
3. execute() 用 `asyncio.wait_for()` 包裹主循环，超时抛 `TaskTimeoutError`
4. 每步循环开始检查 `token.check()`
5. BaseAgent.execute() 从 `TaskMessage.timeout_seconds` 读取超时
6. Server cancel 端点设置 CancellationToken

**Patterns to follow**: Python asyncio.wait_for + CancellationToken 模式

**Test scenarios**:
- 超时触发 TaskTimeoutError，返回部分结果
- CancellationToken 取消，返回已完成步骤
- 超时 0 表示无限（向后兼容）
- 正常完成不受超时影响
- 并发取消和超时竞争

**Verification**: 全量测试通过 + 超时/取消场景覆盖

---

### U3. 进化系统修复 — A/B 测试启用 + _current_module 接入

**Goal**: 修复进化系统的 3 个断裂点，使自我进化管线可运行。

**Requirements**: R1

**Dependencies**: U2（超时机制防止进化循环失控）

**Files**:
- `src/agentkit/evolution/lifecycle.py` — 启用 A/B 测试、自动设置 _current_module
- `src/agentkit/evolution/ab_tester.py` — 持久化、确定性分组
- `src/agentkit/evolution/prompt_optimizer.py` — LLM 驱动重写
- `src/agentkit/evolution/strategy_tuner.py` — 接入进化管线
- `src/agentkit/core/config_driven.py` — 自动 set_current_module
- `src/agentkit/skills/base.py` — EvolutionConfig 扩展
- `tests/unit/test_evolution_lifecycle.py` — 更新测试
- `tests/unit/test_ab_tester.py` — 新增测试
- `tests/unit/test_prompt_optimizer.py` — 新增测试

**Approach**:
1. **A/B 测试启用**：
   - lifecycle.py: 移除 TODO bypass，调用 ABTester
   - ABTester: 改用 hash-based 分组（`hash(task_id) % 2`），确定性可复现
   - ABTester: 结果持久化到 EvolutionStore
   - 最小样本量 10（从 30 降低，适配 GEO 低频场景）
   - 样本不足时不应用变更，记录"insufficient data"
2. **_current_module 自动设置**：
   - ConfigDrivenAgent._handle_react() 在执行前自动 `set_current_module()`
   - 从 SkillConfig 提取当前 prompt 作为 module
3. **LLM PromptOptimizer**：
   - 新增 `LLMPromptOptimizer`：用 LLM 分析失败模式，重写 instruction
   - 保留 `BootstrapPromptOptimizer`（原 PromptOptimizer 重命名）作为 fallback
   - 工厂函数 `create_prompt_optimizer(optimizer_type, llm_gateway)`
4. **StrategyTuner 接入**：
   - EvolutionMixin.evolve_after_task() 在 prompt 优化后检查 strategy 优化
   - StrategyTuner 改用贝叶斯优化（简化版：高斯过程 1D）

**Patterns to follow**: GEO 的 `EnhancedRAG`（LLM 驱动优化模式）

**Test scenarios**:
- A/B 测试：control/treatment 分组确定性
- A/B 测试：最小样本量不足时不应用
- A/B 测试：统计显著时应用/回滚
- _current_module 自动设置
- LLM PromptOptimizer 生成优化 instruction
- StrategyTuner 贝叶斯优化
- 进化管线端到端：reflect → optimize → A/B test → apply/rollback

**Verification**: 全量测试通过 + 进化端到端测试

---

### U4. Anthropic Provider 原生实现

**Goal**: 新增 AnthropicProvider，支持 Claude Messages API 原生调用。

**Requirements**: R4

**Dependencies**: 无

**Files**:
- `src/agentkit/llm/providers/anthropic.py` — 新增 AnthropicProvider
- `src/agentkit/llm/gateway.py` — 注册 Anthropic provider
- `src/agentkit/llm/config.py` — Anthropic 配置
- `tests/unit/test_anthropic_provider.py` — 新增测试

**Approach**:
1. AnthropicProvider 实现 LLMProvider ABC
2. 使用 httpx 直接调用 `https://api.anthropic.com/v1/messages`
3. 支持 Messages API 特有功能：
   - `content` 数组格式（text + tool_use + tool_result）
   - `tool_choice` 结构（`{"type": "auto"|"any"|"tool", "name": "..."}`)
   - `system` 顶层参数
   - `max_tokens` 必填
   - extended thinking（可选）
4. 流式支持：SSE `event: content_block_delta`
5. 错误处理：429 rate limit / 529 overload / 500 server error
6. 配置：`api_key`、`model`、`max_tokens`、`thinking_enabled`

**Patterns to follow**: OpenAICompatibleProvider 的接口模式

**Test scenarios**:
- 标准 chat 请求/响应
- tool_calls 请求/响应
- 流式 chat（content_block_delta）
- 错误处理（429/529/500）
- API key 缺失报错
- 模型别名解析

**Verification**: 全量测试通过 + Anthropic Provider 单元测试覆盖

---

### Phase B: 增强能力（P1 — GEO 质量提升）

---

### U5. Provider 级重试/熔断/指数退避

**Goal**: 每个 Provider 内置重试策略和熔断器，提高 LLM 调用可靠性。

**Requirements**: R6

**Dependencies**: U4（Anthropic Provider 也需要重试）

**Files**:
- `src/agentkit/llm/retry.py` — 新增 RetryPolicy + CircuitBreaker
- `src/agentkit/llm/providers/openai.py` — 集成重试
- `src/agentkit/llm/providers/anthropic.py` — 集成重试
- `src/agentkit/llm/config.py` — 重试/熔断配置
- `tests/unit/test_llm_retry.py` — 新增测试

**Approach**:
1. `RetryPolicy`：max_retries=3, base_delay=1.0, max_delay=30.0, exponential_base=2
2. `CircuitBreaker`：failure_threshold=5, recovery_timeout=60.0, half_open_max=1
3. Provider.chat() 包裹在 RetryPolicy + CircuitBreaker 中
4. 可重试错误：429/529/500/网络超时；不可重试：400/401/403
5. 配置化：per-provider retry 和 circuit_breaker 配置

**Patterns to follow**: resilience4j / tenacity 模式

**Test scenarios**:
- 重试成功（第 2 次成功）
- 重试耗尽抛异常
- 指数退避延迟
- 熔断器打开/半开/关闭状态转换
- 不可重试错误立即抛出
- 配置化重试参数

**Verification**: 全量测试通过 + 重试/熔断单元测试

---

### U6. chat_stream() Fallback 链支持

**Goal**: LLMGateway.chat_stream() 支持 fallback 模型链，与 chat() 对齐。

**Requirements**: R7

**Dependencies**: U5（重试机制）

**Files**:
- `src/agentkit/llm/gateway.py` — stream fallback
- `tests/unit/test_llm_gateway.py` — 更新测试

**Approach**:
1. chat_stream() 在 provider 失败时切换到 fallback model
2. 流式失败的特殊处理：已发送 chunk 后无法切换，记录错误并终止
3. 未发送任何 chunk 时可安全切换到 fallback

**Test scenarios**:
- 首个 provider 失败，fallback 成功
- 已发送 chunk 后失败，终止并记录
- 所有 provider 失败，抛异常

**Verification**: 全量测试通过

---

### U7. WebSocket 端点

**Goal**: 新增 WebSocket 端点支持双向实时通信，客户端可发送取消/参数变更指令。

**Requirements**: R8

**Dependencies**: U2（CancellationToken）

**Files**:
- `src/agentkit/server/routes/ws.py` — 新增 WebSocket 路由
- `src/agentkit/server/app.py` — 注册 WebSocket 路由
- `tests/unit/test_websocket.py` — 新增测试

**Approach**:
1. `WS /api/v1/ws/tasks/{task_id}` — 任务执行实时推送
2. 客户端消息类型：`cancel`（取消任务）、`ping`（心跳）
3. 服务端消息类型：`step`（ReAct 步骤）、`result`（最终结果）、`error`、`pong`
4. 连接认证：URL 参数 `?api_key=xxx` 或首条消息认证
5. 多客户端订阅同一任务（fan-out）
6. 任务完成后自动关闭连接

**Patterns to follow**: FastAPI WebSocket 官方模式

**Test scenarios**:
- WebSocket 连接/认证
- 接收 ReAct 步骤实时推送
- 发送 cancel 取消任务
- 任务完成自动关闭
- 未认证连接拒绝
- 多客户端订阅

**Verification**: 全量测试通过 + WebSocket 集成测试

---

### U8. SSE 流修复

**Goal**: 修复 SSE 流端点的 3 个问题：忽略 Agent 配置、访问私有属性、无 fallback。

**Requirements**: R9

**Dependencies**: 无

**Files**:
- `src/agentkit/server/routes/tasks.py` — 修复 SSE 流
- `src/agentkit/core/react.py` — 暴露公共接口
- `tests/unit/test_server_routes.py` — 更新测试

**Approach**:
1. SSE 流使用 Agent 的公共方法获取配置（`get_tools()`, `get_model()`, `get_system_prompt()`）
2. ConfigDrivenAgent 新增 `get_react_config()` 返回 max_steps/timeout 等
3. SSE 流复用 Agent 已有的 ReActEngine 实例
4. 流式 fallback：provider 失败时尝试 fallback model

**Test scenarios**:
- SSE 流使用 Agent 配置的 max_steps
- SSE 流不访问私有属性
- SSE 流 fallback 到备选模型

**Verification**: 全量测试通过

---

### U9. Evolution + Memory API 路由

**Goal**: 新增 Evolution 和 Memory 管理 API，支持前端展示和运维操作。

**Requirements**: R10

**Dependencies**: U3（进化系统修复）

**Files**:
- `src/agentkit/server/routes/evolution.py` — 新增 Evolution API
- `src/agentkit/server/routes/memory.py` — 新增 Memory API
- `src/agentkit/server/app.py` — 注册路由
- `tests/unit/test_evolution_api.py` — 新增测试
- `tests/unit/test_memory_api.py` — 新增测试

**Approach**:
1. Evolution API：
   - `GET /api/v1/evolution/events` — 进化事件列表（分页、过滤）
   - `GET /api/v1/evolution/skills/{name}/versions` — Skill 版本历史
   - `POST /api/v1/evolution/trigger` — 手动触发进化
   - `GET /api/v1/evolution/ab-tests` — A/B 测试列表
2. Memory API：
   - `GET /api/v1/memory/episodic` — 情景记忆搜索
   - `GET /api/v1/memory/semantic/search` — 知识库搜索代理
   - `DELETE /api/v1/memory/episodic/{key}` — 删除记忆条目

**Test scenarios**:
- Evolution 事件列表分页
- Skill 版本历史查询
- 手动触发进化
- 记忆搜索
- 未授权访问拒绝

**Verification**: 全量测试通过 + API 路由测试

---

### U10. 嵌入缓存 + Enhanced Search 部分降级修复

**Goal**: 嵌入结果缓存减少 API 调用；Enhanced Search 对每个 KB 独立降级而非全量降级。

**Requirements**: R11

**Dependencies**: U1（EpisodicMemory 重构）

**Files**:
- `src/agentkit/memory/embedder.py` — 嵌入缓存
- `src/agentkit/memory/http_rag.py` — 部分降级修复
- `tests/unit/test_episodic_vector_search.py` — 更新测试
- `tests/unit/test_http_rag_service.py` — 更新测试

**Approach**:
1. `EmbeddingCache`：LRU 缓存（max_size=1000, TTL=3600s），基于文本 SHA-256 哈希
2. OpenAIEmbedder.embed() 先查缓存，命中直接返回
3. HttpRAGService.enhanced_search()：逐 KB 尝试 enhanced，单个 404 降级到 standard 仅该 KB
4. 合并所有 KB 结果后统一排序

**Test scenarios**:
- 缓存命中返回相同向量
- 缓存未命中调用 API
- 缓存 TTL 过期重新获取
- 部分 KB enhanced 404，其余 KB 仍用 enhanced
- 所有 KB 降级到 standard

**Verification**: 全量测试通过

---

### Phase C: 扩展能力（P2 — 未来准备）

---

### U11. Gemini Provider 原生实现

**Goal**: 新增 GeminiProvider，支持 Google Gemini API 原生调用。

**Requirements**: R12

**Dependencies**: U5（重试机制）

**Files**:
- `src/agentkit/llm/providers/gemini.py` — 新增 GeminiProvider
- `src/agentkit/llm/gateway.py` — 注册 Gemini provider
- `src/agentkit/llm/config.py` — Gemini 配置
- `tests/unit/test_gemini_provider.py` — 新增测试

**Approach**:
1. GeminiProvider 实现 LLMProvider ABC
2. 使用 httpx 调用 `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent`
3. 支持 Gemini 特有功能：
   - `contents` 数组格式
   - `safetySettings` 配置
   - `toolConfig`（function_calling 配置）
   - 流式：`streamGenerateContent`
4. 认证：API key 作为 URL 参数 `?key=xxx`

**Test scenarios**:
- 标准 generateContent 请求/响应
- function_calling 请求/响应
- 流式 generateContent
- safetySettings 过滤
- API key 缺失报错

**Verification**: 全量测试通过

---

### U12. Agent 状态锁 + 配置热加载

**Goal**: Agent 状态更新加锁防竞态；配置文件变更自动热加载。

**Requirements**: R13

**Dependencies**: 无

**Files**:
- `src/agentkit/core/base.py` — asyncio.Lock 保护状态
- `src/agentkit/server/config.py` — 文件监听 + 热加载
- `src/agentkit/server/app.py` — 热加载集成
- `tests/unit/test_base_agent.py` — 更新测试
- `tests/unit/test_server_config.py` — 更新测试

**Approach**:
1. BaseAgent 新增 `_status_lock: asyncio.Lock`，所有状态更新在锁内
2. ServerConfig 新增 `watch_config()` 方法：使用 `watchfiles` 监听 YAML 变更
3. 变更时重新加载配置，更新 LLMGateway/SkillRegistry 等组件
4. 热加载期间拒绝新请求（drain 模式）

**Test scenarios**:
- 并发状态更新无竞态
- 配置文件变更触发重载
- 重载期间请求排队等待
- 无效配置不覆盖当前配置

**Verification**: 全量测试通过

---

## Phased Delivery

| Phase | Units | 交付物 | GEO 影响 |
|-------|-------|--------|----------|
| **A: 核心修复** | U1-U4 | pgvector 记忆 + 超时取消 + 进化修复 + Anthropic Provider | GEO 内容生成质量提升 + Claude 模型支持 |
| **B: 增强能力** | U5-U10 | 重试熔断 + stream fallback + WebSocket + SSE 修复 + API 路由 + 缓存 | GEO 系统稳定性 + 实时监控 + 运维可见 |
| **C: 扩展能力** | U11-U12 | Gemini Provider + 状态锁 + 热加载 | 多模型选择 + 运维友好 |

## Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| pgvector 查询与 GEO 数据库冲突 | Low | High | 使用独立 schema `agentkit.episodic_memories`，不影响 GEO 表 |
| Anthropic API 格式差异导致 tool_calls 解析错误 | Medium | Medium | 严格按 Messages API 文档实现，覆盖 tool_use/tool_result 测试 |
| A/B 测试样本不足导致进化无法应用 | High | Low | 设置低阈值 min_samples=10，不足时记录日志不阻塞 |
| WebSocket 连接泄漏 | Medium | Medium | 心跳检测 + 超时自动断开 + 连接数上限 |
| 进化应用有害变更 | Medium | High | A/B 测试统计显著才应用 + 自动回滚 + 质量门控 |

## Success Metrics

| Metric | Current | Target |
|--------|---------|--------|
| EpisodicMemory 搜索延迟（1 万条） | >2s (O(N) 客户端) | <100ms (pgvector ANN) |
| ReAct 循环超时保护 | 无 | 100% 任务有超时 |
| 进化系统可运行性 | A/B 测试禁用 | A/B 测试启用 + 统计显著才应用 |
| LLM Provider 覆盖 | 1 (OpenAI 兼容) | 3 (OpenAI + Anthropic + Gemini) |
| Provider 调用可靠性 | 无重试/熔断 | 3 次重试 + 熔断保护 |
| 实时通信 | 仅 SSE | WebSocket + SSE 双通道 |
| API 路由覆盖 | 无 Evolution/Memory | 完整 CRUD + 搜索 |
| 全量测试 | 1037 passed | 1200+ passed |