30 KiB

Raw Permalink Blame History

title	status	created	plan_type	depth	origin	branch
feat: AgentKit Phase 4 — 企业级生产化升级	completed	2026-06-06	feat	deep	AgentKit 全能力成熟度评估 + GEO 系统集成需求	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、可观测性），但审计发现多个"设计完整但执行断裂"的问题：

五大生产级差距

进化系统名存实亡（35% 成熟度）
- A/B 测试被禁用（lifecycle.py:172-188），整个验证循环被绕过
- _current_module 从未被设置（lifecycle.py:74），prompt 优化永远短路
- PromptOptimizer 仅注入 few-shot + 追加失败模式，无 LLM 驱动重写
- StrategyTuner 纯随机扰动，无代码路径调用
- ABTester 结果仅内存，进程重启丢失
记忆系统不可扩展（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）
LLM 仅单 Provider（60% 成熟度）
- 仅 OpenAICompatibleProvider，Anthropic/Gemini/文心等无原生实现
- 无 Provider 级重试/熔断/退避
- chat_stream() 无 fallback 链
- HTTP 超时硬编码 60s
核心引擎缺超时/取消（80% 成熟度）
- ReAct 循环无超时强制执行，可无限运行
- 无 CancellationToken 支持
- BaseAgent.execute() 不读 timeout_seconds
- Agent 状态更新无锁，并发竞态
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:

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

新增 CancellationToken 数据类：is_cancelled: bool，cancel() 方法，check() 抛 TaskCancelledError
ReActEngine.init 新增 default_timeout: float = 300.0
execute() 用 asyncio.wait_for() 包裹主循环，超时抛 TaskTimeoutError
每步循环开始检查 token.check()
BaseAgent.execute() 从 TaskMessage.timeout_seconds 读取超时
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:

A/B 测试启用：
- lifecycle.py: 移除 TODO bypass，调用 ABTester
- ABTester: 改用 hash-based 分组（hash(task_id) % 2），确定性可复现
- ABTester: 结果持久化到 EvolutionStore
- 最小样本量 10（从 30 降低，适配 GEO 低频场景）
- 样本不足时不应用变更，记录"insufficient data"
_current_module 自动设置：
- ConfigDrivenAgent._handle_react() 在执行前自动 set_current_module()
- 从 SkillConfig 提取当前 prompt 作为 module
LLM PromptOptimizer：
- 新增 LLMPromptOptimizer：用 LLM 分析失败模式，重写 instruction
- 保留 BootstrapPromptOptimizer（原 PromptOptimizer 重命名）作为 fallback
- 工厂函数 create_prompt_optimizer(optimizer_type, llm_gateway)
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:

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

RetryPolicy：max_retries=3, base_delay=1.0, max_delay=30.0, exponential_base=2
CircuitBreaker：failure_threshold=5, recovery_timeout=60.0, half_open_max=1
Provider.chat() 包裹在 RetryPolicy + CircuitBreaker 中
可重试错误：429/529/500/网络超时；不可重试：400/401/403
配置化：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:

chat_stream() 在 provider 失败时切换到 fallback model
流式失败的特殊处理：已发送 chunk 后无法切换，记录错误并终止
未发送任何 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:

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

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:

SSE 流使用 Agent 的公共方法获取配置（get_tools(), get_model(), get_system_prompt()）
ConfigDrivenAgent 新增 get_react_config() 返回 max_steps/timeout 等
SSE 流复用 Agent 已有的 ReActEngine 实例
流式 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:

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 测试列表
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:

EmbeddingCache：LRU 缓存（max_size=1000, TTL=3600s），基于文本 SHA-256 哈希
OpenAIEmbedder.embed() 先查缓存，命中直接返回
HttpRAGService.enhanced_search()：逐 KB 尝试 enhanced，单个 404 降级到 standard 仅该 KB
合并所有 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:

GeminiProvider 实现 LLMProvider ABC
使用 httpx 调用 https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
支持 Gemini 特有功能：
- contents 数组格式
- safetySettings 配置
- toolConfig（function_calling 配置）
- 流式：streamGenerateContent
认证：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:

BaseAgent 新增 _status_lock: asyncio.Lock，所有状态更新在锁内
ServerConfig 新增 watch_config() 方法：使用 watchfiles 监听 YAML 变更
变更时重新加载配置，更新 LLMGateway/SkillRegistry 等组件
热加载期间拒绝新请求（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

30 KiB Raw Permalink Blame History Unescape Escape

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

Summary

Problem Frame

五大生产级差距

GEO 系统的关键依赖

Requirements

Key Technical Decisions

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

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

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

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

KTD-5: WebSocket — FastAPI 原生 WebSocket

Scope Boundaries

In Scope

Out of Scope

Deferred to Follow-Up Work

High-Level Technical Design

架构总览

进化系统修复后数据流

EpisodicMemory pgvector 搜索流程

LLM Provider 重试/熔断流程

Implementation Units

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

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

U2. ReAct 超时强制执行 + CancellationToken

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

U4. Anthropic Provider 原生实现

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

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

U6. chat_stream() Fallback 链支持

U7. WebSocket 端点

U8. SSE 流修复

U9. Evolution + Memory API 路由

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

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

U11. Gemini Provider 原生实现

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

Phased Delivery

Risks & Mitigations

Success Metrics

30 KiB

Raw Permalink Blame History